@modootoday/pmcp 0.1.4 → 0.2.0

package/dist/chunk-3NNRQ5A4.js

@@ -0,0 +1,698 @@
+// src/intent.ts
+function normaliseIntent(intent) {
+  return intent.toLowerCase().replaceAll(/[^\p{L}\p{N}\s]/gu, " ").split(/\s+/u).filter(Boolean).join(" ");
+}
+
+// src/marketplace.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync as readdirSync2 } from "fs";
+import { join as join2, resolve } from "path";
+
+// src/catalog.ts
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { basename, dirname, join, relative } from "path";
+var SKIPPED_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  ".cache",
+  ".turbo",
+  "coverage",
+  "__tests__",
+  "__fixtures__"
+]);
+var MAX_SKILL_DEPTH = 3;
+function readFrontmatter(source) {
+  if (!source.startsWith("---")) return {};
+  const end = source.indexOf("\n---", 3);
+  if (end === -1) return {};
+  const fields = {};
+  for (const line of source.slice(3, end).split("\n")) {
+    const match = /^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/u.exec(line);
+    if (!match) continue;
+    const value = (match[2] ?? "").trim();
+    if (value === "" || value.startsWith("#")) continue;
+    fields[match[1]] = value.replace(/^["'](.*)["']$/u, "$1");
+  }
+  return fields;
+}
+function readBody(source) {
+  if (!source.startsWith("---")) return source;
+  const end = source.indexOf("\n---", 3);
+  if (end === -1) return source;
+  return source.slice(end + 4).replace(/^(?:\r?\n)+/u, "");
+}
+function skillFiles(packageDir) {
+  const found = [];
+  const stack = [[packageDir, 0]];
+  while (stack.length > 0) {
+    const next = stack.pop();
+    if (next === void 0) break;
+    const [dir, depth] = next;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isFile()) {
+        if (entry.name === "SKILL.md") found.push(join(dir, entry.name));
+        continue;
+      }
+      if (!entry.isDirectory()) continue;
+      if (SKIPPED_DIRS.has(entry.name)) continue;
+      if (depth + 1 <= MAX_SKILL_DEPTH)
+        stack.push([join(dir, entry.name), depth + 1]);
+    }
+  }
+  return found.sort();
+}
+function packageDirs(root) {
+  if (!existsSync(root)) return [];
+  const found = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (entry.name === ".bin" || entry.name === ".cache") continue;
+    const path = join(root, entry.name);
+    if (entry.name.startsWith("@")) {
+      if (!existsSync(path)) continue;
+      for (const scoped of readdirSync(path, { withFileTypes: true })) {
+        if (scoped.isDirectory() || scoped.isSymbolicLink()) {
+          found.push(join(path, scoped.name));
+        }
+      }
+      continue;
+    }
+    found.push(path);
+  }
+  return found;
+}
+function readCatalog(options) {
+  const scopes = options.scopes ?? [];
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const root of options.roots) {
+    for (const packageDir of packageDirs(root)) {
+      const manifestPath = join(packageDir, "package.json");
+      if (!existsSync(manifestPath)) continue;
+      let packageName;
+      try {
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+        if (!manifest.name) continue;
+        packageName = manifest.name;
+      } catch {
+        continue;
+      }
+      if (scopes.length > 0 && !scopes.some((s) => packageName.startsWith(s))) {
+        continue;
+      }
+      for (const path of skillFiles(packageDir)) {
+        let source;
+        try {
+          source = readFileSync(path, "utf8");
+        } catch {
+          continue;
+        }
+        const front = readFrontmatter(source);
+        const description = front["description"] ?? "";
+        if (description === "") continue;
+        const dirName = basename(dirname(path));
+        const slug = front["name"] ?? (dirName === basename(packageDir) ? packageName : dirName);
+        const name = `${packageName}/${slug}`;
+        if (seen.has(name)) continue;
+        seen.add(name);
+        found.push({
+          name,
+          package: packageName,
+          slug,
+          description,
+          path
+        });
+      }
+    }
+  }
+  for (const dir of options.marketplaces ?? []) {
+    for (const entry of readMarketplace(dir, options.onReject)) {
+      if (seen.has(entry.name)) {
+        options.onReject?.({
+          path: entry.path,
+          reason: `duplicate name ${entry.name}`
+        });
+        continue;
+      }
+      seen.add(entry.name);
+      found.push(entry);
+    }
+  }
+  return found.sort((a, b) => a.name.localeCompare(b.name));
+}
+function withoutBody({
+  path,
+  ...rest
+}) {
+  void path;
+  return rest;
+}
+function displayPath(root, entry) {
+  return relative(root, entry.path).replaceAll("\\", "/");
+}
+
+// src/marketplace.ts
+function parseScalar(raw) {
+  const value = raw.trim();
+  if (value.startsWith("[") && value.endsWith("]")) {
+    return value.slice(1, -1).split(",").map((item) => item.trim().replace(/^["'](.*)["']$/u, "$1")).filter(Boolean);
+  }
+  return value.replace(/^["'](.*)["']$/u, "$1");
+}
+function readMetadata(source) {
+  if (!source.startsWith("---")) return {};
+  const end = source.indexOf("\n---", 3);
+  if (end === -1) return {};
+  const out = {};
+  let inside = false;
+  for (const line of source.slice(3, end).split("\n")) {
+    if (/^metadata:\s*$/u.test(line)) {
+      inside = true;
+      continue;
+    }
+    if (!inside) continue;
+    if (!/^\s/u.test(line)) break;
+    const match = /^ {2}([A-Za-z][A-Za-z0-9_.-]*):\s*(.*)$/u.exec(line);
+    if (!match) continue;
+    const raw = match[2] ?? "";
+    if (raw.trim() === "" || raw.trim().startsWith("#")) continue;
+    out[match[1]] = parseScalar(raw);
+  }
+  return out;
+}
+function readFrontmatterText(source) {
+  if (!source.startsWith("---")) return "";
+  const end = source.indexOf("\n---", 3);
+  return end === -1 ? "" : source.slice(3, end).replace(/^\r?\n/u, "");
+}
+var asString = (value) => typeof value === "string" ? value : void 0;
+var asList = (value) => {
+  if (value === void 0) return [];
+  return typeof value === "string" ? [value] : value;
+};
+function readMarketplace(dir, onReject) {
+  const manifestPath = join2(dir, ".claude-plugin", "marketplace.json");
+  if (!existsSync2(manifestPath)) {
+    onReject?.({
+      path: dir,
+      reason: "no .claude-plugin/marketplace.json here"
+    });
+    return [];
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(
+      readFileSync2(manifestPath, "utf8")
+    );
+  } catch {
+    onReject?.({
+      path: manifestPath,
+      reason: "marketplace.json is not valid JSON"
+    });
+    return [];
+  }
+  const marketplace = manifest.name ?? "marketplace";
+  const tier = manifest.metadata?.tier;
+  const found = [];
+  for (const plugin of manifest.plugins ?? []) {
+    if (!plugin.name || !plugin.source) continue;
+    const skillsDir = join2(resolve(dir, plugin.source), "skills");
+    if (!existsSync2(skillsDir)) continue;
+    for (const child of readdirSync2(skillsDir, { withFileTypes: true })) {
+      if (!child.isDirectory()) continue;
+      const path = join2(skillsDir, child.name, "SKILL.md");
+      if (!existsSync2(path)) continue;
+      const source = readFileSync2(path, "utf8");
+      const front = readFrontmatter(source);
+      const description = front["description"] ?? "";
+      if (description === "") {
+        onReject?.({ path, reason: "no description" });
+        continue;
+      }
+      const metadata = readMetadata(source);
+      const ownTier = asString(metadata["tier"]);
+      if (tier !== void 0 && ownTier !== void 0 && ownTier !== tier) {
+        onReject?.({
+          path,
+          reason: `metadata.tier ${ownTier} in a ${tier} marketplace`
+        });
+        continue;
+      }
+      const slug = front["name"] ?? child.name;
+      found.push({
+        name: `${marketplace}/${plugin.name}/${slug}`,
+        package: `${marketplace}/${plugin.name}`,
+        slug,
+        description,
+        path,
+        tier: ownTier ?? tier,
+        metadata,
+        keywords: asList(metadata["keywords"])
+      });
+    }
+  }
+  return found;
+}
+
+// src/find.ts
+var DEFAULT_FIND_LIMIT = 5;
+function tokens(text) {
+  return normaliseIntent(text).split(" ").filter(Boolean);
+}
+function bigrams(text) {
+  const flat = normaliseIntent(text).replaceAll(" ", "");
+  const out = /* @__PURE__ */ new Set();
+  for (let i = 0; i + 1 < flat.length; i += 1) out.add(flat.slice(i, i + 2));
+  return out;
+}
+function lexicalScore(intent, description) {
+  const wanted = tokens(intent);
+  if (wanted.length === 0) return 0;
+  const have = new Set(tokens(description));
+  const overlap = wanted.filter((token) => have.has(token)).length / wanted.length;
+  const a = bigrams(intent);
+  const b = bigrams(description);
+  if (a.size === 0 || b.size === 0) return overlap / 2;
+  let shared = 0;
+  for (const gram of a) if (b.has(gram)) shared += 1;
+  const dice = 2 * shared / (a.size + b.size);
+  return (overlap + dice) / 2;
+}
+function cosine(a, b) {
+  if (a.length !== b.length) return 0;
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+async function find(options) {
+  const limit = options.limit ?? DEFAULT_FIND_LIMIT;
+  const semantic = options.embedder !== void 0 && options.vectors !== void 0 && options.vectors.size > 0;
+  if (semantic) {
+    const embedder = options.embedder;
+    const vectors = options.vectors;
+    let query = options.cache?.get(options.intent) ?? null;
+    if (!query) {
+      query = await embedder.embed(options.intent);
+      options.cache?.put(options.intent, query);
+    }
+    const scored = [];
+    for (const entry of options.entries) {
+      const vector = vectors.get(entry.name);
+      if (!vector) continue;
+      scored.push({
+        name: entry.name,
+        package: entry.package,
+        description: entry.description,
+        score: cosine(query, vector)
+      });
+    }
+    if (scored.length === options.entries.length) {
+      return {
+        ranking: "semantic",
+        matches: rank(scored, limit)
+      };
+    }
+  }
+  return {
+    ranking: "lexical",
+    matches: rank(
+      options.entries.map((entry) => ({
+        name: entry.name,
+        package: entry.package,
+        description: entry.description,
+        score: lexicalScore(options.intent, entry.description)
+      })),
+      limit
+    )
+  };
+}
+function rank(matches2, limit) {
+  return matches2.filter((match) => match.score > 0).sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, limit);
+}
+
+// src/server.ts
+import { createHash } from "crypto";
+import { readFileSync as readFileSync3, readdirSync as readdirSync3, realpathSync, statSync } from "fs";
+import { dirname as dirname2, isAbsolute, join as join3, relative as relative2, resolve as resolve2, sep } from "path";
+var READ_BUDGET_BYTES = 256 * 1024;
+var DESCRIBE_FILE_LIMIT = 200;
+var CATALOG_PAGE_SIZE = 8;
+var CATALOG_PAGE_MAX = 20;
+function matches(entry, filters) {
+  if (!filters) return true;
+  const meta = entry.metadata ?? {};
+  const field = (key) => {
+    const value = meta[key];
+    return typeof value === "string" ? value : void 0;
+  };
+  if (filters.tier !== void 0 && entry.tier !== filters.tier) return false;
+  if (filters.package !== void 0 && entry.package !== filters.package)
+    return false;
+  if (filters.level !== void 0 && field("level") !== filters.level)
+    return false;
+  if (filters.domain !== void 0 && field("domain") !== filters.domain)
+    return false;
+  if (filters.medium !== void 0 && field("medium") !== filters.medium)
+    return false;
+  return true;
+}
+var sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function listFiles(root) {
+  const files = [];
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    for (const entry of readdirSync3(dir, { withFileTypes: true })) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      const full = join3(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (files.length >= DESCRIBE_FILE_LIMIT)
+        return { files, truncated: true };
+      const bytes = readFileSync3(full);
+      files.push({
+        path: relative2(root, full).split(sep).join("/"),
+        bytes: bytes.length,
+        sha256: sha256(bytes)
+      });
+    }
+  }
+  files.sort((a, b) => a.path.localeCompare(b.path));
+  return { files, truncated: false };
+}
+function createSkillTools(options) {
+  const load = options.loadCatalog ?? readCatalog;
+  let entries = null;
+  const catalog = () => {
+    entries ??= load({
+      roots: options.roots,
+      scopes: options.scopes,
+      marketplaces: options.marketplaces,
+      onReject: options.onReject
+    });
+    return entries;
+  };
+  return {
+    /**
+     * Grouped, and without bodies. The cheap overview and the search's miss
+     * path. Paged by package so a large catalog never arrives in one answer.
+     */
+    catalog(request = {}) {
+      const byPackage = /* @__PURE__ */ new Map();
+      let count = 0;
+      for (const entry of catalog()) {
+        if (!matches(entry, { tier: request.tier })) continue;
+        count += 1;
+        const list = byPackage.get(entry.package) ?? [];
+        list.push(
+          entry.tier === void 0 ? { name: entry.name, description: entry.description } : {
+            name: entry.name,
+            description: entry.description,
+            tier: entry.tier
+          }
+        );
+        byPackage.set(entry.package, list);
+      }
+      const groups = [...byPackage.entries()].sort(
+        ([a], [b]) => a.localeCompare(b)
+      );
+      const size = Math.min(
+        Math.max(request.pageSize ?? CATALOG_PAGE_SIZE, 1),
+        CATALOG_PAGE_MAX
+      );
+      const totalPages = Math.max(1, Math.ceil(groups.length / size));
+      const page = Math.min(Math.max(request.page ?? 1, 1), totalPages);
+      return {
+        count,
+        page,
+        totalPages,
+        hasNext: page < totalPages,
+        packages: groups.slice((page - 1) * size, page * size).map(([pkg, skills]) => ({ package: pkg, skills }))
+      };
+    },
+    /** Ranked names. Returns; never loads a body. */
+    find(intent, limit, filters) {
+      const scoped = catalog().filter((entry) => matches(entry, filters)).map(
+        (entry) => entry.keywords && entry.keywords.length > 0 ? {
+          ...entry,
+          description: `${entry.description} ${entry.keywords.join(" ")}`
+        } : entry
+      );
+      return find({
+        entries: scoped,
+        intent,
+        limit,
+        embedder: options.embedder,
+        cache: options.cache,
+        vectors: options.vectors
+      }).then((result) => ({
+        ...result,
+        matches: result.matches.map((match) => ({
+          ...match,
+          description: catalog().find((entry) => entry.name === match.name)?.description ?? match.description
+        }))
+      }));
+    },
+    /** Every property of one skill and the files it carries, without bodies. */
+    describe(name) {
+      const entry = catalog().find((candidate) => candidate.name === name);
+      if (!entry) return null;
+      const source = readFileSync3(entry.path, "utf8");
+      const listing = listFiles(dirname2(entry.path));
+      return {
+        name: entry.name,
+        package: entry.package,
+        description: entry.description,
+        tier: entry.tier,
+        metadata: entry.metadata ?? {},
+        frontmatter: readFrontmatterText(source),
+        files: listing.files,
+        filesTruncated: listing.truncated
+      };
+    },
+    /**
+     * One file inside a skill's directory. Paths that leave the directory,
+     * directly or through a link, are refused; nothing is ever executed.
+     */
+    read(name, path = "SKILL.md") {
+      const entry = catalog().find((candidate) => candidate.name === name);
+      if (!entry) return { ok: false, error: "unknown_skill", detail: name };
+      if (isAbsolute(path) || path.split(/[\\/]/u).includes("..")) {
+        return { ok: false, error: "path_outside_skill", detail: path };
+      }
+      const root = realpathSync(dirname2(entry.path));
+      let target;
+      try {
+        target = realpathSync(resolve2(root, path));
+      } catch {
+        return { ok: false, error: "no_such_file", detail: path };
+      }
+      if (target !== root && !target.startsWith(root + sep)) {
+        return { ok: false, error: "path_outside_skill", detail: path };
+      }
+      const size = statSync(target).size;
+      if (size > READ_BUDGET_BYTES) {
+        return {
+          ok: false,
+          error: "over_budget",
+          detail: `${size} bytes > ${READ_BUDGET_BYTES}`
+        };
+      }
+      const bytes = readFileSync3(target);
+      return {
+        ok: true,
+        name: entry.name,
+        path: relative2(root, target).split(sep).join("/"),
+        bytes: bytes.length,
+        sha256: sha256(bytes),
+        text: bytes.toString("utf8")
+      };
+    },
+    /** One body, at the moment it is needed. */
+    call(name) {
+      const entry = catalog().find((candidate) => candidate.name === name);
+      if (!entry) return null;
+      return {
+        name: entry.name,
+        body: readBody(readFileSync3(entry.path, "utf8"))
+      };
+    },
+    /** Drops the memoised catalog, so the next call re-reads the tree. */
+    refresh() {
+      entries = null;
+    },
+    entries: () => catalog().map(withoutBody)
+  };
+}
+
+// src/mcp.ts
+import { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+var SERVER_NAME = "pmcp";
+var readOnly = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var asText = (value) => ({
+  content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
+});
+function registerSkillTools(server, tools) {
+  server.registerTool(
+    "skill_catalog",
+    {
+      title: "List installed skills without their bodies",
+      description: "Every skill the installed packages and marketplaces ship, grouped by package or plugin, with names, one-line descriptions and tier, and no bodies. Paged by group. Use it to see what exists, or when skill_find returns nothing.",
+      inputSchema: z.object({
+        page: z.number().int().min(1).optional(),
+        pageSize: z.number().int().min(1).max(20).optional(),
+        tier: z.enum(["open", "free", "paid"]).optional()
+      }),
+      annotations: readOnly
+    },
+    async (request) => asText(tools.catalog(request))
+  );
+  server.registerTool(
+    "skill_find",
+    {
+      title: "Find skills by describing the problem",
+      description: "Ranked skill names for an intent. Describe the problem in a full sentence in English rather than a keyword: a single word matches far worse, and the ranking is over descriptions. Returns names only -- read one with skill_call.",
+      inputSchema: z.object({
+        intent: z.string().min(1).max(256).describe("What you are trying to do, as an English sentence."),
+        limit: z.number().int().min(1).max(25).optional(),
+        filters: z.object({
+          tier: z.enum(["open", "free", "paid"]).optional(),
+          package: z.string().optional(),
+          level: z.string().optional(),
+          domain: z.string().optional(),
+          medium: z.string().optional()
+        }).optional().describe("Exact-match filters over the catalog before ranking.")
+      }),
+      annotations: readOnly
+    },
+    async ({ intent, limit, filters }) => asText(await tools.find(intent, limit, filters))
+  );
+  server.registerTool(
+    "skill_describe",
+    {
+      title: "Check one skill's properties before loading it",
+      description: "Frontmatter, metadata (tier, level, requirements, licence, approval), and the files the skill carries with sizes and sha256, without any body. Use it to decide between candidates before skill_call.",
+      inputSchema: z.object({
+        name: z.string().min(1).describe("The skill name skill_find or skill_catalog returned.")
+      }),
+      annotations: readOnly
+    },
+    async ({ name }) => {
+      const described = tools.describe(name);
+      if (!described) {
+        return {
+          ...asText({
+            error: "unknown_skill",
+            name,
+            hint: "Call skill_catalog for the names that exist."
+          }),
+          isError: true
+        };
+      }
+      return asText(described);
+    }
+  );
+  server.registerTool(
+    "skill_read",
+    {
+      title: "Read one file a skill carries",
+      description: "A reference or script file inside one skill's directory, as text, with its sha256. Read only when the skill body points at the file. Scripts are returned, never run. Files over 256 KiB and paths outside the skill are refused.",
+      inputSchema: z.object({
+        name: z.string().min(1),
+        path: z.string().min(1).optional().describe(
+          "Path relative to the skill directory, as skill_describe lists it. Defaults to SKILL.md."
+        )
+      }),
+      annotations: readOnly
+    },
+    async ({ name, path }) => {
+      const result = tools.read(name, path);
+      if (!result.ok) return { ...asText(result), isError: true };
+      const { text, ...header } = result;
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(header) },
+          { type: "text", text }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "skill_call",
+    {
+      title: "Read one skill",
+      description: "The body of a single skill, by the name skill_find or skill_catalog returned. This is the only call that costs a document.",
+      inputSchema: z.object({
+        name: z.string().min(1).describe("The skill name, as <package>/<slug>.")
+      }),
+      annotations: readOnly
+    },
+    async ({ name }) => {
+      const found = tools.call(name);
+      if (!found) {
+        return {
+          ...asText({
+            error: "unknown_skill",
+            name,
+            hint: "Call skill_catalog for the names that exist."
+          }),
+          isError: true
+        };
+      }
+      return { content: [{ type: "text", text: found.body }] };
+    }
+  );
+  return server;
+}
+function createSkillServer(options) {
+  const server = new McpServer({ name: SERVER_NAME, version: "0.2.0" });
+  return registerSkillTools(server, createSkillTools(options));
+}
+
+export {
+  normaliseIntent,
+  readMetadata,
+  readFrontmatterText,
+  readMarketplace,
+  SKIPPED_DIRS,
+  MAX_SKILL_DEPTH,
+  readFrontmatter,
+  readBody,
+  readCatalog,
+  withoutBody,
+  displayPath,
+  DEFAULT_FIND_LIMIT,
+  lexicalScore,
+  cosine,
+  find,
+  READ_BUDGET_BYTES,
+  DESCRIBE_FILE_LIMIT,
+  CATALOG_PAGE_SIZE,
+  CATALOG_PAGE_MAX,
+  createSkillTools,
+  SERVER_NAME,
+  registerSkillTools,
+  createSkillServer
+};
+//# sourceMappingURL=chunk-3NNRQ5A4.js.map