# Factory MCP 服务

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

## 启动

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

```powershell
.venv\Scripts\python.exe -m mcp_server
```

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

```text
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。