MD3 Docs

npm version

MD3 Docs is a stdio Model Context Protocol server for the live Material Design 3 documentation. It gives Codex, ChatGPT, and other MCP clients concise access to official English Foundations, Styles, and Components content.

Version 2 adds task-focused context gathering, semantic Markdown pagination, explicit structured output schemas, clean search results, and source citations. The server does not bundle a documentation snapshot, translate content, call another model, or use unofficial sources.

Requirements

• Node.js 20 or later
• Network access to https://m3.material.io

Configure

The recommended setup runs the latest published package through npx:

{
  "mcpServers": {
    "MD3-Docs": {
      "command": "npx",
      "args": ["-y", "md3-docs-mcp@latest"]
    }
  }
}

Alternatively, install it globally:

npm install --global md3-docs-mcp

Then use md3-docs-mcp as the MCP server command.

The server communicates only over stdio. Protocol messages are written to stdout and diagnostics to stderr.

Tools

browse_md3_docs

Browse the official directory by category or canonical path prefix.

{
  "category": "components",
  "prefix": "components/button",
  "limit": 20
}

Inputs:

• category: optional foundations, styles, or components
• prefix: optional canonical path prefix
• limit: 1–100, default 50
• cursor: opaque cursor from the preceding page

Directory entries include their title, path, category, available sections, description, updated date, and official source URL.

search_md3_docs

Search the official site using natural language.

{
  "query": "navigation on large screens",
  "category": "components",
  "limit": 10
}

Search results are deduplicated and cleaned of HTML and site-navigation noise. Each result contains a stable rank, canonical path, optional section, concise snippet, and source URL.

read_md3_doc

Read one canonical path or clean https://m3.material.io/ URL.

{
  "path": "components/buttons/guidelines",
  "heading": "Placement",
  "maxCharacters": 12000
}

Inputs:

• path: canonical path or official URL
• section: optional section name when it is not already present in the path
• heading: optional exact heading within the selected section
• maxCharacters: 1,000–30,000, default 12,000
• cursor: opaque semantic-page cursor

Pagination happens between sections, content blocks, paragraphs, tables, and complete code fences. It never slices the response at an arbitrary character offset. The result reports available sections and headings, page and block ranges, media metadata, the live content version, and whether more pages remain.

get_md3_context

Gather several official sources for one task in a single call.

{
  "task": "Implement and review navigation for a large-screen mail app",
  "mode": "implementation",
  "paths": ["components/navigation-rail/guidelines"],
  "maxSources": 5,
  "maxCharacters": 20000
}

Inputs:

• task: the implementation, review, or research question
• mode: implementation, review, or research; default research
• paths: up to five optional sources that must be considered first
• category: optional documentation category
• maxSources: 1–8, default 5
• maxCharacters: 4,000–40,000, default 20,000

The tool combines pinned paths, official search results, and directory matches. It loads candidate documents concurrently and ranks intact semantic blocks by task relevance:

• implementation prioritizes Guidelines, Specs, Overview, and Accessibility.
• review prioritizes Guidelines and Accessibility and adds a cited review checklist.
• research follows query relevance without imposing a workflow-specific section order.

Context excerpts use source labels such as [S1]; the structured result maps every label to its official URL. A failed candidate becomes a warning when other evidence is available. The tool returns an error only when it cannot produce any usable official evidence.

The character budget applies to the Markdown body, not protocol metadata.

Errors

Tool errors are JSON objects with a stable code, message, and retryable flag. Relevant codes include:

• INVALID_PATH and INVALID_REQUEST
• NOT_FOUND
• CURSOR_INVALID and CURSOR_STALE
• UPSTREAM_HTTP, UPSTREAM_TIMEOUT, and UPSTREAM_SCHEMA

Paths are restricted to clean official URLs under foundations, styles, and components. Credentials, query strings, fragments, traversal, ambiguous separators, and external hosts are rejected.

Fetching and caching

• The site index, directory, search pages, raw documents, semantic documents, rendered resources, and context dependencies use five-minute in-process LRU caches.
• Identical concurrent requests share one upstream operation.
• Context documents and auxiliary resource tables load with a concurrency limit of four.
• Requests time out after ten seconds.
• Network failures, HTTP 429, and selected 5xx responses retry once with exponential jitter. Retry-After is honored up to ten seconds.
• Expired content is not served when refresh fails, and no persistent cache is written.

The Material site uses unpublished structured endpoints. If their schema changes, tools return UPSTREAM_SCHEMA; the opt-in live test diagnoses compatibility.

Development

git clone https://github.com/ChouChiu/MD3-Docs-MCP.git
cd MD3-Docs-MCP
bun install --frozen-lockfile
bun run check
bun run test
bun run test:live
bun run build

Development uses Bun for dependency and script management. Published packages contain compiled JavaScript in dist/; runtime users do not install TypeScript or tsx.

The source is feature-driven:

src/
├── app/                    # Server composition
├── features/
│   ├── catalog/            # browse_md3_docs
│   ├── context/            # get_md3_context and evidence ranking
│   ├── document/           # semantic model, rendering, and read_md3_doc
│   └── search/             # search_md3_docs
├── infrastructure/
│   └── material/           # Live Material site client and parsers
└── shared/                 # Cache, HTTP, errors, cursors, concurrency, version

Offline tests cover protocol contracts, semantic pagination, ranking, caching, retries, compiled CLI startup, and the packed npm artifact. Live tests contact m3.material.io only when MD3_LIVE_TESTS=1.

Migrating from v1

Version 2 is intentionally incompatible:

• list_md3_docs is replaced by browse_md3_docs.
• read_md3_doc uses semantic pages instead of character offsets and has a new cursor shape.
• Search and read tools return explicit v2 structured output.
• get_md3_context is new.
• MCP Resources and md3-docs:// URIs are removed.
• The minimum runtime changes from Node.js 24 to Node.js 20.

Remove stored v1 cursors when upgrading. Tool clients should rediscover schemas after restarting the server.

Release

Semantic version tags such as v2.0.0 must match package.json. CI validates formatting, types, offline tests, the compiled CLI, and npm package contents before publication. Releases publish only dist/, the README, license, and package metadata. The compiled dist/index.js contains the Node.js shebang and serves directly as the npm executable.

License and attribution

The server source is available under the MIT License.

Material Design documentation, media, trademarks, and remotely fetched content remain the property of their respective owners and are not covered by this repository's license. All returned evidence retains its official source URL.