git clone https://github.com/chain-engine/x-QiuChi.git
cd x-QiuChi

# 安装项目依赖（含开发依赖：pytest/ruff/mypy）
uv sync --all-extras

# 方式一（推荐）：基于 .env.example 创建环境变量文件
cp .env.example .env

# 方式二：基于 config.yaml.example 创建 YAML 配置文件
cp config.yaml.example config.yaml

# 默认启动 streamable-http（端口 8888）
uv run x-QiuChi

# 等价写法（等价于 python -m src.main）
uv run python -m src.main

# 自定义启动参数
uv run x-QiuChi --transport stdio          # 切换为标准输入输出传输
uv run x-QiuChi --port 8080                # 更换 HTTP 端口
uv run x-QiuChi --log-level DEBUG          # 调整日志级别

# 一键构建并启动（端口 8888，日志挂载卷，自动健康检查）
docker compose up -d --build

# 查看运行状态与日志
docker compose ps
docker compose logs -f qiuchi-mcp

# 停止
docker compose down

# 单元测试（含覆盖率统计，覆盖率门禁 45%）
uv run pytest

# 代码格式化（自动修复）
uv run ruff format src/ tests/
uv run ruff check --fix src/ tests/

# 静态检查
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

# 类型检查
uv run mypy src/

# 构建发行包（wheel + sdist）
uv build

# 依赖漏洞扫描
uv pip audit

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main() -> None:
    server_params = StdioServerParameters(
        command="uv", args=["run", "x-QiuChi", "--transport", "stdio"]
    )
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            result = await session.call_tool("add", {"a": 1, "b": 2})
            print(result)

asyncio.run(main())

{
  "mcpServers": {
    "qiuchi": {
      "command": "uv",
      "args": ["run", "x-QiuChi", "--transport", "stdio"]
    }
  }
}

from langchain_mcp_adapters.client import MultiServerMCPClient

async with MultiServerMCPClient(
    {"qiuchi": {"transport": "http", "url": "http://localhost:8888/mcp"}}
) as client:
    tools = client.get_tools()

x-QiuChi/
├── src/                              # 源码根目录
│   ├── main.py                       # 入口：CLI 解析、配置装配、服务器启动
│   ├── constants/                    # 常量层：全局枚举与基础常量
│   │   ├── enums.py                  # Environment / LogLevel / TransportType / PluginType 等枚举
│   │   ├── constants.py              # 版本、作者、描述等全局常量
│   │   └── base.py                   # 通用基础常量定义
│   ├── core/                         # 核心层：框架基础设施
│   │   ├── config.py                 # Settings 配置管理（dataclass 分节、env>yaml>默认值、校验）
│   │   ├── logger.py                 # loguru 结构化日志（文件轮转、敏感字段过滤）
│   │   ├── middleware.py             # 中间件管道（ErrorHandler / Logging / MiddlewareChain / RequestContext）
│   │   └── auth.py                   # 传输层认证（Bearer Token 验证器，MCP TokenVerifier Protocol）
│   ├── plugins/                      # 插件层：插件系统核心 + 内建扩展
│   │   ├── discovery.py              # PluginDiscovery：扫描 discovery_paths，import 触发装饰器收集
│   │   ├── collector.py              # PluginCollector：进程级全局收集器 + 三大装饰器
│   │   ├── registry.py               # PluginRegistry：统一注册表（工具/资源/提示词 + 元数据）
│   │   ├── manager.py                # PluginManager：门面，编排「发现 → 收集 → 注册」
│   │   └── builtin/                  # 内建扩展插件（discovery 唯一扫描区）
│   │       ├── tools/math.py         # 5 个数学工具（add/subtract/multiply/divide/sqrt）
│   │       ├── resources/config.py   # 3 个配置资源（config://server、config://version、docs://api）
│   │       └── prompts/templates.py  # 4 个提示词模板（greeting/code_review/weather/summarize）
│   ├── adapters/                     # 适配器层：外部系统集成（HTTP 转接代理）
│   │   └── hanjiang/                 # 汉江管理系统适配器（认证 + 用户管理，10 个工具）
│   │       ├── client.py             # HanJiangClient：RSA-OAEP 登录 / token 生命周期 / 错误映射
│   │       ├── auth_tools.py         # 认证域工具（login / logout / session_info）
│   │       └── user_tools.py         # 用户域工具（create / list / get / update / status / reset / delete）
│   ├── server/                       # 服务层：MCP 服务器核心
│   │   ├── server.py                 # MCPServer 编排门面（组装 FastMCP / 认证 / 中间件 / 插件 / 生命周期）
│   │   └── lifecycle.py              # 服务器生命周期状态机（UNINITIALIZED → RUNNING → STOPPED）
│   ├── transport/                    # 传输层：多协议传输抽象
│   │   └── transport.py              # 传输配置、request_id 注入（X-Request-ID / ContextVar）与服务承载
│   └── utils/                        # 工具层：通用辅助函数
│       └── helpers.py                # 通用帮助函数（时间格式化等）
├── tests/                            # 测试套件（11 个测试模块，110+ 用例）
├── examples/                         # 示例代码
│   ├── mcp_clients/                  # MCP 客户端接入示例（官方 SDK / LangChain）
│   └── mcp_servers/                  # 独立 MCP 服务器示例（天气）
├── .github/workflows/ci.yml          # GitHub Actions CI（lint / mypy / test / build）
├── hooks/                            # git hooks（pre-commit / commit-msg 规范检查）
├── scripts/                          # 工程脚本（提交信息检查等）
├── config.yaml / config.yaml.example # YAML 配置（示例）
├── .env / .env.example               # 环境变量配置（示例）
├── Dockerfile                        # 多阶段构建（非 root、健康检查）
├── docker-compose.yml                # 容器编排
├── pyproject.toml                    # 项目元数据 / 依赖 / 工具配置（uv/ruff/mypy/pytest）
└── LICENSE                           # MIT 开源协议

flowchart TD
    A["MCP 客户端<br/>（Claude Desktop / LangChain / 自研 Agent）"]
    B["传输层 transport<br/>stdio / SSE / Streamable-HTTP（默认）"]
    B1["传输加固（HTTP 模式）<br/>Bearer Token 认证 + request_id 注入"]
    C["中间件管道 core.middleware<br/>ErrorHandler → Logging → 业务处理"]
    D["MCP 三大原语（PluginType）"]
    E["插件系统 plugins<br/>发现 → 收集 → 注册"]
    F["插件注册表 PluginRegistry<br/>（线程安全，RLock）"]
    G["MCPServer 编排门面 server<br/>组装 FastMCP + 生命周期状态机"]
    H["核心基础设施 core<br/>配置 / 日志 / 中间件 / 认证"]
    I["常量层 constants<br/>TransportType / PluginType 等枚举"]
    J["适配器层 adapters<br/>HanJiang 转接代理（HTTP → MCP 工具）"]

    A -->|"MCP 协议（JSON-RPC 2.0）"| B
    B --> B1
    B1 --> C
    C --> D
    E -->|"注册"| D
    E --> F
    G -->|"编排"| E
    G --> H
    H --> I
    J -->|"以工具形式注册"| D

flowchart TD
    S1["解析 CLI 参数 / 加载配置<br/>（main.py + Settings，env > yaml > 默认值）"]
    S2["创建 MCPServer 实例<br/>组装 FastMCP / 传输认证 / 默认中间件"]
    S3["生命周期状态机<br/>UNINITIALIZED → READY → RUNNING"]
    S4["插件初始化（PluginManager）<br/>发现 → 收集 → 注册"]
    S5["装饰器函数注册<br/>包裹中间件管道，写入 PluginRegistry + FastMCP"]
    S6["serve_mcp 阻塞监听<br/>Streamable-HTTP（默认）/ SSE / Stdio"]

    S1 --> S2 --> S3 --> S4 --> S5 --> S6

flowchart TD
    R1["接收 MCP 请求（JSON-RPC）"]
    R2["HTTP 传输层<br/>Bearer Token 认证 + request_id 注入"]
    R3["FastMCP 按方法分发<br/>tools/call → 对应工具"]
    R4["中间件管道<br/>ErrorHandler → Logging（敏感字段脱敏）"]
    R5["执行业务函数<br/>（RequestContext 贯穿管道）"]
    R6["返回 MCP 响应"]

    R1 --> R2 --> R3 --> R4 --> R5 --> R6

flowchart LR
    P1["① 发现<br/>PluginDiscovery 扫描 discovery_paths"]
    P2["② 收集<br/>模块 import 时装饰器副作用写入 PluginCollector"]
    P3["③ 注册<br/>PluginManager 读取 Collector，注册进 Registry + FastMCP"]
    P4["④ 调用<br/>MCP 客户端 → wrapper → 中间件管道 → 原函数"]

    P1 --> P2 --> P3 --> P4