@sriinnu/kosha-discovery 1.0.0 → 1.2.0

package/dist/mcp-server.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+/**
+ * kosha-discovery — MCP server (stdio transport, protocol 2024-11-05).
+ *
+ * Exposes the local kosha registry as MCP tools so AI agents can query
+ * model pricing, routing, and health without HTTP.
+ *
+ * Tools:
+ *   kosha_query_models      — list / filter models
+ *   kosha_cheapest_model    — cheapest model meeting requirements
+ *   kosha_model_detail      — full detail for one model
+ *   kosha_model_routes      — all provider routes for a model
+ *   kosha_resolve_alias     — alias → canonical ID
+ *   kosha_provider_health   — provider auth + error status
+ * @module
+ */
+import { computeContextStrategy } from "./context-strategy.js";
+import { ModelRegistry } from "./registry.js";
+// ---------------------------------------------------------------------------
+// Tool definitions (MCP schema)
+// ---------------------------------------------------------------------------
+const TOOLS = [
+    {
+        name: "kosha_query_models",
+        description: "List AI models from the local kosha registry. Optionally filter by provider, mode, or capability tag. Returns id, provider, name, mode, context window, capabilities, and pricing.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                provider: { type: "string", description: "Provider ID (e.g. anthropic, openai, groq, openrouter)" },
+                mode: {
+                    type: "string",
+                    enum: ["chat", "embedding", "image", "video", "audio", "moderation", "rerank"],
+                    description: "Primary model mode",
+                },
+                capability: {
+                    type: "string",
+                    description: "Capability tag (e.g. vision, tool_use, code, reasoning)",
+                },
+                limit: { type: "number", description: "Max results to return (default 20)" },
+            },
+        },
+    },
+    {
+        name: "kosha_cheapest_model",
+        description: "Find the cheapest AI model that meets your requirements. Returns ranked matches with per-million token pricing. Use this before routing a request to pick the most cost-effective option.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                capability: {
+                    type: "string",
+                    description: "Required capability (e.g. tool_use, vision, code, reasoning)",
+                },
+                min_context_k: {
+                    type: "number",
+                    description: "Minimum context window in thousands of tokens (e.g. 128 means 128k)",
+                },
+                provider: { type: "string", description: "Pin to a specific provider" },
+                limit: { type: "number", description: "Number of ranked results (default 5)" },
+            },
+        },
+    },
+    {
+        name: "kosha_model_detail",
+        description: "Get full details for a specific model — pricing, capabilities, context window, tool dialect, structured output modes, status, and deprecation info.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                model: {
+                    type: "string",
+                    description: "Model ID or alias (e.g. sonnet, claude-sonnet-4-6, gpt-4o, deepseek-v3)",
+                },
+            },
+            required: ["model"],
+        },
+    },
+    {
+        name: "kosha_model_routes",
+        description: "List all serving-layer routes for a model (direct provider, OpenRouter, Bedrock, Vertex, etc.) with pricing per route. Useful for finding the cheapest or most available path to a specific model.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                model: { type: "string", description: "Model ID or alias" },
+            },
+            required: ["model"],
+        },
+    },
+    {
+        name: "kosha_resolve_alias",
+        description: "Resolve a model alias or short name to its canonical ID and provider.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                alias: {
+                    type: "string",
+                    description: "Short name or alias (e.g. sonnet, opus, haiku, gpt-4o-mini, gemini-flash)",
+                },
+            },
+            required: ["alias"],
+        },
+    },
+    {
+        name: "kosha_provider_health",
+        description: "Get authentication and health status for all discovered providers. Shows which providers are active, which need credentials, and any recent discovery errors.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                provider: { type: "string", description: "Filter to a specific provider ID" },
+            },
+        },
+    },
+    {
+        name: "kosha_context_strategy",
+        description: "Advise on context management for a long-running conversation. Given a model and current token usage, returns ranked options (continue, enable prompt cache, compact + continue, switch to long-context tier, switch model, batch offload) with rough cost-per-turn math. Useful before deciding whether to summarize, swap models, or just keep going.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                model: { type: "string", description: "Model ID or alias the caller is currently using" },
+                current_tokens: { type: "number", description: "Approximate token count of the conversation so far" },
+                expected_output_tokens: {
+                    type: "number",
+                    description: "Tokens the next reply is expected to produce (default 1024)",
+                },
+                expected_remaining_turns: {
+                    type: "number",
+                    description: "How many more turns the caller plans (default 5)",
+                },
+            },
+            required: ["model", "current_tokens"],
+        },
+    },
+];
+// ---------------------------------------------------------------------------
+// Registry — lazy-load on first tool call so starting the MCP server has no
+// filesystem/network side effects until a client actually asks for data.
+// ---------------------------------------------------------------------------
+let registryInstance = null;
+let registryReady = null;
+async function loadRegistry() {
+    const reg = new ModelRegistry();
+    await reg.discover();
+    registryInstance = reg;
+    return reg;
+}
+async function getRegistry() {
+    if (registryInstance)
+        return registryInstance;
+    registryReady ??= loadRegistry();
+    return registryReady;
+}
+// ---------------------------------------------------------------------------
+// Tool handlers
+// ---------------------------------------------------------------------------
+async function callTool(name, args) {
+    const reg = await getRegistry();
+    switch (name) {
+        case "kosha_query_models": {
+            const models = reg.models({
+                provider: args.provider,
+                mode: args.mode,
+                capability: args.capability,
+            });
+            const limit = typeof args.limit === "number" ? args.limit : 20;
+            return models.slice(0, limit).map((m) => ({
+                id: m.id,
+                provider: m.provider,
+                name: m.name,
+                mode: m.mode,
+                contextWindow: m.contextWindow,
+                capabilities: m.capabilities,
+                pricing: m.pricing ?? null,
+            }));
+        }
+        case "kosha_cheapest_model": {
+            const minContext = typeof args.min_context_k === "number" ? args.min_context_k * 1_000 : undefined;
+            const result = reg.cheapestModels({
+                mode: "chat",
+                capability: args.capability,
+                provider: args.provider,
+                limit: typeof args.limit === "number" ? args.limit : 5,
+            });
+            const matches = minContext
+                ? result.matches.filter((m) => m.model.contextWindow >= minContext)
+                : result.matches;
+            return {
+                matches: matches.map((m) => ({
+                    id: m.model.id,
+                    provider: m.model.provider,
+                    name: m.model.name,
+                    contextWindow: m.model.contextWindow,
+                    pricing: m.model.pricing ?? null,
+                    score: m.score,
+                    priceMetric: m.priceMetric,
+                })),
+                missingCredentials: result.missingCredentials.map((c) => c.providerId),
+            };
+        }
+        case "kosha_model_detail": {
+            const model = reg.model(args.model);
+            if (!model)
+                return { error: `model '${args.model}' not found` };
+            const provider = reg.provider(model.provider);
+            return {
+                ...model,
+                baseUrl: provider?.baseUrl,
+                authenticated: provider?.authenticated ?? false,
+            };
+        }
+        case "kosha_model_routes": {
+            const routes = reg.modelRouteInfo(args.model);
+            if (routes.length === 0)
+                return { error: `model '${args.model}' not found` };
+            return routes.map((r) => ({
+                provider: r.provider,
+                modelId: r.model.id,
+                baseUrl: r.baseUrl,
+                isDirect: r.isDirect,
+                isPreferred: r.isPreferred,
+                pricing: r.model.pricing ?? null,
+                originPricing: r.model.originPricing ?? null,
+            }));
+        }
+        case "kosha_resolve_alias": {
+            const resolved = reg.resolve(args.alias);
+            const model = reg.model(resolved);
+            return {
+                alias: args.alias,
+                resolved,
+                isAlias: resolved !== args.alias,
+                provider: model?.provider ?? null,
+                name: model?.name ?? null,
+            };
+        }
+        case "kosha_provider_health": {
+            const providers = reg.providers_list();
+            const errors = reg.discoveryErrors();
+            const errorByProvider = new Map(errors.map((e) => [e.providerId, e.error]));
+            const list = args.provider
+                ? providers.filter((p) => p.id === args.provider)
+                : providers;
+            return list.map((p) => ({
+                id: p.id,
+                name: p.name,
+                authenticated: p.authenticated,
+                credentialSource: p.credentialSource ?? null,
+                modelCount: p.models.length,
+                lastRefreshed: p.lastRefreshed ?? null,
+                lastError: errorByProvider.get(p.id) ?? null,
+            }));
+        }
+        case "kosha_context_strategy": {
+            const modelId = args.model;
+            if (!modelId)
+                return { error: "model is required" };
+            const currentTokens = typeof args.current_tokens === "number" ? args.current_tokens : undefined;
+            if (currentTokens === undefined || currentTokens < 0) {
+                return { error: "current_tokens must be a non-negative number" };
+            }
+            const model = reg.model(modelId);
+            if (!model)
+                return { error: `model '${modelId}' not found` };
+            const candidates = reg
+                .cheapestModels({ mode: "chat", limit: 20 })
+                .matches.map((m) => m.model);
+            return computeContextStrategy({
+                model,
+                currentTokens,
+                expectedRemainingTurns: typeof args.expected_remaining_turns === "number" ? args.expected_remaining_turns : undefined,
+                expectedOutputTokens: typeof args.expected_output_tokens === "number" ? args.expected_output_tokens : undefined,
+                candidateAlternatives: candidates,
+            });
+        }
+        default:
+            throw new Error(`unknown tool: ${name}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Stdio JSON-RPC loop
+// ---------------------------------------------------------------------------
+function send(msg) {
+    process.stdout.write(`${JSON.stringify(msg)}\n`);
+}
+function respond(id, result) {
+    send({ jsonrpc: "2.0", id: id ?? null, result });
+}
+function respondError(id, code, message) {
+    send({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
+}
+async function handleMessage(msg) {
+    const { id, method, params } = msg;
+    // Notifications carry no id — no response expected.
+    if (!method || method.startsWith("notifications/"))
+        return;
+    switch (method) {
+        case "initialize":
+            respond(id, {
+                protocolVersion: "2024-11-05",
+                capabilities: { tools: {} },
+                serverInfo: { name: "kosha", version: "1.0.0" },
+            });
+            return;
+        case "tools/list":
+            respond(id, { tools: TOOLS });
+            return;
+        case "tools/call": {
+            const { name, arguments: args = {} } = params;
+            try {
+                const result = await callTool(name, args);
+                respond(id, { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                respondError(id, -32603, message);
+            }
+            return;
+        }
+        default:
+            respondError(id, -32601, `method not found: ${method}`);
+    }
+}
+let buffer = "";
+process.stdin.setEncoding("utf-8");
+process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            handleMessage(JSON.parse(trimmed)).catch((err) => {
+                process.stderr.write(`[kosha-mcp] ${err}\n`);
+            });
+        }
+        catch {
+            // malformed JSON — ignore
+        }
+    }
+});
+process.stdin.on("end", () => process.exit(0));
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"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"}

package/dist/provider-catalog.d.ts

@@ -6,7 +6,7 @@
  * versioned schema do not drift apart.
  * @module
  */
-import type { KoshaConfig, ProviderOrigin, ProviderTransport } from "./types.js";
+import type { KoshaConfig, ProviderCacheBehavior, ProviderOrigin, ProviderTransport } from "./types.js";
 /**
  * Stable provider descriptor used by normalization and v1 schema emission.
  */
@@ -27,10 +27,14 @@ export interface ProviderDescriptor {
     transport: ProviderTransport;
     /** Default base URL used by the built-in discoverer. */
     defaultBaseUrl: string;
-    /** Whether the provider normally requires credentials. */
+    /** Whether model discovery normally requires credentials. */
     credentialRequired: boolean;
+    /** Whether execution/model requests require credentials; defaults to `credentialRequired`. */
+    executionCredentialRequired?: boolean;
     /** Environment variables that satisfy the provider credential requirement. */
     credentialEnvVars: string[];
+    /** The single env var that `fallbackRegistryCredential` reads for this provider. */
+    primaryCredentialEnvVar?: string;
     /**
      * Minimum prompt-prefix size (in tokens) required for the provider's prompt
      * cache to engage. Only set when the provider publishes a documented floor.
@@ -38,6 +42,12 @@ export interface ProviderDescriptor {
      * consumer should fall back to its own conservative default in that case.
      */
     minCachePrefixTokens?: number;
+    /**
+     * Prompt-cache TTL semantics for the provider. Undefined means the policy
+     * has not been curated yet — distinct from `{ mode: "none" }` which asserts
+     * the provider documents no prompt cache.
+     */
+    cacheBehavior?: ProviderCacheBehavior;
 }
 /**
  * Canonical provider catalog.
@@ -62,6 +72,13 @@ export declare function listProviderDescriptors(): ProviderDescriptor[];
  * Read provider config using canonical IDs and accepted aliases.
  */
 export declare function getProviderConfig(config: KoshaConfig | undefined, providerId: string | undefined): NonNullable<KoshaConfig["providers"]>[string] | undefined;
+/** Return true when model execution through this provider needs auth. */
+export declare function providerExecutionCredentialRequired(descriptor: Pick<ProviderDescriptor, "credentialRequired" | "executionCredentialRequired">): boolean;
+/**
+ * Return the curated prompt-cache behavior for a provider, or `undefined`
+ * if the policy has not been curated yet.
+ */
+export declare function getProviderCacheBehavior(providerId: string | undefined): ProviderCacheBehavior | undefined;
 /**
  * True when the provider is a local runtime.
  */

package/dist/provider-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-catalog.d.ts","sourceRoot":"","sources":["../src/provider-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,MAAM,EAAE,cAAc,CAAC;IACvB,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,SAAS,EAAE,iBAAiB,CAAC;IAC7B,wDAAwD;IACxD,cAAc,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,kBAAkB,EAAE,OAAO,CAAC;IAC5B,8EAA8E;IAC9E,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,kBAAkB,EA6QhD,CAAC;AAWX;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGtF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CAGpG;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,kBAAkB,EAAE,CAE9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC5B,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,CAW3D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEvE"}
+{"version":3,"file":"provider-catalog.d.ts","sourceRoot":"","sources":["../src/provider-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAExG;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,MAAM,EAAE,cAAc,CAAC;IACvB,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,SAAS,EAAE,iBAAiB,CAAC;IAC7B,wDAAwD;IACxD,cAAc,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,kBAAkB,EAAE,OAAO,CAAC;IAC5B,8FAA8F;IAC9F,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,8EAA8E;IAC9E,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,oFAAoF;IACpF,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAC;CACtC;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,kBAAkB,EA0WhD,CAAC;AAWX;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGtF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CAGpG;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,kBAAkB,EAAE,CAE9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC5B,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,CAW3D;AAED,yEAAyE;AACzE,wBAAgB,mCAAmC,CAClD,UAAU,EAAE,IAAI,CAAC,kBAAkB,EAAE,oBAAoB,GAAG,6BAA6B,CAAC,GACxF,OAAO,CAET;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,qBAAqB,GAAG,SAAS,CAE1G;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEvE"}