oeis-mcp-server

---

概述

来自整数数列在线大全（OEIS）的整数数列。根据少量已知项识别数列，使用 OEIS 自身的查询语法进行搜索，读取条目中的公式和程序，通过其 b-file 分页查看扩展数列项，并浏览交叉引用。每个结果都链接到对应的 oeis.org 页面。无需 API 密钥。

工具

工具	描述
oeis_identify_sequence	按 OEIS 相关性顺序识别包含一段连续数列项的数列，并返回该连续项起始位置的索引
oeis_search_sequences	使用 OEIS 查询语法搜索：词语、带引号的短语、数列项列表，以及 keyword: 和 author: 等前缀
oeis_get_sequence	通过 A 编号获取一条目：数列项、偏移量、关键词、公式、程序、注释、参考文献、链接和交叉引用
oeis_get_terms	列出条目 b-file 中带索引的 a(n) 数列项；若无 b-file，则从数据行读取
oeis_get_cross_refs	列出条目交叉引用的数列，或提及该条目的条目
oeis_list_reference	解读关键词标记、搜索语法、标识符和偏移量约定，不调用上游服务

资源

资源	描述
oeis://sequence/{aNumber}	以 JSON 格式提供一条完整的 A 编号条目

仅调用工具的客户端也可通过 oeis_get_sequence 获取相同记录。

能力参考

oeis_identify_sequence _工具

• terms：最多 60 个连续项，以逗号或空格分隔（接受带方括号的列表或末尾带 ... 的列表）；每项为最多 200 位的整数，或用 _ 表示一个未知项；matchSigns（默认 false）会忽略正负号，除非设置此项
• 每页最多 10 个候选项，start 为 0–100，步长为 10；每行包含 oeis_search_sequences 的行字段，另加 matchStartIndex，即该序列在对应条目数据行中开始的位置 n（若数据行中没有该序列，则省略此字段）
• 无匹配结果和“结果过多”都会返回空页面；notice 会说明是哪种情况，以及如何重试（删除开头的项、除去公因数或添加更多项）。OEIS 只会在每个条目的数据行中匹配序列（最多约 270 个字符），不会搜索其 b-file；若所有非零项都至少有 10 位数字、10% 范围内有 5 项或更多项至少有 4 位数字，或序列超过 270 个字符，则无匹配结果的提示会说明这一点

---

oeis_search_sequences _工具

• query（1–1,000 个字符）会按原样发送：可包含单词、"带引号的短语"、项列表、keyword:、author:、name:、formula:、xref: 和 id: 等前缀、用于 OR 的 |，以及用于排除的前导 -
• sort：relevance（默认）、number、created 或 modified；每页 10 条，start 为 0–100，步长为 10
• 每行包含 name、terms、offset / firstIndex、keywords、author、legacyIds、modified（最后编辑时间，采用带时区偏移量的 ISO 8601 格式）和 url，格式与 oeis_get_sequence 中相同；若 OEIS 中没有 author 或 legacyIds，则省略对应字段
• 返回 totalCount 和 effectiveQuery，即 OEIS 解析后的查询。如果 OEIS 将查询解析为一段项序列（effectiveQuery 会显示 seq: 或 signed: 以及这些项，与用逗号分隔的纯数字相同），则会像 oeis_identify_sequence 一样在每个条目的数据行中匹配；在相同条件下，无匹配结果的提示会说明这一限制
• 如果数字之间仅以空格分隔，OEIS 会在第一个数字之后遇到负数时开始一段新序列，并且不会拼接少于三个数字；当 effectiveQuery 显示发生了这种拆分时，提示会说明这一点，并给出用逗号连接这些项的写法，以便作为一段序列进行搜索

---

oeis_get_sequence _工具

• 返回 name、terms、offset / firstIndex、keywords、author、legacyIds、referenceCount、revision、created / modified、url 和 bFileUrl，以及八个部分：comments、formulas、examples、programs、references、links、crossReferences、extensions
• 当这些部分序列化为 JSON 后超过 24,000 个字符时，kind: "outline" 会返回核心字段以及带大小信息的 sections 列表；传入 sections（例如 ["formulas", "programs"]）即可获取所选部分
• 超过 100,000 字节的选择结果会分块返回，且每块都在完整条目之间截断；将每块的 nextFromItem 作为 fromItem，并使用相同的 sections，即可获取下一块。如果 fromItem 指定的部分不在 sections 中，则会以 from_item_not_selected 失败
• 未知的 A-number 会以 sequence_not_found 失败；已撤回（dead）、预留和重新使用的条目会附带 notice

oeis_get_terms _工具

• fromIndex（默认值：第一个可用索引）和 limit（默认值：100；每次调用最多返回 1,000 项，因此更大的 limit 会按 1,000 处理）；一个切片也会在约 100,000 字节处或到达 b-file 的一个 1 MiB 分段末尾时停止，nextFromIndex 可继续获取
• source: "bfile" 会以 1 MiB 分段读取条目的 b-file，因此，超过第一个 1 MiB 的 fromIndex 会额外消耗一到两次限速请求；bFileCut: true 表示文件内容超出了 lastAvailableIndex。source: "data" 表示该条目没有 b-file，项来自其数据行
• 返回的项格式为 { n, value }，其中 value 是精确的十进制字符串；未知的 A 编号会报错 sequence_not_found
• b-file 中既不是空行、# 注释，也不是 n a(n) 键值对的行会被跳过，notice 会说明跳过的行数；如果 b-file 中完全没有键值对，则会报错 upstream_unparseable，且不会缓存

---

oeis_get_cross_refs _工具

• direction: "outgoing"（默认值）会列出条目交叉引用行中提到的 A 编号，并附上每个编号旁边的 note 和原样返回的 lines；"incoming" 会列出提及该 A 编号的条目
• 每页 10 行；start 为 0–100，步长为 10；每行都包含 url，已解析的行还会附带名称、项、偏移量、关键词、作者、旧版 ID 和最后编辑时间（modified）
• 如果 outgoing 页面中的名称查询遇到速率限制、无法使用或超时，行会以 resolved: false 返回，并附上重试提示，而不是报错；sequence_not_found 仅适用于 outgoing

---

oeis_list_reference _工具

• topic：keywords（例如 nonn、core、tabl、cons 等标志）、search_syntax（前缀、运算符、通配符、排序方式、分页），或 identifiers（A 编号、旧版 M/N 编号、偏移量、b-file）
• 返回静态表中的 entries（name、description）和 notes

---

oeis://sequence/{aNumber} _资源

• 完整条目，格式为 application/json：即 oeis_get_sequence 返回的 kind: "full" 记录，不会返回大纲
• aNumber 的形式与工具接受的相同（oeis://sequence/A108 会读取 A000108）；未知的 A 编号会报错 sequence_not_found

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

OEIS 专属功能：

• 使用单个限速、带缓存的 oeis.org 客户端（参见限速与缓存）；搜索会区分“无结果”和“结果过多”，并报告匹配总数
• 灵活识别 A 编号：A000045、a000045、A45、45 以及 oeis.org 序列 URL 都可在每个工具中解析；旧版 M/N 书目编号会引导至 oeis_search_sequences
• 精确项：每一项和 b-file 值都是十进制字符串，因此超过 2^53 的值也能保留每一位数字
• 粘贴的项序列会进行规范化处理：支持方括号、末尾的 ...、Unicode 负号，以及逗号和空格混用的分隔符

便于 Agent 使用的输出：

• 每一页都包含分页上下文（truncated、shown、cap，以及 OEIS 提供时的 totalCount 和 effectiveQuery），并附上说明如何缩小范围或继续获取的 notice
• 带恢复提示的类型化错误：sequence_not_found、from_item_not_selected、upstream_unparseable、pacer_shed 和 upstream_rate_limited；已知速率限制错误的重试时间时会附带 retryAfter
• 使用判别式输出（kind、source、每行的 resolved），调用方可根据数据分支处理，无需解析字符串
• 每条记录和每一行都包含对应的 https://oeis.org/A###### URL；贡献者撰写的文本会以代码行内格式和代码围栏呈现，因此 Markdown 客户端能原样显示公式和名称，并且只保留 http 和 https 链接 URL

请求节流与缓存

oeis.org 要求自动化客户端在请求之间等待 10 秒。服务器一次只发送一个上游请求，并确保每个请求的启动时间至少比上一个晚 10 秒，所有工具均遵守这一规则。结果缓存在内存中，因此重复查询会立即返回，且不会给 oeis.org 带来额外请求：记录缓存 24 小时，或直到搜索结果显示记录有更新（此时会通过条件请求重新验证）；搜索页面缓存 1 小时；b-file 分块缓存 7 天。一旦获取的记录列出了 b-file，该条目缓存的“无 b-file”结果便会立即失效。

如果某次调用没有缓存结果，就会在队列中等待轮到自己。当等待时间将超过 OEIS_QUEUE_MAX_WAIT_MS（默认值为 30,000 ms）时，该调用会失败并返回 pacer_shed 和 retryAfter，而不是一直挂起。如果 oeis.org 返回 429，服务器会暂停所有排队的调用，然后再重试；重试次数用尽后，会报告 upstream_rate_limited。请求节流按服务器进程分别计算。

已知限制

• 上游将匿名分页限制为每个查询 110 条结果（start ≤ 100）；例如，A000045 的 6,161 条入站引用只能通过前 110 条访问。
• 如果 OEIS 认为查询过于宽泛，就会返回空行（“Too many results”）；单个单词（prime）或仅含两项的数列很容易遇到这种情况。服务器会报告此问题，但无法继续分页。
• OEIS 会将未知前缀作为普通单词搜索，而不是拒绝查询；零结果提示会列出该前缀。
• 项匹配（oeis_identify_sequence，以及仅含数字或 seq: / signed: 项的 oeis_search_sequences 查询）只搜索每条记录的数据行，不搜索 b-file；数据行也很短：在 105 条记录（2026-10-01）的测量中，最长为 269 个字符，符号也计入长度。如果数列从数据行以外的位置开始，或者长度超过约 270 个字符，就无法找到。
• 每次调用中，oeis_get_terms 最多会读取 b-file 第一块之后的两块 1 MiB 数据；如果索引更深，会返回提示要求再次调用，后续调用会从已缓存的分块继续读取。如果 b-file 不支持字节范围请求或强 ETag，则只会读取其前 1 MiB。
• oeis_get_cross_refs 的出站引用也受 start ≤ 100 的限制，因此，列出超过 110 个不同 A-number 的记录只会返回前 110 个；lines 仍会列出全部引用。

数据与许可

OEIS 内容依据 CC BY-SA 4.0 和 OEIS End-User License Agreement 授权。重用内容时，请注明“The On-Line Encyclopedia of Integer Sequences”，并链接到 https://oeis.org/ 或对应的数列页面；服务器返回的每条记录都带有 https://oeis.org/A###### URL，可用于此目的。相同方式共享条款适用：OEIS 内容的改编作品必须依据相同许可共享。

本服务器是独立项目，与 OEIS Foundation 无关，也未获其认可。

入门

公共托管实例

可使用公共实例 https://oeis.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "oeis-mcp-server": {
      "type": "streamable-http",
      "url": "https://oeis.caseyjhand.com/mcp"
    }
  }
}

托管实例的所有调用方共享 oeis.org 的请求速率，每 10 秒一个请求；缓存命中会立即返回。如需持续使用，请运行自己的实例。

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "oeis-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/oeis-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "oeis-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/oeis-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "oeis-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/oeis-mcp-server:latest"]
    }
  }
}

如需使用 Streamable HTTP，请设置传输方式并启动服务器：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥或账户：服务器读取 oeis.org 上的公开数据。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/oeis-mcp-server.git

2. 进入目录：

cd oeis-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# optional: adjust OEIS_QUEUE_MAX_WAIT_MS, the transport, or the log level

配置

变量	描述	默认值
OEIS_QUEUE_MAX_WAIT_MS	调用在 oeis.org 请求队列中等待失败并返回 pacer_shed 和 retryAfter 之前的最长时间，单位为 ms。每次调用的 50 s 截止时间还必须覆盖请求本身，因此无论设置为何值，等待时间都会在约 35,000 ms 时停止。	30000
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

请参阅 .env.example，查看所有服务设置和常见框架覆盖项。

运行服务

本地开发

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

项目结构

目录	用途
src/index.ts	createApp() 入口：注册工具和资源，设置服务说明，并启动 OEIS 服务。
src/config	使用 Zod 解析和验证服务专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。共六个工具。
src/mcp-server/resources	资源定义。oeis://sequence/{aNumber} 资源。
src/mcp-server/shared	各定义共用的架构（A-number 输入、分页、摘要行）、用于贡献者编写文本的 Markdown 辅助工具，以及术语匹配零结果提示共用的数据行数限制测试和句子。
src/services/oeis	oeis.org 客户端：请求节流器、重试、获取边界、LRU 缓存、记录规范化和内部格式解析器。
tests/	与 src/ 结构对应的单元测试；上游响应来自测试固件，不会访问实时网站。

开发指南

请参阅 CLAUDE.md，了解开发指南和架构规则。简要说明如下：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.enrich 补充提示、总数和分页上下文
• 在 src/mcp-server/*/definitions/index.ts 的 barrel 文件中注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目根据 Apache 2.0 许可证授权。详情请参阅 LICENSE 文件。