@modootoday/pmcp 0.1.0

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/NOTICE

@@ -0,0 +1,49 @@
+pmcp
+
+Copyright (c) 2026 modootoday. All rights reserved.
+
+Licensor: modootoday
+Licensed under the Elastic License 2.0; see LICENSE.
+
+The licensor is modootoday, the company, not any individual contributor. This
+file names the licensor because the Elastic License 2.0 defines that term rather
+than carrying a copyright line of its own; LICENSE is kept unmodified.
+
+What the licence permits, in short, without replacing the terms in LICENSE:
+
+  - Using this software inside your own company, on any scale.
+  - Embedding it in a product you sell, and modifying or forking it.
+  - Redistributing it, with these notices intact.
+  - Running it locally as an MCP server, which is what it is for. A host
+    process spawning it on your own machine is use, not a hosted service.
+
+What it does not permit:
+
+  - Offering this software to third parties as a hosted or managed service.
+    A remotely hosted MCP endpoint serving other people is the case this
+    forbids.
+  - Circumventing licence key functionality.
+  - Removing or obscuring these notices.
+
+The Elastic License 2.0 is source-available, not an OSI-approved open source
+licence. It grants a patent licence and ends that licence if you assert a patent
+claim against the software; see the Patents section of LICENSE.
+
+LICENSE governs. Where this summary and LICENSE differ, LICENSE is what applies.
+
+---
+
+This software depends on the following packages, which are distributed under
+their own terms and are not covered by the licence above.
+
+  @modelcontextprotocol/server   MIT   Copyright (c) Anthropic, PBC
+  @modelcontextprotocol/core     MIT   Copyright (c) Anthropic, PBC
+  zod                            MIT   Copyright (c) Colin McDonnell
+  semver                         ISC   See the dependency's LICENSE file.
+
+The MIT License permits this distribution provided the above notices are
+retained. Full licence texts ship with those packages.
+
+@huggingface/transformers is an optional peer dependency. It is never
+distributed with this package; a user who wants semantic ranking installs it
+themselves, under its own Apache-2.0 terms.

package/README.md

@@ -0,0 +1,69 @@
+# 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`.
+
+## Install
+
+```sh
+npm install --save-dev pmcp
+```
+
+Register it with an MCP host:
+
+```json
+{
+  "mcpServers": {
+    "pmcp": { "command": "npx", "args": ["-y", "@modootoday/pmcp"] }
+  }
+}
+```
+
+For Claude Code:
+
+```sh
+claude mcp add pmcp -- npx -y @modootoday/pmcp
+```
+
+## Commands
+
+```sh
+pmcp list
+pmcp available
+pmcp install --all --dry-run
+pmcp install <skill-package> --yes
+pmcp sync --dry-run
+pmcp login
+pmcp whoami
+pmcp logout
+```
+
+`available` matches the provided catalog against actual installed dependency
+versions locally. `install` and `sync` use npm or Bun, pin exact versions, and
+require confirmation before changing the project's manifest and lockfile.
+`--dry-run` does not install packages. `--catalog <file>` uses a saved catalog
+response instead of fetching one. Registry access is handled by your package
+manager; an OAuth login is not an npm registry token.
+
+Run `pmcp --help` or `pmcp <command> --help` for options. With no command,
+`pmcp` serves MCP on stdio. Use `--root <node_modules>` to select a local tree
+and repeat `--scope <prefix>` to restrict local package discovery.
+
+## Package skills
+
+Skills are discovered by filename, including `skills/`, `.agent/skills/`,
+`.claude/skills/`, `.gemini/skills/`, `.codex/skills/`, and `lib/skill/` layouts
+within the discovery depth. A skill needs a frontmatter `description` for search.
+
+`skill_find` accepts a problem description and returns matching skills.
+`skill_call` opens the selected document. Local MCP reading requires no login.
+
+## Runtime and licence
+
+Node.js 22 or later, or Bun 1.3 or later. Default ranking is lexical. The optional
+`index` command requires a separately installed encoder; it is not part of the
+default installation.
+
+Elastic License 2.0. See `LICENSE` and `NOTICE` for terms and dependency notices.
+Documentation: <https://pmcp.build>.

package/SECURITY.md

@@ -0,0 +1,27 @@
+# Security
+
+Please report a vulnerability privately through GitHub's security advisory form:
+
+<https://github.com/modootoday/pmcp/security/advisories/new>
+
+Do not open a public issue for a vulnerability or include credentials, private
+package names, dependency inventories, OAuth tokens, registry tokens, or private
+repository details in a report that other people can read.
+
+## Boundaries
+
+The MCP server reads installed package manifests and `SKILL.md` files locally.
+It must not send dependency inventories or search queries over the network.
+Network access belongs to explicit CLI commands such as catalog retrieval,
+authentication, installation, and synchronization.
+
+Package installation changes a project manifest and lockfile through npm or Bun.
+Inspect the plan with `--dry-run`; non-interactive application requires `--yes`.
+The CLI disables dependency install scripts for skill-package installation and
+checks catalog integrity against registry metadata before applying a plan.
+
+## Supported versions
+
+Security fixes are released on the latest published version. Include the pmcp
+version, runtime version, package manager, operating system, and a minimal
+reproduction that contains no private project data.

package/dist/chunk-UTABV2C4.js

@@ -0,0 +1,33 @@
+import {
+  createSkillServer
+} from "./chunk-WIVQKKE4.js";
+
+// src/stdio.ts
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+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 };
+  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.
+    onerror: (error) => process.stderr.write(`pmcp: ${error.message}
+`)
+  });
+}
+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(",") : []
+  );
+}
+
+export {
+  resolveRoots,
+  serve,
+  main
+};
+//# sourceMappingURL=chunk-UTABV2C4.js.map

package/dist/chunk-WIVQKKE4.js

@@ -0,0 +1,363 @@
+// src/intent.ts
+function normaliseIntent(intent) {
+  return intent.toLowerCase().replaceAll(/[^\p{L}\p{N}\s]/gu, " ").split(/\s+/u).filter(Boolean).join(" ");
+}
+
+// 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
+        });
+      }
+    }
+  }
+  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/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(matches, limit) {
+  return matches.filter((match) => match.score > 0).sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, limit);
+}
+
+// src/server.ts
+import { readFileSync as readFileSync2 } from "fs";
+function createSkillTools(options) {
+  const load = options.loadCatalog ?? readCatalog;
+  let entries = null;
+  const catalog = () => {
+    entries ??= load({ roots: options.roots, scopes: options.scopes });
+    return entries;
+  };
+  return {
+    /** Grouped, and without bodies. The cheap overview and the search's miss path. */
+    catalog() {
+      const byPackage = /* @__PURE__ */ new Map();
+      for (const entry of catalog()) {
+        const list = byPackage.get(entry.package) ?? [];
+        list.push({ name: entry.name, description: entry.description });
+        byPackage.set(entry.package, list);
+      }
+      return {
+        count: catalog().length,
+        packages: [...byPackage.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([pkg, skills]) => ({ package: pkg, skills }))
+      };
+    },
+    /** Ranked names. Returns; never loads a body. */
+    find(intent, limit) {
+      return find({
+        entries: catalog(),
+        intent,
+        limit,
+        embedder: options.embedder,
+        cache: options.cache,
+        vectors: options.vectors
+      });
+    },
+    /** 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(readFileSync2(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 ship, grouped by package, with names and one-line descriptions and no bodies. Use it to see what exists, or when skill_find returns nothing.",
+      inputSchema: z.object({}),
+      annotations: readOnly
+    },
+    async () => asText(tools.catalog())
+  );
+  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()
+      }),
+      annotations: readOnly
+    },
+    async ({ intent, limit }) => asText(await tools.find(intent, limit))
+  );
+  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.1.0" });
+  return registerSkillTools(server, createSkillTools(options));
+}
+
+export {
+  normaliseIntent,
+  SKIPPED_DIRS,
+  MAX_SKILL_DEPTH,
+  readFrontmatter,
+  readBody,
+  readCatalog,
+  withoutBody,
+  displayPath,
+  DEFAULT_FIND_LIMIT,
+  lexicalScore,
+  cosine,
+  find,
+  createSkillTools,
+  SERVER_NAME,
+  registerSkillTools,
+  createSkillServer
+};
+//# sourceMappingURL=chunk-WIVQKKE4.js.map