# 黑123 Hackathons MCP · hack123-mcp

[中文](#中文) | [English](#english)

黑123（[hack123.henryht.sh](https://hack123.henryht.sh)）黑客松导航站的**远程 MCP 服务**和**只读 REST API** 源码。
Source of the **remote MCP server** and **read-only REST API** behind 黑123, a bilingual hackathon directory.

- MCP 端点 / endpoint：`https://hack123.henryht.sh/api/mcp`（Streamable HTTP，只读，免费，无需 API Key / read-only, free, no API key）
- REST API：`https://hack123.henryht.sh/api/v1/hackathons`
- 官方 MCP Registry：`io.github.onehumanbeing/hack123`
- 文档 / docs：https://hack123.henryht.sh/about#mcp

---

## 中文

### 这是什么

让 AI 助手（Claude、Cursor、Cherry Studio、VS Code 等）直接查询黑123 收录的国内外黑客松、组队帖和往届作品。每条结果都带黑123 站内链接，站内详情页再链接到主办方官网。

不依赖 MCP SDK：手写最小 JSON-RPC 2.0，无状态、无鉴权，部署在 Vercel Serverless Functions 上。

### 工具

| 工具 | 作用 | 主要参数 |
|---|---|---|
| `search_hackathons` | 搜索黑客松 | `query` 关键词（中英文）、`city`、`online`、`theme`、`from` / `to` 日期范围、`status`（`open` 报名中 / `upcoming` 未开始 / `ended` 已结束）、`limit` |
| `get_hackathon` | 单场详情：时间、地点、奖金、人群、来源链接 | `slug` |
| `search_team_posts` | 找队友帖 | `hackathon`、`city`、`role`、`query`、`limit` |
| `search_works` | 往届作品 / 获奖项目 | `hackathon`、`tag`、`query`、`limit` |

完整参数以 `tools/list` 返回为准。

### 接入

支持远程 MCP 的客户端：

```json
{
  "mcpServers": {
    "hack123": {
      "type": "streamable-http",
      "url": "https://hack123.henryht.sh/api/mcp"
    }
  }
}
```

只支持本地 stdio 的客户端，可以用 [mcp-remote](https://www.npmjs.com/package/mcp-remote) 转一下：

```json
{
  "mcpServers": {
    "hack123": { "command": "npx", "args": ["-y", "mcp-remote", "https://hack123.henryht.sh/api/mcp"] }
  }
}
```

命令行自测：

```bash
curl -s -X POST https://hack123.henryht.sh/api/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

可以这样问：「这周还能报名的线上 AI 黑客松有哪些？」「上海 12 月有什么黑客松？」「有没有面向学生、奖金 10 万以上的比赛？」

### REST API

`GET https://hack123.henryht.sh/api/v1/hackathons`，只读、可跨域、CDN 缓存 10 分钟。常用参数：

| 参数 | 说明 |
|---|---|
| `q` | 关键词（标题、别名、城市、话题、奖金说明等） |
| `status` | `open` / `upcoming` / `ended` / `undated` |
| `mode` | `online` / `offline` / `hybrid` |
| `region` | `cn` 国内 / `global` 海外 |
| `city` | 城市，中英文均可 |
| `topic` | 专题，如 `ai`、`ai-agent`、`hardware`、`web3` |
| `sort`、`page`、`limit` | 排序与分页 |
| `slug` | 按 slug 取单场 |

```bash
curl 'https://hack123.henryht.sh/api/v1/hackathons?q=上海&status=open'
curl 'https://hack123.henryht.sh/api/v1/hackathons?topic=ai&mode=online&sort=prize&page=2'
```

### 数据来源

本仓库只有查询代码，不含数据。数据来自黑123 站点构建时生成的公开文件（`https://hack123.henryht.sh/mcp-data.json`、`https://hack123.henryht.sh/data/api-hackathons.json`），由黑123 每天对照主办方官网整理更新；比赛信息以主办方官网为准。

### 自己部署

```bash
npm test          # Node 20+
npx vercel deploy # 部署后 /api/mcp 和 /api/v1/hackathons 即可用，数据仍从黑123 公开文件读取
```

---

## English

### What it is

Lets AI assistants query hackathons (China and worldwide), team-up posts and past projects listed on 黑123. Every result links to its hack123.henryht.sh page, which links to the organizer's official page.

No MCP SDK: a minimal hand-written JSON-RPC 2.0 handler, stateless and unauthenticated, running as Vercel Serverless Functions.

### Tools

| Tool | What it does | Main arguments |
|---|---|---|
| `search_hackathons` | Search hackathons | `query` (zh/en), `city`, `online`, `theme`, `from` / `to`, `status` (`open` / `upcoming` / `ended`), `limit` |
| `get_hackathon` | Full details: dates, location, prizes, audience, sources | `slug` |
| `search_team_posts` | Team-up posts | `hackathon`, `city`, `role`, `query`, `limit` |
| `search_works` | Past / winning projects | `hackathon`, `tag`, `query`, `limit` |

See `tools/list` for the exact schemas.

### Connect

```json
{
  "mcpServers": {
    "hack123": { "type": "streamable-http", "url": "https://hack123.henryht.sh/api/mcp" }
  }
}
```

For stdio-only clients: `npx -y mcp-remote https://hack123.henryht.sh/api/mcp`.

### REST API

`GET https://hack123.henryht.sh/api/v1/hackathons` — read-only, CORS enabled, 10-minute CDN cache. Parameters: `q`, `lang`, `status`, `mode`, `region`, `city`, `topic`, `sort`, `page`, `limit`, `slug` (see the table above).

### Data

This repo contains query code only, no data. Data comes from public files generated when hack123.henryht.sh is built (`/mcp-data.json`, `/data/api-hackathons.json`), curated daily against organizers' official pages. Always confirm details on the organizer's site.

## License

MIT