230 lines
4.6 KiB
Markdown
230 lines
4.6 KiB
Markdown
# 🎓 NJUPT MCP Server
|
||
|
||
[](https://www.python.org/downloads/)
|
||
[](https://modelcontextprotocol.io/)
|
||
[](https://opensource.org/licenses/MIT)
|
||
|
||
为 LLM 提供南京邮电大学（NJUPT）相关功能的 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器。
|
||
|
||
本项目几乎完全由 Kimi 生成，感谢 Kimi 🙏
|
||
|
||
## ✨ 功能特性
|
||
|
||
### 🔧 Tools（工具）
|
||
|
||
| 工具名 | 描述 | 示例 |
|
||
|--------|------|------|
|
||
| `get_course_schedule_json` | 获取整学期全部课表数据 | `get_course_schedule_json()` |
|
||
| `get_week_course_schedule_json` | 获取指定教学周的全部课表 | `get_week_course_schedule_json(week=5)` |
|
||
| `get_week_day_course_schedule_json` | 获取指定周和星期的课表 | `get_week_day_course_schedule_json(week=5, day=1)` |
|
||
|
||
### 📚 Resources（资源）
|
||
|
||
| 资源 URI | 描述 |
|
||
|--------|-----|
|
||
| `...` | ... |
|
||
|
||
### 💬 Prompts（提示词模板）
|
||
|
||
| Prompt | 用途 |
|
||
|--------|-----|
|
||
| `...` | ... |
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 环境要求
|
||
|
||
- Python 3.11+
|
||
- [uv](https://docs.astral.sh/uv/)（推荐）或 pip
|
||
|
||
### 2. 安装
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone <your-repo-url>
|
||
cd njupt-mcp
|
||
|
||
# 使用 uv 安装依赖
|
||
uv sync
|
||
|
||
# 或使用 pip
|
||
pip install -e ".[dev]"
|
||
```
|
||
|
||
### 3. 运行
|
||
|
||
#### 方式一：stdio 模式（推荐本地开发）
|
||
|
||
```bash
|
||
# 直接运行
|
||
uv run njupt-mcp
|
||
|
||
# 或
|
||
python -m njupt_mcp.server
|
||
```
|
||
|
||
#### 方式二：SSE 模式（网络服务）
|
||
|
||
```bash
|
||
uv run njupt-mcp --transport sse
|
||
```
|
||
|
||
#### 方式三：streamable-http 模式
|
||
|
||
```bash
|
||
uv run njupt-mcp --transport streamable-http
|
||
```
|
||
|
||
## ⚙️ 客户端配置
|
||
|
||
### Kimi Code CLI 配置
|
||
|
||
编辑 Kimi Code CLI 配置文件（通常位于 `~/.config/kimi-cli/config.toml`）：
|
||
|
||
```toml
|
||
[mcp.servers.njupt-mcp]
|
||
type = "stdio"
|
||
command = "uv"
|
||
args = ["run", "--directory", "/path/to/njupt-mcp", "njupt-mcp"]
|
||
```
|
||
|
||
或使用 SSE 模式：
|
||
|
||
```toml
|
||
[mcp.servers.njupt-mcp]
|
||
type = "sse"
|
||
url = "http://localhost:8000/sse"
|
||
```
|
||
|
||
### Claude Desktop 配置
|
||
|
||
编辑 `claude_desktop_config.json`：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"njupt-mcp": {
|
||
"command": "uv",
|
||
"args": [
|
||
"run",
|
||
"--directory",
|
||
"/path/to/njupt-mcp",
|
||
"njupt-mcp"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### MCP Inspector（调试工具）
|
||
|
||
```bash
|
||
# 启动服务器
|
||
uv run njupt-mcp --transport streamable-http
|
||
|
||
# 在另一个终端启动 Inspector
|
||
npx -y @modelcontextprotocol/inspector
|
||
# 然后访问 http://localhost:5173，连接到 http://localhost:8000/mcp
|
||
```
|
||
|
||
## 🛠️ 开发指南
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
njupt-mcp/
|
||
├── pyproject.toml # 项目配置
|
||
├── src/
|
||
│ └── njupt_mcp/
|
||
│ ├── __init__.py
|
||
│ ├── server.py # MCP 服务器主入口
|
||
│ ├── tools/ # 工具函数目录
|
||
│ ├── resources/ # 资源定义目录
|
||
│ └── utils/ # 工具函数
|
||
├── tests/ # 测试目录
|
||
└── docs/ # 文档目录
|
||
```
|
||
|
||
### 添加新工具
|
||
|
||
在 `src/njupt_mcp/server.py` 中添加：
|
||
|
||
```python
|
||
@mcp.tool()
|
||
async def my_new_tool(param: str) -> str:
|
||
"""工具描述
|
||
|
||
Args:
|
||
param: 参数说明
|
||
|
||
Returns:
|
||
返回值说明
|
||
"""
|
||
# 实现逻辑
|
||
return result
|
||
```
|
||
|
||
### 添加新资源
|
||
|
||
```python
|
||
@mcp.resource("njupt://my-resource")
|
||
async def get_my_resource() -> str:
|
||
"""资源描述"""
|
||
return "资源内容"
|
||
```
|
||
|
||
### 代码检查与格式化
|
||
|
||
```bash
|
||
# 格式化代码
|
||
ruff format .
|
||
|
||
# 检查代码
|
||
ruff check .
|
||
|
||
# 自动修复问题
|
||
ruff check . --fix
|
||
```
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
pytest
|
||
|
||
# 运行特定测试
|
||
pytest tests/test_helpers.py -v
|
||
```
|
||
|
||
## 📝 TODO
|
||
|
||
- [ ] 实现真实的课程数据接口
|
||
- [ ] 实现图书馆 OPAC 系统对接
|
||
- [ ] 添加教务系统登录认证
|
||
- [ ] 添加更多校园生活服务
|
||
- [ ] 完善错误处理和日志记录
|
||
- [ ] 添加数据缓存机制
|
||
|
||
## 🤝 贡献指南
|
||
|
||
1. Fork 本仓库
|
||
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
|
||
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
|
||
4. 推送到分支 (`git push origin feature/amazing-feature`)
|
||
5. 创建 Pull Request
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 [MIT](LICENSE) 许可证。
|
||
|
||
## 🙏 致谢
|
||
|
||
- [Model Context Protocol](https://modelcontextprotocol.io/) - Anthropic 提供的开放协议
|
||
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - 官方 Python SDK
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
Made with ❤️ for NJUPT
|
||
</p>
|