内容
# mcp-itglue
[](https://www.npmjs.com/package/mcp-itglue)
[](LICENSE)
适用于 MSP 的 [IT Glue](https://www.itglue.com/) API 的 [MCP（模型上下文协议）](https://modelcontextprotocol.io) 服务器，用于 AI 助手读取和安全写入文档。
- **文档和章节** — 列出、读取、创建、更新、发布、删除
- **灵活的资产** — 浏览资产类型及其字段，列出/读取/创建/更新/删除资产
- **附件和图片** — 将图片/文件附加到任何记录中，支持 base64、URL 或本地路径；列出和删除附件
- **语义向量搜索** — “如何删除备份代理”会找到 Veeam 取消注册运行手册，即使单词不匹配（OpenAI 或 Azure OpenAI 嵌入，本地 JSON 索引）
- **基于角色的访问控制** — 查看者/编辑者/管理员的 bearer token 决定每个会话可以看到哪些工具
- **自带密钥** — 客户端可以为每个会话提供自己的 IT Glue API 密钥，以便应用 IT Glue 的权限
- **索引新鲜度** — IT Glue webhook、写入后自我刷新和手动刷新端点
- **传输** — 标准输入输出用于本地使用，可流式传输的 HTTP 用于共享部署；包含 Docker 镜像
## 安装
您需要一个 IT Glue API 密钥（IT Glue → 账户 → 设置 → API 密钥）。非美国账户请设置 `ITGLUE_REGION` 为 `eu` 或 `au`。
### npx（推荐）
Claude Desktop（`claude_desktop_config.json`）或 Claude Code（`.mcp.json`）：
```json
{
"mcpServers": {
"itglue": {
"command": "npx",
"args": ["-y", "mcp-itglue"],
"env": { "ITGLUE_API_KEY": "ITG.xxxx" }
}
}
}
```
Claude Code 一行命令：
```bash
claude mcp add itglue --env ITGLUE_API_KEY=ITG.xxxx -- npx -y mcp-itglue
```
Claude Desktop 用户可以从 [最新版本](https://github.com/mspstack/mcp-itglue/releases/latest) 获取 `mcp-itglue.mcpb` — 在 Claude Desktop 中打开它并在提示时填写 API 密钥。
标准输入输出始终使用完整的工具表面 — 它是一个本地的、单用户传输，使用您自己的密钥。
### Docker
容器镜像默认为 HTTP 传输（用于 [共享部署](#http-部署)）：
```bash
docker run --rm -p 3000:3000 \
-e ITGLUE_API_KEY=ITG.xxxx \
ghcr.io/mspstack/mcp-itglue
```
在 Docker 下用于本地标准输入输出：
```json
{
"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" }
}
}
}
```
### 从源码
```bash
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 部署
```bash
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：
```bash
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` | 手动索引刷新（共享密钥或管理员令牌） |
> 会话存储在内存中 — 在负载均衡器后面运行单个实例（或添加粘性会话）。
## 访问控制
### 角色令牌
三个环境变量包含逗号分隔的 `label:token` 列表：
```bash
MCP_TOKENS_VIEWER="alice:tokA,bob:tokB" # 只读工具
MCP_TOKENS_EDITOR="hatz:tokC" # + 创建/更新/发布，删除章节
MCP_TOKENS_ADMIN="ops:tokD" # + 删除文档 / 灵活资产
```
客户端使用 `Authorization: Bearer <token>` 进行身份验证。标签出现在审计日志中（`[rbac] 会话 … for alice （查看者）），允许您撤销某人的令牌而无需轮换每个人的令牌。
工具如果角色无法使用，则 **不会注册** 给该会话 — 查看者甚至不会在 `tools/list` 中看到 `itglue_create_document` — 运行时防护会深度防御地重新检查角色。会话 ID 从不携带权限：每个请求都会重新进行身份验证，针对现有会话呈现不同的主体会返回 403。
如果 **没有** 配置令牌，服务器将在开发模式下运行：所有请求都将获得管理员访问权限，并伴有大声的启动警告。生产环境中请勿这样做。
### 自带 IT Glue 密钥（BYOK）
客户端可以在初始化请求的 `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_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_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` ‡ | 读取 |
查看者 = 读取。编辑者 = 读取 + 写入。管理员 = 所有。
† 永久，但编辑级别：编辑者需要它来重构文档，并且已经可以通过更新清空章节内容。
‡ 高级工具集（按需启用，默认关闭）：`itglue_get` 是对任何 API 路径的只读 GET 直通，对于精选工具未包装的路径，`itglue_find_endpoint` 搜索精选端点目录。启用 `ITGLUE_ADVANCED_TOOLSET=true` 或 `--advanced`。
当配置了嵌入提供程序时，向量工具才会出现。
## 向量搜索
设置 `OPENAI_API_KEY`（或 `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_ENDPOINT`，其中 `EMBEDDING_MODEL` 是您的部署名称），然后对每个组织运行 `itglue_build_vector_index`。索引是一个 JSON 文件，位于 `VECTOR_INDEX_PATH`（默认为 `./vector-index.json`）— 在临时主机上，将其指向持久卷。
索引保持新鲜有三种方式：
1. **IT Glue webhook** — 在 IT Glue 中，webhooks 由 **工作流**（管理员 → 工作流）发送：添加一个 *文档* 触发器（创建/更新）并附加一个 *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` 中解析；触发器名称映射到通过关键字创建/更新/删除。
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` 头部的请求和本地主机来源始终通过；其他浏览器来源被 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 行为。
- 灵活资产特征更新替换整个特征对象 — 更新工具的描述警告模型发送所有特征回。
- 列表工具返回每个项目按项目（在文本和 `structuredContent` 中）的摘要字段；`itglue_get_*` 工具返回完整的记录。
- IT Glue 没有用户模拟：给定的 API 密钥始终作为其自身执行；RBAC 在此处控制会话可以进行的 **工具调用**；BYOK 委托给 IT Glue 自己的密钥权限。
## 开发
```bash
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](https://github.com/selic)) — [defency.net](https://defency.net) 构建。
更多项目： [github.com/selic](https://github.com/selic) · [LinkedIn](https://www.linkedin.com/in/evghenii-samotiia)
## 许可证
[MIT](LICENSE)
