# NGA MCP Server

基于 [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 的 NGA 论坛浏览服务器，允许 AI 助手（如 Claude）直接浏览和搜索 [NGA](https://bbs.nga.cn) 论坛的帖子。

## 功能

| 工具 | 说明 |
|------|------|
| `browse_forum` | 浏览指定版块的帖子列表，支持分页 |
| `browse_post` | 查看指定帖子的详细内容（主帖 + 回复），支持翻页 |
| `search_post` | 按关键词搜索帖子，支持全站或指定版块搜索 |

## 环境要求

- **Python** ≥ 3.10

## 快速开始

### 1. 安装依赖

```bash
pip install -e ".[dev]"
```

### 2. 启动服务

**Windows：** 双击运行 `start.bat`，或在命令行中执行：

```bash
python src/nga_server.py
```

**Linux / macOS：**

```bash
chmod +x start.sh
./start.sh
```

服务默认运行在 `http://0.0.0.0:8001`，MCP 端点为 `/mcp`。

### 3. 配置环境变量（可选）

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `NGA_MCP_HOST` | `0.0.0.0` | 监听地址 |
| `NGA_MCP_PORT` | `8001` | 监听端口 |

## MCP 客户端配置

在 MCP 客户端的配置文件中添加：

```json
{
  "mcpServers": {
    "nga-bbs": {
      "url": "http://localhost:8001/mcp"
    }
  }
}
```

- **Claude Desktop:** 编辑 `claude_desktop_config.json`
- **Claude Code / VS Code 插件:** 编辑项目或用户级的 `mcp.json`

## 工具详情

### browse_forum — 浏览版块

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `fid` | int | 否 | `706` | 版块 ID（706 为大时代） |
| `page` | int | 否 | `1` | 页码 |

### browse_post — 浏览帖子

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `tid` | int | **是** | — | 帖子 ID |
| `page` | int | 否 | `1` | 页码 |

### search_post — 搜索帖子

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `keyword` | string | **是** | — | 搜索关键词 |
| `fid` | int | 否 | `0` | 版块 ID（0 为全站搜索） |
| `page` | int | 否 | `1` | 页码 |

## 项目结构

```
nga_mcp/
├── src/
│   └── nga_server.py    # MCP 服务入口
├── pyproject.toml        # 项目配置与依赖
├── start.bat             # Windows 启动脚本
├── start.sh              # Linux/macOS 启动脚本
└── README.md
```

## 常见问题

### 端口被占用

修改环境变量 `NGA_MCP_PORT` 更换端口，并相应更新 MCP 客户端配置中的 URL。

### 被反爬拦截

NGA 对高频请求有限流和反爬机制。如遇到 `429` 或 `guestJs` 拦截，请稍等片刻再试。

### 页面编码

NGA WAP 页面使用 GBK 编码，服务端会自动处理解码。

## 技术栈

- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) — Streamable HTTP 传输
- [httpx](https://www.python-httpx.org/) — 异步 HTTP 客户端
- [BeautifulSoup4](https://www.crummy.com/software/BeautifulSoup/) + lxml — HTML 解析
- [uvicorn](https://www.uvicorn.org/) — ASGI HTTP 服务器

## License

MIT