@modootoday/pmcp 0.1.4 → 0.3.0

package/README.md

@@ -1,8 +1,11 @@
 # pmcp
 
 Find and use package skills without loading every document into your agent's context.
-`pmcp` reads installed `SKILL.md` files and exposes three MCP tools: `skill_catalog`,
-`skill_find`, and `skill_call`.
+`pmcp` reads `SKILL.md` files from installed packages, from monorepo workspaces
+(`--workspace <dir>`: the root and every member its `workspaces` globs name, nested
+workspace roots included), from single package directories (`--package <dir>`), and
+from plugin marketplaces (`--marketplace <dir>`), and exposes five MCP tools: `skill_catalog`, `skill_find`,
+`skill_describe`, `skill_call`, and `skill_read`.
 
 ## Install
 

package/dist/catalog-BiPLcbLu.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The skills the installed packages brought with them.
+ *
+ * Derived from `node_modules` at read time rather than from a list somebody
+ * maintains: installing a package is how its skill arrives and uninstalling it
+ * is how the skill leaves, so the catalog is always true of the project.
+ */
+interface SkillEntry {
+    /** `<package>/<slug>`. Unique, and stable while the package is installed. */
+    readonly name: string;
+    readonly package: string;
+    readonly slug: string;
+    /** Frontmatter description. The only text `find` ranks against. */
+    readonly description: string;
+    /** Absolute path to the SKILL.md. `call` reads the body from here. */
+    readonly path: string;
+    /** open, free or paid. Set for marketplace skills, absent for packages. */
+    readonly tier?: string;
+    /** The frontmatter `metadata:` block, one level deep. */
+    readonly metadata?: Readonly<Record<string, string | readonly string[]>>;
+    /** Extra search terms. Ranked with the description, never used as triggers. */
+    readonly keywords?: readonly string[];
+}
+interface CatalogOptions {
+    /** Directories to walk. Each is a `node_modules` root, not a package root. */
+    readonly roots: readonly string[];
+    /** Package name prefixes to consider. Empty means every package. */
+    readonly scopes?: readonly string[];
+    /** Marketplace directories, each holding .claude-plugin/marketplace.json. */
+    readonly marketplaces?: readonly string[];
+    /** Package directories read directly, for a package no node_modules links. */
+    readonly packages?: readonly string[];
+    /** Workspace roots: the root and every member its workspaces globs name. */
+    readonly workspaces?: readonly string[];
+    /** Told about every marketplace skill left out, and why. */
+    readonly onReject?: (rejection: {
+        path: string;
+        reason: string;
+    }) => void;
+}
+/**
+ * Directories a walk does not enter. Kept as short as the evidence allows: a
+ * name here is a package whose skill will never be found, and the cost of one
+ * extra readdir is far below the cost of missing a skill. Measured 20260906 --
+ * `lib` was on this list and hid playwright's `lib/skill/SKILL.md`, which is
+ * the most widely installed skill in the real world.
+ */
+declare const SKIPPED_DIRS: ReadonlySet<string>;
+/**
+ * How deep below a package root a SKILL.md is looked for. Three reaches every
+ * convention in use (skills, .agent/skills, .claude/skills, .gemini/skills,
+ * .codex/skills); four was measured to find nothing more.
+ */
+declare const MAX_SKILL_DEPTH = 3;
+/**
+ * Reads `name` and `description` out of YAML frontmatter without a parser.
+ *
+ * A parser is a dependency this server does not otherwise need, and the two
+ * fields it wants are flat scalars on their own line. Anything more nested is
+ * not read, which is the honest limit rather than a partial YAML.
+ */
+declare function readFrontmatter(source: string): Record<string, string>;
+/**
+ * The body after the frontmatter, or the whole file when there is none.
+ *
+ * The slice starts at the newline terminating the closing `---`, and a blank
+ * line after it is separator rather than content, so both are dropped.
+ */
+declare function readBody(source: string): string;
+/**
+ * Every skill reachable from the given roots, sorted by name.
+ *
+ * A package with no skills directory contributes nothing and costs one
+ * `existsSync` per convention. A skill with no description is skipped rather
+ * than listed:
+ * `find` ranks descriptions, so one without a description can only ever be
+ * found by already knowing its name, and listing it would spend a session's
+ * tokens on an entry that cannot answer.
+ */
+declare function readCatalog(options: CatalogOptions): SkillEntry[];
+/** A catalog entry without its body, which is what `catalog` returns. */
+declare function withoutBody({ path, ...rest }: SkillEntry): Omit<SkillEntry, "path">;
+/** Path relative to a root, for a message a reader can act on. */
+declare function displayPath(root: string, entry: SkillEntry): string;
+
+export { type CatalogOptions as C, MAX_SKILL_DEPTH as M, type SkillEntry as S, SKIPPED_DIRS as a, readCatalog as b, readFrontmatter as c, displayPath as d, readBody as r, withoutBody as w };

package/dist/{chunk-SLTUWTII.js → chunk-MBAXK4IZ.js}

@@ -1,6 +1,6 @@
 import {
   normaliseIntent
-} from "./chunk-N3SHKKWG.js";
+} from "./chunk-SPWHSHOC.js";
 
 // src/cache.ts
 async function openDatabase(path) {
@@ -131,4 +131,4 @@ export {
   DEFAULT_INTENT_CACHE_LIMIT,
   openIntentCache
 };
-//# sourceMappingURL=chunk-SLTUWTII.js.map
+//# sourceMappingURL=chunk-MBAXK4IZ.js.map

package/dist/{chunk-AJNIMNCV.js → chunk-QJS3NYLT.js}

@@ -1,6 +1,6 @@
 import {
   createSkillServer
-} from "./chunk-N3SHKKWG.js";
+} from "./chunk-SPWHSHOC.js";
 
 // src/stdio.ts
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
@@ -8,8 +8,12 @@ function resolveRoots(argv, cwd) {
   const given = argv.filter((arg) => !arg.startsWith("-"));
   return given.length > 0 ? given : [`${cwd}/node_modules`];
 }
-function serve(roots, scopes = []) {
-  const options = scopes.length > 0 ? { roots, scopes } : { roots };
+function serve(catalog) {
+  const options = {
+    ...catalog,
+    onReject: ({ path, reason }) => process.stderr.write(`pmcp: skipped ${path}: ${reason}
+`)
+  };
   serveStdio(() => createSkillServer(options), {
     // stdout is the protocol. A diagnostic written there corrupts the stream,
     // so out-of-band errors go to stderr and nowhere else.
@@ -19,10 +23,11 @@ function serve(roots, scopes = []) {
 }
 function main(argv = process.argv.slice(2)) {
   const scopeArg = argv.find((arg) => arg.startsWith("--scope="));
-  serve(
-    resolveRoots(argv, process.cwd()),
-    scopeArg ? scopeArg.slice("--scope=".length).split(",") : []
-  );
+  const scopes = scopeArg ? scopeArg.slice("--scope=".length).split(",") : [];
+  serve({
+    roots: resolveRoots(argv, process.cwd()),
+    ...scopes.length > 0 ? { scopes } : {}
+  });
 }
 
 export {
@@ -30,4 +35,4 @@ export {
   serve,
   main
 };
-//# sourceMappingURL=chunk-AJNIMNCV.js.map
+//# sourceMappingURL=chunk-QJS3NYLT.js.map