内容
# @trigv/mcp
Trigv（模型上下文协议）服务器，适用于 [Trigv](https://trigv.com)。允许 Cursor、Claude Code 和 VS Code 中的 AI 客户端向您的 Trigv 工作区发送通知事件。
## 什么是 Trigv
Trigv 向您的团队设备发送开发人员通知。您的后端（或 AI 代理）发送轻量级 JSON 事件；Trigv 队列推送通知。通知标题和正文不存储在 Trigv 服务器上 — 仅存储元数据。
## 安装
```bash
npm install @trigv/mcp
```
或使用 `npx` 直接运行：
```bash
npx @trigv/mcp
```
## 快速入门
1. 在 [app.trigv.com](https://app.trigv.com) 上创建工作区 API 密钥。
2. 在您的 MCP 客户端配置中设置 `TRIGV_API_KEY`（参见下文）。
3. 请求您的 AI 助手使用 `send_event` 工具发送事件。
示例工具调用：
```json
{
"channel": "deploys",
"title": "生产环境部署完成",
"description": "构建 #42 在 38 秒内成功（提交 abc1234）",
"level": "success",
"event_type": "deploy.completed",
"idempotency_key": "deploy-prod-42"
}
```
## 身份验证
| 变量 | 是否必填 | 默认值 | 描述 |
|----------|:--------:|---------|-------------|
| `TRIGV_API_KEY` | 是 | — | 工作区摄取 API 密钥（`trgv_…`） |
| `TRIGV_BASE_URL` | 否 | `https://api.trigv.com/api` | 本地开发的重写（`http://trigv-platform.test/api`） |
API 密钥作为 `Authorization: Bearer` 发送，**从不** 包含在工具响应或错误消息中。
## 工具：`send_event`
通过 `POST /v1/events` 发送通知事件。
| 字段 | 是否必填 | 描述 |
|-------|:--------:|-------------|
| `channel` | 是 | 频道 slug（例如 `general`、`deploys`） |
| `title` | 是 | 通知标题 |
| `description` | 否 | 正文 |
| `image_url` | 否 | HTTPS 图片 URL（不存储在服务器端） |
| `url` | 否 | 通知的目标 URL（最大 2048 个字符；不存储在服务器端） |
| `level` | 否 | `info`、`success`、`warning`、`error`（默认：`info`） |
| `delivery_urgency` | 否 | `standard` 或 `time_sensitive`（默认：`standard`） |
| `event_type` | 否 | 自定义标签（例如 `deploy.completed`） |
| `idempotency_key` | 否 | 每个工作区的去重密钥 |
**成功响应** 包括 `event.public_id`、`duplicate`（当 HTTP 200 时为 true）和其他事件元数据。
**错误响应** 包括 `error.type`、`error.message` 和可选的 `error.errors` 进行验证失败。
## 级别
- `info` — 一般信息（默认）
- `success` — 成功完成
- `warning` — 需要关注
- `error` — 失败或警报
## 交付紧急程度
- `standard` — 正常通知（默认）
- `time_sensitive` — iOS 时间敏感交付
## 幂等性
当您设置 `idempotency_key` 时，带有相同密钥的重试将返回现有的事件（`duplicate: true`），而不会再次计费。
## 错误处理
| 错误类型 | 何时发生 |
|------------|------|
| `ConfigurationError` | 缺少 `TRIGV_API_KEY` |
| `ValidationError` | 无效输入（客户端或服务器 422） |
| `AuthenticationError` | HTTP 401 |
| `AuthorizationError` | HTTP 403 |
| `NotFoundError` | 频道未找到（HTTP 404） |
| `RateLimitError` | HTTP 429 |
| `NetworkError` / `TimeoutError` | 连接问题 |
## MCP 客户端配置
### Cursor
在项目中（或全局 Cursor MCP 设置）中将以下内容添加到 `.cursor/mcp.json` 中：
```json
{
"mcpServers": {
"trigv": {
"command": "npx",
"args": ["-y", "@trigv/mcp"],
"env": {
"TRIGV_API_KEY": "trgv_您的_api_key_在此"
}
}
}
}
```
在开发过程中进行本地检查：
```json
{
"mcpServers": {
"trigv": {
"command": "node",
"args": ["/path/to/trigv-mcp/dist/index.js"],
"env": {
"TRIGV_API_KEY": "trgv_您的_api_key_在此",
"TRIGV_BASE_URL": "http://trigv-platform.test/api"
}
}
}
}
```
### Claude Code
将以下内容添加到 `~/.claude/settings.json` 或项目 `.claude/settings.json` 中：
```json
{
"mcpServers": {
"trigv": {
"command": "npx",
"args": ["-y", "@trigv/mcp"],
"env": {
"TRIGV_API_KEY": "trgv_您的_api_key_在此"
}
}
}
}
```
### VS Code
在工作区中将以下内容添加到 `.vscode/mcp.json` 中：
```json
{
"servers": {
"trigv": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@trigv/mcp"],
"env": {
"TRIGV_API_KEY": "trgv_您的_api_key_在此"
}
}
}
}
```
## 示例
### 基本事件
```json
{ "channel": "general", "title": "来自 MCP 的问候" }
```
### 部署完成（规范）
```json
{
"channel": "deploys",
"title": "生产环境部署完成",
"description": "构建 #42 在 38 秒内成功（提交 abc1234）",
"level": "success",
"delivery_urgency": "standard",
"event_type": "deploy.completed",
"idempotency_key": "deploy-prod-42"
}
```
### 计划任务失败
```json
{
"channel": "alerts",
"title": "夜间备份失败",
"description": "退出代码 1，运行 12 分钟后",
"level": "error",
"event_type": "cron.failed"
}
```
## 开发
```bash
git clone https://github.com/Trigv/trigv-mcp.git
cd trigv-mcp
npm install
npm run build
npm test
```
本地运行：
```bash
TRIGV_API_KEY=trgv_… npm run dev
```
## 测试
```bash
npm test
```
测试使用模拟的 HTTP — 在 CI 中无需实时 API 密钥。
## 贡献
参见 [Trigv SDK 程序](https://github.com/Trigv/trigv-node)，了解 API 合同和一致性要求。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
