IT Glue

mcp-itglue

一个适用于 IT Glue API 的 MCP（Model Context Protocol）服务，专为希望让 AI 助手读取并安全写入文档的 MSP 打造。

• 文档和章节 — 列出、读取、创建、更新、发布、删除
• 灵活资产 — 浏览资产类型及其字段，列出、读取、创建、更新、删除资产
• 文档中的图片 — 通过 base64、URL 或本地路径将图片上传到文档中（内嵌到 Text/Step 章节，或上传到 Gallery），并使用返回的 <img src> 嵌入；获取和删除文档图片
• 附件 — 将任意文件附加到记录的 Attachments 面板（文档、灵活资产、配置等）；列出和删除附件
• 语义向量搜索 — 即使措辞不匹配，搜索“如何移除备份 Agent”也能找到 Veeam 退役操作手册（使用 OpenAI 或 Azure OpenAI 嵌入、本地 JSON 索引）
• 基于角色的访问控制 — 查看者 / 编辑者 / 管理员持有者令牌决定每个会话能够看到哪些工具
• 使用自有密钥 — 客户端可在每个会话中提供自己的 IT Glue API 密钥，因此会应用 IT Glue 自身的权限
• 索引新鲜度 — IT Glue webhook、写入后自动刷新，以及手动刷新端点
• 传输方式 — 本地使用 stdio，共享部署使用可流式 HTTP；附带 Docker 镜像

安装

你需要一个 IT Glue API 密钥（IT Glue → Account → Settings → API Keys）。非美国地区的账户请将 ITGLUE_REGION 设为 eu 或 au。

npx（推荐）

Claude Desktop（claude_desktop_config.json）或 Claude Code（.mcp.json）：

{
  "mcpServers": {
    "itglue": {
      "command": "npx",
      "args": ["-y", "mcp-itglue"],
      "env": { "ITGLUE_API_KEY": "ITG.xxxx" }
    }
  }
}

Claude Code 单行命令：

claude mcp add itglue --env ITGLUE_API_KEY=ITG.xxxx -- npx -y mcp-itglue

Claude Desktop 用户也可以从最新版本获取 mcp-itglue.mcpb — 用 Claude Desktop 打开，并在提示时填写 API 密钥。

stdio 始终以完整工具集运行 — 这是一种本地单用户传输方式，使用你自己的密钥。

Docker

容器镜像默认使用 HTTP 传输（适用于共享部署）：

docker run --rm -p 3000:3000 \
  -e ITGLUE_API_KEY=ITG.xxxx \
  ghcr.io/mspstack/mcp-itglue

在 Docker 下本地使用 stdio：

{
  "mcpServers": {
    "itglue": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "ITGLUE_API_KEY", "ghcr.io/mspstack/mcp-itglue", "--transport", "stdio"],
      "env": { "ITGLUE_API_KEY": "ITG.xxxx" }
    }
  }
}

从源代码构建

git clone https://github.com/mspstack/mcp-itglue.git && cd mcp-itglue
npm install && npm run build
ITGLUE_API_KEY=ITG.xxxx node dist/index.js

HTTP 部署

ITGLUE_API_KEY=ITG.xxxx \
MCP_TOKENS_VIEWER="alice:$(openssl rand -hex 32)" \
MCP_TOKENS_EDITOR="automation:$(openssl rand -hex 32)" \
MCP_TOKENS_ADMIN="ops:$(openssl rand -hex 32)" \
npx -y mcp-itglue --transport http --port 3000

或使用 Docker：

docker run --rm -p 3000:3000 \
  -e ITGLUE_API_KEY -e MCP_TOKENS_VIEWER -e MCP_TOKENS_EDITOR -e MCP_TOKENS_ADMIN \
  ghcr.io/mspstack/mcp-itglue

端点：

路由	用途
POST/GET/DELETE /mcp	MCP 可流式 HTTP 端点
GET /health	存活探针
POST /webhook/itglue	IT Glue webhook → 增量索引更新
POST /index/refresh	手动刷新索引（共享密钥或管理员令牌）
PUT /upload/:id	暂存文件上传槽位（内存后端；使用与 /mcp 相同的身份验证）

会话保存在内存中 — 请在负载均衡器后运行单个实例（或启用粘性会话）。

访问控制

角色令牌

三个环境变量存放以逗号分隔的 label:token 列表：

MCP_TOKENS_VIEWER="alice:tokA,bob:tokB"   # read-only tools
MCP_TOKENS_EDITOR="hatz:tokC"             # + create/update/publish, delete section
MCP_TOKENS_ADMIN="ops:tokD"               # + delete documents / flexible assets

客户端通过 Authorization: Bearer <token> 进行身份验证。标签会显示在审计日志中（[rbac] session … for alice (viewer)），便于你撤销某个人的令牌，而无需轮换所有人的令牌。

角色无权使用的工具不会为该会话注册 — 查看者甚至不会在 tools/list 中看到 itglue_create_document — 并且运行时保护机制会在每次调用时重新检查角色，以增加纵深防御。会话 ID 不会携带权限：每个请求都会重新进行身份验证，并且在现有会话中使用不同主体进行身份验证会返回 403。

如果未配置令牌，服务将以开发模式运行：所有请求均获得管理员访问权限，并在启动时发出醒目的警告。请勿在生产环境中这样做。

携带自己的 IT Glue 密钥（BYOK）

客户端可以在 initialize 请求的 x-itglue-api-key 标头中发送自己的 IT Glue API 密钥。随后，该会话会使用此密钥与 IT Glue 通信，并获得完整的工具集——IT Glue 自身的密钥权限即为实际访问控制。CLIENT_ITGLUE_KEYS 控制此策略：

值	行为
with-token（默认）	允许 BYOK，但仍要求有效的 bearer token——保护您的服务免于成为开放代理
open	仅凭 IT Glue 密钥即可进行身份验证（适用于受信任的网络／本地使用）
disabled	拒绝此标头；仅使用服务级密钥

启用 BYOK 后，服务级 ITGLUE_API_KEY 变为可选项：未提供客户端密钥的会话会被拒绝，并返回明确的错误。客户端密钥绝不会被记录；会话会绑定到密钥的 SHA-256 哈希，并以 byok:<hash-prefix> 作为审计标签。

工具

工具	等级
itglue_list_organizations, itglue_get_organization	读取
itglue_list_documents, itglue_get_document	读取
itglue_list_document_folders	读取
itglue_list_document_sections, itglue_get_document_section	读取
itglue_list_flexible_asset_types, itglue_get_flexible_asset_type	读取
itglue_list_flexible_assets, itglue_get_flexible_asset	读取
itglue_get_document_image	读取
itglue_list_attachments	读取
itglue_vector_search, itglue_vector_index_status	读取
itglue_create_document, itglue_update_document, itglue_publish_document	写入
itglue_create_document_section, itglue_update_document_section	写入
itglue_delete_document_section †	写入
itglue_create_document_image	写入
itglue_delete_document_image †	写入
itglue_request_upload（HTTP，UPLOAD_STAGING ≠ off 时）	写入
itglue_create_flexible_asset, itglue_update_flexible_asset	写入
itglue_create_attachment	写入
itglue_build_vector_index	写入
itglue_delete_documents	破坏性
itglue_delete_flexible_asset	破坏性
itglue_delete_attachment	破坏性
itglue_find_endpoint, itglue_get ‡	读取

查看者 = 读取。编辑者 = 读取 + 写入。管理员 = 全部权限。 † 永久删除，但属于编辑者级别：编辑者需要这些工具来重组文档，并且已经可以通过更新来清空章节内容（或从中删除 <img>）。

文档中的图片与附件

IT Glue 有两种互不相关的上传方式。附件（itglue_create_attachment）会出现在记录的「附件」侧边栏中，不会显示在文档正文里。若要在文档内部显示图片，请使用 itglue_create_document_image：

1. 使用 document_id 上传（内嵌），或使用 document_id + gallery_id 上传（其中 gallery_id 是 Gallery/Step 章节的 document_gallery_id）。
2. 对于内嵌图片，将返回的 inline_resource_url 原样放入章节 HTML：<img src="/6255696/docs/17772862/images/27211966">——或者传入 append_to_section_id，由工具将其追加到现有的 Text/Step 章节中。

IT Glue 会从章节内容中剥除 data: URI 和自身的 S3 URL；只有这些相对路径（以及公开的 https:// 链接）会保留。

将文件从客户端传到服务端（暂存上传）

工具参数会经过模型，因此 content_base64 只适用于极小的文件——一张截图就有数 MB 的 Base64 数据，模型必须逐个 token 地复现（而 IT Glue 会因结果被截断而返回 NotIdentifiedByImageMagickError）。因此，HTTP 模式下服务端提供暂存上传：

1. 模型调用 itglue_request_upload（file_name 可选），并获取 upload_id、URL 和可直接运行的 curl 命令。
2. 客户端从 shell 将文件 PUT 到该 URL。
3. 模型使用 upload_id 调用 itglue_create_document_image 或 itglue_create_attachment。

上传槽位有效期为 15 分钟，与发起请求的主体（令牌标签 / BYOK 密钥）绑定，且只能使用一次。可通过 UPLOAD_STAGING 选择两种后端：

模式	PUT 请求的目标	适用场景
memory（HTTP 模式下的默认值）	此服务的 PUT /upload/:id，使用与 /mcp 相同的 Authorization / x-itglue-api-key 请求头。设置 PUBLIC_BASE_URL，使 URL 可访问。	客户端可以直接访问该服务。
azure-blob	Azure Blob Storage 上的短时效 SAS URL；服务端随后使用自身凭据下载 blob 并将其删除。	服务端位于网关之后，或因其他原因无法从客户端访问。请配置 AZURE_STORAGE_CONNECTION_STRING（账户密钥 SAS）或 AZURE_STORAGE_ACCOUNT（托管标识 / 通过 DefaultAzureCredential 使用 az login，需要 Storage Blob Data Contributor + Storage Blob Delegator），以及可选的 AZURE_STORAGE_CONTAINER（默认值为 mcp-itglue-uploads）。
off	—	stdio（默认值——file_path 直接读取本地磁盘）或不需要此功能时。

对于已托管在 Web 上的内容，url 仍是最简单的来源。 ‡ 高级工具集（选择启用，默认关闭）：itglue_get 是只读 GET 透传工具，可访问精选工具未封装的任意 API 路径；itglue_find_endpoint 用于搜索精选的端点目录。通过 ITGLUE_ADVANCED_TOOLSET=true 或 --advanced 启用。密码资源（/passwords）会被硬性拦截——凭据值绝不会传给模型。

只有配置了嵌入提供商时，才会显示向量工具。

向量搜索

设置 OPENAI_API_KEY（或设置 AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT，其中 EMBEDDING_MODEL 是你的部署名称），然后针对每个组织运行 itglue_build_vector_index。索引是位于 VECTOR_INDEX_PATH 的 JSON 文件（默认值为 ./vector-index.json）——在临时主机上，请将其指向持久卷。

索引通过以下三种方式保持最新：

1. IT Glue webhook —— 在 IT Glue 中，webhook 由 Workflows 发送（Admin → Workflows）：添加一个 Document 触发器（created/updated），并配置一个 Webhook 操作。工作流操作无法发送自定义请求头，因此请将共享密钥放在 URL 中：

   https://<host>/webhook/itglue?secret=<ITGLUE_WEBHOOK_SECRET>
   

   并使用类似以下内容的 JSON 负载模板：

   键	值
   event	[trigger_name]
   resource_url	[resource_url]
   resource_name	[resource_name]
   organization_name	[organization_name]

   文档 ID 会从 resource_url 中解析；触发器名称会根据关键词映射为 created/updated/deleted。也接受带有 x-itglue-webhook-signature HMAC-SHA256 请求头的经典 JSON:API 风格负载。

2. 自动刷新 —— 通过此服务的工具创建 / 更新 / 发布 / 删除的文档，会在后台自动重新索引。

3. 手动刷新 —— 使用 Authorization: Bearer <ITGLUE_WEBHOOK_SECRET>（或 x-refresh-secret 请求头，或管理员令牌）发送 POST /index/refresh。请求正文 {"document_id": "123"} 会刷新单个文档；空正文会重新爬取所有已索引的组织。返回 202，并在后台处理。

配置参考

变量	默认值	用途
ITGLUE_API_KEY	—	服务级 IT Glue API 密钥
ITGLUE_REGION	us	us、eu 或 au
ITGLUE_BASE_URL	按区域而定	覆盖 API 基础 URL
TRANSPORT	stdio	stdio 或 http
PORT	3000	HTTP 端口
MCP_TOKENS_VIEWER/EDITOR/ADMIN	—	每种角色对应的 label:token,label:token
CLIENT_ITGLUE_KEYS	with-token	BYOK 策略：disabled、with-token、open
ALLOWED_ORIGINS	—	/mcp 允许的额外浏览器来源（以逗号分隔）。没有 Origin 标头的请求和 localhost 来源始终通过；其他浏览器来源会被拒绝，并返回 403
ITGLUE_ADVANCED_TOOLSET	false	true/1 会注册高级工具集（itglue_get、itglue_find_endpoint）
ITGLUE_WEBHOOK_SECRET	—	Webhook 签名和 /index/refresh 密钥
VECTOR_INDEX_PATH	./vector-index.json	向量索引文件
OPENAI_API_KEY	—	启用向量搜索（OpenAI）
AZURE_OPENAI_API_KEY / AZURE_OPENAI_ENDPOINT / AZURE_OPENAI_API_VERSION	—	启用向量搜索（Azure OpenAI）
EMBEDDING_MODEL	text-embedding-3-small	嵌入模型 / Azure 部署

CLI 标志 --transport、--port、--region、--base-url、--advanced 会覆盖环境变量。运行 mcp-itglue --help 查看详情。

说明和限制

• IT Glue 的速率限制：每个密钥 5 分钟内 3000 个请求。
• IT Glue 文档 API 仅有部分文档；文档/章节端点遵循观察到的 API 行为。
• 灵活资产特征更新会替换整个 traits 对象——更新工具的说明会提醒模型发回所有 traits。
• 列表工具会返回每个项目的摘要字段（同时包含在文本和 structuredContent 中），以便默认分页大小保持在客户端令牌限制内；itglue_get_* 工具会返回完整记录。
• IT Glue 不支持用户身份模拟：给定的 API 密钥始终以其自身身份操作。此处的 RBAC 控制会话可以执行哪些工具调用；BYOK 则遵循 IT Glue 自身的密钥权限。

开发

npm install
npm run dev          # stdio via tsx
npm run dev:http     # http via tsx
npm test             # vitest
npm run build        # tsc → dist/

作者

由 Eugene Samotija（@selic）打造 — defency.net。 更多项目：github.com/selic · LinkedIn

许可证

MIT