Rfcxml

npm version CI License: MIT Node.js Claude Code

日本語版 README

A Model Context Protocol (MCP) server for structured understanding of RFC documents.

Purpose

Unlike existing text-based RFC MCP servers, this server leverages the semantic structure of RFCXML to enable:

• Normative requirements extraction (MUST/SHOULD/MAY) with structured output
• RFC dependency graph construction
• Definition scope management
• Implementation checklist generation

Architecture

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

Comparison with Existing MCPs

Feature	Existing mcp-rfc	RFCXML MCP
RFC text retrieval	✅	✅
Section extraction	✅ (text-based)	✅ (structure-based)
MUST/SHOULD/MAY extraction	❌	✅
Condition/exception structuring	❌	✅
RFC dependency graph	❌	✅
Definition scope management	❌	✅
Implementation checklist	❌	✅

Quick Start

Using with Claude Desktop / Claude Code

Add the following to your MCP configuration file:

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

Configuration file locations:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Claude Code (project scope): .mcp.json at the project root
• Claude Code (user scope): ~/.claude.json
• Claude Code (CLI): claude mcp add rfcxml -- npx -y @shuji-bonji/rfcxml-mcp

Installation (Optional)

For global installation:

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

Then configure MCP:

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

Available Tools

Phase 1: Basic Structure

• get_rfc_structure - Get section hierarchy and metadata
• get_requirements - Extract normative requirements (MUST/SHOULD/MAY) with structure
• get_definitions - Get term definitions and their scope

Phase 2: Relationships

• get_rfc_dependencies - Get referenced RFCs (normative/informative)
• get_related_sections - Get related sections within the same RFC

Phase 3: Verification Support

• validate_statement - Verify if a statement complies with RFC requirements
• generate_checklist - Generate implementation checklist

Legacy RFC Support

RFCs published after RFC 8650 (December 2019) are available in official RFCXML v3 format. Earlier RFCs may not have XML available.

This server includes automatic fallback functionality - when XML is unavailable, it parses the text format instead.

Source Information

All responses include source information:

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

_source	Description
xml	Parsed from RFCXML (high accuracy)
text	Parsed from text (medium accuracy)

Compatibility

RFC	Format	Notes
RFC 8650+	XML	Official RFCXML v3 support
Before RFC 8650	Text	Automatic fallback

Output Samples

get_rfc_structure - Get RFC Structure

{
  "metadata": {
    "title": "Transmission Control Protocol (TCP)",
    "docName": "draft-ietf-tcpm-rfc793bis-28",
    "number": 9293
  },
  "sections": [
    {
      "number": "section-1",
      "title": "Purpose and Scope"
    },
    {
      "number": "section-3",
      "title": "Functional Specification",
      "subsections": [
        { "number": "section-3.1", "title": "Header Format" },
        {
          "number": "section-3.5",
          "title": "Establishing a Connection",
          "subsections": [
            { "number": "section-3.5.1", "title": "Half-Open Connections and Other Anomalies" },
            { "number": "section-3.5.2", "title": "Reset Generation" }
          ]
        }
      ]
    }
  ],
  "referenceCount": { "normative": 15, "informative": 85 },
  "_source": "xml"
}

get_requirements - Extract Normative Requirements

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

get_rfc_dependencies - Get RFC Dependencies

{
  "rfc": 9293,
  "normative": [
    { "rfcNumber": 791, "title": "Internet Protocol", "anchor": "RFC0791" },
    { "rfcNumber": 2119, "title": "Key words for use in RFCs to Indicate Requirement Levels" },
    { "rfcNumber": 5681, "title": "TCP Congestion Control" }
  ],
  "informative": [
    { "rfcNumber": 793, "title": "Transmission Control Protocol" },
    { "rfcNumber": 1122, "title": "Requirements for Internet Hosts - Communication Layers" }
  ],
  "_source": "xml"
}

generate_checklist - Generate Implementation Checklist

# RFC 9293 Implementation Checklist

**Transmission Control Protocol (TCP)**

Role: Client

## Required (MUST / REQUIRED / SHALL)

- [ ] A TCP implementation support simultaneous open attempts (MUST-10). (section-3.5)
- [ ] TCP endpoints implement both sending and receiving the MSS Option (MUST-14). (section-3.7.1)
- [ ] The RTO be computed according to the algorithm in, including Karn's algorithm (MUST-18). (section-3.8.1)

## Optional (MAY / OPTIONAL)

- [ ] Implementers include "keep-alives" in their TCP implementations (MAY-5). (section-3.8.4)

Text Fallback Output (Legacy RFCs)

{
  "metadata": {
    "title": "The WebSocket Protocol",
    "number": 6455
  },
  "sections": [
    { "number": "1", "title": "Introduction" },
    { "number": "5", "title": "Data Framing" }
  ],
  "_source": "text",
  "_sourceNote": "Warning: Parsed from text format. Accuracy may be limited."
}

Examples

See the examples/ directory for complete checklist samples:

RFC	Protocol	Source
RFC 6455	WebSocket	Text (fallback)
RFC 9293	TCP	RFCXML
RFC 7540	HTTP/2	Text (fallback)

Example prompt for Claude:

Generate an implementation checklist for RFC 9293 (TCP).

Internal Architecture

Module Structure

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 Fetch Optimization

Sends parallel requests to multiple sources (RFC Editor, IETF Tools, Datatracker) and uses the first successful response:

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

Cache Strategy

LRU (Least Recently Used) cache with memory limits:

Cache	Max Entries	Content
XML Cache	20	Raw RFCXML
Text Cache	20	Raw text
Metadata Cache	100	RFC metadata
Parse Cache	50	Parsed structure

Development

# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Test (watch mode)
npm test

# Test (single run — for CI etc.)
npm test -- --run

# E2E test (MCP client integration)
npm run test:e2e

# Lint
npm run lint

# Format
npm run format

License

MIT

Related Projects

• mjpitz/mcp-rfc - Text-based RFC MCP
• ietf-tools/RFCXML - RFCXML schema
• xml2rfc - IETF official tool