OpenSquilla MCP Gateway

OpenSquilla MCP Gateway 是一个双向 Model Context Protocol 网关：

• 入站 MCP Server：通过 FastMCP + stdio 把 OpenSquilla 会话能力暴露给 MCP Host。
• 出站 MCP Client：连接外部 stdio 或 HTTP+SSE MCP Server，发现工具并注册到统一工具表。
• Gateway Bridge：把 MCP tool/resource 请求转换为 OpenSquilla Gateway WebSocket RPC。

本仓库包含可安装源码和测试，不包含 OpenSquilla Electron 桌面端、完整 Agent Runtime、模型配置或任何本机凭据。代码从 OpenSquilla v0.5.2 的 MCP 模块独立整理，Python import namespace 调整为 opensquilla_mcp_gateway。

架构

flowchart LR
    Host["MCP Host"]
    External["External MCP Server"]

    subgraph Package["opensquilla_mcp_gateway"]
        Server["FastMCP stdio server"]
        Bridge["OpenSquillaMCPBridge"]
        RPC["GatewayRPCClient"]
        Discovery["MCP discovery"]
        Registry["ToolRegistry"]
        Stdio["MCPStdioClient"]
        SSE["MCPSSEClient"]
    end

    Gateway["OpenSquilla Gateway<br/>WebSocket RPC"]
    Agent["Agent Runtime"]

    Host -->|"MCP JSON-RPC over stdio"| Server
    Server --> Bridge
    Bridge --> RPC
    RPC --> Gateway

    Agent --> Registry
    Registry --> Discovery
    Discovery --> Stdio
    Discovery --> SSE
    Stdio --> External
    SSE --> External

代码结构

src/opensquilla_mcp_gateway/
├── server.py          # FastMCP tools 和 resources
├── bridge.py          # MCP -> Gateway 会话工作流适配
├── gateway_client.py  # WebSocket RPC client、事件队列与 heartbeat
├── client.py          # 出站 MCPClient 抽象接口
├── stdio.py           # 出站 stdio transport
├── sse.py             # 出站 HTTP+SSE transport
├── discovery.py       # tools/list、ToolSpec 转换与 client 生命周期
├── registry.py        # 独立包使用的最小 ToolRegistry
├── types.py           # MCP 配置、工具和结果类型
├── env.py             # HTTPX 环境代理开关
├── cli.py             # opensquilla-mcp-gateway run
└── __main__.py        # python -m opensquilla_mcp_gateway

tests/
├── test_protocol_smoke.py
├── test_stdio_client.py
├── test_sse_client.py
├── test_discovery_lifecycle.py
├── test_gateway_client.py
├── test_bridge.py
├── test_server.py
└── test_cli.py

环境要求

• Python 3.12+
• 一个正在运行、可通过 WebSocket 访问的 OpenSquilla Gateway
• MCP Python SDK >=1.27,<2

SDK 2.0 调整了 FastMCP 导入路径和部分客户端 API，本仓库先固定已验证的 1.x 兼容范围。

安装

Windows PowerShell

git clone https://github.com/nhtqgm/opensquilla-mcp-gateway.git
Set-Location opensquilla-mcp-gateway
py -3.12 -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[dev]"

Linux/macOS

git clone https://github.com/nhtqgm/opensquilla-mcp-gateway.git
cd opensquilla-mcp-gateway
python3.12 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

作为 MCP Server 运行

先确认 OpenSquilla Gateway 已经启动，并监听本地 WebSocket，例如：

ws://127.0.0.1:18791/ws

启动 stdio MCP Server：

.venv\Scripts\opensquilla-mcp-gateway.exe run `
  --gateway ws://127.0.0.1:18791/ws

也可以通过 Python module 运行：

.venv\Scripts\python.exe -m opensquilla_mcp_gateway run `
  --gateway ws://127.0.0.1:18791/ws

--gateway 也可以通过环境变量设置：

$env:OPENSQUILLA_GATEWAY_URL = "ws://127.0.0.1:18791/ws"
.venv\Scripts\opensquilla-mcp-gateway.exe run

MCP Host 配置

把 command 改成该虚拟环境中 Python 的绝对路径：

{
  "mcpServers": {
    "opensquilla": {
      "command": "C:\\path\\to\\repo\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "opensquilla_mcp_gateway",
        "run",
        "--gateway",
        "ws://127.0.0.1:18791/ws"
      ]
    }
  }
}

stdio 是协议通道，业务日志不能写入 stdout；需要记录日志时应写入 stderr。

入站 Tools

Tool	参数	Gateway 行为
conversations_list	limit=50	调用 sessions.list
session_resolve	key	调用 sessions.resolve
messages_read	key, limit=1000	调用 chat.history
messages_send	key, message, intent=continue	先订阅，再调用 sessions.send
events_wait	key, since_stream_seq, timeout_ms, max_events, terminal_only	订阅实时/回放事件并返回最新游标
transcript_export	key, limit=1000	将消息和工具执行证据导出为 JSONL

messages_send 先建立 sessions.messages.subscribe，再发送消息，避免执行很快的任务在订阅完成前已经发出终态事件。

events_wait 识别以下终态：

session.event.done
session.event.error
task.cancelled
task.failed
task.timeout
task.abandoned

Resources

类型	URI
Resource	opensquilla://sessions
Template	opensquilla://sessions/{key}
Template	opensquilla://sessions/{key}/messages
Template	opensquilla://sessions/{key}/transcript.jsonl

作为 MCP Client 接入外部工具

stdio Server

import asyncio

from opensquilla_mcp_gateway.discovery import (
    close_active_clients,
    discover_and_register,
)
from opensquilla_mcp_gateway.registry import ToolRegistry
from opensquilla_mcp_gateway.types import MCPServerConfig


async def main() -> None:
    registry = ToolRegistry()
    config = MCPServerConfig(
        name="filesystem",
        transport="stdio",
        command="npx",
        args=["-y", "@modelcontextprotocol/server-filesystem", "."],
        tool_timeout_seconds=30,
    )

    try:
        names = await discover_and_register(config, registry)
        print(names)
    finally:
        await close_active_clients()


asyncio.run(main())

HTTP+SSE Server

config = MCPServerConfig(
    name="remote",
    transport="sse",
    url="http://127.0.0.1:8000/sse",
    tool_timeout_seconds=30,
)

当前 SSE 实现针对 MCP 2024-11-05 的 endpoint-event transport。新的远端部署应优先考虑 Streamable HTTP；本仓库尚未实现该 transport。

Transport 实现

stdio

• 使用 UTF-8、单行、LF 结尾的 JSON-RPC framing。
• 发送 initialize 后再发送 notifications/initialized。
• 一个请求锁覆盖“写请求 + 等待匹配 response”的完整周期，避免并发 reader 读走彼此响应。
• 跳过非法 UTF-8、非 JSON、notification 和不匹配 id 的消息。
• 关闭时先 terminate，2 秒后仍未退出则 kill，并等待子进程回收。

HTTP+SSE

• 先打开长连接 GET stream。
• 从 endpoint event 获取会话级 POST URL。
• endpoint 必须与初始 SSE URL 同源，包括 scheme、hostname 和规范化端口。
• request id 映射到 Future，由后台 SSE reader 分发 response。
• tool timeout 控制等待时间，关闭时取消 reader 并使所有 pending Future 失败。

错误语义

出站 Client 同时处理：

• JSON-RPC 顶层 error
• tools/call result 中的 isError=true
• 工具调用超时

这些错误会转换为 SafeToolError，不会作为普通成功字符串注册到工具系统。

测试

.venv\Scripts\python.exe -m ruff check src tests
.venv\Scripts\python.exe -m pytest -q

协议冒烟测试会启动一个临时 FastMCP stdio Server，并通过官方 MCP Client 完成：

1. initialize
2. tools/list
3. tools/call
4. resources/list
5. resources/templates/list
6. resources/read

其他测试覆盖 stdio framing/并发/进程清理、SSE endpoint 同源校验、工具发现生命周期、Gateway request/Future 配对、事件游标和 JSONL 工具证据。

当前本地基线：

33 passed（MCP Python SDK 1.29.0）

安全边界

• Gateway 默认应只绑定 127.0.0.1；对外部署需要单独的认证、TLS 和网络边界。
• 不要把 API key、token 或密码写入仓库或命令行参数。
• OPENSQUILLA_TRUST_ENV 默认关闭；只有明确需要继承 HTTPX proxy/TLS 环境时才设置为 1。
• stdio 外部 Server 配置了 env 时，当前实现会继承父进程环境后再覆盖指定变量；高隔离环境应改为 allowlist。
• SSE endpoint 同源校验只限制重定向来源，不能替代服务端身份认证。
• JSONL transcript 可能包含会话文本、工具参数和结果，分享前必须脱敏。

当前限制

• 出站 tool result 只聚合 MCP text content，图片和 resource content 尚未保留。
• 发现工具注册为 mcp_{tool_name}；多个 Server 的同名工具可能覆盖。
• SSE 配置还没有通用认证 headers。
• 尚未支持 Streamable HTTP。
• stdio Client 为保证响应正确性，对同一 Server 的请求进行串行化。
• 本仓库只提供 MCP Gateway，不包含完整 OpenSquilla Gateway 服务端实现。

版本对应关系

项目	版本
本独立包	0.1.0
对应 OpenSquilla 源码	v0.5.2 / 0624e20
已验证 MCP Python SDK	1.27.0、1.29.0
出站初始化协议	2024-11-05

入站 FastMCP Server 的协议版本由 MCP Host 与 SDK 协商；serverInfo.version 是 SDK/Server 实现版本，不是 OpenSquilla 产品版本。

来源与许可证

本仓库代码基于 OpenSquilla v0.5.2 MCP 相关模块整理：

• 上游仓库：opensquilla/opensquilla
• 固定提交：0624e20cf6aae4eb818211092956d3a1d611e97e
• 上游许可证：Apache License 2.0

本仓库继续使用 Apache License 2.0。完整作者与贡献记录以上游 Git 历史为准。