Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(bot): add MCP client support (#1392)

ponsdea4c0d267c4bc
diff --git a/bot/vikingbot/agent/loop.py b/bot/vikingbot/agent/loop.py
index df0d31478..10d8fc053 100644
--- a/bot/vikingbot/agent/loop.py
+++ b/bot/vikingbot/agent/loop.py
@@ -5,6 +5,7 @@ from __future__ import annotations
import asyncio
import json
import time
+from contextlib import AsyncExitStack
from pathlib import Path
from typing import TYPE_CHECKING
@@ -61,6 +62,7 @@ class AgentLoop:
sandbox_manager: SandboxManager | None = None,
config: Config = None,
eval: bool = False,
+ mcp_servers: dict | None = None,
):
"""
Initialize the AgentLoop with all required dependencies and configuration.
@@ -128,8 +130,48 @@ class AgentLoop:
)
self._running = False
+ self._mcp_servers = mcp_servers or {}
+ self._mcp_stack: AsyncExitStack | None = None
+ self._mcp_connected = False
+ self._mcp_connecting = False
self._register_default_tools()
+ async def _connect_mcp(self) -> None:
+ """Connect to configured MCP servers (one-time, lazy, retryable on failure).
+
+ Ported from HKUDS/nanobot v0.1.5.
+ """
+ if self._mcp_connected or self._mcp_connecting or not self._mcp_servers:
+ return
+ self._mcp_connecting = True
+ try:
+ from vikingbot.agent.tools.mcp import connect_mcp_servers
+
+ self._mcp_stack = AsyncExitStack()
+ await self._mcp_stack.__aenter__()
+ await connect_mcp_servers(self._mcp_servers, self.tools, self._mcp_stack)
+ self._mcp_connected = True
+ except Exception as e:
+ logger.error(f"Failed to connect MCP servers (will retry next message): {e}")
+ if self._mcp_stack:
+ try:
+ await self._mcp_stack.aclose()
+ except Exception:
+ pass
+ self._mcp_stack = None
+ finally:
+ self._mcp_connecting = False
+
+ async def close_mcp(self) -> None:
+ """Close MCP server connections. Ported from HKUDS/nanobot v0.1.5."""
+ if self._mcp_stack:
+ try:
+ await self._mcp_stack.aclose()
+ except (RuntimeError, BaseExceptionGroup):
+ pass # MCP SDK cancel scope cleanup is noisy but harmless
+ self._mcp_stack = None
+ self._mcp_connected = False
+
async def _publish_thinking_event(
self, session_key: SessionKey, event_type: OutboundEventType, content: str
) -> None:
@@ -181,6 +223,7 @@ class AgentLoop:
async def run(self) -> None:
"""Run the agent loop, processing messages from the bus."""
self._running = True
+ await self._connect_mcp()
logger.info("Agent loop started")
while self._running:
@@ -816,6 +859,7 @@ Respond with ONLY valid JSON, no markdown fences."""
Returns:
The agent's response.
"""
+ await self._connect_mcp()
msg = InboundMessage(session_key=session_key, sender_id="user", content=content)
response = await self._process_message(msg)
diff --git a/bot/vikingbot/agent/tools/mcp.py b/bot/vikingbot/agent/tools/mcp.py
new file mode 100644
index 000000000..884b00712
--- /dev/null
+++ b/bot/vikingbot/agent/tools/mcp.py
@@ -0,0 +1,261 @@
+"""MCP client: connects to MCP servers and wraps their tools as native vikingbot tools.
+
+Ported from HKUDS/nanobot v0.1.5 (bot/vikingbot/agent/tools/mcp.py).
+Original implementation:
+ https://github.com/HKUDS/nanobot/pull/554 (initial MCP support)
+ https://github.com/HKUDS/nanobot/pull/1488 (SSE + streamableHttp transports)
+"""
+
+import asyncio
+from contextlib import AsyncExitStack
+from typing import Any
+
+import httpx
+from loguru import logger
+
+from vikingbot.agent.tools.base import Tool, ToolContext
+from vikingbot.agent.tools.registry import ToolRegistry
+
+
+def _extract_nullable_branch(options: Any) -> tuple[dict[str, Any], bool] | None:
+ """Return the single non-null branch for nullable unions."""
+ if not isinstance(options, list):
+ return None
+
+ non_null: list[dict[str, Any]] = []
+ saw_null = False
+ for option in options:
+ if not isinstance(option, dict):
+ return None
+ if option.get("type") == "null":
+ saw_null = True
+ continue
+ non_null.append(option)
+
+ if saw_null and len(non_null) == 1:
+ return non_null[0], True
+ return None
+
+
+def _normalize_schema_for_openai(schema: Any) -> dict[str, Any]:
+ """Normalize only nullable JSON Schema patterns for tool definitions."""
+ if not isinstance(schema, dict):
+ return {"type": "object", "properties": {}}
+
+ normalized = dict(schema)
+
+ raw_type = normalized.get("type")
+ if isinstance(raw_type, list):
+ non_null = [item for item in raw_type if item != "null"]
+ if "null" in raw_type and len(non_null) == 1:
+ normalized["type"] = non_null[0]
+ normalized["nullable"] = True
+
+ for key in ("oneOf", "anyOf"):
+ nullable_branch = _extract_nullable_branch(normalized.get(key))
+ if nullable_branch is not None:
+ branch, _ = nullable_branch
+ merged = {k: v for k, v in normalized.items() if k != key}
+ merged.update(branch)
+ normalized = merged
+ normalized["nullable"] = True
+ break
+
+ if "properties" in normalized and isinstance(normalized["properties"], dict):
+ normalized["properties"] = {
+ name: _normalize_schema_for_openai(prop)
+ if isinstance(prop, dict)
+ else prop
+ for name, prop in normalized["properties"].items()
+ }
+
+ if "items" in normalized and isinstance(normalized["items"], dict):
+ normalized["items"] = _normalize_schema_for_openai(normalized["items"])
+
+ if normalized.get("type") != "object":
+ return normalized
+
+ normalized.setdefault("properties", {})
+ normalized.setdefault("required", [])
+ return normalized
+
+
+class MCPToolWrapper(Tool):
+ """Wraps a single MCP server tool as a nanobot Tool."""
+
+ def __init__(self, session, server_name: str, tool_def, tool_timeout: int = 30):
+ self._session = session
+ self._original_name = tool_def.name
+ self._name = f"mcp_{server_name}_{tool_def.name}"
+ self._description = tool_def.description or tool_def.name
+ raw_schema = tool_def.inputSchema or {"type": "object", "properties": {}}
+ self._parameters = _normalize_schema_for_openai(raw_schema)
+ self._tool_timeout = tool_timeout
+
+ @property
+ def name(self) -> str:
+ return self._name
+
+ @property
+ def description(self) -> str:
+ return self._description
+
+ @property
+ def parameters(self) -> dict[str, Any]:
+ return self._parameters
+
+ async def execute(self, tool_context: ToolContext, **kwargs: Any) -> str:
+ # tool_context is accepted for interface compatibility with vikingbot's
+ # native Tool.execute signature, but unused here since MCP servers
+ # receive their inputs purely via kwargs.
+ from mcp import types
+
+ try:
+ result = await asyncio.wait_for(
+ self._session.call_tool(self._original_name, arguments=kwargs),
+ timeout=self._tool_timeout,
+ )
+ except asyncio.TimeoutError:
+ logger.warning("MCP tool '{}' timed out after {}s", self._name, self._tool_timeout)
+ return f"(MCP tool call timed out after {self._tool_timeout}s)"
+ except asyncio.CancelledError:
+ # MCP SDK's anyio cancel scopes can leak CancelledError on timeout/failure.
+ # Re-raise only if our task was externally cancelled (e.g. /stop).
+ task = asyncio.current_task()
+ if task is not None and task.cancelling() > 0:
+ raise
+ logger.warning("MCP tool '{}' was cancelled by server/SDK", self._name)
+ return "(MCP tool call was cancelled)"
+ except Exception as exc:
+ logger.exception(
+ "MCP tool '{}' failed: {}: {}",
+ self._name,
+ type(exc).__name__,
+ exc,
+ )
+ return f"(MCP tool call failed: {type(exc).__name__})"
+
+ parts = []
+ for block in result.content:
+ if isinstance(block, types.TextContent):
+ parts.append(block.text)
+ else:
+ parts.append(str(block))
+ return "\n".join(parts) or "(no output)"
+
+
+async def connect_mcp_servers(
+ mcp_servers: dict, registry: ToolRegistry, stack: AsyncExitStack
+) -> None:
+ """Connect to configured MCP servers and register their tools."""
+ from mcp import ClientSession, StdioServerParameters
+ from mcp.client.sse import sse_client
+ from mcp.client.stdio import stdio_client
+ from mcp.client.streamable_http import streamable_http_client
+
+ for name, cfg in mcp_servers.items():
+ try:
+ transport_type = cfg.type
+ if not transport_type:
+ if cfg.command:
+ transport_type = "stdio"
+ elif cfg.url:
+ # Convention: URLs ending with /sse use SSE transport; others use streamableHttp
+ transport_type = (
+ "sse" if cfg.url.rstrip("/").endswith("/sse") else "streamableHttp"
+ )
+ else:
+ logger.warning("MCP server '{}': no command or url configured, skipping", name)
+ continue
+
+ if transport_type == "stdio":
+ params = StdioServerParameters(
+ command=cfg.command, args=cfg.args, env=cfg.env or None
+ )
+ read, write = await stack.enter_async_context(stdio_client(params))
+ elif transport_type == "sse":
+ def httpx_client_factory(
+ headers: dict[str, str] | None = None,
+ timeout: httpx.Timeout | None = None,
+ auth: httpx.Auth | None = None,
+ ) -> httpx.AsyncClient:
+ merged_headers = {
+ "Accept": "application/json, text/event-stream",
+ **(cfg.headers or {}),
+ **(headers or {}),
+ }
+ return httpx.AsyncClient(
+ headers=merged_headers or None,
+ follow_redirects=True,
+ timeout=timeout,
+ auth=auth,
+ )
+
+ read, write = await stack.enter_async_context(
+ sse_client(cfg.url, httpx_client_factory=httpx_client_factory)
+ )
+ elif transport_type == "streamableHttp":
+ # Always provide an explicit httpx client so MCP HTTP transport does not
+ # inherit httpx's default 5s timeout and preempt the higher-level tool timeout.
+ http_client = await stack.enter_async_context(
+ httpx.AsyncClient(
+ headers=cfg.headers or None,
+ follow_redirects=True,
+ timeout=None,
+ )
+ )
+ read, write, _ = await stack.enter_async_context(
+ streamable_http_client(cfg.url, http_client=http_client)
+ )
+ else:
+ logger.warning("MCP server '{}': unknown transport type '{}'", name, transport_type)
+ continue
+
+ session = await stack.enter_async_context(ClientSession(read, write))
+ await session.initialize()
+
+ tools = await session.list_tools()
+ enabled_tools = set(cfg.enabled_tools)
+ allow_all_tools = "*" in enabled_tools
+ registered_count = 0
+ matched_enabled_tools: set[str] = set()
+ available_raw_names = [tool_def.name for tool_def in tools.tools]
+ available_wrapped_names = [f"mcp_{name}_{tool_def.name}" for tool_def in tools.tools]
+ for tool_def in tools.tools:
+ wrapped_name = f"mcp_{name}_{tool_def.name}"
+ if (
+ not allow_all_tools
+ and tool_def.name not in enabled_tools
+ and wrapped_name not in enabled_tools
+ ):
+ logger.debug(
+ "MCP: skipping tool '{}' from server '{}' (not in enabledTools)",
+ wrapped_name,
+ name,
+ )
+ continue
+ wrapper = MCPToolWrapper(session, name, tool_def, tool_timeout=cfg.tool_timeout)
+ registry.register(wrapper)
+ logger.debug("MCP: registered tool '{}' from server '{}'", wrapper.name, name)
+ registered_count += 1
+ if enabled_tools:
+ if tool_def.name in enabled_tools:
+ matched_enabled_tools.add(tool_def.name)
+ if wrapped_name in enabled_tools:
+ matched_enabled_tools.add(wrapped_name)
+
+ if enabled_tools and not allow_all_tools:
+ unmatched_enabled_tools = sorted(enabled_tools - matched_enabled_tools)
+ if unmatched_enabled_tools:
+ logger.warning(
+ "MCP server '{}': enabledTools entries not found: {}. Available raw names: {}. "
+ "Available wrapped names: {}",
+ name,
+ ", ".join(unmatched_enabled_tools),
+ ", ".join(available_raw_names) or "(none)",
+ ", ".join(available_wrapped_names) or "(none)",
+ )
+
+ logger.info("MCP server '{}': connected, {} tools registered", name, registered_count)
+ except Exception as e:
+ logger.error("MCP server '{}': failed to connect: {}", name, e)
diff --git a/bot/vikingbot/cli/commands.py b/bot/vikingbot/cli/commands.py
index dcac8c3f6..aeee2ab9d 100644
--- a/bot/vikingbot/cli/commands.py
+++ b/bot/vikingbot/cli/commands.py
@@ -297,7 +297,10 @@ def gateway(
# if enable_console:
# tasks.append(start_console(console_port))
- await asyncio.gather(*tasks)
+ try:
+ await asyncio.gather(*tasks)
+ finally:
+ await agent_loop.close_mcp()
asyncio.run(run())
@@ -348,6 +351,7 @@ def prepare_agent_loop(config, bus, session_manager, cron, quiet: bool = False,
sandbox_manager=sandbox_manager,
config=config,
eval=eval,
+ mcp_servers=config.tools.mcp_servers,
)
# Set the agent reference in cron if it uses the holder pattern
if hasattr(cron, "_agent_holder"):
@@ -615,31 +619,36 @@ def chat(
)
async def run():
- if is_single_turn:
- # Single-turn mode: run channels and agent, exit after response
- task_cron = asyncio.create_task(cron.start())
- task_channels = asyncio.create_task(channels.start_all())
- task_agent = asyncio.create_task(agent_loop.run())
-
- # Wait for channels to complete (it will complete after getting response)
- done, pending = await asyncio.wait([task_channels], return_when=asyncio.FIRST_COMPLETED)
-
- # Cancel all other tasks
- for task in pending:
- task.cancel()
- task_cron.cancel()
- task_agent.cancel()
-
- # Wait for cancellation
- await asyncio.gather(task_cron, task_agent, return_exceptions=True)
- else:
- # Interactive mode: run forever
- tasks = []
- tasks.append(cron.start())
- tasks.append(channels.start_all())
- tasks.append(agent_loop.run())
+ try:
+ if is_single_turn:
+ # Single-turn mode: run channels and agent, exit after response
+ task_cron = asyncio.create_task(cron.start())
+ task_channels = asyncio.create_task(channels.start_all())
+ task_agent = asyncio.create_task(agent_loop.run())
+
+ # Wait for channels to complete (it will complete after getting response)
+ done, pending = await asyncio.wait(
+ [task_channels], return_when=asyncio.FIRST_COMPLETED
+ )
- await asyncio.gather(*tasks)
+ # Cancel all other tasks
+ for task in pending:
+ task.cancel()
+ task_cron.cancel()
+ task_agent.cancel()
+
+ # Wait for cancellation
+ await asyncio.gather(task_cron, task_agent, return_exceptions=True)
+ else:
+ # Interactive mode: run forever
+ tasks = []
+ tasks.append(cron.start())
+ tasks.append(channels.start_all())
+ tasks.append(agent_loop.run())
+
+ await asyncio.gather(*tasks)
+ finally:
+ await agent_loop.close_mcp()
try:
asyncio.run(run())
diff --git a/bot/vikingbot/config/schema.py b/bot/vikingbot/config/schema.py
index fcefdcee3..438f1dc10 100644
--- a/bot/vikingbot/config/schema.py
+++ b/bot/vikingbot/config/schema.py
@@ -2,7 +2,7 @@
from enum import Enum
from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Literal, Optional
from pydantic import BaseModel, ConfigDict, Field
from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -505,11 +505,30 @@ class ExecToolConfig(BaseModel):
timeout: int = 60
+class MCPServerConfig(BaseModel):
+ """MCP server connection configuration (stdio / sse / streamableHttp).
+
+ Ported from HKUDS/nanobot v0.1.5.
+ """
+
+ type: Optional[Literal["stdio", "sse", "streamableHttp"]] = None # auto-detected if omitted
+ command: str = "" # Stdio: command to run (e.g. "npx")
+ args: list[str] = Field(default_factory=list) # Stdio: command arguments
+ env: dict[str, str] = Field(default_factory=dict) # Stdio: extra env vars
+ url: str = "" # HTTP/SSE endpoint URL
+ headers: dict[str, str] = Field(default_factory=dict) # HTTP/SSE custom headers
+ tool_timeout: int = 30 # seconds before a tool call is cancelled
+ enabled_tools: list[str] = Field(
+ default_factory=lambda: ["*"]
+ ) # Only register these tools; accepts raw MCP names or wrapped mcp_<server>_<tool>; ["*"] = all
+
+
class ToolsConfig(BaseModel):
"""Tools configuration."""
web: WebToolsConfig = Field(default_factory=WebToolsConfig)
exec: ExecToolConfig = Field(default_factory=ExecToolConfig)
+ mcp_servers: dict[str, MCPServerConfig] = Field(default_factory=dict)
class SandboxNetworkConfig(BaseModel):
diff --git a/pyproject.toml b/pyproject.toml
index 6451144c7..90d710219 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -148,6 +148,7 @@ bot = [
"tavily-python>=0.5.0",
"gradio>=6.6.0",
"py-machineid>=1.0.0",
+ "mcp>=1.0.0",
]
# vikingbot optional features
bot-langfuse = ["langfuse>=3.0.0"]