docs(mcp-integration): add scripts reference to SKILL.md#77
Closed
docs(mcp-integration): add scripts reference to SKILL.md#77
Conversation
## 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>
## Summary Adds `search-mcp-servers.sh` discovery script to the mcp-integration skill, enabling programmatic MCP server discovery with GitHub popularity ranking directly from the command line. ## Problem Fixes #73 When developing plugins that require MCP server integrations, discovering relevant servers is currently a manual, tedious process requiring users to browse web interfaces, with no programmatic search or popularity metrics. ## Solution Created a comprehensive bash script that: 1. Queries the official MCP Registry API 2. Enriches results with GitHub stars for popularity ranking 3. Sorts by stars (descending) for quality signal 4. Supports multiple output formats for different use cases ### Features - **Search by keywords**: `./search-mcp-servers.sh database postgres` - **Limit results**: `--limit N` (default: 10) - **Output formats**: `--format table|json|simple` - **Transport filter**: `--transport stdio|sse|http|ws` - **Graceful error handling**: Network issues, rate limits, missing repos ### Output Example (table) ``` ┌─────────────────────────────────────────────────────────────────┐ │ MCP Server Discovery Results (sorted by GitHub stars) │ ├─────────────────────────────────────────────────────────────────┤ │ ⭐ 1,247 @modelcontextprotocol/server-postgres │ │ PostgreSQL database integration with query support │ │ https://github.com/modelcontextprotocol/servers │ └─────────────────────────────────────────────────────────────────┘ ``` ### Alternatives Considered 1. **WebSearch-only approach**: Unstructured results, no metrics 2. **Smithery API integration**: Third-party dependency, undocumented API 3. **Curated static list**: Gets stale, requires maintenance Chose official Registry + GitHub enrichment for best balance of official data source, objective popularity metric, and minimal dependencies. ## Changes - **`scripts/search-mcp-servers.sh`** (new): ~380 lines implementing full discovery functionality - **`references/discovery.md`**: Updated to reference implemented script with usage examples ## Testing **Test Configuration**: - shellcheck: ✅ Passes with no warnings - markdownlint: ✅ Passes - OS: macOS **Acceptance Criteria** (from issue): - [x] Script accepts search keywords as positional arguments - [x] Queries official MCP Registry API successfully - [x] Extracts and fetches GitHub star counts when repos available - [x] Sorts results by star count (descending) - [x] Outputs formatted results with: name, description, stars, repo URL - [x] Handles "no results" case gracefully - [x] Handles network errors with informative messages - [x] Includes `--help` with usage examples - [x] Supports `--limit` option for result count - [x] Supports `--format json` for machine-readable output - [x] Passes shellcheck linting - [x] Documented in skill's scripts section ## Checklist ### General - [x] Follows style guidelines (matches existing scripts) - [x] Self-reviewed - [x] No new warnings or errors ### Shell Script - [x] shellcheck passes - [x] Uses `set -euo pipefail` - [x] Proper error handling - [x] Help message with examples ### Documentation - [x] Updated discovery.md with script usage --- 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude <noreply@anthropic.com>
Add Scripts subsection to the Additional Resources section of the mcp-integration skill SKILL.md. This improves discoverability of the search-mcp-servers.sh utility that was previously only documented within references/discovery.md. Fixes #76 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
|
Claude finished @sjnims's task —— View job Review of PR #77: Add Scripts Reference to SKILL.md
Summary✅ Looks good - This is a clean documentation improvement that follows existing patterns. What's Good
Checklist VerificationFrom the PR description:
Additional NotesThe diff shows: +### Scripts
+
+Utility scripts in `scripts/`:
+
+- **`search-mcp-servers.sh`** - Search MCP Registry with GitHub star rankings (see `references/discovery.md` for usage)
+This placement is logical - it appears right after "Example Configurations" and before "External Resources", completing the inventory of bundled resources. Recommendation: ✅ Approve and merge. |
claude
Bot
added
documentation
sjnims
deleted the
docs/76-add-scripts-reference-to-mcp-integration-skill
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add a Scripts subsection to the mcp-integration skill's Additional Resources section, improving discoverability of the
search-mcp-servers.shutility.Problem
Fixes #76
The
scripts/directory contains a useful utility (search-mcp-servers.sh) for discovering MCP servers with GitHub star rankings. However, this script was not referenced in SKILL.md's Additional Resources section, making it less discoverable for users browsing the skill documentation.Solution
Added a
### Scriptssubsection to the Additional Resources section, following the same pattern used for Reference Files and Example Configurations. This creates a complete inventory of bundled resources in one place.Alternatives Considered
None - this is a straightforward documentation addition following existing patterns.
Changes
plugins/plugin-dev/skills/mcp-integration/SKILL.md: Added Scripts subsection with reference tosearch-mcp-servers.shTesting
scripts/search-mcp-servers.sh)🤖 Generated with Claude Code