@modootoday/pmcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,263 @@
+import { McpServer } from '@modelcontextprotocol/server';
+
+/**
+ * The intent key and the cache contract.
+ *
+ * Separate from the sqlite implementation so that ranking, which needs the key
+ * and the interface, does not pull a bun-only module into a consumer running
+ * under node. Only `cache.ts` requires bun.
+ */
+interface IntentCacheStats {
+    readonly hits: number;
+    readonly misses: number;
+    /** Rows found for the key but written by a different model. */
+    readonly mismatched: number;
+    readonly rows: number;
+    /** Which sqlite builtin answered, or absent when there is no cache. */
+    readonly provider?: string;
+}
+interface IntentCache {
+    /** The cached vector for an intent, or null when nothing usable is stored. */
+    get(intent: string): Float32Array | null;
+    put(intent: string, vector: Float32Array): void;
+    stats(): IntentCacheStats;
+    close(): void;
+}
+/**
+ * Same question, differently typed. Case, punctuation and spacing only — the
+ * key has to survive a caller writing "How do I wire X?" and "how do i wire x".
+ */
+declare function normaliseIntent(intent: string): string;
+
+/**
+ * Query vectors, kept on disk between sessions.
+ *
+ * An MCP server starts per session and exits with it, so a process-local cache
+ * begins empty every time and the same question pays its full embed cost in
+ * every session that asks it. The table outlives the process; that is the whole
+ * reason it is a table.
+ */
+
+interface IntentCacheOptions {
+    /** Database file. `:memory:` is accepted and is what the tests use. */
+    readonly path: string;
+    /** The embedder's identity. Rows from another model are never scored. */
+    readonly modelId: string;
+    /** Vector width. A row of a different width is a different model. */
+    readonly dims: number;
+    /** Rows kept. The least recently asked are dropped past this. */
+    readonly limit?: number;
+    /** Injected for tests. Real time otherwise. */
+    readonly now?: () => number;
+}
+declare const DEFAULT_INTENT_CACHE_LIMIT = 4096;
+/**
+ * Opens the cache, or returns null when it cannot be opened.
+ *
+ * Null is the normal answer on a read-only volume, a locked file, a corrupt
+ * database, or a runtime with neither builtin: the caller embeds on demand
+ * instead. A cache that throws would turn a missing optimisation into a failed
+ * search, and an older runtime is that case rather than an error.
+ */
+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.
+ *
+ * Semantic when an embedder is supplied, lexical otherwise, and the answer says
+ * which. A caller that cannot tell the two apart cannot tell a degraded server
+ * from a working one.
+ */
+
+type Ranking = "semantic" | "lexical";
+interface Match {
+    readonly name: string;
+    readonly package: string;
+    readonly description: string;
+    readonly score: number;
+}
+interface FindResult {
+    readonly ranking: Ranking;
+    readonly matches: readonly Match[];
+}
+/**
+ * The encoder, supplied by the caller. There is no default and no bundled
+ * model: which model runs decides what the scores mean, so it is the consuming
+ * repository's declaration rather than this package's.
+ */
+interface Embedder {
+    readonly modelId: string;
+    readonly dims: number;
+    embed(text: string): Promise<Float32Array>;
+}
+interface FindOptions {
+    readonly entries: readonly SkillEntry[];
+    readonly intent: string;
+    readonly limit?: number;
+    readonly embedder?: Embedder;
+    readonly cache?: IntentCache;
+    /** Precomputed description vectors, keyed by skill name. */
+    readonly vectors?: ReadonlyMap<string, Float32Array>;
+}
+declare const DEFAULT_FIND_LIMIT = 5;
+/**
+ * Token overlap and bigram Dice, averaged. Deterministic and dependency-free:
+ * this is the answer when there is no model, so it must never be the thing
+ * that fails.
+ */
+declare function lexicalScore(intent: string, description: string): number;
+/** Cosine over two equal-width vectors. Zero when either has no magnitude. */
+declare function cosine(a: Float32Array, b: Float32Array): number;
+/**
+ * Ranked matches, and which ranking produced them.
+ *
+ * Returns rather than loads: a search verb that also acts cannot be used to
+ * look, and the whole reason this server exists is that looking should be
+ * cheap.
+ */
+declare function find(options: FindOptions): Promise<FindResult>;
+
+/**
+ * The three 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
+ * catalog holds, and a body is read only when one is asked for.
+ */
+
+interface SkillServerOptions extends CatalogOptions {
+    readonly embedder?: Embedder;
+    readonly cache?: IntentCache;
+    readonly vectors?: ReadonlyMap<string, Float32Array>;
+    /** Injected for tests. Reads the catalog off disk otherwise. */
+    readonly loadCatalog?: (options: CatalogOptions) => SkillEntry[];
+}
+interface CatalogResponse {
+    readonly count: number;
+    readonly packages: readonly {
+        readonly package: string;
+        readonly skills: readonly {
+            readonly name: string;
+            readonly description: string;
+        }[];
+    }[];
+}
+interface CallResponse {
+    readonly name: string;
+    readonly body: string;
+}
+/**
+ * The catalog, the search and the read, as plain functions.
+ *
+ * Separate from the MCP wiring so they can be exercised without a transport,
+ * and so a consumer that wants them from a hook or a script is not made to
+ * 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;
+    /** Ranked names. Returns; never loads a body. */
+    find(intent: string, limit?: number): Promise<FindResult>;
+    /** 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. */
+    refresh(): void;
+    entries: () => Omit<SkillEntry, "path">[];
+};
+type SkillTools = ReturnType<typeof createSkillTools>;
+
+/**
+ * The three 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.
+ */
+
+/** Reported to the host on connect. */
+declare const SERVER_NAME = "pmcp";
+/**
+ * Registers the three 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.
+ *
+ * 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 };

package/dist/index.js

@@ -0,0 +1,43 @@
+import {
+  DEFAULT_INTENT_CACHE_LIMIT,
+  openIntentCache
+} from "./chunk-X3KWFZBP.js";
+import {
+  DEFAULT_FIND_LIMIT,
+  MAX_SKILL_DEPTH,
+  SERVER_NAME,
+  SKIPPED_DIRS,
+  cosine,
+  createSkillServer,
+  createSkillTools,
+  displayPath,
+  find,
+  lexicalScore,
+  normaliseIntent,
+  readBody,
+  readCatalog,
+  readFrontmatter,
+  registerSkillTools,
+  withoutBody
+} from "./chunk-WIVQKKE4.js";
+export {
+  DEFAULT_FIND_LIMIT,
+  DEFAULT_INTENT_CACHE_LIMIT,
+  MAX_SKILL_DEPTH,
+  SERVER_NAME,
+  SKIPPED_DIRS,
+  cosine,
+  createSkillServer,
+  createSkillTools,
+  displayPath,
+  find,
+  lexicalScore,
+  normaliseIntent,
+  openIntentCache,
+  readBody,
+  readCatalog,
+  readFrontmatter,
+  registerSkillTools,
+  withoutBody
+};
+//# sourceMappingURL=index.js.map

package/dist/stdio.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * The stdio entry a host launches.
+ *
+ * Wired as `node <path in node_modules>`, never `npx`: the server's position in
+ * 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 main(argv?: readonly string[]): void;
+
+export { main, resolveRoots, serve };

package/dist/stdio.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import {
+  main,
+  resolveRoots,
+  serve
+} from "./chunk-UTABV2C4.js";
+import "./chunk-WIVQKKE4.js";
+export {
+  main,
+  resolveRoots,
+  serve
+};
+//# sourceMappingURL=stdio.js.map

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@modootoday/pmcp",
+  "version": "0.1.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.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "skills",
+    "agent",
+    "node-modules",
+    "catalog"
+  ],
+  "homepage": "https://pmcp.build",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modootoday/pmcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/modootoday/pmcp/issues"
+  },
+  "packageManager": "bun@1.3.14",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./stdio": {
+      "types": "./dist/stdio.d.ts",
+      "import": "./dist/stdio.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    }
+  },
+  "bin": {
+    "pmcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/.tsbuildinfo",
+    "skills",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit --incremental --tsBuildInfoFile ./dist/.tsbuildinfo && tsc -p tsconfig.tests.json --noEmit",
+    "test": "vitest run",
+    "clean": "rimraf dist",
+    "catalog:refresh": "node scripts/refresh-catalog.mjs",
+    "site:build": "node scripts/build-catalog-pages.mjs",
+    "site:deployed": "node scripts/check-deployed.mjs",
+    "prepack": "npm run build && npm run typecheck && npm test",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "zod": "^4.5.1",
+    "semver": "7.8.5"
+  },
+  "peerDependencies": {
+    "@huggingface/transformers": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "@types/semver": "7.8.0",
+    "prettier": "^3.6.2",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "bun": ">=1.3.0"
+  }
+}

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

@@ -0,0 +1,237 @@
+---
+name: package-skill-catalog
+description: A project has grown past a hundred dependencies and nobody knows which of them shipped usage documentation an agent could read, so every question about an installed package is answered by opening its source; or an agent's context is being spent listing skills it never opens, and startup cost grows with every dependency added.
+---
+
+# 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.
+
+## When to reach for it
+
+Reach for this when the skills you want an agent to read arrive as npm packages
+and leave when those packages are uninstalled. Discovery is derived from the
+installed tree at request time, so the catalog is always true of the project and
+there is no list for anyone to maintain.
+
+Do not reach for this to hold a project's own skills. Those live in the
+repository, they are not installed, and a host that already loads them does not
+need a server in front of them. This exists for the skills you did not write.
+
+## Install and wire
+
+```sh
+npm install --save-dev pmcp
+```
+
+For a host that spawns MCP servers over stdio:
+
+```json
+{
+  "mcpServers": {
+    "pmcp": { "command": "npx", "args": ["@modootoday/pmcp"] }
+  }
+}
+```
+
+Flags, all optional:
+
+| Flag                   | Effect                                                              |
+| ---------------------- | ------------------------------------------------------------------- |
+| `--root=<dir>`         | Use this `node_modules` instead of discovering upwards. Repeatable. |
+| `--scope=@acme,@other` | Only catalogue packages whose names start with one of these.        |
+
+Embedded in a host you are writing yourself:
+
+```ts
+import { createSkillServer } from "@modootoday/pmcp";
+
+const server = createSkillServer({
+  roots: ["./node_modules"],
+  scopes: ["@acme"],
+});
+```
+
+## What the consuming repository must supply
+
+Nothing, to read skills. To publish one, a package supplies a `SKILL.md` whose
+YAML frontmatter carries `name` and `description`, at any of these paths:
+
+```
+<package>/skills/<slug>/SKILL.md
+<package>/.agent/skills/<slug>/SKILL.md
+<package>/.claude/skills/<slug>/SKILL.md
+<package>/.gemini/skills/<slug>/SKILL.md
+<package>/.codex/skills/<slug>/SKILL.md
+```
+
+The path is not what makes it a skill; the file is. Discovery walks each package
+to a depth of three and treats any `SKILL.md` as a skill, skipping build output,
+sources, nested installs and test corpora.
+
+The `description` is the only text ranked, so write it as the symptom a reader
+already has rather than as a list of what the package does. A skill with no
+`description` is skipped rather than listed: ranking could never surface it, and
+listing it would spend a session's tokens on an entry that cannot answer.
+
+The package must also ship the file. A `SKILL.md` outside the manifest's `files`
+array is not in the tarball and therefore not in anyone's `node_modules`.
+
+## API
+
+### Server
+
+`createSkillServer(options)` returns a configured MCP server. `options.roots` is
+required and holds `node_modules` directories, not package directories.
+`options.scopes` filters by package-name prefix.
+
+`SERVER_NAME` is the name the server reports at initialize.
+
+### Catalog
+
+`readCatalog({roots, scopes})` returns `SkillEntry[]`, sorted by name and
+deduplicated: the first root wins, because a nested `node_modules` holds an older
+copy of a package the outer root already resolved.
+
+A `SkillEntry` carries `name` (`<package>/<slug>`), `package`, `slug`,
+`description` and the absolute `path` of the file.
+
+`readFrontmatter(source)` and `readBody(source)` split a `SKILL.md`. The
+frontmatter reader is deliberately not a YAML parser: it reads flat scalars on
+their own line and nothing nested, which is the honest limit rather than a
+partial YAML.
+
+`MAX_SKILL_DEPTH` and `SKIPPED_DIRS` are exported so a caller can see what
+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                  |
+
+## Worked examples
+
+### Reading the catalog without a server
+
+```ts
+import { readCatalog } from "@modootoday/pmcp";
+
+const catalog = readCatalog({ roots: ["./node_modules"] });
+console.log(`${catalog.length} skills`);
+for (const entry of catalog.slice(0, 3)) {
+  console.log(`${entry.name}: ${entry.description}`);
+}
+```
+
+### Asking a question rather than a keyword
+
+`skill_find` ranks descriptions, which are written as symptoms, so a sentence
+retrieves and a bare noun does not. This is the difference the tool descriptions
+are trying to teach, and it is easy to get wrong:
+
+```ts
+// Retrieves: the sentence shares vocabulary with a symptom description.
+await client.callTool({
+  name: "skill_find",
+  arguments: {
+    intent: "my build copies dist into the image but a stale bundle ships",
+  },
+});
+
+// Does not: one word matches many descriptions weakly and none strongly.
+// Use skill_catalog for this shape of question; it filters rather than ranks.
+await client.callTool({ name: "skill_find", arguments: { intent: "build" } });
+```
+
+### Scoping a large tree
+
+```ts
+const mine = readCatalog({
+  roots: ["./node_modules"],
+  scopes: ["@acme/"],
+});
+```
+
+The prefix is matched against the package name with `startsWith`, so `@acme`
+also matches `@acmetools/thing`. Include the trailing slash when you mean the
+scope.
+
+## Testing against it
+
+### Build a tree, do not mock the filesystem
+
+`readCatalog` takes roots, so a test supplies a real temporary directory. This
+is faster than a filesystem mock and it exercises the walk rather than a stand-in
+for it.
+
+```ts
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readCatalog } from "@modootoday/pmcp";
+
+const root = mkdtempSync(join(tmpdir(), "skills-"));
+const pkg = join(root, "node_modules", "example");
+mkdirSync(join(pkg, "skills", "wiring"), { recursive: true });
+writeFileSync(join(pkg, "package.json"), JSON.stringify({ name: "example" }));
+writeFileSync(
+  join(pkg, "skills", "wiring", "SKILL.md"),
+  "---\nname: wiring\ndescription: Something breaks and you need this.\n---\n\nbody\n",
+);
+
+const catalog = readCatalog({ roots: [join(root, "node_modules")] });
+```
+
+### Assert on what was found, never that something was found
+
+```ts
+// Proves nothing: passes on an empty tree and on a broken walk alike.
+expect(catalog).toBeDefined();
+
+// Proves the walk reached this package under this convention.
+expect(catalog.map((entry) => entry.name)).toContain("example/wiring");
+```
+
+A test that asserts a non-empty result cannot distinguish a catalog that found
+the wrong thing from one that found the right thing. Name the entry.
+
+## Invariants
+
+- **Discovery is derived, never declared.** Installing a package is how its
+  skill arrives and uninstalling it is how the skill leaves. There is no list.
+- **A skill without a description is not catalogued.** Ranking is over
+  descriptions, so an entry without one could only be reached by already knowing
+  its name.
+- **The first root wins.** A nested `node_modules` holds an older copy of an
+  already-resolved package; the outer one is the one the project runs.
+- **Absence is not failure.** No model, no SQLite, and an unreadable file each
+  degrade the answer rather than ending the request, and the response says which
+  path answered so a fallback is visible rather than silent.
+- **Startup does not grow with the catalog.** Bodies are read by `skill_call`,
+  one at a time. Adding a dependency that ships ten skills adds ten short
+  descriptions, not ten documents.
+
+## What it will not do
+
+The MCP tools read installed files and return text. They do not install packages
+or make catalog API requests. The CLI's available, install and sync commands are
+separate from that local reading path.
+
+The CLI does not write directly into node_modules or treat OAuth access tokens
+as npm credentials. Installation uses the project's npm or Bun configuration,
+requires confirmation, and verifies registry integrity and the installed version.
+Use --dry-run to inspect changes without applying them. Sync does not delete
+unrelated dependencies or skills authored by the user.
+
+It will not parse full YAML. Frontmatter is read as flat scalars, so a nested
+structure is ignored rather than half-understood.
+
+The default server ranks lexically. The optional index command requires
+`@huggingface/transformers` and may load model assets when explicitly invoked.
+Installing that peer alone is not proof that the server uses its index.
+No postinstall hook downloads a model.