@modootoday/pmcp 0.1.4 → 0.3.0

package/dist/cli.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   openDatabase
-} from "./chunk-SLTUWTII.js";
+} from "./chunk-MBAXK4IZ.js";
 import {
   serve
-} from "./chunk-AJNIMNCV.js";
+} from "./chunk-QJS3NYLT.js";
 import {
   readCatalog
-} from "./chunk-N3SHKKWG.js";
+} from "./chunk-SPWHSHOC.js";
 
 // src/cli/command.ts
 var ArgumentError = class extends Error {
@@ -302,16 +302,46 @@ var CATALOG_OPTIONS = [
     describe: "Only packages whose names start with this. Repeatable.",
     repeat: true,
     placeholder: "<prefix>"
+  },
+  {
+    name: "marketplace",
+    describe: "A plugin marketplace directory (holds .claude-plugin/marketplace.json). Repeatable.",
+    repeat: true,
+    placeholder: "<dir>"
+  },
+  {
+    name: "package",
+    describe: "A package directory read directly, for one no node_modules links; without a package.json its folder name is the package name. Repeatable.",
+    repeat: true,
+    placeholder: "<dir>"
+  },
+  {
+    name: "workspace",
+    describe: "A workspace root, or a glob of them: each root and every member its workspaces globs name. Repeatable.",
+    repeat: true,
+    placeholder: "<dir>"
   }
 ];
 function rootsFrom(context) {
   const given = many(context.args, "root");
   return given.length > 0 ? given : [`${context.cwd}/node_modules`];
 }
-function catalogFrom(context) {
+function catalogOptionsFrom(context, onReject) {
   const scopes = many(context.args, "scope");
-  const roots = rootsFrom(context);
-  return readCatalog(scopes.length > 0 ? { roots, scopes } : { roots });
+  const marketplaces = many(context.args, "marketplace");
+  const packages = many(context.args, "package");
+  const workspaces = many(context.args, "workspace");
+  return {
+    roots: rootsFrom(context),
+    ...scopes.length > 0 ? { scopes } : {},
+    ...marketplaces.length > 0 ? { marketplaces } : {},
+    ...packages.length > 0 ? { packages } : {},
+    ...workspaces.length > 0 ? { workspaces } : {},
+    ...onReject ? { onReject } : {}
+  };
+}
+function catalogFrom(context, onReject) {
+  return readCatalog(catalogOptionsFrom(context, onReject));
 }
 
 // src/commands/reindex.ts
@@ -418,26 +448,39 @@ var indexCommand = {
 // src/commands/list.ts
 var listCommand = {
   name: "list",
-  describe: "List the skills discovered in node_modules",
-  usage: "pmcp list [--root <dir>] [--scope <prefix>] [--json]",
+  describe: "List the skills discovered in node_modules and marketplaces",
+  usage: "pmcp list [--root <dir>] [--scope <prefix>] [--marketplace <dir>] [--package <dir>] [--workspace <dir|glob>] [--json]",
   options: [
     ...CATALOG_OPTIONS,
     { name: "json", describe: "Emit JSON rather than a table.", boolean: true }
   ],
   run(context) {
-    const entries = catalogFrom(context);
+    const rejected = [];
+    const entries = catalogFrom(
+      context,
+      (rejection) => rejected.push(rejection)
+    );
     if (context.args.flags.has("json")) {
-      context.ui.data(`${JSON.stringify(entries, null, 2)}
-`);
-      return entries.length > 0 ? 0 : 1;
+      context.ui.data(
+        `${JSON.stringify({ skills: entries, rejected }, null, 2)}
+`
+      );
+      return entries.length > 0 && rejected.length === 0 ? 0 : 1;
     }
+    for (const { path, reason } of rejected)
+      context.ui.error("skipped", `${path}: ${reason}`);
     if (entries.length === 0) {
       context.ui.error("no skills found", rootsFrom(context).join(" "));
       return 1;
     }
-    context.ui.table(entries.map((entry2) => [entry2.name, entry2.description]));
+    context.ui.table(
+      entries.map((entry2) => [
+        entry2.tier === void 0 ? entry2.name : `${entry2.name} [${entry2.tier}]`,
+        entry2.description
+      ])
+    );
     context.ui.success(`${entries.length} skills`);
-    return 0;
+    return rejected.length === 0 ? 0 : 1;
   }
 };
 
@@ -445,10 +488,10 @@ var listCommand = {
 var serveCommand = {
   name: "serve",
   describe: "Run the MCP server on stdio (the default with no command)",
-  usage: "pmcp serve [--root <dir>] [--scope <prefix>]",
+  usage: "pmcp serve [--root <dir>] [--scope <prefix>] [--marketplace <dir>] [--package <dir>] [--workspace <dir>]",
   options: [...CATALOG_OPTIONS],
   run(context) {
-    serve(rootsFrom(context), many(context.args, "scope"));
+    serve(catalogOptionsFrom(context));
     return 0;
   }
 };
@@ -2042,7 +2085,7 @@ function dispatch(argv, options = {}) {
   }
   return run(command, rest, { ui, env, cwd });
 }
-var VERSION = "0.1.4";
+var VERSION = "0.3.0";
 async function run(command, argv, context) {
   try {
     return await command.run({

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { S as SkillEntry, C as CatalogOptions } from './catalog-BiPLcbLu.js';
+export { M as MAX_SKILL_DEPTH, a as SKIPPED_DIRS, d as displayPath, r as readBody, b as readCatalog, c as readFrontmatter, w as withoutBody } from './catalog-BiPLcbLu.js';
 import { McpServer } from '@modelcontextprotocol/server';
 
 /**
@@ -61,74 +63,6 @@ declare const DEFAULT_INTENT_CACHE_LIMIT = 4096;
  */
 declare function openIntentCache(options: IntentCacheOptions): Promise<IntentCache | null>;
 
-/**
- * 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;
-}
-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[];
-}
-/**
- * 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;
-
 /**
  * Ranking an intent against skill descriptions.
  *
@@ -186,13 +120,65 @@ declare function cosine(a: Float32Array, b: Float32Array): number;
 declare function find(options: FindOptions): Promise<FindResult>;
 
 /**
- * The three tools, and nothing else.
+ * Skills laid out as an agent plugin marketplace: a directory holding
+ * `.claude-plugin/marketplace.json`, whose plugins keep skills at
+ * `skills/<skill>/SKILL.md`. No package.json is involved, which is why the
+ * node_modules walk never saw them.
+ */
+
+type MetadataValue = string | readonly string[];
+/** Why a skill was left out rather than served. */
+interface Rejection {
+    readonly path: string;
+    readonly reason: string;
+}
+/**
+ * The `metadata:` block of a frontmatter, one level deep: scalars and inline
+ * lists. Deeper nesting is skipped rather than half-read.
+ */
+declare function readMetadata(source: string): Record<string, MetadataValue>;
+/** The raw frontmatter text between the fences, for skill_describe. */
+declare function readFrontmatterText(source: string): string;
+/**
+ * Every skill one marketplace lists. A skill whose own tier disagrees with the
+ * marketplace's is rejected: a mislabelled tier is how a private skill leaks.
+ */
+declare function readMarketplace(dir: string, onReject?: (rejection: Rejection) => void): SkillEntry[];
+
+/**
+ * The five tools, and nothing else.
  *
  * The point of the server is that a session's startup cost does not grow with
- * the number of skills installed: the host lists three tools whatever the
+ * the number of skills installed: the host lists five tools whatever the
  * catalog holds, and a body is read only when one is asked for.
  */
 
+/** Largest file skill_read returns. A skill needing more should split it. */
+declare const READ_BUDGET_BYTES: number;
+/** How many files skill_describe lists before saying the rest were cut. */
+declare const DESCRIBE_FILE_LIMIT = 200;
+declare const CATALOG_PAGE_SIZE = 8;
+declare const CATALOG_PAGE_MAX = 20;
+/** Equality filters over catalog fields. Unset keys match everything. */
+interface SkillFilters {
+    readonly tier?: string;
+    readonly package?: string;
+    readonly level?: string;
+    readonly domain?: string;
+    readonly medium?: string;
+}
+type ReadResult = {
+    readonly ok: true;
+    readonly name: string;
+    readonly path: string;
+    readonly bytes: number;
+    readonly sha256: string;
+    readonly text: string;
+} | {
+    readonly ok: false;
+    readonly error: string;
+    readonly detail: string;
+};
 interface SkillServerOptions extends CatalogOptions {
     readonly embedder?: Embedder;
     readonly cache?: IntentCache;
@@ -202,11 +188,15 @@ interface SkillServerOptions extends CatalogOptions {
 }
 interface CatalogResponse {
     readonly count: number;
+    readonly page: number;
+    readonly totalPages: number;
+    readonly hasNext: boolean;
     readonly packages: readonly {
         readonly package: string;
         readonly skills: readonly {
             readonly name: string;
             readonly description: string;
+            readonly tier?: string;
         }[];
     }[];
 }
@@ -222,10 +212,37 @@ interface CallResponse {
  * speak a protocol to get them.
  */
 declare function createSkillTools(options: SkillServerOptions): {
-    /** Grouped, and without bodies. The cheap overview and the search's miss path. */
-    catalog(): CatalogResponse;
+    /**
+     * 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?: {
+        page?: number;
+        pageSize?: number;
+        tier?: string;
+    }): CatalogResponse;
     /** Ranked names. Returns; never loads a body. */
-    find(intent: string, limit?: number): Promise<FindResult>;
+    find(intent: string, limit?: number, filters?: SkillFilters): Promise<FindResult>;
+    /** Every property of one skill and the files it carries, without bodies. */
+    describe(name: string): {
+        name: string;
+        package: string;
+        description: string;
+        tier: string | undefined;
+        metadata: Readonly<Record<string, string | readonly string[]>>;
+        frontmatter: string;
+        files: {
+            path: string;
+            bytes: number;
+            sha256: string;
+        }[];
+        filesTruncated: boolean;
+    } | null;
+    /**
+     * 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: string, path?: string): ReadResult;
     /** One body, at the moment it is needed. */
     call(name: string): CallResponse | null;
     /** Drops the memoised catalog, so the next call re-reads the tree. */
@@ -235,29 +252,29 @@ declare function createSkillTools(options: SkillServerOptions): {
 type SkillTools = ReturnType<typeof createSkillTools>;
 
 /**
- * The three tools, spoken over MCP.
+ * The five tools, spoken over MCP.
  *
  * Thin on purpose: every decision is in `createSkillTools`, and this file only
  * names the tools and shapes their arguments. A consumer that wants the same
- * three operations from a hook or a script uses the tools directly and never
- * speaks a protocol.
+ * operations from a hook or a script uses the tools directly and never speaks
+ * a protocol.
  */
 
 /** Reported to the host on connect. */
 declare const SERVER_NAME = "pmcp";
 /**
- * Registers the three tools on a server.
+ * Registers the five tools on a server.
  *
  * Exported separately from the stdio entry so a consumer already running an MCP
  * server can add these to it rather than starting a second process.
  */
 declare function registerSkillTools(server: McpServer, tools: SkillTools): McpServer;
 /**
- * A server with the three tools registered.
+ * A server with the five tools registered.
  *
  * The catalog is read on first use rather than here, so a host that connects
  * and never asks pays nothing for the walk.
  */
 declare function createSkillServer(options: SkillServerOptions): McpServer;
 
-export { type CallResponse, type CatalogOptions, type CatalogResponse, DEFAULT_FIND_LIMIT, DEFAULT_INTENT_CACHE_LIMIT, type Embedder, type FindOptions, type FindResult, type IntentCache, type IntentCacheOptions, type IntentCacheStats, MAX_SKILL_DEPTH, type Match, type Ranking, SERVER_NAME, SKIPPED_DIRS, type SkillEntry, type SkillServerOptions, type SkillTools, cosine, createSkillServer, createSkillTools, displayPath, find, lexicalScore, normaliseIntent, openIntentCache, readBody, readCatalog, readFrontmatter, registerSkillTools, withoutBody };
+export { CATALOG_PAGE_MAX, CATALOG_PAGE_SIZE, type CallResponse, CatalogOptions, type CatalogResponse, DEFAULT_FIND_LIMIT, DEFAULT_INTENT_CACHE_LIMIT, DESCRIBE_FILE_LIMIT, type Embedder, type FindOptions, type FindResult, type IntentCache, type IntentCacheOptions, type IntentCacheStats, type Match, type MetadataValue, READ_BUDGET_BYTES, type Ranking, type ReadResult, type Rejection, SERVER_NAME, SkillEntry, type SkillFilters, type SkillServerOptions, type SkillTools, cosine, createSkillServer, createSkillTools, find, lexicalScore, normaliseIntent, openIntentCache, readFrontmatterText, readMarketplace, readMetadata, registerSkillTools };

package/dist/index.js

@@ -1,10 +1,14 @@
 import {
   DEFAULT_INTENT_CACHE_LIMIT,
   openIntentCache
-} from "./chunk-SLTUWTII.js";
+} from "./chunk-MBAXK4IZ.js";
 import {
+  CATALOG_PAGE_MAX,
+  CATALOG_PAGE_SIZE,
   DEFAULT_FIND_LIMIT,
+  DESCRIBE_FILE_LIMIT,
   MAX_SKILL_DEPTH,
+  READ_BUDGET_BYTES,
   SERVER_NAME,
   SKIPPED_DIRS,
   cosine,
@@ -17,13 +21,20 @@ import {
   readBody,
   readCatalog,
   readFrontmatter,
+  readFrontmatterText,
+  readMarketplace,
+  readMetadata,
   registerSkillTools,
   withoutBody
-} from "./chunk-N3SHKKWG.js";
+} from "./chunk-SPWHSHOC.js";
 export {
+  CATALOG_PAGE_MAX,
+  CATALOG_PAGE_SIZE,
   DEFAULT_FIND_LIMIT,
   DEFAULT_INTENT_CACHE_LIMIT,
+  DESCRIBE_FILE_LIMIT,
   MAX_SKILL_DEPTH,
+  READ_BUDGET_BYTES,
   SERVER_NAME,
   SKIPPED_DIRS,
   cosine,
@@ -37,6 +48,9 @@ export {
   readBody,
   readCatalog,
   readFrontmatter,
+  readFrontmatterText,
+  readMarketplace,
+  readMetadata,
   registerSkillTools,
   withoutBody
 };

package/dist/stdio.d.ts

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { C as CatalogOptions } from './catalog-BiPLcbLu.js';
+
 /**
  * The stdio entry a host launches.
  *
@@ -6,9 +8,10 @@
  * the dependency tree is its data source, and from an npx cache it is not a
  * sibling of the consumer's packages and would find no skills at all.
  */
+
 /** `node_modules` roots to walk, from argv or from the working directory. */
 declare function resolveRoots(argv: readonly string[], cwd: string): string[];
-declare function serve(roots: readonly string[], scopes?: readonly string[]): void;
+declare function serve(catalog: CatalogOptions): void;
 declare function main(argv?: readonly string[]): void;
 
 export { main, resolveRoots, serve };

package/dist/stdio.js

@@ -3,8 +3,8 @@ import {
   main,
   resolveRoots,
   serve
-} from "./chunk-AJNIMNCV.js";
-import "./chunk-N3SHKKWG.js";
+} from "./chunk-QJS3NYLT.js";
+import "./chunk-SPWHSHOC.js";
 export {
   main,
   resolveRoots,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modootoday/pmcp",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "license": "Elastic-2.0",
   "author": "modootoday",
   "description": "An MCP server that finds the skills your installed packages already ship. Reads SKILL.md out of node_modules by shape rather than by path, so it sees the skills, .agent, .claude, .gemini and .codex conventions alike, and keeps session startup flat as the number of installed skills grows.",
@@ -57,7 +57,7 @@
   ],
   "scripts": {
     "build": "tsup",
-    "typecheck": "tsc --noEmit --incremental --tsBuildInfoFile ./dist/.tsbuildinfo && tsc -p tsconfig.tests.json --noEmit",
+    "typecheck": "tsgo --noEmit --incremental --tsBuildInfoFile ./dist/.tsbuildinfo --singleThreaded && tsgo -p tsconfig.tests.json --noEmit --singleThreaded",
     "test": "vitest run",
     "clean": "rimraf dist",
     "catalog:refresh": "node scripts/refresh-catalog.mjs",
@@ -84,6 +84,7 @@
   "devDependencies": {
     "@types/node": "^22.15.21",
     "@types/semver": "7.8.0",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "prettier": "^3.6.2",
     "rimraf": "^6.0.1",
     "tsup": "^8.5.1",

package/skills/package-skill-catalog/SKILL.md

@@ -5,9 +5,9 @@ description: A project has grown past a hundred dependencies and nobody knows wh
 
 # pmcp
 
-An MCP server that reads `SKILL.md` files out of `node_modules` and serves them
-as three tools, so a session pays for the one skill it opens rather than for the
-whole catalog.
+An MCP server that reads `SKILL.md` files out of `node_modules` and plugin
+marketplaces and serves them as five tools, so a session pays for the one skill
+it opens rather than for the whole catalog.
 
 ## When to reach for it
 
@@ -108,11 +108,13 @@ discovery will and will not walk.
 
 ### Tools on the wire
 
-| Tool            | Argument                               | Returns                            |
-| --------------- | -------------------------------------- | ---------------------------------- |
-| `skill_catalog` | optional scope                         | every skill's name and description |
-| `skill_find`    | `intent`, a sentence; optional `limit` | ranked matches                     |
-| `skill_call`    | `name`                                 | that skill's body                  |
+| Tool             | Argument                                          | Returns                              |
+| ---------------- | ------------------------------------------------- | ------------------------------------ |
+| `skill_catalog`  | optional `page`, `pageSize`, `tier`               | each skill's name, description, tier |
+| `skill_find`     | `intent`, a sentence; optional `limit`, `filters` | ranked matches                       |
+| `skill_describe` | `name`                                            | metadata and files, no body          |
+| `skill_call`     | `name`                                            | that skill's body                    |
+| `skill_read`     | `name`, optional `path`                           | one file inside the skill, as text   |
 
 ## Worked examples