nanobot/docs/mcp_local_clone_and_tool_profiles.md

MCP local clones + tool profiles (local LLM friendly)

This documents the MCP/tool-profile work done to make MCP servers usable with local LLM providers that have low tool limits (e.g. ~20 tools) and/or unreliable native function-calling.

What we changed

• Local-clone policy for MCP servers

  • MCP servers are cloned/built locally under ./mcp-servers/ (not installed from npm/PyPI at runtime).
  • Repo gitignore keeps the clones out of git while keeping mcp-servers/README.md and .gitkeep.
  • Added scripts/setup-mcp-servers.sh to clone/build the Gitea MCP server (mcp-servers/gitea-mcp/) into a runnable binary.

• Docker mounts for local MCP servers

  • Multi-bot compose files mount ./mcp-servers into containers at /app/mcp-servers:ro.
  • This makes config entries like /app/mcp-servers/gitea-mcp/gitea-mcp work inside the container.

• MCP env var expansion

  • nanobot/agent/tools/mcp.py expands $VARS in MCP server env using the container environment, so configs can safely reference secrets without duplicating them:
    • Example: "GITEA_ACCESS_TOKEN": "$NANOBOT_GITLE_TOKEN"

• Local-provider tool calling reliability

  • nanobot/agent/context.py now includes a strict JSON tool-call protocol for providers that don’t do native function calling.
  • nanobot/providers/custom_provider.py was improved to parse tool calls when the model returns:
    • Embedded JSON tool calls in content, or
    • A message that is only a JSON object ({"name": "...", "parameters": {...}})

• Tool profile routing improvements

  • nanobot/agent/tool_routing.py includes a heuristic fast-path to pick an MCP-capable profile (e.g. workspace_mcp) when the user intent includes PRs/issues/repos/Gitea terms.
  • The LLM router still applies for general cases; this heuristic prevents obvious “forge” intents from being routed to a no-MCP profile.

• LLM empty-response retry

  • nanobot/agent/loop.py retries once if the provider returns an empty final message, nudging the model to either call a tool or respond with text.

Where MCP servers live (host vs container)

• Host repo path: ./mcp-servers/
  • Example: ./mcp-servers/gitea-mcp/
• Inside the nanobot container: /app/mcp-servers/ (mounted read-only)
  • Example: /app/mcp-servers/gitea-mcp/gitea-mcp

Minimal Gitea MCP setup

1. Build the local server (host):

./scripts/setup-mcp-servers.sh gitea

2. Add to per-bot config (host) ~/.nanobot-user1/config.json:

{
  "tools": {
    "mcpServers": {
      "gitea": {
        "command": "/app/mcp-servers/gitea-mcp/gitea-mcp",
        "args": ["-t", "stdio", "--host", "http://10.0.30.169:3000", "-r"],
        "env": {
          "GITEA_ACCESS_TOKEN": "$NANOBOT_GITLE_TOKEN"
        }
      }
    }
  }
}

3. Ensure your compose file mounts the local MCP servers directory:

• ./mcp-servers:/app/mcp-servers:ro

Tool profiles: what they do (and what they don’t)

• Built-in tools are registered once at gateway startup and do not “shut down”; profiles only control exposure to the LLM per turn.
• MCP tools/servers are connected lazily and can be connected/disconnected per turn based on the selected profile.

When MCP servers disconnect

• On a later message, if a new profile is selected whose mcpServers set does not include a previously-connected server, nanobot disconnects that MCP server.
• On gateway shutdown, nanobot disconnects all MCP servers.
• /new does not disconnect MCP servers; it only clears session history and triggers memory consolidation.

Common gotchas

• Router picked workspace (no MCP)

  • If the router selects a profile with "mcpServers": [], MCP tools are hidden even if the servers are configured.
  • Either improve routing, or (if acceptable) allowlist the specific MCP server in that profile ("mcpServers": ["gitea"]).

• Tool count limits on local models

  • A single MCP server can register 30+ tools (Gitea MCP: ~30), which can exceed local providers’ tool limits.
  • If you must stay under ~20 tools, prefer:
    • Narrow profiles, or
    • A “dispatcher tool” approach (one tool per MCP server) instead of registering every MCP tool individually.

• Repo owner/repo mismatch

  • Errors like GetUserByName commonly mean the owner string doesn’t exist or the token cannot see it.
  • Resolve the canonical owner/repo first (search/list repos), then call list PRs with the correct pair.