@vibesdotdev/mcp 1.0.0-rc.2 → 1.0.0-rc.5

package/dist/docs/server.docs.descriptor.js

@@ -2,13 +2,13 @@ const descriptor = {
     kind: 'docs/topic',
     id: 'mcp.server',
     title: 'MCP Server',
-    summary: 'Model Context Protocol server setup, transport, and lifecycle',
+    summary: 'Model Context Protocol server composition, transport, and lifecycle',
     body: {
         type: 'markdown',
         sourceType: 'raw',
         source: `---
 title: MCP Server
-summary: Model Context Protocol server setup and lifecycle management
+summary: Model Context Protocol server composition, transport, and lifecycle
 tags: [mcp, server, transport, lifecycle, protocol]
 parent: mcp
 order: 1
@@ -21,343 +21,114 @@ man:
   seeAlso: ["mcp.tools", "dev.mcp.start", "dev.mcp.serve"]
 ---
 
-The **Model Context Protocol (MCP)** server enables AI agents to discover and invoke tools, access resources, and use prompts from the runtime.
+The MCP server projects the runtime's \`tools/tool\` catalog over the Model
+Context Protocol. One adapter owns tool registration, session admission, error
+projection and trust framing; the surface owns only its transport and lifecycle.
 
-## Server architecture
+## Composition
 
-MCP server exposes runtime capabilities via standard protocol:
+Compose \`@vibesdotdev/mcp/plugin\` on every MCP host. It registers the protocol
+kinds, docs, configuration and the universal \`vibes-context\` orientation loader.
+Adapter-only hosts compose \`./client/plugin\`.
 
-\`\`\`
-┌─────────────────┐
-│   MCP Client    │  ←→  MCP Protocol (JSON-RPC)
-│  (Claude, etc.) │
-└─────────────────┘
-         ↓
-┌─────────────────┐
-│  MCP Server     │  ←→  Runtime (tools/resources/prompts)
-│  (@vibesdotdev/mcp)
-└─────────────────┘
-\`\`\`
-
-## Transport modes
+The consumer serve, the cloud Worker and the shared stdio host use the same
+composition. There is no consumer-specific MCP plugin and no root host-adapter
+compatibility factory.
 
-### Stdio transport (default)
+## Transports
 
-Communicate via standard streams:
+Stdio and HTTP use the tool-aware adapter:
 
 \`\`\`ts
 import { createMcpAdapter } from '@vibesdotdev/mcp/adapters/mcp';
 
-const adapter = createMcpAdapter(runtime, { mode: 'stdio', preset: 'full' }, logger);
+const adapter = createMcpAdapter(runtime, { mode: 'stdio' }, logger);
 await adapter.start();
-// On host shutdown:
 await adapter.shutdown();
 \`\`\`
 
-**Use when:** Local MCP clients (Claude Desktop, IDE plugins).
-
-### HTTP transport (Web Standard streamable HTTP)
-
-Bun-native HTTP server using Web Standard APIs (not SSE):
+A serverless or edge host uses the Web Standard handler:
 
 \`\`\`ts
-import { createBunMcpServer } from '@vibesdotdev/mcp/adapters';
-import { createMcpAuthenticator } from '@vibesdotdev/mcp';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { getRuntimeHttpListener } from '@vibesdotdev/kernel';
+import { createMcpWebStandardHandler } from '@vibesdotdev/mcp/adapters/mcp/web-handler';
 
-const server = createBunMcpServer({
-  listener: getRuntimeHttpListener(runtime),
-  port: 3001,
-  hostname: '0.0.0.0',
-  buildServer: () => new McpServer({ name: 'my-server', version: '1.0.0' }),
-  logger: myLogger,
-  lifecycle: runtime.lifecycle,
-  authenticate: createMcpAuthenticator({ remote: true, scope: 'mcp' })
+const handle = createMcpWebStandardHandler(runtime, {
+  mode: 'http',
+  serverName: 'vibes',
+  logger
 });
-
-await server.start();
 \`\`\`
 
-\`lifecycle\` is the serving runtime's: idle sessions expire per request on every
-host, and a persistent host also sweeps them on its runtime-owned interval (a
-finite host has no background sweep). Disposing the runtime clears it.
+The handler serves both protocol eras on one endpoint. A 2026-07-28 request
+carries its per-request \`_meta\` envelope and is served statelessly, with one
+fresh server instance and no session id. A 2025-era request keeps the legacy
+\`initialize\` handshake, \`Mcp-Session-Id\` continuity and its SSE streams.
+The same split applies to stdio: the SDK's \`serveStdio\` pins one factory
+instance per connection and serves either era.
 
-**Use when:** Remote MCP clients, cloud deployments, Workers (use \`createMcpFetchHandler\` instead of \`createBunMcpServer\` in a Workers environment).
+## Identity
 
-**Note:** This transport uses Web Standard streamable HTTP (MCP Streamable HTTP transport; the SDK negotiates protocol version, defaulting to 2025-03-26 and supporting up to 2025-11-25). There are no \`/mcp/sse\` or \`/mcp/message\` endpoints — the server handles all MCP traffic through a single fetch handler.
+\`serverName\` is host-owned. The Vibes hosts pass \`vibes\`; the framework
+default is neutral. \`serverVersion\` defaults to this package's version. The
+\`vibes://diagnostics/projection-birth\` resource carries the build provenance
+and catalog digest.
 
-## Server lifecycle
+## Tool catalog
 
-### Starting MCP server
+The adapter folds \`tools/tool\` once per catalog revision, applies the selected
+preset and registers the selected descriptors. A settled fold excludes tools
+whose loader is unavailable; a required tool without a loader refuses to serve.
+The catalog is not mutated per connection.
 
-\`\`\`bash
-vibes dev mcp start
-\`\`\`
+The long tail is discoverable through \`tool-search\`, readable through
+\`tool-help\` and callable through \`tool-call\`. The bridge refuses nested write
+actions; the target tool's own host approval path owns those.
 
-Starts MCP server in background with stdio transport.
+## Sessions and approval
 
-### Serving HTTP endpoint
+Session owns durable participants and authority. The \`session\` tool mints and
+binds explicit handles; the transport does not invent a role or a capability
+ceiling. A harness is a transport, not a role.
 
-\`\`\`bash
-vibes dev mcp serve --port 3001
-\`\`\`
+\`requiresApproval: true\` is enforced through the SDK's multi-round-trip
+input seam. A 2026-07-28 client receives \`input_required\` with a form
+elicitation; a 2025-era client receives the same flow through the real
+\`elicitation/create\` legacy shim. The approval is bound to a signed
+\`requestState\`, so a caller cannot pre-supply an acceptance without the
+prompt. A client without elicitation is refused
+\`UNAVAILABLE / tool-approval-unavailable\`; a decline is
+\`PERMISSION_DENIED / tool-approval-declined\`.
 
-Starts HTTP server using Web Standard streamable HTTP transport (not SSE).
+## Configuration
 
-### Stopping server
-
-\`\`\`bash
-vibes dev mcp stop
-\`\`\`
-
-Gracefully shuts down server.
-
-### Restarting server
-
-\`\`\`bash
-vibes dev mcp restart
-\`\`\`
-
-Stops and restarts server (picks up config changes).
-
-## Server configuration
-
-### MCP adapter options
-
-\`\`\`ts
-import type { McpAdapterOptions } from '@vibesdotdev/mcp';
-import { createMcpAdapter } from '@vibesdotdev/mcp/adapters/mcp';
-import { createMcpAuthenticator } from '@vibesdotdev/mcp';
-
-// \`runtime\` is the VibesRuntime handed to your host entry. The token is a credential.
-const token = await runtime.resolveCredential({ source: 'secret', key: 'MCP_TOKEN' });
-if (!token.ok) throw token.error;
-
-const options: McpAdapterOptions = {
-  mode: 'http',                         // 'stdio' | 'http'
-  mcpClientId: 'claude-desktop',        // Client identifier (optional)
-  logLevel: 'info',                     // LogLevel (optional)
-  toolExecutionTimeoutMs: 30_000,       // Per-tool timeout (optional)
-  port: 3001,                           // http mode only
-  authenticate: createMcpAuthenticator({
-    apiKeys: [token.value],
-    scope: 'mcp'
-  })                                    // optional; omit for unauthenticated
-};
-
-const server = createMcpAdapter(runtime, options, logger);
-\`\`\`
-
-### Capability negotiation
-
-Server advertises capabilities during handshake:
-
-\`\`\`ts
-capabilities: {
-  tools: { listChanged: true },      // Tool discovery
-  resources: { listChanged: true },  // Resource access
-  prompts: { listChanged: true }     // Prompt templates
-}
-\`\`\`
-
-Clients can request specific capabilities.
-
-## Tool registration
-
-Tools are auto-discovered from runtime:
-
-\`\`\`ts
-const descriptors = runtime.query('tools/tool').descriptors();
-for (const descriptor of descriptors) {
-  server.registerTool(
-    descriptor.id,
-    {
-      title: descriptor.name,
-      description: descriptor.description,
-      inputSchema: descriptor.schemas.input,
-      outputSchema: descriptor.schemas.output
-    },
-    async (args) => {
-      return invokeTool({ runtime, toolId: descriptor.id, input: args });
-    }
-  );
-}
-\`\`\`
-
-## Resource registration
-
-Resources provide read-only data access:
-
-\`\`\`ts
-server.registerResource(
-  'workspace-files',
-  'file://workspace/**',
-  {
-    description: 'Workspace file contents',
-    mimeType: 'text/plain'
-  },
-  async (uri) => {
-    const content = await fs.read(uri.pathname);
-    return {
-      contents: [{
-        uri: uri.href,
-        mimeType: 'text/plain',
-        text: content
-      }]
-    };
-  }
-);
-\`\`\`
-
-## Prompt registration
-
-Prompts provide templated messages:
-
-\`\`\`ts
-server.registerPrompt(
-  'code-review',
-  {
-    description: 'Review code for best practices',
-    argsSchema: {
-      filePath: z.string().describe('File to review')
-    }
-  },
-  async (args) => {
-    const code = await fs.read(args.filePath);
-    return {
-      messages: [{
-        role: 'user',
-        content: {
-          type: 'text',
-          text: \`Review this code:\\n\\n\${code}\`
-        }
-      }]
-    };
-  }
-);
-\`\`\`
+The \`mcp\` config manifest drives the host defaults. \`approvalStateSecret\`
+names the runtime credential that keys approval \`requestState\` (default
+\`MCP_APPROVAL_STATE_KEY\`); when no secret is configured, approval uses a
+per-process key and fails closed across process boundaries. \`sampling:
+'transport' | 'off'\` controls legacy transport sampling; a 2026-07-28
+connection always refuses the removed server-to-client sampling channel.
 
 ## Authentication
 
-### Bearer token auth (local allowlist)
-
-Pass allowed API keys directly. The returned function is passed as \`authenticate\` to the transport or adapter options.
-
-\`\`\`ts
-import { createMcpAuthenticator } from '@vibesdotdev/mcp';
-
-const token = await runtime.resolveCredential({ source: 'secret', key: 'MCP_TOKEN' });
-if (!token.ok) throw token.error;
-
-const authenticate = createMcpAuthenticator({
-  apiKeys: [token.value],
-  scope: 'mcp'
-});
-
-// Pass to createBunMcpServer:
-const server = createBunMcpServer({ ..., authenticate });
-
-// Or pass to createMcpAdapter:
-const adapter = createMcpAdapter(runtime, { ..., authenticate }, logger);
-\`\`\`
-
-### Remote validation (cloud mode)
-
-For cloud deployments, configure the host-owned authentication API endpoint:
-
-\`\`\`ts
-const authenticate = createMcpAuthenticator({
-  remote: true,
-  scope: 'mcp',
-  authApiBaseUrl: 'https://auth.example.test' // supplied by host composition
-});
-\`\`\`
+\`createMcpAuthenticator\` validates an API key or OAuth token against the
+host-supplied validator. The cloud edge authenticates before routing to a
+session or Durable Object. Local stdio is the user's own process.
 
 ## Logging
 
-MCP server emits structured logs on the logger of the runtime it was handed (never a module-level logger, which has no runtime):
-
-\`\`\`ts
-import { getLogger } from '@vibesdotdev/logging';
-
-const logger = getLogger('mcp', runtime);
-logger.info('MCP server started', {
-  transport: 'stdio',
-  capabilities: ['tools', 'resources']
-});
-\`\`\`
-
-**Log levels:**
-- \`debug\` — Protocol messages
-- \`info\` — Lifecycle events
-- \`warn\` — Non-critical errors
-- \`error\` — Critical failures
-
-## WRONG: Manual protocol handling
-
-\`\`\`ts
-// ❌ NEVER — use createMcpAdapter instead
-const server = new McpServer({ name: 'custom', version: '1.0' });
-// Manual tool registration...
-\`\`\`
-
-## RIGHT: Runtime-integrated server
-
-\`\`\`ts
-// ✅ Auto-discovers tools/resources/prompts
-const server = createMcpAdapter(runtime, options, logger);
-\`\`\`
-
-## MCP client configuration
-
-### Claude Desktop
-
-\`\`\`json
-{
-  "mcpServers": {
-    "vibes": {
-      "command": "vibes",
-      "args": ["dev", "mcp", "start"]
-    }
-  }
-}
-\`\`\`
+Every logger is the runtime's (\`getLogger(id, runtime)\`), never a module-level
+default. One INFO line records a catalog fold; per-call stages are DEBUG. A
+session start, a registration failure and a degraded surface are the events
+that deserve INFO/WARN/ERROR.
 
-### Cursor IDE (and any stdio-capable client)
+## Verify
 
-\`\`\`json
-{
-  "mcpServers": {
-    "vibes": {
-      "type": "stdio",
-      "command": "vibes",
-      "args": ["dev", "mcp", "serve", "--mode", "stdio", "--client", "claude"]
-    }
-  }
-}
+\`\`\`bash
+vibes dev audit tools            # policy reachability + schema/annotation findings
+vibes dev audit tools --live     # real serve; served vs authored wire
+vibes dev audit tools --doctor   # birth digest, canary, host attestation
 \`\`\`
 
-The stdio relay attaches to the shared runtime host, so there is no fixed URL
-to configure. The HTTP transport's port is derived per workspace (there is no
-fixed \`3001\`) — run \`vibes dev mcp status\` to see the port the current
-workspace is serving on before pointing an HTTP client at it. \`--client\` is
-the legacy catalog/harness selector; \`vibes dev mcp serve --help\` lists the
-newer \`--preset\` / \`--harness\` / \`--agent\` knobs.
-
-## Monitoring
-
-Adapters expose start() and shutdown(). They do not expose an event emitter.
-Pass the runtime logger to observe protocol and listener failures. For tool-call
-instrumentation, supply prepareToolCallContext on the tool-aware adapter; it
-receives the canonical tool id, validated input and prepared context before
-invocation. Return the context to preserve the serving authority.
-
-Use the projection doctor and live tool audit to compare the observed wire
-catalog with authored descriptors. They report measured bytes, schema loss and
-description drift; policy audit findings and high-severity wire findings retain
-their distinct verdicts.
-
 :::card{title="See also"}
 - [\`mcp.tools\`](mcp.tools) — MCP tool exposure
 - [\`mcp.resources\`](mcp.resources) — MCP resources

package/dist/docs/server.docs.descriptor.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/server.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACtC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,YAAY;IAChB,KAAK,EAAE,YAAY;IACnB,OAAO,EAAE,+DAA+D;IACxE,IAAI,EAAE;QACJ,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsWX;KACE;IACD,MAAM,EAAE,KAAK;IACb,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,CAAC;IAC7D,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,GAAG,EAAE;QACH,IAAI,EAAE,6CAA6C;QACnD,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,sBAAsB;QAChC,OAAO,EAAE,CAAC,WAAW,EAAE,eAAe,EAAE,eAAe,CAAC;KACzD;IACD,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"server.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/server.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACtC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,YAAY;IAChB,KAAK,EAAE,YAAY;IACnB,OAAO,EAAE,qEAAqE;IAC9E,IAAI,EAAE;QACJ,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiIX;KACE;IACD,MAAM,EAAE,KAAK;IACb,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,CAAC;IAC7D,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,GAAG,EAAE;QACH,IAAI,EAAE,6CAA6C;QACnD,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,sBAAsB;QAChC,OAAO,EAAE,CAAC,WAAW,EAAE,eAAe,EAAE,eAAe,CAAC;KACzD;IACD,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/tools.docs.descriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/tools.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBAyTjB,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"tools.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/tools.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBA0IjB,CAAC;AAEF,eAAe,UAAU,CAAC"}