Skip to main content
Glama
Chin-mae

skillfinder-mcp

by Chin-mae
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

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.

Related MCP server: skillsmp-mcp-server

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

{
  "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.

Available Tools

2 tools
refresh_indexA

Force a full re-fetch of the skill index from GitHub, bypassing the cache. Use this if you know the upstream skill repo was recently updated.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose that the operation re-fetches from GitHub and bypasses the cache, which is useful. However, it does not mention potential side effects, failure conditions, network dependency, or whether the cache is invalidated before the fetch succeeds.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The core behavior is front-loaded, and the usage condition follows directly. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, straightforward refresh operation, the description is complete: it states what happens, where data comes from, and when to use it. The sibling tool is not confused with this one, and no output schema is needed for such a simple action.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema provides full coverage and the description does not need to explain parameter meaning. The baseline of 4 applies, and the description adds context about the underlying fetch behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Force a full re-fetch') applied to a specific resource ('the skill index from GitHub') and distinguishes it from the sibling search_skills, which searches rather than refreshes. There is no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit condition for use: 'Use this if you know the upstream skill repo was recently updated.' It could also state when not to use it, but the provided condition is clear and actionable enough for an agent to select this tool appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_skillsA

Search the skill library for skills relevant to your current task. Pass a natural language description of what you're working on and get back the most relevant skill documents with full content. Call this BEFORE starting any coding task to get specialized guidance.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoNumber of results to return (default: 3, max: 10)
queryYesNatural language description of the task or topic to find skills for

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the behavioral burden. It discloses the input (natural language task description) and output (full content of relevant skill documents), which implies a read-only search operation. It does not describe ordering guarantees or indexing behavior, but that is acceptable for a straightforward search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The core action and output are front-loaded, and the usage timing is stated at the end without unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter search tool without an output schema, the description covers the input format, output behavior, and when to invoke it. The limit parameter is already documented in the schema, so nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already well documented: query as a natural language description and limit with default and maximum. The description adds little beyond the schema, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly specifies the verb 'Search', the resource 'skill library', and the return value 'most relevant skill documents with full content'. The search-vs-index purpose is unambiguous even without naming the sibling tool refresh_index.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use the tool: 'Call this BEFORE starting any coding task to get specialized guidance'. This provides a strong trigger condition, though it does not name alternatives or describe when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.1.0
    • First observedrefresh_index
    • First observedsearch_skills
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 2 tools

Disambiguation5/5

search_skills and refresh_index serve clearly different purposes—one retrieves relevant skill documents, the other updates the underlying index. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tool names follow a consistent verb_noun snake_case pattern (search_skills, refresh_index). The verbs clearly describe the action and the nouns identify the target.

Tool Count4/5

Two tools is slightly below the typical 3-15 range, but for a focused skill-finding server the pair is logical: one core search tool and one maintenance tool. It is not thin enough to feel incomplete.

Completeness5/5

The domain is read-only skill discovery, and the search tool returns full skill content while refresh_index keeps the library current. No obvious operations are missing for this server's stated purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers