# 安装 uv（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或使用 pip 安装
pip install uv

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用 pip
pip install uv

# 使用 Homebrew 安装
brew install uv

# 或使用官方安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用 pip
pip install uv

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

# 使用 uv 同步依赖（推荐）
uv sync

# 开发模式（包含测试、格式化、类型检查等工具）
uv sync --extra dev

# 复制配置文件
cp config.yaml.example config.yaml

# HTTP 模式（默认，端口 8000）
uv run x-QiuChi

# Stdio 模式（兼容 Claude Desktop）
uv run x-QiuChi --transport stdio

# 自定义参数
uv run x-QiuChi --host 127.0.0.1 --port 8080 --log-level DEBUG

# 查看帮助
uv run x-QiuChi --help

# HTTP 模式（默认，端口 8000）
uv run python src/main.py

# Stdio 模式（兼容 Claude Desktop）
uv run python src/main.py --transport stdio

# 自定义参数
uv run python src/main.py --host 127.0.0.1 --port 8080 --log-level DEBUG

# 构建并启动
docker compose up -d --build

# 查看日志
docker compose logs -f

# 停止
docker compose down

# 运行全部测试
uv run pytest

# 运行指定测试文件（详细输出）
uv run pytest tests/test_integration.py -v

# 测试覆盖率报告
uv run pytest --cov=src tests/

# 代码格式化
uv run ruff format src/

# 代码静态检查
uv run ruff check src/

# 自动修复可修复的 lint 问题
uv run ruff check --fix src/

# 类型检查
uv run mypy src/

# MCP Inspector 验证
npx @anthropic-ai/mcp-inspector
# 连接地址: http://localhost:8000/mcp

from main import create_server, tool, resource, prompt

server = create_server("MyServer")

# 注册工具
@tool(category="math")
def add(a: float, b: float) -> float:
    """两数相加"""
    return a + b

# 注册资源
@resource(name="config://app", category="config")
def get_app_config() -> str:
    """获取应用配置"""
    return '{"version": "1.0.0"}'

# 注册提示词
@prompt(category="code")
def code_review(language: str) -> str:
    """生成代码审查提示词"""
    return f"请审查以下 {language} 代码的最佳实践。"

server.run()

import httpx

# 获取 Session ID
resp = httpx.get("http://localhost:8000/mcp",
                 headers={"Accept": "text/event-stream"})
session_id = resp.headers.get("mcp-session-id")

# 调用工具
resp = httpx.post(
    "http://localhost:8000/mcp",
    json={"jsonrpc": "2.0", "method": "tools/call",
          "params": {"name": "add", "arguments": {"a": 10, "b": 20}},
          "id": 1},
    headers={"Content-Type": "application/json",
             "mcp-session-id": session_id}
)
print(resp.json())  # {"result": {"content": [{"text": "30.0"}]}}

from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.chat_models import init_chat_model
from langgraph.prebuilt import create_react_agent

client = MultiServerMCPClient({
    "qiuchi_mcp": {
        "transport": "http",
        "url": "http://localhost:8000/mcp",
    }
})

tools = await client.get_tools()
model = init_chat_model("openai:gpt-4o-mini")
agent = create_react_agent(model, tools)

response = await agent.ainvoke({"messages": "计算 123 + 456"})
print(response['messages'][-1].content)

x-QiuChi/
├── config.yaml                      # 运行时配置文件
├── config.yaml.example              # 配置示例（含全部字段说明）
├── pyproject.toml                   # 包配置、依赖声明、工具链设置
├── Dockerfile                       # 多阶段构建镜像定义
├── docker-compose.yml               # 容器编排配置
├── LICENSE                          # MIT 开源许可证
│
├── src/                             # 源码根目录
│   ├── main.py                      # 主入口：CLI 参数解析与服务器启动
│   │
│   ├── constants/                   # 常量定义层
│   │   ├── base.py                  # 基础常量
│   │   ├── constants.py             # 业务常量
│   │   └── enums.py                 # 枚举类型定义
│   │
│   ├── core/                        # 核心层：框架基础设施
│   │   ├── config.py                # Pydantic Settings 配置管理（多源优先级、热重载）
│   │   ├── exceptions.py            # 自定义异常体系
│   │   ├── logger.py                # loguru 结构化日志封装（文件轮转、敏感信息过滤）
│   │   └── middleware.py            # 中间件管道（ErrorHandler / Logging / Auth / Cache）
│   │
│   ├── plugins/                     # 插件层：插件系统核心
│   │   ├── base.py                  # 插件抽象基类与元数据定义（PluginType / PluginMetadata）
│   │   ├── registry.py              # UnifiedRegistry 统一注册表（线程安全）
│   │   ├── manager.py               # PluginManager 插件管理器（自动发现、依赖解析、生命周期）
│   │   ├── discovery.py             # 插件发现扫描器
│   │   ├── loader.py                # 插件加载器
│   │   └── collector.py             # 插件收集器（装饰器注册入口）
│   │
│   ├── server/                      # 服务层：MCP 服务器核心
│   │   ├── server.py                # MCPServer 类（封装 FastMCP，装饰器注册，中间件集成）
│   │   └── lifecycle.py             # 服务器生命周期状态机（UNINITIALIZED → RUNNING → STOPPED）
│   │
│   ├── runtime/                     # 运行时层：请求上下文与会话管理
│   │   ├── context.py               # RequestContext 请求上下文
│   │   └── session.py               # SessionManager 会话管理器
│   │
│   ├── transport/                   # 传输层：多协议传输抽象
│   │   └── transport.py             # 传输层配置（Stdio / SSE / Streamable-HTTP / TLS）
│   │
│   ├── utils/                       # 工具层：通用辅助函数
│   │   └── helpers.py               # 工具函数集合
│   │
│   └── examples/                    # 示例层：内置示例插件
│       ├── tools/
│       │   └── math.py              # 8 个数学工具（加减乘除、幂、开方、温度转换）
│       ├── resources/
│       │   └── config.py            # 3 个配置资源（server config / version / API docs）
│       └── prompts/
│           └── templates.py         # 5 个提示词模板（问候、代码审查、天气穿搭等）
│
├── examples/                        # 外部示例代码
│   ├── mcp_clients/
│   │   ├── mcp_client.py            # 原生 JSON-RPC MCP 客户端示例
│   │   └── langchain_mcp_client.py  # LangChain MCP 集成示例
│   └── mcp_servers/
│       └── weather_mcp_server.py    # OpenWeatherMap 天气 MCP 服务示例
│
├── tests/                           # 测试目录
│   └── test_integration.py          # 7 步集成测试套件
│
├── docs/                            # 文档目录
├── scripts/                         # 脚本工具目录
├── static/                          # 静态资源目录
├── logs/                            # 日志输出目录（运行时生成）
└── tmp/                             # 临时文件目录

flowchart TD
    A["MCP 客户端<br/>(Claude Desktop / LangChain / 自定义客户端)"]
    B["传输层<br/>Stdio / SSE / Streamable-HTTP"]
    C["中间件管道<br/>ErrorHandler → Logging → Auth → Cache → Handler"]
    subgraph D["MCP 三大原语"]
        direction LR
        D1["Tools（工具原语）"]
        D2["Resources（资源原语）"]
        D3["Prompts（提示词原语）"]
    end
    E["插件系统<br/>Discovery → Load → Register → Enable → Serve"]
    F["统一注册表（线程安全）"]
    G["核心服务器<br/>MCPServer（封装 FastMCP）+ 生命周期管理"]
    H["配置管理<br/>Pydantic Settings（环境变量 > YAML > 默认值）"]
    I["结构化日志<br/>loguru（stderr + 文件轮转）"]

    A -->|"MCP 协议（JSON-RPC）"| B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I

flowchart TD
    S1["解析 CLI 参数 / 加载配置"] --> S2["创建 MCPServer 实例"]
    S2 --> S3["注册默认中间件管道<br/>ErrorHandler / Logging / Auth（可选） / Cache（可选）"]
    S3 --> S4["扫描 discovery_paths<br/>自动发现并加载插件"]
    S4 --> S5["注册到 UnifiedRegistry<br/>（Tools / Resources / Prompts）"]
    S5 --> S6["启动传输层监听<br/>（Stdio / SSE / HTTP）"]
    S6 --> S7["状态：RUNNING"]

flowchart TD
    R1["接收 MCP 请求"] --> R2["中间件链<br/>ErrorHandler → Logging → Auth → Cache"]
    R2 --> R3{"缓存命中？"}
    R3 -->|"是"| R8["直接返回缓存结果"]
    R3 -->|"否"| R4["路由到对应原语处理器<br/>Tool / Resource / Prompt"]
    R4 --> R5["执行业务逻辑"]
    R5 --> R6["写入缓存（可选）"]
    R6 --> R7["返回 MCP 响应"]

flowchart TD
    A["src/main.py<br/>主入口"] --> B["src/server/server.py<br/>MCPServer"]
    A --> K["src/core/logger.py<br/>日志系统"]
    K --> K1["loguru（外部依赖）"]

    B --> C1["FastMCP（外部依赖）"]
    B --> D["src/plugins/manager.py<br/>插件管理器"]
    B --> E["src/core/middleware.py<br/>中间件管道"]
    B --> F["src/transport/transport.py<br/>传输层"]

    D --> D1["src/plugins/base.py<br/>插件基类"]
    D --> D2["src/plugins/registry.py<br/>统一注册表"]
    D --> D3["src/plugins/discovery.py<br/>插件发现"]

    E --> E1["ErrorHandler 中间件"]
    E --> E2["Logging 中间件"]
    E --> E3["Auth 中间件"]
    E --> E4["Cache 中间件"]

    B --> G["src/runtime/<br/>上下文与会话"]
    B --> H["src/core/config.py<br/>配置管理"]
    H --> H1["Pydantic Settings（外部依赖）"]