jiang
be6317eb48
Add project-bound OAuth MCP queries and controlled analysis with scoped evidence, limits, timeouts and a nearby-model spatial query using EPSG:4326 inputs. Default nearby searches to 200 meters and five results. Integrate investigation messaging/presentation, health/readiness and typed history; remove duplicate web search and fix online simulation and compressed baseline writes. Include project migrations 023-025; keep local credentials and demo seeding excluded. Validation: 319 focused pytest checks; real PostGIS temporary-table regression; read-only Jinqian bridge radius comparison; cross-language MCP discovery/calls.
5.8 KiB
MCP 接入的 Keycloak 管理员配置清单
这里创建的是 OAuth 认证配置。OpenCode 到 Agent、Agent 到 Server 的 MCP 协议客户端已实现，无需再开发或安装 MCP 客户端程序。
以下使用已创建的请求方客户端 agent-mcp，MCP 资源的 audience 使用 tjwater-mcp。它们位于现有业务登录使用的同一个 realm。
1. 请求方客户端 agent-mcp
在 Keycloak 的 Clients 中打开 agent-mcp：
| 设置 | 值 |
|---|---|
| Client type / Protocol | OpenID Connect |
| Client authentication | On；这是 confidential 客户端 |
| Service accounts roles | On；用于启动时读取 MCP 工具目录 |
| Standard token exchange | On；用于按当前用户或 worker 的身份换取 MCP 令牌 |
| Standard flow | Off；该客户端不负责浏览器登录 |
| Direct access grants | Off |
| Access token lifespan | 建议300秒，不超过900秒 |
| 签名算法 | RS256 |
保存后，在 Credentials 中取得 Client Secret。密钥只写入 Agent 的忽略文件 .local.env：
TJWATER_MCP_CLIENT_ID='agent-mcp'
TJWATER_MCP_CLIENT_SECRET='<Credentials 中的 Client Secret>'
不要把密钥放入聊天、前端配置、OpenCode 配置或 Git。Server 只配置 TJWATER_MCP_HOST_CLIENT_ID='agent-mcp'，不需要保存这个客户端的密钥。
2. 资源客户端及 scopes
创建或复用表示 MCP 服务的 OIDC 客户端 tjwater-mcp；关闭浏览器登录、直接密码登录和服务账户。这个 ID 是目标 audience，不是另一个需要部署的服务。
创建以下 OIDC Client scopes，并作为 Optional scopes 分配给 agent-mcp；启用 Include in token scope：
mcp.catalog.readmcp.querymcp.context.bind
在这些 scopes 中添加 Audience mapper，使对应 token 的 aud 包含目标客户端 tjwater-mcp。应用按实际 grant 请求 scope：服务账户请求只有 mcp.catalog.read；用户/worker 的交换请求才包含查询和上下文 scope。不要给服务账户额外分配项目成员、管理或设备控制权限。
3. 允许当前业务身份交换
在原有前端登录客户端和 worker 客户端的专用 scope 中添加 Audience mapper，使源 token 的 aud 包含请求方 agent-mcp。保留原业务 API 所需的 audience；不要给源 token 添加 MCP 目标 tjwater-mcp。
交换后必须保持用户主体 sub 不变，azp=agent-mcp，目标 aud 包含 tjwater-mcp。Keycloak 的 audience 参数只筛选已有映射的 audience，不能代替 Audience mapper。
版本和界面名称以当前 Keycloak 为准。配置依据：Keycloak Standard Token Exchange。仅在公开发现中看到 token exchange，并不能证明具体客户端已启用或映射正确。
4. 地址、数据库和启用顺序
正式环境提供该 realm 的 HTTPS issuer。本地开发可显式允许一个 RFC1918 IPv4 HTTP issuer：Agent 设置 NODE_ENV=development，Server 设置 ENVIRONMENT=development，两端 TJWATER_MCP_DEV_HTTP_ISSUER_URI 均填写与各自 TJWATER_MCP_ISSUER_URI 完全相同的地址（含 realm）。此例外不放行远程 HTTP MCP resource；Agent 只允许该 issuer 同源的远程 HTTP 发现及令牌端点，继续拒绝重定向。正式环境必须清空此项并使用 HTTPS 域名。配置值必须与发现文档和令牌 iss 一致，不能仅替换访问地址。
例如，同机开发时 Server .env 可配置为（内网地址按实际认证服务替换）：
ENVIRONMENT=development
TJWATER_MCP_ENABLED=true
TJWATER_MCP_ISSUER_URI=http://192.168.1.114:8088/realms/tjwater
TJWATER_MCP_DEV_HTTP_ISSUER_URI=http://192.168.1.114:8088/realms/tjwater
TJWATER_MCP_RESOURCE_URI=http://127.0.0.1:8000/mcp
Agent .local.env 使用相同的三个 URI，并设置 NODE_ENV=development、
TJWATER_MCP_ENABLED=true。开发模式不跳过签名、issuer、audience、scope 或项目权限校验，
也不自动接受另一种 issuer。切换 Server 环境还会开启开发 API 文档页面。
修改环境文件后需重启相应进程；已有进程不一定自动重读 .env，系统环境变量也可能覆盖文件。
应先确认 Server 的 /.well-known/oauth-protected-resource/mcp 公布的新 issuer，
再启动 Agent 检查工具目录。切回生产时，两端恢复相同 HTTPS issuer 并删除 HTTP 白名单。
业务身份也必须使用同一 issuer：供水前端只在被 Git 忽略的
.env.development.local 中将 TJWATER_KEYCLOAK_ISSUER 设为该内网地址，
保留 .env.local 的 HTTPS 配置供正常 production 构建使用。
Server 本机 .env 可额外设置 OPERATIONAL_WORKER_DEV_TOKEN_URL 为同一内网 issuer
发现文档中的 token_endpoint；该值仅在 ENVIRONMENT=development 时生效，
不替换原来的 OPERATIONAL_WORKER_TOKEN_URL。重启开发前端和 worker，并在浏览器重新登录。
旧 HTTPS 令牌不能用于内网 issuer 的交换；工具目录读取成功不等于业务身份交换成功。
接入人员随后执行：
- 安装 MCP SDK 2 对应的 Server 依赖。
- 对选定项目业务库备份并应用 025_mcp_query_contexts.sql。
- 在 Agent 和 Server 的私有环境中配置相同的 issuer、resource、audience；resource 必须指向实际 Server
/mcp，请求方客户端 ID 均使用agent-mcp。 - 验证带标准
resource的目录 grant 和用户/worker token exchange 都成功；若身份平台拒绝，先解决兼容性，不移除参数重试。 - 在受控测试实例中开启两端
TJWATER_MCP_ENABLED并重载；通过测试项目查询、任务证据和越权拒绝验收后，再按部署流程启用正式环境。
完整环境变量与验收要求见 MCP 实施文档。在以上步骤完成前保持 MCP 开关关闭。