# 🎓 NJUPT MCP Server

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-1.7+-green.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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")` |

### 📚 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>