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

package/dist/docs/resources.docs.descriptor.js

@@ -2,386 +2,97 @@ const descriptor = {
     kind: 'docs/topic',
     id: 'mcp.resources',
     title: 'MCP Resources',
-    summary: 'Resource exposure, templates, and URI-based access patterns',
+    summary: 'Read-only URI-addressed resources and the projection birth snapshot',
     body: {
         type: 'markdown',
         sourceType: 'raw',
         source: `---
 title: MCP Resources
-summary: Expose read-only data via MCP resource protocol
-tags: [mcp, resources, templates, uris, access]
+summary: Read-only URI-addressed resources and the projection birth snapshot
+tags: [mcp, resources, uris, projection-birth]
 parent: mcp
 order: 3
 surfaces: [cli, web, in-app]
 hardware: [consumer, cloud]
 ---
 
-MCP **resources** provide read-only access to data via URI schemes. Resources are auto-discovered from tool descriptors that declare MCP resource metadata.
+MCP **resources** are read-only, URI-addressed data. They are not tools and they
+are not a second copy of the tool catalog.
 
-## Resource types
+## The projection birth resource
 
-### Static resources
-
-Fixed URI with static content:
-
-\`\`\`ts
-server.registerResource(
-  'workspace-files',
-  'file://workspace/README.md',
-  {
-    description: 'Workspace README file',
-    mimeType: 'text/markdown'
-  },
-  async (uri) => {
-    const content = await fs.read(uri.pathname);
-    return {
-      contents: [{
-        uri: uri.href,
-        mimeType: 'text/markdown',
-        text: content
-      }]
-    };
-  }
-);
-\`\`\`
-
-### Resource templates
-
-URI templates with variables:
-
-\`\`\`ts
-import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
-
-server.registerResource(
-  'file-content',
-  new ResourceTemplate('file://workspace/{path}', {
-    list: async (uri) => {
-      // List all matching files
-      const files = await fs.list('workspace/', { recursive: true });
-      return {
-        resources: files.map(f => ({
-          uri: \`file://workspace/\${f.path}\`,
-          name: f.name,
-          mimeType: getMimeType(f.name)
-        }))
-      };
-    }
-  }),
-  {
-    description: 'Workspace file contents',
-    mimeType: 'text/plain'
-  },
-  async (uri, variables) => {
-    const content = await fs.read(variables.path);
-    return {
-      contents: [{
-        uri: uri.href,
-        mimeType: getMimeType(variables.path),
-        text: content
-      }]
-    };
-  }
-);
-\`\`\`
-
-**Template syntax:**
-- \`{variable}\` — Path segment variable
-- \`{variable*}\` — Multi-segment wildcard
-- List function enumerates matching resources
-
-## Descriptor-based resources
-
-Tools can declare MCP resources in their descriptor:
-
-\`\`\`ts
-export const fsReadDescriptor = {
-  kind: 'tools/tool',
-  id: 'workspace-fs',
-  mcp: {
-    resource: {
-      uri: 'file://workspace/{path}',
-      name: 'workspace-file',
-      description: 'Read workspace file contents',
-      mimeType: 'text/plain',
-      cacheable: true,
-      subscriptions: ['file:changed']
-    }
-  }
-} as const;
-\`\`\`
-
-MCP server auto-registers these:
-
-\`\`\`ts
-// Auto-registration in buildServer()
-for (const descriptor of descriptors) {
-  if (descriptor.mcp?.resource) {
-    server.registerResource(
-      descriptor.mcp.resource.name,
-      descriptor.mcp.resource.uri,
-      {
-        description: descriptor.mcp.resource.description,
-        mimeType: descriptor.mcp.resource.mimeType,
-        _meta: {
-          vibes: {
-            toolId: descriptor.id,
-            cacheable: descriptor.mcp.resource.cacheable,
-            subscriptions: descriptor.mcp.resource.subscriptions
-          }
-        }
-      },
-      async (uri) => {
-        // Returns descriptor metadata (not live data)
-        return {
-          contents: [{
-            uri: uri.href,
-            mimeType: 'application/json',
-            text: buildResourceText(descriptor, uri.href)
-          }]
-        };
-      }
-    );
-  }
-}
-\`\`\`
-
-## Resource URIs
-
-### URI schemes
-
-**file://** — Local filesystem
-
-\`\`\`
-file://workspace/src/index.ts
-file://workspace/docs/api.md
-\`\`\`
-
-**vfs://** — Virtual filesystem
+Every serving surface exposes one immutable startup snapshot:
 
 \`\`\`
-vfs://projects/my-app/src/main.ts
-vfs://knowledge/base/articles
+vibes://diagnostics/projection-birth
 \`\`\`
 
-**data://** — Inline data
-
-\`\`\`
-data://config/runtime.json
-data://secrets/requirements
-\`\`\`
-
-### URI resolution
-
-URIs resolved by resource handlers:
+It carries the build provenance, catalog hash, selected tool ids and registered
+tool ids for the body that is actually serving. Its contents are bound by digest
+at startup; it is the diagnostic source of truth when an agent and an operator
+disagree about what was served.
 
-\`\`\`ts
-server.registerResource(
-  'config',
-  'data://config/{domain}.{format}',
-  { description: 'Configuration data' },
-  async (uri, variables) => {
-    const config = await runtime.query('config/domain')
-      .withId(variables.domain)
-      .resolve();
-    
-    return {
-      contents: [{
-        uri: uri.href,
-        mimeType: \`application/\${variables.format}\`,
-        text: JSON.stringify(config, null, 2)
-      }]
-    };
-  }
-);
-\`\`\`
-
-## Resource metadata
+## Descriptor metadata is not a live resource
 
-Resources include metadata for clients:
+A tool descriptor may declare \`mcp.resource\` metadata. The MCP adapter projects
+that as a **descriptor-metadata** payload, and the payload says so explicitly.
+It does not read the underlying file, row or remote object.
 
-\`\`\`ts
-{
-  uri: 'file://workspace/src/index.ts',
-  name: 'workspace-file',
-  description: 'Workspace file content',
-  mimeType: 'text/typescript',
-  _meta: {
-    vibes: {
-      toolId: 'workspace-fs',
-      cacheable: true,      // Client can cache response
-      subscriptions: ['file:changed']  // Subscribe to updates
-    }
-  }
-}
-\`\`\`
+Use \`mcp.resource\` only when descriptor metadata is the intended resource. If a
+capability has live data, its owning package implements a real resource handler
+and registers it through the MCP adapter; do not advertise a live URI that only
+returns descriptor metadata.
 
-## Resource listing
+## Templates
 
-Clients can list available resources:
-
-\`\`\`ts
-// MCP protocol: resources/list
-const resources = await mcpClient.listResources();
-
-// Returns
-[
-  {
-    uri: 'file://workspace/README.md',
-    name: 'workspace-file',
-    description: 'README file',
-    mimeType: 'text/markdown'
-  },
-  // ... more resources
-]
-\`\`\`
-
-## Resource subscriptions
-
-Clients can subscribe to resource updates:
-
-\`\`\`ts
-// MCP protocol: resources/subscribe
-await mcpClient.subscribe('file://workspace/src/index.ts');
-
-// Server sends notification when resource changes
-mcpClient.on('resources/updated', (event) => {
-  console.log('Resource updated:', event.uri);
-});
-\`\`\`
-
-Subscriptions tied to runtime events:
-
-\`\`\`ts
-runtime.on('fs-operation/write', (event) => {
-  // Notify subscribed clients
-  mcpServer.notify('resources/updated', {
-    uri: \`file://\${event.path}\`
-  });
-});
-\`\`\`
-
-## Resource templates vs resources
-
-**Resources:** Fixed URI, single resource
-
-\`\`\`ts
-mcp: {
-  resource: {
-    uri: 'file://workspace/README.md',
-    name: 'readme'
-  }
-}
-\`\`\`
-
-**Templates:** URI pattern, multiple matches
+URI templates are supported for descriptor metadata:
 
 \`\`\`ts
 mcp: {
   resourceTemplates: [{
-    uriTemplate: 'file://workspace/{path}',
-    name: 'workspace-files'
+    uriTemplate: 'example://items/{id}',
+    name: 'Item metadata',
+    mimeType: 'application/json'
   }]
 }
 \`\`\`
 
-## Resource caching
-
-Cacheable resources include ETag:
-
-\`\`\`ts
-async (uri) => {
-  const stat = await fs.stat(uri.pathname);
-  const etag = \`\${stat.mtimeMs}-\${stat.size}\`;
-  
-  return {
-    contents: [{
-      uri: uri.href,
-      mimeType: 'text/plain',
-      text: content,
-      _meta: { etag }
-    }]
-  };
-}
-\`\`\`
+The template handler receives the URI and variables. It must return the same
+descriptor-metadata contract as a static descriptor resource.
 
-Clients can use If-None-Match for conditional requests.
+## List changes and subscriptions
 
-## WRONG: Manual resource registration
+The server advertises \`resources.listChanged\` only when the resource list can
+actually change. The projection birth resource is immutable, so the default
+surface does not need a resource subscription stream. A live resource owner
+that changes must provide the change notification through its owning transport.
 
-\`\`\`ts
-// ❌ NEVER — bypasses descriptor auto-discovery
-server.registerResource('manual', 'data://manual', {...}, handler);
-\`\`\`
-
-## RIGHT: Descriptor-based
-
-\`\`\`ts
-// ✅ Declare in tool descriptor, auto-registered
-export const descriptor = {
-  mcp: {
-    resource: { uri: '...', name: '...' }
-  }
-};
-\`\`\`
-
-## Resource security
-
-### URI containment
-
-Validate URIs are within allowed paths:
-
-\`\`\`ts
-async (uri) => {
-  const allowed = await checkWorkspaceContainment({
-    path: uri.pathname,
-    operation: 'read'
-  });
-  
-  if (!allowed) {
-    throw new McpResourceError('URI outside workspace');
-  }
-  
-  return readResource(uri);
-}
-\`\`\`
-
-### MIME type validation
-
-Sanitize MIME types:
-
-\`\`\`ts
-const allowedMimes = ['text/plain', 'application/json', 'text/markdown'];
-const mimeType = getMimeType(path);
-
-if (!allowedMimes.includes(mimeType)) {
-  throw new McpResourceError('Unsupported MIME type');
-}
-\`\`\`
+## Security
 
-## Resource debugging
+- Resolve every URI through the owning capability; never concatenate a caller
+  path onto a filesystem root.
+- Return a MIME type and reject an unreadable or out-of-scope URI with a typed
+  refusal.
+- Do not put credentials, tokens or raw provider errors in resource contents.
 
-List registered resources:
+## Verify
 
 \`\`\`bash
-vibes dev mcp status --resources
+vibes dev audit tools --doctor   # birth digest + canary
 \`\`\`
 
-Shows:
-- Registered resource URIs
-- Template patterns
-- Subscription counts
-- Cache hit rates
+Read the birth resource and compare its catalog hash with the live \`tools/list\`.
 
 :::card{title="See also"}
 - [\`mcp.server\`](mcp.server) — MCP server setup
 - [\`mcp.tools\`](mcp.tools) — MCP tools
-- [\`filesystem.operations\`](filesystem.operations) — File operations
+- [\`mcp.prompts\`](mcp.prompts) — MCP prompts
 :::
 `
     },
     parent: 'mcp',
     order: 3,
-    tags: ['mcp', 'resources', 'templates', 'uris', 'access'],
+    tags: ['mcp', 'resources', 'uris', 'projection-birth'],
     surfaces: ['cli', 'web', 'in-app'],
     hardware: ['consumer', 'cloud'],
     enabled: true

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

@@ -1 +1 @@
-{"version":3,"file":"resources.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/resources.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACtC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,eAAe;IACnB,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,6DAA6D;IACtE,IAAI,EAAE;QACJ,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmXX;KACE;IACD,MAAM,EAAE,KAAK;IACb,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC;IACzD,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"resources.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/resources.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACtC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,eAAe;IACnB,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,qEAAqE;IAC9E,IAAI,EAAE;QACJ,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkFX;KACE;IACD,MAAM,EAAE,KAAK;IACb,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,kBAAkB,CAAC;IACtD,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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