@modootoday/pmcp 0.8.2 → 0.9.0

package/README.md

@@ -142,6 +142,22 @@ breaks the specification is reported, and `pmcp validate [<skill-dir>...]` check
 directories or every skill the catalog reaches (name rules and length, description and
 compatibility length, field types, name matching the directory, duplicate names).
 
+`metadata` keeps strings, string lists and maps of those one level down, so
+`requires: {mcp, bin, env, capabilities, gpu-gb}` reaches `skill_describe`; deeper
+nesting is dropped.
+
+Since 0.9.0 a skill can list `metadata.verified-runtimes`, a list drawn from `claude-code`,
+`codex-cli`, `gemini-cli`, `grok-cli` and `antigravity`, meaning its effect was verified on
+that runtime. `skill_find` and `skill_catalog` items carry `verifiedRuntimes` (omitted when
+empty) and accept `runtime` and `verifiedOnly`. `runtime` never removes a skill: it marks
+each item `verified` and lists verified ones first (within a package group in
+`skill_catalog`). `verifiedOnly` drops the rest, keeping those verified on `runtime`, or on
+any runtime when none is given. Without `runtime` the answer is ordered exactly as before.
+A server can opt in with `rankByClientRuntime: true`: then, when `runtime` is not passed and
+the MCP client's name is recognised (`claude-code`, `codex`, `gemini`, `grok`,
+`antigravity`), that runtime is used for the ordering only, never for filtering.
+`skill_find` answers with `runtime`, the one the ordering used, or `null`.
+
 `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`.
 

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

@@ -1,3 +1,26 @@
+/**
+ * SKILL.md frontmatter, read as YAML the way a host reads it, and checked against
+ * the Agent Skills specification (https://agentskills.io/specification).
+ */
+type MetadataLeaf = string | readonly string[];
+/** A metadata value: a leaf, or a map of leaves one level below the metadata key. */
+type MetadataValue = MetadataLeaf | {
+    readonly [key: string]: MetadataLeaf;
+};
+/**
+ * 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[];
+
 /**
  * The skills the installed packages brought with them.
  *
@@ -5,6 +28,7 @@
  * 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;
@@ -16,8 +40,8 @@ interface SkillEntry {
     readonly path: string;
     /** open, free or paid. Set for marketplace skills, absent for packages. */
     readonly tier?: string;
-    /** The frontmatter `metadata:` block, one level deep. */
-    readonly metadata?: Readonly<Record<string, string | readonly string[]>>;
+    /** The frontmatter `metadata:` block; maps such as `requires` are kept one level down. */
+    readonly metadata?: Readonly<Record<string, MetadataValue>>;
     /** Extra search terms. Ranked with the description, never used as triggers. */
     readonly keywords?: readonly string[];
     /** What the entry is. Absent means a skill. */
@@ -94,4 +118,4 @@ declare function withoutBody({ path, ...rest }: SkillEntry): Omit<SkillEntry, "p
 /** Path relative to a root, for a message a reader can act on. */
 declare function displayPath(root: string, entry: SkillEntry): string;
 
-export { type AssetKind as A, type CatalogOptions as C, MAX_SKILL_DEPTH as M, type SkillEntry as S, ASSET_KINDS as a, SKIPPED_DIRS as b, readCatalog as c, displayPath as d, readFrontmatter as e, kindOf as k, readBody as r, withoutBody as w };
+export { type AssetKind as A, type CatalogOptions as C, DESCRIPTION_MAX as D, type MetadataValue as M, NAME_MAX as N, type SkillEntry as S, ASSET_KINDS as a, COMPATIBILITY_MAX as b, MAX_SKILL_DEPTH as c, type MetadataLeaf as d, SKIPPED_DIRS as e, displayPath as f, frontmatterObject as g, readCatalog as h, readFrontmatter as i, kindOf as k, readBody as r, specProblems as s, withoutBody as w };

package/dist/{chunk-IRQTGYHA.js → chunk-AKPSLZRJ.js}

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

package/dist/{chunk-O2P5AIHX.js → chunk-PWEAKJZ3.js}

@@ -2,7 +2,7 @@ import {
   frontmatterObject,
   readCatalog,
   specProblems
-} from "./chunk-UGRHZHHC.js";
+} from "./chunk-PXNRZXL6.js";
 
 // src/config.ts
 import { existsSync, readFileSync } from "fs";
@@ -1139,4 +1139,4 @@ export {
   validateSkillDir,
   validateCatalog
 };
-//# sourceMappingURL=chunk-O2P5AIHX.js.map
+//# sourceMappingURL=chunk-PWEAKJZ3.js.map

package/dist/{chunk-UGRHZHHC.js → chunk-PXNRZXL6.js}

@@ -47,15 +47,31 @@ function stringFields(front) {
   }
   return out;
 }
+function leafOf(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  if (Array.isArray(value))
+    return value.filter((v) => typeof v === "string");
+  return void 0;
+}
 function metadataOf(front) {
   const out = {};
   const meta = asObject(front?.["metadata"]);
   for (const [key, value] of Object.entries(meta ?? {})) {
-    if (typeof value === "string") out[key] = value;
-    else if (typeof value === "number" || typeof value === "boolean")
-      out[key] = String(value);
-    else if (Array.isArray(value))
-      out[key] = value.filter((v) => typeof v === "string");
+    const leaf = leafOf(value);
+    if (leaf !== void 0) {
+      out[key] = leaf;
+      continue;
+    }
+    const nested = asObject(value);
+    if (nested === null) continue;
+    const map = {};
+    for (const [inner, innerValue] of Object.entries(nested)) {
+      const innerLeaf = leafOf(innerValue);
+      if (innerLeaf !== void 0) map[inner] = innerLeaf;
+    }
+    if (Object.keys(map).length > 0) out[key] = map;
   }
   return out;
 }
@@ -377,7 +393,8 @@ function readFrontmatterText(source) {
 var asString = (value) => typeof value === "string" ? value : void 0;
 var asList = (value) => {
   if (value === void 0) return [];
-  return typeof value === "string" ? [value] : value;
+  if (typeof value === "string") return [value];
+  return Array.isArray(value) ? value : [];
 };
 function readJson(path) {
   try {
@@ -1018,6 +1035,44 @@ function bundleSkill(entry) {
   };
 }
 
+// src/runtime.ts
+import { CLIENT_INFO_META_KEY } from "@modelcontextprotocol/server";
+var RUNTIMES = [
+  "claude-code",
+  "codex-cli",
+  "gemini-cli",
+  "grok-cli",
+  "antigravity"
+];
+var VERIFIED_RUNTIMES_KEY = "verified-runtimes";
+var isRuntime = (value) => RUNTIMES.includes(value);
+function verifiedRuntimesOf(metadata) {
+  const raw = metadata?.[VERIFIED_RUNTIMES_KEY];
+  if (raw === void 0) return [];
+  const words = typeof raw === "string" ? raw.split(/[\s,]+/u) : Array.isArray(raw) ? raw.map((word) => String(word).trim()) : [];
+  return [...new Set(words.filter(isRuntime))];
+}
+var CLIENT_PATTERNS = [
+  [/claude[-_ ]?code/u, "claude-code"],
+  [/codex/u, "codex-cli"],
+  [/gemini/u, "gemini-cli"],
+  [/grok/u, "grok-cli"],
+  [/antigravity/u, "antigravity"]
+];
+function runtimeOfClient(name) {
+  if (!name) return null;
+  const lower = name.toLowerCase();
+  for (const [pattern, runtime] of CLIENT_PATTERNS)
+    if (pattern.test(lower)) return runtime;
+  return null;
+}
+function detectRuntime(server, ctx) {
+  const envelope = ctx?.mcpReq?.envelope;
+  const fromEnvelope = envelope?.[CLIENT_INFO_META_KEY]?.name;
+  if (typeof fromEnvelope === "string") return runtimeOfClient(fromEnvelope);
+  return runtimeOfClient(server.server?.getClientVersion?.()?.name);
+}
+
 // src/server.ts
 import { readFileSync as readFileSync6 } from "fs";
 var DESCRIBE_FILE_LIMIT = FILE_LIST_LIMIT;
@@ -1041,14 +1096,33 @@ function matches(entry, filters) {
     return false;
   if (filters.medium !== void 0 && field("medium") !== filters.medium)
     return false;
+  if (filters.verifiedOnly) {
+    const verified = verifiedRuntimesOf(entry.metadata);
+    if (filters.runtime === void 0) return verified.length > 0;
+    return verified.includes(filters.runtime);
+  }
   return true;
 }
-function catalogItem(entry) {
+function verification(entry, runtime) {
+  const verifiedRuntimes = verifiedRuntimesOf(entry?.metadata);
+  return {
+    ...verifiedRuntimes.length > 0 ? { verifiedRuntimes } : {},
+    ...runtime === null ? {} : { verified: verifiedRuntimes.includes(runtime) }
+  };
+}
+function verifiedFirst(items) {
+  return [
+    ...items.filter((item) => item.verified === true),
+    ...items.filter((item) => item.verified !== true)
+  ];
+}
+function catalogItem(entry, runtime) {
   return {
     name: entry.name,
     description: entry.description,
     ...entry.tier === void 0 ? {} : { tier: entry.tier },
-    ...kindOf(entry) === "skill" ? {} : { kind: kindOf(entry) }
+    ...kindOf(entry) === "skill" ? {} : { kind: kindOf(entry) },
+    ...verification(entry, runtime)
   };
 }
 function createSkillTools(options) {
@@ -1073,19 +1147,27 @@ function createSkillTools(options) {
      * path. Paged by package so a large catalog never arrives in one answer.
      */
     catalog(request = {}) {
+      const client = options.rankByClientRuntime ? request.clientRuntime : null;
+      const runtime = request.runtime ?? client ?? null;
       const byPackage = /* @__PURE__ */ new Map();
       let count = 0;
       for (const entry of catalog()) {
-        if (!matches(entry, { tier: request.tier, kind: request.kind }))
+        if (!matches(entry, {
+          tier: request.tier,
+          kind: request.kind,
+          runtime: request.runtime,
+          verifiedOnly: request.verifiedOnly
+        }))
           continue;
         count += 1;
         const list = byPackage.get(entry.package) ?? [];
-        list.push(catalogItem(entry));
+        list.push(catalogItem(entry, runtime));
         byPackage.set(entry.package, list);
       }
-      const groups = [...byPackage.entries()].sort(
-        ([a], [b]) => a.localeCompare(b)
-      );
+      const groups = [...byPackage.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([pkg, skills]) => [
+        pkg,
+        runtime === null ? skills : verifiedFirst(skills)
+      ]);
       const size = Math.min(
         Math.max(request.pageSize ?? CATALOG_PAGE_SIZE, 1),
         CATALOG_PAGE_MAX
@@ -1101,7 +1183,9 @@ function createSkillTools(options) {
       };
     },
     /** Ranked names. Returns; never loads a body. */
-    find(intent, limit, filters) {
+    find(intent, limit, filters, clientRuntime) {
+      const client = options.rankByClientRuntime ? clientRuntime : null;
+      const runtime = filters?.runtime ?? client ?? null;
       const scoped = catalog().filter((entry) => matches(entry, filters)).map(
         (entry) => entry.keywords && entry.keywords.length > 0 ? {
           ...entry,
@@ -1111,17 +1195,26 @@ function createSkillTools(options) {
       return find({
         entries: scoped,
         intent,
-        limit,
+        limit: runtime === null ? limit : scoped.length,
         embedder: options.embedder,
         cache: options.cache,
         vectors: options.vectors
-      }).then((result) => ({
-        ...result,
-        matches: result.matches.map((match) => ({
-          ...match,
-          description: catalog().find((entry) => entry.name === match.name)?.description ?? match.description
-        }))
-      }));
+      }).then((result) => {
+        const marked = result.matches.map((match) => {
+          const entry = byName(match.name) ?? void 0;
+          return {
+            ...match,
+            description: entry?.description ?? match.description,
+            ...verification(entry, runtime)
+          };
+        });
+        const ordered = runtime === null ? marked : verifiedFirst(marked);
+        return {
+          ...result,
+          runtime,
+          matches: runtime === null ? ordered : ordered.slice(0, limit ?? DEFAULT_FIND_LIMIT)
+        };
+      });
     },
     /** Every property of one skill and the files it carries, without bodies. */
     describe(name) {
@@ -1310,11 +1403,14 @@ function registerSkillsExtension(server, skills, options = {}) {
 // src/tools/schemas.ts
 import { z as z3 } from "zod";
 var kind = z3.enum(ASSET_KINDS);
+var runtimeSchema = z3.enum(RUNTIMES);
 var catalogItemSchema = z3.object({
   name: z3.string(),
   description: z3.string(),
   tier: z3.string().optional(),
-  kind: kind.optional()
+  kind: kind.optional(),
+  verifiedRuntimes: z3.array(runtimeSchema).optional(),
+  verified: z3.boolean().optional()
 });
 var catalogResponseSchema = z3.object({
   count: z3.number().int(),
@@ -1327,12 +1423,15 @@ var catalogResponseSchema = z3.object({
 });
 var findResultSchema = z3.object({
   ranking: z3.enum(["semantic", "lexical"]),
+  runtime: runtimeSchema.nullable(),
   matches: z3.array(
     z3.object({
       name: z3.string(),
       package: z3.string(),
       description: z3.string(),
-      score: z3.number()
+      score: z3.number(),
+      verifiedRuntimes: z3.array(runtimeSchema).optional(),
+      verified: z3.boolean().optional()
     })
   )
 });
@@ -1341,6 +1440,10 @@ var skillFileSchema = z3.object({
   bytes: z3.number().int(),
   sha256: z3.string()
 });
+var metadataLeafSchema = z3.union([
+  z3.string(),
+  z3.array(z3.string()).readonly()
+]);
 var describeResponseSchema = z3.object({
   name: z3.string(),
   kind,
@@ -1349,7 +1452,10 @@ var describeResponseSchema = z3.object({
   tier: z3.string().optional(),
   metadata: z3.record(
     z3.string(),
-    z3.union([z3.string(), z3.array(z3.string()).readonly()])
+    z3.union([
+      metadataLeafSchema,
+      z3.record(z3.string(), metadataLeafSchema).readonly()
+    ])
   ),
   frontmatter: z3.string(),
   files: z3.array(skillFileSchema),
@@ -1414,6 +1520,12 @@ var kindInput = z4.enum(["skill", "agent", "hook", "mcp", "any"]).optional().des
   "skill (default), agent, hook, mcp, or any. Commands are skills; agents, hooks and MCP servers are installed with pmcp add rather than read."
 );
 var tierInput = z4.enum(["open", "free", "paid", "internal"]).optional();
+var runtimeInput = runtimeSchema.optional().describe(
+  "A runtime (claude-code, codex-cli, gemini-cli, grok-cli, antigravity). Skills whose metadata.verified-runtimes lists it are marked verified and listed first; the rest are kept. Without it, the runtime of the connected client is used for the same ordering when it is recognised."
+);
+var verifiedOnlyInput = z4.boolean().optional().describe(
+  "Drop skills that are not verified: on the given runtime, or on any runtime when none is given. The detected client runtime never filters."
+);
 var skillNameInput = z4.string().min(1).describe("A skill name as skill_find or skill_catalog returns it.");
 var asText = (value) => ({
   content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
@@ -1502,16 +1614,23 @@ function registerCatalogTool(server, tools) {
     "skill_catalog",
     {
       ...readOnlyTool("List skills"),
-      description: "Every skill the installed packages and marketplaces ship, grouped by package or plugin, with names, one-line descriptions and tier, and no bodies. Paged by group. With kind it lists agents, hooks or MCP servers instead.",
+      description: "Every skill the installed packages and marketplaces ship, grouped by package or plugin, with names, one-line descriptions and tier, and no bodies. Paged by group. With kind it lists agents, hooks or MCP servers instead. Items list the runtimes they were verified on (verifiedRuntimes). With runtime, verified items are marked and listed first within their group but the others are kept; verifiedOnly drops the unverified ones.",
       inputSchema: z7.object({
         page: z7.number().int().min(1).optional(),
         pageSize: z7.number().int().min(1).max(20).optional(),
         tier: tierInput,
-        kind: kindInput
+        kind: kindInput,
+        runtime: runtimeInput,
+        verifiedOnly: verifiedOnlyInput
       }),
       outputSchema: catalogResponseSchema
     },
-    async (request) => structured(tools.catalog(request))
+    async (request, ctx) => structured(
+      tools.catalog({
+        ...request,
+        clientRuntime: detectRuntime(server, ctx)
+      })
+    )
   );
 }
 
@@ -1522,7 +1641,7 @@ function registerDescribeTool(server, tools) {
     "skill_describe",
     {
       ...readOnlyTool("Describe a skill"),
-      description: "One skill's frontmatter, metadata (tier, level, requirements, licence, approval), and the files it carries with sizes and sha256, without any body.",
+      description: "One skill's frontmatter, metadata (tier, level, requirements as a nested requires map, verified-runtimes, licence, approval), and the files it carries with sizes and sha256, without any body.",
       inputSchema: z8.object({ name: skillNameInput }),
       outputSchema: describeResponseSchema
     },
@@ -1540,10 +1659,12 @@ function registerFindTool(server, tools) {
     "skill_find",
     {
       ...readOnlyTool("Find skills"),
-      description: "Skill names ranked against an intent, with descriptions and scores, and no bodies. The ranking compares the intent with skill descriptions, so a full sentence matches better than a single keyword.",
+      description: "Skill names ranked against an intent, with descriptions and scores, and no bodies. The ranking compares the intent with skill descriptions, so a full sentence matches better than a single keyword. Each match lists the runtimes it was verified on (verifiedRuntimes). With runtime, verified matches are marked and listed first but the others are kept; verifiedOnly drops the unverified ones. The answer's runtime is the one the ordering used, or null.",
       inputSchema: z9.object({
         intent: z9.string().min(1).max(256).describe("What the task is, as a sentence."),
         limit: z9.number().int().min(1).max(25).optional(),
+        runtime: runtimeInput,
+        verifiedOnly: verifiedOnlyInput,
         filters: z9.object({
           kind: kindInput,
           tier: tierInput,
@@ -1555,7 +1676,14 @@ function registerFindTool(server, tools) {
       }),
       outputSchema: findResultSchema
     },
-    async ({ intent, limit, filters }) => structured(await tools.find(intent, limit, filters))
+    async ({ intent, limit, runtime, verifiedOnly, filters }, ctx) => structured(
+      await tools.find(
+        intent,
+        limit,
+        { ...filters, runtime, verifiedOnly },
+        detectRuntime(server, ctx)
+      )
+    )
   );
 }
 
@@ -1590,7 +1718,7 @@ function registerReadTool(server, tools) {
 
 // src/mcp.ts
 var SERVER_NAME = "pmcp";
-var SERVER_VERSION = "0.8.2";
+var SERVER_VERSION = "0.9.0";
 function registerSkillTools(server, tools) {
   registerCatalogTool(server, tools);
   registerFindTool(server, tools);
@@ -1645,6 +1773,10 @@ export {
   cosine,
   find,
   bundleSkill,
+  RUNTIMES,
+  verifiedRuntimesOf,
+  runtimeOfClient,
+  detectRuntime,
   DESCRIBE_FILE_LIMIT,
   CATALOG_PAGE_SIZE,
   CATALOG_PAGE_MAX,
@@ -1661,4 +1793,4 @@ export {
   registerSkillTools,
   createSkillServer
 };
-//# sourceMappingURL=chunk-UGRHZHHC.js.map
+//# sourceMappingURL=chunk-PXNRZXL6.js.map

package/dist/{chunk-3JNWCUHA.js → chunk-RYOLBTSW.js}

@@ -1,6 +1,6 @@
 import {
   openDatabase
-} from "./chunk-IRQTGYHA.js";
+} from "./chunk-AKPSLZRJ.js";
 
 // src/embed.ts
 var DEFAULT_MODEL_ID = "Xenova/multilingual-e5-small";
@@ -157,4 +157,4 @@ export {
   encodeEntries,
   openEntryVectors
 };
-//# sourceMappingURL=chunk-3JNWCUHA.js.map
+//# sourceMappingURL=chunk-RYOLBTSW.js.map

package/dist/{chunk-UW7HTILA.js → chunk-Y7UX36AC.js}

@@ -1,6 +1,6 @@
 import {
   createSkillServer
-} from "./chunk-UGRHZHHC.js";
+} from "./chunk-PXNRZXL6.js";
 
 // src/stdio.ts
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
@@ -38,4 +38,4 @@ export {
   serve,
   main
 };
-//# sourceMappingURL=chunk-UW7HTILA.js.map
+//# sourceMappingURL=chunk-Y7UX36AC.js.map

package/dist/cli.js

@@ -2,7 +2,7 @@
 import {
   loadEmbedder,
   openEntryVectors
-} from "./chunk-3JNWCUHA.js";
+} from "./chunk-RYOLBTSW.js";
 import {
   ConfigError,
   ProjectError,
@@ -17,15 +17,15 @@ import {
   splitFrontmatter,
   validateCatalog,
   validateSkillDir
-} from "./chunk-O2P5AIHX.js";
-import "./chunk-IRQTGYHA.js";
+} from "./chunk-PWEAKJZ3.js";
+import "./chunk-AKPSLZRJ.js";
 import {
   serve
-} from "./chunk-UW7HTILA.js";
+} from "./chunk-Y7UX36AC.js";
 import {
   kindOf,
   readCatalog
-} from "./chunk-UGRHZHHC.js";
+} from "./chunk-PXNRZXL6.js";
 
 // src/cli/command.ts
 var ArgumentError = class extends Error {
@@ -2347,7 +2347,7 @@ function dispatch(argv, options = {}) {
   }
   return run(command, rest, { ui, env, cwd });
 }
-var VERSION = "0.8.2";
+var VERSION = "0.9.0";
 async function run(command, argv, context) {
   try {
     return await command.run({

package/dist/http.d.ts

@@ -1,5 +1,5 @@
-import { S as SkillEntry } from './catalog-CS0j6-0U.js';
-import { E as Embedder, S as SkillServerOptions } from './server-CLyCpwZb.js';
+import { S as SkillEntry } from './catalog-BU5VLLyd.js';
+import { E as Embedder, S as SkillServerOptions } from './server-BBZDjzWZ.js';
 import 'zod';
 
 /**
@@ -74,6 +74,7 @@ interface SkillCaller {
     readonly claims?: Readonly<Record<string, unknown>>;
 }
 interface SkillHttpOptions extends SkillServerOptions {
+    /** Gets the Request the host's fetch received; read headers only, the body is still unread. */
     readonly authorize: (request: Request) => SkillCaller | undefined | Promise<SkillCaller | undefined>;
     /** Tiers a caller may list and load. Package skills without a tier count as open. */
     readonly tiersFor?: (caller: SkillCaller) => readonly string[];

package/dist/http.js

@@ -2,12 +2,12 @@ import {
   DEFAULT_MODEL_ID,
   encodeEntries,
   loadEmbedder
-} from "./chunk-3JNWCUHA.js";
-import "./chunk-IRQTGYHA.js";
+} from "./chunk-RYOLBTSW.js";
+import "./chunk-AKPSLZRJ.js";
 import {
   createSkillServer,
   readCatalog
-} from "./chunk-UGRHZHHC.js";
+} from "./chunk-PXNRZXL6.js";
 
 // src/http.ts
 import {
@@ -166,12 +166,7 @@ function createSkillHttpHandler(options) {
   };
   const limit = options.rateLimit ? createRateLimiter(options.rateLimit) : void 0;
   const serve = async (request) => {
-    const capped = await capBody(
-      request,
-      options.maxRequestBytes ?? DEFAULT_MAX_REQUEST_BYTES
-    );
-    if (capped instanceof Response) return capped;
-    const caller = await options.authorize(capped);
+    const caller = await options.authorize(request);
     if (!caller) {
       return new Response(JSON.stringify({ error: "unauthorized" }), {
         status: 401,
@@ -183,6 +178,11 @@ function createSkillHttpHandler(options) {
     }
     const limited = limit?.(caller.id);
     if (limited) return limited;
+    const capped = await capBody(
+      request,
+      options.maxRequestBytes ?? DEFAULT_MAX_REQUEST_BYTES
+    );
+    if (capped instanceof Response) return capped;
     return handlerFor(tiersFor(caller)).fetch(capped, {
       authInfo: {
         token: "",

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-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 { I as IntentCache, S as SkillServerOptions, a as SkillTools } from './server-BBZDjzWZ.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 RUNTIMES, l as Ranking, m as ReadResult, n as Runtime, o as SkillBundle, p as SkillFile, q as SkillFileContent, r as SkillFileListing, s as SkillFilters, t as bundleResponseSchema, u as bundleSkill, v as catalogResponseSchema, w as classify, x as cosine, y as createSkillTools, z as describeResponseSchema, A as detectRuntime, G as find, H as findResultSchema, J as isUtf8Text, L as lexicalScore, N as listSkillFiles, O as mimeOf, P as normaliseIntent, Q as readSkillFile, T as runtimeOfClient, U as verifiedRuntimesOf } from './server-BBZDjzWZ.js';
+import { S as SkillEntry, M as MetadataValue, C as CatalogOptions } from './catalog-BU5VLLyd.js';
+export { a as ASSET_KINDS, A as AssetKind, b as COMPATIBILITY_MAX, D as DESCRIPTION_MAX, c as MAX_SKILL_DEPTH, d as MetadataLeaf, N as NAME_MAX, e as SKIPPED_DIRS, f as displayPath, k as kindOf, g as parseSkillFrontmatter, r as readBody, h as readCatalog, i as readFrontmatter, s as specProblems, w as withoutBody } from './catalog-BU5VLLyd.js';
 import { McpServer } from '@modelcontextprotocol/server';
 import 'zod';
 
@@ -37,25 +37,6 @@ 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,
@@ -68,7 +49,7 @@ interface Rejection {
     readonly path: string;
     readonly reason: string;
 }
-/** The `metadata:` map of a frontmatter, one level deep: strings and string lists. */
+/** The `metadata:` map of a frontmatter: strings, string lists and maps of those. */
 declare function readMetadata(source: string): Record<string, MetadataValue>;
 /** The raw frontmatter text between the fences, for skill_describe. */
 declare function readFrontmatterText(source: string): string;
@@ -304,7 +285,7 @@ declare function resolveSkillFileUri(uri: string, entries: readonly SkillEntry[]
 
 /** Reported to the host on connect. */
 declare const SERVER_NAME = "pmcp";
-declare const SERVER_VERSION = "0.8.2";
+declare const SERVER_VERSION = "0.9.0";
 /**
  * Registers the skill_* tools on a server.
  *
@@ -356,4 +337,4 @@ declare function registerSkillResources(server: McpServer, skills: () => readonl
 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 };
+export { CONFIG_FILE, CatalogOptions, type CatalogSection, ConfigError, DEFAULT_INTENT_CACHE_LIMIT, type Finding$1 as Finding, IntentCache, type IntentCacheOptions, LOCK_FILE, type McpServerSpec, MetadataValue, 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, plan, project, promptName, readConfig, readFrontmatterText, readMarketplace, readMetadata, readSpec, registerSkillPrompts, registerSkillResources, registerSkillTools, registerSkillsExtension, resolveSkillFileUri, skillFileUri, skillFileUri as skillUri, validateCatalog, validateSkillDir };

package/dist/index.js

@@ -14,11 +14,11 @@ import {
   readSpec,
   validateCatalog,
   validateSkillDir
-} from "./chunk-O2P5AIHX.js";
+} from "./chunk-PWEAKJZ3.js";
 import {
   DEFAULT_INTENT_CACHE_LIMIT,
   openIntentCache
-} from "./chunk-IRQTGYHA.js";
+} from "./chunk-AKPSLZRJ.js";
 import {
   ASSET_KINDS,
   CATALOG_PAGE_MAX,
@@ -30,6 +30,7 @@ import {
   MAX_SKILL_DEPTH,
   NAME_MAX,
   READ_BUDGET_BYTES,
+  RUNTIMES,
   SERVER_NAME,
   SERVER_VERSION,
   SKILLS_EXTENSION,
@@ -43,6 +44,7 @@ import {
   createSkillServer,
   createSkillTools,
   describeResponseSchema,
+  detectRuntime,
   displayPath,
   extensionEntry,
   find,
@@ -67,10 +69,12 @@ import {
   registerSkillTools,
   registerSkillsExtension,
   resolveSkillFileUri,
+  runtimeOfClient,
   skillFileUri,
   specProblems,
+  verifiedRuntimesOf,
   withoutBody
-} from "./chunk-UGRHZHHC.js";
+} from "./chunk-PXNRZXL6.js";
 export {
   ASSET_KINDS,
   CATALOG_PAGE_MAX,
@@ -87,6 +91,7 @@ export {
   NAME_MAX,
   ProjectError,
   READ_BUDGET_BYTES,
+  RUNTIMES,
   SERVER_NAME,
   SERVER_VERSION,
   SKILLS_EXTENSION,
@@ -103,6 +108,7 @@ export {
   deadGlobs,
   deriveName,
   describeResponseSchema,
+  detectRuntime,
   displayPath,
   doctor,
   extensionEntry,
@@ -134,11 +140,13 @@ export {
   registerSkillTools,
   registerSkillsExtension,
   resolveSkillFileUri,
+  runtimeOfClient,
   skillFileUri,
   skillFileUri as skillUri,
   specProblems,
   validateCatalog,
   validateSkillDir,
+  verifiedRuntimesOf,
   withoutBody
 };
 //# sourceMappingURL=index.js.map

package/dist/{server-CLyCpwZb.d.ts → server-BBZDjzWZ.d.ts}

@@ -1,4 +1,4 @@
-import { S as SkillEntry, C as CatalogOptions, A as AssetKind } from './catalog-CS0j6-0U.js';
+import { S as SkillEntry, M as MetadataValue, C as CatalogOptions, A as AssetKind } from './catalog-BU5VLLyd.js';
 import { z } from 'zod';
 
 /**
@@ -179,6 +179,36 @@ type ReadResult = SkillFileContent | FileRefusal | {
 };
 declare function readSkillFile(entry: SkillEntry, wanted?: string, budget?: number): ReadResult;
 
+/**
+ * Agent runtimes a skill can declare itself verified on, and the mapping from
+ * an MCP client's reported name to one of them.
+ */
+
+declare const RUNTIMES: readonly ["claude-code", "codex-cli", "gemini-cli", "grok-cli", "antigravity"];
+type Runtime = (typeof RUNTIMES)[number];
+/** The runtimes a metadata block lists as verified; unknown values are dropped. */
+declare function verifiedRuntimesOf(metadata: Readonly<Record<string, MetadataValue>> | undefined): Runtime[];
+/** The runtime an MCP client name stands for; null when it is not recognised. */
+declare function runtimeOfClient(name: string | undefined): Runtime | null;
+interface ClientSource {
+    readonly server?: {
+        getClientVersion?: () => {
+            readonly name?: string;
+        } | undefined;
+    };
+}
+interface RequestContext {
+    readonly mcpReq?: {
+        readonly envelope?: object;
+    };
+}
+/**
+ * The runtime of the client making this request. The per-request envelope is
+ * read first, then the initialize-scoped identity; a stateless caller has
+ * neither and gets null.
+ */
+declare function detectRuntime(server: ClientSource, ctx?: RequestContext): Runtime | null;
+
 /**
  * The shapes the tools answer with, defined once: the TypeScript types are
  * inferred from these schemas and the same schemas are each tool's outputSchema,
@@ -195,6 +225,14 @@ declare const catalogItemSchema: z.ZodObject<{
         hook: "hook";
         mcp: "mcp";
     }>>;
+    verifiedRuntimes: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        "claude-code": "claude-code";
+        "codex-cli": "codex-cli";
+        "gemini-cli": "gemini-cli";
+        "grok-cli": "grok-cli";
+        antigravity: "antigravity";
+    }>>>;
+    verified: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 declare const catalogResponseSchema: z.ZodObject<{
     count: z.ZodNumber;
@@ -213,6 +251,14 @@ declare const catalogResponseSchema: z.ZodObject<{
                 hook: "hook";
                 mcp: "mcp";
             }>>;
+            verifiedRuntimes: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                "claude-code": "claude-code";
+                "codex-cli": "codex-cli";
+                "gemini-cli": "gemini-cli";
+                "grok-cli": "grok-cli";
+                antigravity: "antigravity";
+            }>>>;
+            verified: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -221,11 +267,26 @@ declare const findResultSchema: z.ZodObject<{
         semantic: "semantic";
         lexical: "lexical";
     }>;
+    runtime: z.ZodNullable<z.ZodEnum<{
+        "claude-code": "claude-code";
+        "codex-cli": "codex-cli";
+        "gemini-cli": "gemini-cli";
+        "grok-cli": "grok-cli";
+        antigravity: "antigravity";
+    }>>;
     matches: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         package: z.ZodString;
         description: z.ZodString;
         score: z.ZodNumber;
+        verifiedRuntimes: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            "claude-code": "claude-code";
+            "codex-cli": "codex-cli";
+            "gemini-cli": "gemini-cli";
+            "grok-cli": "grok-cli";
+            antigravity: "antigravity";
+        }>>>;
+        verified: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 declare const describeResponseSchema: z.ZodObject<{
@@ -239,7 +300,7 @@ declare const describeResponseSchema: z.ZodObject<{
     package: z.ZodString;
     description: z.ZodString;
     tier: z.ZodOptional<z.ZodString>;
-    metadata: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodReadonly<z.ZodArray<z.ZodString>>]>>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodReadonly<z.ZodArray<z.ZodString>>]>, z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodReadonly<z.ZodArray<z.ZodString>>]>>>]>>;
     frontmatter: z.ZodString;
     files: z.ZodArray<z.ZodObject<{
         path: z.ZodString;
@@ -261,6 +322,7 @@ declare const bundleResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 type CatalogItem = z.infer<typeof catalogItemSchema>;
 type CatalogResponse = z.infer<typeof catalogResponseSchema>;
+type FindResponse = z.infer<typeof findResultSchema>;
 type DescribeResponse = z.infer<typeof describeResponseSchema>;
 
 /**
@@ -288,6 +350,10 @@ interface SkillFilters {
     readonly level?: string;
     readonly domain?: string;
     readonly medium?: string;
+    /** The runtime verified skills are ranked and marked for. Never filters by itself. */
+    readonly runtime?: Runtime;
+    /** Keep only skills verified on `runtime`, or on any runtime when it is unset. */
+    readonly verifiedOnly?: boolean;
 }
 interface SkillServerOptions extends CatalogOptions {
     readonly embedder?: Embedder;
@@ -295,6 +361,8 @@ interface SkillServerOptions extends CatalogOptions {
     readonly vectors?: ReadonlyMap<string, Float32Array>;
     /** Injected for tests. Reads the catalog off disk otherwise. */
     readonly loadCatalog?: (options: CatalogOptions) => SkillEntry[];
+    /** Off by default so a call without a runtime input ranks exactly as before. */
+    readonly rankByClientRuntime?: boolean;
 }
 
 interface CallResponse {
@@ -321,9 +389,13 @@ declare function createSkillTools(options: SkillServerOptions): {
         pageSize?: number;
         tier?: string;
         kind?: KindFilter;
+        runtime?: Runtime;
+        verifiedOnly?: boolean;
+        /** The caller's own runtime, for ordering only. */
+        clientRuntime?: Runtime | null;
     }): CatalogResponse;
     /** Ranked names. Returns; never loads a body. */
-    find(intent: string, limit?: number, filters?: SkillFilters): Promise<FindResult>;
+    find(intent: string, limit?: number, filters?: SkillFilters, clientRuntime?: Runtime | null): Promise<FindResponse>;
     /** Every property of one skill and the files it carries, without bodies. */
     describe(name: string): DescribeResponse | null;
     /**
@@ -349,4 +421,4 @@ declare function createSkillTools(options: SkillServerOptions): {
 };
 type SkillTools = ReturnType<typeof createSkillTools>;
 
-export { isUtf8Text as A, type BundleFile as B, CATALOG_PAGE_MAX as C, DEFAULT_FIND_LIMIT as D, type Embedder as E, type FileKind as F, lexicalScore as G, listSkillFiles as H, type IntentCache as I, mimeOf as J, type KindFilter as K, normaliseIntent as L, type Match as M, readSkillFile as N, READ_BUDGET_BYTES as R, type SkillServerOptions as S, type SkillTools as a, CATALOG_PAGE_SIZE as b, type CallResponse as c, type CatalogItem as d, type CatalogResponse as e, type Classified as f, DESCRIBE_FILE_LIMIT as g, type FindOptions as h, type FindResult as i, type IntentCacheStats as j, type Ranking as k, type ReadResult as l, type SkillBundle as m, type SkillFile as n, type SkillFileContent as o, type SkillFileListing as p, type SkillFilters as q, bundleResponseSchema as r, bundleSkill as s, catalogResponseSchema as t, classify as u, cosine as v, createSkillTools as w, describeResponseSchema as x, find as y, findResultSchema as z };
+export { detectRuntime as A, type BundleFile as B, CATALOG_PAGE_MAX as C, DEFAULT_FIND_LIMIT as D, type Embedder as E, type FileKind as F, find as G, findResultSchema as H, type IntentCache as I, isUtf8Text as J, type KindFilter as K, lexicalScore as L, type Match as M, listSkillFiles as N, mimeOf as O, normaliseIntent as P, readSkillFile as Q, READ_BUDGET_BYTES as R, type SkillServerOptions as S, runtimeOfClient as T, verifiedRuntimesOf as U, type SkillTools as a, CATALOG_PAGE_SIZE as b, type CallResponse as c, type CatalogItem as d, type CatalogResponse as e, type Classified as f, DESCRIBE_FILE_LIMIT as g, type FindOptions as h, type FindResult as i, type IntentCacheStats as j, RUNTIMES as k, type Ranking as l, type ReadResult as m, type Runtime as n, type SkillBundle as o, type SkillFile as p, type SkillFileContent as q, type SkillFileListing as r, type SkillFilters as s, bundleResponseSchema as t, bundleSkill as u, catalogResponseSchema as v, classify as w, cosine as x, createSkillTools as y, describeResponseSchema as z };

package/dist/stdio.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { C as CatalogOptions } from './catalog-CS0j6-0U.js';
+import { C as CatalogOptions } from './catalog-BU5VLLyd.js';
 
 /**
  * The stdio entry a host launches.

package/dist/stdio.js

@@ -3,8 +3,8 @@ import {
   main,
   resolveRoots,
   serve
-} from "./chunk-UW7HTILA.js";
-import "./chunk-UGRHZHHC.js";
+} from "./chunk-Y7UX36AC.js";
+import "./chunk-PXNRZXL6.js";
 export {
   main,
   resolveRoots,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modootoday/pmcp",
-  "version": "0.8.2",
+  "version": "0.9.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.",