feat(mcp): resource support — list on connect + @server:uri expansion (#115)

Implements MCP resources (DEVELOPMENT_PLAN §3.3 / BEHAVIOR_PARITY): an MCP
server's resources can now be referenced from a prompt and their content is
injected for the model.

core (mcp/client.ts):
- connectMcpServer now lists resources on connect (capability-gated; a server
  without `resources` — or one that errors on resources/list — yields []).
  McpClientHandle gains `resources: McpResourceMeta[]`.
- readMcpResource(handle, uri) — reads a resource, flattens contents to text
  (binary blobs → `[binary …]` placeholder).
- parseResourceRefs(text) — finds `@server:scheme://path` tokens (requires
  `://`, so it won't match emails or `@user:pass`; dedupes).
- expandMcpResourceRefs(text, handles) — reads each referenced resource and
  appends a `<mcp-resource server=… uri=…>` block, leaving the original token
  in place; unknown server / read failure surface as errors, never throw.

cli:
- repl.ts + headless.ts expand `@server:uri` refs in the user message after
  MCP connect (resolved/error lines to the user).

Tests: +5 (connect→list→read→expand end-to-end against a real spawned stdio
server with a `resources` capability; parseResourceRefs pure cases incl.
email/`@user:pass` rejection + dedup). Core suite 569 green.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: oratis

apps/cli/src/headless.ts

@@ -29,6 +29,7 @@ import {
   buildSkillsDescriptionBlock,
   closeAllMcpServers,
   connectAllMcpServers,
+  expandMcpResourceRefs,
   contextWindowFor,
   findStyle,
   loadMemory,
@@ -152,6 +153,16 @@ export async function runHeadless(opts: HeadlessOpts): Promise<number> {
     for (const handle of mcpServers) for (const t of handle.tools) tools.register(t);
   }
 
+  // Expand `@server:scheme://path` MCP resource references in the prompt.
+  let userMessage = prompt;
+  if (mcpServers.length > 0) {
+    const { text, errors } = await expandMcpResourceRefs(prompt, mcpServers);
+    userMessage = text;
+    for (const e of errors) {
+      errOutput.write(`MCP resource @${e.ref.server}:${e.ref.uri} — ${e.error}\n`);
+    }
+  }
+
   // ─── system prompt assembly ─────────────────────────────────────────
   let systemPrompt = opts.systemPromptOverride ?? DEFAULT_SYSTEM_PROMPT;
   if (memory.text) systemPrompt += '\n\n' + memory.text;
@@ -229,7 +240,7 @@ export async function runHeadless(opts: HeadlessOpts): Promise<number> {
       provider,
       tools,
       systemPrompt,
-      userMessage: prompt,
+      userMessage,
       history: [],
       model,
       maxTokens,

apps/cli/src/repl.ts

@@ -17,6 +17,7 @@ import {
   buildSkillsDescriptionBlock,
   closeAllMcpServers,
   connectAllMcpServers,
+  expandMcpResourceRefs,
   expandCommandBody,
   findCustomCommand,
   findStyle,
@@ -330,6 +331,17 @@ export async function startRepl(opts: ReplOpts): Promise<number> {
       }
     }
 
+    // Expand `@server:scheme://path` MCP resource references — read each resource
+    // and append its content as a tagged block the model can use.
+    if (mcpServers.length > 0) {
+      const { text, resolved, errors } = await expandMcpResourceRefs(userInput, mcpServers);
+      userInput = text;
+      for (const r of resolved) output.write(`  ⊞ resource @${r.server}:${r.uri}\n`);
+      for (const e of errors) {
+        output.write(`  ⚠ resource @${e.ref.server}:${e.ref.uri} — ${e.error}\n`);
+      }
+    }
+
     // Otherwise: send to agent (with mode/permission/hooks gating from M3b)
     const result = await runAgent({
       provider,

packages/core/src/index.ts

@@ -192,11 +192,17 @@ export {
   serveMcpOverStdio,
   mcpServableTools,
   MCP_SERVE_EXCLUDE,
+  readMcpResource,
+  parseResourceRefs,
+  expandMcpResourceRefs,
   type McpClientHandle,
   type McpToolMeta,
+  type McpResourceMeta,
   type ConnectAllResult,
   type BuildMcpServerOpts,
   type ServeMcpStdioOpts,
+  type ResourceRef,
+  type ExpandResourcesResult,
 } from './mcp/index.js';
 
 // Plugins (M5 — manifest + hash pin; M5.1 — subprocess runtime + RPC bridge;

packages/core/src/mcp/client.test.ts

@@ -13,8 +13,11 @@ import { join } from 'node:path';
 import {
   connectAllMcpServers,
   connectMcpServer,
+  expandMcpResourceRefs,
   parseHelperOutput,
+  parseResourceRefs,
   pickTransportKind,
+  readMcpResource,
 } from './client.js';
 
 const require_ = createRequire(import.meta.url);
@@ -32,8 +35,28 @@ const TYPES_INDEX = join(SDK_PKG_PATH, 'dist/esm/types.js');
  * We import the SDK by absolute path so the spawned script doesn't have to
  * resolve `@modelcontextprotocol/sdk` from /tmp (which lacks node_modules).
  */
-async function writeFakeServer(dir: string, name: string, tools: object[]): Promise<string> {
+async function writeFakeServer(
+  dir: string,
+  name: string,
+  tools: object[],
+  resources?: Array<{ uri: string; name?: string; text: string; mimeType?: string }>,
+): Promise<string> {
   const serverPath = join(dir, `${name}.mjs`);
+  const caps = resources ? '{ tools: {}, resources: {} }' : '{ tools: {} }';
+  const resourceBlock = resources
+    ? `
+import { ListResourcesRequestSchema, ReadResourceRequestSchema } from '${TYPES_INDEX}';
+const RESOURCES = ${JSON.stringify(resources)};
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: RESOURCES.map((r) => ({ uri: r.uri, name: r.name, mimeType: r.mimeType })),
+}));
+server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+  const found = RESOURCES.find((r) => r.uri === req.params.uri);
+  if (!found) throw new Error('no such resource: ' + req.params.uri);
+  return { contents: [{ uri: found.uri, mimeType: found.mimeType ?? 'text/plain', text: found.text }] };
+});
+`
+    : '';
   await fs.writeFile(
     serverPath,
     `
@@ -43,7 +66,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '${TYPES_INDEX}';
 
 const server = new Server(
   { name: '${name}', version: '0.0.1' },
-  { capabilities: { tools: {} } },
+  { capabilities: ${caps} },
 );
 
 const TOOLS = ${JSON.stringify(tools)};
@@ -55,7 +78,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     content: [{ type: 'text', text: 'called: ' + req.params.name + ' args: ' + argsStr }],
   };
 });
-
+${resourceBlock}
 await server.connect(new StdioServerTransport());
 `,
     'utf8',
@@ -192,6 +215,47 @@ describe('MCP client', () => {
   it('rejects a server config with neither command nor url', async () => {
     await expect(connectMcpServer('bad', {})).rejects.toThrow(/command.*url|url.*command/);
   });
+
+  it('lists resources on connect, reads them, and expands @server:uri refs', async () => {
+    const serverScript = await writeFakeServer(
+      tmp,
+      'docs',
+      [{ name: 'noop', description: 'd', inputSchema: { type: 'object', properties: {} } }],
+      [
+        { uri: 'file:///readme.md', name: 'readme', text: '# Hello\nbody text' },
+        { uri: 'mem://note', name: 'note', text: 'a short note' },
+      ],
+    );
+    const handle = await connectMcpServer('docs', { command: 'node', args: [serverScript] });
+    try {
+      // resources/list populated the handle
+      expect(handle.resources.map((r) => r.uri).sort()).toEqual([
+        'file:///readme.md',
+        'mem://note',
+      ]);
+
+      // readMcpResource flattens contents to text
+      expect(await readMcpResource(handle, 'file:///readme.md')).toContain('# Hello');
+
+      // expandMcpResourceRefs appends a tagged block, keeps the original token
+      const { text, resolved, errors } = await expandMcpResourceRefs(
+        'please summarize @docs:file:///readme.md now',
+        [handle],
+      );
+      expect(resolved).toHaveLength(1);
+      expect(errors).toHaveLength(0);
+      expect(text).toContain('@docs:file:///readme.md'); // original kept
+      expect(text).toContain('<mcp-resource server="docs" uri="file:///readme.md">');
+      expect(text).toContain('body text');
+
+      // unknown server + bad uri surface as errors, not throws
+      const r2 = await expandMcpResourceRefs('@nope:file:///x and @docs:mem://missing', [handle]);
+      expect(r2.errors).toHaveLength(2);
+      expect(r2.resolved).toHaveLength(0);
+    } finally {
+      await handle.close();
+    }
+  }, 20_000);
 });
 
 describe('pickTransportKind', () => {
@@ -226,6 +290,31 @@ describe('parseHelperOutput', () => {
   });
 });
 
+describe('parseResourceRefs', () => {
+  it('finds @server:scheme://path references', () => {
+    const refs = parseResourceRefs(
+      'look at @files:file:///etc/hosts and @db:postgres://h/t please',
+    );
+    expect(refs).toEqual([
+      { raw: '@files:file:///etc/hosts', server: 'files', uri: 'file:///etc/hosts' },
+      { raw: '@db:postgres://h/t', server: 'db', uri: 'postgres://h/t' },
+    ]);
+  });
+
+  it('ignores @user:pass and emails (no scheme://)', () => {
+    expect(parseResourceRefs('email me@host.com or @user:secret')).toEqual([]);
+  });
+
+  it('dedupes repeated references', () => {
+    const refs = parseResourceRefs('@a:x://1 then again @a:x://1');
+    expect(refs).toHaveLength(1);
+  });
+
+  it('returns [] when there are no references', () => {
+    expect(parseResourceRefs('just plain text')).toEqual([]);
+  });
+});
+
 // Silence unused-import warning — Server/Transport are used via the spawned script
 void Server;
 void StdioServerTransport;

packages/core/src/mcp/client.ts

@@ -28,13 +28,23 @@ export interface McpToolMeta {
 
 export type McpTransportKind = 'stdio' | 'http' | 'sse';
 
+/** A resource a server exposes (from resources/list). */
+export interface McpResourceMeta {
+  uri: string;
+  name?: string;
+  description?: string;
+  mimeType?: string;
+}
+
 export interface McpClientHandle {
   serverName: string;
   client: Client;
   transport: Transport;
   /** Which transport this connection uses. */
   transportKind: McpTransportKind;
   tools: ToolHandler[];
+  /** Resources the server advertised (empty if it has no `resources` capability). */
+  resources: McpResourceMeta[];
   close(): Promise<void>;
 }
 
@@ -176,18 +186,122 @@ export async function connectMcpServer(
     };
   });
 
+  // Resources (best-effort, capability-gated). A server without the `resources`
+  // capability — or one that errors on resources/list — just yields [].
+  let resources: McpResourceMeta[] = [];
+  if (client.getServerCapabilities()?.resources) {
+    try {
+      const r = await client.listResources();
+      resources = (r.resources ?? []).map((res) => ({
+        uri: res.uri,
+        name: res.name,
+        description: res.description,
+        mimeType: res.mimeType,
+      }));
+    } catch {
+      /* server advertised resources but list failed — degrade to none */
+    }
+  }
+
   return {
     serverName,
     client,
     transport,
     transportKind: kind,
     tools,
+    resources,
     async close() {
       await client.close();
     },
   };
 }
 
+/**
+ * Read an MCP resource by URI and flatten its contents to text. Binary blobs are
+ * rendered as a `[binary …]` placeholder (the model can't use raw base64).
+ */
+export async function readMcpResource(handle: McpClientHandle, uri: string): Promise<string> {
+  const result = await handle.client.readResource({ uri });
+  const parts = (result.contents ?? []).map((c) => {
+    if ('text' in c && typeof c.text === 'string') return c.text;
+    if ('blob' in c && typeof c.blob === 'string') {
+      return `[binary ${c.mimeType ?? 'application/octet-stream'} ${c.uri}]`;
+    }
+    return '';
+  });
+  return parts.filter(Boolean).join('\n');
+}
+
+/** A parsed `@server:scheme://path` resource reference found in user text. */
+export interface ResourceRef {
+  /** The full matched token, e.g. `@files:file:///etc/hosts`. */
+  raw: string;
+  server: string;
+  uri: string;
+}
+
+// `@<server>:<scheme>://<rest>` — requires `://` so it can't match `@user:pass`
+// or an email. Server names are the settings.mcpServers keys (word chars + `-`).
+const RESOURCE_REF_RE = /@([A-Za-z0-9_-]+):([A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s]+)/g;
+
+/** Find all `@server:scheme://path` references in `text` (deduped by raw token). */
+export function parseResourceRefs(text: string): ResourceRef[] {
+  const out: ResourceRef[] = [];
+  const seen = new Set<string>();
+  for (const m of text.matchAll(RESOURCE_REF_RE)) {
+    const raw = m[0];
+    if (seen.has(raw)) continue;
+    seen.add(raw);
+    out.push({ raw, server: m[1]!, uri: m[2]! });
+  }
+  return out;
+}
+
+export interface ExpandResourcesResult {
+  /** Original text with resolved resource contents appended as tagged blocks. */
+  text: string;
+  resolved: ResourceRef[];
+  errors: Array<{ ref: ResourceRef; error: string }>;
+}
+
+/**
+ * Expand `@server:scheme://path` references by reading each resource and
+ * appending its content as a `<mcp-resource>` block after the user's text. The
+ * original tokens are left in place so the model sees what was referenced.
+ */
+export async function expandMcpResourceRefs(
+  text: string,
+  handles: McpClientHandle[],
+): Promise<ExpandResourcesResult> {
+  const refs = parseResourceRefs(text);
+  if (refs.length === 0) return { text, resolved: [], errors: [] };
+
+  const byName = new Map(handles.map((h) => [h.serverName, h]));
+  const blocks: string[] = [];
+  const resolved: ResourceRef[] = [];
+  const errors: Array<{ ref: ResourceRef; error: string }> = [];
+
+  for (const ref of refs) {
+    const handle = byName.get(ref.server);
+    if (!handle) {
+      errors.push({ ref, error: `unknown MCP server "${ref.server}"` });
+      continue;
+    }
+    try {
+      const content = await readMcpResource(handle, ref.uri);
+      blocks.push(
+        `<mcp-resource server="${ref.server}" uri="${ref.uri}">\n${content}\n</mcp-resource>`,
+      );
+      resolved.push(ref);
+    } catch (err) {
+      errors.push({ ref, error: (err as Error).message });
+    }
+  }
+
+  const expanded = blocks.length > 0 ? `${text}\n\n${blocks.join('\n\n')}` : text;
+  return { text: expanded, resolved, errors };
+}
+
 /**
  * Connect to many MCP servers — used at session start by the CLI.
  * Failures are individual (one bad server doesn't kill the rest).

packages/core/src/mcp/index.ts

@@ -9,10 +9,16 @@ export {
   closeAllMcpServers,
   pickTransportKind,
   parseHelperOutput,
+  readMcpResource,
+  parseResourceRefs,
+  expandMcpResourceRefs,
   type McpClientHandle,
   type McpToolMeta,
+  type McpResourceMeta,
   type McpTransportKind,
   type ConnectAllResult,
+  type ResourceRef,
+  type ExpandResourcesResult,
 } from './client.js';
 
 export {