内容
# Luma 事件 MCP 服务器
开源的 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器，用于管理来自与 MCP 兼容的 AI 客户端的 Luma 事件。
服务器连接到与您的 Luma API 密钥关联的日历。它可以列出和检查事件，创建或更新事件（需明确确认），检查嘉宾注册情况，并返回注重隐私的注册摘要。
## 功能
- 验证已配置的 Luma API 连接。
- 列出已批准或待处理的 日历事件。
- 检索事件的完整详细信息。
- 创建事件（需明确用户确认）。
- 更新事件详细信息和注册设置（需明确确认）。
- 列出事件嘉宾。
- 统计注册状态和签到情况（不暴露嘉宾身份）。
- 生成注册摘要时自动分页。
写入操作需要 `confirmed` 值作为保护。MCP 客户端应向用户显示拟议的事件详细信息，并在调用写入工具之前获得明确的批准。
## 截图
### 发现可用功能
### 列出即将到来的事件
### 分析嘉宾出席情况
嘉宾身份已从此公开示例中删除。
## 可用工具
### `verify_connection`
检查 API 密钥并返回已认证的 Luma 用户。
### `list_events`
列出日历事件。支持日期范围、审批状态、分页限制和分页游标。
### `get_event`
返回单个事件的完整详细信息。
### `create_event`
创建事件（需明确确认）。支持事件名称、日期、时区、描述、容量、在线会议网址、物理位置、可见性、注册、候补名单和嘉宾名单设置。
### `update_event`
更新选定的事件字段（需明确确认）。
### `list_guests`
列出事件嘉宾，可选按审批状态过滤。此工具可能返回个人信息，仅应用于合法的事件操作。
### `registration_summary`
按注册状态返回总数和已签到嘉宾人数，不暴露姓名或电子邮件地址。
## 要求
- Node.js 20 或更新版本
- [pnpm](https://pnpm.io/)
- 具有 API 访问权限的 Luma 日历
- Luma API 密钥
- 与 MCP 兼容的客户端，如 Cursor 或 Codex
## 获取 Luma API 密钥
按照 [Luma API 文档](https://docs.lu.ma/reference/getting-started-with-your-api) 中的说明生成日历 API 密钥。该密钥决定了服务器可以访问哪个日历。
请像对待密钥一样保护该密钥。永远不要将其提交到代码库中、在截图中显示或直接放在受跟踪的 MCP 配置文件中。
## 安装
克隆代码库并进入此插件目录：
```bash
git clone https://github.com/Blackie360/luma-events-mcp.git
cd luma-events-mcp
```
安装依赖项并构建服务器：
```bash
corepack enable
pnpm install
pnpm build
```
生产入口点生成在 `dist/index.js`。
## 配置
服务器需要以下环境变量：
```bash
export LUMA_API_KEY="your-luma-api-key"
```
可以为测试或兼容的代理提供可选的 API 基地址：
```bash
export LUMA_API_BASE="https://public-api.luma.com"
```
服务器不会自动加载 `.env` 文件。在本地开发时，您可以创建一个被忽略的 `.env` 文件，并在运行服务器之前将其加载到您的 shell 中：
```bash
set -a
source .env
set +a
```
`.env` 示例：
```dotenv
LUMA_API_KEY=your-luma-api-key
```
## 在本地运行
构建并启动 stdio MCP 服务器：
```bash
pnpm build
pnpm start
```
该进程通过标准输入和输出进行通信，因此直接启动时它通常看起来是空闲的。预计 MCP 客户端将启动并与其通信。
## 连接 MCP 客户端
配置您的客户端以使用 Node.js 运行内置服务器。除非客户端支持工作目录选项，否则请使用绝对路径。
```json
{
"mcpServers": {
"luma-events": {
"command": "node",
"args": ["/absolute/path/to/plugins/luma-events/dist/index.js"]
}
}
}
```
在启动 MCP 客户端的环境中提供 `LUMA_API_KEY`，或使用客户端的安全密钥/环境变量配置。在更新环境或 MCP 配置后，请重启客户端。
此代码库还包含：
- `.mcp.json`，适用于支持插件提供的 MCP 配置的客户端。
- `.codex-plugin/plugin.json`，包含 Codex 插件元数据。
连接后，请要求客户端运行 `verify_connection`，然后再使用其他工具。
## 示例提示
- "验证我的 Luma 连接。"
- "显示我的即将到来的 Luma 事件。"
- "显示下一个事件的详细信息。"
- "汇总我的下一个事件的注册情况。"
- "准备一个星期五下午 5 点的活动，但在我确认之前不要创建它。"
- "在向我显示拟议的更改后，关闭此活动的注册。"
## 开发
运行 TypeScript 编译器检查：
```bash
pnpm check
```
构建项目：
```bash
pnpm build
```
运行测试套件：
```bash
pnpm test
```
测试套件涵盖了写入确认、API 错误报告、注册分页和注重隐私的摘要。
## 项目结构
```text
.
├── .codex-plugin/plugin.json # Codex 插件元数据
├── .mcp.json # 插件 MCP 服务器配置
├── src/index.ts # MCP 服务器和 Luma API 集成
├── src/index.test.ts # Node.js 测试
├── package.json # 脚本和依赖项
└── tsconfig.json # TypeScript 配置
```
## 安全和隐私
- 永远不要提交 `LUMA_API_KEY` 或任何 `.env` 文件。
- 在确认写入操作之前，请审查请求更改。
- 仅在必要时使用 `list_guests` 获取嘉宾级数据。
- 当仅需要汇总计数时，请优先使用 `registration_summary`。
- 保持依赖项更新，并向维护人员私下报告漏洞。
## 贡献
欢迎贡献：
1. 分叉代码库。
2. 创建一个专注的分支。
3. 为您的更改添加或更新测试。
4. 运行 `pnpm check` 和 `pnpm test`。
5. 打开一个拉取请求，解释更改及其动机。
请避免在问题、测试、提交或拉取请求中包含 API 密钥、嘉宾信息或其他私人活动数据。
## API
服务器使用 Luma 的官方 API，地址为 `https://public-api.luma.com`。API 密钥的作用范围限定在日历和 Luma 中配置的权限内。
## 许可证
该项目在 [MIT License](LICENSE) 下可用。
