iana-registries-mcp-server

---

概述

官方 IANA 协议注册表，以及 RFC 和 Internet-Draft 状态。查询端口、媒体类型、HTTP 状态码和标头、URI 方案、企业编号及语言标签；搜索其他任意注册表；并检查 RFC 是否仍然有效、已被废止或已更新。无需 API 密钥。

工具

工具	描述
iana_lookup_port	按端口号、服务名称或关键词查询各传输协议的服务名称和端口分配情况，以及端口的 RFC 6335 类别
iana_lookup_media_type	按完整类型或关键词查询已注册的媒体（MIME）类型，以及状态、替代项和注册模板声明
iana_lookup_http_status	按数字查询 HTTP 状态码，或按关键词查询原因短语；未分配的代码会报告其范围
iana_lookup_http_field	查询已注册的 HTTP 字段（标头和尾部字段）名称、状态和结构化字段类型
iana_lookup_uri_scheme	查询已注册的 URI 方案、状态、描述和知名 URI 支持情况
iana_lookup_pen	按数字或 1.3.6.1.4.1 下的 OID 查询私有企业编号，或按组织名称查询
iana_lookup_language_tag	按子标签验证并规范化 BCP 47 语言标签，或按描述搜索子标签
iana_get_rfc_status	每次调用最多查询 10 个 RFC、Internet-Draft 或 BCP/STD/FYI 系列的当前状态和关联关系
iana_search_registries	按关键词在 IANA 协议索引中查找任意注册表或子注册表
iana_get_registry_records	读取并筛选任意 IANA XML 注册表中指定 id 的记录

能力参考

iana_lookup_port _工具

• 指定 port（0–65535）、service（精确名称）或 keyword 之一；transport（tcp、udp、sctp、dccp）可筛选所有模式
• 每行包含 state（assigned、reserved、unassigned、unnamed）和对应的传输协议；端口模式还会添加 port_class（system、user、dynamic），以及包含该端口的范围行

---

iana_lookup_media_type _工具

• 指定 type（例如 application/json；会移除 ; 之后的参数）或 keyword 之一；top_level 可缩小关键词模式的范围
• keyword 会匹配已注册的类型名称和状态注释，不会匹配文件扩展名；如果形似扩展名的单词关键词（jpg、.mp3、*.jpg），会收到相应提示，除非该词是已注册的顶级类型或子类型（png 不会触发提示，因为存在 image/png）
• status 为 current、deprecated 或 obsoleted；如果注册表指定了替代项，则会提供 replaced_by
• type 模式还会读取注册模板，并在模板包含相关声明时，于 template 下返回文件扩展名、预期用途和已弃用别名声明；无法读取模板时，template.fetched 为 false；当 IANA 未为该类型发布模板（image/gif、text/plain）时，template.available 为 false

---

iana_lookup_http_status _工具

• 指定 code（100–599）或在已注册的原因短语中搜索 keyword 之一
• 返回 class 和 state（assigned、temporary、obsoleted、unused），以及定义该状态的参考文献和章节；对于未分配的代码，返回 found: false 和其 unassigned_range

---

iana_lookup_http_field _工具

• 指定 name（不区分大小写）或在名称和注释中搜索 keyword 之一；status 可筛选两种模式
• 返回 status（permanent、provisional、deprecated、obsoleted）、已注册时的 structured_type、注释以及定义该字段的参考文献

---

iana_lookup_uri_scheme _工具

• 指定 scheme（末尾的 : 或 :// 会被忽略）或 keyword 之一；status（permanent、provisional、historical）可筛选两种模式
• 返回描述、参考文献、well_known_uri_support，以及发布了注册模板时的 template_url

---

iana_lookup_pen _工具

• 指定 pen（数字，或 1.3.6.1.4.1 下的 OID）或组织名称中的词语之一
• 每个条目都包含其 oid 前缀和 state（assigned、reserved、unassigned）；如果某行组织信息因混有联系方式而被隐去，则 organization_withheld: true
• 如果 OID 包含企业编号以下的弧段，则返回 requested_oid 和 sub_arcs；这些弧段由企业分配，而非由 IANA 分配

iana_lookup_language_tag _工具

• tag（下划线按连字符读取）或 description 二选一；subtag_type 用于缩小描述模式的范围
• 标签模式会返回 well_formed、valid、canonical_tag（仅适用于有效标签）、subtags[] 中的各个部分，以及 issues[]：kind 为 unknown 和 wrong_position 会使标签无效，而 deprecated、variant_prefix_mismatch、suppress_script_redundant 和 extension_not_validated 仅供参考
• 单个子标签输入会在 also_registered_as 中列出同一子标签下其他类型的记录
• 规范化会保留变体顺序，同时消除首选值冲突；已注册的 ja-Latn-hepburn-heploc 上下文会转换为 ja-Latn-alalc97，并保留无关部分
• 扩展部分会添加扩展分配信息 extension（allocated、unallocated 或 unavailable）、描述、定义它的 RFC 以及组织管理机构；extension_source 会记录所使用的副本。分配状态不会改变基础有效性，也不会验证扩展内容。可选的分配信息读取会在 3 秒内停止；如果失败，则返回基础分析结果和重试指南，或返回标记为过期的分配信息副本

---

iana_get_rfc_status _工具

• 最多接受 1,000 个经过规范化的非空白 ids，并在选择每次调用的十个 ID 前进行规范去重：任何常见格式的 RFC 编号；BCP、STD 和 FYI 编号（BCP 14）；带或不带修订后缀的草案名称；RFC 和草案文件名（rfc2616.txt、draft-ietf-httpbis-semantics-19.txt）；datatracker.ietf.org、tools.ietf.org 或 ietf.org 上 RFC 或草案的 URL，或 rfc-editor.org 上 RFC 的 URL（https://tools.ietf.org/html/rfc7231）；以及 rfc-editor.org/info/ 或 datatracker.ietf.org/doc/ 下的系列 URL（https://datatracker.ietf.org/doc/bcp14/）。URL 的查询参数和片段会被删除
• total_ids 统计不同 ID 的数量；deferred_ids 预览接下来的十个 ID，而 deferred_count 统计剩余的全部 ID。要继续处理，请将相同的原始 ids 与 next_ids_offset 作为 ids_offset 一起重新提交。deferred_reason: "batch_limit" 和 deferred_guidance 会说明截断原因；偏移量达到或超出末尾时，会返回空页且不发起上游请求
• documents[] 会为 RFC 提供当前状态和发布时状态、流、工作组、废止和更新关系、所属系列（is_also）以及勘误页面；为草案提供其状态、IESG 状态、替代文档以及 became_rfc；为系列提供其成员 RFC（kind: "series"）。未知 ID 的结果为 found: false，并附有 guidance；高于最新版本的草案修订仍会判定为已找到，并由 guidance 指明最新版本
• 查找失败的 ID 会进入 failed[]，其他 ID 仍会正常返回；失败项包含 reason，并在失败信息中说明时包含 retryable（如果再次调用仍以相同方式失败，则为 false）；仅当所有 ID 均失败时，整个调用才会失败。一次调用最多发起 20 个 Datatracker 请求（一个 RFC 或系列需要 1 个请求，另加每次调用为 RFC 系列查询所需的 1 个请求；一个草案需要 3 个请求，带修订后缀时需要 4 个）；超出限制的 ID 会以原因 request_limit 返回在 failed[] 中，供重新提交

---

iana_search_registries _工具

• query 中的词会与注册表标题、类别和 ID 匹配，不区分单复数（ethertype 可找到 "Ethertypes"）；每个词都必须匹配，包括 for 和 the；limit 接受 1–1,000,000，超出时会限制为 50，默认为 15，并通过 offset 分页
• 完全匹配的注册表或子注册表 ID 排名靠前；以词语形式给出的注册表 ID 也会排名靠前（protocol numbers → protocol-numbers）；最接近的标题随后列出
• 在多个协议类别下列出的注册表只会返回一次，其类别以 ; 拼接
• 每个条目都包含 iana_get_registry_records 使用的 registry_id 和 subregistry_id，以及注册流程、定义文档、页面 URL 和 XML URL

---

iana_get_registry_records _工具

• 一个 registry ID 或 iana.org/assignments URL、可选的 subregistry，以及筛选条件 value（与键列精确匹配，或与列 field 名称匹配）和 contains（匹配任意字段中的词语；字段值相同的记录优先）
• 数字形式的 value 会与数字单元格精确比较（0443 可找到 443），或与十进制范围比较，包括 64 位端点。单个 0x 词元会按数值与单个 0x 单元格比较（0x5 可找到 0x05），或与十六进制范围比较；其他 0x 形式则按原样比较其数字，不论逗号、空格或花括号的写法
• 如果 value 未匹配，结果会列出包含该值的其他列及其行数，因此可通过 field 按助记符或服务名称查找；如果匹配，结果会说明是否还有不含键单元格但包含该值的行
• 按 cursor / next_cursor 分页（第一页之后的页面会携带 offset），并受有效 limit 限制（最多 100，默认 25）及 48,000 个字符的记录预算限制；超过 2,000 个字符的字段会被截断，每条记录最多保留 16 个字段，cut_fields 会列出被截断的字段
• 如果某个注册表包含多个子注册表且未指定子注册表，则返回 subregistries[]，而不是记录；包含嵌套表格的表会在第一页的 subregistries[] 中列出这些表，读取子注册表时会在 registry_notes[] 中附带注册表自身的说明和脚注
• 失败时会返回 unknown_registry、unknown_subregistry、unknown_field、non_xml_registry、invalid_cursor 或 cursor_mismatch

功能

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

IANA 专属功能：

• 实时、无需密钥地读取 IANA 注册表文件、RFC Editor 的逐 RFC JSON 文件以及 IETF Datatracker
• 注册表在首次使用时加载，并缓存 24 小时后重新验证；刷新失败时，最多 7 天前的缓存副本仍可用于响应，且 source.stale: true
• 按主机控制请求节奏（iana.org、rfc-editor.org、datatracker.ietf.org），每次工具调用共用 45 秒预算，涵盖所有重试和队列等待
• 通用记录使用注册表的 XML 元素名称作为字段名称（rec 是 Recommended 列）
• 不返回联系人、指定专家和注册人个人信息字段，并将自由文本中的电子邮件地址替换为 [email removed]

便于 Agent 使用的输出：

• 未匹配是结果，而非错误：查无结果时，查找会返回 found: false，并通过 notice 说明下一步；遇到未知 RFC 或草案时，返回 found: false 和 guidance；语言标签无效时，返回 valid: false 和 issues[]。未匹配意味着 IANA 没有相关注册，并不代表该值在实际中未被使用
• 统一的查找约定：每次查找必须且只能指定一个模式键，否则返回 mode_required；正的安全整数 limit 最大为 1,000,000，超过 100 时会被限制为 100（iana_search_registries 除外，其默认值为 15、上限为 50）。受限调用在两种接口中都会披露 requested_limit 和 effective_limit，包括精确匹配和空模式。列表模式（keyword、organization、description）使用 offset 分页，并返回 next_offset、totalCount、shown 和 truncated
• 每个注册表响应均包含来源信息：source 携带注册表文件、registry_updated、fetched_at 和 stale
• 带恢复提示的类型化失败：每个工具都会声明 upstream_unreadable（搜索时为 index_unreadable）和 pacer_shed；当此服务自身的请求队列已满时，后者会携带 retryAfter

快速开始

公共托管实例

公共实例位于 https://iana-registries.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

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

自托管 / 本地

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

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

或使用 npx（无需 Bun）：

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

或使用 Docker：

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

对于 Streamable HTTP，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bunx @cyanheads/iana-registries-mcp-server@latest
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥或账户：IANA、RFC Editor 和 IETF Datatracker 均无需密钥。

安装

1. 克隆仓库：

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

2. 进入目录：

cd iana-registries-mcp-server

3. 安装依赖项：

bun install

4. 配置环境（可选）：

cp .env.example .env
# the server needs no variables of its own; edit framework overrides as needed

配置

此服务自身不读取任何环境变量。以下框架设置适用：

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_HOST	HTTP 服务主机。	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径。	/mcp
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() 入口点：注册工具，并启动和停止服务。
src/mcp-server/tools/definitions	工具定义（*.tool.ts），共 10 个工具。
src/mcp-server/tools/shared	工具共用的架构、列表分页与通知，以及 Markdown 辅助函数。
src/services/upstream	面向 iana.org、rfc-editor.org 和 datatracker.ietf.org 的限速、预算控制 HTTP 客户端。
src/services/registry	注册表缓存和解析器：XML 注册表、PEN 列表、语言子标签和扩展注册表、协议索引及其排序搜索、BCP 47 标签分析，以及个人数据清理。
src/services/media-template	媒体类型注册模板读取器。
src/services/ietf	RFC Editor 和 Datatracker 文档状态。
tests/	单元测试和工具测试，结构与 src/ 对应。

开发指南

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

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志；注册表文本来自第三方，因此 format() 会通过 quote() 和 inline() 辅助函数进行渲染
• 在 src/mcp-server/tools/definitions/index.ts 的汇总文件中注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；切勿编造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。

IANA 和 IETF Trust 根据 CC0 1.0 将协议注册表献给公有领域（许可条款，2021 年 11 月 10 日联合声明）。RFC 文档不在该声明范围内；此服务仅返回 RFC 元数据，不返回 RFC 正文。本项目独立于 IANA、IETF 和 RFC Editor。