@modootoday/pmcp 0.7.0 → 0.8.0

package/dist/cli.js

@@ -2,7 +2,7 @@
 import {
   loadEmbedder,
   openEntryVectors
-} from "./chunk-NI2OLZPA.js";
+} from "./chunk-WSTCBVXW.js";
 import {
   ConfigError,
   ProjectError,
@@ -14,16 +14,18 @@ import {
   readSpec,
   renderFrontmatter,
   spawnRunner,
-  splitFrontmatter
-} from "./chunk-GNJSZCRH.js";
-import "./chunk-ZLELYZHL.js";
+  splitFrontmatter,
+  validateCatalog,
+  validateSkillDir
+} from "./chunk-M6LBYJDS.js";
+import "./chunk-OPDVUHTK.js";
 import {
   serve
-} from "./chunk-POJOFL4L.js";
+} from "./chunk-LUBYOET7.js";
 import {
   kindOf,
   readCatalog
-} from "./chunk-QHFORYIN.js";
+} from "./chunk-ZDV75HZN.js";
 
 // src/cli/command.ts
 var ArgumentError = class extends Error {
@@ -448,10 +450,19 @@ 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>] [--marketplace <dir>] [--package <dir>] [--workspace <dir>] [--config <file> | --no-config]",
-  options: [...CATALOG_OPTIONS],
+  usage: "pmcp serve [--root <dir>] [--scope <prefix>] [--marketplace <dir>] [--package <dir>] [--workspace <dir>] [--config <file> | --no-config] [--prompts]",
+  options: [
+    ...CATALOG_OPTIONS,
+    {
+      name: "prompts",
+      describe: "Also offer one prompt per skill, for hosts that turn prompts into commands.",
+      boolean: true
+    }
+  ],
   run(context) {
-    serve(catalogOptionsFrom(context));
+    serve(catalogOptionsFrom(context), {
+      prompts: context.args.flags.has("prompts")
+    });
     return 0;
   }
 };
@@ -2249,6 +2260,33 @@ var doctorCommand = {
   }
 };
 
+// src/commands/validate.ts
+var validateCommand = {
+  name: "validate",
+  describe: "Check skills against the Agent Skills specification: given directories, or every skill the catalog reaches",
+  usage: "pmcp validate [<skill-dir>...] [--root <dir>] [--marketplace <dir>] [--package <dir>] [--workspace <dir>] [--config <file> | --no-config] [--json]",
+  options: [
+    ...CATALOG_OPTIONS,
+    { name: "json", describe: "Emit JSON rather than a table.", boolean: true }
+  ],
+  run(context) {
+    const dirs = context.args.positional;
+    const findings = dirs.length > 0 ? dirs.flatMap(validateSkillDir) : validateCatalog(catalogOptionsFrom(context));
+    const errors = findings.filter((f) => f.level === "error").length;
+    if (context.args.flags.has("json")) {
+      context.ui.data(`${JSON.stringify({ findings }, null, 2)}
+`);
+      return errors > 0 ? 1 : 0;
+    }
+    for (const finding of findings) {
+      const report = finding.level === "error" ? context.ui.error : context.ui.warn;
+      report.call(context.ui, finding.reason, finding.path);
+    }
+    if (findings.length === 0) context.ui.success("every skill is valid");
+    return errors > 0 ? 1 : 0;
+  }
+};
+
 // src/commands/index.ts
 var COMMANDS = [
   serveCommand,
@@ -2262,7 +2300,8 @@ var COMMANDS = [
   installCommand,
   syncCommand,
   projectCommand,
-  doctorCommand
+  doctorCommand,
+  validateCommand
 ];
 var PLANNED = [];
 var GLOBAL = /* @__PURE__ */ new Set(["-q", "--quiet", "--no-color", "--color"]);
@@ -2308,7 +2347,7 @@ function dispatch(argv, options = {}) {
   }
   return run(command, rest, { ui, env, cwd });
 }
-var VERSION = "0.7.0";
+var VERSION = "0.8.0";
 async function run(command, argv, context) {
   try {
     return await command.run({

package/dist/http.d.ts

@@ -1,5 +1,6 @@
-import { S as SkillEntry } from './catalog-5v7jrGwP.js';
-import { E as Embedder, S as SkillServerOptions } from './server-wpYiAJ2n.js';
+import { S as SkillEntry } from './catalog-CS0j6-0U.js';
+import { E as Embedder, S as SkillServerOptions } from './server-CLyCpwZb.js';
+import 'zod';
 
 /**
  * The optional encoder and the store for the vectors it produces.
@@ -67,6 +68,13 @@ interface SkillHttpOptions extends SkillServerOptions {
     readonly challenge?: string;
     /** Encode the catalog at start so find ranks by meaning across languages. */
     readonly semantic?: SkillHttpSemanticOptions;
+    /** One prompt per skill. Off by default: the list grows with the catalog. */
+    readonly prompts?: boolean;
+    /**
+     * Cache scope the Skills extension declares. The catalog is filtered per caller
+     * here, so "private" unless the host knows every caller sees the same list.
+     */
+    readonly cacheScope?: "public" | "private";
 }
 declare const DEFAULT_TIERS: readonly string[];
 declare function visibleTo(entries: readonly SkillEntry[], tiers: readonly string[]): SkillEntry[];

package/dist/http.js

@@ -2,12 +2,12 @@ import {
   DEFAULT_MODEL_ID,
   encodeEntries,
   loadEmbedder
-} from "./chunk-NI2OLZPA.js";
-import "./chunk-ZLELYZHL.js";
+} from "./chunk-WSTCBVXW.js";
+import "./chunk-OPDVUHTK.js";
 import {
   createSkillServer,
   readCatalog
-} from "./chunk-QHFORYIN.js";
+} from "./chunk-ZDV75HZN.js";
 
 // src/http.ts
 import {
@@ -50,7 +50,8 @@ function createSkillHttpHandler(options) {
       () => createSkillServer({
         ...options,
         ...embedder && vectors ? { embedder, vectors } : {},
-        loadCatalog: () => visibleTo(all, tiers)
+        loadCatalog: () => visibleTo(all, tiers),
+        skillsExtension: { cacheScope: options.cacheScope ?? "private" }
       })
     );
     handlers.set(key, handler);

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import { I as IntentCache, S as SkillServerOptions, a as SkillTools } from './server-wpYiAJ2n.js';
-export { C as CATALOG_PAGE_MAX, b as CATALOG_PAGE_SIZE, c as CallResponse, d as CatalogItem, e as CatalogResponse, D as DEFAULT_FIND_LIMIT, f as DESCRIBE_FILE_LIMIT, E as Embedder, F as FindOptions, g as FindResult, h as IntentCacheStats, K as KindFilter, M as Match, R as READ_BUDGET_BYTES, i as Ranking, j as ReadResult, k as SkillFilters, l as cosine, m as createSkillTools, n as find, o as lexicalScore, p as normaliseIntent } from './server-wpYiAJ2n.js';
-import { S as SkillEntry } from './catalog-5v7jrGwP.js';
-export { a as ASSET_KINDS, A as AssetKind, C as CatalogOptions, M as MAX_SKILL_DEPTH, b as SKIPPED_DIRS, d as displayPath, k as kindOf, r as readBody, c as readCatalog, e as readFrontmatter, w as withoutBody } from './catalog-5v7jrGwP.js';
+import { I as IntentCache, S as SkillServerOptions, a as SkillTools } from './server-CLyCpwZb.js';
+export { B as BundleFile, C as CATALOG_PAGE_MAX, b as CATALOG_PAGE_SIZE, c as CallResponse, d as CatalogItem, e as CatalogResponse, f as Classified, D as DEFAULT_FIND_LIMIT, g as DESCRIBE_FILE_LIMIT, E as Embedder, F as FileKind, h as FindOptions, i as FindResult, j as IntentCacheStats, K as KindFilter, M as Match, R as READ_BUDGET_BYTES, k as Ranking, l as ReadResult, m as SkillBundle, n as SkillFile, o as SkillFileContent, p as SkillFileListing, q as SkillFilters, r as bundleResponseSchema, s as bundleSkill, t as catalogResponseSchema, u as classify, v as cosine, w as createSkillTools, x as describeResponseSchema, y as find, z as findResultSchema, A as isUtf8Text, G as lexicalScore, H as listSkillFiles, J as mimeOf, L as normaliseIntent, N as readSkillFile } from './server-CLyCpwZb.js';
+import { S as SkillEntry, C as CatalogOptions } from './catalog-CS0j6-0U.js';
+export { a as ASSET_KINDS, A as AssetKind, M as MAX_SKILL_DEPTH, b as SKIPPED_DIRS, d as displayPath, k as kindOf, r as readBody, c as readCatalog, e as readFrontmatter, w as withoutBody } from './catalog-CS0j6-0U.js';
 import { McpServer } from '@modelcontextprotocol/server';
+import 'zod';
 
 /**
  * Query vectors, kept on disk between sessions.
@@ -36,6 +37,25 @@ declare const DEFAULT_INTENT_CACHE_LIMIT = 4096;
  */
 declare function openIntentCache(options: IntentCacheOptions): Promise<IntentCache | null>;
 
+/**
+ * SKILL.md frontmatter, read as YAML the way a host reads it, and checked against
+ * the Agent Skills specification (https://agentskills.io/specification).
+ */
+type MetadataValue = string | readonly string[];
+/**
+ * Parsed frontmatter. A value with an unquoted ": " is a common authoring slip
+ * the client guide says to recover from by quoting it, so that is retried once.
+ */
+declare function frontmatterObject(source: string): Record<string, unknown> | null;
+declare const NAME_MAX = 64;
+declare const DESCRIPTION_MAX = 1024;
+declare const COMPATIBILITY_MAX = 500;
+/**
+ * What the specification requires of one SKILL.md, as messages; empty when valid.
+ * directory is the name of the folder holding it.
+ */
+declare function specProblems(front: Record<string, unknown> | null, directory: string): string[];
+
 /**
  * Assets laid out as an agent plugin marketplace: a directory holding
  * `.claude-plugin/marketplace.json`, whose plugins keep skills, commands,
@@ -43,16 +63,12 @@ declare function openIntentCache(options: IntentCacheOptions): Promise<IntentCac
  * package.json is involved, which is why the node_modules walk never saw them.
  */
 
-type MetadataValue = string | readonly string[];
 /** Why an asset 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.
- */
+/** The `metadata:` map of a frontmatter, one level deep: strings and string lists. */
 declare function readMetadata(source: string): Record<string, MetadataValue>;
 /** The raw frontmatter text between the fences, for skill_describe. */
 declare function readFrontmatterText(source: string): string;
@@ -200,7 +216,7 @@ interface RunResult {
 }
 type Runner = (command: string, args: readonly string[], cwd: string) => RunResult;
 type Status = "ok" | "fail" | "skip";
-interface Finding {
+interface Finding$1 {
     readonly tool: Tool | "project";
     readonly check: string;
     readonly status: Status;
@@ -211,7 +227,7 @@ interface DoctorOptions {
     readonly home: string;
     readonly only?: ReadonlySet<Tool>;
 }
-declare function doctor(spec: ProjectSpec, options: DoctorOptions): Finding[];
+declare function doctor(spec: ProjectSpec, options: DoctorOptions): Finding$1[];
 
 /**
  * Links each package's path-scoped rule file into .claude/rules/<dir>/. One level
@@ -225,60 +241,119 @@ declare class ProjectError extends Error {
 declare function deriveName(dir: string, strip: readonly string[]): string;
 
 /**
- * The five tools, spoken over MCP.
+ * One catalog skill as the Skills extension (SEP-2640) describes it: frontmatter
+ * plus a complete manifest of its files with sha256 digests and sizes.
+ */
+
+interface SkillResource {
+    readonly uri: string;
+    readonly digest: string;
+    readonly size: number;
+}
+interface SkillExtensionEntry {
+    readonly uri: string;
+    readonly frontmatter: Readonly<Record<string, unknown>>;
+    readonly resources: readonly SkillResource[];
+}
+/**
+ * The extension's entry, or null when the skill cannot be served under SEP-2640:
+ * not a directory with SKILL.md, frontmatter that breaks the Agent Skills
+ * specification, a name unlike its path, or over the per-skill limits. Such a
+ * skill stays reachable through the skill_* tools.
+ */
+declare function extensionEntry(entry: SkillEntry): SkillExtensionEntry | null;
+
+/**
+ * The Skills extension's methods, skills/list and skills/get. Their files are
+ * served by the skill:// resources (resources.ts), which every surface shares.
+ */
+
+declare const SKILLS_EXTENSION = "io.modelcontextprotocol/skills";
+interface SkillsExtensionOptions {
+    /**
+     * "public" when every caller sees the same catalog; "private" when the list is
+     * filtered per caller, as it is behind authorization.
+     */
+    readonly cacheScope?: "public" | "private";
+}
+/** Declares the extension and its methods. Must run before the server connects. */
+declare function registerSkillsExtension(server: McpServer, skills: () => readonly SkillEntry[], options?: SkillsExtensionOptions): void;
+
+/**
+ * skill:// URIs for skill files. The authority names this server's namespace and
+ * resolves to nothing; the path is the catalog name, then the file inside it.
+ */
+
+declare const skillFileUri: (entry: Pick<SkillEntry, "name">, file?: string) => string;
+/**
+ * The catalog entry and relative file a URI names, matched against the entries
+ * the caller may see. Names contain slashes, so the longest matching name wins.
+ */
+declare function resolveSkillFileUri(uri: string, entries: readonly SkillEntry[]): {
+    entry: SkillEntry;
+    file: string;
+} | null;
+
+/**
+ * The catalog, spoken over MCP: the skill_* tools, skill:// resources, the
+ * Skills extension and, when asked for, one prompt per skill.
  *
- * 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
- * operations from a hook or a script uses the tools directly and never speaks
- * a protocol.
+ * Thin on purpose: every decision is in createSkillTools and the modules under
+ * tools/ and files/; this file only composes them on one server.
  */
 
 /** Reported to the host on connect. */
 declare const SERVER_NAME = "pmcp";
+declare const SERVER_VERSION = "0.8.0";
 /**
- * Registers the five tools on a server.
+ * Registers the skill_* 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;
+interface SkillMcpOptions extends SkillServerOptions {
+    /** One prompt per skill, for hosts that offer prompts as commands. Off by default. */
+    readonly prompts?: boolean;
+    readonly skillsExtension?: SkillsExtensionOptions;
+}
 /**
- * A server with the five tools and the Skills extension registered.
+ * A server with everything 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;
+declare function createSkillServer(options: SkillMcpOptions): McpServer;
 
-/**
- * The MCP Skills extension (SEP-2640): `skills/list`, `skills/get` and the
- * skill files as `skill://pmcp/<name>/<file>` resources, so a host that speaks
- * the extension loads skills natively instead of through the skill_* tools.
- */
+/** Checks skill directories against the Agent Skills specification. */
 
-declare const SKILLS_EXTENSION = "io.modelcontextprotocol/skills";
-interface SkillResource {
-    readonly uri: string;
-    readonly digest: string;
-    readonly size: number;
-}
-interface SkillExtensionEntry {
-    readonly uri: string;
-    readonly frontmatter: Readonly<Record<string, unknown>>;
-    readonly resources: readonly SkillResource[];
+interface Finding {
+    readonly path: string;
+    readonly reason: string;
+    /** error: the skill is left out or breaks a MUST; warning: served anyway. */
+    readonly level: "error" | "warning";
 }
-declare const skillUri: (entry: Pick<SkillEntry, "name">, file?: string) => string;
+/** One skill directory, or the SKILL.md inside it. */
+declare function validateSkillDir(dir: string): Finding[];
+/** Every skill the catalog options reach, with what loading reported. */
+declare function validateCatalog(options: CatalogOptions): Finding[];
+
 /**
- * The extension's entry for one catalog skill, or null when the skill cannot
- * be served under SEP-2640: not a directory with SKILL.md, a frontmatter name
- * that is missing, invalid or unlike its path, or over the per-skill limits.
- * Such a skill stays reachable through the skill_* tools.
+ * skill:// resources: every file of every skill the caller may see. The tools,
+ * the Skills extension and resource links all resolve here, over the same
+ * caller-filtered catalog, so nothing a caller cannot list can be read.
  */
-declare function extensionEntry(entry: SkillEntry): SkillExtensionEntry | null;
+
+declare function registerSkillResources(server: McpServer, skills: () => readonly SkillEntry[]): void;
+
 /**
- * Declares the extension and its methods on a server, over the skills the
- * catalog function returns. Must run before the server connects.
+ * One prompt per skill, for hosts that offer prompts as commands: the Agent
+ * Skills "user-explicit activation" path. Off unless the host asks for it,
+ * because the list grows with the catalog.
  */
-declare function registerSkillsExtension(server: McpServer, skills: () => readonly SkillEntry[]): void;
 
-export { CONFIG_FILE, type CatalogSection, ConfigError, DEFAULT_INTENT_CACHE_LIMIT, type Finding, IntentCache, type IntentCacheOptions, LOCK_FILE, type McpServerSpec, type MetadataValue, type Output, type PackageRulesSpec, type ProjectConfig, ProjectError, type ProjectResult, type ProjectSpec, type Rejection, type Runner, SERVER_NAME, SKILLS_EXTENSION, SkillEntry, type SkillExtensionEntry, type SkillResource, SkillServerOptions, SkillTools, TOOLS, type Tool, assetRoot, createSkillServer, deadGlobs, deriveName, doctor, extensionEntry, findConfig, openIntentCache, plan, project, readConfig, readFrontmatterText, readMarketplace, readMetadata, readSpec, registerSkillTools, registerSkillsExtension, skillUri };
+/** Prompt names travel into host command names, so they stay to a plain set. */
+declare const promptName: (entry: Pick<SkillEntry, "name">) => string;
+declare function registerSkillPrompts(server: McpServer, tools: SkillTools): void;
+
+export { COMPATIBILITY_MAX, CONFIG_FILE, CatalogOptions, type CatalogSection, ConfigError, DEFAULT_INTENT_CACHE_LIMIT, DESCRIPTION_MAX, type Finding$1 as Finding, IntentCache, type IntentCacheOptions, LOCK_FILE, type McpServerSpec, type MetadataValue, NAME_MAX, type Output, type PackageRulesSpec, type ProjectConfig, ProjectError, type ProjectResult, type ProjectSpec, type Rejection, type Runner, SERVER_NAME, SERVER_VERSION, SKILLS_EXTENSION, SkillEntry, type SkillExtensionEntry, type SkillMcpOptions, type SkillResource, SkillServerOptions, SkillTools, TOOLS, type Tool, type Finding as ValidationFinding, assetRoot, createSkillServer, deadGlobs, deriveName, doctor, extensionEntry, findConfig, openIntentCache, frontmatterObject as parseSkillFrontmatter, plan, project, promptName, readConfig, readFrontmatterText, readMarketplace, readMetadata, readSpec, registerSkillPrompts, registerSkillResources, registerSkillTools, registerSkillsExtension, resolveSkillFileUri, skillFileUri, skillFileUri as skillUri, specProblems, validateCatalog, validateSkillDir };

package/dist/index.js

@@ -11,78 +11,115 @@ import {
   plan,
   project,
   readConfig,
-  readSpec
-} from "./chunk-GNJSZCRH.js";
+  readSpec,
+  validateCatalog,
+  validateSkillDir
+} from "./chunk-M6LBYJDS.js";
 import {
   DEFAULT_INTENT_CACHE_LIMIT,
   openIntentCache
-} from "./chunk-ZLELYZHL.js";
+} from "./chunk-OPDVUHTK.js";
 import {
   ASSET_KINDS,
   CATALOG_PAGE_MAX,
   CATALOG_PAGE_SIZE,
+  COMPATIBILITY_MAX,
   DEFAULT_FIND_LIMIT,
   DESCRIBE_FILE_LIMIT,
+  DESCRIPTION_MAX,
   MAX_SKILL_DEPTH,
+  NAME_MAX,
   READ_BUDGET_BYTES,
   SERVER_NAME,
+  SERVER_VERSION,
   SKILLS_EXTENSION,
   SKIPPED_DIRS,
   assetRoot,
+  bundleResponseSchema,
+  bundleSkill,
+  catalogResponseSchema,
+  classify,
   cosine,
   createSkillServer,
   createSkillTools,
+  describeResponseSchema,
   displayPath,
   extensionEntry,
   find,
+  findResultSchema,
+  frontmatterObject,
+  isUtf8Text,
   kindOf,
   lexicalScore,
+  listSkillFiles,
+  mimeOf,
   normaliseIntent,
+  promptName,
   readBody,
   readCatalog,
   readFrontmatter,
   readFrontmatterText,
   readMarketplace,
   readMetadata,
+  readSkillFile,
+  registerSkillPrompts,
+  registerSkillResources,
   registerSkillTools,
   registerSkillsExtension,
-  skillUri,
+  resolveSkillFileUri,
+  skillFileUri,
+  specProblems,
   withoutBody
-} from "./chunk-QHFORYIN.js";
+} from "./chunk-ZDV75HZN.js";
 export {
   ASSET_KINDS,
   CATALOG_PAGE_MAX,
   CATALOG_PAGE_SIZE,
+  COMPATIBILITY_MAX,
   CONFIG_FILE,
   ConfigError,
   DEFAULT_FIND_LIMIT,
   DEFAULT_INTENT_CACHE_LIMIT,
   DESCRIBE_FILE_LIMIT,
+  DESCRIPTION_MAX,
   LOCK_FILE,
   MAX_SKILL_DEPTH,
+  NAME_MAX,
   ProjectError,
   READ_BUDGET_BYTES,
   SERVER_NAME,
+  SERVER_VERSION,
   SKILLS_EXTENSION,
   SKIPPED_DIRS,
   TOOLS,
   assetRoot,
+  bundleResponseSchema,
+  bundleSkill,
+  catalogResponseSchema,
+  classify,
   cosine,
   createSkillServer,
   createSkillTools,
   deadGlobs,
   deriveName,
+  describeResponseSchema,
   displayPath,
   doctor,
   extensionEntry,
   find,
   findConfig,
+  findResultSchema,
+  isUtf8Text,
   kindOf,
   lexicalScore,
+  listSkillFiles,
+  mimeOf,
   normaliseIntent,
   openIntentCache,
+  frontmatterObject as parseSkillFrontmatter,
   plan,
   project,
+  promptName,
   readBody,
   readCatalog,
   readConfig,
@@ -90,10 +127,18 @@ export {
   readFrontmatterText,
   readMarketplace,
   readMetadata,
+  readSkillFile,
   readSpec,
+  registerSkillPrompts,
+  registerSkillResources,
   registerSkillTools,
   registerSkillsExtension,
-  skillUri,
+  resolveSkillFileUri,
+  skillFileUri,
+  skillFileUri as skillUri,
+  specProblems,
+  validateCatalog,
+  validateSkillDir,
   withoutBody
 };
 //# sourceMappingURL=index.js.map