内容
# hit-mcp
连接 AI 代理（如 Claude、Cursor、VS Code 等）到 HIT — Devpeak 的工单管理系统的 MCP 服务器。只读：代理可以浏览工单队列、搜索工单、读取完整的工单历史、使用工单模板，但不能修改任何数据。
## 快速开始
1. 全局安装软件包：
```bash
npm install --global @devpeak/hit-mcp
```
2. 在 HIT 中生成 API 令牌：点击头像（右上角）→ **账户设置** → **安全** → **API 令牌** → **创建 API 令牌**。
3. 使用 `HIT_BASE_URL`（您的 HIT 实例，例如 `https://support.example.com`）和 `HIT_API_TOKEN`（步骤 2 中的令牌）配置您的 MCP 客户端。参见下面的示例。
---
### 每个客户端的配置
#### Claude Code
```bash
claude mcp add hit -e HIT_BASE_URL=https://your-domain-here -e HIT_API_TOKEN=your-token -- npx hit-mcp
```
#### Cursor
将以下内容添加到 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"hit": {
"command": "hit-mcp",
"env": {
"HIT_BASE_URL": "https://support.example.com",
"HIT_API_TOKEN": "..."
}
}
}
}
```
#### OpenCode
在 `~/.config/opencode/opencode.jsonc` 中，在 `"mcp"` 下添加一个新键，类似如下：
```json
{
"mcp": {
"your-server-name": {
"type": "local",
"command": ["npx", "hit-mcp"],
"environment": {
"HIT_BASE_URL": "https://support.example.com",
"HIT_API_TOKEN": "..."
}
}
}
}
```
---
## 代理可以执行的操作
| 工具 | 描述 |
|---|---|
| `list_queues` | 列出您有权访问的所有支持队列 — 获取有关存在哪些区域（IT、维护、行政等）的概览。 |
| `list_tickets` | 浏览和搜索队列中的工单。按打开/关闭状态过滤，按主题搜索，分页。每个工单都链接到 HIT 的 Web 界面。 |
| `get_ticket` | 获取单个工单的完整详细信息 — 描述、优先级、截止日期、历史记录。 |
| `list_templates` | 列出队列的工单模板 — 有助于查看可用的标准工作流程。 |
**注意：** 所有访问权限均为 **只读** — 代理无法创建、更新或删除工单。
## 在本地构建和开发
```bash
npm install
npm run build
```
复制 `.env.example` 到 `.env`，填写 `HIT_BASE_URL` 和 `HIT_API_TOKEN`，然后运行：
```bash
npm start
```
服务器在标准输入/输出上启动。将您的 MCP 客户端指向绝对路径：
```json
{
"mcpServers": {
"hit": {
"command": "node",
"args": ["/path/to/hit-mcp/dist/index.js"],
"env": {
"HIT_BASE_URL": "https://support.example.com",
"HIT_API_TOKEN": "..."
}
}
}
}
```
