skill-library-mcp 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "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

@@ -0,0 +1,85 @@
+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

@@ -0,0 +1,57 @@
+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

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

package/CLAUDE.md

@@ -0,0 +1,60 @@
+# 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 skill-library-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Makefile

@@ -0,0 +1,18 @@
+.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/README.md

@@ -0,0 +1,222 @@
+# Skill Library MCP
+
+**690+ ready-to-use skills for AI coding assistants, served on demand via MCP.**
+
+[![npm version](https://img.shields.io/npm/v/skill-library-mcp)](https://www.npmjs.com/package/skill-library-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
+
+An MCP server that provides on-demand skill loading for AI coding assistants. Instead of stuffing your system prompt with every skill you might need, this server indexes 690+ skills and serves only the ones relevant to your current task — keeping context windows lean and responses focused.
+
+## Why?
+
+- **690+ skills** covering frontend, backend, DevOps, security, testing, databases, AI/ML, automation, and more
+- **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
+- **Zero config** — run with `npx`, no setup needed
+
+## Quick Start
+
+```
+npx -y skill-library-mcp
+```
+
+Add it to your tool's MCP configuration:
+
+<details>
+<summary><strong>Claude Code (CLI)</strong></summary>
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "skill-library": {
+      "command": "npx",
+      "args": ["-y", "skill-library-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to your `claude_desktop_config.json` ([location varies by OS](https://modelcontextprotocol.io/quickstart/user)):
+
+```json
+{
+  "mcpServers": {
+    "skill-library": {
+      "command": "npx",
+      "args": ["-y", "skill-library-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "skill-library": {
+      "command": "npx",
+      "args": ["-y", "skill-library-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "skill-library": {
+      "command": "npx",
+      "args": ["-y", "skill-library-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>VS Code (Copilot)</strong></summary>
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "skill-library": {
+      "command": "npx",
+      "args": ["-y", "skill-library-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Antigravity</strong></summary>
+
+See [Antigravity docs](https://docs.antigravity.dev) for MCP server configuration format.
+
+</details>
+
+<details>
+<summary><strong>Manual installation</strong></summary>
+
+```bash
+git clone https://github.com/modbender/skill-library-mcp
+cd skill-library-mcp
+pnpm install
+pnpm build
+```
+
+Then point your MCP config to the built binary:
+
+```json
+{
+  "mcpServers": {
+    "skill-library": {
+      "command": "node",
+      "args": ["/path/to/skill-library-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+</details>
+
+## Tools
+
+### `search_skill`
+
+Search for skills by keyword. Returns a ranked list of matching skill names and descriptions.
+
+```
+search_skill({ query: "react patterns" })
+```
+
+### `load_skill`
+
+Load the full content of a skill by name. Optionally includes resource files.
+
+```
+load_skill({ name: "brainstorming", include_resources: true })
+```
+
+## Skill Categories
+
+The library includes 690+ skills across areas like:
+
+| Category | Examples |
+|----------|----------|
+| **Frontend** | React patterns, Angular, Tailwind, accessibility, web performance |
+| **Backend** | Node.js, FastAPI, Django, NestJS, GraphQL, API design |
+| **DevOps & Cloud** | Terraform, Kubernetes, Docker, AWS, CI/CD, GitOps |
+| **Testing** | TDD workflows, Playwright, testing patterns, E2E testing |
+| **Security** | Penetration testing, OWASP, threat modeling, security scanning |
+| **AI & ML** | LLM application dev, RAG implementation, agent patterns, prompt engineering |
+| **Databases** | PostgreSQL, database design, migrations, SQL optimization |
+| **Automation** | Slack, GitHub, Jira, Salesforce, Zapier, and 40+ integrations |
+| **Architecture** | Microservices, event sourcing, CQRS, clean code, design patterns |
+
+## Skill Format
+
+Skills are directories containing a `SKILL.md` file with YAML frontmatter:
+
+```markdown
+---
+name: my-skill
+description: What this skill does
+---
+
+# My Skill
+
+Skill content here...
+```
+
+Skills can optionally include a `resources/` directory with additional `.md` files that are appended when `include_resources: true` is set.
+
+## Contributing
+
+Contributions are welcome! To add a new skill:
+
+1. Create a directory under `skills/` with your skill name
+2. Add a `SKILL.md` file with YAML frontmatter (`name`, `description`)
+3. Run `pnpm dedup` to check for duplicates
+4. Submit a PR
+
+## Development
+
+```bash
+pnpm install          # Install dependencies
+pnpm test             # Run tests
+pnpm build            # Build to dist/
+pnpm dev              # Run server locally
+pnpm dedup            # Check for duplicate skills
+make ci               # Run test + build
+```
+
+## License
+
+[MIT](LICENSE)