From ddb93bd3a8753d9cb7127bf507cc87575c85ea53 Mon Sep 17 00:00:00 2001
From: Radoslav Dimitrov <radoslav@stacklok.com>
Date: Sun, 22 Mar 2026 16:42:18 +0200
Subject: [PATCH] Add contributing guidelines to prevent seed.json PRs (#1079)

<!-- Provide a brief summary of your changes -->

## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
We've been receiving numerous PRs from authors attempting to publish
their MCP server by adding entries to `data/seed.json`. This is not the
correct approach as servers should be published using the
`mcp-publisher` CLI tool.

Many of these PRs appear to be AI-generated so the existing docs aren't
being surfaced effectively. This PR adds explicit guidance in the files
that AI coding assistants actually read:
- `CONTRIBUTING.md` - shown by GitHub when opening new PRs; widely
ingested by AI tools
- `.github/copilot-instructions.md` - read by GitHub Copilot
- `CLAUDE.md` - read by Claude Code and Claude on github.com

## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->

## Breaking Changes
<!-- Will users need to update their code or configurations? -->

## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update

## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [ ] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [ ] My code follows the repository's style guidelines
- [ ] New and existing tests pass locally
- [ ] I have added appropriate error handling
- [ ] I have added or updated documentation as needed

## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->

Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>
---
 .github/copilot-instructions.md | 13 +++++++++++
 CLAUDE.md                       |  6 +++++
 CONTRIBUTING.md                 | 39 +++++++++++++++++++++++++++++++++
 3 files changed, 58 insertions(+)
 create mode 100644 .github/copilot-instructions.md
 create mode 100644 CONTRIBUTING.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..b37dd38
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,13 @@
+# Copilot Instructions for MCP Registry
+
+## Important: Publishing MCP servers
+
+The `data/seed.json` file is seed data for local development only. Do NOT create pull requests that add or modify server entries in `data/seed.json` to publish a server.
+
+To publish an MCP server to the registry, use the `mcp-publisher` CLI tool. See `docs/modelcontextprotocol-io/quickstart.mdx` for instructions.
+
+## Development
+
+- Use `make` targets where possible (run `make help` to see available targets)
+- Run `make check` to run lint, unit tests, and integration tests
+- Run `make dev-compose` to start the local development environment
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
index 213802b..8e8969e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,3 +2,9 @@
 _Guidance for Claude Code (claude.ai/code) when working in this repository. If it's also useful to humans (probably most things!), put the instructions in README.md instead._
 
 Import @README.md
+
+## Important: Publishing MCP servers
+
+The `data/seed.json` file is seed data for local development only. Do NOT create pull requests or commits that add server entries to `data/seed.json` as a way to publish a server to the registry.
+
+To publish an MCP server, use the `mcp-publisher` CLI tool. See `docs/modelcontextprotocol-io/quickstart.mdx` for instructions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..a5a42cb
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,39 @@
+# Contributing to the MCP Registry
+
+Thank you for your interest in contributing!
+
+## Want to publish an MCP server?
+
+**Do NOT open a pull request to add your server to `data/seed.json`.**
+
+The `data/seed.json` file is seed data used only for local development. Modifying it will not publish your server to the registry.
+
+To publish an MCP server, use the official `mcp-publisher` CLI tool. See the [publishing quickstart guide](docs/modelcontextprotocol-io/quickstart.mdx) for step-by-step instructions.
+
+## Contributing to the registry codebase
+
+We welcome contributions to the registry itself! Here's how to get started:
+
+### Communication channels
+
+We use multiple channels for collaboration - see [modelcontextprotocol.io/community/communication](https://modelcontextprotocol.io/community/communication).
+
+Often (but not always) ideas flow through this pipeline:
+
+- **[Discord](https://modelcontextprotocol.io/community/communication)** - Real-time community discussions
+- **[Discussions](https://github.com/modelcontextprotocol/registry/discussions)** - Propose and discuss product/technical requirements
+- **[Issues](https://github.com/modelcontextprotocol/registry/issues)** - Track well-scoped technical work
+- **[Pull Requests](https://github.com/modelcontextprotocol/registry/pulls)** - Contribute work towards issues
+
+### Development setup
+
+See the [README](README.md#quick-start) for prerequisites and instructions on running the server locally.
+
+### Running checks
+
+```bash
+# Run lint, unit tests and integration tests
+make check
+```
+
+Run `make help` for more available commands.
\ No newline at end of file