Track It MCP

TrackIt MCP

安装后，Claude可以通过自然语言查找工单、添加注释、更改状态、创建和更新工作项、搜索知识库等，而无需离开聊天窗口。

______________________________________________________________________

它能做什么

______________________________________________________________________

需求

• 克劳德桌面 （Mac或Windows）
• Node.js 18+ 在每个用户的计算机上（用于运行 server.js 连接器内部）
• Track It WebAPI的网络访问(http://your-server/TrackIt/WebApi)

______________________________________________________________________

安装

选项A——安装预构建的连接器（最终用户）

1. 下载 trackit-mcp.mcpb 从 发布 页面。
2. 打开 克劳德桌面 → 设置→ 连接器.
3. 点击 安装连接器 并选择 trackit-mcp.mcpb.
4. 填写五个配置字段：

1. 克劳德将确认连接器是否处于活动状态。开始一段对话，问一些类似的问题： *“查找分配给我的未结门票”* 或 *“1234号票的状态如何？”*

选项B——从源代码构建（开发人员）

git clone https://github.com/ImperatorRuscal/TrackIt-MCP.git
cd TrackIt-MCP
npm install
npm run bundle

这产生 connector/trackit-mcp.mcpb.如上所述在Claude Desktop中安装它。

______________________________________________________________________

运作原理

Claude Desktop
    │
    │  spawns as child process
    ▼
server.js  (bundled Node.js MCP server)
    │
    │  stdio JSON-RPC (MCP protocol)
    │
    │  HTTP requests
    ▼
Track-It WebAPI  (http://your-server/TrackIt/WebApi)

连接器运行 在每个用户的本地计算机上 作为stdio MCP服务器。克劳德桌面生成 server.js （嵌入 .mcpb 包），并使用MCP协议通过stdin/stdout进行通信。服务器使用OAuth2密码授权对Track It进行身份验证，在内存中缓存令牌，并在令牌过期之前使用刷新令牌静默刷新它们。

没有云组件，也没有数据离开您的网络。

______________________________________________________________________

身份验证详细信息

Track It使用非标准用户名格式的OAuth2：

GROUP\DOMAIN\username

使用Windows身份验证： HELP DESK\CONTOSO\jsmith 没有Windows身份验证（域留空）： HELP DESK\jsmith

连接器通过三个单独的配置字段自动组装。令牌在每个会话（约30分钟生存期）中缓存在内存中，并通过刷新令牌进行更新，而无需重新提示凭据。

______________________________________________________________________

安全说明

API错误消息： 当Track It返回错误（例如字段名无效、权限被拒绝）时，响应正文的前300个字符将显示给Claude。这是有意的——它允许Claude进行自我更正，并使用正确的字段名重试。没有数据离开本地计算机。

HTTP部署： 如果您的Track It服务器配置了 http:// URL，Bearer令牌在用户计算机和Track It服务器之间的网络上未加密地传输。对于本地局域网段之外的任何部署，请配置HTTPS后的Track It并使用 https:// 基本URL。

______________________________________________________________________

示例对话

“给我看看4821号票及其完整历史”

Claude将取票，然后立即取下所有笔记（工作日志），并呈现可读的摘要。

“创建工单：三楼的打印机不工作，分配给服务台，优先级高”

克劳德会先打电话 get_module_fields 要发现确切的字段名，请使用正确的字段值创建票证。

在票证4821中添加工作说明：更换碳粉盒，15分钟

克劳德添加了一条注释，并附上了持续时间。

“哪些门票分配给莎拉，已经开放了一个多星期？”

Claude按受让人搜索未结门票和过滤器。

“结束作业217，并注明问题已解决”

克劳德结束作业，并在一个步骤中附上结束语。

______________________________________________________________________

发展

项目结构

src/
  auth.ts              OAuth2 token management (password grant + refresh)
  trackit-client.ts    HTTP client — one function per Track-It API endpoint
  server-stdio.ts      MCP server — tool definitions and handlers

connector/
  manifest.json        MCPB manifest (user_config fields, env var wiring)

scripts/
  build-connector.mjs  esbuild bundle + ZIP packager (no external zip dep)

脚本

npm run bundle      # Full build: TypeScript → bundle → .mcpb
npm run build       # TypeScript compile only (outputs to dist/)
npx tsc --noEmit    # Type-check without emitting

环境变量（用于本地测试）

TRACKIT_BASE_URL=http://your-server/TrackIt/WebApi
TRACKIT_GROUP=HELP DESK
TRACKIT_DOMAIN=YOURDOMAIN
TRACKIT_USERNAME=jsmith
TRACKIT_PASSWORD=yourpassword

node connector/server.js   # should print: [trackit-mcp] v1.x.x started

轨道-It API怪癖

一些不明显的东西 trackit-client.ts:

• 创建和更新都使用POST — POST /tickets 创建， POST /tickets/{id} 更新。没有PUT或PATCH。
• 删除也是POST — POST /tickets/{id}/Delete，而不是HTTP DELETE方法。
• 分页在路上 — GET /tickets/{id}/Notes/{pageSize}/{pageNumber}.使用 0/0 返回所有记录。
• 字段名中有空格 — "Assigned Tech", "Note Type", "Activity Code"这些必须精确地复制。
• priorityheirarchy 拼写错误 在API中-这是正确的端点名称。
• 优先级层次结构需要ID — DepartmentId, CategoryId, LocationId 是整数，不是名称字符串。
• 作业笔记没有 Private 旗帜 --仅支持工单备注 Private: boolean.

看 BOOTSTRAP.md 以供完整参考。

______________________________________________________________________

许可证

GNU Affero通用公共许可证v3.0