# 开发指南

本文档介绍如何开发和扩展 NJUPT MCP Server。

## 架构概述

```
┌─────────────────┐
│   MCP Client    │  (Kimi Code CLI, Claude Desktop, etc.)
│  (Kimi, Claude) │
└────────┬────────┘
         │ MCP Protocol (stdio / SSE)
         ▼
┌─────────────────┐
│   njupt-mcp     │
│  (FastMCP)      │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│ Tools │ │Resources│
└───┬───┘ └───┬───┘
    │         │
    ▼         ▼
┌───────┐ ┌───────┐
│ NJUPT │ │ Static│
│ APIs  │ │ Data  │
└───────┘ └───────┘
```

## 添加新功能

### 1. 添加工具 (Tool)

工具用于执行操作、调用 API。在 `src/njupt_mcp/server.py` 中添加：

```python
@mcp.tool()
async def my_tool(param1: str, param2: int = 10) -> str:
    """工具的描述，会显示给 LLM
    
    详细说明工具的用途、使用场景等。
    
    Args:
        param1: 参数1的描述
        param2: 参数2的描述，默认为 10
    
    Returns:
        返回值的描述，通常是 JSON 字符串
    
    Example:
        my_tool("test", 20) -> 返回结果
    """
    # 实现逻辑
    result = {"param1": param1, "param2": param2}
    return json.dumps(result, ensure_ascii=False)
```

**最佳实践：**

- 使用 `async def` 定义异步函数
- 提供详细的文档字符串（LLM 依赖此信息决定是否调用）
- 使用类型注解
- 返回 JSON 字符串便于 LLM 解析
- 处理异常情况，返回友好的错误信息

### 2. 添加资源 (Resource)

资源用于提供数据、文档等只读内容：

```python
@mcp.resource("njupt://resource-name")
async def get_resource() -> str:
    """资源的描述"""
    return "资源内容"
```

资源 URI 格式：`scheme://path`，建议使用 `njupt://` 作为 scheme。

### 3. 添加提示词模板 (Prompt)

提示词模板用于生成特定场景的提示词：

```python
@mcp.prompt()
def my_prompt(context: str, question: str) -> str:
    """提示词模板的描述"""
    return f"""基于以下上下文：
{context}

请回答：{question}
"""
```

## 数据获取实现

目前示例代码使用硬编码数据，实际应用中需要对接 NJUPT 的数据源：

### 教务系统

```python
import httpx

async def fetch_course_data(course_code: str) -> dict:
    """从教务系统获取课程数据"""
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://jw.njupt.edu.cn/api/course",
            params={"code": course_code},
            cookies={"session": await get_session()}
        )
        response.raise_for_status()
        return response.json()
```

### 图书馆 OPAC

```python
async def search_library(keyword: str) -> list[dict]:
    """搜索图书馆 OPAC 系统"""
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "http://opac.njupt.edu.cn/opac/search",
            params={"q": keyword}
        )
        # 解析 HTML 或 JSON
        return parse_search_results(response.text)
```

## 测试

### 运行测试

```bash
# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/test_helpers.py -v

# 运行并生成覆盖率报告
pytest --cov=njupt_mcp --cov-report=html
```

### 编写测试

```python
# tests/test_new_feature.py
import pytest
from njupt_mcp.server import my_new_tool

@pytest.mark.asyncio
async def test_my_tool():
    result = await my_tool("test", 20)
    assert "test" in result
    assert "20" in result
```

## 调试技巧

### 使用 MCP Inspector

```bash
# 启动服务器
uv run njupt-mcp --transport streamable-http

# 启动 Inspector
npx -y @modelcontextprotocol/inspector
```

访问 http://localhost:5173 进行交互式调试。

### 启用调试日志

```bash
uv run njupt-mcp --debug
```

### 手动测试工具

```python
# test_manual.py
import asyncio
from njupt_mcp.server import search_course

async def main():
    result = await search_course("数据结构")
    print(result)

if __name__ == "__main__":
    asyncio.run(main())
```

## 部署

### 本地部署

使用 `uv` 运行：

```bash
uv run njupt-mcp
```

### Docker 部署

```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install -e "."

EXPOSE 8000

CMD ["njupt-mcp", "--transport", "sse", "--host", "0.0.0.0"]
```

### 云服务部署

适合使用 SSE 或 streamable-http 模式，部署到：

- [Railway](https://railway.app/)
- [Render](https://render.com/)
- [Fly.io](https://fly.io/)

## 性能优化

### 添加缓存

```python
from functools import lru_cache
import asyncio
from cachetools import TTLCache

# 使用 TTLCache 缓存结果
course_cache = TTLCache(maxsize=100, ttl=3600)

@mcp.tool()
async def search_course(keyword: str) -> str:
    if keyword in course_cache:
        return course_cache[keyword]
    
    result = await fetch_course_from_api(keyword)
    course_cache[keyword] = result
    return result
```

### 并发请求

```python
async def fetch_multiple_courses(course_codes: list[str]) -> list[dict]:
    async with httpx.AsyncClient() as client:
        tasks = [fetch_course(client, code) for code in course_codes]
        return await asyncio.gather(*tasks)
```