内容
# 事件公共MCP服务器
用于Evento开发者面向的公共API的本地MCP服务器。
它在您的机器上通过stdio运行，使用您的API密钥验证每个API调用，并且可以与Claude Desktop（或任何支持stdio传输的MCP客户端）连接。
## 服务器概述
- 仅MCP传输适配器（stdio）
- 工具调用映射到Evento公共API路由
- 使用您的API密钥集中注入身份验证
- 在MCP层中无数据库访问，无Supabase，无服务器端持久性
该架构与admin MCP模式相同，但具有不同的API路由和密钥类型。
## 功能
- `列出事件`
- 列出用户事件
- 可选过滤器：`类型`，`限制`
- `获取事件`
- 按ID获取事件
## 要求
- Node.js 18+
- npm
- Evento开发者API密钥
- MCP客户端（Claude Desktop，Cursor等）
## 快速入门
```bash
git clone https://github.com/andreneves/evento-public-mcp.git
cd evento-public-mcp
npm install
npm run build
```
创建环境文件：
```bash
cp .env.example .env
```
至少设置：
- `公共API密钥`
然后运行：
```bash
npm start
```
## 安装技能（`SKILL.md`）
该存储库在以下位置包含一个可安装的Claude技能文件：
- `SKILL.md`
在本地安装：
```bash
mkdir -p ~/.claude/skills/evento-public-mcp
cp SKILL.md ~/.claude/skills/evento-public-mcp/SKILL.md
```
规范来源和文档：
- 技能文件：`https://github.com/andreneves/evento-public-mcp/blob/main/SKILL.md`
- 文档页面：`https://docs.evento.so/mcp-server/skill`
### 版本控制和同步策略
- 真相来源是此存储库的`SKILL.md`
- 更新技能行为或说明时，首先更新`SKILL.md`
- 保持文档镜像页面的同步：`evento-docs/ai/skill.mdx`
- 为有意义的内容更改增加`SKILL.md`中的`metadata.version`
- 在发布前验证文档页面是否反映完整的文件内容
## 环境变量
必需：
- `公共API密钥`
- 用作`Authorization: Bearer <key>`的面向开发者的Evento API密钥
可选：
- `EVENTO_API_BASE_URL`（默认值：`https://evento.so/api`）
- `EVENTO_API_TIMEOUT_MS`（默认值：`15000`）
- `EVENTO_API_RETRY_ATTEMPTS`（默认值：`2`）
- `EVENTO_API_RETRY_DELAY_MS`（默认值：`250`）
- `EVENTO_PUBLIC_API_KEY`（如果缺少`PUBLIC_API_KEY`时的遗留兼容性备用）
- `EVENTO_SMOKE_USERNAME`（由smoke命令使用）
## MCP客户端配置
Claude Desktop配置示例（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"evento-public": {
"command": "node",
"args": ["/absolute/path/to/evento-public-mcp/dist/index.js"],
"env": {
"PUBLIC_API_KEY": "your-evento-api-key",
"EVENTO_API_BASE_URL": "https://evento.so/api"
}
}
}
}
```
注意：
- 在`args`中使用绝对路径
- 配置更改后重启Claude Desktop
## 可用工具
### `列出事件`
列出用户的事件。
输入：
- `用户名`（必填，字符串）
- `类型`（可选，`upcoming | past | profile`）
- `限制`（可选，数字）
路由映射：
- `GET /public/v1/users/{username}/events`
### `获取事件`
按ID获取事件详情。
输入：
- `eventId`（必填，字符串）
路由映射：
- `GET /public/v1/events/{eventId}`
## 架构
关键文件：
- `src/index.ts`
- 进程入口点
- `src/mcp-server.ts`
- MCP协议处理（`tools/list`，`tools/call`）
- `src/public-tools.ts`
- 单运行时注册表（`PUBLIC_TOOLS`）
- 泛型执行器（`executePublicTool`）
- 身份验证/头部注入，路径插值，超时/重试，规范化响应
- `PUBLIC_MCP.tools.json`
- 运行时工具的清单镜像
执行流程：
1. MCP客户端调用`tools/list`
2. 服务器返回`PUBLIC_TOOLS`
3. MCP客户端调用`tools/call`
4. 服务器委托给`executePublicTool(name, args)`
5. 执行器验证必填参数，解析路径占位符，从正文中剥离路径参数
6. 执行器使用身份验证头部和重试/超时策略调用Evento API
7. 执行器将成功/错误有效载荷规范化回MCP响应
## 本地开发
安装依赖：
```bash
npm install
```
在TypeScript中直接运行：
```bash
npm run dev
```
构建：
```bash
npm run build
```
运行构建的服务器：
```bash
npm start
```
## 测试和验证
运行测试：
```bash
npm test
```
运行构建 + 测试：
```bash
npm run verify
```
烟雾检查（实时API）：
```bash
EVENTO_SMOKE_USERNAME=your-username npm run smoke
```
测试层包括：
- 单元：`tests/public-tools.unit.test.ts`
- 清单一致性：`tests/manifest-parity.test.ts`
- MCP stdio 端到端：`tests/mcp.e2e.test.ts`
## 添加新工具
1. 在`src/public-tools.ts`中将新工具定义添加到`PUBLIC_TOOLS`
- 名称，描述，方法，路径，输入模式
2. 确保路由/路径占位符与参数一致
3. 更新`PUBLIC_MCP.tools.json`以匹配
4. 添加/扩展单元测试和一致性断言
5. 运行`npm run verify`
## 错误处理和重试策略
- 重试可重试状态：`408`，`429`，`5xx`
- 重试可重试网络错误（超时/DNS/连接重置类）
- 由环境变量控制（`EVENTO_API_RETRY_*`）
- 当失败时，使用结构化错误有效载荷返回MCP `isError: true`
## 故障排除
### 缺少API密钥
症状：
- 工具调用返回缺少密钥错误
修复：
- 在MCP客户端环境配置中设置`PUBLIC_API_KEY`
### 客户端中工具不可见
修复检查清单：
1. 运行`npm run build`
2. 确认`dist/index.js`存在
3. 确认MCP配置中的绝对路径
4. 重启MCP客户端应用程序
### API错误
修复检查清单：
1. 验证密钥是否对已验证的公共端点有效
2. 验证`EVENTO_API_BASE_URL`
3. 使用已知用户名运行烟雾检查
## 安全说明
- 将API密钥保留在本地环境配置中，而不是源代码控制中
- 该项目不会在进程环境变量之外存储您的API密钥
## 许可证
ISC
