x-QiuChi/
├── main.py                          # 主入口，CLI 参数解析与服务器启动
├── config.yaml                      # 运行时配置文件
├── config.yaml.example              # 配置示例（含全部字段说明）
├── .env.example                     # 环境变量示例
├── pyproject.toml                   # 包配置、依赖、工具链设置
├── Dockerfile                       # 多阶段构建镜像
├── docker-compose.yml               # 容器编排
├── LICENSE                          # MIT 许可证
│
├── src/                             # 源码目录
│   ├── __init__.py                  # 统一 API 入口（create_server, tool, resource, prompt）
│   │
│   ├── core/                        # [核心层] 框架核心功能
│   │   ├── config/
│   │   │   └── config.py            # Pydantic Settings 配置管理（多源优先级、热重载）
│   │   ├── server/
│   │   │   ├── server.py            # MCPServer（封装 FastMCP，装饰器注册，中间件集成）
│   │   │   └── lifecycle.py         # 服务器状态机（UNINITIALIZED → RUNNING → STOPPED）
│   │   ├── plugins/
│   │   │   ├── base.py              # 插件抽象基类（ToolPlugin / ResourcePlugin / PromptPlugin）
│   │   │   ├── registry.py          # UnifiedRegistry（线程安全统一注册表）
│   │   │   ├── manager.py           # PluginManager（自动发现、依赖解析、生命周期）
│   │   │   └── discovery.py         # 插件发现扫描器
│   │   ├── middleware/
│   │   │   ├── base.py              # Middleware ABC + MiddlewareChain 管道
│   │   │   ├── error_handler.py     # 统一错误处理（JSON-RPC 标准错误码）
│   │   │   ├── logging.py           # 请求/响应日志（敏感信息过滤）
│   │   │   ├── auth.py              # Token 认证 + 角色权限
│   │   │   └── cache.py             # 内存缓存（TTL、SHA-256 Key）
│   │   ├── transport/
│   │   │   └── transport.py         # 传输层配置（SSE / HTTP / TLS）
│   │   ├── logging/
│   │   │   └── logger.py            # loguru 封装（文件轮转、多输出）
│   │   └── types.py                 # 共享枚举（TransportType, LogLevel, LogOutput）
│   │
│   ├── plugins/                     # [插件层] 装饰器工厂
│   │   ├── base.py                  # PluginDecorator（生成 @tool / @resource / @prompt）
│   │   ├── tools/__init__.py        # 导出 tool 装饰器
│   │   ├── resources/__init__.py    # 导出 resource 装饰器
│   │   └── prompts/__init__.py      # 导出 prompt 装饰器
│   │
│   ├── runtime/                     # [运行时层] 请求上下文
│   │   └── context.py               # RequestContext + SessionManager + ContextManager
│   │
│   ├── utils/                       # [工具层] 通用工具（预留）
│   ├── cli/                         # [CLI 层] 命令行工具（预留）
│   │
│   └── 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_servers/
│       └── weather_mcp_server.py    # OpenWeatherMap 天气服务示例
│
├── tests/
│   └── test_integration.py          # 7 步集成测试套件
│
└── logs/                            # 日志输出目录

flowchart TD
    A["MCP Client<br/>(Claude Desktop / LangChain / 自定义)"]
    B["Transport Layer<br/>Stdio / SSE / Streamable-HTTP"]
    C["Middleware Pipeline<br/>ErrorHandler → Logging → Auth → Cache → Handler"]
    subgraph D["MCP 三大原语"]
        direction LR
        D1["Tools (工具原语)"]
        D2["Resources (资源原语)"]
        D3["Prompts (提示词原语)"]
    end
    E["Plugin System<br/>Discovery → Load → Register → Enable → Serve"]
    F["Unified Registry (线程安全)"]
    G["Core Server<br/>MCPServer (封装 FastMCP) + Lifecycle"]
    H["Configuration Management<br/>Pydantic Settings (Env > YAML > Defaults)"]
    I["Structured Logging<br/>loguru (stderr + file rotation)"]

    A -->|"MCP Protocol (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["Middleware Chain<br/>ErrorHandler → Logging → Auth → Cache"]
    R2 --> R3{"缓存命中?"}
    R3 -->|"是"| R8["直接返回缓存"]
    R3 -->|"否"| R4["路由到对应原语<br/>Tool / Resource / Prompt Handler"]
    R4 --> R5["执行业务逻辑"]
    R5 --> R6["写入缓存（可选）"]
    R6 --> R7["返回 MCP 响应"]

flowchart TD
    A["main.py"] --> B["src/__init__.py<br/>(统一 API 入口)"]
    A --> K["src/core/logging/logger.py"]
    K --> K1["loguru (外部依赖)"]

    B --> C["src/core/server/server.py"]
    B --> G["src/plugins/base.py<br/>(装饰器工厂)"]
    B --> H["src/runtime/context.py"]
    B --> I["src/core/config/config.py"]
    I --> I1["Pydantic Settings<br/>(外部依赖)"]

    C --> C1["FastMCP (外部依赖)"]
    C --> D["src/core/plugins/manager.py"]
    C --> E["src/core/middleware/base.py"]
    C --> F["src/core/transport/transport.py"]

    D --> D1["src/core/plugins/base.py"]
    D --> D2["src/core/plugins/registry.py"]
    D --> D3["src/core/plugins/discovery.py"]

    E --> E1["error_handler.py"]
    E --> E2["logging.py"]
    E --> E3["auth.py"]
    E --> E4["cache.py"]

# 安装 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

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

# 使用 uv（推荐）
uv sync

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

# 或使用 pip
pip install -e .
pip install -e ".[dev]"

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

# 2. 复制环境变量文件
cp .env.example .env

# HTTP 模式（默认，端口 8000）
uv run main.py
# 或使用项目名称
uv run x-QiuChi

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

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

# 查看全部参数
uv run main.py --help
# 或
uv run x-QiuChi --help

# 构建并启动
docker compose up -d

# 查看日志
docker compose logs -f qiuchi-mcp

# 自定义环境变量启动
MCP_PORT=9000 MCP_LOG_LEVEL=DEBUG docker compose up -d

# 停止服务
docker compose down

# 运行测试
pytest

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

# 测试覆盖率
pytest --cov=src tests/

# 代码格式化
ruff format src/

# 代码检查
ruff check src/

# 类型检查
mypy src/