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

## 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

- [x] Documentation update (improvements to README, CLAUDE.md, or
component docs)

## Component(s) Affected

- [x] 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

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

### Documentation

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

### Markdown

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

### Component-Specific Checks

#### Skills (if applicable)

- [x] SKILL.md references section updated
- [x] New reference file follows established format
- [x] Content organized with clear sections and tables

### Testing

- [x] 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](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: sjnims

plugins/plugin-dev/skills/mcp-integration/SKILL.md

@@ -520,6 +520,7 @@ For detailed information, consult:
 - **`references/server-types.md`** - Deep dive on each server type
 - **`references/authentication.md`** - Authentication patterns and OAuth
 - **`references/tool-usage.md`** - Using MCP tools in commands and agents
+- **`references/discovery.md`** - Finding and evaluating MCP servers
 
 ### Example Configurations
 

plugins/plugin-dev/skills/mcp-integration/references/discovery.md

@@ -0,0 +1,305 @@
+# MCP Server Discovery: Finding and Evaluating Servers
+
+Complete reference for discovering MCP servers to integrate into Claude Code plugins.
+
+## Overview
+
+When building plugins that need external capabilities, finding the right MCP server saves development time and leverages community-tested implementations. This guide covers discovery sources, search strategies, and evaluation criteria.
+
+### When to Use MCP Servers
+
+**Integrate existing MCP servers when:**
+
+- Standard functionality exists (file system, database, API clients)
+- Multiple tools needed from single service (10+ related operations)
+- OAuth or complex authentication required
+- Community maintenance preferred over custom implementation
+
+**Build custom solutions when:**
+
+- Functionality is unique to your use case
+- Only 1-2 simple tools needed
+- Tight integration with plugin logic required
+- Existing servers don't meet security requirements
+
+## Official MCP Registry
+
+The official registry at `registry.modelcontextprotocol.io` provides a REST API for discovering servers.
+
+### API Endpoint
+
+```text
+https://registry.modelcontextprotocol.io/v0/servers
+```
+
+### Search Syntax
+
+**Basic search:**
+
+```text
+GET /v0/servers?search=filesystem
+```
+
+**With limit:**
+
+```text
+GET /v0/servers?search=database&limit=10
+```
+
+**Pagination:**
+
+```text
+GET /v0/servers?cursor=<cursor_from_previous_response>
+```
+
+**Quick test:**
+
+```bash
+curl "https://registry.modelcontextprotocol.io/v0/servers?search=filesystem&limit=5"
+```
+
+No authentication required. Returns JSON with matching servers.
+
+### Response Structure
+
+```json
+{
+  "servers": [
+    {
+      "name": "@modelcontextprotocol/server-filesystem",
+      "description": "MCP server for file system operations",
+      "repository": "https://github.com/modelcontextprotocol/servers",
+      "homepage": "https://modelcontextprotocol.io"
+    }
+  ],
+  "cursor": "next_page_cursor"
+}
+```
+
+### Key Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Package/server name (often npm scope) |
+| `description` | Brief functionality summary |
+| `repository` | Source code location |
+| `homepage` | Documentation URL |
+
+### Limitations
+
+The official registry provides no popularity metrics. Supplement with GitHub stars or npm downloads for quality signals.
+
+## Alternative Discovery Sources
+
+### Smithery.ai
+
+Largest MCP server marketplace with usage metrics.
+
+**URL:** <https://smithery.ai/>
+
+**Advantages:**
+
+- Call volume statistics (popularity indicator)
+- Curated categories
+- Installation instructions
+- User ratings
+
+**Search tips:**
+
+- Browse categories for common use cases
+- Sort by popularity for battle-tested servers
+- Check "Recently Added" for new capabilities
+
+### npm Registry
+
+Official MCP servers and community packages available via npm.
+
+**Official scope search:**
+
+```bash
+npm search @modelcontextprotocol
+```
+
+**Community search:**
+
+```bash
+npm search mcp-server
+```
+
+**Key indicators:**
+
+- Weekly downloads (popularity)
+- Last publish date (maintenance)
+- Dependency count (complexity)
+
+### GitHub
+
+Direct source code access and community engagement metrics.
+
+**Topic search:**
+
+```text
+https://github.com/topics/mcp-server
+```
+
+**Curated lists:**
+
+- `awesome-mcp-servers` repositories
+- `modelcontextprotocol` organization
+
+**Search queries:**
+
+```text
+mcp server in:name,description language:TypeScript
+model context protocol in:readme
+```
+
+### MCP.SO
+
+Third-party aggregator with rankings and categories.
+
+**URL:** <https://mcp.so/>
+
+**Features:**
+
+- Combined metrics from multiple sources
+- Category browsing
+- Quick comparison view
+
+## Category Mappings
+
+Find servers for common plugin needs:
+
+| Plugin Need | Search Terms | Notable Servers |
+|-------------|--------------|-----------------|
+| Database access | postgres, sqlite, database, sql | @modelcontextprotocol/server-postgres, mcp-server-sqlite |
+| File operations | filesystem, files, directory | @modelcontextprotocol/server-filesystem |
+| GitHub integration | github, git, repository | Official GitHub MCP server |
+| Web search | search, web, exa, tavily | Exa MCP, Tavily MCP |
+| Browser automation | browser, playwright, puppeteer | Browserbase, Playwright MCP |
+| Memory/knowledge | memory, knowledge, notes | @modelcontextprotocol/server-memory |
+| Time/scheduling | time, calendar, scheduling | Google Calendar MCP |
+| HTTP/APIs | fetch, http, rest, api | mcp-server-fetch |
+| Slack integration | slack, messaging | Slack MCP server |
+| Email | email, gmail, smtp | Gmail MCP servers |
+
+## Evaluation Criteria
+
+### Popularity Signals
+
+Strong indicators of production-ready servers:
+
+| Metric | Good | Excellent |
+|--------|------|-----------|
+| GitHub stars | 50+ | 500+ |
+| npm weekly downloads | 100+ | 1,000+ |
+| Smithery call volume | 1K+ | 10K+ |
+| Forks | 10+ | 50+ |
+
+### Maintenance Indicators
+
+Signs of active development:
+
+- **Recent commits:** Last commit within 3 months
+- **Issue response time:** Maintainers respond within 1-2 weeks
+- **Release cadence:** Regular releases (monthly or quarterly)
+- **Open issues ratio:** Less than 50% of total issues open
+
+### Quality Markers
+
+Technical quality signals:
+
+- **TypeScript:** Type safety and better IDE support
+- **Tests:** Test suite with reasonable coverage
+- **Documentation:** README with setup instructions and examples
+- **Semantic versioning:** Proper version management
+- **License:** Permissive license (MIT, Apache 2.0)
+- **CI/CD:** Automated testing and publishing
+
+### Red Flags
+
+Avoid servers with these issues:
+
+| Red Flag | Risk |
+|----------|------|
+| No license | Legal uncertainty |
+| Abandoned (1+ year stale) | Security vulnerabilities, no bug fixes |
+| Hardcoded secrets in examples | Poor security practices |
+| No error handling | Unreliable in production |
+| Excessive permissions | Security risk |
+| No README | Integration difficulty |
+| Only personal use | Not designed for distribution |
+
+## Discovery Workflow
+
+Recommended process for finding MCP servers:
+
+1. **Define requirements**
+   - List needed capabilities
+   - Identify authentication requirements
+   - Consider security constraints
+
+2. **Search official registry first**
+   - Query `registry.modelcontextprotocol.io`
+   - Check official `@modelcontextprotocol` packages
+
+3. **Expand to alternative sources**
+   - Browse Smithery categories
+   - Search npm for community packages
+   - Check GitHub awesome lists
+
+4. **Evaluate candidates**
+   - Apply popularity filters
+   - Check maintenance status
+   - Review code quality
+
+5. **Test integration**
+   - Clone and run locally
+   - Verify tools work as expected
+   - Check error handling
+
+6. **Document choice**
+   - Record why server was selected
+   - Note any limitations
+   - Plan for future updates
+
+## Discovery Script
+
+For automated discovery, see the companion script implementation in issue [#73](https://github.com/sjnims/plugin-dev/issues/73). Once implemented, usage:
+
+```bash
+./scripts/search-mcp-servers.sh "filesystem" --limit 10
+```
+
+## Quick Reference
+
+### Search Priority
+
+1. Official MCP Registry (`registry.modelcontextprotocol.io`)
+2. npm `@modelcontextprotocol` scope
+3. Smithery.ai curated servers
+4. npm community packages (`mcp-server-*`)
+5. GitHub topic search
+
+### Minimum Quality Bar
+
+Before integrating an MCP server, verify:
+
+- [ ] Active maintenance (commits within 6 months)
+- [ ] Proper license (MIT, Apache 2.0, etc.)
+- [ ] Documentation exists
+- [ ] No obvious security issues
+- [ ] Works with current MCP protocol version
+
+**Verifying protocol compatibility:** Check the server's `package.json` for `@modelcontextprotocol/sdk` dependency version, or look for protocol version notes in the README.
+
+### Quick Evaluation
+
+```bash
+# Check npm package health
+npm view <package-name> time.modified
+npm view <package-name> repository.url
+
+# Check GitHub activity
+gh repo view <owner/repo> --json stargazerCount,pushedAt
+```