mcp-service-template: Instructions file for Codex

AGENTS.md — Service MCP 模板

项目概览

通用 MCP 服务模板（FastMCP + SQLAlchemy async + Pydantic v2 + Typer CLI），含示例实体 Product / ProductPrice，演示完整 CRUD + 外键解析 + 动态 Filter/Search 链路。 示例域字段与同族 backend/apps/demo_module、frontend demo 商品契约对齐。

• Python: 3.12+ 必须
• 包管理器: uv（pip 可用但 uv 为主）
• 入口: service_mcp/server.py — CLI 命令 service-mcp
• 工具数量: 约 33 个（2 个示例实体 + CSV 导出示例）

快速命令

# 环境
uv venv && uv sync --dev

# 运行服务（任选一种传输）
uv run service-mcp stdio
uv run service-mcp streamable-http --host 0.0.0.0 --port 8001
uv run service-mcp sse --host 0.0.0.0 --port 8001
uv run service-mcp ui --dev-port 8080 --mcp-port 8001

# 测试（内存 SQLite，无需外部 DB；mysql/postgresql 参数化用例需对应服务运行）
pytest                          # 全部测试
pytest tests/test_config.py     # 单文件
pytest -k "test_name"           # 单测试

# Lint + 格式 + 类型
ruff check .
ruff check --fix .
ruff format .
mypy service_mcp

# 修改 filter/search 声明后重新生成 .pyi stub（跑两次，第二次应无 diff）
uv run python scripts/refresh_project_stub.py

# 生成演示数据
uv run python mock/mock_product_data.py

# 数据库迁移（幂等，可重复执行）
uv run python scripts/migrate_example.py
uv run python scripts/migrate_example.py --url sqlite+aiosqlite:///path/to/service_data.db

# 项目改名（模板 → 新项目；默认 dry-run 预览，加 --write 才落盘）
uv run python scripts/rename_project.py my_company --project my-company-mcp --display "My Company MCP"
uv run python scripts/rename_project.py my_company --project my-company-mcp --write

架构

service_mcp/
├── server.py          # FastMCP app + Typer CLI（stdio/sse/streamable-http/ui）
├── config.py          # MCPSettings 分层配置（env → TOML → code），前缀 MCP_，分隔符 __
├── apps/              # FastMCP Apps UI（config_app：数据库/缓存配置管理面板）
├── auth/              # JWT 认证 + 权限
│   ├── config.py      # AuthConfig（mode: tool/admin，从环境变量加载）
│   ├── context.py     # 请求上下文（current_owner / scope_visibility_where 三级可见性）
│   ├── decorator.py   # @mcp_perm(resource, action) 权限装饰器 + build_perm_code（码格式唯一来源）
│   ├── discovery.py   # get_entity_metadata / get_all_permissions（实体元数据缓存）
│   └── middleware.py  # JWTAuthMiddleware（admin 模式时启用，server.py 挂载）
├── db/core.py         # DBManager（异步 SQLAlchemy CRUD/分页）+ InfluxDBManager + 管理器缓存
├── error/exceptions.py # UniqueConflictError / ToolError（业务失败收口）等自定义异常
├── handlers/          # 业务逻辑层
│   ├── base_handlers.py   # CodeResolveMixin — FK code→id 解析、占位自动创建、写侧可见性收敛
│   ├── ownership.py   # 归属档位判据 + GOVERNANCE_RESOURCES（表名→资源码）治理注册表
│   ├── add_handlers.py    # 单条 + 批量插入（含价格冲突版本升级）
│   ├── delete_handlers.py # 注册表驱动的删除定位 + 孤儿标记
│   ├── update_handlers.py # 部分更新（None 字段跳过）
│   └── query_handlers.py  # 分页、外键显示展开、异常待办聚合
├── models/
│   ├── orm/           # Base（id/created_at/updated_at/created_by + EnumInt）+ Product/ProductPrice
│   │                  # + PARENT_ENTITY_MAP（父实体可见性注册表）
│   ├── pydantic/      # 动态 Filter/Search 生成器（builder.py）+ 实体请求/响应模型
│   └── schemas.py     # 数据库/缓存配置 + 分页（PaginationParams/PageData）
├── tools/             # MCP 工具定义
│   ├── __init__.py    # @global_tool 装饰器（配置类工具，Apps UI 可跨 App 调用）
│   ├── annotations.py # ToolAnnotations 预设（READ_ONLY / WRITE_* 四件套）
│   ├── crud_factory.py # 注册表驱动生成 add/update/delete 工具（单条+批量）
│   ├── crud_tools.py  # __all__ = register_crud_tools(globals()) —— 保持原样
│   ├── query_tools.py # 列表/搜索/枚举工具
│   ├── basic_tools.py # health、配置 CRUD、review_abnormal_items
│   ├── export_tools.py # CSV 导出示例工具（export_products_csv）
│   └── dict_tools.py  # dict_meta 实体元数据工具
├── task/              # 通用后台任务包（TaskManager 生命周期 + TaskScheduler cron 调度）
└── utils/             # enums（BaseEnum/Errcode/领域枚举）、log、path_utils、common、
                       # rate_limiter（按 key 限速）、spill（大结果溢出）、cron、export（CSV）