skill-library-mcp 1.0.0 → 1.2.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "skill-library",
+  "description": "On-demand access to 700+ curated skills for AI coding assistants. Search, browse categories, and load skills without polluting your context window.",
+  "version": "1.1.0",
+  "author": {
+    "name": "modbender"
+  },
+  "homepage": "https://github.com/modbender/skill-library-mcp",
+  "repository": "https://github.com/modbender/skill-library-mcp",
+  "license": "MIT",
+  "keywords": ["skills", "mcp", "skill-library", "claude-code", "ai"]
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "skill-library": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/index.js"]
+    }
+  }
+}

package/README.md

@@ -14,15 +14,31 @@ An MCP server that provides on-demand skill loading for AI coding assistants. In
 - **On-demand loading** — skills are fetched only when needed, not crammed into every conversation
 - **IDF-weighted search** — finds the right skill even from natural language queries like "help me debug a memory leak"
 - **Works with any MCP-compatible tool** — Claude Code, Cursor, Windsurf, VS Code, Claude Desktop, and others
+- **Claude Code plugin** — one-command install with `claude plugin install`
 - **Zero config** — run with `npx`, no setup needed
 
 ## Quick Start
 
+### Claude Code Plugin (Recommended)
+
+The easiest way to use this with Claude Code — install as a plugin:
+
+```bash
+claude plugin install skill-library-mcp
 ```
-npx -y skill-library-mcp
+
+The MCP server starts automatically when Claude Code launches. No manual configuration needed.
+
+To install for a specific scope:
+
+```bash
+claude plugin install skill-library-mcp --scope user      # Default, available everywhere
+claude plugin install skill-library-mcp --scope project   # Project-only, shared with collaborators
 ```
 
-Add it to your tool's MCP configuration:
+### MCP Server (Manual)
+
+For other tools or manual Claude Code setup, add to your MCP configuration:
 
 <details>
 <summary><strong>Claude Code (CLI)</strong></summary>

package/dist/index.js

@@ -6,54 +6,98 @@ import { fileURLToPath } from "url";
 import { dirname, join as join3 } from "path";
 
 // src/skill-index.ts
-import { readdir, readFile, access } from "fs/promises";
+import { readdir, readFile } from "fs/promises";
 import { join } from "path";
 import { parse as parseYaml } from "yaml";
+
+// src/tokenize.ts
+function tokenize(text) {
+  const words = text.toLowerCase().replace(/[^a-z0-9\-]/g, " ").split(/\s+/).filter(Boolean);
+  const tokens = [];
+  for (const word of words) {
+    tokens.push(word);
+    if (word.includes("-")) {
+      for (const part of word.split("-")) {
+        if (part) tokens.push(part);
+      }
+    }
+  }
+  return tokens;
+}
+
+// src/categories.ts
+var CATEGORY_KEYWORDS = [
+  ["Frontend", ["react", "angular", "vue", "svelte", "nextjs", "frontend", "css", "tailwind", "ui", "ux"]],
+  ["Backend", ["backend", "nodejs", "express", "nestjs", "fastapi", "django", "rails", "api", "rest", "graphql"]],
+  ["AI & LLM", ["ai", "llm", "agent", "prompt", "rag", "claude", "openai", "embedding", "ml"]],
+  ["DevOps & Infra", ["docker", "kubernetes", "terraform", "aws", "gcp", "azure", "deployment", "infrastructure"]],
+  ["Data & Databases", ["data", "database", "sql", "postgres", "mongodb", "redis", "analytics", "pipeline", "etl"]],
+  ["Security", ["security", "penetration", "vulnerability", "audit", "owasp", "xss", "encryption"]],
+  ["Testing", ["test", "tdd", "testing", "e2e", "vitest", "jest", "playwright"]],
+  ["Mobile", ["mobile", "react-native", "flutter", "ios", "android", "expo"]],
+  ["Automation", ["automation", "workflow", "n8n", "zapier", "scraping", "bot"]],
+  ["Python", ["python", "django", "flask", "fastapi", "pandas"]],
+  ["TypeScript & JS", ["typescript", "javascript", "deno", "bun"]],
+  ["Architecture", ["architecture", "microservices", "system-design", "patterns", "monorepo"]]
+];
+function buildCategories(entries) {
+  const categories = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const text = `${entry.dirName} ${entry.frontmatter.description}`.toLowerCase();
+    let matched = false;
+    for (const [category, keywords] of CATEGORY_KEYWORDS) {
+      if (keywords.some((kw) => text.includes(kw))) {
+        const list = categories.get(category) ?? [];
+        list.push(entry.dirName);
+        categories.set(category, list);
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) {
+      const list = categories.get("Other") ?? [];
+      list.push(entry.dirName);
+      categories.set("Other", list);
+    }
+  }
+  return categories;
+}
+
+// src/skill-index.ts
 function parseFrontmatter(content) {
   const match = content.match(/^---\n([\s\S]*?)\n---/);
   if (!match) return null;
   try {
     const parsed = parseYaml(match[1]);
     if (!parsed || typeof parsed.name !== "string") return null;
+    const metadata = parsed.metadata && typeof parsed.metadata === "object" && !Array.isArray(parsed.metadata) ? parsed.metadata : void 0;
+    const allowedTools = Array.isArray(parsed.allowedTools) && parsed.allowedTools.every((t) => typeof t === "string") ? parsed.allowedTools : void 0;
     return {
       name: parsed.name,
       description: typeof parsed.description === "string" ? parsed.description.trim() : "",
-      metadata: parsed.metadata,
-      allowedTools: parsed.allowedTools
+      metadata,
+      allowedTools
     };
   } catch {
     return null;
   }
 }
-function tokenize(text) {
-  const words = text.toLowerCase().replace(/[^a-z0-9\-]/g, " ").split(/\s+/).filter(Boolean);
-  const tokens = /* @__PURE__ */ new Set();
-  for (const word of words) {
-    tokens.add(word);
-    if (word.includes("-")) {
-      for (const part of word.split("-")) {
-        if (part) tokens.add(part);
-      }
-    }
-  }
-  return tokens;
-}
 async function buildIndex(skillsDir2) {
   const entries = [];
   let dirs;
   try {
     dirs = await readdir(skillsDir2);
   } catch {
-    return { entries, idfScores: /* @__PURE__ */ new Map(), totalDocs: 0 };
+    return { entries, idfScores: /* @__PURE__ */ new Map(), totalDocs: 0, categories: /* @__PURE__ */ new Map() };
   }
   for (const dirName of dirs) {
     const skillPath = join(skillsDir2, dirName, "SKILL.md");
+    let content;
     try {
-      await access(skillPath);
+      content = await readFile(skillPath, "utf-8");
     } catch {
       continue;
     }
-    const content = await readFile(skillPath, "utf-8");
     const frontmatter = parseFrontmatter(content);
     if (!frontmatter) continue;
     const resourceDir = join(skillsDir2, dirName, "resources");
@@ -65,10 +109,9 @@ async function buildIndex(skillsDir2) {
       hasResources = resourceFiles.length > 0;
     } catch {
     }
-    const searchTokens = /* @__PURE__ */ new Set([
-      ...tokenize(frontmatter.name),
-      ...tokenize(frontmatter.description)
-    ]);
+    const searchTokens = /* @__PURE__ */ new Set(
+      [...tokenize(frontmatter.name), ...tokenize(frontmatter.description)]
+    );
     entries.push({
       dirName,
       frontmatter,
@@ -88,7 +131,8 @@ async function buildIndex(skillsDir2) {
   for (const [token, df] of docFrequency) {
     idfScores.set(token, Math.log(totalDocs / df));
   }
-  return { entries, idfScores, totalDocs };
+  const categories = buildCategories(entries);
+  return { entries, idfScores, totalDocs, categories };
 }
 
 // src/server.ts
@@ -144,11 +188,8 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "should",
   "please"
 ]);
-function tokenize2(text) {
-  return text.toLowerCase().replace(/[^a-z0-9\-]/g, " ").split(/\s+/).filter(Boolean);
-}
 function searchSkills(index, query, limit = 20) {
-  const rawTokens = tokenize2(query);
+  const rawTokens = tokenize(query);
   if (rawTokens.length === 0) return [];
   const filtered = rawTokens.filter((t) => !STOP_WORDS.has(t));
   const meaningful = filtered.length > 0 ? filtered : rawTokens;
@@ -228,10 +269,12 @@ ${resourceContent}`;
 
 // src/server.ts
 function createServer(index, skillsDir2) {
-  const server = new McpServer({
-    name: "skill-library",
-    version: "1.0.0"
-  });
+  const server = new McpServer(
+    { name: "skill-library", version: "1.0.0" },
+    {
+      instructions: `Skill library with ${index.totalDocs} skills across ${index.categories.size} categories. Use search_skill to find skills by keyword, or list_categories to browse available categories.`
+    }
+  );
   const lookupMap = /* @__PURE__ */ new Map();
   for (const entry of index.entries) {
     lookupMap.set(entry.dirName.toLowerCase(), entry);
@@ -291,6 +334,27 @@ ${lines.join("\n")}`
       };
     }
   );
+  server.tool(
+    "list_categories",
+    "List all skill categories with counts and examples. Use this to discover what skills are available before searching.",
+    {},
+    async () => {
+      const lines = [];
+      for (const [category, skills] of index.categories) {
+        const examples = skills.slice(0, 3).join(", ");
+        const more = skills.length > 3 ? `, +${skills.length - 3} more` : "";
+        lines.push(`- **${category}** (${skills.length}) \u2014 ${examples}${more}`);
+      }
+      return {
+        content: [{
+          type: "text",
+          text: `${index.totalDocs} skills in ${index.categories.size} categories:
+
+${lines.join("\n")}`
+        }]
+      };
+    }
+  );
   return server;
 }
 

package/package.json

@@ -1,8 +1,37 @@
 {
   "name": "skill-library-mcp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "MCP server providing on-demand skill loading for AI coding assistants",
+  "license": "MIT",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/modbender/skill-library-mcp"
+  },
+  "homepage": "https://github.com/modbender/skill-library-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/modbender/skill-library-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "skills",
+    "claude",
+    "claude-code",
+    "ai",
+    "llm",
+    "coding-assistant",
+    "skill-library",
+    "mcp-server"
+  ],
+  "files": [
+    "dist/",
+    "skills/",
+    ".claude-plugin/",
+    ".mcp.json",
+    "README.md",
+    "LICENSE"
+  ],
   "bin": {
     "skill-library-mcp": "dist/index.js"
   },

package/.claude/settings.local.json

@@ -1,10 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "mcp__skill-library__search_skill",
-      "Bash(for name in \"AI Code Review\" \"CI\" \"brand-guidelines\" \"docx\" \"pdf\")",
-      "Bash(do:*)",
-      "Bash(done)"
-    ]
-  }
-}

package/.github/workflows/ci.yml

@@ -1,85 +0,0 @@
-name: CI
-
-permissions:
-  contents: read
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Run tests
-        run: pnpm test
-
-  build:
-    runs-on: ubuntu-latest
-    needs: test
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Build
-        run: pnpm build
-
-      - name: Upload build artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: dist
-          path: dist/
-          retention-days: 7
-
-  ci-summary:
-    runs-on: ubuntu-latest
-    needs: [test, build]
-    if: always()
-    steps:
-      - name: Check all jobs status
-        env:
-          TEST_RESULT: ${{ needs.test.result }}
-          BUILD_RESULT: ${{ needs.build.result }}
-        run: |
-          if [[ "$TEST_RESULT" != "success" ]]; then
-            echo "Test job failed"
-            exit 1
-          fi
-          if [[ "$BUILD_RESULT" != "success" ]]; then
-            echo "Build job failed"
-            exit 1
-          fi
-          echo "All CI jobs passed successfully"

package/.github/workflows/release.yml

@@ -1,57 +0,0 @@
-name: Release
-
-on:
-  push:
-    branches:
-      - main
-
-permissions:
-  contents: write
-  pull-requests: write
-  id-token: write
-
-jobs:
-  release-please:
-    runs-on: ubuntu-latest
-    outputs:
-      release_created: ${{ steps.release.outputs.release_created }}
-      tag_name: ${{ steps.release.outputs.tag_name }}
-    steps:
-      - uses: googleapis/release-please-action@v4
-        id: release
-        with:
-          release-type: node
-
-  publish:
-    runs-on: ubuntu-latest
-    needs: release-please
-    if: needs.release-please.outputs.release_created == 'true'
-    permissions:
-      contents: read
-      id-token: write
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          registry-url: 'https://registry.npmjs.org'
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Run tests
-        run: pnpm test
-
-      - name: Build
-        run: pnpm build
-
-      - name: Publish to npm
-        run: pnpm publish --access public --no-git-checks --provenance
-        env:
-          NPM_CONFIG_PROVENANCE: true

package/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "1.0.0"
-}

package/CLAUDE.md

@@ -1,60 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## What This Is
-
-MCP server that indexes and serves Claude Code skills on demand. It exposes two tools (`search_skill`, `load_skill`) over stdio transport using the Model Context Protocol SDK.
-
-## Commands
-
-```bash
-pnpm install          # Install dependencies
-pnpm test             # Run all tests (vitest)
-pnpm test -- test/search.test.ts              # Run a single test file
-pnpm test -- -t "exact token match"           # Run a single test by name
-pnpm build            # Build to dist/ (tsup, ESM-only, node22 target)
-pnpm dev              # Run server locally via tsx
-make ci               # Run test + build
-make mcp-test         # Build and send initialize request to verify MCP handshake
-pnpm dedup            # Check for duplicate skills
-tsx scripts/import-skills.ts <source-dir> [--no-dry-run]  # Import skills from external source
-```
-
-## Architecture
-
-The data flow is: `skills/` → `buildIndex()` → `SearchIndex` → `createServer()` → MCP tools over stdio.
-
-- `src/skill-index.ts` — Reads `skills/*/SKILL.md`, parses YAML frontmatter, builds tokenized search index with IDF scores as `SearchIndex`
-- `src/search.ts` — IDF-weighted search with stop-word filtering, query deduplication, minimum substring length (≥2 chars), name bonus +2.0, description bonus +1.0, threshold ≥0.5. Normalizes by matched token count (not total query tokens) to prevent unmatched terms from diluting scores
-- `src/loader.ts` — Loads full SKILL.md content; optionally appends `resources/*.md` files
-- `src/server.ts` — Creates `McpServer` with two tools. Builds a case-insensitive lookup map keyed by both `dirName` and `frontmatter.name`. `load_skill` falls back to fuzzy search suggestions when exact lookup fails
-- `src/index.ts` — Entry point: resolves `skills/` dir relative to `dist/`, builds index, connects stdio transport
-- `src/types.ts` — `SkillFrontmatter`, `SkillEntry`, `SearchIndex`, `SearchResult` interfaces
-- `src/dedup.ts` — Deduplication utility: finds exact (hash-based) and near (Jaccard similarity >0.8) duplicate skills. Runnable as CLI
-- `scripts/import-skills.ts` — Imports skills from external directories with dry-run support and dedup checking
-
-## Testing
-
-Two test layers, both using vitest:
-
-**Unit tests** use synthetic skills in `test/fixtures/` for deterministic results. Never use the real `skills/` directory in unit tests.
-
-**Integration tests** (`test/integration.test.ts`) use the real `skills/` directory to validate index completeness and search relevance.
-
-## Conventions
-
-- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `test:`
-- ESM-only (`"type": "module"`) — all internal imports use `.js` extensions
-- Node 22 target, pnpm package manager
-- tsup bundles `src/index.ts` to `dist/index.js` with `#!/usr/bin/env node` banner
-- `skills/` lives at project root, resolved at runtime as `join(__dirname, "..", "skills")` from `dist/`
-
-## Releases
-
-Releases are fully automated via [release-please](https://github.com/googleapis/release-please). On every push to `main`, release-please analyzes conventional commits and opens/updates a Release PR with version bumps and changelog. Merging that PR creates a git tag and GitHub Release, which triggers npm publish.
-
-**Commit → version mapping:**
-- `fix: ...` → patch (1.0.0 → 1.0.1)
-- `feat: ...` → minor (1.0.0 → 1.1.0)
-- `feat!: ...` or `BREAKING CHANGE:` footer → major (1.0.0 → 2.0.0)

package/Makefile

@@ -1,18 +0,0 @@
-.PHONY: test build ci dev clean mcp-test
-
-test:        ## Run vitest
-	pnpm test
-
-build:       ## Build with tsup
-	pnpm build
-
-ci: test build  ## Run CI locally (test + build)
-
-dev:         ## Run MCP server locally via tsx
-	pnpm dev
-
-clean:       ## Remove dist/ node_modules/ coverage/
-	rm -rf dist/ node_modules/ coverage/
-
-mcp-test: build  ## Build and test MCP server with initialize request
-	@echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node dist/index.js 2>/dev/null

package/docs/architecture.md

@@ -1,61 +0,0 @@
-# Architecture
-
-## Data Flow
-
-```
-skills/ (shipped with package)
-    ↓
-buildIndex()
-    ↓
-SkillEntry[] (in-memory index)
-    ↓
-┌─────────────┴─────────────┐
-↓                           ↓
-searchSkills()          loadSkill()
-↓                           ↓
-SearchResult[]       string (content)
-↓                           ↓
-MCP tool:              MCP tool:
-search_skill          load_skill
-```
-
-1. **Index build** (`src/skill-index.ts`): Reads all `skills/*/SKILL.md` files, parses YAML frontmatter, tokenizes name+description, detects resources. Returns `SkillEntry[]`.
-
-2. **Search** (`src/search.ts`): Token-based scoring against the in-memory index. No external dependencies.
-
-3. **Load** (`src/loader.ts`): Reads SKILL.md content from disk. Optionally appends resource files alphabetically.
-
-4. **Server** (`src/server.ts`): Wraps search and load into MCP tools with a lookup map for direct name/dirName access.
-
-## Search Algorithm
-
-Given a query string, the algorithm:
-
-1. **Tokenizes** query: lowercase, remove non-alphanumeric (except hyphens), split on whitespace
-2. **Scores** each skill entry:
-   - For each query token × search token pair:
-     - Exact match: **+1.0**
-     - Substring match (either contains the other): **+0.5**
-   - Bonus: query is substring of skill name: **+0.5**
-   - Bonus: query is substring of skill description: **+0.3**
-3. **Normalizes** by dividing total score by query token count
-4. **Filters** results below 0.2 threshold
-5. **Sorts** descending by score, limits to top N (default 20)
-
-## Design Decisions
-
-- **In-memory index**: Skills are indexed once at startup. The index is small (frontmatter + tokens only, not full content). Search is O(n) over entries — fast enough for hundreds of skills.
-
-- **Lazy content loading**: Full SKILL.md content is only read from disk when `load_skill` is called. This keeps memory usage low.
-
-- **Token-based search over full-text**: Simpler, no external dependencies, good enough for skill names and descriptions. Avoids pulling in a search library.
-
-- **YAML frontmatter**: Standard format used by many tools (Jekyll, Hugo, MDX). Makes skills compatible with existing tooling.
-
-- **ESM-only**: Modern Node.js (22+) target. No CJS compatibility needed.
-
-## Performance
-
-- Index build: ~50ms for 700 skills (sequential file reads)
-- Search: <1ms for typical queries against 700 entries
-- Load: Single file read (~1ms), plus resource files if requested

package/docs/development.md

@@ -1,83 +0,0 @@
-# Development Guide
-
-## Setup
-
-```bash
-git clone <repo-url>
-cd skill-library-mcp
-pnpm install
-```
-
-Requirements: Node.js 22+, pnpm 9.15+
-
-## Testing
-
-Tests use synthetic fixtures in `test/fixtures/`, not the real `skills/` directory. This means tests work in CI without any skill data.
-
-```bash
-pnpm test              # Run all tests once
-pnpm test:watch        # Run in watch mode
-pnpm test:coverage     # Run with coverage report
-```
-
-Test files:
-- `test/skill-index.test.ts` — Index building, frontmatter parsing, resource detection
-- `test/search.test.ts` — Search scoring, ranking, limits, edge cases
-- `test/loader.test.ts` — Content loading, resource inclusion, alphabetical ordering
-
-## Build
-
-```bash
-pnpm build    # Produces dist/index.js via tsup
-```
-
-Build config is in `tsup.config.ts`:
-- Entry: `src/index.ts`
-- Format: ESM
-- Target: Node 22
-- Adds `#!/usr/bin/env node` shebang for CLI usage
-
-## Local MCP Testing
-
-Test the MCP server handshake:
-
-```bash
-make mcp-test
-```
-
-This builds the project and sends a JSON-RPC `initialize` request via stdin. You should see a valid JSON-RPC response with server capabilities.
-
-For interactive testing:
-
-```bash
-pnpm dev
-```
-
-Then paste JSON-RPC messages to stdin.
-
-## Makefile Targets
-
-| Target | Description |
-|--------|-------------|
-| `make test` | Run vitest |
-| `make build` | Build with tsup |
-| `make ci` | Run test + build |
-| `make dev` | Run MCP server via tsx |
-| `make clean` | Remove dist/, node_modules/, coverage/ |
-| `make mcp-test` | Build and test MCP initialize handshake |
-
-## Release Process
-
-1. Bump version in `package.json`
-2. Commit: `git commit -m "chore: release v1.x.x"`
-3. Tag: `git tag v1.x.x`
-4. Push: `git push && git push --tags`
-5. GitHub Actions automatically: runs tests → builds → publishes to npm (OIDC) → creates GitHub Release with changelog
-
-## Troubleshooting
-
-**Tests fail with "module not found"**: Make sure you ran `pnpm install`. The project uses ESM with `.js` extensions in imports.
-
-**`make mcp-test` shows no output**: The server writes logs to stderr. Make sure the build succeeded (`pnpm build`).
-
-**pnpm version mismatch**: The project pins `pnpm@9.15.4` via `packageManager` in `package.json`. Use `corepack enable` to auto-install the correct version.