bixiu-mcp

基于 MCP (Model Context Protocol) 的多类型 MCP 服务器。支持五种 MCP 实例，每种独立加载自己的工具集。

端口分配

端口	类型	工具数	说明
9191	all	26	全部工具（terminal + codex + git）
9192	codex	13	代码开发（旧版，待切换）
9193	old	8	传统工具集（bixiu_talk 等）

架构

一个进程只服务一种 MCP 类型，由 MCP_TYPE 环境变量或 --type 参数指定。

MCPType:
  TERMINAL → tools/terminal/  (5 个工具)
  CODEX    → tools/codex/     (13 个工具)
  GIT      → tools/git/       (8 个工具)
  ALL      → 全部三个目录     (26 个工具)
  OLD      → tools/old/       (8 个传统工具)

快速安装

# editable 模式安装（开发用）
pip install -e .

# 安装 wheel
pip install dist/bixiu_mcp-0.7.0-py3-none-any.whl

CLI

bx-mcp start --type all --port 9191    # ALL 模式（26 工具）
bx-mcp start --type old --port 9193    # OLD 模式（8 传统工具）
bx-mcp start --type all                 # 开三个端口（9191/9192/9193）
bx-mcp start --type codex               # Codex 模式（默认 9192）
bx-mcp start --stdio --type codex       # stdio 模式（IDE 内嵌用）
bx-mcp status                           # 查看各端口运行状态

传输协议

同时支持 SSE（HTTP）和 stdio 两种传输方式：

SSE:   GET  /sse  → 建立连接，获取 session_id
       POST /    → 发送 JSON-RPC 请求

stdio: stdin/stdout 逐行 JSON-RPC 消息

匿名 session 兼容：SSE 模式下 POST 请求自动创建匿名 session，无需先 GET /sse。

鉴权

支持两种鉴权方式，通过 MCP_AUTH_METHOD 环境变量控制。

Forgejo 模式（推荐）

export MCP_AUTH_METHOD=forgejo
export MCP_FORGEJO_SERVER=https://git.bx.wedata.club

客户端使用 Forgejo Personal Access Token 作为 api_key。鉴权只发生在 initialize 阶段，后续请求复用 Session 的认证状态。

Continue 集成配置：

- name: bixiu-mcp
  transport: streamable-http
  url: "http://localhost:9192"
  requestOptions:
    headers:
      Authorization: "Bearer <your-forgejo-token>"

ApiKeyStore 模式（传统）

使用内部管理的 API Key 列表：

export MCP_REQUIRE_AUTH=0      # 0=本地免密钥(默认), 1=严格, 2=按域

测试

使用 pytest + aiohttp 测试工具，FakeForgejo 模拟 Forgejo API，不依赖真实网络：

python3 -m pytest test/test_auth_flow.py -v

测试覆盖三个核心场景：

• test_auth_pass — 合法 Token → initialize 通过
• test_auth_fail — 无 Token → 返回 32001 错误
• test_auth_once — 鉴权仅发生在 initialize，后续请求不复用鉴权

Continue 集成配置

# .continue/mcpServers/bixiu-mcp.yaml
name: bixiu-mcp
schema: v1
mcpServers:
  # SSE 模式（无鉴权）
  - name: Bixiu ALL
    transport: sse
    url: "http://localhost:9191"

  # Streamable HTTP 模式（Forgejo 鉴权）
  - name: Bixiu CODEX
    transport: streamable-http
    url: "http://localhost:9192"
    requestOptions:
      headers:
        Authorization: "Bearer <your-forgejo-token>"

  # SSE 模式（旧）
  - name: Bixiu OLD
    transport: sse
    url: "http://localhost:9193"

stdio 模式：

  - name: Bixiu Stdio
    transport: stdio
    command: python3
    args:
      - -m
      - mcp_server.stdio_terminal_server
    env:
      MCP_TYPE: all
      MCP_WORK_DIR: /path/to/your/project

目录结构

src/mcp_server/
├── session.py              Session 管理器（持有工具注册表 + work_dir + mcp_type）
├── core.py                 纯 JSON-RPC 路由（~60 行）
├── cli.py                  bx-mcp CLI 入口
├── stdio_terminal_server.py  stdio 传输服务
├── ipc_terminal_server.py    SSE 传输服务（多 Session 并发 + 匿名 session 兼容）
├── tools/
│   ├── terminal/           5 个工具（run_terminal_command 等终端命令）
│   ├── codex/              13 个工具（read_file, write_file, grep_search 等）
│   ├── git/                8 个工具（status, diff, commit 等）
│   └── old/                8 个传统工具（bixiu_talk, fetch_url 等）

添加新工具

在对应类型目录下创建 .py 文件，定义 TOOL_DEFINITION 和 handle() 即可自动发现：

# tools/codex/my_tool.py
TOOL_DEFINITION = {
    "name": "my_tool",
    "description": "工具描述",
    "inputSchema": {
        "type": "object",
        "properties": {
            "param1": {"type": "string", "description": "参数说明"}
        },
        "required": ["param1"]
    }
}

def handle(req_id, arguments, work_dir=None):
    return {
        "jsonrpc": "2.0", "id": req_id,
        "result": {"content": [{"type": "text", "text": "结果"}]}
    }

环境变量

变量	说明	默认
MCP_TYPE	MCP 类型（terminal / codex / git / all / old）	codex
MCP_WORK_DIR	工作目录	当前目录
MCP_LOG_LEVEL	日志级别	INFO

systemd 服务

systemctl --user start mcp-terminal.service     # 9191 ALL 模式
systemctl --user start mcp-terminal-ikd.service # 9193 OLD 模式
systemctl --user status mcp-terminal.service    # 查看状态
journalctl --user -u mcp-terminal -f            # 查看日志

项目状态

main ← 当前开发分支（v1 架构）

历史版本：

• v0_8_pre — 旧架构（单进程多域合并），保留作为历史参考