内容
# Duke MCP (多用途通信协议)
## 项目概述
Duke MCP 是一个统一的后端服务器，通过 OpenWebUI 提供对各种杜克大学服务的自然语言访问。该系统允许用户通过简单的对话查询与大学资源进行交互，而无需浏览复杂的 API 或网页界面。
MCP 作为杜克现有数据服务与大型语言模型（LLM）接口之间的中间件层，提供智能缓存、数据转换和系统间的集成。
## 核心组件
Duke MCP 目前集成了三个主要服务：
### 1. 日历 MCP
日历 MCP 提供对杜克大学事件日历系统的访问，允许用户以自然语言查询校园活动。
**主要特性：**
- 自然语言时间解析（例如，“这个周末”，“下周一”）
- 事件过滤和分类
- 简化的数据表示以减少令牌使用
- 智能处理大型结果集
**策略：**
我们的日历 MCP 方法解决了杜克日历系统的几个挑战：
- **数据量与质量**：我们通过实施简化的数据模型来处理成千上万的团体/赞助商（许多是孤立的）、数百个临时类别和不一致的数据录入。数据源非常糟糕，处理起来如同噩梦。
- **复杂层级**：我们利用 LLM 理解查询意图的能力，而不是苦苦挣扎于传统的过滤方法，以匹配相关事件。
- **时间绑定数据**：我们提供原生时间表达处理，将自然语言转换为 API 参数。
### 2. 目录 MCP
目录 MCP 连接到杜克的 LDAP 目录服务，使查找杜克社区成员的联系信息变得简单。
**主要特性：**
- 基于姓名和 NetID 的搜索
- 详细的联系信息检索
- 高效的缓存以减少对杜克 LDAP 服务的负载
- 注重隐私的数据展示
**策略：**
目录 MCP 采用直接的方法提供联系信息：
- **数据简化**：我们提取并展示最有用的联系细节。
- **高效缓存**：目录信息变化不频繁，因此积极的缓存减少了对杜克系统的负载。
- **姓名解析**：我们优化了最常见的用例——通过姓名查找某人，并提供 NetID 搜索的后备方案。
### 3. 学者 MCP
学者 MCP 提供对杜克学术数据库的访问，使用户能够查询研究、出版物和资助信息。
**主要特性：**
- 与目录集成以查找 DUID
- 出版物和资助信息检索
- 研究档案访问
- 复杂数据提取和格式化
**策略：**
学者 MCP 解决了独特的挑战：
- **两阶段查找**：我们处理从目录中首先查找 DUID 的复杂性，然后使用它进行学者查询，使用户感知不到这一过程。
- **数据复杂性**：学者 API 返回深度嵌套的复杂数据结构，我们智能解析以提取最相关的信息。
- **关联展示**：我们将传记信息与研究兴趣、出版物和资助连接起来，创建全面的档案。
## 技术架构
### 核心设计原则
1. **模块化组件**：每个服务都有专用的模型、MCP 实现和路由。
2. **共享基础设施**：所有组件在同一服务器上运行，模式一致。
3. **智能缓存**：基于时间的缓存减少了对杜克服务的负载。
4. **原生功能支持**：针对 OpenWebUI 的原生功能能力进行了优化。
### 服务器结构
```
duke-mcp/
├── app/
│ ├── mcp/
│ │ ├── __init__.py
│ │ ├── calendar.py
│ │ ├── directory.py
│ │ └── scholars.py
│ ├── models/
│ │ ├── __init__.py
│ │ ├── calendar.py
│ │ ├── directory.py
│ │ └── scholars.py
│ ├── routers/
│ │ ├── calendar.py
│ │ ├── directory.py
│ │ └── scholars.py
│ ├── __init__.py
│ ├── config.py
│ └── main.py
├── duke_calendar_tool.py
├── duke_directory_tool.py
├── duke_scholars_tool.py
├── requirements.txt
├── .env
└── README.md
```
### 组件架构
每个服务组件遵循相同的架构模式：
1. **模型**：定义 API 请求和响应的数据结构
2. **MCP 实现**：业务逻辑、API 通信和缓存
3. **API 路由**：FastAPI 端点用于访问服务
4. **OpenWebUI 工具**：客户端工具用于与 MCP 交互
### 缓存策略
为了减少对杜克服务的负载并提高性能，我们实施了基于时间的缓存系统：
- **基于 TTL 的缓存**：数据以可配置的生存时间（默认：1 小时）进行缓存
- **缓存键**：结构化以允许细粒度的失效
- **服务特定缓存**：每个 MCP 组件实现针对其数据模式的缓存
## OpenWebUI 集成
### 原生功能
每个 MCP 组件都配有一个 OpenWebUI 工具，提供：
1. 针对服务特定查询的专用功能
2. 清晰的 LLM 指令
3. 错误处理和后备策略
4. 用户友好的响应格式
### LLM 策略
我们与 LLM 合作的方法包括：
- **清晰指令**：为每个工具定义明确的使用步骤
- **上下文示例**：常见查询模式以指导 LLM
- **格式指南**：如何展示不同类型的结果
- **教育提示**：帮助 LLM 理解领域上下文
## 安装与设置
### 先决条件
- Python 3.8 或更高版本
- FastAPI 和 Uvicorn
- 访问杜克 API 服务
### 配置
创建一个 `.env` 文件，包含以下变量：
```
# 一般设置
DEBUG=False
REFERENCE_CACHE_TTL=3600
# 日历 API
DUKE_CALENDAR_API_URL=https://calendar.duke.edu/events/index.json
# 目录 API
DUKE_DIRECTORY_API_KEY=your_directory_api_key
DUKE_DIRECTORY_BASE_URL=https://streamer.oit.duke.edu/ldap/people
# 学者 API
DUKE_SCHOLARS_BASE_URL=https://scholars.duke.edu/widgets/api/v0.9
```
### 运行服务器
```bash
uvicorn app.main:app --host 0.0.0.0 --port 8000
```
对于生产环境，您可能希望使用 Gunicorn 和 Uvicorn 工作进程：
```bash
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
```
### OpenWebUI 工具设置
1. 将每个工具文件导入到您的 OpenWebUI 安装中
2. 更新每个工具中的 `mcp_url`，指向您的 MCP 服务器
## API 文档
当服务器运行时，交互式 API 文档可在 `/docs` 访问。
### 日历端点
- `GET /api/v1/calendar/simplified-events`：获取日期范围内的事件
- `POST /api/v1/calendar/events-by-local-ids`：通过 ID 获取完整事件详情
### 目录端点
- `GET /api/v1/directory/search`：搜索目录
- `GET /api/v1/directory/person/{ldapkey}`：获取详细的个人信息
- `GET /api/v1/directory/netid/{netid}`：通过 NetID 搜索
- `GET /api/v1/directory/name/{name}`：通过姓名搜索
### 学者端点
- `GET /api/v1/scholars/details`：获取学者档案
- `GET /api/v1/scholars/publications`：获取学者出版物
- `GET /api/v1/scholars/grants`：获取学者资助
## 未来发展
### 计划组件
1. **课程 MCP**：访问课程信息和时间表
2. **地图 MCP**：建筑位置和方向
3. **餐饮 MCP**：餐饮地点和菜单
### 路线图
1. **增强集成**：组件之间更深层次的连接（例如，事件位置链接到地图）
2. **高级缓存**：更复杂的缓存策略，带有选择性失效
3. **个性化**：用户特定的定制和偏好
4. **分析**：使用跟踪以提高服务质量
## 贡献
欢迎贡献！请随时提交 Pull Request。
## 许可证
本项目根据 MIT 许可证授权 - 详见 LICENSE 文件。
MCP 市场