feat: host-side MCP client (@tanstack/ai-mcp)

[AlemTuzlak]

Summary

Adds @tanstack/ai-mcp — a host-side Model Context Protocol client — so a server-side chat() / agent loop can discover and run tools (and read resources/prompts) from external MCP servers, across any adapter, with optional generated end-to-end types.

Built on the official @modelcontextprotocol/sdk. The runtime stays edge-deployable (Streamable HTTP is node:-free); the Node-only stdio transport is isolated behind a @tanstack/ai-mcp/stdio subpath, and the codegen CLI's heavy deps are bundled into the bin only (never the library).

How it works

An MCP client turns a server into ready-to-spread ServerTool[]; you spread them into chat({ tools }). TanStack AI never knows MCP is involved.

import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai/adapters'
import { createMCPClient } from '@tanstack/ai-mcp'

const mcp = await createMCPClient({ transport: { type: 'http', url } })
const stream = chat({ adapter: openaiText(), model: 'gpt-4o', messages, tools: await mcp.tools() })
await mcp.close()

What's included

• createMCPClient — connect to one server. Transports: Streamable HTTP (edge-safe), SSE, and stdio (via @tanstack/ai-mcp/stdio), plus a user-supplied-transport escape hatch.
• createMCPClients — multi-server pool: parallel connect, auto-prefixed tool names (collision-free by default), close-all, typed per-server access.
• Three type-safety modes:
  1. client.tools() — auto-discovery (args unknown).
  2. client.tools([toolDefinition(...)]) — bind TanStack toolDefinition()s → typed + runtime-validated, allowlisted (reuses the existing tool primitive; no parallel schema system).
  3. createMCPClient<GeneratedServer>(...) — generated end-to-end types via npx @tanstack/ai-mcp generate + mcp.config.ts (emits per-server descriptors + a combined MCPServers map; pure types, zero runtime cost).
• Resources & prompts — resources()/readResource()/resourceTemplates(), prompts()/getPrompt(), plus mcpResourceToContentPart / mcpPromptToMessages converters for seeding chat().
• Lifecycle — caller-owned close() + [Symbol.asyncDispose] (await using); chat() never closes the client (warm reuse supported).
• Core change (@tanstack/ai) — adds an optional abortSignal to ToolExecutionContext and threads the chat run's signal through tool execution, so long-running tools (e.g. MCP callTool) cancel with the run. Additive/backward-compatible.

Testing & docs

• Unit tests across the package (client, pool, tools, resources, prompts, transport, CLI) using an in-memory MCP server.
• E2E (testing/e2e): a real in-process MCP server + chat route + Playwright spec proving an MCP tool executes inside chat() and its result reaches the streamed transcript.
• New docs page docs/tools/mcp.md (+ nav/cross-links), updated tool-calling skill + a new ai-mcp skill, and a changeset (minor: @tanstack/ai-mcp, @tanstack/ai).

Notes for reviewers

• History is granular (one commit per reviewed unit) — squash-merge recommended.
• Pre-existing examples/ typecheck failures (ts-solid-chat/ts-react-chat/ts-code-mode-web, missing fetcher from docs(chat): document the fetcher chat transport for server functions #681) are unrelated to this PR and excluded from the test:pr gate.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Host-side MCP support: connect/discover/run server tools, resources, and prompts in server-side chat; multi-server pooling with auto-prefixing, typed bindings, CLI type generation, stdio transport, and abort/cancel support for long-running tool calls; new chat({ mcp }) option to manage discovery/lifecycle.
• Documentation
  • Comprehensive MCP guides, README, codegen and chat integration how-tos, examples, and migration notes.
• Tests
  • Extensive unit, type, integration, and end-to-end coverage for MCP flows.

[tombeckenham]

I had to look into why you had these dynamic imports. I get it. It's the one package for the bin and the lib. If you'd imported at module level it would have added node and other dependencies into the library. It looks weird, but I'm happy with it. It's clever to be able to include the cli in the same package.

[tombeckenham]

This is great work. Really. I added a few small changes and cleaned up the docs. Ship it!