Skip to main content
Glama
tyer-mcp-server

tyer-mcp-server

by qbsoft

tyer MCP Server

把 PigX 系统(翌核 CRM、SRM…)的业务接口包装成 MCP 工具,供 WeKnora 智能体调用。

核心是按人鉴权:每个 WeKnora 用户各自 OAuth 授权,本服务原样转发其本人的 上游令牌,权限判定完全交给上游系统。服务侧不写任何权限代码——所以永远不会 和上游的权限模型漂移。

目录结构

tyer_mcp_core/      共享层:PigX 鉴权 + 响应处理 + 雪花 ID,接新系统时一行不用改
mcp-tyer-crm/       翌核 CRM   :8765   .env + 业务工具
mcp-tyer-srm/       SRM 骨架   :8766   .env + 业务工具(待接入)
tests/              核心层测试
start-crm.bat       双击启动 CRM
start-srm.bat       双击启动 SRM
start-all.bat       两个一起

Related MCP server: openproject-mcp

启动

双击 start-crm.bat。关闭窗口即停止。

依赖上游先起:MCP 服务启动时不连上游,但首次调用/刷新令牌时需要。 上游没起就授权,会失败。

为什么是两个进程而不是一个

鉴权边界是每个 MCP server 一个:一份 .well-known 元数据、一个上游 IdP、 一个 OAuthProxy。合成一个进程后,第二个系统就没法按人鉴权了。

运维上也更稳:改 SRM 的工具重启进程,不会连累 CRM 的用户重新授权 (实测过——上游重启撞上令牌刷新会清空授权)。

接一个新的 PigX 系统

  1. 在该系统的 PigX 里注册 OAuth2 客户端(照抄 CRM 的 weknora-mcp,改回调端口):

    authorizedGrantTypes    authorization_code,refresh_token
    web_server_redirect_uri http://127.0.0.1:<本服务端口>/auth/callback
    scope                   server
    autoapprove             true
    additional_information  {"enc_flag":"1","captcha_flag":"0"}
  2. 复制 mcp-tyer-srm/ 改名,改 .env(端口、前缀、端点)

  3. 写业务工具——只需要写这部分

  4. 在 WeKnora 里加一个 MCP 服务,认证方式选 OAuth 2.0,用户各自授权

踩过的坑(都已固化进代码,接新系统不用再踩)

坑

现象

解法

PigX 不支持 RFC 7591 DCR

WeKnora 无法完成 OAuth

OAuthProxy 桥接

check_token 不合规 RFC 7662

授权成功但调用 401

改用 /user/info 验令牌

OAuth 端点与登录页跨源

登录后跳到 {"code":1,"msg":"No static resource ."}

端点必须与登录页同源

前端 vite changeOrigin: true

同上(Host 被改写)

改成 false

雪花 ID 经 JSON 数字传递

报「不存在或无权访问」,看起来像权限问题

ID 全程 str,用 as_id()

业务异常是 HTTP 500 + code=1

业务提示被压成一句 "HTTP 500"

按 code 判成败

「不存在或无权访问」

—

防 ID 探测的含糊语义,按空结果返回不抛异常

上游重启撞上令牌刷新

全部用户授权被清空

ResilientOAuthProxy 区分连接错误与授权失效

雪花 ID 那条用演示数据(id=1)测不出来,必须拿真实的 19 位 ID 验证。

加了工具之后

改完 server.py 重启服务还不够:WeKnora 缓存着 MCP 连接,ListTools 返回旧列表。 必须去 WeKnora → 设置 → MCP 服务 → 点「测试连接」 强制重连。 不做这一步的表现是「模型调用一个不存在的工具」,很容易误判成模型的问题。

越权复验

CRM 里留了只读测试账号 test_agent_ro(迁移脚本 2026-08-05-agent-readonly-testuser.sql)。 每次新增工具接口后用它复验一遍:同一个 Agent、同样的问题,低权限账号应当 查不到高权限才能看的数据。

切换账号前要先登出上游会话,否则 /oauth2/authorize 看到已登录会直接发码、不弹登录页:

http://127.0.0.1:9999/admin/oauth2/logout

已验证(2026-08-06):sales01 能查自己名下的 5 个客户、查不到 admin 的 6 个; 未授权接口返回 403。MCP 侧零权限代码。

扩展点:将来要同时支持 API Key 调用

当前鉴权是互斥的:build_auth() 里 OAuth 优先,配齐了就完全不看 MCP_API_KEY。 这是故意的——两者若能同时生效,OAuth 一出问题就会悄悄退回共用服务账号, 不报错、没人发现,按人鉴权名存实亡。

什么时候需要改:出现非 WeKnora 的调用方,且它不支持 OAuth。 典型是定时任务、别的后端系统直接调这些工具。在那之前不要动。

要改两处,都是单点:

  1. auth.py 的 build_auth() 换成 MultiAuth(server=ResilientOAuthProxy(...), verifiers=[StaticTokenVerifier(...)])。FastMCP 的文档场景就是 "OAuth proxy for interactive clients + verifier for machine-to-machine"。

  2. client.py 的 _bearer() 必须加分流,否则会出错: OAuth 模式下它拿 get_access_token().token 转发给上游,而 API Key 进来的 调用方,那个 token 就是 MCP_API_KEY 本身——它不是 PigX 令牌,转发过去 只会得到 424。要靠 client_id 或 scope 区分来路:API Key 那条走 cfg.fallback_token(服务账号),OAuth 那条走用户本人令牌。

别只改第一处。只加 MultiAuth 不改 _bearer(),机器调用会以一种很难懂的 方式失败(授权明明通过了,取数却报凭证过期)。

安全说明

  • 服务默认监听 127.0.0.1,无 HTTPS。要绑 0.0.0.0 或放内网前,先加 TLS。

  • .env 已被 gitignore,不要提交真实凭据。

  • WeKnora 侧需要 SSRF_WHITELIST_EXTRA=127.0.0.1,...,否则保存 MCP 服务时会被 安全校验拦下。生产环境应只放行具体主机,不要放行回环地址。

  • 将来接入写操作接口时,务必在 WeKnora 的 MCP 服务里打开对应工具的 **「需人工审核」**开关。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      An MCP server that bridges AI agents to the eyeot ERP, exposing ~600 business actions (CRM, sales, stock, HR, finance, etc.) as MCP tools over stdio via OAuth 2.1 authentication.
      33
      1
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Exposes the OpenProject REST API as MCP tools for project management, including creating and managing projects, work packages, relations, attachments, users, notifications, watchers, boards, and reference data.
      37
      -
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for the bexio API, enabling interaction with contacts, sales, accounting, projects, and more through 35 tools. Supports both PAT and OAuth authentication with read-only mode and tool group filtering.
      35
      4
      MIT