factory/docs/mcp.md

Factory MCP 服务

Factory MCP 是仓库顶层的独立服务，使用官方 Python SDK v2，通过 Streamable HTTP 暴露 Agent 工具。当前已提供基础工具和第一批 Dataset 领域工具。

启动

在项目根目录使用项目虚拟环境启动独立进程：

.venv\Scripts\python.exe -m mcp_server

默认监听 127.0.0.1:2260，MCP 端点为 /mcp。客户端必须在每次请求中携带 Factory access token：

Authorization: Bearer <Factory access token>

配置

生产环境在本机已忽略的 config/conf.py 中覆盖以下配置：

• MCP_HOST：监听地址。
• MCP_PORT：监听端口。
• MCP_PATH：Streamable HTTP 路径。
• MCP_ALLOWED_HOSTS：允许的 HTTP Host，支持 hostname:* 端口通配形式。
• MCP_ALLOWED_ORIGINS：允许的浏览器 Origin；非浏览器客户端通常不发送 Origin。
• MCP_MAX_REQUEST_BODY_SIZE：单个 MCP 请求体上限，默认 1 MiB。
• MCP_MAX_RESULT_BYTES：单次领域工具结果上限，默认 512 KiB。

生产部署必须明确配置实际域名的 Host 白名单，不应直接复用 Django 当前的宽泛 ALLOWED_HOSTS。

基础工具

• factory_server_info：返回系统版本、MCP 协议版本和认证方式。
• factory_whoami：返回当前 JWT 对应的 Factory 用户。
• search_datasets：按名称、code 或描述搜索启用的数据集，不返回 SQL 配置。
• execute_dataset：按 code 执行数据集，需要当前用户具有 dataset.exec 权限。
• search_wprs：按编号、物料、批次、状态和当前位置搜索 WPR，只返回摘要。
• get_wpr：按 ID、内部编号或对外编号读取 WPR 详情、缺陷和业务数据。

WPR 当前沿用既有 API 的读取边界：有效登录用户可读，且该 ViewSet 未启用部门数据过滤。MCP 不开放修改编号、分配对外编号或更新预处理信息等写操作。

• search_batch_stats：按批次、直通大批、起始物料和版本搜索批次统计摘要。
• get_batch_stat：读取指定批次版本的完整统计数据，可附带直接拆批/合批关系。

BatchSt 同样沿用既有 API 的 get: * 读取边界，不提供创建、重算或修改工具。完整统计结果仍受 MCP_MAX_RESULT_BYTES 限制。

新增领域工具时必须从 MCP 请求身份获取用户，并复用 Factory 的权限码和数据范围过滤；不得直接使用固定管理员身份查询 ORM。