itglue-mcp

基于 Example Corp / examplecorp IT Glue 租户（your-company.itglue.com）的只读 MCP 服务器。可从聊天中回答“我们对这个客户了解什么”，并回答“X 的凭据是什么”，返回的是 IT Glue 链接 而非机密信息。

基于内部远程 MCP 标准构建：fastmcp 资源服务器 + Entra ID 认证，部署在 Portainer 上的 Nginx Proxy Manager 之后。参见 ~/.claude/context/mcp-server-playbook.md。

影响此设计的 API 与内容审计结论见 FEASIBILITY.md。在修改任何内容之前，请先阅读 §0 和 §1。

两大保证

1. 绝不向 IT Glue 写入任何内容

当前使用的 API 密钥具有 完整的写入和删除权限。这是经过验证的，而非假设：

PATCH  /configurations/999999999  -> 404 "Record not found"
PATCH  /passwords/999999999       -> 404 "Record not found"
DELETE /configurations/999999999  -> 404

没有写入权限的密钥会在记录查找 之前 就返回 401/403 失败。404 意味着该变更操作已获授权，只是没有可操作的对象。IT Glue 不签发只读范围的经典 API 密钥，因此 服务器端没有可依赖的权限机制 —— 这一保证完全依赖本代码库：

• client.py 仅暴露一个请求方法 get()，其内部硬编码了 method="GET"。

• 不存在 post/patch/put/delete 辅助方法。添加这些方法属于安全回归，而非功能增强。

• 一旦构造出非 GET 请求，WriteAttemptError 绊线即会触发。

• tests/smoke_local.py 同时断言了缺失的方法和缺失的动词。

如果将来要实现写回功能（FEASIBILITY.md 中的选项 C），必须放在 使用独立密钥的独立进程 中。这种隔离是整个安全论证的核心，因为 IT Glue 文档是客户撰写的文本，由模型进行总结 —— 即不可信输入。

2. 绝不返回任何凭据值

itglue_find_credential 返回的是一个 指针：凭据的名称、类别、所属设备、最近轮换时间、是否启用 OTP，以及一个 IT Glue 深链接。用户点击链接并登录 IT Glue 才能查看机密信息。

脱敏发生在数据 进入 镜像的过程中（redact.py），因此任何下游工具都无法因忘记剥离字段而导致泄露。IT Glue 标记为 restricted 的记录会被完全丢弃。

Related MCP server: invgate-mcp

为什么需要本地镜像

IT Glue 的 filter[name] 仅支持精确匹配， 且部分过滤器会被静默忽略而非拒绝：

因此，服务端搜索要么需要模型并不掌握的精确字符串，要么会静默地给出错误结果。因此，所有数据都被镜像到内存中并在本地搜索（search.py、index.py）。

实测同步成本：约 ~10 个请求 用于约 ~7,000 条结构化记录；约 ~400 个请求 用于 300 个文档正文（95 个组织列表 + 逐文档获取），上限为每 5 分钟 3,000 个请求。核心数据在数秒内即可预热；文档在后台数分钟内完成预热，文档工具会报告 status: indexing 而不是挂起。

不会持久化到磁盘 —— 语料量很小，因此重启只需重新同步，不存在缓存过期失效模式。

搜索刻意设计得较为宽松，因为真实查询往往形如 “EF Vista Del Mar Unified Controller”：一个缩写、一个全名，以及一个在数据中拼写为 Unifi 的产品。通过缩写匹配（EF → Example Foundation）、逐词模糊匹配（unified ≈ unifi，比率 0.83）、组织令牌剔除以及原子标识符处理（确保 192.0.2.51 不会被拆成 ['10','105','251']）来应对。

工具

所有工具均标注 readOnlyHint: true。

此工具所针对的典型查询

“Example Foundation UniFi 控制器的凭据是什么？”

itglue_find_credential 从句子中推断组织，剔除其名称中的词语，在 460 条 EF 凭据记录中模糊匹配 unified→unifi，并返回五个指针 —— 两个位于当前 Unifi Controller (New Staging) 上，三个是较旧的 VDM_Cloudwifi 登录 —— 每个都带有可点击的链接、设备 URL 和最后轮换日期。任何机密信息都不会离开服务器。

本地开发

python -m venv .venv && .venv/Scripts/activate    # Windows
pip install -r requirements.txt
cp .env.example .env      # fill in ITGLUE_API_KEY; set MCP_AUTH_ENABLED=false
python -m itglue_mcp

切勿暴露未启用认证的服务器。MCP_AUTH_ENABLED=false 仅用于 localhost 上的 MCP Inspector。

冒烟测试（实时、只读）

python tests/smoke_local.py

针对实时租户的 47 条断言。如果环境中未设置 ITGLUE_API_KEY，则读取 ~/.claude/credentials/itglue.env，且无需安装 fastmcp。凭据断言是最重要的 —— 如果任何一条失败，请先停止并修复，然后再部署。

部署

1. Entra 应用 + 组 + 令牌生命周期 —— scripts/setup_entra_app.ps1（默认试运行；使用 -Apply 执行）。配置应用、包含五名初始成员的 ITGlue-MCP-Users 安全组、分配强制策略，以及 23 小时 59 分钟访问令牌生命周期策略。参见 docs/ENTRA_SETUP_CHECKLIST.md。

2. Portainer 堆栈 + NPM —— PORTAINER_DEPLOY.md。主机端口 8111（2026-07-29 在 10.0.0.10 上探测为空闲 —— 8100 和 8110 已被占用）。公共主机 itglue-mcp.example.com。

日常维护

• 轮换 IT Glue 密钥 —— 仍未完成。 该密钥现在位于 ~/.claude/credentials/itglue.env，采用内部 KEY=VALUE 格式（2026-07-30 从明文 .itglueapicreds.txt 迁移），但 这只是格式变更，并非轮换 —— 密钥值未变。 该密钥具有写入和删除权限，且曾在明文 .txt 文件中存放了未知时长。轮换步骤：在 IT Glue → 账户 → 设置 → API 密钥中创建新密钥，更新 itglue.env 和 Portainer 栈中的 ITGLUE_API_KEY，然后撤销旧密钥。

• IT Glue 会 自动撤销超过 90 天未使用的 API 密钥。 镜像刷新可保持该密钥活跃；如果服务器长期停用，唤醒时预计会收到 401 错误。

• 通过 ITGlue-MCP-Users 组（而非代码）来添加和移除访问权限。