OrgTJWater/next-tjwater-server
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add project-scoped operations
Generic Container CI/CD / test-build-publish (push) Failing after 6s
Details
Server CI/CD v2 / build-test-publish-and-deploy (push) Failing after 6s
Details

Browse Source
This commit is contained in:
jiang
2026-10-22 18:40:20 +08:00
parent d320972d57
commit 1d061f6099
73 changed files with 4384 additions and 228 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/mcp-query-implementation.md
+4 -4
View File
@@ -1,6 +1,6 @@
# 产品 MCP 查询：本地实施与启用
实现使用 MCP 2026-07-28、Python mcp 2.3.0、TypeScript @modelcontextprotocol/client 与 @modelcontextprotocol/server 2.3.1。Server 提供 `/mcp` 和35项工具（25项查询、10项受控分析）；Agent 将其投影合并到本地 MCP，由 OpenCode 原生发现为 `mcp_tjwater_*`，普通项目会话、调查主 Agent 和已验证的直接只读子 Agent 共享25项查询；10项分析仅向非reader会话开放。个人会话不能获取项目凭据。旧 CLI 只作为能力清单，没有运行时 CLI 桥接。
实现使用 MCP 2026-07-28、Python mcp 2.3.0、TypeScript @modelcontextprotocol/client 与 @modelcontextprotocol/server 2.3.1。Server 提供 `/mcp` 和67项工具（42项查询、12项计算、13项预览式写入）；Agent 将其投影合并到本地 MCP，由 OpenCode 原生发现为 `mcp_tjwater_*`，普通项目会话、调查主 Agent 和已验证的直接只读子 Agent 共享42项查询；12项计算仅向非reader会话开放，13项写入仅向项目成员的普通聊天开放。个人会话不能获取项目凭据。旧 CLI 只作为能力清单，没有运行时 CLI 桥接。
`run_simulation` 是在线重算，复用 REST 在线计算服务而不复制数据库；按水力步长更新模型条件和实时基线，不创建正式方案。MCP 时长为秒，原 REST 时长仍为分钟。其 annotation 为 `readOnlyHint=false`、`destructiveHint=true`；只读 reader 不能调用，其他方案模拟继续使用隔离临时模型。详细边界见 [MCP 分析工具说明](mcp-analysis-tools.md)。
@@ -76,11 +76,11 @@ TJWATER_MCP_CLIENT_SECRET=<由身份平台注入>
安装 Agent 更新的 Bun 依赖。本地 MCP 使用官方 Server SDK，独立监听127.0.0.1临时端口，先于原生工具发现就绪。宿主只把公开端点写入 `SESSION_METADATA_STORAGE_DIR` 的兄弟目录 `mcp-query/connection.json`，目录0700、文件0600；不保存令牌或 client secret。embedded 自动注入连接路径，OpenCode 环境仍剔除全部 `TJWATER_MCP_*`。client 模式须同网络空间、同版本可信插件、同一内部密钥，并共享 `TJWATER_AGENT_MCP_CONNECTION_PATH` 指向的连接文件，Agent 重启后同步重载原生连接。默认路径 `data/mcp-query/connection.json`。不要把 OAuth 配置注入外部 OpenCode。
项目及宿主只读工具统一由 MCP 提供，插件只配置原生连接与权限；额外六项是地理编码、会话搜索、调查任务列表与详情、消息读取、待办读取，合并后共41项。公开网页搜索使用 OpenCode 原生 `websearch`，搜索服务及凭据由 OpenCode 管理；Server 的 Bocha 接口、配置和 MCP 搜索入口已移除。`memory_manager` 和 `skill_manager` 保留完整读写插件，写入、展示工具保持插件形式。旧项目和任务查询工具及其内部 HTTP 查询桥已移除；未启用产品 MCP 时项目数据不可用，不回退。
项目及宿主只读工具统一由 MCP 提供，插件只配置原生连接与权限；额外六项是地理编码、会话搜索、调查任务列表与详情、消息读取、待办读取，合并后共73项。公开网页搜索使用 OpenCode 原生 `websearch`，搜索服务及凭据由 OpenCode 管理；Server 的 Bocha 接口、配置和 MCP 搜索入口已移除。`memory_manager` 和 `skill_manager` 保留完整读写插件，报告/消息/现场业务动作与展示工具保持插件形式；新增模型和数据维护写入通过预览式MCP提供。旧项目和任务查询工具及其内部 HTTP 查询桥已移除；未启用产品 MCP 时项目数据不可用，不回退。
原生调用的 `_meta["ai.opencode/sessionID"]` 仅用于关联宿主会话，本地服务先核验内部密钥和本机来源，再核验所有权及直接父子关系。原生工具发现、权限、元数据传递与待办 RPC 已由 `bun run tests/integration/query-mcp-smoke.ts` 验证，不调用模型。任务上下文保留可选 `report_revision`，缺省使用协作会话绑定修订号。隔离启动器显式设置自己的 `TJWATER_AGENT_MCP_CONNECTION_PATH`，两端共同读取该文件，不继承其他实例的连接文件。
6. 先用测试项目分别验证普通项目会话、worker 调查和直接 reader 子会话，再开启生产。Agent 启动先发现 Server 目录并与宿主35项白名单对齐，再验证 OpenCode 的真实工具 ID；失败不进入 ready。切换开关需重启 Agent。Server 未迁移项目的绑定接口返回503。
6. 先用测试项目分别验证普通项目会话、worker 调查和直接 reader 子会话，再开启生产。Agent 启动先发现 Server 目录并与宿主67项白名单对齐，再验证 OpenCode 的真实工具 ID；失败不进入 ready。切换开关需重启 Agent。Server 未迁移项目的绑定接口返回503。
client_credentials 与 token exchange 均发送标准 `resource=TJWATER_MCP_RESOURCE_URI`；exchange 同时保留配置的 audience。部署前必须验证身份平台接受该参数，且两种 grant 都将规范资源映射到 Server 要求的专用 audience。若所用 Keycloak 拒绝该参数，会报告配置不兼容，需升级或提供兼容适配；代码不会移除 resource 后重试。目录的服务 grant 与用户/worker 的 exchange 均不会退回共享管理员 Bearer或直接转发产品 Bearer给MCP。[Keycloak 官方说明](https://www.keycloak.org/securing-apps/token-exchange)。外部交互客户端的授权码流程和第三方客户端绑定不包含在本次交付中。
@@ -103,6 +103,6 @@ bun test tests/product/mcpAuthDiscovery.test.ts tests/product/mcpQueryClient.tes
MCP_TEST_PYTHON=<隔离Server环境Python> MCP_TEST_SERVER_ROOT=<Server仓库绝对路径> bun tests/integration/mcp-query-smoke.ts
```
HTTP smoke 只启动自己的 loopback fixture，使用真实两端 SDK，无生产数据库、Keycloak或模型推理。它验证新版发现、真实资源元数据 HTTP 读取、授权服务器元数据及带 resource 的两种 grant（后两者为桩）、35项工具、主机绑定、查询及撤销；真实环境验收记录见上方实际运行环境一节，不能用 fixture 结果代替。前端严格解析已接受这些 MCP 快照来源，未加入浏览器 MCP 凭据或新 UI。
HTTP smoke 只启动自己的 loopback fixture，使用真实两端 SDK，无生产数据库、Keycloak或模型推理。它验证新版发现、真实资源元数据 HTTP 读取、授权服务器元数据及带 resource 的两种 grant（后两者为桩）、67项工具、主机绑定、查询及撤销；真实环境验收记录见上方实际运行环境一节，不能用 fixture 结果代替。前端严格解析已接受这些 MCP 快照来源，未加入浏览器 MCP 凭据或新 UI。
查询限制回归使用 `python -m pytest tests/unit/test_mcp_query_limits.py tests/unit/test_mcp_query.py tests/unit/test_timeseries_history.py tests/unit/test_timeseries_history_schema.py -q`。实际 PostgreSQL SQL 验证可设置 `MCP_QUERY_TEST_DSN` 后运行 `python -m pytest tests/integration/test_mcp_query_limits_postgres.py -q`；该 DSN 必须指向空的、可丢弃的独立数据库，测试创建临时业务同名 schema 并在事务结束时回滚。它验证数据点跨序列翻页、证据路径/Unicode分页、任务摘要与指定报告、章节稳定路径、项目/任务隔离、既有scope边界、字节门槛和合成摘要，不代替真实项目验收。