@vibesdotdev/mcp 0.0.0-stage → 1.0.0-rc.0

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

@@ -0,0 +1,390 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'mcp.resources',
+    title: 'MCP Resources',
+    summary: 'Resource exposure, templates, and URI-based access patterns',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: MCP Resources
+summary: Expose read-only data via MCP resource protocol
+tags: [mcp, resources, templates, uris, access]
+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.
+
+## Resource types
+
+### 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
+
+\`\`\`
+vfs://projects/my-app/src/main.ts
+vfs://knowledge/base/articles
+\`\`\`
+
+**data://** — Inline data
+
+\`\`\`
+data://config/runtime.json
+data://secrets/requirements
+\`\`\`
+
+### URI resolution
+
+URIs resolved by resource handlers:
+
+\`\`\`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
+
+Resources include metadata for clients:
+
+\`\`\`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
+    }
+  }
+}
+\`\`\`
+
+## Resource listing
+
+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
+
+\`\`\`ts
+mcp: {
+  resourceTemplates: [{
+    uriTemplate: 'file://workspace/{path}',
+    name: 'workspace-files'
+  }]
+}
+\`\`\`
+
+## 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 }
+    }]
+  };
+}
+\`\`\`
+
+Clients can use If-None-Match for conditional requests.
+
+## WRONG: Manual resource registration
+
+\`\`\`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');
+}
+\`\`\`
+
+## Resource debugging
+
+List registered resources:
+
+\`\`\`bash
+vibes dev mcp status --resources
+\`\`\`
+
+Shows:
+- Registered resource URIs
+- Template patterns
+- Subscription counts
+- Cache hit rates
+
+:::card{title="See also"}
+- [\`mcp.server\`](mcp.server) — MCP server setup
+- [\`mcp.tools\`](mcp.tools) — MCP tools
+- [\`filesystem.operations\`](filesystem.operations) — File operations
+:::
+`
+    },
+    parent: 'mcp',
+    order: 3,
+    tags: ['mcp', 'resources', 'templates', 'uris', 'access'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=resources.docs.descriptor.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=server.docs.descriptor.d.ts.map

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

@@ -0,0 +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"}