skill-library-mcp 1.0.0

package/dist/index.js

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { fileURLToPath } from "url";
+import { dirname, join as join3 } from "path";
+
+// src/skill-index.ts
+import { readdir, readFile, access } from "fs/promises";
+import { join } from "path";
+import { parse as parseYaml } from "yaml";
+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;
+    return {
+      name: parsed.name,
+      description: typeof parsed.description === "string" ? parsed.description.trim() : "",
+      metadata: parsed.metadata,
+      allowedTools: parsed.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 };
+  }
+  for (const dirName of dirs) {
+    const skillPath = join(skillsDir2, dirName, "SKILL.md");
+    try {
+      await access(skillPath);
+    } catch {
+      continue;
+    }
+    const content = await readFile(skillPath, "utf-8");
+    const frontmatter = parseFrontmatter(content);
+    if (!frontmatter) continue;
+    const resourceDir = join(skillsDir2, dirName, "resources");
+    let hasResources = false;
+    let resourceFiles = [];
+    try {
+      const files = await readdir(resourceDir);
+      resourceFiles = files.filter((f) => f.endsWith(".md"));
+      hasResources = resourceFiles.length > 0;
+    } catch {
+    }
+    const searchTokens = /* @__PURE__ */ new Set([
+      ...tokenize(frontmatter.name),
+      ...tokenize(frontmatter.description)
+    ]);
+    entries.push({
+      dirName,
+      frontmatter,
+      searchTokens,
+      hasResources,
+      resourceFiles
+    });
+  }
+  const totalDocs = entries.length;
+  const docFrequency = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    for (const token of entry.searchTokens) {
+      docFrequency.set(token, (docFrequency.get(token) ?? 0) + 1);
+    }
+  }
+  const idfScores = /* @__PURE__ */ new Map();
+  for (const [token, df] of docFrequency) {
+    idfScores.set(token, Math.log(totalDocs / df));
+  }
+  return { entries, idfScores, totalDocs };
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// src/search.ts
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "build",
+  "write",
+  "create",
+  "use",
+  "using",
+  "when",
+  "this",
+  "for",
+  "from",
+  "with",
+  "that",
+  "are",
+  "has",
+  "its",
+  "was",
+  "will",
+  "your",
+  "you",
+  "is",
+  "it",
+  "in",
+  "on",
+  "of",
+  "to",
+  "be",
+  "by",
+  "at",
+  "as",
+  "and",
+  "help",
+  "need",
+  "want",
+  "how",
+  "do",
+  "can",
+  "me",
+  "i",
+  "my",
+  "show",
+  "about",
+  "what",
+  "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);
+  if (rawTokens.length === 0) return [];
+  const filtered = rawTokens.filter((t) => !STOP_WORDS.has(t));
+  const meaningful = filtered.length > 0 ? filtered : rawTokens;
+  const queryTokens = [...new Set(meaningful)];
+  const queryLower = query.toLowerCase();
+  const results = [];
+  const defaultIdf = Math.log((index.totalDocs || 1) + 1);
+  for (const entry of index.entries) {
+    let score = 0;
+    let matchedTokens = 0;
+    for (const qt of queryTokens) {
+      const idfWeight = index.idfScores.get(qt) ?? defaultIdf;
+      let bestTokenScore = 0;
+      for (const st of entry.searchTokens) {
+        if (st === qt) {
+          bestTokenScore = Math.max(bestTokenScore, idfWeight);
+        } else if (qt.length >= 2 && st.length >= 2 && (st.includes(qt) || qt.includes(st))) {
+          bestTokenScore = Math.max(bestTokenScore, idfWeight * 0.5);
+        }
+      }
+      if (bestTokenScore > 0) matchedTokens++;
+      score += bestTokenScore;
+    }
+    if (entry.frontmatter.name.toLowerCase().includes(queryLower)) {
+      score += 2;
+    }
+    if (entry.frontmatter.description.toLowerCase().includes(queryLower)) {
+      score += 1;
+    }
+    score = score / Math.max(matchedTokens, 1);
+    if (score >= 0.5) {
+      results.push({
+        name: entry.frontmatter.name,
+        dirName: entry.dirName,
+        description: entry.frontmatter.description,
+        score: Math.round(score * 100) / 100,
+        hasResources: entry.hasResources
+      });
+    }
+  }
+  results.sort((a, b) => b.score - a.score);
+  return results.slice(0, limit);
+}
+
+// src/loader.ts
+import { readFile as readFile2, readdir as readdir2 } from "fs/promises";
+import { join as join2, resolve } from "path";
+async function loadSkill(entry, skillsDir2, includeResources = false) {
+  const skillDir = join2(skillsDir2, entry.dirName);
+  const skillPath = join2(skillDir, "SKILL.md");
+  const absoluteSkillDir = resolve(skillDir);
+  let content = `> **Skill directory**: ${absoluteSkillDir}
+> Resolve relative paths (scripts/, resources/, etc.) against this directory.
+
+`;
+  content += await readFile2(skillPath, "utf-8");
+  if (includeResources && entry.hasResources) {
+    const resourceDir = join2(skillsDir2, entry.dirName, "resources");
+    try {
+      const files = await readdir2(resourceDir);
+      const mdFiles = files.filter((f) => f.endsWith(".md")).sort();
+      for (const file of mdFiles) {
+        const resourceContent = await readFile2(join2(resourceDir, file), "utf-8");
+        content += `
+
+---
+
+# Resource: ${file}
+
+${resourceContent}`;
+      }
+    } catch {
+    }
+  }
+  return content;
+}
+
+// src/server.ts
+function createServer(index, skillsDir2) {
+  const server = new McpServer({
+    name: "skill-library",
+    version: "1.0.0"
+  });
+  const lookupMap = /* @__PURE__ */ new Map();
+  for (const entry of index.entries) {
+    lookupMap.set(entry.dirName.toLowerCase(), entry);
+    lookupMap.set(entry.frontmatter.name.toLowerCase(), entry);
+  }
+  server.tool(
+    "search_skill",
+    "Search for skills by keyword. Returns ranked list of matching skill names and descriptions.",
+    { query: z.string().describe("Keywords to search for (e.g. 'debugging', 'react patterns', 'terraform')") },
+    async ({ query }) => {
+      const results = searchSkills(index, query);
+      if (results.length === 0) {
+        return {
+          content: [{ type: "text", text: `No skills found matching "${query}".` }]
+        };
+      }
+      const lines = results.map(
+        (r) => `- **${r.name}** (${r.dirName})${r.hasResources ? " [+resources]" : ""} \u2014 ${r.description}`
+      );
+      return {
+        content: [{
+          type: "text",
+          text: `Found ${results.length} skills matching "${query}":
+
+${lines.join("\n")}`
+        }]
+      };
+    }
+  );
+  server.tool(
+    "load_skill",
+    "Load the full content of a skill by name. Returns the complete SKILL.md content and optionally resources.",
+    {
+      name: z.string().describe("Skill name or directory name (e.g. 'brainstorming', 'ai-engineer')"),
+      include_resources: z.boolean().default(false).describe("Whether to include resource files")
+    },
+    async ({ name, include_resources }) => {
+      const entry = lookupMap.get(name.toLowerCase());
+      if (!entry) {
+        const results = searchSkills(index, name, 5);
+        if (results.length > 0) {
+          const suggestions = results.map((r) => r.name).join(", ");
+          return {
+            content: [{
+              type: "text",
+              text: `Skill "${name}" not found. Did you mean: ${suggestions}?`
+            }]
+          };
+        }
+        return {
+          content: [{ type: "text", text: `Skill "${name}" not found.` }]
+        };
+      }
+      const content = await loadSkill(entry, skillsDir2, include_resources);
+      return {
+        content: [{ type: "text", text: content }]
+      };
+    }
+  );
+  return server;
+}
+
+// src/index.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+var skillsDir = join3(__dirname, "..", "skills");
+async function main() {
+  const index = await buildIndex(skillsDir);
+  console.error(`[skill-library] Indexed ${index.entries.length} skills from ${skillsDir}`);
+  const server = createServer(index, skillsDir);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[skill-library] MCP server running on stdio");
+}
+main().catch((err) => {
+  console.error("[skill-library] Fatal error:", err);
+  process.exit(1);
+});

package/docs/architecture.md

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

@@ -0,0 +1,83 @@
+# 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.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "skill-library-mcp",
+  "version": "1.0.0",
+  "description": "MCP server providing on-demand skill loading for AI coding assistants",
+  "type": "module",
+  "bin": {
+    "skill-library-mcp": "dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "yaml": "^2.4.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "dedup": "tsx src/dedup.ts skills/"
+  }
+}

package/release-please-config.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "changelog-sections": [
+        { "type": "feat", "section": "Features" },
+        { "type": "fix", "section": "Bug Fixes" },
+        { "type": "perf", "section": "Performance" },
+        { "type": "docs", "section": "Documentation", "hidden": true },
+        { "type": "chore", "section": "Miscellaneous", "hidden": true },
+        { "type": "test", "section": "Tests", "hidden": true },
+        { "type": "ci", "section": "CI", "hidden": true }
+      ]
+    }
+  }
+}

package/scripts/import-skills.ts

@@ -0,0 +1,103 @@
+import { readdir, access, cp } from "node:fs/promises";
+import { join, basename } from "node:path";
+import { findDuplicates } from "../src/dedup.js";
+
+async function hasSkillMd(dir: string): Promise<boolean> {
+  try {
+    await access(join(dir, "SKILL.md"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function getExistingSkillDirs(skillsDir: string): Promise<Set<string>> {
+  const dirs = await readdir(skillsDir);
+  return new Set(dirs);
+}
+
+async function importSkills(
+  sourceDir: string,
+  targetDir: string,
+  sourceName: string,
+  dryRun: boolean,
+): Promise<void> {
+  console.log(`\nImporting skills from: ${sourceDir}`);
+  console.log(`Target: ${targetDir}`);
+  console.log(`Source: ${sourceName}`);
+  console.log(`Mode: ${dryRun ? "DRY RUN" : "LIVE"}\n`);
+
+  const existing = await getExistingSkillDirs(targetDir);
+  let sourceDirs: string[];
+
+  try {
+    sourceDirs = await readdir(sourceDir);
+  } catch (err) {
+    console.error(`Failed to read source directory: ${err}`);
+    process.exit(1);
+  }
+
+  let added = 0;
+  let skipped = 0;
+  const conflicts: string[] = [];
+
+  for (const dirName of sourceDirs) {
+    const srcPath = join(sourceDir, dirName);
+    if (!(await hasSkillMd(srcPath))) continue;
+
+    if (existing.has(dirName)) {
+      conflicts.push(dirName);
+      skipped++;
+      continue;
+    }
+
+    if (!dryRun) {
+      await cp(srcPath, join(targetDir, dirName), { recursive: true });
+    }
+    console.log(`  + ${dirName}`);
+    added++;
+  }
+
+  console.log(`\nResults:`);
+  console.log(`  Added: ${added}`);
+  console.log(`  Skipped (already exists): ${skipped}`);
+
+  if (conflicts.length > 0) {
+    console.log(`\nConflicts (skipped):`);
+    for (const c of conflicts) {
+      console.log(`  - ${c}`);
+    }
+  }
+
+  // Run dedup check
+  if (!dryRun && added > 0) {
+    console.log(`\nRunning dedup check...`);
+    const report = await findDuplicates(targetDir);
+    if (report.exactDuplicates.length > 0) {
+      console.log(`\n❌ ${report.exactDuplicates.length} exact duplicate group(s) created:`);
+      for (const group of report.exactDuplicates) {
+        console.log(`  "${group[0].name}": ${group.map((s) => s.dirName).join(", ")}`);
+      }
+    } else {
+      console.log(`✅ No new exact duplicates.`);
+    }
+  }
+}
+
+// CLI
+const args = process.argv.slice(2);
+const sourceDir = args.find((a) => !a.startsWith("--"));
+const sourceName = args.find((a) => a.startsWith("--source="))?.split("=")[1] ?? basename(sourceDir ?? "");
+const dryRun = !args.includes("--no-dry-run");
+const targetDir = args.find((a) => a.startsWith("--target="))?.split("=")[1] ?? join(process.cwd(), "skills");
+
+if (!sourceDir) {
+  console.error("Usage: tsx scripts/import-skills.ts <source-dir> [--source=name] [--target=dir] [--no-dry-run]");
+  console.error("\nOptions:");
+  console.error("  --source=name     Name of the source (for logging)");
+  console.error("  --target=dir      Target skills directory (default: ./skills)");
+  console.error("  --no-dry-run      Actually copy files (default is dry-run)");
+  process.exit(1);
+}
+
+importSkills(sourceDir, targetDir, sourceName, dryRun);