init
This commit is contained in:
231
README.md
Normal file
231
README.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# 🎓 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/) 服务器。
|
||||
|
||||
## ✨ 功能特性
|
||||
|
||||
### 🔧 Tools（工具）
|
||||
|
||||
| 工具名 | 描述 | 示例 |
|
||||
|--------|------|------|
|
||||
| `search_course` | 搜索课程信息 | `search_course("数据结构")` |
|
||||
| `get_course_schedule` | 获取学生课表 | `get_course_schedule("B21010101", "2024-2025-1")` |
|
||||
| `search_library_book` | 搜索图书馆藏书 | `search_library_book("Python", "title")` |
|
||||
| `get_campus_info` | 获取校园信息 | `get_campus_info("contacts")` |
|
||||
|
||||
### 📚 Resources（资源）
|
||||
|
||||
| 资源 URI | 描述 |
|
||||
|----------|------|
|
||||
| `njupt://announcements` | 最新公告列表 |
|
||||
| `njupt://academic-calendar` | 校历信息 |
|
||||
| `njupt://departments` | 学院/部门列表 |
|
||||
|
||||
### 💬 Prompts（提示词模板）
|
||||
|
||||
| Prompt | 用途 |
|
||||
|--------|------|
|
||||
| `academic_advisor_query` | 学业咨询助手 |
|
||||
| `campus_guide_query` | 校园导航助手 |
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 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 --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
#### 方式三：streamable-http 模式
|
||||
|
||||
```bash
|
||||
uv run njupt-mcp --transport streamable-http --port 8000
|
||||
```
|
||||
|
||||
## ⚙️ 客户端配置
|
||||
|
||||
### 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>
|
||||
Reference in New Issue
Block a user