内容
# mcp-itglue
[](https://www.npmjs.com/package/mcp-itglue)
[](LICENSE)
MCP（模型上下文协议）服务器，适用于IT Glue API，为MSP（托管服务提供商）构建，允许AI助手读取和安全写入文档。
- **文档和章节** — 列出、读取、创建、更新、发布、删除
- **灵活的资产** — 浏览资产类型和字段，列出/创建/更新/删除资产
- **语义向量搜索** — “如何删除备份会找到Veeam运行手册，即使词语不匹配（OpenAI或Azure OpenAI嵌入，本地JSON索引）
-的访问控制** — 查看者/编辑者/管理员令牌决定每个会话可以看到哪些工具
- **自带密钥** — 客户端可以为每个会话提供自己的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/selic/mcp-itglue/releases/latest)获取`mcp-itglue.mcpb` — 在Claude Desktop中打开并在提示时填写API密钥。
标准输入输出始终使用完整的工具集 — 它是一种本地、单用户传输，使用您自己的密钥。
### Docker
容器镜像默认为HTTP传输（适用于[共享部署](#http-deployment)）：
```bash
docker run --rm -p 3000:3000 \
-e ITGLUE_API_KEY=ITG.xxxx \
ghcr.io/selic/mcp-itglue
```
在Docker下进行本地标准输入输出：
```json
{
"mcpServers": {
"itglue": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "ITGLUE_API_KEY", "ghcr.io/selic/mcp-itglue", "--transport", "stdio"],
"env": { "ITGLUE_API_KEY": "ITG.xxxx" }
}
}
}
```
### 从源码构建
```bash
git clone https://github.com/selic/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/selic/mcp-itglue
```
端点：
| 路由 | 目的 |
|---|---|
| `POST/GET/DELETE /mcp` | MCP可流式HTTP端点 |
| `GET /health` | 存活探测 |
| `POST /webhook/itglue` | IT Glue webhook → 索引增量更新 |
| `POST /index/refresh` | 手动索引刷新（共享密钥或管理员令牌） |
> 会话存储在内存中 — 在负载均衡器后面运行单个实例（或添加粘性会话）。
## 访问控制
### 角色令牌
三个环境变量持有以逗号分隔的`标签:令牌`列表：
```bash
MCP_TOKENS_VIEWER="alice:tokA,bob:tokB" # 只读工具
MCP_TOKENS_EDITOR="hatz:tokC" # + 创建/更新/发布，删除章节
MCP_TOKENS_ADMIN="ops:tokD" # + 删除文档 / 灵活资产
```
客户端使用`Authorization: Bearer <token>`进行身份验证。标签出现在审计日志中（`[rbac] 会话 … 适用于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，但仍需要有效的承载令牌 — 保护您的服务器不被用作开放代理 |
| `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` | 读取 |
| `itgl_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_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_build_vector_index` | 写入 |
| `itglue_delete_documents` | 销毁 |
| `itglue_delete_flexible_asset` | 销毁 |
查看者 = 读取。编辑者 = 读取 + 写入。管理员 = 所有权限。
† 永久，但编辑者级别：编辑者需要它来重构文档，并且可以通过更新使章节内容为空。
当配置了嵌入式提供程序时，向量工具才会出现。
## 向量搜索
设置`OPENAI_API_KEY`（或`AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_ENDPOINT`，其中`EMBEDDING_MODEL`是您的部署名称），然后为每个组织运行`itglue_build_vector_index`。索引是`VECTOR_INDEX_PATH`（默认为`./vector-index.json`）处的JSON文件 — 在临时主机上，将其指向持久卷。
索引保持新鲜有三种方式：
1. **IT Glue webhook** — 在IT Glue中，webhook由**工作流**（管理员 → 工作流）发送：添加一个*文档*触发器（已创建/更新）并带有*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`中解析；触发器名称通过关键字映射到已创建/更新/删除。经典的JSON：API样式的有效载体，带有`x-itglue-webhook-signature` HMAC-SHA256头部也会被接受。
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` | — | 每个角色的`标签:令牌,标签:令牌` |
|_ITGLUE_KEYS` | `with-token` | BYOK策略：`disabled`, `with-token`, `open` |
| `ALLOWED_ORIGINS` | — | 允许在`/mcp`上的额外浏览器源（逗号分隔）。没有`Origin`头部和本地源的请求始终通过；其他浏览器源会被403拒绝 |
| `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`, `--`会覆盖环境变量。运行`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 # 通过tsx进行标准输入输出
npm run dev:http # 通过tsx进行HTTP
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)
