MCP client integration

[glassBead-tc]

Implement a local MCP client to integrate external tools.

This PR introduces a client-side implementation for the Model Context Protocol (MCP), allowing the CLI to connect to and utilize tools exposed by local MCP servers. This enables users to define and manage local MCP servers, dynamically loading their tools into the CLI's tool registry for agent use.

Key features include:

• Integration of @modelcontextprotocol/sdk for communication.
• New /mcp subcommands (add --local, list, remove, refresh) for managing local MCP server configurations.
• Dynamic registration of MCP tools into the CLI's tool registry, making them available to the agent.
• Caching of connections and tools, along with graceful error handling and startup refresh.
• Sanitization of MCP tool names to prevent conflicts and ensure compatibility.
• Support for stdio, http, and sse transports for local MCP servers.

Usage highlights:

• Add local server:
  /mcp add --local --transport stdio my-server ./mcp-server --env "API_KEY=token"
/mcp add --local --transport http notion https://mcp.notion.com/mcp --header "Authorization: Bearer token"
• List: /mcp list
• Refresh tools: /mcp refresh
• Remove: /mcp remove my-server

---

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[glassBead-tc]

@cursoragent review this PR and produce a list of any bugs or conflicts of intention that appear more like drift than purposeful change

[cursor]

Below are the review findings focused on bugs or intent drift. I’ve ordered them by severity and pointed to the relevant files/sections.

---

Findings

1) High – resource_read can return the wrong type (breaks tool output)

Where: src/mcp/manager.ts → buildResourceToolDefinitions() → readResourceTool.execute
What:
When contents.length === 1, the tool returns a single TextContent | ImageContent object:

return blocks.length === 1 ? blocks[0] : blocks;

But ToolReturnContent is defined as string | Array<TextContent | ImageContent>. Returning a single object means the downstream flattening code (e.g. flattenToolResponse) treats it as a generic object and JSON stringifies it, yielding raw JSON instead of displayable content. This is a correctness bug (tool returns get mangled).

Fix idea: Always return blocks (even if length 1), or return a string for the single block.

---

2) High – Sampling declares tool support but never returns tool-use content

Where:

• src/mcp/manager.ts → createConnection() declares sampling: { tools: {} }
• src/cli/App.tsx → resolveMcpSampling() always returns plain text

What:
The MCP client advertises sampling.tools capability, but the response path only produces a plain text response with stopReason: "endTurn". If the server sends toolChoice: "required" or includes tools, this response is invalid per spec (it should return tool_use content and/or tool results). This is a spec mismatch and likely to cause server errors or incorrect behavior.

Why this is drift: The request was “sampling (+ tools)”. Right now sampling is manual text-only; tools are not supported in the response even though capability is advertised.

---

3) Medium – Capabilities are always advertised even when handlers aren’t available

Where:

• src/mcp/manager.ts → createConnection()
• src/mcp/interactions.ts → handleSamplingRequest() throws MethodNotFound when no handler

What:
The client always declares sampling and elicitation capabilities, even in headless mode where handlers are not installed. In that case, sampling will return MethodNotFound and elicitation will cancel. This is a mismatch between the advertised capabilities and actual support, and may cause servers to behave unexpectedly.

Fix idea: Gate capabilities.sampling / capabilities.elicitation on handler availability (or disable in headless).

---

4) Low – Synthetic prompt/resource tools are exposed even if server lacks support

Where: src/mcp/manager.ts → buildResourceToolDefinitions() / buildPromptToolDefinitions()
What:
Wrapper tools (resources_list, resource_read, prompts_list, prompt_get) are added unconditionally. If the server doesn’t implement resources/prompts, these tools will always error at runtime. This is likely harmless but adds noise and could lead the agent to call non-functional tools.

Fix idea: Only register these wrappers if the server reports the capability, or if the first call succeeds.

---

Test / Coverage Gaps

• No tests added for:
  • sampling flows (especially with tools)
  • resource/prompt wrapper tool outputs
  • elicitation form parsing edge cases
  • progress handling output

---

If you want, I can follow up with a patch addressing (1)–(3) quickly (they’re mostly localized fixes).