内容
# MCP Meetup-Claude 集成服务器
## 概述
这是一个生产级别的模型通信协议（MCP）服务器，它将 Meetup.com 的活动发现 API 与 Anthropic 的 Claude 大型语言模型（LLM）无缝集成。服务器实现了智能活动发现、自然语言查询和基于 AI 的 Meetup 活动推荐。
## 架构
### 核心组件
1. **MCP 协议处理器**（`MeetupClaudeMCPServer`）
- 管理客户端连接和工具定义
- 处理资源管理和服务器生命周期
- 提供标准化的 MCP 接口
2. **身份验证管理器**（`AuthenticationManager`）
- Meetup.com 的 OAuth2 流实现
- Token 生命周期管理和刷新
- 安全的凭证处理
3. **活动发现引擎**（`EventDiscoveryEngine`）
- 自然语言查询参数提取
- 双 API 支持（REST 和 GraphQL）
- 智能活动过滤和排名
4. **提示增强服务**（`PromptAugmentationService`）
- 上下文感知提示增强
- LLM 消耗的活动数据格式化
- 智能相关性过滤
5. **Claude 集成**（`ClaudeIntegration`）
- Anthropic API 客户端管理
- 响应生成和错误处理
- 可配置的模型参数
### 数据流
```
用户查询 → 参数提取 → 活动发现 → 数据增强 → Claude 处理 → 响应
```
## 快速入门
### 前提条件
- Python 3.8+
- Meetup.com 账户
- Anthropic API 账户
### 安装
```bash
# 克隆或下载项目
cd /home/daniel/work/mcp-meetup
# 安装依赖
pip install -r requirements.txt
# 配置环境
cp .env.example .env
# 使用您的凭证编辑 .env
# 运行服务器
python meetup_claude_mcp_server.py
```
## API 设置说明
### 1. Meetup.com OAuth 设置
1. 访问 [Meetup OAuth 消费者](https://secure.meetup.com/meetup_api/oauth_consumers/)
2. 点击 "创建新消费者"
3. 填写应用程序详细信息：
- **应用程序名称**：您的应用程序名称
- **应用程序网站**：您的网站或 GitHub 仓库
- **重定向 URI**：`http://localhost:8080/oauth/callback`
- **应用程序描述**：您的用例简要描述
4. 保存生成的：
- **客户端 ID**
- **客户端密钥**
### 2. Anthropic API 设置
1. 访问 [Anthropic 控制台](https://console.anthropic.com/)
2. 创建账户或登录
3. 导航到 API 密钥部分
4. 生成新的 API 密钥
5. 安全复制 API 密钥
### 3. 环境配置
`.env` 中所需的环境变量：
```bash
MEETUP_CLIENT_ID=您的_meetup_client_id
MEETUP_CLIENT_SECRET=您的_meetup_client_secret
ANTHROPIC_API_KEY=您的_anthropic_api_key
```
可选配置：
```bash
MEETUP_ACCESS_TOKEN=如果可用，则为您的访问令牌
MEETUP_REDIRECT_URI=http://localhost:8080/oauth/callback
LOG_LEVEL=INFO
MAX_EVENTS_PER_QUERY=20
DEFAULT_RADIUS=25
```
## MCP 工具
### 1. `search_meetup_events`
使用自然语言查询搜索 Meetup 活动。
**参数：**
- `query`（字符串，必填）：自然语言搜索查询
- `max_results`（整数，可选）：返回的最大活动数（默认：20）
**示例：**
```json
{
"query": "本周在旧金山的 Python 编程活动",
"max_results": 10
}
```
### 2. `augment_prompt_with_events`
使用相关活动数据增强用户提示。
**参数：**
- `prompt`（字符串，必填）：要增强的用户提示
**示例：**
```json
{
"prompt": "这个周末我应该参加哪些编程活动？"
}
```
### 3. `get_event_recommendations`
使用 Claude 和活动上下文获取 AI 驱动的活动推荐。
**参数：**
- `query`（字符串，必填）：推荐的自然语言查询
- `preferences`（字符串，可选）：其他偏好或约束
**示例：**
```json
{
"query": "我对机器学习和网络活动感兴趣",
"preferences": "优先选择免费活动，愿意 travel 最多 30 英里"
}
```
### 4. `get_oauth_url`
获取 Meetup OAuth 授权 URL 进行身份验证设置。
**参数：** 无
## MCP 资源
### 1. `meetup://config`
当前服务器配置和状态信息。
### 2. `meetup://auth/status`
与 Meetup.com 的身份验证状态，包括令牌有效性。
## 自然语言查询示例
服务器智能地从自然语言中提取参数：
**基于时间的查询：**
- "今天的活动"
- "明天有什么活动"
- "本周的活动"
**基于位置的查询：**
- "附近的活动"
- "旧金山的聚会"
- "仅远程活动"
**基于主题的查询：**
- "Python 编程聚会"
- "数据科学活动"
- "初创企业交流"
- "AI 和机器学习"
**组合查询：**
- "附近今天的 Python 活动"
- "本周远程数据科学聚会"
- "旧金山免费的交流活动"
## 错误处理
服务器包含全面的错误处理：
- **身份验证错误**：缺少凭证、令牌过期
- **API 错误**：速率限制、网络故障、无效查询
- **数据处理错误**：活动格式错误、结果为空
## 安全考虑
- 环境变量配置防止凭证暴露
- OAuth2 流实现遵循安全最佳实践
- 没有持久存储用户查询或个人数据
- 可配置的日志记录级别以控制信息暴露
## 开发
### 项目结构
```
mcp-meetup/
├── meetup_claude_mcp_server.py # 主要服务器实现
├── requirements.txt # Python 依赖项
├── .env.example # 环境配置模板
├── README.md # 本文档
├── docs/ # 附加文档
│ └── adr/ # 架构决策记录
└── tests/ # 测试文件（未来）
```
### 测试
可以通过运行服务器和使用 MCP 客户端工具进行基本测试：
```bash
# 启动服务器
python meetup_claude_mcp_server.py
# 在另一个终端，使用 MCP 客户端测试
# （MCP 客户端实现将位于此处）
```
### 扩展服务器
模块化设计使其易于扩展：
1. **附加 API**：在 `EventDiscoveryEngine` 中添加其他活动平台
2. **增强过滤**：扩展 `extract_query_parameters` 方法
3. **缓存**：在 `PromptAugmentationService` 中添加 Redis 或内存缓存
4. **附加工具**：在 `_setup_tools` 方法中添加新的 MCP 工具
## 故障排除
### 常见问题
1. **身份验证失败**
- 验证客户端 ID 和密钥是否正确
- 检查重定向 URI 是否与 OAuth 消费者设置匹配
- 确保访问令牌未过期
2. **未找到活动**
- 尝试更广泛的搜索词
- 检查位置拼写和格式
- 验证时间参数是否合理
3. **API 速率限制**
- 减少查询频率
- 实现请求缓存
- 检查 API 配额使用情况
4. **Claude 集成错误**
- 验证 Anthropic API 密钥是否有效
- 检查 API 配额和计费状态
- 审查提示长度和复杂性
### 调试模式
启用调试日志：
```bash
export LOG_LEVEL=DEBUG
python meetup_claude_mcp_server.py
```
### 健康检查
使用 MCP 资源检查服务器状态：
```bash
# 检查配置
# 使用 MCP 客户端读取 meetup://config
# 检查身份验证状态
# 使用 MCP 客户端读取 meetup://auth/status
```
## 贡献
### 开发工作流
1. 复刻仓库
2. 创建功能分支
3. 实现变更并附上测试
4. 更新文档
5. 提交拉取请求
### 代码标准
- 遵循 PEP 8 样式指南
- 在整个代码中使用类型提示
- 维护全面的文档字符串
- 为新功能添加单元测试
## 许可证
MIT 许可证 - 参见 LICENSE 文件获取详细信息。
## 支持
如有问题：
1. 检查故障排除部分
2. 审查配置和设置
3. 创建详细的错误报告并附上日志
4. 包括重现步骤和环境详细信息
---
**版本**：1.0.0
**最后更新**：2025-07-27
**作者**：为 Dan Shields 生成
