Anteater MCP

Anteater MCP

版本 1.0.0-beta.2 新增了独立的个人／共享 MCPHub 配置，以及供 HTTP 托管使用的可选按请求上游密钥，并采用凭据隔离缓存。 如果未设置密钥，共享服务仍支持使用匿名上游配额。

一个 MCP 服务，让 Claude 和 ChatGPT 帮你选择 UC Irvine 的课程。

它封装了 Anteater API——UCI 的课程目录、 实时课程安排（WebSoc）、历史成绩分布、选课历史、先修课程树、AP 学分、学位要求和补充 RMP 评分——并将其整理为 20 个工具、6 个引导式提示词和 4 个参考资源，围绕学生实际会问的问题设计。

零运行时依赖。 使用 Node 24 LTS 运行源代码，或下载已包含相同 Node 运行时的 Linux、macOS 或 Windows 独立可执行文件。

"Find me a GE-2 for Fall that ends before 5pm and still has seats, ranked by how well people do."

Course        Title                Units  GPA   A%   n     SeatsOpen  Example meeting
------------  -------------------  -----  ----  ---  ----  ---------  ---------------------------
BIO SCI 17    EVO PSYCHOLOGY       4      3.80  88%  2410  2          TuTh 15:30-16:50 @ SH 134
UNI STU H30A  ANALYSIS HEALTH LIT  4      3.77  84%  864   15         TuTh 12:30-13:50 @ ALP 1600
LPS 31        INTRO INDUCT LOGIC   4      3.61  80%  2108  11         TuTh 14:00-15:20 @ EH 1200

快速入门

git clone https://github.com/KKazuhaK/Anteater-MCP.git
cd anteater-mcp
node --version                         # Node 24 LTS
node anteater-mcp.mjs --list-tools     # confirm it runs

然后将其添加到你的客户端中——Claude Desktop、 Claude Code、ChatGPT，或 任何其他 MCP 客户端。

无需其他配置。API 密钥为可选项，但建议设置。

安装

独立二进制文件

每个 GitHub Release 都包含适用于 Linux、macOS 和 Windows 的原生压缩包，支持 amd64 和 arm64，另附 SHA256SUMS.txt。这些文件无需 Node.js：

# After downloading and extracting the archive for your platform:
./anteater-mcp --version
./anteater-mcp --list-tools

在 MCP 客户端配置中，将 anteater-mcp（或 anteater-mcp.exe）的绝对路径用作 command，并省略 args 数组。macOS 压缩包采用临时签名；目前尚未配置公开的 Developer ID 签名和公证。

Docker

已发布的镜像支持 Linux amd64 和 arm64。macOS 和 Windows 上的 Docker Desktop 会运行相同的 Linux 镜像：

cp .env.example .env
# Set ANTEATER_MCP_TOKEN in .env, then:
docker compose up -d
curl -fsS http://127.0.0.1:8787/health

Compose 服务以非 root 身份运行，采用只读模式，不启用任何能力，且默认仅绑定到回环地址。将其置于公开 HTTPS 之后之前，请参阅 DEPLOY.md。

Claude Desktop

打开配置文件：

添加一个 anteater 条目。路径必须是绝对路径——Claude Desktop 不会从你的项目目录运行该服务：

{
  "mcpServers": {
    "anteater": {
      "command": "node",
      "args": ["/absolute/path/to/anteater-mcp/anteater-mcp.mjs"]
    }
  }
}

使用 API 密钥：

{
  "mcpServers": {
    "anteater": {
      "command": "node",
      "args": ["/absolute/path/to/anteater-mcp/anteater-mcp.mjs"],
      "env": { "ANTEATER_API_KEY": "your-secret-key" }
    }
  }
}

完全重启 Claude Desktop（退出应用，而不只是关闭窗口）。你应该会看到 20 个 anteater 工具，6 个提示词也会以斜杠命令的形式显示。

此仓库中的 claude_desktop_config.example.json 内容相同，可直接复制使用。

Claude Code

claude mcp add anteater -- node /absolute/path/to/anteater-mcp/anteater-mcp.mjs

使用密钥：

claude mcp add anteater -e ANTEATER_API_KEY=your-secret-key -- node /absolute/path/to/anteater-mcp/anteater-mcp.mjs

使用 claude mcp list 验证。

ChatGPT

有两种方式。第一种无需服务器。

node anteater-mcp.mjs --http --port 8787   # binds 127.0.0.1 only — do not add --host
# in another terminal
ngrok http 8787      # or: cloudflared tunnel --url http://localhost:8787

https://<your-domain>/mcp?token=<ANTEATER_MCP_TOKEN>

⚠️ **ChatGPT 的 MCP 插件仅支持网页端。**OpenAI 自己的文档指出，开发者模式“适用于 Pro、Plus、Business、Enterprise 和 Education 账户，且仅限网页端”——手机应用无法连接 MCP 服务。要在手机上使用 ChatGPT，请使用自定义 GPT，并将其 Action 指向此服务的 REST 门面，下文会对此进行介绍。

不同 ChatGPT 方式的功能对比

在手机上

Claude 的 iOS 和 Android 应用支持远程 MCP 服务。将此服务部署在 HTTPS 后面， 在浏览器中于 claude.ai 添加一次，即可同步到应用中 — 你无法直接通过手机添加新 服务。DEPLOY.md 提供了完整方案：令牌身份验证、systemd 单元、 Caddy 或 nginx，以及连接器设置。

ChatGPT 自定义 GPT 方案也适用于移动设备，且完全不需要服务。

Codex

Codex 使用可流式传输的 HTTP，并从环境变量读取令牌，因此令牌不会写入配置文件：

export ANTEATER_MCP_TOKEN=...   # in your shell profile
codex mcp add anteater --url https://your.domain/mcp --bearer-token-env-var ANTEATER_MCP_TOKEN

或者直接将其写入 ~/.codex/config.toml — 项目本地的 .codex/config.toml 优先于全局配置：

[mcp_servers.anteater]
url = "https://your.domain/mcp"
bearer_token_env_var = "ANTEATER_MCP_TOKEN"

Codex 会在连接时读取该变量，并发送 Authorization: Bearer <token>。

其他 MCP 客户端

此服务通过标准输入/输出使用标准 MCP。将客户端指向：

command: node
args:    ["/absolute/path/to/anteater-mcp/anteater-mcp.mjs"]

或者使用 node anteater-mcp.mjs --http，将其作为可流式传输的 HTTP 服务运行在 http://127.0.0.1:8787/mcp。

协议版本 2025-06-18、2025-03-26 和 2024-11-05 均受支持； 服务会协商到较低版本，而不会原样返回收到的版本。

你可以获得什么

工具（20 个）

查找课程

选课前了解课程情况

确认自己确实可以选课

规划学位

其中有五个工具可以计算上游 API 未提供的内容：先修课程树评估、课程表冲突检测、实时课程安排与历史成绩数据的关联、AP 学分授予结果呈现，以及确定性的学位进度评估。

全部 20 个工具均标注为 readOnlyHint: true — 这里的工具不会修改任何内容。

提示词（6）

在 Claude Desktop 中，这些提示词会显示为斜杠命令。每个提示词都会触发完整的多工具工作流，而非单次查询。

* = 必填。名为 term、ge、department、major 和 course 的参数支持通过 MCP completions API 自动补全。

资源（4）

客户端可直接读取的参考表，无需调用工具：

• anteater://reference/departments — 所有院系代码和名称
• anteater://reference/terms — 所有包含课程安排数据的学期
• anteater://reference/ge-categories — GE 代码及其含义
• anteater://reference/restriction-codes — 注册处提供的选课限制代码

配置

API 密钥

可选，但建议配置：匿名调用使用共享的每小时配额，很容易耗尽；配置密钥后则可使用专属配额。

它不会解锁模糊搜索。/v2/rest/search 会拒绝普通密钥，并返回 not permitted to access this resource——它需要 ICSSC 单独授予的更高权限。未配置该权限时，search_courses 会退回到按标题、再按描述进行子串匹配，并会在输出中说明这一点。结构化筛选条件（department、geCategory、courseLevel、units）不受影响，而且通常更实用。

1. 前往 dashboard.anteaterapi.com/create
2. 选择类型 secret — publishable 密钥会通过 Origin 标头进行验证，而 Node 不会发送该标头，因此在此处无法使用
3. 在客户端配置中设置密钥（见上文），或用于本地开发：

cp .env.example .env     # then edit .env
set -a; . ./.env; set +a # load it without echoing the value

.env 已被 gitignore。切勿将密钥粘贴到 issue、PR 或截图中。

共享和个人上游密钥（MCPHub）

要在 MCPHub 中直接执行，请按照 MCPHub 指南导入 stdio 配置。每位用户都可以绑定个人密钥，另有一个独立的共享条目使用公共/默认密钥。无需单独运行 Anteater 容器。以下标头机制适用于 HTTP 部署。

HTTP 调用可以使用部署的共享 ANTEATER_API_KEY，也可以通过 X-Anteater-Api-Key 发送个人密钥。对于该请求及其所有并发上游调用，个人标头优先级更高。如果未提供该标头，则使用共享密钥（若未配置共享密钥，则匿名访问上游）。空白或含糊不清的个人标头会被拒绝；个人密钥无效时不会重试共享密钥。Anteater API 缓存按凭据隔离。

Authorization: Bearer <ANTEATER_MCP_TOKEN> 仍用于验证对此服务的访问权限。它与上游 API 密钥相互独立，并且在配置后，两种模式都必须提供该令牌。个人密钥应放在标头中，切勿放入 URL 查询参数。

有关单独的 Shared 和 Personal 服务条目，请参阅 MCPHub 设置。Personal 条目需要绑定；Shared 条目即使未绑定也可使用。

环境变量

命令行

node anteater-mcp.mjs                    # stdio (what MCP clients use)
node anteater-mcp.mjs --http             # HTTP on 127.0.0.1:8787, endpoint /mcp
node anteater-mcp.mjs --http --port 9000 # different port
node anteater-mcp.mjs --http --host 0.0.0.0  # bind all interfaces (warns; see below)
node anteater-mcp.mjs --list-tools       # list every tool

HTTP 模式安全性

• 默认绑定到 127.0.0.1。 不指定主机时，server.listen(port) 会绑定所有 网络接口，从而将未经身份验证的服务暴露给整个局域网。必须使用 --host 才能更改此设置，更改时会显示警告。
• 验证 Origin。 MCP 规范要求本地 HTTP 服务执行此验证： 否则，你访问的任何页面都可以向你的端口发送 POST 请求并调用所有工具（DNS 重绑定／CSRF）。允许没有 Origin 的请求（原生 MCP 客户端）； 带有 Origin 的请求必须来自 localhost，或列在 ANTEATER_ALLOWED_ORIGINS 中。
• Access-Control-Allow-Origin 会回显单个已验证的来源，绝不会是 *。
• 除非设置了 ANTEATER_MCP_TOKEN，否则不进行身份验证。 这在回环地址上没问题， 在其他任何地址上都不安全；如果服务绑定到非回环地址但未设置令牌，启动时会发出警告。 参见 DEPLOY.md。
• HTTP 活动会写入 stderr，每个请求和响应各记录一行 JSON。 日志包含请求 ID、方法、净化后的目标、远程地址、状态、耗时、 RPC／工具名称，以及可用时的结果。绝不会记录授权值和 RPC 参数；URL 中的令牌值会显示为 [REDACTED]。
• /health 会报告状态和源 URL；/source 会重定向到此代码库， 帮助部署了修改版副本的任何人遵守 AGPL 第 13 节。

故障排查

开发

npm test                # 20 conformance tests; makes no API calls
npm run test:live       # live calls; needs a key in practice
npm ci                  # build tooling only; the shipped server has no runtime packages
npm run build:sea       # standalone binary; requires the exact Node in .node-version

UPSTREAM.md 记录了确切的 Anteater API 版本，以及本服务逐个端点验证所依据的上游提交 — API 变更后若开始返回错误或空结果，请从这里着手排查。

VERIFICATION.md 是一份完整的发布检查清单，包含逐项回归的通过标准、安全检查和集成检查；编写时考虑到执行者可能从未读过代码。

CI 使用与 Docker 和原生打包相同的固定 Node 24 LTS 版本。它会运行离线测试套件、语法和 OpenAPI 检查、独立可执行文件冒烟测试，以及受限容器协议测试。它不会调用在线 Anteater API，因此绝不会消耗公共速率限制配额。

推送一个标签名与 v 加 package.json 版本号完全匹配的标签后，工作流会构建六个原生可执行文件、生成校验和及来源证明，将 amd64/arm64 镜像推送到 GHCR，并发布 GitHub Release。稳定标签会更新 :latest；每个发布都会更新 :beta；精确的 :vX.Y.Z 标签不可变。

首次发布镜像后，将 GHCR 软件包的可见性设置为公开即可。工作流使用范围受限的 GITHUB_TOKEN；如果仓库策略阻止机器人创建 Release，请添加具有 Contents 写入权限的细粒度 RELEASE_PAT 密钥，作为与上游项目相同的备用方案。

范围

Anteater API 还提供餐厅、图书馆客流和自习室预订服务。这里有意不封装这些功能 — 本服务专注于选课和注册课程。

LARC 辅导课程小节属于范围内，但实际上上游已不再提供：/v2/rest/larc 对 2024 Fall 返回 22 门课程，对此后任何学期都不返回数据，因此，对于学生实际计划的学期，工具总会回答“没有”。

已知限制

这些是上游数据的特性，并非错误。服务会如实说明这些限制，而不是粉饰它们，因为另一种做法就是给出听起来笃定却错误的建议。

• WebSoc 不会公布哪场讨论课对应哪节课。 有些课程会在分组编号中体现对应关系（Lec A → Dis A1），另一些课程则会独立编号配套课程（I&C SCI 31：讲课为 A/B，实验课为 1–9）。因此，check_schedule 会告知你必修部分是否完全缺失，以及某种配对是否无法验证，但无法确认某场实验课是否对应某节讲课。请在 WebReg 上确认。ICSSC 自己的两个客户端也不会推断这种对应关系：AntAlmanac 和 PeterPortal 都将分组显示为平铺列表，把配对工作留给学生，这充分说明数据中根本没有这些信息。
• 不会根据你的情况检查选课限制。 search_sections 和 recommend_courses 会显示限制代码及其含义；你是否符合“仅限本专业”或“仅限研究生”的要求，由注册处执行。
• 不包含转学和社区大学的课程。 check_prerequisites 会报告无法识别的已修课程，而不会悄悄忽略它们，但只有学业顾问才能确认转学学分。
• 没有选课窗口日期。 校历涵盖教学和期末考试，但不会说明你的选课窗口何时开放。请查看 StudentAccess。
• 成绩数据有延迟。 最近的学季可能尚无数据，近期学期的成绩也常被归在 STAFF 名下。样本量较小时，平均 GPA 不可靠——工具始终会显示 n，供你判断。
• 历史 GPA 按课程汇总。 recommend_courses 根据所有过往授课教师的平均成绩进行排序，这些教师未必是本学期的授课教师。做决定前，请使用 get_course_grades 查看具体授课教师的成绩。

发布前发现并修复的错误

六维并行审查（逻辑、MCP 一致性、实时 API 契约、安全性、稳健性、仓库就绪情况）共发现 41 个原始问题，去重后为 38 个。以下是那些确实可能误导用户的问题：

第二轮审查通过六种真实的学生场景端到端调用服务，又发现了 54 个问题，其中 10 个属于阻断级问题。最严重的包括：

还修复了：NOT 先修条件子树中反转的勾选标记；48 个含空格的院系代码对应的课程编号丢失；HTTP 分块边界处多字节 UTF-8 字符损坏；对未经验证的输入使用会导致二次回溯的正则表达式；以及将 socAvailable 错误标为“开放选课时间”，而它实际表示课表发布日期。

值得了解的 API 特性

上游文档未说明；这里都已处理，并列出如下，或许能帮你省去调试的麻烦。

• days 必须用逗号分隔。 Tu,Th 可用，TuTh 会被拒绝。它表示匹配所列日期中的 至少一天，而非全部日期。
• enrollmentHistory 返回并行数组（dates[]、totalEnrolledHistory[]、 requestedHistory[] 等），而非标量。-1 表示“未跟踪”。
• finalExam.month 从 0 开始计数。
• 课程评论是原始 HTML 片段，包含 <p> 和 "。
• startTime / endTime 表示“开始时间不早于”和“结束时间不晚于”，而非时间段重叠。
• /v2/rest/search 需要 特权 API 密钥。 普通密钥会被拒绝，并返回 not permitted to access this resource；这与完全没有密钥时返回的 key is required 是不同错误——值得区分，否则告诉已有密钥的人去获取密钥，无异于走进死胡同。
• /v2/rest/websoc/syllabi 接受 courseId，而非 department + courseNumber。
• /v2/rest/courseMaterials 需要同时提供 department 和 courseNumber。 单独提供其中一个会被拒绝，而且它会将三个夏季学期合并为一个 Summer。
• 限制条件字符串包含普通文本。 "A and N" 必须按空白字符拆分，并且丢弃字面上的 and / or，否则连词会被渲染成代码。
• 课程状态是枚举值，而非自由文本：OPEN、Waitl、FULL、NewOnly 或空值。只有 OPEN 表示在读学生现在可以选课——NewOnly 表示名额留给新生。numNewOnlyReserved 统计的是容量内同样预留的名额，因此表面上的空余名额会高估实际可选名额。

分发

已发布到 MCP Registry，名称为 io.github.KKazuhaK/anteater-mcp，仅列出容器镜像。注册表条目说明了如何运行自己的实例；它不会指向任何人的部署，因为托管实例需要通过各自的令牌访问，上游配额也归运行该实例的人所有。

每个版本还会发布 GHCR 镜像，以及适用于六个平台的独立二进制文件。

许可证与署名

数据来自由 ICSSC Projects 维护的 Anteater API。

这不是 UCI 的官方工具。 注册前请在 WebReg 或 General Catalogue 中核实。使用须遵守 Anteater API 的 署名政策。

采用 AGPL-3.0-or-later 许可，与上游 Anteater API 服务保持一致，以便将来如贡献回上游，代码可以自由地双向流动。这是一个独立的 HTTP 客户端，不包含任何上游源代码。如果你修改它并将其作为网络服务运行，AGPL 第 13 条要求你向用户提供对应源代码——请参阅 NOTICE。

学术用途：

@misc{anteater-api,
  author = {ICS Student Council},
  title = {Anteater API},
  year = {2024},
  howpublished = {\url{https://github.com/icssc/anteater-api}},
}