next-tjwater-server/docs/mcp-project-services.md

MCP 项目服务

当前 Server 有 67 项工具：42 项查询、12 项计算、13 项预览式写入。Agent 合并六项宿主查询后共 73 项。目录来自 app/mcp/catalog.py，Agent 使用独立的有限白名单并在启动时全等核对。工具前缀为 mcp_tjwater_。

新增能力

领域	工具（省略前缀）	权限
区域与连接	list_regions, get_region, get_region_nodes, get_node_connections	webgis.view
空间范围与骨干节点	query_network_extent, list_major_nodes	webgis.view
模型配置	get_model_configuration, list_model_configurations	webgis.view
项目地名	search_project_places, reverse_geocode	webgis.view
项目概况与导出	get_project_info, export_project_model	webgis.view
监测点交付	get_sensor_placement_candidate, export_sensor_placement	optimization.run
调度与运行历史	list_task_schedules, get_task_run_history	operational_task.view
需水量分配	calculate_demand_allocation	webgis.view
假设爆管水力模拟	run_burst_simulation	simulation.run + scada.view
模型编辑	edit_model_element, edit_model_configuration	webgis.edit
SCADA 维护	clean_scada_readings, write_scada_readings, delete_scada_readings	scada.clean
正式分析成果	save_simulation_scenario	simulation.run + scada.view
正式监测点方案	create_sensor_placement, update_sensor_placement	optimization.run
任务与定时配置	create_operational_task, create_task_schedule, update_task_schedule, retry_operational_task, cancel_task_run	operational_task.write
写入状态核实	get_mutation_status	webgis.view，仅当前身份与会话的执行记录

健康预测不在本次接入范围。报告发布、工单/设备动作的提议与审批、消息发送继续使用既有受控插件和业务动作流程。

数据与计算边界

• 所有查询使用当前授权项目连接。当前只有 TJWater 提供 GIS 信息；其他项目没有所需 GIS 数据或关系时返回空数据/明确不可用，不借用 TJWater 的图层或数据库。空页不能证明其他数据源没有对象。
• 范围查询直接用 PostGIS ST_Intersects，不调用旧的空占位服务。范围和输出坐标为 EPSG:4326，单轴范围最多一度。查询模型几何，不把空间邻近称为供水连通。
• 区域成员优先使用已配置节点关系，未配置时使用区域几何；配置、几何成员与真实供水拓扑需分别解释。
• 模型配置 data_path 选择嵌套字段，limit/offset 对选中集合分页。模式和曲线可单独列出 ID。编辑字段必须通过现有模型 schema 的可写属性校验；有限业务枚举不接受 SQL、任意路由、命令、身份、数据库地址或文件路径。
• 需水量分配按关联管长权重，只返回建议值，不修改节点需水量；输入输出沿用模型流量单位。区域或全网结果按节点 ID 稳定分页。
• 爆管模拟输入是已说明依据的破口面积（cm²），不是流量。复用隔离模型，persist_results=False；这与异常侦测和候选定位是不同工具。
• 保存正式场景会重新执行真实计算并持久化成果。压力调节和关阀正式成果使用宿主绑定的用户名。计算共用原有两项并发槽位，超时后槽位保留至原生线程退出。
• 新建任务限未绑定 Agent 的 operator/agent 事件调查；不能伪造外部工单或租约。重试只重新入队，实际执行仍由原有 Worker 领取。取消、启停和方案点位更新复用现有版本或旧值校验。

写入预览和原生许可

13 项新写入工具只对项目成员的 ordinary_chat 开放。任务执行、任务协作、只读 reader、个人会话和学习复盘均不能调用。每次校验当前权限及绑定时的权限上限；写入工具不加入只读自动许可名单，管理员拒绝继续优先。交互聊天遵循现有本轮 request/always 策略，always 不改变业务权限。

1. 为具体操作生成 UUID request_id，默认 dry_run=true，取得预览与 expected_digest。预览不运行模拟/优化，也不写业务数据。
2. 保持相同参数和 request_id，使用 dry_run=false 及返回的 expected_digest 请求执行，并经过宿主原生许可。
3. 服务重新读取目标并校验摘要。模型预览复核与修改共用模型变更锁；SCADA 操作在时序库串行化事务中复核相关数据。数据变化返回冲突，须重新预览。
4. 执行前在现有 workbench.mcp_query_receipts 保存 started 记录，完成后保存结果。同一会话、身份、项目和请求键的完成操作返回原结果，已启动但状态不明确的操作不会再次执行。可用 get_mutation_status 核实记录，并通过目标查询核实实际数据。超时/进程退出可能已有部分结果，不能解释为回滚，也不能自动换键重试。

计算容量已满且原生函数尚未调用时，返回 CALCULATION_CAPACITY_EXCEEDED。 这类明确未执行的请求记为 rejected、retryable=true；状态查询同时返回具体 错误。容量释放后可用原身份、会话、项目、参数和 request_id 重试，仍需通过 原生许可和预览摘要复核。重试时继续锁定请求记录，成功后的重复调用只返回 已保存结果。其他 503、算法异常、超时或取消仍保留 started，不能据此自动重试。

SCADA 维护必须明确列出设备，窗口最多 24 小时。清洗/删除最多 10000 条，补录/修正最多 500 条，来源依据必填；不开放 all。数据写入清洗值或实测表，不从模拟结果构造实测。涉及 BizDB 和 TimescaleDB 时不承诺跨库事务原子性，执行日志中的 started 与业务修改之间也不承诺分布式 exactly-once。

导出与会话下载

export_project_model 从数据库导出 ZIP（INP 或 ChangeSet，含顶点和 SCADA 元素），export_sensor_placement 导出已有方案 XLSX。单文件最多 5 MiB；模型通过 ZIP 压缩传输。Server 返回长度及 SHA-256；Agent 验证后只写当前会话 workspace/files/，返回相对路径和下载链接，模型消息不包含文件正文或宿主绝对路径。导出暂不支持超过该预算的文件分片。

下载接口为 Agent GET /api/v1/session/{session_id}/files/{filename}。它复用身份与项目校验，验证会话所有权，仅接受服务生成的文件名格式，拒绝符号链接和跨会话目录。前端通过已认证的 Agent client 下载；链接和磁盘文件均不是公开资源。文件随会话持久化和删除，不引入独立结果引用存储。

无需数据库迁移、新环境变量或新密钥。地名搜索沿用项目配置与已有天地图服务凭据。需同步发布 Server、Agent、前端，再重载 Server 与 Agent 工具目录；不要以代码目录一致代替线上重载验收。

验证

运行 focused pytest、Agent MCP/策略/导出测试及类型检查、前端协议与下载测试、浏览器下载覆盖及构建。另用隔离 MCP fixture 验证两端 SDK 目录、上下文绑定和原生工具调用。测试不运行真实项目模拟、优化、SCADA 清洗或任何业务写入；真实项目运算与数据效果仍须按项目验收。