@contentrain/mcp 1.8.0 → 1.9.0

package/dist/server/http/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["createMcpServer"],"sources":["../../../src/server/http/server.ts"],"sourcesContent":["import http from 'node:http'\nimport { randomUUID } from 'node:crypto'\nimport type { AddressInfo } from 'node:net'\nimport type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'\nimport { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'\nimport { createServer as createMcpServer, type ToolProvider } from '../../server.js'\n\nexport interface HttpMcpServerOptions {\n  /** Project root the MCP server operates against (LocalProvider path). */\n  projectRoot: string\n  /** Optional Bearer token — when set, requests must send `Authorization: Bearer <token>`. */\n  authToken?: string\n  /** Mount path for the MCP JSON-RPC endpoint. Defaults to `/mcp`. */\n  path?: string\n}\n\nexport interface HttpMcpServerProviderOptions {\n  /** Pre-built content provider (GitHubProvider, a mock, etc.). */\n  provider: ToolProvider\n  /** Local project root when the provider is a LocalProvider; optional otherwise. */\n  projectRoot?: string\n  /** Optional Bearer token — when set, requests must send `Authorization: Bearer <token>`. */\n  authToken?: string\n  /** Mount path for the MCP JSON-RPC endpoint. Defaults to `/mcp`. */\n  path?: string\n}\n\n/**\n * Multi-tenant entry point — one resolver, many providers.\n *\n * Every new MCP session resolves its own `RepoProvider` from the incoming\n * HTTP request (typically via a workspace / project identifier in a\n * header or path segment). The resolver is invoked exactly once per\n * session; follow-up requests carrying the `Mcp-Session-Id` header are\n * routed to the existing `McpServer` + transport pair.\n *\n * Use this for Studio's hosted MCP Cloud or any agent that drives\n * multiple Contentrain projects through a single HTTP endpoint.\n */\nexport interface HttpMcpServerResolverOptions {\n  /**\n   * Per-session provider resolver. Invoked on the first request of a\n   * new session (typically the MCP `initialize` call). Whatever\n   * provider the resolver returns is bound to that session for its\n   * lifetime.\n   */\n  resolveProvider: (req: http.IncomingMessage) => ToolProvider | Promise<ToolProvider>\n  /** Optional fallback project root injected into each resolved session. */\n  projectRoot?: string\n  /** Optional Bearer token — when set, requests must send `Authorization: Bearer <token>`. */\n  authToken?: string\n  /** Mount path for the MCP JSON-RPC endpoint. Defaults to `/mcp`. */\n  path?: string\n  /**\n   * Idle-session TTL in ms. Sessions that haven't received a request\n   * within this window are closed and their providers discarded.\n   * Defaults to 15 minutes.\n   */\n  sessionTtlMs?: number\n}\n\nexport interface HttpMcpServerHandle {\n  server: http.Server\n  /**\n   * The single shared `McpServer` when the server was started with\n   * `{ projectRoot }` or `{ provider }`. **Not set** in multi-tenant\n   * resolver mode — in that mode each session owns its own server and\n   * you should address them through the HTTP endpoint, not directly.\n   */\n  mcp: McpServer | null\n  url: string\n  close: () => Promise<void>\n}\n\nconst MCP_SESSION_HEADER = 'mcp-session-id'\n\n/**\n * Start an HTTP transport for the MCP server on top of the local project.\n *\n * Stateless, single-endpoint `POST /mcp`. The underlying `McpServer` is\n * the same one the stdio entry point uses, so every tool registered for\n * stdio is available over HTTP with no duplication. Only the transport\n * swaps out.\n *\n * Auth is a simple opaque Bearer token. When `authToken` is supplied,\n * any request without the exact `Authorization: Bearer <token>` header\n * gets a 401 before the MCP transport sees it. Non-local bind addresses\n * should always set this — the `contentrain serve --mcpHttp` CLI hard-\n * errors when it detects a non-localhost bind without a token.\n */\nexport async function startHttpMcpServer(\n  opts: HttpMcpServerOptions & { port: number, host?: string },\n): Promise<HttpMcpServerHandle> {\n  const mcp = createMcpServer(opts.projectRoot)\n  const transport = new StreamableHTTPServerTransport({\n    sessionIdGenerator: () => randomUUID(),\n  })\n  await mcp.connect(transport)\n\n  return startHttpMcpServerInternal({\n    mode: 'single',\n    mcp,\n    transport,\n    port: opts.port,\n    host: opts.host,\n    authToken: opts.authToken,\n    path: opts.path,\n  })\n}\n\n/**\n * Variant accepting a pre-built provider or a per-request resolver.\n *\n * **Single-provider mode** (`{ provider }`):\n * All sessions share one `McpServer` backed by the given provider.\n * Good for CI runners, single-tenant deployments, or any case where\n * the backing repository is fixed at boot time.\n *\n * **Multi-tenant mode** (`{ resolveProvider }`):\n * Each session resolves its own provider from the incoming request.\n * The resolver is invoked once per session; subsequent requests with\n * the `Mcp-Session-Id` header reuse the same server + transport pair.\n * Idle sessions are closed after `sessionTtlMs` (default 15m).\n */\nexport async function startHttpMcpServerWith(\n  opts: (HttpMcpServerProviderOptions | HttpMcpServerResolverOptions) & { port: number, host?: string },\n): Promise<HttpMcpServerHandle> {\n  if ('resolveProvider' in opts) {\n    return startMultiTenantHttpMcpServer(opts)\n  }\n  const mcp = createMcpServer({ provider: opts.provider, projectRoot: opts.projectRoot })\n  const transport = new StreamableHTTPServerTransport({\n    sessionIdGenerator: () => randomUUID(),\n  })\n  await mcp.connect(transport)\n  return startHttpMcpServerInternal({\n    mode: 'single',\n    mcp,\n    transport,\n    port: opts.port,\n    host: opts.host,\n    authToken: opts.authToken,\n    path: opts.path,\n  })\n}\n\ninterface MultiTenantSession {\n  mcp: McpServer\n  transport: StreamableHTTPServerTransport\n  lastUsed: number\n}\n\nasync function startMultiTenantHttpMcpServer(\n  opts: HttpMcpServerResolverOptions & { port: number, host?: string },\n): Promise<HttpMcpServerHandle> {\n  const sessions = new Map<string, MultiTenantSession>()\n  const ttl = opts.sessionTtlMs ?? 15 * 60 * 1000\n  const mountPath = opts.path ?? '/mcp'\n  const host = opts.host ?? '127.0.0.1'\n\n  async function disposeSession(sessionId: string): Promise<void> {\n    const session = sessions.get(sessionId)\n    if (!session) return\n    sessions.delete(sessionId)\n    await session.transport.close().catch(() => { /* best-effort */ })\n    await session.mcp.close().catch(() => { /* best-effort */ })\n  }\n\n  const reaper = setInterval(() => {\n    const now = Date.now()\n    for (const [id, session] of sessions) {\n      if (now - session.lastUsed > ttl) void disposeSession(id)\n    }\n  }, Math.min(ttl, 60_000)).unref()\n\n  const server = http.createServer((req, res) => {\n    void handleMultiTenantRequest(req, res, {\n      mountPath,\n      authToken: opts.authToken,\n      resolveProvider: opts.resolveProvider,\n      projectRoot: opts.projectRoot,\n      sessions,\n    })\n  })\n\n  await new Promise<void>((resolve, reject) => {\n    server.once('error', reject)\n    server.listen(opts.port, host, () => {\n      server.off('error', reject)\n      resolve()\n    })\n  })\n\n  const address = server.address() as AddressInfo\n  const url = `http://${host}:${address.port}${mountPath}`\n\n  return {\n    server,\n    mcp: null,\n    url,\n    close: async () => {\n      clearInterval(reaper)\n      await new Promise<void>((resolve, reject) => {\n        server.close(err => (err ? reject(err) : resolve()))\n      })\n      const ids = [...sessions.keys()]\n      await Promise.all(ids.map(id => disposeSession(id)))\n    },\n  }\n}\n\nasync function handleMultiTenantRequest(\n  req: http.IncomingMessage,\n  res: http.ServerResponse,\n  ctx: {\n    mountPath: string\n    authToken?: string\n    resolveProvider: (req: http.IncomingMessage) => ToolProvider | Promise<ToolProvider>\n    projectRoot?: string\n    sessions: Map<string, MultiTenantSession>\n  },\n): Promise<void> {\n  if (!applyRouteChecks(req, res, { mountPath: ctx.mountPath, authToken: ctx.authToken })) return\n\n  const existingSessionId = pickSessionId(req.headers[MCP_SESSION_HEADER])\n  if (existingSessionId && ctx.sessions.has(existingSessionId)) {\n    const session = ctx.sessions.get(existingSessionId)!\n    session.lastUsed = Date.now()\n    try {\n      await session.transport.handleRequest(req, res)\n    } catch (error) {\n      writeInternalError(res, error)\n    }\n    return\n  }\n\n  try {\n    const provider = await ctx.resolveProvider(req)\n    const mcp = createMcpServer({ provider, projectRoot: ctx.projectRoot })\n    const transport = new StreamableHTTPServerTransport({\n      sessionIdGenerator: () => randomUUID(),\n      onsessioninitialized: (sessionId: string) => {\n        ctx.sessions.set(sessionId, { mcp, transport, lastUsed: Date.now() })\n      },\n    })\n    await mcp.connect(transport)\n    await transport.handleRequest(req, res)\n  } catch (error) {\n    writeInternalError(res, error)\n  }\n}\n\nfunction pickSessionId(header: string | string[] | undefined): string | undefined {\n  if (!header) return undefined\n  return Array.isArray(header) ? header[0] : header\n}\n\nfunction applyRouteChecks(\n  req: http.IncomingMessage,\n  res: http.ServerResponse,\n  ctx: { mountPath: string, authToken?: string },\n): boolean {\n  if (req.method !== 'POST' && req.method !== 'GET' && req.method !== 'DELETE') {\n    writeJson(res, 405, { error: 'Method Not Allowed' })\n    return false\n  }\n  if (!req.url || !req.url.startsWith(ctx.mountPath)) {\n    writeJson(res, 404, { error: 'Not Found' })\n    return false\n  }\n  if (ctx.authToken) {\n    const header = req.headers.authorization\n    if (header !== `Bearer ${ctx.authToken}`) {\n      writeJson(res, 401, { error: 'Unauthorized' })\n      return false\n    }\n  }\n  return true\n}\n\nasync function startHttpMcpServerInternal(input: {\n  mode: 'single'\n  mcp: McpServer\n  transport: StreamableHTTPServerTransport\n  port: number\n  host?: string\n  authToken?: string\n  path?: string\n}): Promise<HttpMcpServerHandle> {\n  const { mcp, transport } = input\n  const mountPath = input.path ?? '/mcp'\n  const host = input.host ?? '127.0.0.1'\n\n  const server = http.createServer((req, res) => {\n    void handleRequest(req, res, { transport, mountPath, authToken: input.authToken })\n  })\n\n  await new Promise<void>((resolve, reject) => {\n    server.once('error', reject)\n    server.listen(input.port, host, () => {\n      server.off('error', reject)\n      resolve()\n    })\n  })\n\n  const address = server.address() as AddressInfo\n  const url = `http://${host}:${address.port}${mountPath}`\n\n  return {\n    server,\n    mcp,\n    url,\n    close: async () => {\n      await new Promise<void>((resolve, reject) => {\n        server.close(err => (err ? reject(err) : resolve()))\n      })\n      await transport.close().catch(() => { /* best-effort */ })\n      await mcp.close().catch(() => { /* best-effort */ })\n    },\n  }\n}\n\nasync function handleRequest(\n  req: http.IncomingMessage,\n  res: http.ServerResponse,\n  ctx: { transport: StreamableHTTPServerTransport, mountPath: string, authToken?: string },\n): Promise<void> {\n  if (!applyRouteChecks(req, res, { mountPath: ctx.mountPath, authToken: ctx.authToken })) return\n\n  try {\n    await ctx.transport.handleRequest(req, res)\n  } catch (error) {\n    writeInternalError(res, error)\n  }\n}\n\nfunction writeInternalError(res: http.ServerResponse, error: unknown): void {\n  if (res.headersSent) return\n  writeJson(res, 500, {\n    error: 'Internal Server Error',\n    message: error instanceof Error ? error.message : String(error),\n  })\n}\n\nfunction writeJson(res: http.ServerResponse, status: number, body: unknown): void {\n  res.writeHead(status, { 'Content-Type': 'application/json' })\n  res.end(JSON.stringify(body))\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":["createMcpServer"],"sources":["../../../src/server/http/server.ts"],"sourcesContent":["import http from 'node:http'\nimport { randomUUID } from 'node:crypto'\nimport type { AddressInfo } from 'node:net'\nimport type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'\nimport { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'\nimport { createServer as createMcpServer, type ToolProvider } from '../../server.js'\n\nexport interface HttpMcpServerOptions {\n  /** Project root the MCP server operates against (LocalProvider path). */\n  projectRoot: string\n  /** Optional Bearer token — when set, requests must send `Authorization: Bearer <token>`. */\n  authToken?: string\n  /** Mount path for the MCP JSON-RPC endpoint. Defaults to `/mcp`. */\n  path?: string\n}\n\nexport interface HttpMcpServerProviderOptions {\n  /** Pre-built content provider (GitHubProvider, a mock, etc.). */\n  provider: ToolProvider\n  /** Local project root when the provider is a LocalProvider; optional otherwise. */\n  projectRoot?: string\n  /** Optional Bearer token — when set, requests must send `Authorization: Bearer <token>`. */\n  authToken?: string\n  /** Mount path for the MCP JSON-RPC endpoint. Defaults to `/mcp`. */\n  path?: string\n}\n\n/**\n * Multi-tenant entry point — one resolver, many providers.\n *\n * Every new MCP session resolves its own `RepoProvider` from the incoming\n * HTTP request (typically via a workspace / project identifier in a\n * header or path segment). The resolver is invoked exactly once per\n * session; follow-up requests carrying the `Mcp-Session-Id` header are\n * routed to the existing `McpServer` + transport pair.\n *\n * Use this for Studio's hosted MCP Cloud or any agent that drives\n * multiple Contentrain projects through a single HTTP endpoint.\n */\nexport interface HttpMcpServerResolverOptions {\n  /**\n   * Per-session provider resolver. Invoked on the first request of a\n   * new session (typically the MCP `initialize` call). Whatever\n   * provider the resolver returns is bound to that session for its\n   * lifetime.\n   */\n  resolveProvider: (req: http.IncomingMessage) => ToolProvider | Promise<ToolProvider>\n  /** Optional fallback project root injected into each resolved session. */\n  projectRoot?: string\n  /** Optional Bearer token — when set, requests must send `Authorization: Bearer <token>`. */\n  authToken?: string\n  /** Mount path for the MCP JSON-RPC endpoint. Defaults to `/mcp`. */\n  path?: string\n  /**\n   * Idle-session TTL in ms. Sessions that haven't received a request\n   * within this window are closed and their providers discarded.\n   * Defaults to 15 minutes.\n   */\n  sessionTtlMs?: number\n  /**\n   * Optional tenant binding. When set, the fingerprint computed on the\n   * session-creating request is stored with the session, and every\n   * follow-up request carrying that `Mcp-Session-Id` must produce the\n   * same fingerprint (e.g. derive it from the tenant headers the proxy\n   * injects). A mismatch answers 404 — per the Streamable HTTP spec the\n   * client then re-initializes and gets a session bound to its own\n   * provider. This closes session-id replay across tenants.\n   */\n  sessionFingerprint?: (req: http.IncomingMessage) => string | undefined\n}\n\nexport interface HttpMcpServerHandle {\n  server: http.Server\n  /**\n   * The single shared `McpServer` when the server was started with\n   * `{ projectRoot }` or `{ provider }`. **Not set** in multi-tenant\n   * resolver mode — in that mode each session owns its own server and\n   * you should address them through the HTTP endpoint, not directly.\n   */\n  mcp: McpServer | null\n  url: string\n  close: () => Promise<void>\n}\n\nconst MCP_SESSION_HEADER = 'mcp-session-id'\n\n/**\n * Start an HTTP transport for the MCP server on top of the local project.\n *\n * Stateless, single-endpoint `POST /mcp`. The underlying `McpServer` is\n * the same one the stdio entry point uses, so every tool registered for\n * stdio is available over HTTP with no duplication. Only the transport\n * swaps out.\n *\n * Auth is a simple opaque Bearer token. When `authToken` is supplied,\n * any request without the exact `Authorization: Bearer <token>` header\n * gets a 401 before the MCP transport sees it. Non-local bind addresses\n * should always set this — the `contentrain serve --mcpHttp` CLI hard-\n * errors when it detects a non-localhost bind without a token.\n */\nexport async function startHttpMcpServer(\n  opts: HttpMcpServerOptions & { port: number, host?: string },\n): Promise<HttpMcpServerHandle> {\n  const mcp = createMcpServer(opts.projectRoot)\n  const transport = new StreamableHTTPServerTransport({\n    sessionIdGenerator: () => randomUUID(),\n  })\n  await mcp.connect(transport)\n\n  return startHttpMcpServerInternal({\n    mode: 'single',\n    mcp,\n    transport,\n    port: opts.port,\n    host: opts.host,\n    authToken: opts.authToken,\n    path: opts.path,\n  })\n}\n\n/**\n * Variant accepting a pre-built provider or a per-request resolver.\n *\n * **Single-provider mode** (`{ provider }`):\n * All sessions share one `McpServer` backed by the given provider.\n * Good for CI runners, single-tenant deployments, or any case where\n * the backing repository is fixed at boot time.\n *\n * **Multi-tenant mode** (`{ resolveProvider }`):\n * Each session resolves its own provider from the incoming request.\n * The resolver is invoked once per session; subsequent requests with\n * the `Mcp-Session-Id` header reuse the same server + transport pair.\n * Idle sessions are closed after `sessionTtlMs` (default 15m).\n */\nexport async function startHttpMcpServerWith(\n  opts: (HttpMcpServerProviderOptions | HttpMcpServerResolverOptions) & { port: number, host?: string },\n): Promise<HttpMcpServerHandle> {\n  if ('resolveProvider' in opts) {\n    return startMultiTenantHttpMcpServer(opts)\n  }\n  const mcp = createMcpServer({ provider: opts.provider, projectRoot: opts.projectRoot })\n  const transport = new StreamableHTTPServerTransport({\n    sessionIdGenerator: () => randomUUID(),\n  })\n  await mcp.connect(transport)\n  return startHttpMcpServerInternal({\n    mode: 'single',\n    mcp,\n    transport,\n    port: opts.port,\n    host: opts.host,\n    authToken: opts.authToken,\n    path: opts.path,\n  })\n}\n\ninterface MultiTenantSession {\n  mcp: McpServer\n  transport: StreamableHTTPServerTransport\n  lastUsed: number\n  /** Tenant fingerprint captured on the session-creating request (when `sessionFingerprint` is configured). */\n  fingerprint: string | undefined\n}\n\nasync function startMultiTenantHttpMcpServer(\n  opts: HttpMcpServerResolverOptions & { port: number, host?: string },\n): Promise<HttpMcpServerHandle> {\n  const sessions = new Map<string, MultiTenantSession>()\n  const ttl = opts.sessionTtlMs ?? 15 * 60 * 1000\n  const mountPath = opts.path ?? '/mcp'\n  const host = opts.host ?? '127.0.0.1'\n\n  async function disposeSession(sessionId: string): Promise<void> {\n    const session = sessions.get(sessionId)\n    if (!session) return\n    sessions.delete(sessionId)\n    await session.transport.close().catch(() => { /* best-effort */ })\n    await session.mcp.close().catch(() => { /* best-effort */ })\n  }\n\n  const reaper = setInterval(() => {\n    const now = Date.now()\n    for (const [id, session] of sessions) {\n      if (now - session.lastUsed > ttl) void disposeSession(id)\n    }\n  }, Math.min(ttl, 60_000)).unref()\n\n  const server = http.createServer((req, res) => {\n    void handleMultiTenantRequest(req, res, {\n      mountPath,\n      authToken: opts.authToken,\n      resolveProvider: opts.resolveProvider,\n      projectRoot: opts.projectRoot,\n      sessionFingerprint: opts.sessionFingerprint,\n      sessions,\n    })\n  })\n\n  await new Promise<void>((resolve, reject) => {\n    server.once('error', reject)\n    server.listen(opts.port, host, () => {\n      server.off('error', reject)\n      resolve()\n    })\n  })\n\n  const address = server.address() as AddressInfo\n  const url = `http://${host}:${address.port}${mountPath}`\n\n  return {\n    server,\n    mcp: null,\n    url,\n    close: async () => {\n      clearInterval(reaper)\n      await new Promise<void>((resolve, reject) => {\n        server.close(err => (err ? reject(err) : resolve()))\n      })\n      const ids = [...sessions.keys()]\n      await Promise.all(ids.map(id => disposeSession(id)))\n    },\n  }\n}\n\nasync function handleMultiTenantRequest(\n  req: http.IncomingMessage,\n  res: http.ServerResponse,\n  ctx: {\n    mountPath: string\n    authToken?: string\n    resolveProvider: (req: http.IncomingMessage) => ToolProvider | Promise<ToolProvider>\n    projectRoot?: string\n    sessionFingerprint?: (req: http.IncomingMessage) => string | undefined\n    sessions: Map<string, MultiTenantSession>\n  },\n): Promise<void> {\n  if (!applyRouteChecks(req, res, { mountPath: ctx.mountPath, authToken: ctx.authToken })) return\n\n  const existingSessionId = pickSessionId(req.headers[MCP_SESSION_HEADER])\n  if (existingSessionId && ctx.sessions.has(existingSessionId)) {\n    const session = ctx.sessions.get(existingSessionId)!\n    // Tenant binding: a session id minted for one tenant must not be\n    // honored for another. Answer 404 (not 403) so a legitimate client\n    // that landed on a foreign session re-initializes its own.\n    if (ctx.sessionFingerprint && ctx.sessionFingerprint(req) !== session.fingerprint) {\n      writeJson(res, 404, { error: 'Session not found' })\n      return\n    }\n    session.lastUsed = Date.now()\n    try {\n      await session.transport.handleRequest(req, res)\n    } catch (error) {\n      writeInternalError(res, error)\n    }\n    return\n  }\n\n  try {\n    const provider = await ctx.resolveProvider(req)\n    const fingerprint = ctx.sessionFingerprint?.(req)\n    const mcp = createMcpServer({ provider, projectRoot: ctx.projectRoot })\n    const transport = new StreamableHTTPServerTransport({\n      sessionIdGenerator: () => randomUUID(),\n      onsessioninitialized: (sessionId: string) => {\n        ctx.sessions.set(sessionId, { mcp, transport, lastUsed: Date.now(), fingerprint })\n      },\n    })\n    await mcp.connect(transport)\n    await transport.handleRequest(req, res)\n  } catch (error) {\n    writeInternalError(res, error)\n  }\n}\n\nfunction pickSessionId(header: string | string[] | undefined): string | undefined {\n  if (!header) return undefined\n  return Array.isArray(header) ? header[0] : header\n}\n\nfunction applyRouteChecks(\n  req: http.IncomingMessage,\n  res: http.ServerResponse,\n  ctx: { mountPath: string, authToken?: string },\n): boolean {\n  if (req.method !== 'POST' && req.method !== 'GET' && req.method !== 'DELETE') {\n    writeJson(res, 405, { error: 'Method Not Allowed' })\n    return false\n  }\n  if (!req.url || !req.url.startsWith(ctx.mountPath)) {\n    writeJson(res, 404, { error: 'Not Found' })\n    return false\n  }\n  if (ctx.authToken) {\n    const header = req.headers.authorization\n    if (header !== `Bearer ${ctx.authToken}`) {\n      writeJson(res, 401, { error: 'Unauthorized' })\n      return false\n    }\n  }\n  return true\n}\n\nasync function startHttpMcpServerInternal(input: {\n  mode: 'single'\n  mcp: McpServer\n  transport: StreamableHTTPServerTransport\n  port: number\n  host?: string\n  authToken?: string\n  path?: string\n}): Promise<HttpMcpServerHandle> {\n  const { mcp, transport } = input\n  const mountPath = input.path ?? '/mcp'\n  const host = input.host ?? '127.0.0.1'\n\n  const server = http.createServer((req, res) => {\n    void handleRequest(req, res, { transport, mountPath, authToken: input.authToken })\n  })\n\n  await new Promise<void>((resolve, reject) => {\n    server.once('error', reject)\n    server.listen(input.port, host, () => {\n      server.off('error', reject)\n      resolve()\n    })\n  })\n\n  const address = server.address() as AddressInfo\n  const url = `http://${host}:${address.port}${mountPath}`\n\n  return {\n    server,\n    mcp,\n    url,\n    close: async () => {\n      await new Promise<void>((resolve, reject) => {\n        server.close(err => (err ? reject(err) : resolve()))\n      })\n      await transport.close().catch(() => { /* best-effort */ })\n      await mcp.close().catch(() => { /* best-effort */ })\n    },\n  }\n}\n\nasync function handleRequest(\n  req: http.IncomingMessage,\n  res: http.ServerResponse,\n  ctx: { transport: StreamableHTTPServerTransport, mountPath: string, authToken?: string },\n): Promise<void> {\n  if (!applyRouteChecks(req, res, { mountPath: ctx.mountPath, authToken: ctx.authToken })) return\n\n  try {\n    await ctx.transport.handleRequest(req, res)\n  } catch (error) {\n    writeInternalError(res, error)\n  }\n}\n\nfunction writeInternalError(res: http.ServerResponse, error: unknown): void {\n  if (res.headersSent) return\n  writeJson(res, 500, {\n    error: 'Internal Server Error',\n    message: error instanceof Error ? error.message : String(error),\n  })\n}\n\nfunction writeJson(res: http.ServerResponse, status: number, body: unknown): void {\n  res.writeHead(status, { 'Content-Type': 'application/json' })\n  res.end(JSON.stringify(body))\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAoFA,MAAM,qBAAqB;;;;;;;;;;;;;;;AAgB3B,eAAsB,mBACpB,MAC8B;CAC9B,MAAM,MAAMA,aAAgB,KAAK,YAAY;CAC7C,MAAM,YAAY,IAAI,8BAA8B,EAClD,0BAA0B,YAAY,EACvC,CAAC;AACF,OAAM,IAAI,QAAQ,UAAU;AAE5B,QAAO,2BAA2B;EAChC,MAAM;EACN;EACA;EACA,MAAM,KAAK;EACX,MAAM,KAAK;EACX,WAAW,KAAK;EAChB,MAAM,KAAK;EACZ,CAAC;;;;;;;;;;;;;;;;AAiBJ,eAAsB,uBACpB,MAC8B;AAC9B,KAAI,qBAAqB,KACvB,QAAO,8BAA8B,KAAK;CAE5C,MAAM,MAAMA,aAAgB;EAAE,UAAU,KAAK;EAAU,aAAa,KAAK;EAAa,CAAC;CACvF,MAAM,YAAY,IAAI,8BAA8B,EAClD,0BAA0B,YAAY,EACvC,CAAC;AACF,OAAM,IAAI,QAAQ,UAAU;AAC5B,QAAO,2BAA2B;EAChC,MAAM;EACN;EACA;EACA,MAAM,KAAK;EACX,MAAM,KAAK;EACX,WAAW,KAAK;EAChB,MAAM,KAAK;EACZ,CAAC;;AAWJ,eAAe,8BACb,MAC8B;CAC9B,MAAM,2BAAW,IAAI,KAAiC;CACtD,MAAM,MAAM,KAAK,gBAAgB,MAAU;CAC3C,MAAM,YAAY,KAAK,QAAQ;CAC/B,MAAM,OAAO,KAAK,QAAQ;CAE1B,eAAe,eAAe,WAAkC;EAC9D,MAAM,UAAU,SAAS,IAAI,UAAU;AACvC,MAAI,CAAC,QAAS;AACd,WAAS,OAAO,UAAU;AAC1B,QAAM,QAAQ,UAAU,OAAO,CAAC,YAAY,GAAsB;AAClE,QAAM,QAAQ,IAAI,OAAO,CAAC,YAAY,GAAsB;;CAG9D,MAAM,SAAS,kBAAkB;EAC/B,MAAM,MAAM,KAAK,KAAK;AACtB,OAAK,MAAM,CAAC,IAAI,YAAY,SAC1B,KAAI,MAAM,QAAQ,WAAW,IAAU,gBAAe,GAAG;IAE1D,KAAK,IAAI,KAAK,IAAO,CAAC,CAAC,OAAO;CAEjC,MAAM,SAAS,KAAK,cAAc,KAAK,QAAQ;AACxC,2BAAyB,KAAK,KAAK;GACtC;GACA,WAAW,KAAK;GAChB,iBAAiB,KAAK;GACtB,aAAa,KAAK;GAClB,oBAAoB,KAAK;GACzB;GACD,CAAC;GACF;AAEF,OAAM,IAAI,SAAe,SAAS,WAAW;AAC3C,SAAO,KAAK,SAAS,OAAO;AAC5B,SAAO,OAAO,KAAK,MAAM,YAAY;AACnC,UAAO,IAAI,SAAS,OAAO;AAC3B,YAAS;IACT;GACF;AAKF,QAAO;EACL;EACA,KAAK;EACL,KALU,UAAU,KAAK,GADX,OAAO,SAAS,CACM,OAAO;EAM3C,OAAO,YAAY;AACjB,iBAAc,OAAO;AACrB,SAAM,IAAI,SAAe,SAAS,WAAW;AAC3C,WAAO,OAAM,QAAQ,MAAM,OAAO,IAAI,GAAG,SAAS,CAAE;KACpD;GACF,MAAM,MAAM,CAAC,GAAG,SAAS,MAAM,CAAC;AAChC,SAAM,QAAQ,IAAI,IAAI,KAAI,OAAM,eAAe,GAAG,CAAC,CAAC;;EAEvD;;AAGH,eAAe,yBACb,KACA,KACA,KAQe;AACf,KAAI,CAAC,iBAAiB,KAAK,KAAK;EAAE,WAAW,IAAI;EAAW,WAAW,IAAI;EAAW,CAAC,CAAE;CAEzF,MAAM,oBAAoB,cAAc,IAAI,QAAQ,oBAAoB;AACxE,KAAI,qBAAqB,IAAI,SAAS,IAAI,kBAAkB,EAAE;EAC5D,MAAM,UAAU,IAAI,SAAS,IAAI,kBAAkB;AAInD,MAAI,IAAI,sBAAsB,IAAI,mBAAmB,IAAI,KAAK,QAAQ,aAAa;AACjF,aAAU,KAAK,KAAK,EAAE,OAAO,qBAAqB,CAAC;AACnD;;AAEF,UAAQ,WAAW,KAAK,KAAK;AAC7B,MAAI;AACF,SAAM,QAAQ,UAAU,cAAc,KAAK,IAAI;WACxC,OAAO;AACd,sBAAmB,KAAK,MAAM;;AAEhC;;AAGF,KAAI;EACF,MAAM,WAAW,MAAM,IAAI,gBAAgB,IAAI;EAC/C,MAAM,cAAc,IAAI,qBAAqB,IAAI;EACjD,MAAM,MAAMA,aAAgB;GAAE;GAAU,aAAa,IAAI;GAAa,CAAC;EACvE,MAAM,YAAY,IAAI,8BAA8B;GAClD,0BAA0B,YAAY;GACtC,uBAAuB,cAAsB;AAC3C,QAAI,SAAS,IAAI,WAAW;KAAE;KAAK;KAAW,UAAU,KAAK,KAAK;KAAE;KAAa,CAAC;;GAErF,CAAC;AACF,QAAM,IAAI,QAAQ,UAAU;AAC5B,QAAM,UAAU,cAAc,KAAK,IAAI;UAChC,OAAO;AACd,qBAAmB,KAAK,MAAM;;;AAIlC,SAAS,cAAc,QAA2D;AAChF,KAAI,CAAC,OAAQ,QAAO,KAAA;AACpB,QAAO,MAAM,QAAQ,OAAO,GAAG,OAAO,KAAK;;AAG7C,SAAS,iBACP,KACA,KACA,KACS;AACT,KAAI,IAAI,WAAW,UAAU,IAAI,WAAW,SAAS,IAAI,WAAW,UAAU;AAC5E,YAAU,KAAK,KAAK,EAAE,OAAO,sBAAsB,CAAC;AACpD,SAAO;;AAET,KAAI,CAAC,IAAI,OAAO,CAAC,IAAI,IAAI,WAAW,IAAI,UAAU,EAAE;AAClD,YAAU,KAAK,KAAK,EAAE,OAAO,aAAa,CAAC;AAC3C,SAAO;;AAET,KAAI,IAAI;MACS,IAAI,QAAQ,kBACZ,UAAU,IAAI,aAAa;AACxC,aAAU,KAAK,KAAK,EAAE,OAAO,gBAAgB,CAAC;AAC9C,UAAO;;;AAGX,QAAO;;AAGT,eAAe,2BAA2B,OAQT;CAC/B,MAAM,EAAE,KAAK,cAAc;CAC3B,MAAM,YAAY,MAAM,QAAQ;CAChC,MAAM,OAAO,MAAM,QAAQ;CAE3B,MAAM,SAAS,KAAK,cAAc,KAAK,QAAQ;AACxC,gBAAc,KAAK,KAAK;GAAE;GAAW;GAAW,WAAW,MAAM;GAAW,CAAC;GAClF;AAEF,OAAM,IAAI,SAAe,SAAS,WAAW;AAC3C,SAAO,KAAK,SAAS,OAAO;AAC5B,SAAO,OAAO,MAAM,MAAM,YAAY;AACpC,UAAO,IAAI,SAAS,OAAO;AAC3B,YAAS;IACT;GACF;AAKF,QAAO;EACL;EACA;EACA,KALU,UAAU,KAAK,GADX,OAAO,SAAS,CACM,OAAO;EAM3C,OAAO,YAAY;AACjB,SAAM,IAAI,SAAe,SAAS,WAAW;AAC3C,WAAO,OAAM,QAAQ,MAAM,OAAO,IAAI,GAAG,SAAS,CAAE;KACpD;AACF,SAAM,UAAU,OAAO,CAAC,YAAY,GAAsB;AAC1D,SAAM,IAAI,OAAO,CAAC,YAAY,GAAsB;;EAEvD;;AAGH,eAAe,cACb,KACA,KACA,KACe;AACf,KAAI,CAAC,iBAAiB,KAAK,KAAK;EAAE,WAAW,IAAI;EAAW,WAAW,IAAI;EAAW,CAAC,CAAE;AAEzF,KAAI;AACF,QAAM,IAAI,UAAU,cAAc,KAAK,IAAI;UACpC,OAAO;AACd,qBAAmB,KAAK,MAAM;;;AAIlC,SAAS,mBAAmB,KAA0B,OAAsB;AAC1E,KAAI,IAAI,YAAa;AACrB,WAAU,KAAK,KAAK;EAClB,OAAO;EACP,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;EAChE,CAAC;;AAGJ,SAAS,UAAU,KAA0B,QAAgB,MAAqB;AAChF,KAAI,UAAU,QAAQ,EAAE,gBAAgB,oBAAoB,CAAC;AAC7D,KAAI,IAAI,KAAK,UAAU,KAAK,CAAC"}

package/dist/{server-DZBcZWhE.d.mts → server-B1KfvywF.d.mts}

@@ -1,4 +1,4 @@
-import { u as RepoProvider } from "./index-D0wQJSgs.mjs";
+import { u as RepoProvider } from "./index-6yasXNLQ.mjs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 //#region src/server.d.ts
@@ -10,6 +10,12 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  * not need to migrate.
  */
 type ToolProvider = RepoProvider;
+/**
+ * Default MCP `instructions` surfaced to clients at initialize time.
+ * Deliberately kept under 512 characters — directory listings and client
+ * UIs truncate longer strings. Override via `CreateServerOptions.instructions`.
+ */
+declare const DEFAULT_INSTRUCTIONS: string;
 interface CreateServerOptions {
   /**
    * Content provider — drives reads (and, in later phases, writes) through
@@ -21,13 +27,20 @@ interface CreateServerOptions {
   /**
    * Local project root. When the provider is a `LocalProvider`, its own
    * `projectRoot` is used as the fallback. Tools that require local disk
-   * (normalize, setup, git submit/merge) short-circuit with a capability
-   * error when no projectRoot is available.
+   * (normalize, setup, git submit/merge) are not registered when no
+   * projectRoot is available.
    */
   projectRoot?: string;
+  /**
+   * MCP `instructions` string sent to clients in the `initialize` response.
+   * Defaults to `DEFAULT_INSTRUCTIONS`; pass an empty string to omit
+   * instructions entirely.
+   */
+  instructions?: string;
 }
 /**
- * Create an MCP server instance with every Contentrain tool registered.
+ * Create an MCP server instance with every *available* Contentrain tool
+ * registered.
  *
  * Two signatures:
  *
@@ -37,14 +50,16 @@ interface CreateServerOptions {
  * - `createServer({ provider, projectRoot? })` — phase 5.3 flow. Any
  *   `RepoProvider` (including `GitHubProvider`) drives reads and writes. If
  *   the provider is a `LocalProvider` and `projectRoot` is omitted, the
- *   provider's own `projectRoot` is used. Otherwise `projectRoot` stays
- *   undefined and tools that need local disk report a capability error.
+ *   provider's own `projectRoot` is used.
  *
- * Public MCP tool surface (names, parameters, response JSON shape) is
- * unchanged across both signatures.
+ * Tool listing is capability-aware: tools whose requirements
+ * (`TOOL_REQUIREMENTS`) cannot be met by the resolved provider +
+ * projectRoot pair are not registered, so `tools/list` only advertises
+ * tools that can actually succeed. With a `LocalProvider` (stdio and CLI
+ * flows) all 19 tools remain registered — behavior there is unchanged.
  */
 declare function createServer(projectRoot: string): McpServer;
 declare function createServer(opts: CreateServerOptions): McpServer;
 //#endregion
-export { ToolProvider as n, createServer as r, CreateServerOptions as t };
-//# sourceMappingURL=server-DZBcZWhE.d.mts.map
+export { createServer as i, DEFAULT_INSTRUCTIONS as n, ToolProvider as r, CreateServerOptions as t };
+//# sourceMappingURL=server-B1KfvywF.d.mts.map

package/dist/server-B1KfvywF.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-B1KfvywF.d.mts","names":[],"sources":["../src/server.ts"],"mappings":";;;;;;AAYA;;;;;KAAY,YAAA,GAAe,YAAA;;;;;AA0B3B;cAVa,oBAAA;AAAA,UAUI,mBAAA;EAOQ;;;;;;EAAvB,QAAA,GAAW,YAAA;EAiEG;;;;;AAChB;EA3DE,WAAA;;;;;;EAMA,YAAA;AAAA;;;;;;;;;;;;;;;;;;;;;iBAoDc,YAAA,CAAa,WAAA,WAAsB,SAAA;AAAA,iBACnC,YAAA,CAAa,IAAA,EAAM,mBAAA,GAAsB,SAAA"}

package/dist/{server-tTuinKHD.mjs → server-B6_fzRmK.mjs}

@@ -8,15 +8,16 @@ import { n as readContext } from "./context-CYN__o3Q.mjs";
 import { a as deleteRemoteBranch, c as pruneMergedRemoteBranches, i as cleanupMergedBranches, n as checkBranchHealth, s as listRemoteCrBranches } from "./branch-lifecycle-D7tXOE4f.mjs";
 import { i as mergeBranch, n as createTransaction, r as ensureContentBranch, t as buildBranchName } from "./transaction-qliKvBRL.mjs";
 import { n as isMerged, t as LocalProvider } from "./local-BZEUWBoC.mjs";
-import { t as detectStack } from "./detect-eWS6lvoH.mjs";
-import { t as TOOL_ANNOTATIONS } from "./annotations-BFJbfSKe.mjs";
-import { n as listTemplates, t as getTemplate } from "./templates-VrLVqfe5.mjs";
-import { t as validateProject } from "./validator-Z3DGNWQ6.mjs";
-import { t as OverlayReader } from "./overlay-reader-CUs9jgqk.mjs";
-import { t as buildGraph } from "./graph-builder-DXv2JEp-.mjs";
-import { n as scanSummary, t as scanCandidates } from "./scanner-DKMwc03k.mjs";
-import { n as applyExtract, r as applyReuse } from "./apply-manager-BRmB27H5.mjs";
-import { t as runDoctor } from "./doctor-qiUKCy9b.mjs";
+import { n as isToolAvailable, t as TOOL_REQUIREMENTS } from "./availability-Bj9zOfEn.mjs";
+import { t as detectStack } from "./detect-wVSI9VuY.mjs";
+import { t as TOOL_ANNOTATIONS } from "./annotations-DSzewhL4.mjs";
+import { n as listTemplates, t as getTemplate } from "./templates-D6EllixQ.mjs";
+import { t as validateProject } from "./validator-8vaPxSba.mjs";
+import { t as OverlayReader } from "./overlay-reader-BOb105gS.mjs";
+import { t as buildGraph } from "./graph-builder-CRUX_8mA.mjs";
+import { n as scanSummary, t as scanCandidates } from "./scanner-VOwrKLGC.mjs";
+import { n as applyExtract, r as applyReuse } from "./apply-manager-BnPbPXFG.mjs";
+import { t as runDoctor } from "./doctor-BTToHt0y.mjs";
 import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CONTENTRAIN_BRANCH } from "@contentrain/types";
@@ -2368,15 +2369,39 @@ function registerDoctorTools(server, _provider, projectRoot) {
 }
 //#endregion
 //#region package.json
-var version = "1.8.0";
+var version = "1.9.0";
 //#endregion
 //#region src/server.ts
+/**
+* Default MCP `instructions` surfaced to clients at initialize time.
+* Deliberately kept under 512 characters — directory listings and client
+* UIs truncate longer strings. Override via `CreateServerOptions.instructions`.
+*/
+const DEFAULT_INSTRUCTIONS = "Contentrain is git-native content governance: models define structure; content is canonical JSON/Markdown on a dedicated branch. Call contentrain_describe_format before creating models or content. Preview writes with dry_run:true, review the plan, then re-run with dry_run:false. Start with contentrain_status for models, locales, and workflow; inspect a model with contentrain_describe before editing its entries. Tools are deterministic infrastructure — content decisions stay with the agent.";
+/**
+* `McpServer` variant that silently skips registration for tools named in
+* `skipTools`. Register functions call `server.tool(...)` unconditionally;
+* this subclass is what keeps capability-gated tools out of `tools/list`
+* when the provider (or missing projectRoot) could never satisfy them.
+*/
+var CapabilityFilteredMcpServer = class extends McpServer {
+	_skipTools;
+	constructor(serverInfo, options, skipTools) {
+		super(serverInfo, options);
+		this._skipTools = skipTools;
+	}
+	tool(...args) {
+		if (this._skipTools.has(args[0])) return;
+		return McpServer.prototype.tool.apply(this, args);
+	}
+};
 function createServer(input) {
-	const { provider, projectRoot } = resolveServerContext(input);
-	const server = new McpServer({
+	const { provider, projectRoot, instructions } = resolveServerContext(input);
+	const skipTools = new Set(Object.keys(TOOL_REQUIREMENTS).filter((name) => !isToolAvailable(name, provider, projectRoot)));
+	const server = new CapabilityFilteredMcpServer({
 		name: "contentrain-mcp",
 		version
-	});
+	}, { instructions: instructions || void 0 }, skipTools);
 	registerContextTools(server, provider, projectRoot);
 	registerSetupTools(server, provider, projectRoot);
 	registerModelTools(server, provider, projectRoot);
@@ -2390,23 +2415,27 @@ function createServer(input) {
 function resolveServerContext(input) {
 	if (typeof input === "string") return {
 		provider: new LocalProvider(input),
-		projectRoot: input
+		projectRoot: input,
+		instructions: DEFAULT_INSTRUCTIONS
 	};
+	const instructions = input.instructions ?? "Contentrain is git-native content governance: models define structure; content is canonical JSON/Markdown on a dedicated branch. Call contentrain_describe_format before creating models or content. Preview writes with dry_run:true, review the plan, then re-run with dry_run:false. Start with contentrain_status for models, locales, and workflow; inspect a model with contentrain_describe before editing its entries. Tools are deterministic infrastructure — content decisions stay with the agent.";
 	if (input.provider) {
 		let projectRoot = input.projectRoot;
 		if (!projectRoot && input.provider instanceof LocalProvider) projectRoot = input.provider.projectRoot;
 		return {
 			provider: input.provider,
-			projectRoot
+			projectRoot,
+			instructions
 		};
 	}
 	if (input.projectRoot) return {
 		provider: new LocalProvider(input.projectRoot),
-		projectRoot: input.projectRoot
+		projectRoot: input.projectRoot,
+		instructions
 	};
 	throw new Error("createServer: either `provider` or `projectRoot` must be provided");
 }
 //#endregion
-export { createServer as t };
+export { createServer as n, DEFAULT_INSTRUCTIONS as t };
 
-//# sourceMappingURL=server-tTuinKHD.mjs.map
+//# sourceMappingURL=server-B6_fzRmK.mjs.map