# Gaokao Helper MCP for Cloudflare Workers

A standalone Cloudflare Worker that exposes public Guangdong gaokao data through a read-only MCP endpoint.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/stmtc233/gaokao-helper-worker-mcp)

The deployment button creates a copy of this repository in your GitHub account, provisions a Worker, and configures Workers Builds for subsequent pushes.

## Endpoints

- `GET /health` returns a small health payload.
- `POST /mcp` is the streamable HTTP MCP endpoint.
- Static data files are deployed from the committed `public/` snapshot, so this repository builds independently.

## Tools

- `list_data_files` lists available data files and resource URIs.
- `read_data_sample` reads a bounded sample from a CSV or JSON file.
- `search_schools` searches across school, group, major, code, and other CSV text.
- `score_rank_lookup` looks up the nearest row in `score_rank_2026.csv`.

## Commands

```bash
npm ci
npm run dev
```

Deploy:

```bash
npm run deploy
```

After deployment, connect MCP clients to:

```text
https://<your-worker-host>/mcp
```

## Updating the data snapshot

When the source [`gaokao-helper`](https://github.com/stmtc233/gaokao-helper) checkout is the parent directory:

```bash
npm run sync:data
```

For a source checkout elsewhere, pass its path explicitly:

```bash
GAOKAO_HELPER_ROOT=/path/to/gaokao-helper npm run sync:data
```

Commit the updated files under `public/` so Cloudflare's one-click deployment remains self-contained.