environ-mcp

环境监测数据 MCP Server —— 让 AI 助手在对话里直接回答「XX 站点现在数据多少」这类问题。

服务入口：https://app.environ.online/mcp（Streamable HTTP + OAuth 2.1 / PKCE） 服务介绍页：https://app.environ.online/mcp/about

每位使用者需要自己的账号：在浏览器打开绑定页完成绑定后，只能看到自己权限范围内的站点， 多人之间互不影响。

两种运行模式

两个入口共用 src/core.js + src/tools.js，工具定义完全一致。

多用户身份（v1.1 起）

HTTP 模式按 客户端标识 区分用户：每个同事在自己的 mcp.json 里放一个随机串 （请求头 X-Environ-Client），服务器记住这个串对应的是哪个 environ 账号。 于是 A 的小布查 A 的站点，B 的小布查 B 的站点，互不串号。

身份解析优先级：

绑定表落在 ENVIRON_BINDINGS_FILE（容器内 /data/bindings.json），容器重启不丢绑定。

三种绑定方式：

详见 docs/多用户接入指南.md。

OAuth 2.1 + PKCE（v1.2 起）

服务端实现了 MCP 规范要求的授权面，标准客户端可以直接走「点一下授权」：

未授权访问返回 401 + WWW-Authenticate: Bearer resource_metadata="..."， 客户端据此自动发现授权端点。access_token 就是用户身份——服务端把该用户的 environ token 装在令牌里，工具调用按本人权限查数据。

平台接入（豆包 / 扣子 / 火山引擎 / n8n / Dify）

对外同时提供三套入口：

令牌可来自 Authorization 头，也可来自 ?token= / ?key= / ?access_token= （火山引擎的 injection_type=query 注入方式）；客户端标识同样支持 ?client= 查询参数。

平台没有「个人身份」维度，需要先建一个 environ 服务账号并绑定到平台专属 clientKey。逐平台配置见 docs/平台接入指南.md。

容器化

# 构建（Docker Hub 不通时走国内源）
docker build --build-arg BASE_IMAGE=docker.m.daocloud.io/library/node:22-alpine \
             --build-arg NPM_REGISTRY=https://registry.npmmirror.com \
             -t environ-mcp:1.1.0 .

# 启动
docker run -d --name environ-mcp --restart unless-stopped -p 3000:3000 \
  -v $(pwd)/data:/data \
  -e MCP_AUTH_TOKEN=<访问令牌> \
  -e ENVIRON_API_BASE=http://localhost:8081 \
  -e ENVIRON_BINDINGS_FILE=/data/bindings.json \
  -e ALLOW_DEFAULT_BINDING=false \
  environ-mcp:1.1.0

或用 compose：

cp .env.example .env   # 填入 MCP_AUTH_TOKEN
docker compose up -d

镜像特性：多阶段构建、alpine 基础、tini 转发信号、非 root 运行（node 用户）、 HEALTHCHECK 探活、SIGTERM 优雅退出。

完整部署指南见 deploy/DEPLOY.md。

架构

WorkBuddy (MCP Client)
   │  stdio (JSON-RPC)  或  Streamable HTTP → https://app.environ.online/mcp
   │  headers: Authorization + X-Environ-Client
   ▼
environ-mcp  (Node ESM, 本项目)             ← 暴露 8 个 tool
   │  HTTP + Bearer token（X-Environ-Token）
   ▼
environ-svr-v2  /openapi/**                 ← 开放接口
   │
   ▼
InfluxDB (实时/小时时序) + MySQL + Redis

绑定关系存在后端 Redis（wb:bind:{token}，30 天），MCP 侧把 token 缓存在绑定表里， 所以一次绑定，长期可用，不用每次对话都登录。

工具一览

站点参数同时接受 ID 和名称：station 传 "814" 按 ID 查；传 "南明区监测站" 则先调 /openapi/stations?search=... 模糊匹配（完全相等优先，其次包含）。这是让 「查 XX 站点」这种自然语言能跑通的关键。

启用步骤（管理员）

1. MCP 配置已写入 C:\Users\Hailin\.workbuddy\mcp.json（无点前缀的那个文件）
2. 打开 WorkBuddy → 左侧「专家·技能·连接器」→ 右上角「自定义连接器」
3. 找到 environ-mcp → 点信任
4. 重启会话（或开新会话），工具才会注入到对话里

首次使用

打开 https://app.environ.online/mcp/bind，填自己的客户端标识和 environ 账号密码完成绑定； 之后直接问：

• 「XX 站点现在数据多少」
• 「南明区监测站昨天各小时的数据」
• 「给我看下 814 站点的完整情况」

配置项

服务端环境变量：

开发

npm install
npm test                    # 冒烟测试：MCP 握手 + tools/list + check_bind
node test/multi-user.js     # 多用户隔离测试：两个 clientKey 互不串号
node test/oauth-e2e.js      # OAuth 端到端：注册/授权码+PKCE/设备码/刷新/401 头
npm start                   # 手动启动（stdio 模式，需由 MCP Client 拉起）

改完 src/server.js 后，重启 WorkBuddy 会话即可生效（MCP 子进程是常驻的， 不重启拿到的是旧代码）。

注意

• stdout 属于 MCP 协议，所有日志必须走 stderr（代码里用 console.error）
• 后端 /openapi/** 在 WebSecurityConfig 里是用 web.ignoring() 放行的， 不能改成 permitAll() —— 否则 JwtAuthenticationFilter 会把 UUID token 当无效 JWT 拦截返回 401
• 密码校验走后端 up_user_login 存储过程（MD5，不是 BCrypt）
• nginx 只反代了 /mcp 前缀，所以绑定端点挂在 /mcp/bind（而不是 /bind）， OAuth 端点与 .well-known 元数据同理都挂在 /mcp 之下
• 公网根路径 /.well-known/* 被 SPA 的 nginx 占着（返回 index.html）， 所以 OAuth 元数据必须从 /mcp/.well-known/... 取

已上架

发布方式与踩坑记录见 docs/上架指南.md。

License

MIT —— 见 LICENSE。

数据来自企业内部环境监测业务系统，不随本仓库授权分发。