@modootoday/pmcp 0.7.1 → 0.8.0

package/README.md

@@ -4,8 +4,9 @@ Find and use package skills without loading every document into your agent's con
 `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`.
+from plugin marketplaces (`--marketplace <dir>`), and exposes six MCP tools: `skill_catalog`, `skill_find`,
+`skill_describe`, `skill_call`, `skill_read` and `skill_bundle`, plus every skill file as a
+`skill://` resource and, on request, one prompt per skill.
 
 ## Install
 
@@ -121,7 +122,28 @@ Skills are discovered by filename, including `skills/`, `.agents/skills/`,
 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.
+`skill_call` opens the selected document and lists the reference, script and asset
+files it carries, as text and as resource links. Local MCP reading requires no login.
+
+Files keep their type, as the Agent Skills layout (`references/`, `scripts/`, `assets/`)
+expects: `skill_read` returns text as text, images and audio as image and audio content,
+and other binary files as an embedded resource with its media type; a file whose extension
+names text but whose bytes are not UTF-8 goes out as a blob, so its sha256 stays exact.
+Scripts are returned, never run: running them is the host's job, from a local copy of the
+skill. `skill_bundle` lists every file of a skill as resource links that `resources/read`
+returns, so a host can write the skill into a local skills directory without the bytes
+passing through the model.
+
+`skill_catalog`, `skill_find`, `skill_describe` and `skill_bundle` declare an
+`outputSchema` and return `structuredContent` alongside the same JSON as text.
+Frontmatter is read as YAML (folded and block descriptions, a BOM and CRLF are fine), and
+`metadata` is read for every skill. Loading is lenient, as the client guide asks; what
+breaks the specification is reported, and `pmcp validate [<skill-dir>...]` checks given
+directories or every skill the catalog reaches (name rules and length, description and
+compatibility length, field types, name matching the directory, duplicate names).
+
+`pmcp serve --prompts` also offers one prompt per skill, for hosts that turn prompts into
+commands; the prompt's text is the skill body and its file list, with an optional `task`.
 
 Marketplace plugins also carry commands, agents, hooks and MCP servers.
 Commands are listed as skills. The others are listed under their own kind and
@@ -132,15 +154,24 @@ are left out of `skill_catalog` and `skill_find` unless `kind` asks for them
 ## MCP Skills extension
 
 The server also declares `io.modelcontextprotocol/skills` (SEP-2640): it
-answers `skills/list` and `skills/get`, and serves each file of a conforming
-skill as `skill://pmcp/<package>/<name>/<file>` through `resources/read`, with
-a sha256 digest and size per file. A skill qualifies when its frontmatter
-`name` matches its directory and the Agent Skills naming rules, and it stays
-within 512 files and 16 MiB; the rest remain reachable through the tools.
+answers `skills/list` and `skills/get` (both with `ttlMs` and `cacheScope`), with
+a sha256 digest and size per file. A skill qualifies when its frontmatter passes the
+Agent Skills specification and its `name` matches its directory, and it stays within
+512 files and 16 MiB; the rest remain reachable through the tools.
+
+Every file of every skill the caller may see is a `skill://pmcp/<package>/<name>/<file>`
+resource: `resources/list` lists each skill's `SKILL.md`, `resources/read` returns any file
+(text, or a blob with its media type), and the template completes skill names and paths.
+List-change notifications and subscriptions are not offered: they need a session, and the
+HTTP handler is stateless.
 
 ## Hosting over HTTP
 
-`@modootoday/pmcp/http` serves the same five tools over streamable HTTP for a hosted catalog.
+`@modootoday/pmcp/http` serves the same tools and resources over streamable HTTP for a hosted
+catalog. Tools, resources, the Skills extension and prompts all read the same per-caller,
+tier-filtered catalog, so a file of a skill a caller cannot list cannot be read either. The
+extension's `cacheScope` is `private` there by default (`cacheScope` overrides it), and
+`prompts: true` turns prompts on.
 The host owns identity: `authorize(request)` returns the caller or `undefined` (answered 401),
 and `tiersFor(caller)` decides which tiers that caller sees (default `open` and `free`; skills
 without a tier count as `open`). The catalog is read once; call `reload()` after deploying new

package/dist/{catalog-5v7jrGwP.d.ts → catalog-CS0j6-0U.d.ts}

@@ -48,6 +48,14 @@ interface CatalogOptions {
         path: string;
         reason: string;
     }) => void;
+    /**
+     * Told about a skill that is served but breaks the Agent Skills specification,
+     * or that lost a name collision. Loading stays lenient, as the client guide asks.
+     */
+    readonly onWarning?: (warning: {
+        path: string;
+        reason: string;
+    }) => void;
 }
 /**
  * Directories a walk does not enter. Kept as short as the evidence allows: a
@@ -64,19 +72,11 @@ declare const SKIPPED_DIRS: ReadonlySet<string>;
  */
 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.
+ * Top-level scalar fields of a SKILL.md frontmatter, parsed as YAML, so a folded
+ * `description: >-` arrives as its text rather than as the indicator.
  */
 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.
- */
+/** The body after the frontmatter, or the whole file when there is none. */
 declare function readBody(source: string): string;
 /**
  * Every skill reachable from the given roots, sorted by name.

package/dist/{chunk-IJPOJ6PG.js → chunk-LUBYOET7.js}

@@ -1,6 +1,6 @@
 import {
   createSkillServer
-} from "./chunk-C46YCY2I.js";
+} from "./chunk-ZDV75HZN.js";
 
 // src/stdio.ts
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
@@ -8,10 +8,13 @@ function resolveRoots(argv, cwd) {
   const given = argv.filter((arg) => !arg.startsWith("-"));
   return given.length > 0 ? given : [`${cwd}/node_modules`];
 }
-function serve(catalog) {
+function serve(catalog, serving = {}) {
   const options = {
     ...catalog,
+    ...serving,
     onReject: ({ path, reason }) => process.stderr.write(`pmcp: skipped ${path}: ${reason}
+`),
+    onWarning: ({ path, reason }) => process.stderr.write(`pmcp: warning ${path}: ${reason}
 `)
   };
   serveStdio(() => createSkillServer(options), {
@@ -35,4 +38,4 @@ export {
   serve,
   main
 };
-//# sourceMappingURL=chunk-IJPOJ6PG.js.map
+//# sourceMappingURL=chunk-LUBYOET7.js.map

package/dist/{chunk-GNJSZCRH.js → chunk-M6LBYJDS.js}

@@ -1,3 +1,9 @@
+import {
+  frontmatterObject,
+  readCatalog,
+  specProblems
+} from "./chunk-ZDV75HZN.js";
+
 // src/config.ts
 import { existsSync, readFileSync } from "fs";
 import { dirname, join, resolve } from "path";
@@ -1086,6 +1092,33 @@ function readSpec(config) {
   return { root: config.dir, tools, skills, agents, packageRules, mcp };
 }
 
+// src/validate.ts
+import { existsSync as existsSync6, readFileSync as readFileSync5, statSync } from "fs";
+import { basename, join as join6, resolve as resolve2 } from "path";
+function validateSkillDir(dir) {
+  const root = resolve2(dir);
+  const skillMd = basename(root) === "SKILL.md" ? root : join6(root, "SKILL.md");
+  if (!existsSync6(skillMd) || !statSync(skillMd).isFile()) {
+    return [{ path: root, reason: "no SKILL.md", level: "error" }];
+  }
+  const front = frontmatterObject(readFileSync5(skillMd, "utf8"));
+  const directory = basename(skillMd === root ? join6(root, "..") : root);
+  return specProblems(front, directory).map((reason) => ({
+    path: skillMd,
+    reason,
+    level: "error"
+  }));
+}
+function validateCatalog(options) {
+  const findings = [];
+  readCatalog({
+    ...options,
+    onReject: (r) => findings.push({ ...r, level: "error" }),
+    onWarning: (w) => findings.push({ ...w, level: "warning" })
+  });
+  return findings;
+}
+
 export {
   CONFIG_FILE,
   ConfigError,
@@ -1102,6 +1135,8 @@ export {
   spawnRunner,
   doctor,
   TOOLS,
-  readSpec
+  readSpec,
+  validateSkillDir,
+  validateCatalog
 };
-//# sourceMappingURL=chunk-GNJSZCRH.js.map
+//# sourceMappingURL=chunk-M6LBYJDS.js.map

package/dist/{chunk-KP3TQ3QY.js → chunk-OPDVUHTK.js}

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

package/dist/{chunk-VBLAH6J2.js → chunk-WSTCBVXW.js}

@@ -1,6 +1,6 @@
 import {
   openDatabase
-} from "./chunk-KP3TQ3QY.js";
+} from "./chunk-OPDVUHTK.js";
 
 // src/embed.ts
 var DEFAULT_MODEL_ID = "Xenova/multilingual-e5-small";
@@ -157,4 +157,4 @@ export {
   encodeEntries,
   openEntryVectors
 };
-//# sourceMappingURL=chunk-VBLAH6J2.js.map
+//# sourceMappingURL=chunk-WSTCBVXW.js.map