skill-library-mcp 1.0.0

package/test/search.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildIndex } from "../src/skill-index.js";
+import { searchSkills } from "../src/search.js";
+import type { SearchIndex } from "../src/types.js";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const fixturesDir = join(__dirname, "fixtures");
+
+let index: SearchIndex;
+
+beforeAll(async () => {
+  index = await buildIndex(fixturesDir);
+});
+
+describe("searchSkills", () => {
+  it("exact token match scores highest", () => {
+    const results = searchSkills(index, "basic-skill");
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].dirName).toBe("basic-skill");
+    if (results.length > 1) {
+      expect(results[0].score).toBeGreaterThanOrEqual(results[1].score);
+    }
+  });
+
+  it("partial/substring matches still return the right skill first", () => {
+    const results = searchSkills(index, "basic");
+    expect(results.length).toBeGreaterThan(0);
+    // "basic" should still find basic-skill as the top result
+    expect(results[0].dirName).toBe("basic-skill");
+  });
+
+  it("name bonus applied for substring match in name", () => {
+    const results = searchSkills(index, "basic-skill");
+    expect(results[0].dirName).toBe("basic-skill");
+    // Score includes IDF weight + name bonus (2.0), should be well above threshold
+    expect(results[0].score).toBeGreaterThan(2);
+  });
+
+  it("results sorted by score descending", () => {
+    const results = searchSkills(index, "skill");
+    for (let i = 1; i < results.length; i++) {
+      expect(results[i - 1].score).toBeGreaterThanOrEqual(results[i].score);
+    }
+  });
+
+  it("limit parameter works", () => {
+    const results = searchSkills(index, "skill", 1);
+    expect(results.length).toBeLessThanOrEqual(1);
+  });
+
+  it("empty query returns empty", () => {
+    const results = searchSkills(index, "");
+    expect(results).toEqual([]);
+  });
+
+  it("no matches returns empty", () => {
+    const results = searchSkills(index, "zzzznonexistent");
+    expect(results).toEqual([]);
+  });
+
+  it("description substring bonus is applied", () => {
+    // "unit testing" appears in basic-skill description
+    const results = searchSkills(index, "unit testing");
+    const basic = results.find((r) => r.dirName === "basic-skill");
+    expect(basic).toBeDefined();
+    // IDF-weighted token matches + description bonus, normalized by 2 tokens
+    expect(basic!.score).toBeGreaterThan(1);
+  });
+
+  it("multi-token query with unmatched tokens does not dilute score", () => {
+    const singleToken = searchSkills(index, "basic-skill");
+    const multiToken = searchSkills(index, "basic-skill nonexistenttoken");
+    const singleBasic = singleToken.find((r) => r.dirName === "basic-skill");
+    const multiBasic = multiToken.find((r) => r.dirName === "basic-skill");
+    // Unmatched tokens should not dilute score — only name bonus difference
+    expect(singleBasic).toBeDefined();
+    expect(multiBasic).toBeDefined();
+    // Single gets name bonus (full query matches name), multi doesn't
+    expect(singleBasic!.score).toBeGreaterThanOrEqual(multiBasic!.score);
+  });
+
+  it("hasResources flag propagated to search results", () => {
+    const results = searchSkills(index, "skill");
+    const withRes = results.find((r) => r.dirName === "skill-with-resources");
+    const basic = results.find((r) => r.dirName === "basic-skill");
+    expect(withRes?.hasResources).toBe(true);
+    expect(basic?.hasResources).toBe(false);
+  });
+
+  it("scores are rounded to two decimal places", () => {
+    const results = searchSkills(index, "skill");
+    for (const r of results) {
+      const rounded = Math.round(r.score * 100) / 100;
+      expect(r.score).toBe(rounded);
+    }
+  });
+
+  it("stop-words are filtered from query", () => {
+    // "create a basic" → "create" and "a" are stop-words, "basic" remains
+    const results = searchSkills(index, "create a basic");
+    expect(results.length).toBeGreaterThan(0);
+    // Should match on "basic" token, same as searching "basic" directly
+    const basicResults = searchSkills(index, "basic");
+    expect(results.map((r) => r.dirName)).toEqual(basicResults.map((r) => r.dirName));
+  });
+
+  it("natural language stop-words are filtered (help, need, how, etc.)", () => {
+    // "help me with basic" → "help", "me", "with" are stop-words, "basic" remains
+    const results = searchSkills(index, "help me with basic");
+    expect(results.length).toBeGreaterThan(0);
+    const basicResults = searchSkills(index, "basic");
+    expect(results.map((r) => r.dirName)).toEqual(basicResults.map((r) => r.dirName));
+  });
+
+  it("query tokens are deduplicated", () => {
+    const single = searchSkills(index, "testing");
+    const double = searchSkills(index, "testing testing");
+    // Deduplication means "testing testing" should produce same result set
+    expect(single.map((r) => r.dirName)).toEqual(double.map((r) => r.dirName));
+  });
+
+  it("2-char tokens can match via substring", () => {
+    // 2-char tokens should match via substring (minimum is now 2)
+    // "zx" has no match in fixtures, so still empty
+    const results = searchSkills(index, "zx");
+    expect(results).toEqual([]);
+  });
+
+  it("single-char tokens are too short for substring matching", () => {
+    const results = searchSkills(index, "z");
+    expect(results).toEqual([]);
+  });
+});

package/test/server.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { buildIndex } from "../src/skill-index.js";
+import { createServer } from "../src/server.js";
+import type { SearchIndex } from "../src/types.js";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const fixturesDir = join(__dirname, "fixtures");
+
+let client: Client;
+
+beforeAll(async () => {
+  const index = await buildIndex(fixturesDir);
+  const server = createServer(index, fixturesDir);
+
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await server.connect(serverTransport);
+
+  client = new Client({ name: "test-client", version: "1.0.0" });
+  await client.connect(clientTransport);
+});
+
+async function callTool(name: string, args: Record<string, unknown>): Promise<string> {
+  const result = await client.callTool({ name, arguments: args });
+  const content = result.content as Array<{ type: string; text: string }>;
+  return content[0].text;
+}
+
+describe("search_skill tool", () => {
+  it("returns matching skills for valid query", async () => {
+    const text = await callTool("search_skill", { query: "basic" });
+    expect(text).toContain("basic-skill");
+    expect(text).toContain("Found");
+  });
+
+  it("returns 'no skills found' for unmatched query", async () => {
+    const text = await callTool("search_skill", { query: "zzzznonexistent" });
+    expect(text).toContain("No skills found");
+  });
+
+  it("includes [+resources] marker for skills with resources", async () => {
+    const text = await callTool("search_skill", { query: "skill" });
+    expect(text).toContain("[+resources]");
+  });
+
+  it("formats results as markdown list", async () => {
+    const text = await callTool("search_skill", { query: "skill" });
+    expect(text).toMatch(/^Found \d+ skills/);
+    expect(text).toContain("- **");
+    expect(text).toContain("** (");
+  });
+});
+
+describe("load_skill tool", () => {
+  it("loads skill by exact dirName", async () => {
+    const text = await callTool("load_skill", { name: "basic-skill" });
+    expect(text).toContain("# Basic Skill");
+    expect(text).toContain("basic skill used for testing");
+  });
+
+  it("loads skill case-insensitively", async () => {
+    const text = await callTool("load_skill", { name: "Basic-Skill" });
+    expect(text).toContain("# Basic Skill");
+  });
+
+  it("includes resources when requested", async () => {
+    const text = await callTool("load_skill", {
+      name: "skill-with-resources",
+      include_resources: true,
+    });
+    expect(text).toContain("# Resource: examples.md");
+    expect(text).toContain("# Resource: guide.md");
+  });
+
+  it("returns fuzzy suggestions for unknown skill name", async () => {
+    const text = await callTool("load_skill", { name: "basik-skill" });
+    expect(text).toContain("not found");
+    expect(text).toContain("Did you mean");
+  });
+
+  it("returns plain 'not found' when no fuzzy matches", async () => {
+    const text = await callTool("load_skill", { name: "zzzznonexistent" });
+    expect(text).toBe('Skill "zzzznonexistent" not found.');
+  });
+
+  it("defaults include_resources to false", async () => {
+    const text = await callTool("load_skill", { name: "skill-with-resources" });
+    expect(text).toContain("# Skill With Resources");
+    expect(text).not.toContain("# Resource:");
+  });
+});

package/test/skill-index.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect } from "vitest";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildIndex } from "../src/skill-index.js";
+import type { SearchIndex } from "../src/types.js";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const fixturesDir = join(__dirname, "fixtures");
+
+describe("buildIndex", () => {
+  it("parses valid skills and counts entries correctly", async () => {
+    const index = await buildIndex(fixturesDir);
+    // basic-skill, skill-with-resources, multiline-description,
+    // skill-with-hyphenated-resources, empty-description, allowed-tools
+    expect(index.entries.length).toBe(6);
+  });
+
+  it("extracts frontmatter fields (name, description)", async () => {
+    const index = await buildIndex(fixturesDir);
+    const basic = index.entries.find((e) => e.dirName === "basic-skill");
+    expect(basic).toBeDefined();
+    expect(basic!.frontmatter.name).toBe("basic-skill");
+    expect(basic!.frontmatter.description).toBe(
+      "A basic test skill for unit testing",
+    );
+  });
+
+  it("extracts metadata from frontmatter", async () => {
+    const index = await buildIndex(fixturesDir);
+    const basic = index.entries.find((e) => e.dirName === "basic-skill");
+    expect(basic!.frontmatter.metadata).toEqual({
+      category: "testing",
+      difficulty: "easy",
+    });
+  });
+
+  it("populates searchTokens from name and description", async () => {
+    const index = await buildIndex(fixturesDir);
+    const basic = index.entries.find((e) => e.dirName === "basic-skill");
+    expect(basic!.searchTokens).toBeInstanceOf(Set);
+    expect(basic!.searchTokens.has("basic-skill")).toBe(true);
+    expect(basic!.searchTokens.has("testing")).toBe(true);
+    expect(basic!.searchTokens.has("unit")).toBe(true);
+  });
+
+  it("splits hyphenated tokens into sub-tokens", async () => {
+    const index = await buildIndex(fixturesDir);
+    const basic = index.entries.find((e) => e.dirName === "basic-skill");
+    // "basic-skill" should be preserved AND sub-tokens added
+    expect(basic!.searchTokens.has("basic-skill")).toBe(true);
+    expect(basic!.searchTokens.has("basic")).toBe(true);
+    expect(basic!.searchTokens.has("skill")).toBe(true);
+  });
+
+  it("detects hasResources and resourceFiles", async () => {
+    const index = await buildIndex(fixturesDir);
+    const withResources = index.entries.find(
+      (e) => e.dirName === "skill-with-resources",
+    );
+    expect(withResources!.hasResources).toBe(true);
+    expect(withResources!.resourceFiles).toContain("guide.md");
+    expect(withResources!.resourceFiles).toContain("examples.md");
+
+    const basic = index.entries.find((e) => e.dirName === "basic-skill");
+    expect(basic!.hasResources).toBe(false);
+    expect(basic!.resourceFiles).toEqual([]);
+  });
+
+  it("skips invalid frontmatter", async () => {
+    const index = await buildIndex(fixturesDir);
+    const invalid = index.entries.find((e) => e.dirName === "invalid-frontmatter");
+    expect(invalid).toBeUndefined();
+  });
+
+  it("skips missing frontmatter", async () => {
+    const index = await buildIndex(fixturesDir);
+    const noFm = index.entries.find((e) => e.dirName === "no-frontmatter");
+    expect(noFm).toBeUndefined();
+  });
+
+  it("handles missing directory", async () => {
+    const index = await buildIndex("/nonexistent/path");
+    expect(index.entries).toEqual([]);
+    expect(index.totalDocs).toBe(0);
+  });
+
+  it("parses multiline YAML description", async () => {
+    const index = await buildIndex(fixturesDir);
+    const ml = index.entries.find((e) => e.dirName === "multiline-description");
+    expect(ml).toBeDefined();
+    expect(ml!.frontmatter.description).toContain("multiline description");
+    expect(ml!.frontmatter.description).toContain("YAML folded scalar");
+    // Folded scalar collapses newlines into spaces
+    expect(ml!.frontmatter.description).not.toContain("\n");
+  });
+
+  it("handles missing description field gracefully", async () => {
+    const index = await buildIndex(fixturesDir);
+    const empty = index.entries.find((e) => e.dirName === "empty-description");
+    expect(empty).toBeDefined();
+    expect(empty!.frontmatter.description).toBe("");
+  });
+
+  it("extracts allowedTools array from frontmatter", async () => {
+    const index = await buildIndex(fixturesDir);
+    const at = index.entries.find((e) => e.dirName === "allowed-tools");
+    expect(at).toBeDefined();
+    expect(at!.frontmatter.allowedTools).toEqual(["Bash", "Read"]);
+  });
+
+  it("detects hyphenated resource filenames", async () => {
+    const index = await buildIndex(fixturesDir);
+    const hyph = index.entries.find((e) => e.dirName === "skill-with-hyphenated-resources");
+    expect(hyph).toBeDefined();
+    expect(hyph!.hasResources).toBe(true);
+    expect(hyph!.resourceFiles).toContain("implementation-playbook.md");
+    expect(hyph!.resourceFiles).toContain("quick-start-guide.md");
+  });
+
+  it("tokenize preserves hyphens within tokens", async () => {
+    const index = await buildIndex(fixturesDir);
+    const basic = index.entries.find((e) => e.dirName === "basic-skill");
+    // "basic-skill" should be a single token, not split on hyphen
+    expect(basic!.searchTokens.has("basic-skill")).toBe(true);
+  });
+
+  it("computes IDF scores for all tokens", async () => {
+    const index = await buildIndex(fixturesDir);
+    expect(index.idfScores.size).toBeGreaterThan(0);
+    expect(index.totalDocs).toBe(6);
+    // Rare tokens should have higher IDF than common ones
+    for (const [, idf] of index.idfScores) {
+      expect(idf).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  it("rare tokens have higher IDF than common tokens", async () => {
+    const index = await buildIndex(fixturesDir);
+    // "unit" appears only in basic-skill, "skill" appears in multiple
+    const unitIdf = index.idfScores.get("unit")!;
+    const skillIdf = index.idfScores.get("skill")!;
+    expect(unitIdf).toBeGreaterThan(skillIdf);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"]
+}

package/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm"],
+  target: "node22",
+  outDir: "dist",
+  clean: true,
+  banner: {
+    js: "#!/usr/bin/env node",
+  },
+});

package/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: { include: ['test/**/*.test.ts'] }
+})