How modelcontextprotocol/modelcontextprotocol works
Project type and purpose
• This repo is an open-source specification and documentation project. It defines the “Model Context Protocol” (MCP) schema in TypeScript and publishes it as JSON Schema, and it hosts extensive MDX-based docs powered by a static site generator (Mintlify).
File structure
• Top-level:
• schema/ – TypeScript + JSON Schema definitions, versioned by spec date (e.g., 2024-11-05, 2025-03-26, draft)
• docs/ – MDX files organizing guides, tutorials, concepts, specification chapters, images, code snippets
• .github/workflows/ – CI workflows for formatting and build
• package.json, tsconfig.json – Node/TypeScript project config
• Key patterns:
• Versioned spec directories under both docs/specification and schema
• docs/docs holds conceptual overviews, docs/quickstart holds usage examples, docs/sdk holds client/server SDK guides
• CI pipelines run lint/format on docs and schemas, likely build/publish website
README for additional insights
• Confirms: TypeScript schema → JSON Schema
• Docs are published at modelcontextprotocol.io using Mintlify
• Focus is on specification maintenance and docs generation
Main components
a. Schema Module
• TypeScript sources (schema/**/*.ts)
• JSON Schema outputs (schema/**/*.json)
b. Documentation Module
• MDX source files (docs/**/*.mdx)
• Static Site Generator (Mintlify CLI)
c. CI/CD
• GitHub Actions workflows: lint/format checks, site build, deploy
d. Hosting / CDN
• modelcontextprotocol.io
e. Consumers
• Developers pulling JSON Schema for validation
• Doc readers visiting website
f. Versioning
• Release branches or version tags mapping to schema/2025-03-26, 2024-11-05, draft
Architectural patterns and principles
• “Source of truth” separation: schema code vs. docs content
• Versioned directories ensure backward-compatible spec releases
• CI as single orchestration for code quality, build, and deployment
• Static site generation for performance and security
Relevant technologies / frameworks
• Node.js, TypeScript
• JSON Schema
• MDX (Markdown + JSX)
• Mintlify (SSG / documentation platform)
• GitHub Actions