Address AI-guided PR flood: Document correct MCP server submission workflow & tag deprecated instructions

[drQedwards]

AI Guidance Mismatch: PR Flood Root Cause & Documentation Update Proposal

Background

Recent uptick in PRs attempting to publish MCP servers via manual addition to data/<namespace>/<package>.json was observed (see PR #1008 for example). The cause, confirmed via user conversations and assistant logs, is outdated guidance given by AI assistants (GitHub Copilot, Claude, etc.).

Detailed Root Cause

• AI assistants are trained on the internal structure of this repository, which stores server definitions in data/<namespace>/<package>.json.
• Users are being advised by the AI to submit PRs that add new files in this location, believing this is the official submission workflow.
• In actuality, the correct workflow uses the mcp-publisher CLI or Registry API (documentation), not direct PR submission.
• This misunderstanding has generated a flood of PRs that must be closed manually.

Real-World Evidence

• PR Add pmll-memory-mcp entry to server.json registry . Told Jonathan why Claude used deprecated pr registry how to  #1008 documents the journey: AI guidance resulted in outdated instructions, submission via PR, manual closure, and a feedback loop with maintainers.
• The underlying concern is reinforced by comments like Jonathan's (#1008 comment), which asks for the source of these incorrect guides.

Proposal: Clear Contributor Guidance & AI-Optimized Docstrings

1. Add/update CONTRIBUTING.md:
   • Explicitly state: "Do not submit PRs to add MCP servers. Use the publisher CLI or API."
   • Reference the Quickstart Guide prominently.
2. Add a notice to the repo README and/or repo description about the submission workflow.
3. (Optional) Tag docstrings, comments, or references to deprecated internal workflows with deprecated for easier AI routing by tools like topic integrator (used in pmll-memory-mcp).
4. Encourage feedback from contributors if documentation or AI guidance appears unclear or out of date.

Impact

• Reduce manual PR triage burden for maintainers
• Correct upstream guides for both human and AI consumers
• Ensure the Registry is up-to-date and only contains valid, publisher-registered MCP servers
  Bug summary**

AI assistants (Copilot, Claude, etc.) are prompting users to submit PRs to data/<namespace>/<package>.json to publish MCP servers, instead of directing them to use the official publisher CLI or Registry API. This is causing a flood of incorrect PRs, including PR #1008, which adds manual files that do not match the sanctioned registry workflow.

Expected behavior

Documentation and repo guidance should clearly instruct users and AI agents to use the official publisher CLI or Registry API for server submission, and explicitly discourage manual PR submissions to the internal file structure.

How to reproduce

1. Ask Copilot or Claude for instructions to publish a new MCP server
2. Follow the AI-generated guidance—most recommend creating a new file in data/<namespace>/<package>.json and opening a PR
3. Submit the PR; it is closed by maintainers, referencing the correct workflow

Screenshots/Logs

• PR Add pmll-memory-mcp entry to server.json registry . Told Jonathan why Claude used deprecated pr registry how to  #1008: Add pmll-memory-mcp entry to server.json registry . Told Jonathan why Claude used deprecated pr registry how to  #1008
• Comment from Jonathan: Add pmll-memory-mcp entry to server.json registry . Told Jonathan why Claude used deprecated pr registry how to  #1008 (comment)

Proposed Solution

• Update CONTRIBUTING.md and README to emphasize the publisher CLI/API submission flow
• Clearly tag internal documentation and code comments referencing deprecated workflows as deprecated
• Encourage feedback if documentation or AI guidance appears outdated

Additional context

Using topic integrator logic from tools like pmll-memory-mcp, deprecated documentation context can be separated from actionable guidance. This assists both AI and human contributors, minimizing confusion and triage workload.