@modootoday/pmcp 0.7.0 → 0.8.0

package/dist/server-CLyCpwZb.d.ts

@@ -0,0 +1,352 @@
+import { S as SkillEntry, C as CatalogOptions, A as AssetKind } from './catalog-CS0j6-0U.js';
+import { z } from 'zod';
+
+/**
+ * The intent key and the cache contract.
+ *
+ * Separate from the sqlite implementation so that ranking, which needs the key
+ * and the interface, does not pull a bun-only module into a consumer running
+ * under node. Only `cache.ts` requires bun.
+ */
+interface IntentCacheStats {
+    readonly hits: number;
+    readonly misses: number;
+    /** Rows found for the key but written by a different model. */
+    readonly mismatched: number;
+    readonly rows: number;
+    /** Which sqlite builtin answered, or absent when there is no cache. */
+    readonly provider?: string;
+}
+interface IntentCache {
+    /** The cached vector for an intent, or null when nothing usable is stored. */
+    get(intent: string): Float32Array | null;
+    put(intent: string, vector: Float32Array): void;
+    stats(): IntentCacheStats;
+    close(): void;
+}
+/**
+ * Same question, differently typed. Case, punctuation and spacing only — the
+ * key has to survive a caller writing "How do I wire X?" and "how do i wire x".
+ */
+declare function normaliseIntent(intent: string): string;
+
+/**
+ * Ranking an intent against skill descriptions.
+ *
+ * Semantic when an embedder is supplied, lexical otherwise, and the answer says
+ * which. A caller that cannot tell the two apart cannot tell a degraded server
+ * from a working one.
+ */
+
+type Ranking = "semantic" | "lexical";
+interface Match {
+    readonly name: string;
+    readonly package: string;
+    readonly description: string;
+    readonly score: number;
+}
+interface FindResult {
+    readonly ranking: Ranking;
+    readonly matches: readonly Match[];
+}
+/**
+ * The encoder, supplied by the caller. There is no default and no bundled
+ * model: which model runs decides what the scores mean, so it is the consuming
+ * repository's declaration rather than this package's.
+ */
+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[];
+    readonly intent: string;
+    readonly limit?: number;
+    readonly embedder?: Embedder;
+    readonly cache?: IntentCache;
+    /** Precomputed description vectors, keyed by skill name. */
+    readonly vectors?: ReadonlyMap<string, Float32Array>;
+}
+declare const DEFAULT_FIND_LIMIT = 5;
+/**
+ * Token overlap and bigram Dice, averaged. Deterministic and dependency-free:
+ * this is the answer when there is no model, so it must never be the thing
+ * that fails.
+ */
+declare function lexicalScore(intent: string, description: string): number;
+/** Cosine over two equal-width vectors. Zero when either has no magnitude. */
+declare function cosine(a: Float32Array, b: Float32Array): number;
+/**
+ * Ranked matches, and which ranking produced them.
+ *
+ * Returns rather than loads: a search verb that also acts cannot be used to
+ * look, and the whole reason this server exists is that looking should be
+ * cheap.
+ */
+declare function find(options: FindOptions): Promise<FindResult>;
+
+/** The files one skill carries, with sizes and digests. */
+interface SkillFile {
+    /** Relative to the skill directory, with forward slashes. */
+    readonly path: string;
+    readonly bytes: number;
+    readonly sha256: string;
+}
+interface SkillFileListing {
+    readonly files: readonly SkillFile[];
+    readonly truncated: boolean;
+}
+/**
+ * Every file under a skill root, or the root itself when the asset is one file.
+ * node_modules and .git are never part of a skill.
+ */
+declare function listSkillFiles(root: string, limit?: number): SkillFileListing;
+
+/**
+ * Every file of one skill as fetchable links, so a host can write the skill to a
+ * local skills directory without routing its bytes through the model.
+ */
+
+interface BundleFile extends SkillFile {
+    readonly uri: string;
+    readonly mimeType: string;
+}
+interface SkillBundle {
+    readonly name: string;
+    readonly files: readonly BundleFile[];
+    readonly truncated: boolean;
+}
+declare function bundleSkill(entry: SkillEntry): SkillBundle;
+
+/**
+ * One MIME table for every surface that hands out skill files, so a file is text,
+ * image, audio or blob the same way through skill_read and through resources/read.
+ */
+/** The declared type of a path by extension, or null when the extension is unknown. */
+declare function mimeOf(path: string): string | null;
+/** True when the bytes decode as UTF-8 and encode back to themselves, without NUL. */
+declare function isUtf8Text(bytes: Uint8Array): boolean;
+type FileKind = "text" | "image" | "audio" | "blob";
+interface Classified {
+    readonly kind: FileKind;
+    readonly mimeType: string;
+}
+/**
+ * How a file goes out. A type that names text is still served as a blob when the
+ * bytes are not valid UTF-8, so a digest over them stays exact.
+ */
+declare function classify(path: string, bytes: Uint8Array): Classified;
+
+/**
+ * Turns a path a caller asked for into a file inside one skill. A path that
+ * leaves the skill, directly or through a link, is refused.
+ */
+
+type FileRefusal = {
+    readonly ok: false;
+    readonly error: "path_outside_skill" | "no_such_file";
+    readonly detail: string;
+};
+
+/**
+ * One skill file's bytes, typed. Text stays text; images, audio and other binary
+ * go out as base64 so nothing is corrupted on the way. Nothing is ever executed.
+ */
+
+/** Largest file returned whole. A skill needing more should split it. */
+declare const READ_BUDGET_BYTES: number;
+interface SkillFileContent {
+    readonly ok: true;
+    readonly name: string;
+    readonly path: string;
+    readonly bytes: number;
+    readonly sha256: string;
+    readonly mimeType: string;
+    readonly kind: FileKind;
+    /** Set when kind is text. */
+    readonly text?: string;
+    /** Base64, set when kind is not text. */
+    readonly blob?: string;
+}
+type ReadResult = SkillFileContent | FileRefusal | {
+    readonly ok: false;
+    readonly error: "over_budget";
+    readonly detail: string;
+};
+declare function readSkillFile(entry: SkillEntry, wanted?: string, budget?: number): ReadResult;
+
+/**
+ * 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,
+ * so structuredContent cannot drift from what a client validates it against.
+ */
+
+declare const catalogItemSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    tier: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        agent: "agent";
+        skill: "skill";
+        hook: "hook";
+        mcp: "mcp";
+    }>>;
+}, z.core.$strip>;
+declare const catalogResponseSchema: z.ZodObject<{
+    count: z.ZodNumber;
+    page: z.ZodNumber;
+    totalPages: z.ZodNumber;
+    hasNext: z.ZodBoolean;
+    packages: z.ZodArray<z.ZodObject<{
+        package: z.ZodString;
+        skills: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            tier: z.ZodOptional<z.ZodString>;
+            kind: z.ZodOptional<z.ZodEnum<{
+                agent: "agent";
+                skill: "skill";
+                hook: "hook";
+                mcp: "mcp";
+            }>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const findResultSchema: z.ZodObject<{
+    ranking: z.ZodEnum<{
+        semantic: "semantic";
+        lexical: "lexical";
+    }>;
+    matches: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        package: z.ZodString;
+        description: z.ZodString;
+        score: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const describeResponseSchema: z.ZodObject<{
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        agent: "agent";
+        skill: "skill";
+        hook: "hook";
+        mcp: "mcp";
+    }>;
+    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>>]>>;
+    frontmatter: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        bytes: z.ZodNumber;
+        sha256: z.ZodString;
+    }, z.core.$strip>>;
+    filesTruncated: z.ZodBoolean;
+}, z.core.$strip>;
+declare const bundleResponseSchema: z.ZodObject<{
+    name: z.ZodString;
+    truncated: z.ZodBoolean;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        bytes: z.ZodNumber;
+        sha256: z.ZodString;
+        uri: z.ZodString;
+        mimeType: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type CatalogItem = z.infer<typeof catalogItemSchema>;
+type CatalogResponse = z.infer<typeof catalogResponseSchema>;
+type DescribeResponse = z.infer<typeof describeResponseSchema>;
+
+/**
+ * The catalog operations the tools speak, as plain functions.
+ *
+ * The point of the server is that a session's startup cost does not grow with
+ * the number of skills installed: the host lists a fixed set of tools whatever
+ * the catalog holds, and a body is read only when one is asked for.
+ */
+
+/** How many files skill_describe lists before saying the rest were cut. */
+declare const DESCRIBE_FILE_LIMIT = 200;
+declare const CATALOG_PAGE_SIZE = 8;
+declare const CATALOG_PAGE_MAX = 20;
+/** A kind filter value: one kind, or every kind. */
+type KindFilter = AssetKind | "any";
+/**
+ * Equality filters over catalog fields. Unset keys match everything except
+ * kind, which defaults to skill so a search for a skill never returns a hook.
+ */
+interface SkillFilters {
+    readonly kind?: KindFilter;
+    readonly tier?: string;
+    readonly package?: string;
+    readonly level?: string;
+    readonly domain?: string;
+    readonly medium?: string;
+}
+interface SkillServerOptions extends CatalogOptions {
+    readonly embedder?: Embedder;
+    readonly cache?: IntentCache;
+    readonly vectors?: ReadonlyMap<string, Float32Array>;
+    /** Injected for tests. Reads the catalog off disk otherwise. */
+    readonly loadCatalog?: (options: CatalogOptions) => SkillEntry[];
+}
+
+interface CallResponse {
+    readonly name: string;
+    readonly body: string;
+    /** Files the skill carries besides its body, for skill_read and resources/read. */
+    readonly files: readonly BundleFile[];
+    readonly filesTruncated: boolean;
+}
+/**
+ * The catalog, the search and the read, as plain functions.
+ *
+ * Separate from the MCP wiring so they can be exercised without a transport,
+ * and so a consumer that wants them from a hook or a script is not made to
+ * speak a protocol to get them.
+ */
+declare function createSkillTools(options: SkillServerOptions): {
+    /**
+     * Grouped, and without bodies. The cheap overview and the search's miss
+     * path. Paged by package so a large catalog never arrives in one answer.
+     */
+    catalog(request?: {
+        page?: number;
+        pageSize?: number;
+        tier?: string;
+        kind?: KindFilter;
+    }): CatalogResponse;
+    /** Ranked names. Returns; never loads a body. */
+    find(intent: string, limit?: number, filters?: SkillFilters): Promise<FindResult>;
+    /** Every property of one skill and the files it carries, without bodies. */
+    describe(name: string): DescribeResponse | null;
+    /**
+     * One file inside a skill's directory. Paths that leave the directory,
+     * directly or through a link, are refused; nothing is ever executed.
+     */
+    read(name: string, path?: string): ReadResult | {
+        ok: false;
+        error: "unknown_skill";
+        detail: string;
+    };
+    /** Every file of one skill as links; the bytes stay out of the answer. */
+    bundle(name: string): SkillBundle | null;
+    /** One body, at the moment it is needed, and the other files it carries. */
+    call(name: string): CallResponse | null;
+    /** The catalog entry for a name, among those this caller may see. */
+    entry: (name: string) => SkillEntry | null;
+    /** Drops the memoised catalog, so the next call re-reads the tree. */
+    refresh(): void;
+    entries: () => Omit<SkillEntry, "path">[];
+    /** The catalog with paths, for the Skills extension. The same array until refresh. */
+    skills: () => readonly SkillEntry[];
+};
+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 };

package/dist/stdio.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { C as CatalogOptions } from './catalog-5v7jrGwP.js';
+import { C as CatalogOptions } from './catalog-CS0j6-0U.js';
 
 /**
  * The stdio entry a host launches.
@@ -11,7 +11,11 @@ import { C as CatalogOptions } from './catalog-5v7jrGwP.js';
 
 /** `node_modules` roots to walk, from argv or from the working directory. */
 declare function resolveRoots(argv: readonly string[], cwd: string): string[];
-declare function serve(catalog: CatalogOptions): void;
+interface ServeOptions {
+    /** One prompt per skill, for hosts that offer prompts as commands. */
+    readonly prompts?: boolean;
+}
+declare function serve(catalog: CatalogOptions, serving?: ServeOptions): void;
 declare function main(argv?: readonly string[]): void;
 
-export { main, resolveRoots, serve };
+export { type ServeOptions, main, resolveRoots, serve };

package/dist/stdio.js

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

package/package.json

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

package/dist/server-wpYiAJ2n.d.ts

@@ -1,210 +0,0 @@
-import { S as SkillEntry, C as CatalogOptions, A as AssetKind } from './catalog-5v7jrGwP.js';
-
-/**
- * The intent key and the cache contract.
- *
- * Separate from the sqlite implementation so that ranking, which needs the key
- * and the interface, does not pull a bun-only module into a consumer running
- * under node. Only `cache.ts` requires bun.
- */
-interface IntentCacheStats {
-    readonly hits: number;
-    readonly misses: number;
-    /** Rows found for the key but written by a different model. */
-    readonly mismatched: number;
-    readonly rows: number;
-    /** Which sqlite builtin answered, or absent when there is no cache. */
-    readonly provider?: string;
-}
-interface IntentCache {
-    /** The cached vector for an intent, or null when nothing usable is stored. */
-    get(intent: string): Float32Array | null;
-    put(intent: string, vector: Float32Array): void;
-    stats(): IntentCacheStats;
-    close(): void;
-}
-/**
- * Same question, differently typed. Case, punctuation and spacing only — the
- * key has to survive a caller writing "How do I wire X?" and "how do i wire x".
- */
-declare function normaliseIntent(intent: string): string;
-
-/**
- * Ranking an intent against skill descriptions.
- *
- * Semantic when an embedder is supplied, lexical otherwise, and the answer says
- * which. A caller that cannot tell the two apart cannot tell a degraded server
- * from a working one.
- */
-
-type Ranking = "semantic" | "lexical";
-interface Match {
-    readonly name: string;
-    readonly package: string;
-    readonly description: string;
-    readonly score: number;
-}
-interface FindResult {
-    readonly ranking: Ranking;
-    readonly matches: readonly Match[];
-}
-/**
- * The encoder, supplied by the caller. There is no default and no bundled
- * model: which model runs decides what the scores mean, so it is the consuming
- * repository's declaration rather than this package's.
- */
-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[];
-    readonly intent: string;
-    readonly limit?: number;
-    readonly embedder?: Embedder;
-    readonly cache?: IntentCache;
-    /** Precomputed description vectors, keyed by skill name. */
-    readonly vectors?: ReadonlyMap<string, Float32Array>;
-}
-declare const DEFAULT_FIND_LIMIT = 5;
-/**
- * Token overlap and bigram Dice, averaged. Deterministic and dependency-free:
- * this is the answer when there is no model, so it must never be the thing
- * that fails.
- */
-declare function lexicalScore(intent: string, description: string): number;
-/** Cosine over two equal-width vectors. Zero when either has no magnitude. */
-declare function cosine(a: Float32Array, b: Float32Array): number;
-/**
- * Ranked matches, and which ranking produced them.
- *
- * Returns rather than loads: a search verb that also acts cannot be used to
- * look, and the whole reason this server exists is that looking should be
- * cheap.
- */
-declare function find(options: FindOptions): Promise<FindResult>;
-
-/**
- * The five tools, and nothing else.
- *
- * The point of the server is that a session's startup cost does not grow with
- * the number of skills installed: the host lists five tools whatever the
- * catalog holds, and a body is read only when one is asked for.
- */
-
-/** Largest file skill_read returns. A skill needing more should split it. */
-declare const READ_BUDGET_BYTES: number;
-/** How many files skill_describe lists before saying the rest were cut. */
-declare const DESCRIBE_FILE_LIMIT = 200;
-declare const CATALOG_PAGE_SIZE = 8;
-declare const CATALOG_PAGE_MAX = 20;
-/** A kind filter value: one kind, or every kind. */
-type KindFilter = AssetKind | "any";
-/**
- * Equality filters over catalog fields. Unset keys match everything except
- * kind, which defaults to skill so a search for a skill never returns a hook.
- */
-interface SkillFilters {
-    readonly kind?: KindFilter;
-    readonly tier?: string;
-    readonly package?: string;
-    readonly level?: string;
-    readonly domain?: string;
-    readonly medium?: string;
-}
-type ReadResult = {
-    readonly ok: true;
-    readonly name: string;
-    readonly path: string;
-    readonly bytes: number;
-    readonly sha256: string;
-    readonly text: string;
-} | {
-    readonly ok: false;
-    readonly error: string;
-    readonly detail: string;
-};
-interface SkillServerOptions extends CatalogOptions {
-    readonly embedder?: Embedder;
-    readonly cache?: IntentCache;
-    readonly vectors?: ReadonlyMap<string, Float32Array>;
-    /** Injected for tests. Reads the catalog off disk otherwise. */
-    readonly loadCatalog?: (options: CatalogOptions) => SkillEntry[];
-}
-interface CatalogResponse {
-    readonly count: number;
-    readonly page: number;
-    readonly totalPages: number;
-    readonly hasNext: boolean;
-    readonly packages: readonly {
-        readonly package: string;
-        readonly skills: readonly CatalogItem[];
-    }[];
-}
-/** One catalog line. `kind` appears only for an asset that is not a skill. */
-interface CatalogItem {
-    readonly name: string;
-    readonly description: string;
-    readonly tier?: string;
-    readonly kind?: AssetKind;
-}
-interface CallResponse {
-    readonly name: string;
-    readonly body: string;
-}
-/**
- * The catalog, the search and the read, as plain functions.
- *
- * Separate from the MCP wiring so they can be exercised without a transport,
- * and so a consumer that wants them from a hook or a script is not made to
- * speak a protocol to get them.
- */
-declare function createSkillTools(options: SkillServerOptions): {
-    /**
-     * Grouped, and without bodies. The cheap overview and the search's miss
-     * path. Paged by package so a large catalog never arrives in one answer.
-     */
-    catalog(request?: {
-        page?: number;
-        pageSize?: number;
-        tier?: string;
-        kind?: KindFilter;
-    }): CatalogResponse;
-    /** Ranked names. Returns; never loads a body. */
-    find(intent: string, limit?: number, filters?: SkillFilters): Promise<FindResult>;
-    /** Every property of one skill and the files it carries, without bodies. */
-    describe(name: string): {
-        name: string;
-        kind: "agent" | "skill" | "hook" | "mcp";
-        package: string;
-        description: string;
-        tier: string | undefined;
-        metadata: Readonly<Record<string, string | readonly string[]>>;
-        frontmatter: string;
-        files: {
-            path: string;
-            bytes: number;
-            sha256: string;
-        }[];
-        filesTruncated: boolean;
-    } | null;
-    /**
-     * One file inside a skill's directory. Paths that leave the directory,
-     * directly or through a link, are refused; nothing is ever executed.
-     */
-    read(name: string, path?: string): ReadResult;
-    /** One body, at the moment it is needed. */
-    call(name: string): CallResponse | null;
-    /** Drops the memoised catalog, so the next call re-reads the tree. */
-    refresh(): void;
-    entries: () => Omit<SkillEntry, "path">[];
-    /** The catalog with paths, for the Skills extension. The same array until refresh. */
-    skills: () => readonly SkillEntry[];
-};
-type SkillTools = ReturnType<typeof createSkillTools>;
-
-export { CATALOG_PAGE_MAX as C, DEFAULT_FIND_LIMIT as D, type Embedder as E, type FindOptions as F, type IntentCache as I, type KindFilter as K, type Match as M, 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, DESCRIBE_FILE_LIMIT as f, type FindResult as g, type IntentCacheStats as h, type Ranking as i, type ReadResult as j, type SkillFilters as k, cosine as l, createSkillTools as m, find as n, lexicalScore as o, normaliseIntent as p };