初始化提交

backend/app/integrations/mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP server 接入（简化 HTTP client，非完整 JSON-RPC）。"""

backend/app/integrations/mcp/client.py

@@ -0,0 +1,106 @@
+"""MCP 客户端 — Streamable HTTP 与 stdio 均用的 JSON-RPC 解析工具。
+
+两种传输层的具体实现在 ``transports/`` 子包中。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from app.core.config import settings
+from app.modules.tool_runtime.definition import ToolResult
+
+
+def _auth_headers(auth_token: str | None) -> dict[str, str]:
+    return {"Authorization": f"Bearer {auth_token}"} if auth_token else {}
+
+
+def _parse_call_result(data: dict) -> ToolResult:
+    """解析 JSON-RPC tools/call 响应为 ToolResult。
+
+    供 StreamableHttpTransport 和 StdioTransport 共用。
+    """
+    if data.get("error"):
+        return ToolResult(
+            ok=False,
+            stdout="",
+            stderr=data["error"].get("message", "MCP 错误"),
+            duration_ms=0,
+            exit_code=1,
+            timeout=False,
+            truncated=False,
+            trace_id="",
+        )
+    result = data.get("result") if isinstance(data, dict) else None
+    if not isinstance(result, dict):
+        return ToolResult(
+            ok=False,
+            stdout=str(result) if result else "",
+            stderr="无效响应格式",
+            duration_ms=0,
+            exit_code=1,
+            timeout=False,
+            truncated=False,
+            trace_id="",
+        )
+    content = result.get("content", [])
+    stdout_parts = []
+    for item in content:
+        if item.get("type") in ("text", "json"):
+            stdout_parts.append(item.get("text", ""))
+    truncated = bool((result.get("meta") or {}).get("truncated", False))
+    return ToolResult(
+        ok=not result.get("isError", False),
+        stdout="".join(stdout_parts),
+        stderr="",
+        duration_ms=0,
+        exit_code=0 if not result.get("isError", False) else 1,
+        timeout=False,
+        truncated=truncated,
+        trace_id="",
+    )
+
+
+async def call_tool(
+    http_client: httpx.AsyncClient,
+    endpoint_url: str,
+    tool_name: str,
+    arguments: dict,
+    auth_token: str | None = None,
+    meta: dict | None = None,
+) -> ToolResult:
+    """通过 Streamable HTTP 调用 MCP 工具（供 _make_mcp_executor 使用）。"""
+    body: dict[str, Any] = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {
+            "name": tool_name,
+            "arguments": arguments,
+        },
+    }
+    if meta:
+        body["meta"] = meta
+    try:
+        resp = await http_client.post(
+            endpoint_url,
+            json=body,
+            headers=_auth_headers(auth_token),
+            timeout=settings.mcp_call_timeout_seconds,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+    except (httpx.HTTPError, ValueError, TypeError) as exc:
+        return ToolResult(
+            ok=False,
+            stdout="",
+            stderr=str(exc),
+            duration_ms=0,
+            exit_code=None,
+            timeout=False,
+            truncated=False,
+            trace_id="",
+        )
+    return _parse_call_result(data)

backend/app/integrations/mcp/process_manager.py

@@ -0,0 +1,96 @@
+"""MCP stdio 子进程生命周期管理。
+
+全局单例，维护 server_id → TransportProtocol 的映射，
+前端通过 API 控制 start/stop/restart/status。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.integrations.mcp.transports.base import TransportProtocol
+from app.integrations.mcp.transports.http import StreamableHttpTransport
+
+logger = logging.getLogger(__name__)
+
+# 模块级全局实例（避免依赖 request.app.state）
+_default_instance: ProcessManager | None = None
+
+
+def get_process_manager() -> ProcessManager | None:
+    """返回默认的全局 ProcessManager 实例。"""
+    return _default_instance
+
+
+def set_process_manager(manager: ProcessManager) -> None:
+    """设置全局 ProcessManager 实例（由 lifespan 调用）。"""
+    global _default_instance
+    _default_instance = manager
+
+
+class ProcessManager:
+    """MCP 进程管理器（全局单例）。"""
+
+    def __init__(self) -> None:
+        self._transports: dict[str, TransportProtocol] = {}
+
+    def register_transport(self, server_id: str, transport: TransportProtocol) -> None:
+        """注册传输层实例（不自动 start）。"""
+        self._transports[server_id] = transport
+
+    def unregister(self, server_id: str) -> None:
+        """注销传输层实例（不自动 stop，调用方需先 stop）。"""
+        self._transports.pop(server_id, None)
+
+    def get(self, server_id: str) -> TransportProtocol | None:
+        return self._transports.get(server_id)
+
+    async def start(self, server_id: str) -> None:
+        transport = self._transports.get(server_id)
+        if transport is None:
+            raise ValueError(f"server {server_id} 未注册")
+        if isinstance(transport, StreamableHttpTransport):
+            raise ValueError("streamable-http 无需启动")
+        await transport.start()
+
+    async def stop(self, server_id: str) -> None:
+        transport = self._transports.get(server_id)
+        if transport is None:
+            raise ValueError(f"server {server_id} 未注册")
+        if isinstance(transport, StreamableHttpTransport):
+            raise ValueError("streamable-http 无需停止")
+        await transport.stop()
+
+    async def restart(self, server_id: str) -> None:
+        transport = self._transports.get(server_id)
+        if transport is None:
+            raise ValueError(f"server {server_id} 未注册")
+        if isinstance(transport, StreamableHttpTransport):
+            raise ValueError("streamable-http 无需重启")
+        await transport.restart()
+
+    async def status(self, server_id: str) -> dict[str, Any]:
+        transport = self._transports.get(server_id)
+        if transport is None:
+            return {
+                "server_id": server_id,
+                "name": "unknown",
+                "transport": "unknown",
+                "status": "unregistered",
+                "pid": None,
+                "uptime_seconds": None,
+            }
+        return await transport.get_status()
+
+    async def shutdown_all(self) -> None:
+        """停止所有 stdio 子进程（lifespan 关闭时调用）。"""
+        for sid, transport in list(self._transports.items()):
+            try:
+                await transport.stop()
+            except Exception:  # noqa: BLE001
+                logger.warning(
+                    "停止 MCP 进程失败",
+                    extra={"server_id": sid},
+                )
+        self._transports.clear()

backend/app/integrations/mcp/transports/__init__.py

@@ -0,0 +1,67 @@
+"""MCP 传输层工厂。
+
+根据 server 的 transport 字段创建对应的 TransportProtocol 实例。
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+from app.integrations.mcp.transports.base import TransportProtocol
+from app.integrations.mcp.transports.http import StreamableHttpTransport
+from app.integrations.mcp.transports.stdio import StdioTransport
+
+
+def get_transport(
+    server: Any,
+    http_client: httpx.AsyncClient | None = None,
+) -> TransportProtocol:
+    """根据 server 的 transport 字段创建传输层实例。"""
+    transport = server.transport if hasattr(server, "transport") else "streamable-http"
+
+    if transport == "stdio":
+        args: list[str] = []
+        if hasattr(server, "args_json") and server.args_json:
+            try:
+                parsed = json.loads(server.args_json)
+                if isinstance(parsed, list):
+                    args = [str(a) for a in parsed]
+            except (json.JSONDecodeError, TypeError):
+                pass
+
+        env: dict[str, str] | None = None
+        if hasattr(server, "env_json") and server.env_json:
+            try:
+                parsed = json.loads(server.env_json)
+                if isinstance(parsed, dict):
+                    env = {str(k): str(v) for k, v in parsed.items()}
+            except (json.JSONDecodeError, TypeError):
+                pass
+
+        cwd: str | None = None
+        if hasattr(server, "cwd") and server.cwd:
+            cwd = server.cwd
+
+        cmd = getattr(server, "command", None) or ""
+        return StdioTransport(
+            server_id=server.id,
+            server_name=server.name,
+            command=cmd,
+            args=args,
+            env=env,
+            cwd=cwd,
+        )
+
+    # 默认 streamable-http
+    endpoint_url = getattr(server, "endpoint_url", None) or ""
+    auth_token = getattr(server, "auth_token", None)
+    return StreamableHttpTransport(
+        server_id=server.id,
+        server_name=server.name,
+        endpoint_url=endpoint_url,
+        auth_token=auth_token,
+        http_client=http_client,
+    )

backend/app/integrations/mcp/transports/base.py

@@ -0,0 +1,57 @@
+"""TransportProtocol — MCP 传输层抽象接口。
+
+定义所有传输层（streamable-http / stdio）共有的 list_tools / call_tool / 生命周期方法。
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from app.modules.tool_runtime.definition import ToolResult
+
+
+class TransportProtocol(ABC):
+    """MCP 传输层协议接口。"""
+
+    server_id: str
+    server_name: str
+
+    @abstractmethod
+    async def list_tools(self) -> list[dict[str, Any]]:
+        """调用 tools/list，返回工具清单。"""
+        ...
+
+    @abstractmethod
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> ToolResult:
+        """调用 tools/call，返回 ToolResult。"""
+        ...
+
+    async def start(self) -> None:
+        """启动传输层（stdio 启子进程；HTTP no-op）。"""
+        return
+
+    async def stop(self) -> None:
+        """停止传输层（stdio 杀子进程；HTTP no-op）。"""
+        return
+
+    async def restart(self) -> None:
+        """重启传输层。"""
+        await self.stop()
+        await self.start()
+
+    @property
+    def is_running(self) -> bool:
+        """传输层是否正在运行。"""
+        return True
+
+    async def get_status(self) -> dict[str, Any]:
+        """返回当前状态信息。"""
+        return {
+            "server_id": self.server_id,
+            "name": self.server_name,
+            "transport": "unknown",
+            "status": "unknown",
+            "pid": None,
+            "uptime_seconds": None,
+        }

backend/app/integrations/mcp/transports/http.py

@@ -0,0 +1,111 @@
+"""Streamable HTTP 传输层实现。
+
+通过 HTTP POST /message 发送 JSON-RPC 2.0 请求的标准 MCP 传输协议。
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from app.core.config import settings
+from app.integrations.mcp.client import _auth_headers, _parse_call_result
+from app.integrations.mcp.transports.base import TransportProtocol
+from app.modules.tool_runtime.definition import ToolResult
+
+
+class StreamableHttpTransport(TransportProtocol):
+    """通过 HTTP POST /message 通信的 MCP 传输层。"""
+
+    def __init__(
+        self,
+        server_id: str,
+        server_name: str,
+        endpoint_url: str,
+        auth_token: str | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.server_id = server_id
+        self.server_name = server_name
+        self._endpoint_url = endpoint_url.rstrip("/")
+        self._auth_token = auth_token
+        self._http_client = http_client or httpx.AsyncClient(trust_env=False)
+        self._own_client = http_client is None
+        self._started_at: float | None = None
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        body = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tools/list",
+            "params": {},
+        }
+        try:
+            resp = await self._http_client.post(
+                self._endpoint_url,
+                json=body,
+                headers=_auth_headers(self._auth_token),
+                timeout=settings.mcp_list_timeout_seconds,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+        except (httpx.HTTPError, ValueError):
+            return []
+        result = data.get("result") if isinstance(data, dict) else None
+        if not result:
+            return []
+        return result.get("tools") if isinstance(result.get("tools"), list) else []
+
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> ToolResult:
+        body = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tools/call",
+            "params": {
+                "name": name,
+                "arguments": arguments,
+            },
+        }
+        try:
+            resp = await self._http_client.post(
+                self._endpoint_url,
+                json=body,
+                headers=_auth_headers(self._auth_token),
+                timeout=settings.mcp_call_timeout_seconds,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+        except (httpx.HTTPError, ValueError, TypeError) as exc:
+            return ToolResult(
+                ok=False,
+                stdout="",
+                stderr=str(exc),
+                duration_ms=0,
+                exit_code=None,
+                timeout=False,
+                truncated=False,
+                trace_id="",
+            )
+        return _parse_call_result(data)
+
+    async def start(self) -> None:
+        self._started_at = time.time()
+
+    @property
+    def is_running(self) -> bool:
+        return True
+
+    async def get_status(self) -> dict[str, Any]:
+        uptime = None
+        if self._started_at is not None:
+            uptime = time.time() - self._started_at
+        return {
+            "server_id": self.server_id,
+            "name": self.server_name,
+            "transport": "streamable-http",
+            "status": "running",
+            "pid": None,
+            "uptime_seconds": uptime,
+        }

backend/app/integrations/mcp/transports/stdio.py

@@ -0,0 +1,231 @@
+"""stdio 传输层实现。
+
+通过子进程 stdin/stdout 通信的标准 MCP 传输协议（本地 MCP 集成）。
+JSON-RPC 2.0 请求写入 stdin，从 stdout 读取响应，stderr 记日志。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import signal
+import time
+from typing import Any
+
+from app.core.config import settings
+from app.integrations.mcp.client import _parse_call_result
+from app.integrations.mcp.transports.base import TransportProtocol
+from app.modules.tool_runtime.definition import ToolResult
+
+logger = logging.getLogger(__name__)
+
+
+class StdioTransport(TransportProtocol):
+    """通过子进程 stdin/stdout 通信的 MCP 传输层。"""
+
+    def __init__(
+        self,
+        server_id: str,
+        server_name: str,
+        command: str,
+        args: list[str] | None = None,
+        env: dict[str, str] | None = None,
+        cwd: str | None = None,
+    ) -> None:
+        self.server_id = server_id
+        self.server_name = server_name
+        self._command = command
+        self._args = args or []
+        self._env = env
+        self._cwd = cwd
+        self._process: asyncio.subprocess.Process | None = None
+        self._request_id = 0
+        self._started_at: float | None = None
+        self._lock = asyncio.Lock()
+
+    async def start(self) -> None:
+        if self._process is not None and self._process.returncode is None:
+            return  # already running
+
+        resolved_env = os.environ.copy()
+        if self._env:
+            resolved_env.update(self._env)
+
+        self._process = await asyncio.create_subprocess_exec(
+            self._command,
+            *self._args,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=resolved_env,
+            cwd=self._cwd,
+        )
+        self._started_at = time.time()
+        logger.info(
+            "stdio MCP 子进程已启动",
+            extra={
+                "server_id": self.server_id,
+                "server_name": self.server_name,
+                "pid": self._process.pid,
+            },
+        )
+
+        # 后台读取 stderr，记日志
+        asyncio.create_task(self._read_stderr())
+
+    async def stop(self) -> None:
+        proc = self._process
+        if proc is None or proc.returncode is not None:
+            self._process = None
+            self._started_at = None
+            return
+
+        logger.info(
+            "停止 stdio MCP 子进程",
+            extra={
+                "server_id": self.server_id,
+                "pid": proc.pid,
+            },
+        )
+        try:
+            proc.send_signal(signal.SIGTERM)
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=settings.mcp_stdio_stop_timeout_seconds)
+            except TimeoutError:
+                proc.send_signal(signal.SIGKILL)
+                await proc.wait()
+        except ProcessLookupError:
+            pass
+        self._process = None
+        self._started_at = None
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        result = await self._send_request("tools/list", {})
+        if result is None:
+            return []
+        return result.get("tools") if isinstance(result.get("tools"), list) else []
+
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> ToolResult:
+        result = await self._send_request(
+            "tools/call",
+            {"name": name, "arguments": arguments},
+        )
+        if result is None:
+            return ToolResult(
+                ok=False,
+                stdout="",
+                stderr="stdio 子进程无响应",
+                duration_ms=0,
+                exit_code=1,
+                timeout=False,
+                truncated=False,
+                trace_id="",
+            )
+        return _parse_call_result({"result": result})
+
+    async def restart(self) -> None:
+        await self.stop()
+        await self.start()
+
+    @property
+    def is_running(self) -> bool:
+        return (
+            self._process is not None
+            and self._process.returncode is None
+            and self._process.stdin is not None
+        )
+
+    async def get_status(self) -> dict[str, Any]:
+        running = self.is_running
+        uptime = None
+        if running and self._started_at is not None:
+            uptime = time.time() - self._started_at
+        return {
+            "server_id": self.server_id,
+            "name": self.server_name,
+            "transport": "stdio",
+            "status": "running" if running else "stopped",
+            "pid": self._process.pid if self._process else None,
+            "uptime_seconds": uptime,
+        }
+
+    async def _send_request(self, method: str, params: dict[str, Any]) -> dict[str, Any] | None:
+        async with self._lock:
+            self._request_id += 1
+            req_id = self._request_id
+
+        proc = self._process
+        if proc is None or proc.stdin is None or proc.stdout is None:
+            return None
+
+        request = {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "method": method,
+            "params": params,
+        }
+        line = (json.dumps(request) + "\n").encode("utf-8")
+
+        try:
+            proc.stdin.write(line)
+            await asyncio.wait_for(
+                proc.stdin.drain(),
+                timeout=settings.mcp_stdio_call_timeout_seconds,
+            )
+
+            response_line = await asyncio.wait_for(
+                proc.stdout.readline(),
+                timeout=settings.mcp_stdio_call_timeout_seconds,
+            )
+            if not response_line:
+                return None
+
+            data = json.loads(response_line.decode("utf-8"))
+        except (TimeoutError, json.JSONDecodeError, OSError) as exc:
+            logger.warning(
+                "stdio MCP 请求失败",
+                extra={
+                    "server_id": self.server_id,
+                    "method": method,
+                    "error": str(exc),
+                },
+            )
+            return None
+
+        if isinstance(data, dict) and data.get("error"):
+            logger.warning(
+                "stdio MCP 返回 JSON-RPC 错误",
+                extra={
+                    "server_id": self.server_id,
+                    "method": method,
+                    "error": data["error"],
+                },
+            )
+            return None
+
+        return data.get("result") if isinstance(data, dict) else None
+
+    async def _read_stderr(self) -> None:
+        proc = self._process
+        if proc is None or proc.stderr is None:
+            return
+        try:
+            while True:
+                line = await proc.stderr.readline()
+                if not line:
+                    break
+                text = line.decode("utf-8", errors="replace").rstrip()
+                if text:
+                    logger.info(
+                        "[stdio %s] %s",
+                        self.server_name,
+                        text,
+                        extra={
+                            "server_id": self.server_id,
+                            "server_name": self.server_name,
+                        },
+                    )
+        except Exception:  # noqa: BLE001
+            pass