@strav/brain 1.0.0-alpha.11 → 1.0.0-alpha.12

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@strav/brain",
-  "version": "1.0.0-alpha.11",
+  "version": "1.0.0-alpha.12",
   "description": "Strav AI module — unified Provider interface, BrainManager, threads, prompt caching, tools / agents / MCP. Anthropic + OpenAI providers; Gemini / DeepSeek follow.",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./mcp": "./src/mcp/index.ts"
   },
   "files": [
     "src",
@@ -19,8 +20,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/kernel": "1.0.0-alpha.11",
     "@anthropic-ai/sdk": "^0.100.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@strav/kernel": "1.0.0-alpha.12",
     "openai": "^6.0.0"
   },
   "peerDependencies": {

package/src/mcp/client.ts

@@ -0,0 +1,157 @@
+/**
+ * `MCPClient` — local MCP client for providers that lack server-side
+ * MCP support (OpenAI, Gemini, DeepSeek, …).
+ *
+ * Wraps the official `@modelcontextprotocol/sdk` client. Connects to a
+ * single MCP server over Streamable HTTP, lists its tools, and invokes
+ * them. The agentic loop sees these as ordinary `Tool`s — translation
+ * happens in `resolveMcpTools`.
+ *
+ * Lifecycle:
+ *
+ *   const client = new MCPClient(serverConfig)
+ *   await client.connect()
+ *   const tools = await client.listTools()
+ *   const result = await client.callTool('name', {...})
+ *   await client.close()
+ *
+ * Authentication:
+ *   `MCPServer.authorizationToken` is forwarded as
+ *   `Authorization: Bearer <token>`. OAuth-flow servers need
+ *   out-of-band token exchange — same constraint as the server-side
+ *   path. Full OAuth handshake is a later slice.
+ *
+ * Transport:
+ *   V1 only does Streamable HTTP — the current MCP transport. Legacy
+ *   SSE-only endpoints aren't supported; if a server URL ends with
+ *   `/sse` and only speaks the legacy protocol, the connection will
+ *   fail and apps should run against a Streamable-HTTP endpoint
+ *   instead.
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import { BrainError } from '../brain_error.ts'
+import type { MCPServer } from '../mcp_server.ts'
+
+/** Result of a single MCP tool invocation, as returned by `tools/call`. */
+export interface MCPCallToolResult {
+  /** Stringified content — text blocks concatenated; image / resource blocks JSON-serialized. */
+  content: string
+  /** `true` when the MCP server reports the tool execution failed. */
+  isError: boolean
+}
+
+/** Tool descriptor surfaced by `tools/list`. */
+export interface MCPToolDescriptor {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+}
+
+export interface MCPClientOptions {
+  /** Override the transport used to dial the server. Tests inject a mock here. */
+  client?: Client
+}
+
+export class MCPClient {
+  readonly server: MCPServer
+  private readonly _client: Client
+  private _connected = false
+
+  constructor(server: MCPServer, options: MCPClientOptions = {}) {
+    this.server = server
+    this._client =
+      options.client ??
+      new Client(
+        { name: `@strav/brain:${server.name}`, version: '1.0.0' },
+        { capabilities: {} },
+      )
+  }
+
+  async connect(): Promise<void> {
+    if (this._connected) return
+    const transport = this._buildTransport()
+    try {
+      await this._client.connect(transport)
+      this._connected = true
+    } catch (cause) {
+      throw new BrainError(
+        `MCPClient(${this.server.name}): failed to connect to ${this.server.url}.`,
+        { context: { server: this.server.name, url: this.server.url }, cause },
+      )
+    }
+  }
+
+  async listTools(): Promise<MCPToolDescriptor[]> {
+    await this.connect()
+    let response: Awaited<ReturnType<Client['listTools']>>
+    try {
+      response = await this._client.listTools()
+    } catch (cause) {
+      throw new BrainError(
+        `MCPClient(${this.server.name}): tools/list failed.`,
+        { context: { server: this.server.name }, cause },
+      )
+    }
+    return response.tools.map((t) => ({
+      name: t.name,
+      description: t.description ?? '',
+      inputSchema: (t.inputSchema ?? { type: 'object' }) as Record<string, unknown>,
+    }))
+  }
+
+  async callTool(name: string, input: unknown): Promise<MCPCallToolResult> {
+    await this.connect()
+    let response: Awaited<ReturnType<Client['callTool']>>
+    try {
+      response = await this._client.callTool({
+        name,
+        arguments: (input ?? {}) as Record<string, unknown>,
+      })
+    } catch (cause) {
+      throw new BrainError(
+        `MCPClient(${this.server.name}): tools/call ${name} failed.`,
+        { context: { server: this.server.name, tool: name }, cause },
+      )
+    }
+    return {
+      content: flattenContent(response.content),
+      isError: Boolean(response.isError),
+    }
+  }
+
+  async close(): Promise<void> {
+    if (!this._connected) return
+    try {
+      await this._client.close()
+    } finally {
+      this._connected = false
+    }
+  }
+
+  private _buildTransport(): StreamableHTTPClientTransport {
+    const headers: Record<string, string> = {}
+    if (this.server.authorizationToken !== undefined) {
+      headers.Authorization = `Bearer ${this.server.authorizationToken}`
+    }
+    return new StreamableHTTPClientTransport(new URL(this.server.url), {
+      requestInit: { headers },
+    })
+  }
+}
+
+function flattenContent(
+  content: Awaited<ReturnType<Client['callTool']>>['content'],
+): string {
+  if (!Array.isArray(content)) return ''
+  const parts: string[] = []
+  for (const block of content) {
+    if (block.type === 'text') {
+      parts.push(block.text)
+    } else {
+      parts.push(JSON.stringify(block))
+    }
+  }
+  return parts.join('')
+}

package/src/mcp/index.ts

@@ -0,0 +1,16 @@
+// Public API of `@strav/brain/mcp` — local MCP client for providers
+// without server-side MCP support (OpenAI, Gemini, DeepSeek). The
+// Anthropic provider continues to use server-side MCP via the
+// top-level `MCPServer` config; nothing here is needed for that path.
+
+export {
+  MCPClient,
+  type MCPCallToolResult,
+  type MCPClientOptions,
+  type MCPToolDescriptor,
+} from './client.ts'
+export {
+  resolveMcpTools,
+  type ResolveMcpToolsOptions,
+  type ResolvedMcpTools,
+} from './resolve_mcp_tools.ts'

package/src/mcp/resolve_mcp_tools.ts

@@ -0,0 +1,86 @@
+/**
+ * `resolveMcpTools` — connects to each `MCPServer`, discovers its
+ * tools, and surfaces them as framework `Tool`s the standard agentic
+ * loop already knows how to invoke.
+ *
+ * Honors the per-server config in `MCPServer.tools`:
+ *   - `enabled: false` → server is skipped entirely.
+ *   - `allowedTools` → only those tool names are exposed.
+ *
+ * Naming: discovered tools are namespaced as `<server>__<tool>` to
+ * keep names unique when multiple servers expose overlapping names.
+ * The `Tool.execute` then routes back to the correct server. The
+ * underscore separator (not `.` or `/`) is chosen because OpenAI's
+ * tool-name regex rejects `.` and `/`.
+ *
+ * Lifecycle: this helper returns `{ tools, close }`. `close` runs all
+ * client `close()` calls in parallel — providers must call it in a
+ * `finally` to avoid leaking transports.
+ */
+
+import type { MCPServer } from '../mcp_server.ts'
+import type { Tool, ToolContext } from '../tool.ts'
+import { MCPClient } from './client.ts'
+
+export interface ResolvedMcpTools {
+  tools: Tool[]
+  close(): Promise<void>
+}
+
+export interface ResolveMcpToolsOptions {
+  /** Override the client factory — tests inject mock clients per server here. */
+  clientFactory?(server: MCPServer): MCPClient
+}
+
+const NAME_SEPARATOR = '__'
+
+export async function resolveMcpTools(
+  servers: readonly MCPServer[],
+  options: ResolveMcpToolsOptions = {},
+): Promise<ResolvedMcpTools> {
+  const clients: MCPClient[] = []
+  const tools: Tool[] = []
+
+  for (const server of servers) {
+    if (server.tools?.enabled === false) continue
+    const client = options.clientFactory
+      ? options.clientFactory(server)
+      : new MCPClient(server)
+    clients.push(client)
+
+    const allowed = server.tools?.allowedTools
+    const allowedSet = allowed ? new Set(allowed) : null
+
+    const descriptors = await client.listTools()
+    for (const descriptor of descriptors) {
+      if (allowedSet && !allowedSet.has(descriptor.name)) continue
+      tools.push(buildTool(server.name, client, descriptor))
+    }
+  }
+
+  return {
+    tools,
+    close: async () => {
+      await Promise.all(clients.map((c) => c.close()))
+    },
+  }
+}
+
+function buildTool(
+  serverName: string,
+  client: MCPClient,
+  descriptor: { name: string; description: string; inputSchema: Record<string, unknown> },
+): Tool {
+  return {
+    name: `${serverName}${NAME_SEPARATOR}${descriptor.name}`,
+    description: descriptor.description,
+    inputSchema: descriptor.inputSchema,
+    async execute(input: unknown, _ctx: ToolContext): Promise<string> {
+      const result = await client.callTool(descriptor.name, input)
+      if (result.isError) {
+        return `MCP tool error: ${result.content}`
+      }
+      return result.content
+    },
+  }
+}

package/src/providers/openai_provider.ts

@@ -22,9 +22,12 @@
  *     a `function` namespace where Anthropic uses flat tool
  *     definitions.
  *
- *   - `MCPServer[]` → throws `BrainError`. OpenAI has no
- *     server-side MCP support; the local MCP client slice
- *     (`@strav/brain/mcp`) lands when this is needed.
+ *   - `MCPServer[]` → resolved via the local MCP client
+ *     (`@strav/brain/mcp`). Each server is dialed, its tools are
+ *     discovered, and they're merged with locally-defined tools.
+ *     The agentic loop then treats them uniformly. Tool names are
+ *     namespaced `<server>__<tool>` to avoid collisions. Transports
+ *     are closed in a `finally` once the loop exits.
  *
  *   - `cache: true` is a no-op. OpenAI auto-caches; there's no
  *     per-block cache_control to set. The framework flag is
@@ -48,6 +51,8 @@ import OpenAI from 'openai'
 import type { AgentResult } from '../agent_result.ts'
 import { BrainError } from '../brain_error.ts'
 import type { OpenAIProviderConfig } from '../brain_config.ts'
+import type { MCPServer } from '../mcp_server.ts'
+import { resolveMcpTools, type ResolveMcpToolsOptions } from '../mcp/resolve_mcp_tools.ts'
 import type { Provider, RunWithToolsOptions } from '../provider.ts'
 import type { Tool } from '../tool.ts'
 import { ToolExecutionError } from '../tool_execution_error.ts'
@@ -66,20 +71,32 @@ import type {
 
 const DEFAULT_OPENAI_MODEL = 'gpt-5'
 
+export interface OpenAIProviderOptions {
+  client?: OpenAI
+  /**
+   * Internal seam — tests inject a stub MCP client factory so MCP
+   * tool resolution doesn't dial the network. Real apps leave it
+   * unset; the provider uses the default `MCPClient`.
+   */
+  mcpClientFactory?: ResolveMcpToolsOptions['clientFactory']
+}
+
 export class OpenAIProvider implements Provider {
   readonly name: string
   private readonly client: OpenAI
   private readonly defaultModel: string
   private readonly defaultMaxTokens: number
+  private readonly mcpClientFactory?: ResolveMcpToolsOptions['clientFactory']
 
   constructor(
     name: string,
     config: OpenAIProviderConfig,
-    options: { client?: OpenAI } = {},
+    options: OpenAIProviderOptions = {},
   ) {
     this.name = name
     this.defaultModel = config.defaultModel ?? DEFAULT_OPENAI_MODEL
     this.defaultMaxTokens = config.defaultMaxTokens ?? 4096
+    this.mcpClientFactory = options.mcpClientFactory
     this.client =
       options.client ??
       new OpenAI({
@@ -129,12 +146,25 @@ export class OpenAIProvider implements Provider {
     tools: readonly Tool[],
     options: RunWithToolsOptions = {},
   ): Promise<AgentResult> {
-    if (options.mcpServers && options.mcpServers.length > 0) {
-      throw new BrainError(
-        'OpenAIProvider.runWithTools: MCP servers are not supported by the OpenAI provider in V1. Use the Anthropic provider for server-side MCP, or wait for the local MCP client slice.',
-        { context: { provider: this.name } },
-      )
+    const mcpServers: readonly MCPServer[] = options.mcpServers ?? []
+    const resolved =
+      mcpServers.length > 0
+        ? await resolveMcpTools(mcpServers, {
+            ...(this.mcpClientFactory ? { clientFactory: this.mcpClientFactory } : {}),
+          })
+        : { tools: [] as Tool[], close: async () => {} }
+    try {
+      return await this._runLoop(messages, [...tools, ...resolved.tools], options)
+    } finally {
+      await resolved.close()
     }
+  }
+
+  private async _runLoop(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptions,
+  ): Promise<AgentResult> {
     const maxIterations = options.maxIterations ?? 10
     const toolMap = new Map<string, Tool>(tools.map((t) => [t.name, t]))
     const workingMessages: Message[] = [...messages]