Rfcxml Mcp

RFCXML MCP 服务

日本語版 README · 文档

用于结构化理解 RFC 文档的模型上下文协议（MCP）服务。

用途

与现有基于文本的 RFC MCP 服务不同，本服务利用 RFCXML 的语义结构来实现：

• 规范性要求提取（MUST/SHOULD/MAY），并提供结构化输出
• RFC 依赖关系图构建
• 定义范围管理
• 实现检查清单生成

架构

┌─────────────────────────┐
│  Markdown / PDF         │  Display & Sharing
├─────────────────────────┤
│  Translation            │  Explanation & Verification
├─────────────────────────┤
│  RFCXML MCP             │  Common Understanding for AI & Humans
├─────────────────────────┤
│  RFCXML                 │  Single Source of Truth
└─────────────────────────┘

与现有 MCP 的比较

功能	现有 mcp-rfc	RFCXML MCP
RFC 文本检索	✅	✅
章节提取	✅（基于文本）	✅（基于结构）
MUST/SHOULD/MAY 提取	❌	✅
条件/例外结构化	❌	✅
RFC 依赖关系图	❌	✅
定义范围管理	❌	✅
实现检查清单	❌	✅

快速开始

与 Claude Desktop / Claude Code 配合使用

将以下内容添加到 MCP 配置文件中：

{
  "mcpServers": {
    "rfcxml": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/rfcxml-mcp"]
    }
  }
}

如需固定版本（0.6.x 经常发布补丁版本），请将版本写入包规格：

{
  "mcpServers": {
    "rfcxml": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/[email protected]"]
    }
  }
}

如需在重启后将获取的 RFC 保留在磁盘上，请传入 RFCXML_CACHE_DIR（参见磁盘缓存和 rfcxml-prefetch）：

{
  "mcpServers": {
    "rfcxml": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/[email protected]"],
      "env": { "RFCXML_CACHE_DIR": "/home/you/.cache/rfcxml-mcp" }
    }
  }
}

配置文件位置：

• Claude Desktop（macOS）：~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop（Windows）：%APPDATA%\Claude\claude_desktop_config.json
• Claude Code（项目范围）：项目根目录下的 .mcp.json
• Claude Code（用户范围）：~/.claude.json
• Claude Code（命令行）：claude mcp add rfcxml -- npx -y @shuji-bonji/rfcxml-mcp

安装（可选）

如需全局安装：

npm install -g @shuji-bonji/rfcxml-mcp

然后配置 MCP：

{
  "mcpServers": {
    "rfcxml": {
      "command": "rfcxml-mcp"
    }
  }
}

可用工具

阶段 1：基本结构

• get_rfc_structure - 获取章节层级和元数据
• get_requirements - 提取规范性要求（MUST/SHOULD/MAY）及其结构
• get_definitions - 获取术语定义及其范围

阶段 2：关系

• get_rfc_dependencies - 获取引用的 RFC（规范性/参考性）
• get_related_sections - 获取同一 RFC 中的相关章节

阶段 3：验证支持

• validate_statement - 查找与某项陈述相关的 RFC 要求，并报告检测到的矛盾。这不是符合性判断：isValid 有三个取值（null = 没有足够强的匹配结果可供判断，false = 检测到矛盾，true = 匹配结果中未检测到矛盾）。最终结论由你决定。
• generate_checklist - 生成实现检查清单

旧版 RFC 支持

RFC 8650（2019 年 12 月）之后发布的 RFC 均提供官方 RFCXML v3 格式。更早的 RFC 可能没有 XML 格式。

此服务包含自动回退功能：如果没有 XML 格式，就改为解析文本格式。

来源信息

所有响应都包含来源信息：

{
  "rfc": 6455,
  "sections": [...],
  "_source": "text",
  "_sourceNote": "Warning: Parsed from text format. Accuracy may be limited."
}

_source	描述
xml	从 RFCXML 解析（准确度高）
text	从文本解析（准确度中等）

兼容性

RFC	格式	说明
RFC 8650+	XML	支持官方 RFCXML v3
RFC 8650 之前	文本	自动回退

输出示例

以下每个示例都截取自当前构建的实际输出（运行 npm run build，然后通过 MCP 客户端调用列出的工具）。字段名和值均为原样；较长的数组会以 ... 截断。

get_rfc_structure - 获取 RFC 结构

get_rfc_structure { "rfc": 9293 }

{
  "metadata": {
    "title": "Transmission Control Protocol (TCP)",
    "docName": "draft-ietf-tcpm-rfc793bis-28",
    "number": 9293,
    "date": "2022-08",
    "category": "std",
    "stream": "IETF",
    "abstract": "This document specifies the Transmission Control Protocol (TCP). ..."
  },
  "sections": [
    { "number": "1", "title": "Purpose and Scope" },
    { "number": "2", "title": "Introduction" },
    {
      "number": "3",
      "title": "Functional Specification",
      "subsections": [
        { "number": "3.1", "title": "Header Format" },
        {
          "number": "3.5",
          "title": "Establishing a Connection",
          "subsections": [
            { "number": "3.5.1", "title": "Half-Open Connections and Other Anomalies" },
            { "number": "3.5.2", "title": "Reset Generation" },
            { "number": "3.5.3", "title": "Reset Processing" }
          ]
        }
      ]
    }
  ],
  "referenceCount": { "normative": 15, "informative": 85 },
  "_source": "xml"
}

number 是 RFC 中印出的章节编号（3.5、A.2），而不是 RFCXML pn（section-3.5）。category / stream / abstract 来自 IETF Datatracker API；如果 API 无法访问，或返回的值不在映射范围内（例如 RFC 1 的值为 unkn / legacy），这些字段会被省略；此时 _sourceNote 会说明原因。

get_requirements - 提取规范性要求

get_requirements { "rfc": 9293, "level": "MUST" }

{
  "rfc": 9293,
  "filter": { "section": "all", "level": "MUST" },
  "stats": { "total": 55, "byLevel": { "MUST": 55 } },
  "requirements": [
    {
      "id": "R-3.5-1",
      "level": "MUST",
      "text": "A TCP implementation MUST support simultaneous open attempts (MUST-10).",
      "section": "3.5",
      "sectionTitle": "Establishing a Connection",
      "fullContext": "A TCP implementation MUST support simultaneous open attempts (MUST-10).",
      "subject": "tcp implementation",
      "action": "support simultaneous open attempts (MUST-10)"
    },
    {
      "id": "R-3.7.1-1",
      "level": "MUST",
      "text": "TCP endpoints MUST implement both sending and receiving the MSS Option (MUST-14).",
      "section": "3.7.1",
      "sectionTitle": "Maximum Segment Size Option",
      "fullContext": "TCP endpoints MUST implement both sending and receiving the MSS Option (MUST-14).",
      "subject": "tcp endpoints",
      "action": "implement both sending and receiving the MSS Option (MUST-14)"
    }
  ],
  "_source": "xml"
}

id 的格式为 R-<section>-<n>，其中 n 在每个章节内单独编号，因此即使在文档其他位置添加要求，标识符也能保持稳定。

get_rfc_dependencies - 获取 RFC 依赖项

get_rfc_dependencies { "rfc": 9293 }

{
  "rfc": 9293,
  "normative": [
    { "rfcNumber": 791, "title": "Internet Protocol", "anchor": "RFC0791" },
    { "rfcNumber": 1191, "title": "Path MTU discovery", "anchor": "RFC1191" },
    {
      "rfcNumber": 2119,
      "title": "Key words for use in RFCs to Indicate Requirement Levels",
      "anchor": "RFC2119"
    }
  ],
  "informative": [
    { "rfcNumber": 793, "title": "Transmission Control Protocol", "anchor": "RFC0793" },
    { "rfcNumber": 896, "title": "Congestion Control in IP/TCP Internetworks", "anchor": "RFC0896" }
  ],
  "_source": "xml",
  "_referencesSource": "xml"
}

_referencesSource 表示参考文献列表的来源：xml（RFCXML <references>）、text（纯文本中的 References 章节）或 api（Datatracker relateddocument，标题为占位文本）。

generate_checklist - 生成实施清单

generate_checklist { "rfc": 9293, "role": "client", "sections": ["3.5", "3.7.1"] } — markdown 字段：

# RFC 9293 Implementation Checklist

**Transmission Control Protocol (TCP)**

Role: client

Generated: 2026-09-04T17:09:37.833Z

## Mandatory Requirements (MUST / REQUIRED / SHALL)

- [ ] **MUST** A TCP implementation MUST support simultaneous open attempts (MUST-10). (§3.5)
- [ ] **MUST** TCP endpoints MUST implement both sending and receiving the MSS Option (MUST-14). (§3.7.1)
- [ ] **MUST** If an MSS Option is not received at connection setup, TCP implementations MUST assume a default send MSS of 536 (576 - 40) for IPv4 or 1220 (1280 - 60) for IPv6 (MUST-15). (§3.7.1)

## Recommended Requirements (SHOULD / RECOMMENDED)

- [ ] **SHOULD** TCP implementations SHOULD allow a received RST segment to include data (SHLD-2). (§3.5.3)

同一调用还会返回 "stats": { "must": 6, "should": 2, "may": 1, "total": 9 }。

validate_statement - 查找相关要求

validate_statement { "rfc": 6455, "statement": "The client MUST mask all frames sent to the server." }

{
  "rfc": 6455,
  "statement": "The client MUST mask all frames sent to the server.",
  "analysis": { "detectedLevel": "MUST", "detectedSubject": "client" },
  "isValid": true,
  "matchingRequirements": [
    {
      "id": "R-5.3-2",
      "level": "MUST",
      "text": "When preparing a masked frame, the client MUST pick a fresh masking key from the set of allowed 32-bit values.",
      "section": "5.3",
      "sectionTitle": "Client-to-Server Masking",
      "_matchScore": 17,
      "_matchedKeywords": ["client", "mask", "frames"],
      "_subjectMatch": true,
      "_levelMatch": true
    }
  ],
  "conflicts": [],
  "_source": "text",
  "_sourceNote": "Warning: Parsed from text format. Validation accuracy may be limited."
}

isValid: true 仅表示在匹配到的要求中未检测到矛盾。如果没有足够强的匹配项，isValid 为 null，并由 _verdictNote 说明原因。

文本回退输出（旧版 RFC）

get_rfc_structure { "rfc": 6455 } — RFC 6455 早于 RFCXML v3，因此会解析纯文本：

{
  "metadata": {
    "title": "The WebSocket Protocol",
    "number": 6455,
    "date": "2011-12",
    "category": "std",
    "stream": "IETF",
    "abstract": "The WebSocket Protocol enables two-way communication ..."
  },
  "sections": [
    { "number": "1", "title": "Introduction" },
    { "number": "2", "title": "Conformance Requirements" },
    { "number": "5", "title": "Data Framing" }
  ],
  "referenceCount": { "normative": 18, "informative": 9 },
  "_source": "text",
  "_sourceNote": "Warning: Parsed from text format. Accuracy may be limited."
}

对于 RFC 8650 及之后的 RFC，会优先尝试 XML。如果所有 XML 源都返回 404，则调用失败（“No RFC with that number is published”）。如果 XML 获取因其他原因失败（5xx、超时），则会使用文本，并由 _sourceNote 说明 XML 获取失败且可能只是暂时性问题。

磁盘缓存和 rfcxml-prefetch

默认情况下，获取的 RFC 只存储在内存 LRU 缓存中，每次重启后都会重新获取。设置 RFCXML_CACHE_DIR 可将其保存在磁盘上：

$RFCXML_CACHE_DIR/
├── xml/rfc9293.xml     # RFCXML (RFC 8650 and later)
└── text/rfc6455.txt    # plain text (older RFCs, or XML fetch failures)

此软件包还提供 rfcxml-prefetch CLI，可预先填充相同的目录结构，以供离线或 CI 使用：

# Fetch a range into $RFCXML_CACHE_DIR (or ~/.cache/rfcxml-mcp when unset)
npx -y -p @shuji-bonji/rfcxml-mcp rfcxml-prefetch --range 9110-9114

# Individual RFCs, explicit directory, re-download even if cached
npx -y -p @shuji-bonji/rfcxml-mcp rfcxml-prefetch --rfc 6455 --rfc 9293 --cache-dir ./rfc-cache --force

选项：--range A-B、--rfc N（可重复）、--cache-dir DIR、--concurrency N（默认为 3）、--force。磁盘上已有的 RFC（XML 或文本）会被跳过，除非指定 --force。RFC 编号必须仅包含数字；--rfc 9110abc 会以代码 1 退出。

示例

完整的清单示例请参阅 examples/ 目录：

RFC	协议	来源
RFC 6455	WebSocket	文本（备用）
RFC 9293	TCP	RFCXML
RFC 7540	HTTP/2	文本（备用）

Claude 提示词示例：

Generate an implementation checklist for RFC 9293 (TCP).

内部架构

模块结构

src/
├── index.ts                    # MCP server entry point
├── config.ts                   # Centralized configuration
├── constants.ts                # BCP 14 keyword definitions + RFC number limits
├── services/
│   ├── rfc-fetcher.ts          # RFC fetching (parallel)
│   ├── rfc-service.ts          # RFC parse & cache management
│   ├── rfcxml-parser.ts        # RFCXML parser
│   ├── rfc-text-parser.ts      # Text fallback parser
│   └── checklist-generator.ts  # Checklist generation service
├── tools/
│   ├── definitions.ts          # MCP tool definitions
│   └── handlers.ts             # Tool handlers (toolHandlers map)
├── types/
│   └── index.ts                # Type definitions
└── utils/
    ├── cache.ts                # LRU cache
    ├── fetch.ts                # Parallel fetch utility
    ├── logger.ts               # Logger abstraction
    ├── requirement-extractor.ts # Shared requirement extraction
    ├── section.ts              # Section search utilities
    ├── statement-matcher.ts    # Weighted statement matching
    ├── text.ts                 # Text processing utility
    └── validation.ts           # Input validation

RFC 获取优化

向两个 XML 源（RFC Editor、Datatracker）并行发送请求，并使用第一个成功的响应。tools.ietf.org 已于 2021 年停用，因此不会使用。此处没有重试机制；并行竞速是唯一的冗余措施。

┌─────────────────┐
│  fetchRFCXML()  │
└────────┬────────┘
         │ Parallel requests
    ┌────┴─────────┐
    ▼              ▼
┌────────┐    ┌────────┐
│RFC     │    │Data-   │
│Editor  │    │tracker │
└────┬───┘    └────┬───┘
     │             │
     └──────┬──────┘
            │ Promise.any (first success)
            ▼
    ┌───────────┐
    │ Successful│ → Cancel other requests via AbortController
    │ Response  │
    └───────────┘

对同一 RFC 的并发调用（例如，同时发出 get_rfc_structure 和 get_requirements）会共用一次进行中的获取和解析。

缓存策略

LRU（最近最少使用）缓存，带有内存限制，并可选用磁盘缓存（RFCXML_CACHE_DIR），其优先级低于 XML / 文本缓存：

缓存	最大条目数	内容
XML 缓存	20	原始 RFCXML
文本缓存	20	原始文本
元数据缓存	100	RFC 元数据
解析缓存	50	已解析的结构

开发

# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Unit tests (single run) / watch mode
npm test
npm run test:watch

# E2E test (MCP client integration; fetches a few real RFCs)
npm run test:e2e

# Audit against real RFCs, tool-to-tool crosscheck, output snapshots
# (see tests/audit/README.md; run weekly by .github/workflows/audit.yml)
npm run audit
npm run crosscheck
npm run snapshot

# Lint
npm run lint

# Format
npm run format

许可证

MIT

相关项目

• mjpitz/mcp-rfc - 基于文本的 RFC MCP
• ietf-tools/RFCXML - RFCXML 架构
• xml2rfc - IETF 官方工具