Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

9.4 KB
Raw Blame
/**
 * Minimal MCP stdio server: newline-delimited JSON-RPC 2.0.
 * stdout carries protocol messages ONLY; diagnostics go to stderr.
 */
import { createInterface } from 'node:readline';
import { TOOLS, callTool } from './tools.js';
import { mcpInstructions } from './instructions.js';
import { hasGraftIndex } from '../graph/root.js';
import { mainWorktreeRoot } from '../graph/seed.js';
import { runUpkeep } from '../upkeep-run.js';
import { runningVersion } from '../upkeep.js';
import { maybeFlushInBackground, track } from '../telemetry/index.js';
import { brand, inBrand } from '../brand.js';
import { canonicalToolName } from './tool-names.js';
import { BRAIN_TOOL_DEFS, BrainProxy, isBrainTool } from './brains.js';

/**
 * MCP tool name → the command enum the telemetry contract knows. A tool absent
 * here is simply not counted: `track` would drop an unlisted command anyway, and
 * mapping by hand keeps the wire vocabulary identical across the CLI and MCP so
 * `ask` means the same thing in both.
 */
const TOOL_COMMAND: Record<string, string> = {
  graft_find_code: 'ask',
  graft_find_all: 'grep',
  graft_trace_calls: 'callers',
  graft_file_api: 'skeleton',
  graft_repo_map: 'map',
  graft_check_freshness: 'check',
};

/** How long `tools/list` waits on the workspace for its brain tools before listing the built-in ones. */
const BRAIN_LIST_WAIT_MS = 4000;

/** Said in `instructions` when this machine is connected to a Trail workspace. */
const BRAINS_LINE =
  "Connected to a Trail workspace: list_brains, get_context, search_rules and get_rules answer from the team's brains (brand, product, conventions, decisions); each result names its brain and rule. Use them for how the team does things, the tools above for the code.";

/** What the brains-only server says when this machine isn't connected (any more). */
const NOT_CONNECTED_LINE = 'Not connected to a Trail workspace: run `trail init --connect <code>` with the code from team.trailhq.com to use its brains here.';

function send(msg: object): void {
  process.stdout.write(`${JSON.stringify(msg)}\n`);
}

function reply(id: unknown, result: object): void {
  send({ jsonrpc: '2.0', id, result });
}

function replyError(id: unknown, code: number, message: string): void {
  send({ jsonrpc: '2.0', id, error: { code, message } });
}

/**
 * Which tools this server admits to having.
 *
 * `hosts/claude-global.ts` registers graft at the *user* MCP scope, which starts this
 * server in every project the user opens — including ones that never asked for graft.
 * Six tool schemas is real context, charged on every turn of every session, and in a
 * repo with no graph every one of them can only answer "run graft build". So a repo
 * that never invited graft is told there is nothing to call.
 *
 * The parent-checkout clause is not an optimization, it is the case the global
 * registration exists for: a fresh `git worktree add` has no `graft/` of its own
 * (it's gitignored, so git never checks it out) and gets one from its parent on the
 * first query — see graph/seed.ts. Gating on this tree alone would hide graft in
 * precisely the worktree the user is trying to work in, which is the bug, inverted.
 *
 * A `--dir` override is an explicit "the graph is over there", so it always
 * advertises without a probe.
 */
function advertised(root: string, dirOverride?: string): typeof TOOLS {
  if (dirOverride !== undefined) return TOOLS;
  if (hasGraftIndex(root)) return TOOLS;
  const main = mainWorktreeRoot(root);
  return main && hasGraftIndex(main) ? TOOLS : [];
}

/**
 * `version` is threaded in from the CLI rather than read here: `readCurrentVersion`
 * resolves package.json relative to the calling module, and from `dist/mcp/` that
 * lookup misses. The caller already knows it.
 */
export function startMcpServer(root: string, dirOverride?: string, version = '0', opts: { brainsOnly?: boolean } = {}): void {
  // `trail mcp --brains`: the one entry Claude Code gets once connected to a
  // workspace. It serves the workspace's brain tools and nothing of the repo's,
  // so it does none of the repo upkeep either: it starts in every project.
  const brainsOnly = opts.brainsOnly === true;
  // The self-maintenance pass, run once at boot. This is the ONLY channel that
  // reaches hosts with no hook support (Cursor, and any plain MCP client): it
  // refreshes rule files an older `graft init` wrote, and kicks off the cached
  // registry check. Both are fail-soft, and the resulting lines ride along in
  // `instructions` below — stdout is protocol-only, so there is nowhere else to
  // put them. Never blocks: the registry fetch happens in a detached child.
  const upkeep = brainsOnly ? [] : runUpkeep(root, runningVersion()).lines;
  for (const line of upkeep) console.error(line);
  // Same deal for the telemetry queue: flushed from a detached child at boot, so
  // a Cursor user who never touches the CLI still gets their events out.
  //
  // Deliberately NOT the first-run notice. This server's stderr goes to an editor
  // log nobody reads, so printing it here would mark the disclosure as shown
  // without anyone having seen it. It stays pending for the next CLI command,
  // and `graft init`'s picker is the channel that reached this user already.
  if (!brainsOnly) maybeFlushInBackground();

  // The workspace's brains, when this machine is connected to one: asked for
  // their list now, so it's in hand by the time the client lists tools.
  const brains = new BrainProxy({ version });
  if (brains.connected()) void brains.listTools();

  const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
  rl.on('line', (line) => {
    const text = line.trim();
    if (!text) return;
    let msg: { id?: unknown; method?: string; params?: Record<string, any> };
    try {
      msg = JSON.parse(text);
    } catch {
      replyError(null, -32700, 'parse error');
      return;
    }
    const { id, method, params } = msg;
    const isNotification = id === undefined;
    switch (method) {
      case 'initialize':
        reply(id, {
          protocolVersion: params?.protocolVersion ?? '2024-11-05',
          capabilities: { tools: {} },
          serverInfo: { name: brand(), version },
          // The one channel that survives tool deferral — see ./instructions.ts.
          instructions: [upkeep.length ? upkeep.join('\n') : '', brainsOnly ? '' : mcpInstructions(), brains.connected() ? BRAINS_LINE : brainsOnly ? NOT_CONNECTED_LINE : '']
            .filter(Boolean)
            .join('\n\n'),
        });
        return;
      case 'notifications/initialized':
      case 'notifications/cancelled':
        return; // notifications get no response
      case 'ping':
        if (!isNotification) reply(id, {});
        return;
      case 'tools/list': {
        if (isNotification) return;
        // Under trail, the same tools as `trail_*`, described in trail's words.
        const local = (brainsOnly ? [] : advertised(root, dirOverride)).map((t) => ({ name: inBrand(t.name), description: inBrand(t.description), inputSchema: t.inputSchema }));
        if (!brains.connected()) {
          reply(id, { tools: local });
          return;
        }
        // Connected: the workspace's brain tools too. A slow workspace never holds the repo tools up for long.
        const capped = new Promise<typeof BRAIN_TOOL_DEFS>((r) => setTimeout(() => r(BRAIN_TOOL_DEFS), BRAIN_LIST_WAIT_MS).unref());
        Promise.race([brains.listTools(), capped]).then(
          (remote) => reply(id, { tools: [...local, ...remote] }),
          () => reply(id, { tools: local }),
        );
        return;
      }
      case 'tools/call': {
        if (isNotification) return;
        const name = String(params?.name ?? '');
        const args = (params?.arguments ?? {}) as Record<string, unknown>;
        if (isBrainTool(name)) {
          // A workspace brain: passed to the workspace as is. Never throws.
          brains.callTool(name, args).then((r) => reply(id, r));
          return;
        }
        if (brainsOnly) {
          reply(id, { content: [{ type: 'text', text: `this server answers the workspace's brain tools only; ${name} isn't one` }], isError: true });
          return;
        }
        // Async because a tool call may rebuild the graph first (see
        // graph/refresh.ts). `callTool` absorbs its own errors, so the only thing
        // that can reject here is a bug — surface it as a JSON-RPC error rather
        // than an unhandled rejection that kills the server.
        callTool(root, name, args, dirOverride).then(
          (r) => {
            // No `hit`: `isError` means the tool failed, which is not the same
            // question as "did the graph have an answer". Absent beats wrong.
            // hasOwn for the same reason as track()'s: a client is free to send
            // `{"name":"constructor"}`, and a plain lookup would hand `track` a
            // function rather than undefined.
            const canonical = canonicalToolName(name);
            const command = Object.hasOwn(TOOL_COMMAND, canonical) ? TOOL_COMMAND[canonical] : undefined;
            track('query', { command, surface: 'mcp' }, { repo: root, host: 'mcp' });
            reply(id, { content: [{ type: 'text', text: r.text }], isError: r.isError });
          },
          (err) => replyError(id, -32603, err instanceof Error ? err.message : String(err)),
        );
        return;
      }
      default:
        if (!isNotification) replyError(id, -32601, `method not found: ${method}`);
    }
  });
  process.stdin.on('end', () => process.exit(0));
}