skillfinder-mcp

SkillFinder MCP

SkillFinder MCP is an MCP (Model Context Protocol) server that provides on-demand skill discovery for AI coding agents.

Instead of loading a full skill library into context up front, it lets an agent query only what is relevant, pulls skills from GitHub, and returns full SKILL.md content for immediate use.

On startup, the server hydrates from local cache immediately (if present), then checks upstream SHA in the background and refreshes automatically when needed.

During package installation, SkillFinder also attempts a one-time cache prewarm so the first MCP query is faster.

Why Use It

• Reduces context bloat by loading only relevant skills.
• Uses fast local BM25 ranking over skill metadata.
• Auto-syncs from the upstream repository when content changes.
• Runs over stdio with no database, embeddings, or external service.

Features

• Fast BM25 search over skill name, description, and tags.
• Immediate cache hydration with background SHA validation.
• Duplicate skill handling with preference for canonical skills/ paths.
• Local disk cache for fast warm starts.
• Automatic zip-archive fallback when GitHub API is unavailable/rate-limited.

Tools Exposed

1. search_skills(query: string, limit?: number)

Returns the most relevant skills and full SKILL.md content.

1. refresh_index()

Forces a full index rebuild from GitHub (bypasses cache check).

Installation and Usage

SkillFinder MCP runs via stdio and is typically launched with npx.

Claude Desktop

Config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "skillfinder": {
      "command": "npx",
      "args": ["-y", "skillfinder-mcp"]
    }
  }
}

Cursor

In Cursor: Features -> MCP Servers -> Add New MCP Server

• Type: command
• Name: skillfinder
• Command: npx -y skillfinder-mcp

Claude Code

claude mcp add skillfinder -- npx -y skillfinder-mcp

Configuration

Set optional environment variables in your MCP server config:

| Variable | Description | Default | | -------- | ----------- | ------- | | SKILLFINDER_REPO | GitHub repository containing skills (owner/repo) | sickn33/antigravity-awesome-skills | | SKILLFINDER_RESULTS | Default number of search results (1-10) | 3 | | SKILLFINDER_GITHUB_TOKEN | Optional GitHub token to increase API limit | None | | SKILLFINDER_FETCH_CONCURRENCY | Parallel raw file fetch count during full index build (1-40) | 40 | | SKILLFINDER_HTTP_TIMEOUT_MS | Per-request timeout in milliseconds (1000-60000) | 15000 | | SKILLFINDER_PREWARM_ON_INSTALL | Enable/disable install-time cache prewarm (1/0, true/false) | Enabled |

Local Development

npm install
npm run build
npm start

Run the automated test suite:

npm test

Run integration test:

node test-run.mjs

Operational Notes

• Cache location:
• macOS: ~/Library/Caches/skillfinder-mcp/index.json
• Linux: $XDG_CACHE_HOME/skillfinder-mcp/index.json (or ~/.cache/...)
• Windows: %LOCALAPPDATA%\skillfinder-mcp\index.json
• If GitHub is temporarily unavailable, stale cache is used when present.
• Install-time prewarm does not fail installation if GitHub is unavailable.
• First run can take longer due to full index fetch (often 10-30s depending on network).
• Warm starts are typically near-instant because results are served from cache.

License

MIT. See LICENSE.