docs(mcp-integration): add MCP server discovery reference

[sjnims]

Description

Adds comprehensive reference documentation for discovering and evaluating MCP servers to integrate into Claude Code plugins. This addresses a gap in the mcp-integration skill where users had no guidance on finding appropriate servers for their plugin needs.

Type of Change

• Documentation update (improvements to README, CLAUDE.md, or component docs)

Component(s) Affected

• Skills (methodology and best practices)

Motivation and Context

When building a plugin that needs external capabilities (database access, API integration, file operations), users currently must manually browse registries, guess at search terms, evaluate quality blindly, and potentially miss relevant options. This creates friction in the plugin development workflow.

Fixes #72

How Has This Been Tested?

Test Configuration:

• markdownlint: Passes with no errors
• OS: macOS

Test Steps:

1. Ran markdownlint on both changed files - passes
2. Verified file structure matches existing references (server-types.md pattern)
3. Confirmed SKILL.md update correctly references the new file

Checklist

General

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• My changes generate no new warnings or errors

Documentation

• I have updated the documentation accordingly (README.md, CLAUDE.md, or component docs)
• I have verified all links work correctly

Markdown

• I have run markdownlint and fixed all issues
• My markdown follows the repository style (ATX headers, dash lists, fenced code blocks)

Component-Specific Checks

Skills (if applicable)

• SKILL.md references section updated
• New reference file follows established format
• Content organized with clear sections and tables

Testing

• I have verified markdown linting passes

Changes

• references/discovery.md (new): ~1,100 word reference covering:

  • Overview of when to use MCP servers vs custom solutions
  • Official MCP Registry API (endpoint, search syntax, response structure)
  • Alternative discovery sources (Smithery.ai, npm, GitHub, MCP.SO)
  • Category mappings table for common plugin needs
  • Evaluation criteria (popularity, maintenance, quality, red flags)
  • Discovery workflow recommendations
  • Reference to companion script in #73

• SKILL.md: Added reference to new discovery.md file

Additional Notes

This establishes the conceptual foundation; a companion feature issue (#73) will implement the discovery script referenced in the documentation.

---

🤖 Generated with Claude Code

[claude]

Claude finished @sjnims's task —— View job

---

Review Complete: PR #74

Summary

✅ Looks good - Excellent documentation addition

This PR adds comprehensive MCP server discovery reference documentation that fills an important gap in the mcp-integration skill. The content is well-structured, thorough, and follows all repository conventions.

---

What's Good

📚 Content Quality

• Comprehensive coverage: ~1,100 words covering official registry API, alternative sources (Smithery, npm, GitHub, MCP.SO), evaluation criteria, and practical workflows
• Actionable guidance: Clear category mappings table, quality metrics with specific thresholds, and step-by-step discovery workflow
• Progressive disclosure: Properly placed in references/ directory as detailed reference material, not cluttering main SKILL.md
• Real-world focus: Includes red flags, quality markers, and practical evaluation criteria

🏗️ Structure & Organization

• Logical flow: Moves from "when to use MCP servers" → discovery sources → evaluation → workflow
• Excellent tables: Category mappings, quality metrics, and red flags tables provide quick reference
• Proper references update: SKILL.md correctly updated to link new reference file (line 523)
• Future-proofing: References companion script in #73 for automation

✅ Technical Compliance

• Markdown linting: Passes markdownlint with zero errors
• Skill conventions: Follows progressive disclosure pattern (detailed content in references/)
• Documentation style: Matches existing reference files (server-types.md pattern)
• Example quality: Code blocks use proper syntax highlighting, realistic examples

---

Suggestions

Minor Enhancement Opportunities (optional, not blocking):

1. API Example Enhancement (lines 57-69)

   • Consider adding a note about authentication requirements for the official registry API (if any)
   • Example curl command would help users test the endpoint quickly:

   curl "https://registry.modelcontextprotocol.io/v0/servers?search=filesystem&limit=5"

2. Version Compatibility (line 284)

   • The checklist mentions "Works with current MCP protocol version" but doesn't specify how to check this
   • Could reference where protocol version is documented or how to verify compatibility

3. Search Strategy Priority (lines 268-275)

   • Excellent prioritized list! Consider adding a sentence about when to skip official sources and go straight to community (e.g., for niche use cases)

These are truly minor - the documentation is already production-ready.

---

Markdown Linting

✅ All checks passed

markdownlint --config .markdownlint.json \
  plugins/plugin-dev/skills/mcp-integration/SKILL.md \
  plugins/plugin-dev/skills/mcp-integration/references/discovery.md

No errors or warnings.

---

Checklist Verification

Reviewing against the PR checklist:

General

• ✅ Follows style guidelines
• ✅ Self-reviewed
• ✅ No new warnings or errors

Documentation

• ✅ Documentation updated (SKILL.md references section)
• ✅ All links work correctly (verified internal reference and external URLs)

Markdown

• ✅ markdownlint passes
• ✅ Follows repository style (ATX headers, dash lists, fenced code blocks)

Skills (Component-Specific)

• ✅ SKILL.md references section updated (line 523)
• ✅ New reference file follows established format (matches server-types.md pattern)
• ✅ Content organized with clear sections and tables

Testing

• ✅ Markdown linting verified

---

Files Changed

plugins/plugin-dev/skills/mcp-integration/SKILL.md (+1 line)

• Added reference to references/discovery.md in the Additional Resources section

plugins/plugin-dev/skills/mcp-integration/references/discovery.md (new file, +295 lines)

• Comprehensive MCP server discovery guide
• Official registry API documentation
• Alternative sources (Smithery, npm, GitHub, MCP.SO)
• Category mappings for common plugin needs
• Evaluation criteria with metrics
• Discovery workflow recommendations

---

Recommendation

✅ Approved - Ready to merge

This PR achieves its stated goal of addressing the discovery gap in the mcp-integration skill. The documentation is thorough, well-organized, and will significantly improve the plugin development workflow for users needing external capabilities.

The minor suggestions above are truly optional enhancements - the current implementation is excellent and ready for production.

---

[sjnims]

Addressed review suggestions 1 and 2:

1. API Example Enhancement ✅
Added curl command for quick API testing with note about no authentication requirement.

2. Version Compatibility ✅
Added guidance on verifying protocol compatibility by checking @modelcontextprotocol/sdk dependency version in package.json or README.

Skipped suggestion 3 (niche use cases) as the current prioritized list already implies flexibility.

[claude]

Claude finished @sjnims's task —— View job

---

Review Complete: Updates Look Great! ✅

Todo List

• Get PR diff to see latest changes
• Read updated files to verify suggestions addressed
• Run markdownlint on changed files
• Verify suggestions 1 and 2 are properly addressed
• Post review feedback

---

Summary

✅ Excellent updates - Both review suggestions have been properly addressed with clear, actionable improvements to the documentation.

---

What Was Added

Suggestion 1: API Example Enhancement ✅ (lines 55-61)

• Added practical curl command for quick testing: curl "https://registry.modelcontextprotocol.io/v0/servers?search=filesystem&limit=5"
• Clarified that no authentication is required
• Provides immediate hands-on way for users to test the API

Suggestion 2: Version Compatibility ✅ (lines 292-294)

• Added concrete guidance on verifying protocol compatibility
• Directs users to check @modelcontextprotocol/sdk dependency in package.json
• Provides fallback: check README for protocol version notes
• Makes the checklist item actionable rather than vague

---

Markdown Linting

✅ All checks passed

markdownlint --config .markdownlint.json \
  plugins/plugin-dev/skills/mcp-integration/SKILL.md \
  plugins/plugin-dev/skills/mcp-integration/references/discovery.md

No errors or warnings.

---

Quality Assessment

Both additions follow the documentation style established in the file:

• Practical focus: Curl example gives users immediate way to experiment
• Specific guidance: Version compatibility check is concrete and actionable
• Appropriate placement: Both additions fit naturally into their sections
• Clear language: No jargon, straightforward instructions

The decision to skip suggestion 3 (niche use cases) was appropriate - the existing prioritized list (lines 277-282) already provides sufficient flexibility.

---

Final Recommendation

✅ Ready to merge

The updates directly address the review feedback and enhance the documentation's practical value. Users can now:

1. Quickly test the registry API with a copy-paste command
2. Verify protocol compatibility with specific, actionable steps

No further changes needed.

---