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

2. `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`

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

```bash
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

```bash
npm install
npm run build
npm start
```

Run the automated test suite:

```bash
npm test
```

Run integration test:

```bash
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](LICENSE).