mcpcat: Instructions file for Codex

AGENTS.md

本文件为 AI 在此代码仓库中工作时提供指导。

请始终使用中文输出。

构建和运行命令

# 安装依赖
pip install -r requirements.txt

# 运行开发服务器
python main.py
# 或启用热重载
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# 运行测试
pytest

# 代码格式化
black .
isort .

# 代码检查
flake8

# Docker
docker build -t mcpcat:dev .
docker-compose up -d

架构概述

mcpcat 是一个 MCP（Model Context Protocol）聚合平台，通过统一的 FastAPI 接口管理多个 MCP 服务器。

核心流程（main.py）

1. 模块加载时：创建全局 MCPServerManager 实例
2. 配置加载：调用 load_config() → ConfigService.load_mcp_servers_config()
3. 安全初始化：security_service.ensure_default_keys() 首次启动时自动创建默认 API Key
4. 服务器加载：server_manager.load_servers_from_config() 遍历配置，通过 MCPServerFactory 创建 FastMCP 实例
5. 应用创建：创建 FastAPI 应用，添加 AuthMiddleware，挂载所有服务器
6. 生命周期管理：lifespan_manager 调用 server_manager.create_unified_lifespan() 统一管理所有 MCP 生命周期

核心组件

MCPServerManager (app/services/server_manager.py)

• MCP 服务器生命周期的中央调度器
• add_mcp_server(): 创建 FastMCP 实例、生成 mcp_app/sse_app、创建 MCPProxyApp 代理
• mount_all_servers(): 将代理应用挂载到 FastAPI
• create_unified_lifespan(): 使用 AsyncExitStack 管理所有 MCP 生命周期
• 维护 server_info 字典：存储 config、mcp、mcp_app、sse_app、status

MCPProxyApp (app/services/server_manager.py)

• ASGI 代理应用，包装实际的 MCP 应用
• 根据 transport_type（'mcp' 或 'sse'）转发请求到对应的应用实例
• 实现运行时实例切换，无需重启应用

MCPServerFactory (app/services/mcp_factory.py)

• 根据 type 字段创建 FastMCP 实例：
  • stdio: FastMCP.as_proxy() 配置 command/args/env
  • sse: FastMCP.as_proxy() 配置 url/transport="sse"/headers
  • streamable-http: FastMCP.as_proxy() 配置 url/transport="streamable-http"/headers
  • openapi: FastMCP.from_openapi() 配置 spec_url/api_base_url/route_configs

ConfigService (app/services/config_service.py)

• 配置文件路径：settings.mcpcat_config_path（默认 .mcpcat/config.json）
• load_raw_config(): 返回完整配置（包含 mcpServers、security、app）
• load_mcp_servers_config(): 只返回 mcpServers 部分
• add_server_to_config() / update_server_config() / remove_server_from_config(): 配置 CRUD