# 化竞50：全国中学生化学竞赛数据 MCP 与 Agent Skill

**Huajing50 — Chinese Chemistry Olympiad data for AI agents.** 查询中国化学奥林匹克竞赛（化竞）的历届获奖、学校与省份表现、学生跨届轨迹，以及国家集训队和国家队名单。适合学生、家长、教练和研究者用自然语言探索竞赛数据，并追溯收录来源。

[化竞50网站](https://huajing50.com) · [Agent Skill](./skill/huajing50/SKILL.md) · [MIT 许可证](./LICENSE)

> 本仓库只开源 **MCP 接入服务端和 Agent Skill**，不包含网站源码、查询后端、数据库、学生资料或密钥。竞赛数据由化竞50在线服务提供；使用数据工具需要注册并使用自己的 API Key。本项目不隶属于中国化学会。

## 可以问什么

- “第39届决赛金牌有哪些学校？按人数排序。”
- “某学校近三届获得多少金牌、银牌和省一？与往届相比如何？”
- “某省历届国家集训队和国家队人数是多少？”
- “获得决赛前50名的选手，前一届常见的获奖轨迹是什么？”
- “这条获奖记录对应哪份官方文件？目前收录范围覆盖哪些届次？”

工具支持实体查找、学生／学校／省份档案、获奖名单、排名统计、跨届人群和轨迹分析，以及来源查询。具体工具参数由服务端实时提供。数据覆盖并非每届、每种奖项都一样完整；**缺档不等于零**。国家集训队名单不直接等同于决赛前50名。

## 选择接入方式

| 方式 | 适合谁 | 接入地址或命令 |
| --- | --- | --- |
| 远程 MCP | 客户端支持 Streamable HTTP 和私有请求头 | `https://huajing50.com/mcp` |
| 本地 MCP | 客户端支持 stdio MCP | 运行本仓库的 Node.js 接入程序 |
| Agent Skill | Agent 支持 `SKILL.md` | 安装 [`skill/huajing50`](./skill/huajing50) |

三种方式均使用化竞50账号的个人 API Key。请先在[化竞50](https://huajing50.com)登录，并从“数据服务 / API”页面取得自己的连接信息。**不要**把密钥提交到 GitHub、写进 Skill、放在公开配置或分享截图中。

### 远程 MCP

在支持远程 Streamable HTTP MCP 的客户端中填写服务地址 `https://huajing50.com/mcp`，并在客户端的私有配置中设置请求头 `Authorization: Bearer <个人 API Key>`。不同客户端的配置界面不同，以其文档和网站“数据服务 / API”页面为准。

### 本地 MCP

需要 Node.js 20 或更新版本：

```sh
git clone https://github.com/sunjun333/huajing50-mcp.git
cd huajing50-mcp
npm install
```

在 MCP 客户端的**本机私有环境**设置 `HUAJING50_API_KEY`，再添加 stdio 服务端：

```json
{
  "mcpServers": {
    "huajing50": {
      "command": "node",
      "args": ["/absolute/path/to/huajing50-mcp/bin/huajing50-mcp.mjs"],
      "env": {
        "HUAJING50_API_KEY": "<仅存于本机私有配置的个人密钥>"
      }
    }
  }
}
```

Windows 用户将 `args` 中的路径改为本机绝对路径，JSON 路径分隔符建议使用 `/`。接入程序只通过标准输入／输出与客户端通信；单独启动不会打开网页。默认连接 `https://huajing50.com`。

### Agent Skill

使用 [skills.sh](https://skills.sh) 的安装工具（按提示选择你的 Agent）：

```sh
npx skills add sunjun333/huajing50-mcp --skill huajing50
```

也可以手动将 [`skill/huajing50`](./skill/huajing50) 文件夹复制到 Agent 支持的个人 Skill 目录。Skill 会优先调用已连接的 `huajing50` MCP；若 Agent 有 HTTPS 请求能力，也可以通过私有凭据调用数据接口。**安装 Skill 不会自动取得 API Key，也不会代替 MCP 连接。**

## 工具与口径

| 需求 | 工具 |
| --- | --- |
| 收录范围、统计口径 | `describe_data` |
| 查找学生、学校、省份 | `find_entities` |
| 查看实体档案 | `get_profile` |
| 排名、趋势、汇总 | `query_statistics` |
| 奖项记录及名次 | `query_records` |
| 跨届人群筛选 | `select_cohort` |
| 相邻届成绩轨迹 | `analyze_transitions` |
| 文件来源 | `get_sources` |
| 图表配置 | `build_view` |

工具定义通过 `GET /data/tools` 动态获取，调用由 `POST /data/call` 转发。不要猜测字段或将不同口径的人次相加。国家集训队、国家队按收录名单认定；官方获奖 PDF 与另行整理的国家荣誉名单应区分来源。账号额度和频率限制以在线服务为准。

## English quick reference

Huajing50 provides an MCP server and an Agent Skill for exploring **Chinese Chemistry Olympiad** results: student award histories, school and province statistics, national training team and national team rosters, cross-edition transitions, and source documents. Use the hosted Streamable HTTP endpoint `https://huajing50.com/mcp` or this repository's local stdio bridge. Both require a personal Huajing50 API key; the open-source repository does not include the underlying data or website. Coverage varies by edition and award category, and missing records must not be interpreted as zero.

## 开发与验证

```sh
npm install
npm test
```

测试使用模拟接口，不需要个人密钥，也不请求真实学生数据。代码和 Skill 按 [MIT 许可证](./LICENSE)发布；许可证不授予网站、接口数据或官方文件的再分发权。若遇到接入问题，欢迎在本仓库提交 Issue（**不要附上 API Key 或未遮罩的学生资料**）。