MCP Kynhood Events Server

MCP Kynhood事件服务器

模型上下文协议（MCP）服务器，使Claude Desktop能够与Kynhood事件API交互。此服务器提供用于列出事件和检索详细事件信息的工具。

特性

• 自动令牌管理：自动获取和缓存访客令牌
• 智能重试逻辑：通过刷新令牌处理401个错误
• 类型安全：使用TypeScript构建，用于强大的错误处理
• 生产准备就绪：全面的日志记录和错误处理

可用工具

1. listEvents

列出Kynhood API中支持分页的事件。

参数：

• skip （可选，默认值：0）：要跳过的事件数
• limit （可选，默认值：10）：要返回的最大事件数

退货： 包含元数据的事件数组

2. getEventById

获取特定事件的详细信息。

参数：

• id （必填）：事件ID（24个字符的十六进制字符串）

退货： 完整的活动详细信息

安装

先决条件

• Node.js 18+
• npm或纱线
• Claude桌面应用程序

步骤

1. 克隆或创建项目目录：

mkdir mcp-kynhood-events
cd mcp-kynhood-events

1. 安装依赖项：

npm install

1. 配置环境（可选）：

cp .env.example .env

编辑 .env 如果需要自定义设置：

API_BASE_URL=https://***.****.com/api
DEFAULT_SKIP=0
DEFAULT_LIMIT=10
DEBUG=false

运行服务器

发展模式

npm start

构建TypeScript

npm run build

监视模式（自动重启）

npm run dev

连接到克劳德桌面

配置

将此服务器添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kynhood-events": {
      "command": "node",
      "args": [
        "G:\\projects\\mcp\\event\\dist\\index.js"
      ],
      "env": {
        "API_BASE_URL": "https://***.****.com/api"
      }
    }
  }
}

替代方案：直接使用TypeScript（无需构建）：

{
  "mcpServers": {
    "kynhood-events": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "G:\\projects\\mcp\\event\\src\\index.ts"
      ],
      "env": {
        "API_BASE_URL": "https://***.****.com/api"
      }
    }
  }
}

备注：更新路径以匹配您的实际安装目录。

重新启动克劳德桌面

更新配置后，完全退出并重新启动Claude Desktop以使更改生效。

使用示例

连接到Claude Desktop后，您可以使用自然语言与Kynhood Events API进行交互：

查询示例

列出趋势事件：

Show me the latest events from Kynhood

获取特定事件详细信息：

Get details for event 68cd87381ea5

带分页的列表：

Show me events 10-20 from Kynhood (skip 10, limit 10)

多项操作：

List the first 5 events, then show me details for the first one

建筑

项目结构

mcp-kynhood-events/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── api/
│   │   ├── token.ts          # Token fetching logic
│   │   └── events.ts         # Events API calls
│   ├── tools/
│   │   ├── listEvents.ts     # List events tool
│   │   └── getEventById.ts   # Get event by ID tool
│   └── utils/
│       ├── http.ts           # HTTP client with retry logic
│       ├── logger.ts         # Logging utility
│       └── tokenCache.ts     # In-memory token cache
├── package.json
├── tsconfig.json
└── README.md

令牌管理流程

1. 首次请求：服务器检查令牌缓存（空）
2. 获取令牌：通话 GET /api/token 获取访客令牌
3. 缓存令牌：存储TTL为55分钟的令牌
4. 使用令牌：附加到所有后续API请求
5. 手柄401：如果令牌过期，则自动获取新令牌并重试

错误处理

• 网络错误：记录并将上下文返回给Claude
• 401未经授权：使用新令牌自动重试一次
• 无效响应：验证响应结构并提供有意义的错误
• 缺少参数：在API调用之前验证所需的参数

使用的API端点

1.获取访客令牌

GET https://***.****.com/api/token

返回用于访客身份验证的JWT令牌。

2.列出事件

POST https://***.****.com/api/events?skip=0&limit=10
Authorization: Bearer 
Body: {}

返回事件的分页列表。

3.按ID获取事件

GET https://***.****.com/api/events/:eventId
Authorization: Bearer 

返回详细的事件信息。

发展

添加新工具

1. 在中创建工具文件 src/tools/
2. 定义输入/输出接口
3. 执行工具功能
4. 导出工具定义
5. 注册 src/index.ts

调试

启用调试日志记录：

DEBUG=true

日志输出到stderr（在Claude Desktop日志中可见）。

故障排除

服务器未出现在Claude桌面中

1. 检查配置文件路径是否正确
2. 验证JSON语法 claude_desktop_config.json
3. 确保文件路径使用绝对路径
4. 完全重新启动克劳德桌面

令牌错误

• 服务器自动处理令牌刷新
• 检查API_BASE_URL是否正确
• 验证与api.kynhood.com的网络连接

构建错误

# Clean and reinstall
rm -rf node_modules dist
npm install
npm run build

手动测试API

您可以直接测试Kynhood API端点：

# Get token
curl https://***.****.com/api/token

# List events (replace TOKEN with actual token)
curl -X POST "https://***.****.com/api/events?skip=0&limit=10" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d "{}"

# Get event by ID
curl "https://***.****.com/api/events/68cd8a9496a5" \
  -H "Authorization: Bearer TOKEN"

许可证

麻省理工学院

支持

对于问题或疑问：

• 检查Claude Desktop中的日志
• 验证API连接： curl https://***.****.com/api/token
• 查看此README以了解配置步骤