@modootoday/pmcp 0.6.0 → 0.7.0

package/README.md

@@ -160,11 +160,18 @@ export default { fetch: (request: Request) => skills.fetch(request) };
 
 Put Origin and Host validation in front of it when it is mounted bare.
 
+Pass `semantic: { cacheDir, localOnly: true }` to rank by meaning: the handler encodes
+the catalog at start with `@huggingface/transformers` and the multilingual model, so an
+intent in one language finds a description in another. Requests rank lexically until
+`ready()` settles, and stay lexical when the encoder cannot load (`onError` says why).
+
 ## 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.
+Node.js 22 or later, or Bun 1.3 or later. Default ranking is lexical. Semantic
+ranking (the `index` command, or the HTTP handler's `semantic` option) needs
+`@huggingface/transformers` installed separately; it is not part of the default
+installation. The default encoder is `Xenova/multilingual-e5-small` (MIT, about
+130 MB), so vectors indexed with the earlier English-only default are re-encoded.
 
 Elastic License 2.0. See `LICENSE` and `NOTICE` for terms and dependency notices.
 Documentation: <https://pmcp.build>.

package/dist/{chunk-6TSHDCUY.js → chunk-GNJSZCRH.js}

@@ -1,131 +1,3 @@
-import {
-  normaliseIntent
-} from "./chunk-5TX2IAVD.js";
-
-// src/cache.ts
-async function openDatabase(path) {
-  try {
-    const { DatabaseSync } = await import(`node:${"sqlite"}`);
-    return { db: new DatabaseSync(path), provider: "node:sqlite" };
-  } catch {
-  }
-  try {
-    const { Database } = await import(`bun:${"sqlite"}`);
-    const bun = new Database(path, { create: true });
-    return {
-      db: {
-        exec: (sql) => bun.run(sql),
-        prepare: (sql) => bun.query(sql),
-        close: () => bun.close()
-      },
-      provider: "bun:sqlite"
-    };
-  } catch {
-    return null;
-  }
-}
-var DEFAULT_INTENT_CACHE_LIMIT = 4096;
-var SCHEMA = `
-  CREATE TABLE IF NOT EXISTS intent_vector (
-    intent   TEXT    NOT NULL PRIMARY KEY,
-    model_id TEXT    NOT NULL,
-    dims     INTEGER NOT NULL,
-    vector   BLOB    NOT NULL,
-    used_at  INTEGER NOT NULL
-  );
-  CREATE INDEX IF NOT EXISTS intent_vector_used_at ON intent_vector (used_at);
-`;
-async function openIntentCache(options) {
-  const opened = await openDatabase(options.path);
-  if (!opened) return null;
-  const { db, provider } = opened;
-  try {
-    db.exec("PRAGMA journal_mode = WAL");
-    db.exec(SCHEMA);
-  } catch {
-    db.close();
-    return null;
-  }
-  const limit = options.limit ?? DEFAULT_INTENT_CACHE_LIMIT;
-  const now = options.now ?? (() => Date.now());
-  let hits = 0;
-  let misses = 0;
-  let mismatched = 0;
-  const selectRow = db.prepare("SELECT model_id, dims, vector FROM intent_vector WHERE intent = ?");
-  const touch = db.prepare(
-    "UPDATE intent_vector SET used_at = ? WHERE intent = ?"
-  );
-  const upsert = db.prepare(
-    `INSERT INTO intent_vector (intent, model_id, dims, vector, used_at)
-     VALUES (?, ?, ?, ?, ?)
-     ON CONFLICT(intent) DO UPDATE SET
-       model_id = excluded.model_id,
-       dims     = excluded.dims,
-       vector   = excluded.vector,
-       used_at  = excluded.used_at`
-  );
-  const countRows = db.prepare(
-    "SELECT count(*) AS n FROM intent_vector"
-  );
-  const evict = db.prepare(
-    `DELETE FROM intent_vector WHERE intent IN (
-       SELECT intent FROM intent_vector ORDER BY used_at ASC LIMIT ?
-     )`
-  );
-  return {
-    get(intent) {
-      const key = normaliseIntent(intent);
-      const row = selectRow.get(key) ?? null;
-      if (!row) {
-        misses += 1;
-        return null;
-      }
-      if (row.model_id !== options.modelId || row.dims !== options.dims) {
-        mismatched += 1;
-        return null;
-      }
-      hits += 1;
-      touch.run(now(), key);
-      const bytes = row.vector;
-      return new Float32Array(
-        bytes.buffer.slice(
-          bytes.byteOffset,
-          bytes.byteOffset + bytes.byteLength
-        )
-      );
-    },
-    put(intent, vector) {
-      if (vector.length !== options.dims) {
-        throw new Error(
-          `intent vector is ${vector.length} wide, cache holds ${options.dims}`
-        );
-      }
-      const key = normaliseIntent(intent);
-      upsert.run(
-        key,
-        options.modelId,
-        options.dims,
-        new Uint8Array(vector.buffer, vector.byteOffset, vector.byteLength),
-        now()
-      );
-      const rows = countRows.get()?.n ?? 0;
-      if (rows > limit) evict.run(rows - limit);
-    },
-    stats() {
-      return {
-        hits,
-        misses,
-        mismatched,
-        rows: countRows.get()?.n ?? 0,
-        provider
-      };
-    },
-    close() {
-      db.close();
-    }
-  };
-}
-
 // src/config.ts
 import { existsSync, readFileSync } from "fs";
 import { dirname, join, resolve } from "path";
@@ -1215,9 +1087,6 @@ function readSpec(config) {
 }
 
 export {
-  openDatabase,
-  DEFAULT_INTENT_CACHE_LIMIT,
-  openIntentCache,
   CONFIG_FILE,
   ConfigError,
   findConfig,
@@ -1235,4 +1104,4 @@ export {
   TOOLS,
   readSpec
 };
-//# sourceMappingURL=chunk-6TSHDCUY.js.map
+//# sourceMappingURL=chunk-GNJSZCRH.js.map

package/dist/chunk-NI2OLZPA.js

@@ -0,0 +1,160 @@
+import {
+  openDatabase
+} from "./chunk-ZLELYZHL.js";
+
+// src/embed.ts
+var DEFAULT_MODEL_ID = "Xenova/multilingual-e5-small";
+var PLAIN = {
+  queryPrefix: "",
+  passagePrefix: "",
+  pooling: "mean"
+};
+var E5 = {
+  queryPrefix: "query: ",
+  passagePrefix: "passage: ",
+  pooling: "mean"
+};
+var KNOWN_ENCODERS = {
+  "Xenova/multilingual-e5-small": E5,
+  "Xenova/multilingual-e5-base": E5,
+  "Xenova/multilingual-e5-large": E5,
+  "Xenova/bge-m3": { ...PLAIN, pooling: "cls" }
+};
+function encoderSpec(modelId) {
+  return KNOWN_ENCODERS[modelId] ?? PLAIN;
+}
+var ENTRY_SCHEMA = `
+  CREATE TABLE IF NOT EXISTS entry_vector (
+    name TEXT NOT NULL,
+    model_id TEXT NOT NULL,
+    dims INTEGER NOT NULL,
+    description_hash TEXT NOT NULL,
+    vector BLOB NOT NULL,
+    PRIMARY KEY (name, model_id)
+  );
+`;
+var TRANSFORMERS = "@huggingface/transformers";
+async function loadEmbedder(modelId = DEFAULT_MODEL_ID, options = {}) {
+  let module;
+  try {
+    module = options.module ?? await import(TRANSFORMERS);
+  } catch {
+    return null;
+  }
+  const factory = module.pipeline;
+  if (typeof factory !== "function") return null;
+  if (module.env) {
+    if (options.cacheDir !== void 0)
+      module.env["cacheDir"] = options.cacheDir;
+    if (options.localOnly) module.env["allowRemoteModels"] = false;
+  }
+  const encode = await factory("feature-extraction", modelId, {
+    dtype: options.dtype ?? "q8"
+  });
+  const spec = encoderSpec(modelId);
+  let dims = 0;
+  const run = async (text) => {
+    const output = await encode(text, {
+      pooling: spec.pooling,
+      normalize: true
+    });
+    const vector = Float32Array.from(output.data);
+    dims = vector.length;
+    return vector;
+  };
+  return {
+    modelId,
+    get dims() {
+      return dims;
+    },
+    embed: (text) => run(spec.queryPrefix + text),
+    embedPassage: (text) => run(spec.passagePrefix + text)
+  };
+}
+async function encodeEntries(embedder, entries, previous = /* @__PURE__ */ new Map()) {
+  const out = /* @__PURE__ */ new Map();
+  const passage = (text) => embedder.embedPassage ? embedder.embedPassage(text) : embedder.embed(text);
+  for (const entry of entries) {
+    const hash = describeHash(entry.description);
+    const kept = previous.get(entry.name);
+    if (kept && kept.hash === hash) {
+      out.set(entry.name, kept);
+      continue;
+    }
+    out.set(entry.name, { hash, vector: await passage(entry.description) });
+  }
+  return out;
+}
+function describeHash(description) {
+  let hash = 2166136261;
+  for (let i = 0; i < description.length; i++) {
+    hash ^= description.charCodeAt(i);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+async function openEntryVectors(path) {
+  const opened = await openDatabase(path);
+  if (opened === null) return null;
+  const db = opened.db;
+  db.exec(ENTRY_SCHEMA);
+  return {
+    read(modelId) {
+      const out = /* @__PURE__ */ new Map();
+      const rows = db.prepare(
+        "SELECT name, dims, vector FROM entry_vector WHERE model_id = ?"
+      ).all(modelId);
+      for (const row of rows) {
+        const bytes = row.vector;
+        const vector = new Float32Array(
+          bytes.buffer.slice(
+            bytes.byteOffset,
+            bytes.byteOffset + bytes.byteLength
+          )
+        );
+        if (vector.length === row.dims) out.set(row.name, vector);
+      }
+      return out;
+    },
+    stale(modelId, entries) {
+      const rows = db.prepare(
+        "SELECT name, description_hash FROM entry_vector WHERE model_id = ?"
+      ).all(modelId);
+      const stored = new Map(
+        rows.map((row) => [row.name, row.description_hash])
+      );
+      const out = [];
+      for (const [name, description] of entries) {
+        if (stored.get(name) !== describeHash(description)) out.push(name);
+      }
+      return out;
+    },
+    write(modelId, name, description, vector) {
+      db.prepare(
+        `INSERT INTO entry_vector (name, model_id, dims, description_hash, vector)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(name, model_id) DO UPDATE SET
+           dims = excluded.dims,
+           description_hash = excluded.description_hash,
+           vector = excluded.vector`
+      ).run(
+        name,
+        modelId,
+        vector.length,
+        describeHash(description),
+        new Uint8Array(vector.buffer, vector.byteOffset, vector.byteLength)
+      );
+    },
+    close() {
+      db.close();
+    }
+  };
+}
+
+export {
+  DEFAULT_MODEL_ID,
+  loadEmbedder,
+  encodeEntries,
+  openEntryVectors
+};
+//# sourceMappingURL=chunk-NI2OLZPA.js.map

package/dist/{chunk-FXBLBKP6.js → chunk-POJOFL4L.js}

@@ -1,6 +1,6 @@
 import {
   createSkillServer
-} from "./chunk-5TX2IAVD.js";
+} from "./chunk-QHFORYIN.js";
 
 // src/stdio.ts
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
@@ -35,4 +35,4 @@ export {
   serve,
   main
 };
-//# sourceMappingURL=chunk-FXBLBKP6.js.map
+//# sourceMappingURL=chunk-POJOFL4L.js.map

package/dist/{chunk-5TX2IAVD.js → chunk-QHFORYIN.js}

@@ -1129,7 +1129,7 @@ function registerSkillTools(server, tools) {
   return server;
 }
 function createSkillServer(options) {
-  const server = new McpServer({ name: SERVER_NAME, version: "0.6.0" });
+  const server = new McpServer({ name: SERVER_NAME, version: "0.7.0" });
   const tools = createSkillTools(options);
   registerSkillsExtension(server, tools.skills);
   return registerSkillTools(server, tools);
@@ -1167,4 +1167,4 @@ export {
   registerSkillTools,
   createSkillServer
 };
-//# sourceMappingURL=chunk-5TX2IAVD.js.map
+//# sourceMappingURL=chunk-QHFORYIN.js.map

package/dist/chunk-ZLELYZHL.js

@@ -0,0 +1,134 @@
+import {
+  normaliseIntent
+} from "./chunk-QHFORYIN.js";
+
+// src/cache.ts
+async function openDatabase(path) {
+  try {
+    const { DatabaseSync } = await import(`node:${"sqlite"}`);
+    return { db: new DatabaseSync(path), provider: "node:sqlite" };
+  } catch {
+  }
+  try {
+    const { Database } = await import(`bun:${"sqlite"}`);
+    const bun = new Database(path, { create: true });
+    return {
+      db: {
+        exec: (sql) => bun.run(sql),
+        prepare: (sql) => bun.query(sql),
+        close: () => bun.close()
+      },
+      provider: "bun:sqlite"
+    };
+  } catch {
+    return null;
+  }
+}
+var DEFAULT_INTENT_CACHE_LIMIT = 4096;
+var SCHEMA = `
+  CREATE TABLE IF NOT EXISTS intent_vector (
+    intent   TEXT    NOT NULL PRIMARY KEY,
+    model_id TEXT    NOT NULL,
+    dims     INTEGER NOT NULL,
+    vector   BLOB    NOT NULL,
+    used_at  INTEGER NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS intent_vector_used_at ON intent_vector (used_at);
+`;
+async function openIntentCache(options) {
+  const opened = await openDatabase(options.path);
+  if (!opened) return null;
+  const { db, provider } = opened;
+  try {
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec(SCHEMA);
+  } catch {
+    db.close();
+    return null;
+  }
+  const limit = options.limit ?? DEFAULT_INTENT_CACHE_LIMIT;
+  const now = options.now ?? (() => Date.now());
+  let hits = 0;
+  let misses = 0;
+  let mismatched = 0;
+  const selectRow = db.prepare("SELECT model_id, dims, vector FROM intent_vector WHERE intent = ?");
+  const touch = db.prepare(
+    "UPDATE intent_vector SET used_at = ? WHERE intent = ?"
+  );
+  const upsert = db.prepare(
+    `INSERT INTO intent_vector (intent, model_id, dims, vector, used_at)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(intent) DO UPDATE SET
+       model_id = excluded.model_id,
+       dims     = excluded.dims,
+       vector   = excluded.vector,
+       used_at  = excluded.used_at`
+  );
+  const countRows = db.prepare(
+    "SELECT count(*) AS n FROM intent_vector"
+  );
+  const evict = db.prepare(
+    `DELETE FROM intent_vector WHERE intent IN (
+       SELECT intent FROM intent_vector ORDER BY used_at ASC LIMIT ?
+     )`
+  );
+  return {
+    get(intent) {
+      const key = normaliseIntent(intent);
+      const row = selectRow.get(key) ?? null;
+      if (!row) {
+        misses += 1;
+        return null;
+      }
+      if (row.model_id !== options.modelId || row.dims !== options.dims) {
+        mismatched += 1;
+        return null;
+      }
+      hits += 1;
+      touch.run(now(), key);
+      const bytes = row.vector;
+      return new Float32Array(
+        bytes.buffer.slice(
+          bytes.byteOffset,
+          bytes.byteOffset + bytes.byteLength
+        )
+      );
+    },
+    put(intent, vector) {
+      if (vector.length !== options.dims) {
+        throw new Error(
+          `intent vector is ${vector.length} wide, cache holds ${options.dims}`
+        );
+      }
+      const key = normaliseIntent(intent);
+      upsert.run(
+        key,
+        options.modelId,
+        options.dims,
+        new Uint8Array(vector.buffer, vector.byteOffset, vector.byteLength),
+        now()
+      );
+      const rows = countRows.get()?.n ?? 0;
+      if (rows > limit) evict.run(rows - limit);
+    },
+    stats() {
+      return {
+        hits,
+        misses,
+        mismatched,
+        rows: countRows.get()?.n ?? 0,
+        provider
+      };
+    },
+    close() {
+      db.close();
+    }
+  };
+}
+
+export {
+  openDatabase,
+  DEFAULT_INTENT_CACHE_LIMIT,
+  openIntentCache
+};
+//# sourceMappingURL=chunk-ZLELYZHL.js.map

package/dist/cli.js

@@ -1,25 +1,29 @@
 #!/usr/bin/env node
+import {
+  loadEmbedder,
+  openEntryVectors
+} from "./chunk-NI2OLZPA.js";
 import {
   ConfigError,
   ProjectError,
   TOOLS,
   doctor,
   findConfig,
-  openDatabase,
   project,
   readConfig,
   readSpec,
   renderFrontmatter,
   spawnRunner,
   splitFrontmatter
-} from "./chunk-6TSHDCUY.js";
+} from "./chunk-GNJSZCRH.js";
+import "./chunk-ZLELYZHL.js";
 import {
   serve
-} from "./chunk-FXBLBKP6.js";
+} from "./chunk-POJOFL4L.js";
 import {
   kindOf,
   readCatalog
-} from "./chunk-5TX2IAVD.js";
+} from "./chunk-QHFORYIN.js";
 
 // src/cli/command.ts
 var ArgumentError = class extends Error {
@@ -198,109 +202,6 @@ var Ui = class {
   }
 };
 
-// src/embed.ts
-var DEFAULT_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
-var ENTRY_SCHEMA = `
-  CREATE TABLE IF NOT EXISTS entry_vector (
-    name TEXT NOT NULL,
-    model_id TEXT NOT NULL,
-    dims INTEGER NOT NULL,
-    description_hash TEXT NOT NULL,
-    vector BLOB NOT NULL,
-    PRIMARY KEY (name, model_id)
-  );
-`;
-var TRANSFORMERS = "@huggingface/transformers";
-async function loadEmbedder(modelId = DEFAULT_MODEL_ID) {
-  let module;
-  try {
-    module = await import(TRANSFORMERS);
-  } catch {
-    return null;
-  }
-  const factory = module.pipeline;
-  if (typeof factory !== "function") return null;
-  const encode = await factory("feature-extraction", modelId);
-  let dims = 0;
-  return {
-    modelId,
-    get dims() {
-      return dims;
-    },
-    async embed(text) {
-      const output = await encode(text, { pooling: "mean", normalize: true });
-      const vector = Float32Array.from(output.data);
-      dims = vector.length;
-      return vector;
-    }
-  };
-}
-function describeHash(description) {
-  let hash = 2166136261;
-  for (let i = 0; i < description.length; i++) {
-    hash ^= description.charCodeAt(i);
-    hash = Math.imul(hash, 16777619) >>> 0;
-  }
-  return hash.toString(16).padStart(8, "0");
-}
-async function openEntryVectors(path) {
-  const opened = await openDatabase(path);
-  if (opened === null) return null;
-  const db = opened.db;
-  db.exec(ENTRY_SCHEMA);
-  return {
-    read(modelId) {
-      const out = /* @__PURE__ */ new Map();
-      const rows = db.prepare(
-        "SELECT name, dims, vector FROM entry_vector WHERE model_id = ?"
-      ).all(modelId);
-      for (const row of rows) {
-        const bytes = row.vector;
-        const vector = new Float32Array(
-          bytes.buffer.slice(
-            bytes.byteOffset,
-            bytes.byteOffset + bytes.byteLength
-          )
-        );
-        if (vector.length === row.dims) out.set(row.name, vector);
-      }
-      return out;
-    },
-    stale(modelId, entries) {
-      const rows = db.prepare(
-        "SELECT name, description_hash FROM entry_vector WHERE model_id = ?"
-      ).all(modelId);
-      const stored = new Map(
-        rows.map((row) => [row.name, row.description_hash])
-      );
-      const out = [];
-      for (const [name, description] of entries) {
-        if (stored.get(name) !== describeHash(description)) out.push(name);
-      }
-      return out;
-    },
-    write(modelId, name, description, vector) {
-      db.prepare(
-        `INSERT INTO entry_vector (name, model_id, dims, description_hash, vector)
-         VALUES (?, ?, ?, ?, ?)
-         ON CONFLICT(name, model_id) DO UPDATE SET
-           dims = excluded.dims,
-           description_hash = excluded.description_hash,
-           vector = excluded.vector`
-      ).run(
-        name,
-        modelId,
-        vector.length,
-        describeHash(description),
-        new Uint8Array(vector.buffer, vector.byteOffset, vector.byteLength)
-      );
-    },
-    close() {
-      db.close();
-    }
-  };
-}
-
 // src/commands/roots.ts
 var CATALOG_OPTIONS = [
   {
@@ -454,7 +355,7 @@ var indexCommand = {
         return 0;
       }
       for (const entry2 of todo) {
-        const vector = await embedder.embed(entry2.description);
+        const vector = embedder.embedPassage ? await embedder.embedPassage(entry2.description) : await embedder.embed(entry2.description);
         store.write(embedder.modelId, entry2.name, entry2.description, vector);
       }
       const indexed = store.read(embedder.modelId).size;
@@ -2407,7 +2308,7 @@ function dispatch(argv, options = {}) {
   }
   return run(command, rest, { ui, env, cwd });
 }
-var VERSION = "0.6.0";
+var VERSION = "0.7.0";
 async function run(command, argv, context) {
   try {
     return await command.run({

package/dist/http.d.ts

@@ -1,5 +1,40 @@
 import { S as SkillEntry } from './catalog-5v7jrGwP.js';
-import { S as SkillServerOptions } from './server-Dm71qZgM.js';
+import { E as Embedder, S as SkillServerOptions } from './server-wpYiAJ2n.js';
+
+/**
+ * The optional encoder and the store for the vectors it produces.
+ *
+ * Neither the model nor its runtime is a dependency: a caller who wants
+ * semantic ranking installs the peer and runs `pmcp index`, and everything
+ * here degrades to null rather than throwing when that has not happened.
+ */
+
+/**
+ * What `pmcp index` writes and what the server reads back. Multilingual, so a
+ * Korean intent finds an English description (measured 20261005: 8/8 Korean
+ * and 8/8 English intents in the top three over a 99-skill catalog).
+ */
+declare const DEFAULT_MODEL_ID = "Xenova/multilingual-e5-small";
+interface LoadEmbedderOptions {
+    /** Where model files live; a host bakes them into its image here. */
+    readonly cacheDir?: string;
+    /** Refuse to download, so a missing model is an error rather than a fetch. */
+    readonly localOnly?: boolean;
+    /**
+     * Weight precision. q8 is a quarter of fp32's size (118 MB against 470 MB for
+     * the default model) and ranked the same in the 20261005 measurement.
+     */
+    readonly dtype?: "q8" | "fp32";
+    /** Injected for tests. The optional peer is imported otherwise. */
+    readonly module?: unknown;
+}
+/**
+ * Loads the encoder, or returns null when the peer is not installed.
+ *
+ * Absence is not failure anywhere in this package: the caller reports it and
+ * ranking stays lexical.
+ */
+declare function loadEmbedder(modelId?: string, options?: LoadEmbedderOptions): Promise<Embedder | null>;
 
 /**
  * The catalog over streamable HTTP, for a hosted skills server.
@@ -9,6 +44,15 @@ import { S as SkillServerOptions } from './server-Dm71qZgM.js';
  * tiers tiersFor() grants. The catalog is read once and filtered per request.
  */
 
+/** Semantic ranking for a hosted catalog: the encoder runs in the host process. */
+interface SkillHttpSemanticOptions extends Omit<LoadEmbedderOptions, "module"> {
+    /** Defaults to the multilingual model pmcp index uses. */
+    readonly modelId?: string;
+    /** Injected for tests, or by a host that already holds an encoder. */
+    readonly embedder?: Embedder;
+    /** Told when the encoder cannot load; ranking then stays lexical. */
+    readonly onError?: (error: unknown) => void;
+}
 interface SkillCaller {
     /** Stable id of the signed-in user, recorded by the host, never by pmcp. */
     readonly id: string;
@@ -21,6 +65,8 @@ interface SkillHttpOptions extends SkillServerOptions {
     readonly tiersFor?: (caller: SkillCaller) => readonly string[];
     /** Sent in WWW-Authenticate on a refused request, e.g. a resource metadata URL. */
     readonly challenge?: string;
+    /** Encode the catalog at start so find ranks by meaning across languages. */
+    readonly semantic?: SkillHttpSemanticOptions;
 }
 declare const DEFAULT_TIERS: readonly string[];
 declare function visibleTo(entries: readonly SkillEntry[], tiers: readonly string[]): SkillEntry[];
@@ -28,7 +74,9 @@ interface SkillHttpHandler {
     fetch(request: Request): Promise<Response>;
     /** Re-read the catalog, for a host that deploys new skill releases in place. */
     reload(): void;
+    /** Settles once the catalog is encoded, or at once when ranking is lexical. */
+    ready(): Promise<"semantic" | "lexical">;
 }
 declare function createSkillHttpHandler(options: SkillHttpOptions): SkillHttpHandler;
 
-export { DEFAULT_TIERS, type SkillCaller, type SkillHttpHandler, type SkillHttpOptions, createSkillHttpHandler, visibleTo };
+export { DEFAULT_MODEL_ID, DEFAULT_TIERS, Embedder, type SkillCaller, type SkillHttpHandler, type SkillHttpOptions, type SkillHttpSemanticOptions, createSkillHttpHandler, loadEmbedder, visibleTo };

package/dist/http.js

@@ -1,7 +1,13 @@
+import {
+  DEFAULT_MODEL_ID,
+  encodeEntries,
+  loadEmbedder
+} from "./chunk-NI2OLZPA.js";
+import "./chunk-ZLELYZHL.js";
 import {
   createSkillServer,
   readCatalog
-} from "./chunk-5TX2IAVD.js";
+} from "./chunk-QHFORYIN.js";
 
 // src/http.ts
 import {
@@ -17,6 +23,25 @@ function createSkillHttpHandler(options) {
   let all = load(options);
   const tiersFor = options.tiersFor ?? (() => DEFAULT_TIERS);
   const handlers = /* @__PURE__ */ new Map();
+  let embedder;
+  let encoded = /* @__PURE__ */ new Map();
+  let vectors;
+  const semantic = options.semantic;
+  const encode = async () => {
+    if (!semantic) return "lexical";
+    try {
+      embedder ??= semantic.embedder ?? await loadEmbedder(semantic.modelId, semantic) ?? void 0;
+      if (!embedder)
+        throw new Error("@huggingface/transformers is not installed");
+      encoded = await encodeEntries(embedder, all, encoded);
+      vectors = new Map([...encoded].map(([name, v]) => [name, v.vector]));
+      return "semantic";
+    } catch (error) {
+      semantic.onError?.(error);
+      return "lexical";
+    }
+  };
+  let ready = encode();
   const handlerFor = (tiers) => {
     const key = [...tiers].sort().join(",");
     const cached = handlers.get(key);
@@ -24,6 +49,7 @@ function createSkillHttpHandler(options) {
     const handler = createMcpHandler(
       () => createSkillServer({
         ...options,
+        ...embedder && vectors ? { embedder, vectors } : {},
         loadCatalog: () => visibleTo(all, tiers)
       })
     );
@@ -54,12 +80,17 @@ function createSkillHttpHandler(options) {
     reload() {
       all = load(options);
       handlers.clear();
-    }
+      vectors = void 0;
+      ready = encode();
+    },
+    ready: () => ready
   };
 }
 export {
+  DEFAULT_MODEL_ID,
   DEFAULT_TIERS,
   createSkillHttpHandler,
+  loadEmbedder,
   visibleTo
 };
 //# sourceMappingURL=http.js.map

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { I as IntentCache, S as SkillServerOptions, a as SkillTools } from './server-Dm71qZgM.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-Dm71qZgM.js';
+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 { McpServer } from '@modelcontextprotocol/server';

package/dist/index.js

@@ -1,7 +1,6 @@
 import {
   CONFIG_FILE,
   ConfigError,
-  DEFAULT_INTENT_CACHE_LIMIT,
   LOCK_FILE,
   ProjectError,
   TOOLS,
@@ -9,12 +8,15 @@ import {
   deriveName,
   doctor,
   findConfig,
-  openIntentCache,
   plan,
   project,
   readConfig,
   readSpec
-} from "./chunk-6TSHDCUY.js";
+} from "./chunk-GNJSZCRH.js";
+import {
+  DEFAULT_INTENT_CACHE_LIMIT,
+  openIntentCache
+} from "./chunk-ZLELYZHL.js";
 import {
   ASSET_KINDS,
   CATALOG_PAGE_MAX,
@@ -46,7 +48,7 @@ import {
   registerSkillsExtension,
   skillUri,
   withoutBody
-} from "./chunk-5TX2IAVD.js";
+} from "./chunk-QHFORYIN.js";
 export {
   ASSET_KINDS,
   CATALOG_PAGE_MAX,

package/dist/{server-Dm71qZgM.d.ts → server-wpYiAJ2n.d.ts}

@@ -56,7 +56,10 @@ interface FindResult {
 interface Embedder {
     readonly modelId: string;
     readonly dims: number;
+    /** Encodes an intent, the query side. */
     embed(text: string): Promise<Float32Array>;
+    /** Encodes a description, for models that write the two sides differently. */
+    embedPassage?(text: string): Promise<Float32Array>;
 }
 interface FindOptions {
     readonly entries: readonly SkillEntry[];

package/dist/stdio.js

@@ -3,8 +3,8 @@ import {
   main,
   resolveRoots,
   serve
-} from "./chunk-FXBLBKP6.js";
-import "./chunk-5TX2IAVD.js";
+} from "./chunk-POJOFL4L.js";
+import "./chunk-QHFORYIN.js";
 export {
   main,
   resolveRoots,

package/package.json

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