@zooid/context-mcp 0.7.0

package/src/mcp-server.test.ts

@@ -0,0 +1,186 @@
+import { describe, it, expect } from 'vitest'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
+import { buildContextMcpServer } from './mcp-server.js'
+import type { TransportContextProvider } from '@zooid/core'
+
+function makeProvider(over: Partial<TransportContextProvider> = {}): TransportContextProvider {
+  return {
+    getRoomHistory: async () => ({ messages: [], has_more: false }),
+    getRecentThreads: async () => ({ threads: [], has_more: false }),
+    getThreadHistory: async () => ({ messages: [], has_more: false }),
+    getChannelMembers: async () => [],
+    getChannelInfo: async () => ({ id: 'r', name: 'r', transport: 'matrix' }),
+    ...over,
+  }
+}
+
+async function connect(server: ReturnType<typeof buildContextMcpServer>) {
+  const [clientT, serverT] = InMemoryTransport.createLinkedPair()
+  const client = new Client({ name: 'test', version: '0.0.1' }, { capabilities: {} })
+  await Promise.all([server.connect(serverT), client.connect(clientT)])
+  return client
+}
+
+describe('buildContextMcpServer', () => {
+  it('lists exactly five tools with the spec names', async () => {
+    const server = buildContextMcpServer({ resolve: async () => makeProvider() })
+    const client = await connect(server)
+    const list = await client.listTools()
+    expect(list.tools.map((t) => t.name).sort()).toEqual([
+      'zooid_get_channel_info',
+      'zooid_get_history',
+      'zooid_get_members',
+      'zooid_get_recent_threads',
+      'zooid_get_thread_history',
+    ])
+  })
+
+  it('zooid_get_history forwards limit + before and returns the page as text JSON', async () => {
+    const calls: Array<{ limit?: number; before?: string }> = []
+    const provider = makeProvider({
+      getRoomHistory: async (_c, opts) => {
+        calls.push(opts)
+        return {
+          messages: [
+            { id: 'e1', sender: 'alice', text: 'hi', timestamp: 'T', is_agent: false },
+          ],
+          next_before: 'cursor-2',
+          has_more: true,
+        }
+      },
+    })
+    const server = buildContextMcpServer({ resolve: async () => provider })
+    const client = await connect(server)
+    const res = await client.callTool({
+      name: 'zooid_get_history',
+      arguments: { limit: 10, before: 'cursor-1' },
+    })
+    expect(calls).toEqual([{ limit: 10, before: 'cursor-1' }])
+    const text = (res.content as Array<{ type: string; text: string }>)[0].text
+    expect(JSON.parse(text)).toEqual({
+      messages: [{ id: 'e1', sender: 'alice', text: 'hi', timestamp: 'T', is_agent: false }],
+      next_before: 'cursor-2',
+      has_more: true,
+    })
+  })
+
+  it('clamps limit to max 200', async () => {
+    const calls: Array<{ limit?: number }> = []
+    const provider = makeProvider({
+      getRoomHistory: async (_c, opts) => {
+        calls.push(opts)
+        return { messages: [], has_more: false }
+      },
+    })
+    const server = buildContextMcpServer({ resolve: async () => provider })
+    const client = await connect(server)
+    await client.callTool({ name: 'zooid_get_history', arguments: { limit: 5000 } })
+    expect(calls[0].limit).toBe(200)
+  })
+
+  it('defaults limit to 50 when omitted', async () => {
+    const calls: Array<{ limit?: number }> = []
+    const provider = makeProvider({
+      getRoomHistory: async (_c, opts) => {
+        calls.push(opts)
+        return { messages: [], has_more: false }
+      },
+    })
+    const server = buildContextMcpServer({ resolve: async () => provider })
+    const client = await connect(server)
+    await client.callTool({ name: 'zooid_get_history', arguments: {} })
+    expect(calls[0].limit).toBe(50)
+  })
+
+  it('zooid_get_recent_threads returns the provider payload', async () => {
+    const provider = makeProvider({
+      getRecentThreads: async () => ({
+        threads: [
+          {
+            id: '$root',
+            sender: 'alice',
+            text: 'kickoff',
+            timestamp: 'T',
+            is_agent: false,
+            reply_count: 4,
+            last_activity_at: 'T2',
+          },
+        ],
+        has_more: false,
+      }),
+    })
+    const server = buildContextMcpServer({ resolve: async () => provider })
+    const client = await connect(server)
+    const res = await client.callTool({ name: 'zooid_get_recent_threads', arguments: {} })
+    const payload = JSON.parse((res.content as Array<{ text: string }>)[0].text)
+    expect(payload.threads[0]).toMatchObject({ id: '$root', reply_count: 4 })
+  })
+
+  it('zooid_get_thread_history forwards thread_id and limit/before', async () => {
+    const calls: Array<{ threadId: string; opts: { limit?: number; before?: string } }> = []
+    const provider = makeProvider({
+      getThreadHistory: async (_c, threadId, opts) => {
+        calls.push({ threadId, opts })
+        return {
+          messages: [
+            { id: '$root', sender: 'alice', text: 'root', timestamp: 'T', is_agent: false },
+          ],
+          has_more: false,
+        }
+      },
+    })
+    const server = buildContextMcpServer({ resolve: async () => provider })
+    const client = await connect(server)
+    await client.callTool({
+      name: 'zooid_get_thread_history',
+      arguments: { thread_id: '$root', limit: 10 },
+    })
+    expect(calls[0]).toEqual({ threadId: '$root', opts: { limit: 10, before: undefined } })
+  })
+
+  it('zooid_get_thread_history surfaces a validation error when thread_id is missing', async () => {
+    const server = buildContextMcpServer({ resolve: async () => makeProvider() })
+    const client = await connect(server)
+    const res = await client.callTool({ name: 'zooid_get_thread_history', arguments: {} })
+    expect(res.isError).toBe(true)
+  })
+
+  it('zooid_get_members and zooid_get_channel_info return the provider payload', async () => {
+    const provider = makeProvider({
+      getChannelMembers: async () => [
+        { id: '@alice:hs', name: 'alice', is_agent: false },
+        { id: '@architect:hs', name: 'architect', is_agent: true, agent_name: 'architect' },
+      ],
+      getChannelInfo: async () => ({ id: '!r:hs', name: 'general', transport: 'matrix' }),
+    })
+    const server = buildContextMcpServer({ resolve: async () => provider })
+    const client = await connect(server)
+
+    const m = await client.callTool({ name: 'zooid_get_members', arguments: {} })
+    expect(JSON.parse((m.content as Array<{ text: string }>)[0].text)).toEqual({
+      members: [
+        { id: '@alice:hs', name: 'alice', is_agent: false },
+        { id: '@architect:hs', name: 'architect', is_agent: true, agent_name: 'architect' },
+      ],
+    })
+
+    const i = await client.callTool({ name: 'zooid_get_channel_info', arguments: {} })
+    expect(JSON.parse((i.content as Array<{ text: string }>)[0].text)).toEqual({
+      id: '!r:hs',
+      name: 'general',
+      transport: 'matrix',
+    })
+  })
+
+  it('returns isError when the resolver throws (e.g. orphaned spawn-id)', async () => {
+    const server = buildContextMcpServer({
+      resolve: async () => {
+        throw new Error('unknown spawn')
+      },
+    })
+    const client = await connect(server)
+    const res = await client.callTool({ name: 'zooid_get_history', arguments: {} })
+    expect(res.isError).toBe(true)
+  })
+})

package/src/mcp-server.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { TransportContextProvider } from '@zooid/core'
+
+const MAX_LIMIT = 200
+const DEFAULT_LIMIT = 50
+
+export interface BuildContextMcpServerOpts {
+  /**
+   * Resolves the provider for the current spawn. In production this calls
+   * back to the daemon over the Unix socket; in unit tests it returns a
+   * fake provider directly.
+   */
+  resolve: () => Promise<TransportContextProvider>
+}
+
+export function buildContextMcpServer(opts: BuildContextMcpServerOpts): McpServer {
+  const server = new McpServer({ name: 'zooid-context', version: '0.0.1' })
+
+  server.tool(
+    'zooid_get_history',
+    "Read every message in the current room chronologically — top-level messages and all thread replies. Each message has an optional `thread_id` so the agent can group by thread. For a scan-the-room overview without reply noise, use `zooid_get_recent_threads` instead. Supports `limit` + `before` pagination.",
+    {
+      limit: z.number().int().positive().optional(),
+      before: z.string().optional(),
+    },
+    async ({ limit, before }) => {
+      const provider = await opts.resolve()
+      const clamped = Math.min(limit ?? DEFAULT_LIMIT, MAX_LIMIT)
+      const page = await provider.getRoomHistory('', { limit: clamped, before })
+      return { content: [{ type: 'text', text: JSON.stringify(page) }] }
+    },
+  )
+
+  server.tool(
+    'zooid_get_recent_threads',
+    "Scan-the-room overview: top-level messages and thread roots in the current room, newest first. Each entry has `reply_count` and `last_activity_at` so the agent can spot active conversations. Drill into a thread with `zooid_get_thread_history(thread_id)` where `thread_id` is the entry's `id`.",
+    {
+      limit: z.number().int().positive().optional(),
+      before: z.string().optional(),
+    },
+    async ({ limit, before }) => {
+      const provider = await opts.resolve()
+      const clamped = Math.min(limit ?? DEFAULT_LIMIT, MAX_LIMIT)
+      const page = await provider.getRecentThreads('', { limit: clamped, before })
+      return { content: [{ type: 'text', text: JSON.stringify(page) }] }
+    },
+  )
+
+  server.tool(
+    'zooid_get_thread_history',
+    "Drill into a specific thread: the root message followed by all replies in chronological order. Pass the `thread_id` from a `zooid_get_recent_threads` entry or a `Message.thread_id` from `zooid_get_history`.",
+    {
+      thread_id: z.string(),
+      limit: z.number().int().positive().optional(),
+      before: z.string().optional(),
+    },
+    async ({ thread_id, limit, before }) => {
+      const provider = await opts.resolve()
+      const clamped = Math.min(limit ?? DEFAULT_LIMIT, MAX_LIMIT)
+      const page = await provider.getThreadHistory('', thread_id, {
+        limit: clamped,
+        before,
+      })
+      return { content: [{ type: 'text', text: JSON.stringify(page) }] }
+    },
+  )
+
+  server.tool(
+    'zooid_get_members',
+    'List the humans and agents in the current room.',
+    {},
+    async () => {
+      const provider = await opts.resolve()
+      const members = await provider.getChannelMembers('')
+      return { content: [{ type: 'text', text: JSON.stringify({ members }) }] }
+    },
+  )
+
+  server.tool(
+    'zooid_get_channel_info',
+    'Describe the current room: id, display name, transport kind.',
+    {},
+    async () => {
+      const provider = await opts.resolve()
+      const info = await provider.getChannelInfo('')
+      return { content: [{ type: 'text', text: JSON.stringify(info) }] }
+    },
+  )
+
+  return server
+}

package/src/spawn-registry.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest'
+import { SpawnRegistry } from './spawn-registry.js'
+import type { TransportContextProvider } from '@zooid/core'
+
+const fakeProvider: TransportContextProvider = {
+  getRoomHistory: async () => ({ messages: [], has_more: false }),
+  getRecentThreads: async () => ({ threads: [], has_more: false }),
+  getThreadHistory: async () => ({ messages: [], has_more: false }),
+  getChannelMembers: async () => [],
+  getChannelInfo: async () => ({ id: 'r', name: 'r', transport: 'matrix' }),
+}
+
+describe('SpawnRegistry', () => {
+  it('register() returns a unique spawn-id', () => {
+    const r = new SpawnRegistry()
+    const a = r.register({
+      agentName: 'architect',
+      threadRef: { channelId: '!room:hs', threadId: '$root' },
+      provider: fakeProvider,
+    })
+    const b = r.register({
+      agentName: 'architect',
+      threadRef: { channelId: '!room:hs', threadId: '$root' },
+      provider: fakeProvider,
+    })
+    expect(a).not.toEqual(b)
+    expect(a).toMatch(/^[a-f0-9-]{36}$/)
+  })
+
+  it('get() returns the binding stored under the spawn-id', () => {
+    const r = new SpawnRegistry()
+    const spawnId = r.register({
+      agentName: 'architect',
+      threadRef: { channelId: '!room:hs', threadId: '$root' },
+      provider: fakeProvider,
+    })
+    const b = r.get(spawnId)
+    expect(b?.agentName).toBe('architect')
+    expect(b?.threadRef.channelId).toBe('!room:hs')
+    expect(b?.provider).toBe(fakeProvider)
+  })
+
+  it('release() removes the binding', () => {
+    const r = new SpawnRegistry()
+    const spawnId = r.register({
+      agentName: 'a',
+      threadRef: { channelId: 'c', threadId: 't' },
+      provider: fakeProvider,
+    })
+    r.release(spawnId)
+    expect(r.get(spawnId)).toBeUndefined()
+  })
+
+  it('get() returns undefined for unknown spawn-ids', () => {
+    const r = new SpawnRegistry()
+    expect(r.get('not-a-real-id')).toBeUndefined()
+  })
+})

package/src/spawn-registry.ts

@@ -0,0 +1,25 @@
+import { randomUUID } from 'node:crypto'
+import type { SpawnBinding } from './types.js'
+import type { TransportContextProvider, ThreadRef } from '@zooid/core'
+
+export class SpawnRegistry {
+  private readonly bindings = new Map<string, SpawnBinding>()
+
+  register(input: {
+    agentName: string
+    threadRef: ThreadRef
+    provider: TransportContextProvider
+  }): string {
+    const spawnId = randomUUID()
+    this.bindings.set(spawnId, { spawnId, ...input })
+    return spawnId
+  }
+
+  get(spawnId: string): SpawnBinding | undefined {
+    return this.bindings.get(spawnId)
+  }
+
+  release(spawnId: string): void {
+    this.bindings.delete(spawnId)
+  }
+}

package/src/types.ts

@@ -0,0 +1,20 @@
+import type { TransportContextProvider, ThreadRef } from '@zooid/core'
+
+/**
+ * Daemon-internal record keyed by spawn-id. One per ACP session that has
+ * a TransportContextProvider attached.
+ */
+export interface SpawnBinding {
+  spawnId: string
+  agentName: string
+  threadRef: ThreadRef
+  provider: TransportContextProvider
+}
+
+/** Shape we pass into ACP `session/new mcpServers[]`. */
+export interface ZooidContextServerSpec {
+  name: 'zooid-context'
+  command: string
+  args: string[]
+  env: Array<{ name: string; value: string }>
+}