studiograph 1.3.48-next.21 → 1.3.48-next.211

package/dist/mcp/stdio-proxy.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Transparent stdio→HTTP MCP proxy (Increment 1 of the unified multi-peer
+ * editing model — see ~/.claude/plans/indexed-stirring-turtle.md).
+ *
+ * `studiograph mcp` no longer writes entities directly. Instead it presents an
+ * MCP server to Claude Desktop over stdio and forwards every `tools/list` and
+ * `tools/call` to an upstream MCP `Client`:
+ *
+ *   - REMOTE: a `StreamableHTTPClientTransport` to the running local server's
+ *     `/mcp` endpoint, so the write goes through BodyWriteCoordinator and merges
+ *     into any open live editor (this is the data-loss fix).
+ *   - LOCAL: an in-process server (InMemoryTransport) built lazily on demand,
+ *     used only when no live server is reachable — in which case there is no
+ *     open editor to clobber, so a direct write is safe.
+ *
+ * The upstream is re-selected on EVERY forwarded request (`probeServer`), which
+ * closes the "server started after Claude Desktop" window.
+ *
+ * FAIL-LOUD: if a request is routed to the remote and the transport throws, the
+ * error is surfaced to Claude Desktop and the remote client is marked stale so
+ * the next call re-probes. We NEVER silently retry the failed call against the
+ * local in-process server — that silent fallback is exactly the data-loss path
+ * this increment removes. A `probeServer` `fail` (the server rejected our token)
+ * is likewise surfaced, never downgraded to a local write.
+ *
+ * NOTE: stdout is owned by the JSON-RPC protocol — never console.log here. Use
+ * log.error (writes to stderr).
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { type ProbeDeps, type ProbeResult } from './server-discovery.js';
+export interface StdioProxyOptions {
+    workspacePath: string;
+    /** Per-user API token (or JWT) — sent only to a loopback server. */
+    token: string;
+    /** Builds + connects the in-process fallback client (lazy, cached). */
+    buildLocalClient: () => Promise<Client>;
+    /** Test seams. */
+    probeFn?: (workspacePath: string, token: string, deps?: ProbeDeps) => Promise<ProbeResult>;
+    buildRemoteClient?: (url: string, token: string) => Promise<Client>;
+}
+/** Connect an MCP Client to a running server's /mcp over Streamable HTTP. */
+export declare function createRemoteClient(url: string, token: string): Promise<Client>;
+export declare class StdioProxy {
+    private readonly opts;
+    private readonly probeFn;
+    private readonly buildRemoteClient;
+    private remote;
+    private localClient;
+    constructor(opts: StdioProxyOptions);
+    /**
+     * Probe + return the upstream client for this request. Throws an McpError on
+     * a `fail` probe (token rejected by a live server) — never falls back local.
+     */
+    private selectUpstream;
+    private markRemoteStale;
+    /** Forward a tools/list to the selected upstream. */
+    forwardListTools(params?: any): Promise<any>;
+    /** Forward a tools/call to the selected upstream. */
+    forwardCallTool(params: any): Promise<any>;
+    /** On a transport error against the remote, drop the cached client. */
+    private onUpstreamError;
+    /** Wire the two forwarders onto a low-level MCP Server. */
+    registerHandlers(server: Server): void;
+    /** Build the stdio-facing Server and connect it to Claude Desktop. */
+    start(): Promise<void>;
+}

package/dist/mcp/stdio-proxy.js

@@ -0,0 +1,149 @@
+/**
+ * Transparent stdio→HTTP MCP proxy (Increment 1 of the unified multi-peer
+ * editing model — see ~/.claude/plans/indexed-stirring-turtle.md).
+ *
+ * `studiograph mcp` no longer writes entities directly. Instead it presents an
+ * MCP server to Claude Desktop over stdio and forwards every `tools/list` and
+ * `tools/call` to an upstream MCP `Client`:
+ *
+ *   - REMOTE: a `StreamableHTTPClientTransport` to the running local server's
+ *     `/mcp` endpoint, so the write goes through BodyWriteCoordinator and merges
+ *     into any open live editor (this is the data-loss fix).
+ *   - LOCAL: an in-process server (InMemoryTransport) built lazily on demand,
+ *     used only when no live server is reachable — in which case there is no
+ *     open editor to clobber, so a direct write is safe.
+ *
+ * The upstream is re-selected on EVERY forwarded request (`probeServer`), which
+ * closes the "server started after Claude Desktop" window.
+ *
+ * FAIL-LOUD: if a request is routed to the remote and the transport throws, the
+ * error is surfaced to Claude Desktop and the remote client is marked stale so
+ * the next call re-probes. We NEVER silently retry the failed call against the
+ * local in-process server — that silent fallback is exactly the data-loss path
+ * this increment removes. A `probeServer` `fail` (the server rejected our token)
+ * is likewise surfaced, never downgraded to a local write.
+ *
+ * NOTE: stdout is owned by the JSON-RPC protocol — never console.log here. Use
+ * log.error (writes to stderr).
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, McpError, ErrorCode, } from '@modelcontextprotocol/sdk/types.js';
+import { probeServer } from './server-discovery.js';
+import { MCP_SERVER_INFO, MCP_INSTRUCTIONS } from './tools.js';
+import { log } from '../utils/log.js';
+/** Connect an MCP Client to a running server's /mcp over Streamable HTTP. */
+export async function createRemoteClient(url, token) {
+    const client = new Client({ name: 'studiograph-stdio-proxy', version: '1.0.0' });
+    const transport = new StreamableHTTPClientTransport(new URL(`${url}/mcp`), {
+        requestInit: { headers: { Authorization: `Bearer ${token}` } },
+    });
+    await client.connect(transport);
+    return client;
+}
+export class StdioProxy {
+    opts;
+    probeFn;
+    buildRemoteClient;
+    remote = null;
+    localClient = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.probeFn = opts.probeFn ?? probeServer;
+        this.buildRemoteClient = opts.buildRemoteClient ?? createRemoteClient;
+    }
+    /**
+     * Probe + return the upstream client for this request. Throws an McpError on
+     * a `fail` probe (token rejected by a live server) — never falls back local.
+     */
+    async selectUpstream() {
+        const result = await this.probeFn(this.opts.workspacePath, this.opts.token);
+        if (result.mode === 'fail') {
+            this.markRemoteStale();
+            throw new McpError(ErrorCode.InternalError, `Studiograph server is running but rejected the token: ${result.reason}. ` +
+                `Check STUDIOGRAPH_MCP_TOKEN. (Not falling back to a local write — a live ` +
+                `editor may be open and a local write could overwrite unsaved edits.)`);
+        }
+        if (result.mode === 'remote') {
+            if (this.remote && this.remote.url === result.url)
+                return this.remote.client;
+            // URL changed or no cached remote — (re)connect.
+            this.markRemoteStale();
+            const client = await this.buildRemoteClient(result.url, this.opts.token);
+            this.remote = { client, url: result.url };
+            return client;
+        }
+        // local
+        if (!this.localClient) {
+            this.localClient = await this.opts.buildLocalClient();
+        }
+        return this.localClient;
+    }
+    markRemoteStale() {
+        if (this.remote) {
+            void this.remote.client.close().catch(() => { });
+            this.remote = null;
+        }
+    }
+    /** Forward a tools/list to the selected upstream. */
+    async forwardListTools(params) {
+        const client = await this.selectUpstream();
+        try {
+            return await client.listTools(params);
+        }
+        catch (err) {
+            this.onUpstreamError(err);
+            throw toMcpError(err);
+        }
+    }
+    /** Forward a tools/call to the selected upstream. */
+    async forwardCallTool(params) {
+        const client = await this.selectUpstream();
+        try {
+            // A tool that fails returns a normal result with `isError: true`; the SDK
+            // does NOT throw for that, so it forwards verbatim. A throw here is a
+            // transport/protocol failure — fail loud + re-probe next call.
+            return await client.callTool(params);
+        }
+        catch (err) {
+            this.onUpstreamError(err);
+            throw toMcpError(err);
+        }
+    }
+    /** On a transport error against the remote, drop the cached client. */
+    onUpstreamError(err) {
+        log.error(`[stdio-proxy] upstream call failed: ${err instanceof Error ? err.message : String(err)}`);
+        this.markRemoteStale();
+    }
+    /** Wire the two forwarders onto a low-level MCP Server. */
+    registerHandlers(server) {
+        server.setRequestHandler(ListToolsRequestSchema, async (req) => this.forwardListTools(req.params));
+        server.setRequestHandler(CallToolRequestSchema, async (req) => this.forwardCallTool(req.params));
+    }
+    /** Build the stdio-facing Server and connect it to Claude Desktop. */
+    async start() {
+        const server = new Server(MCP_SERVER_INFO, {
+            instructions: MCP_INSTRUCTIONS,
+            capabilities: { tools: {} },
+        });
+        this.registerHandlers(server);
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        log.error('Studiograph MCP stdio proxy ready');
+        process.on('SIGINT', async () => {
+            this.markRemoteStale();
+            await this.localClient?.close().catch(() => { });
+            await server.close();
+            process.exit(0);
+        });
+    }
+}
+/** Normalize an arbitrary upstream error into an McpError for the client. */
+function toMcpError(err) {
+    if (err instanceof McpError)
+        return err;
+    return new McpError(ErrorCode.InternalError, err instanceof Error ? err.message : String(err));
+}
+//# sourceMappingURL=stdio-proxy.js.map

package/dist/mcp/stdio-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-proxy.js","sourceRoot":"","sources":["../../src/mcp/stdio-proxy.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools.d.ts

@@ -5,11 +5,74 @@
  * methods — no new business logic. Results are returned as JSON text so the
  * MCP client (Claude Desktop) can process structured data.
  *
+ * Every tool enforces per-user access control via `services/access-control.ts`.
+ * Callers (the HTTP /mcp route, the stdio MCP server) must resolve a user
+ * identity before registering tools — `registerTools` requires a user in its
+ * `McpAccessContext` argument so there is no anonymous MCP path.
+ *
  * Note: `inputSchema` is cast to `any` at each call site because the MCP SDK's
  * ZodRawShapeCompat type does not accept ZodObject in TypeScript's strict mode.
  * Runtime schema validation is handled correctly by the SDK regardless.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { WorkspaceManager } from '../core/workspace-manager.js';
-import type { AuthService } from '../services/auth-service.js';
-export declare function registerTools(server: McpServer, wm: WorkspaceManager, authService?: AuthService | null): void;
+import type { AuthService, AuthUser } from '../services/auth-service.js';
+import type { WsHub } from '../server/ws-hub.js';
+import type { CommentService } from '../services/comment-service.js';
+/**
+ * Server identity passed to `new McpServer(...)` on BOTH transports (stdio
+ * `src/mcp/server.ts` + HTTP `src/server/routes/mcp.ts`). Centralized so the
+ * two surfaces can never drift on name/version.
+ */
+export declare const MCP_SERVER_INFO: {
+    readonly name: "studiograph";
+    readonly version: "1.0.0";
+};
+/**
+ * Server-level `instructions` (MCP `ServerOptions.instructions`, surfaced in
+ * the `initialize` response). With Claude Code's tool-search/deferral on, this
+ * is what tells the client WHEN to search for Studiograph's tools — it loads
+ * even when individual tool schemas are deferred. Must be passed in McpServer's
+ * SECOND constructor arg (`new McpServer(MCP_SERVER_INFO, { instructions })`) —
+ * putting it in the serverInfo object silently drops it.
+ *
+ * Budget: Claude Code truncates server instructions at 2KB and front-loads
+ * matter most — keep this short and lead with category + when-to-reach-for-it.
+ */
+export declare const MCP_INSTRUCTIONS: string;
+/**
+ * Tools pinned against Claude Code's tool-search deferral via
+ * `_meta["anthropic/alwaysLoad"]=true` (see PIN_META). These are the handful an
+ * agent needs on essentially every turn, so they stay loaded even when the rest
+ * of the surface is deferred (verified: code.claude.com/docs/en/mcp.md, CC
+ * v2.1.121+). Keep this set SMALL — each pinned tool consumes upfront context.
+ * Exported so tests can assert the pin lands on exactly these tools.
+ */
+export declare const MCP_PINNED_TOOLS: readonly ["search_entities", "list_entities", "get_entity", "create_entity"];
+/** The resolved caller identity for an MCP session. */
+export interface McpAccessContext {
+    user: AuthUser;
+    /**
+     * Optional WebSocket hub. When supplied, entity-mutation tools
+     * (create_entity, update_entity) broadcast `entity_change` events so
+     * connected web clients refresh their views live — matching the HTTP
+     * routes in graph-api.ts. Absent in contexts that have no hub (stdio
+     * server, tests that don't care about live updates).
+     */
+    wsHub?: WsHub;
+    /**
+     * The user-set name on the api_tokens row that authenticated this session
+     * (e.g. "Cursor", "Claude Desktop"). Surfaced in `entity_change` and
+     * `agent_activity` events so other workspace users can see "Christian's
+     * Cursor created entry X" rather than a bare username.
+     */
+    apiTokenName?: string;
+    /**
+     * Optional CommentService. When supplied, generic entity tools dispatch
+     * `entity_type='comment'` reads through the virtual-entity adapter so
+     * agents see comments as first-class typed entities. Absent on stdio
+     * MCP contexts that don't construct a CommentService.
+     */
+    commentService?: CommentService;
+}
+export declare function registerTools(server: McpServer, wm: WorkspaceManager, authService: AuthService, ctx: McpAccessContext): void;