Skip to content

Latest commit

 

History

History
186 lines (126 loc) · 6.28 KB

CONTRIBUTING.md

File metadata and controls

186 lines (126 loc) · 6.28 KB

Contributing to Model Context Protocol

Thank you for your interest in contributing to the Model Context Protocol specification, schemas, or docs! This document outlines how to contribute to this project.

Also see the overall MCP communication guidelines in our docs, which explains how and where discussions about changes happen.

General prerequisites

The following software is required to work on the spec:

  • Node.js 20 or above
  • TypeScript
  • TypeScript JSON Schema (for generating JSON schema)
  • Mintlify (optional, for docs)
  • nvm (optional, for managing Node versions)

Getting Started

  1. Fork the repository

  2. Clone your fork:

    git clone https://github.com/YOUR-USERNAME/modelcontextprotocol.git
cd modelcontextprotocol

  3. Install dependencies:

    nvm install  # install correct Node version
npm install  # install dependencies

  4. Create a new branch:

    git checkout -b feature/your-feature-name

Schema changes

Schema changes go in schema/draft/schema.ts. To validate your changes, run:

npm run check:schema:ts

schema/draft/schema.json and docs/specification/draft/schema.mdx are generated from schema/draft/schema.ts; do not edit them directly. To generate them, run:

npm run generate:schema

Documentation changes

Documentation is written in MDX format and in the docs directory.

You can preview documentation changes locally by running:

npm run serve:docs

And lint them with:

npm run check:docs
npm run format

Note

You can run all schema/documentation changes at once with npm run prep.

Blog changes

The blog is built using Hugo and located in the blog directory.

To preview blog changes locally:

npm run serve:blog

Documentation Guidelines

When contributing to the documentation:

  • Keep content clear, concise, and technically accurate
  • Follow the existing file structure and naming conventions
  • Include code examples where appropriate
  • Use proper MDX formatting and components
  • Test all links and code samples
    • You may run npm run check:docs:links to look for broken internal links.
  • Use appropriate headings: "When to use", "Steps", and "Tips" for tutorials
  • Place new pages in appropriate sections (concepts, tutorials, etc.)
  • Update docs.json when adding new pages
  • Follow existing file naming conventions (kebab-case.mdx)
  • Include proper frontmatter in MDX files

Specification Proposal Guidelines

Principles of MCP

  1. Simple + Minimal: It is much easier to add things to a specification than it is to remove them. To maintain simplicity, we keep a high bar for adding new concepts and primitives as each addition requires maintenance and compatibility consideration.
  2. Concrete: Specification changes need to be based on specific implementation challenges and not on speculative ideas.

Stages of a specification proposal

  1. Define: Explore the problem space, validate that other MCP users face a similar issue, and then clearly define the problem.
  2. Prototype: Build an example solution to the problem and demonstrate its practical application.
  3. Write: Based on the prototype, write a specification proposal.

Submitting Changes

  1. Push your changes to your fork
  2. Submit a pull request to the main repository
  3. Follow the pull request template
  4. Wait for review

AI Contributions

Important

If you are using any kind of AI assistance to contribute to Model Context Protocol, it must be disclosed in the pull request or issue.

We welcome and encourage the use of AI tools to help improve Model Context Protocol. Many valuable contributions have been enhanced with AI assistance for code generation, issue detection, and feature definition.

That being said, if you are using any kind of AI assistance (e.g., agents such as Claude Code, ChatGPT) while contributing to Model Context Protocol, this must be disclosed in the pull request or issue, along with the extent to which AI assistance was used (e.g., documentation comments vs. code generation).

If your PR responses or comments are being generated by an AI, disclose that as well.

As an exception, trivial spacing or typo fixes don't need to be disclosed, so long as the changes are limited to small parts of the code or short phrases.

An example disclosure:

This PR was written primarily by Claude Code.

Or a more detailed disclosure:

I consulted ChatGPT to understand the codebase but the solution was fully authored manually by myself.

Failure to disclose this is first and foremost rude to the human operators on the other end of the pull request, but it also makes it difficult to determine how much scrutiny to apply to the contribution.

In a perfect world, AI assistance would produce equal or higher quality work than any human. That isn't the world we live in today, and in most cases where human supervision or expertise is not in the loop, it's generating code or changes that cannot be reasonably maintained or evolved.

What we're looking for

When submitting AI-assisted contributions, please ensure they include:

  • Clear disclosure of AI use - You are transparent about AI use and degree to which you're using it for the contribution
  • Human understanding - You personally understand what the changes do
  • Clear rationale - You can explain why the change is needed and how it fits within Model Context Protocol goals
  • Concrete evidence - Include test cases, scenarios, or examples that demonstrate the improvement
  • Your own analysis - Share your thoughts on the end-to-end experience

What we'll close

We reserve the right to close submissions that appear to not follow the disclosure policy.

License

By contributing, you agree that your code or specification contributions will be licensed under the Apache License 2.0. Documentation contributions (excluding specifications) are licensed under CC-BY 4.0. See the LICENSE file for details.

Security

Please review our Security Policy for reporting security issues.