@namingsignal/mcp 0.2.0

package/dist/core/usage.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BudgetGuard = exports.BudgetExceededError = exports.UsageLedger = void 0;
+exports.estimateModelCost = estimateModelCost;
+exports.checkBudget = checkBudget;
+exports.assertWithinBudget = assertWithinBudget;
+const ZERO_USAGE = {
+    providerCalls: 0,
+    modelCalls: 0,
+    domainRequests: 0,
+    namespaceRequests: 0,
+    searchQueries: 0,
+    fetchedPages: 0,
+    inputTokens: 0,
+    cachedInputTokens: 0,
+    reasoningTokens: 0,
+    outputTokens: 0,
+    estimatedUsd: 0,
+    cacheHits: 0,
+    retries: 0,
+    failures: 0,
+    latencyMs: 0,
+    events: 0,
+};
+function finiteNonNegative(value) {
+    return typeof value === "number" && Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+function eventCost(event) {
+    if (event.estimatedUsd !== undefined)
+        return finiteNonNegative(event.estimatedUsd);
+    if (event.kind === "model" && event.pricing)
+        return estimateModelCost(event, event.pricing);
+    return 0;
+}
+function addUsage(left, right) {
+    return {
+        providerCalls: left.providerCalls + finiteNonNegative(right.providerCalls),
+        modelCalls: left.modelCalls + finiteNonNegative(right.modelCalls),
+        domainRequests: left.domainRequests + finiteNonNegative(right.domainRequests),
+        namespaceRequests: left.namespaceRequests + finiteNonNegative(right.namespaceRequests),
+        searchQueries: left.searchQueries + finiteNonNegative(right.searchQueries),
+        fetchedPages: left.fetchedPages + finiteNonNegative(right.fetchedPages),
+        inputTokens: left.inputTokens + finiteNonNegative(right.inputTokens),
+        cachedInputTokens: left.cachedInputTokens + finiteNonNegative(right.cachedInputTokens),
+        reasoningTokens: left.reasoningTokens + finiteNonNegative(right.reasoningTokens),
+        outputTokens: left.outputTokens + finiteNonNegative(right.outputTokens),
+        estimatedUsd: left.estimatedUsd + finiteNonNegative(right.estimatedUsd),
+        cacheHits: left.cacheHits + finiteNonNegative(right.cacheHits),
+        retries: left.retries + finiteNonNegative(right.retries),
+        failures: left.failures + finiteNonNegative(right.failures),
+        latencyMs: left.latencyMs + finiteNonNegative(right.latencyMs),
+        events: left.events + finiteNonNegative(right.events),
+    };
+}
+function eventToUsage(event) {
+    const calls = event.calls ?? 1;
+    const requests = event.requests ?? calls;
+    return {
+        ...ZERO_USAGE,
+        providerCalls: event.kind === "model" ? calls : 0,
+        modelCalls: event.kind === "model" ? calls : 0,
+        domainRequests: event.kind === "domain" ? requests : 0,
+        namespaceRequests: event.kind === "namespace" ? requests : 0,
+        searchQueries: event.searchQueries ?? (event.kind === "search" ? requests : 0),
+        fetchedPages: event.fetchedPages ?? 0,
+        inputTokens: finiteNonNegative(event.inputTokens),
+        cachedInputTokens: finiteNonNegative(event.cachedInputTokens),
+        reasoningTokens: finiteNonNegative(event.reasoningTokens),
+        outputTokens: finiteNonNegative(event.outputTokens),
+        estimatedUsd: eventCost(event),
+        cacheHits: finiteNonNegative(event.cacheHits),
+        retries: finiteNonNegative(event.retries),
+        failures: finiteNonNegative(event.failures),
+        latencyMs: finiteNonNegative(event.latencyMs),
+        events: 1,
+    };
+}
+function estimateModelCost(usageOrInput, pricingOrOutput, maybePricing, maybeCached = 0, maybeReasoning = 0) {
+    const usage = typeof usageOrInput === "number"
+        ? {
+            inputTokens: usageOrInput,
+            outputTokens: typeof pricingOrOutput === "number" ? pricingOrOutput : 0,
+            cachedInputTokens: maybeCached,
+            reasoningTokens: maybeReasoning,
+        }
+        : usageOrInput;
+    const pricing = (typeof pricingOrOutput === "object" ? pricingOrOutput : maybePricing);
+    if (!pricing)
+        throw new TypeError("Model pricing is required.");
+    const input = finiteNonNegative(usage.inputTokens);
+    const cached = Math.min(input, finiteNonNegative(usage.cachedInputTokens));
+    const uncached = Math.max(0, input - cached);
+    const output = finiteNonNegative(usage.outputTokens);
+    const reasoning = finiteNonNegative(usage.reasoningTokens);
+    const cost = (uncached * finiteNonNegative(pricing.inputPerMillionUsd)) / 1_000_000 +
+        (cached * finiteNonNegative(pricing.cachedInputPerMillionUsd ?? pricing.inputPerMillionUsd)) / 1_000_000 +
+        (output * finiteNonNegative(pricing.outputPerMillionUsd)) / 1_000_000 +
+        (reasoning * finiteNonNegative(pricing.reasoningPerMillionUsd ?? pricing.outputPerMillionUsd)) / 1_000_000;
+    return cost;
+}
+class UsageLedger {
+    eventsInternal = [];
+    now;
+    sequence = 0;
+    constructor(options = {}) {
+        this.now = options.now ?? (() => new Date());
+    }
+    record(event) {
+        if (!event || !event.kind || !event.provider || !event.task) {
+            throw new TypeError("Usage events require kind, provider, and task.");
+        }
+        this.sequence += 1;
+        const recorded = {
+            ...event,
+            id: event.id ?? `usage_${this.sequence}`,
+            occurredAt: event.occurredAt ?? this.now().toISOString(),
+            estimatedUsd: eventCost(event),
+        };
+        this.eventsInternal.push(Object.freeze(recorded));
+        return recorded;
+    }
+    recordModel(event) {
+        return this.record({ ...event, kind: "model" });
+    }
+    recordDomain(provider, task, requests = 1, extra = {}) {
+        return this.record({ ...extra, provider, task, requests, kind: "domain" });
+    }
+    recordNamespace(provider, task, requests = 1, extra = {}) {
+        return this.record({ ...extra, provider, task, requests, kind: "namespace" });
+    }
+    getEvents() {
+        return this.eventsInternal.map((event) => ({ ...event }));
+    }
+    snapshot() {
+        return this.eventsInternal.reduce((summary, event) => addUsage(summary, eventToUsage(event)), { ...ZERO_USAGE });
+    }
+    merge(other) {
+        const events = other instanceof UsageLedger ? other.getEvents() : other;
+        for (const event of events)
+            this.record({ ...event, id: undefined });
+        return this;
+    }
+    clear() {
+        this.eventsInternal.length = 0;
+    }
+    toJSON() {
+        return { ...this.snapshot(), eventLog: this.getEvents() };
+    }
+}
+exports.UsageLedger = UsageLedger;
+function usageFrom(input) {
+    if (input instanceof UsageLedger)
+        return input.snapshot();
+    if ("kind" in input && "provider" in input && "task" in input)
+        return eventToUsage(input);
+    return addUsage({ ...ZERO_USAGE }, input);
+}
+const LIMIT_METRICS = [
+    { limit: "maxProviderCalls", actual: (usage) => usage.providerCalls },
+    { limit: "maxModelCalls", actual: (usage) => usage.modelCalls },
+    { limit: "maxDomainRequests", actual: (usage) => usage.domainRequests },
+    { limit: "maxNamespaceRequests", actual: (usage) => usage.namespaceRequests },
+    { limit: "maxSearchQueries", actual: (usage) => usage.searchQueries },
+    { limit: "maxFetchedPages", actual: (usage) => usage.fetchedPages },
+    { limit: "maxInputTokens", actual: (usage) => usage.inputTokens },
+    { limit: "maxCachedInputTokens", actual: (usage) => usage.cachedInputTokens },
+    { limit: "maxReasoningTokens", actual: (usage) => usage.reasoningTokens },
+    { limit: "maxOutputTokens", actual: (usage) => usage.outputTokens },
+    { limit: "maxTotalTokens", actual: (usage) => usage.inputTokens + usage.reasoningTokens + usage.outputTokens },
+    { limit: "maxEstimatedUsd", actual: (usage) => usage.estimatedUsd },
+    { limit: "maxRetries", actual: (usage) => usage.retries },
+    { limit: "maxFailures", actual: (usage) => usage.failures },
+];
+function checkBudget(usageInput, limits, pending) {
+    const current = usageFrom(usageInput);
+    const usage = pending ? addUsage(current, usageFrom(pending)) : current;
+    const violations = [];
+    const remaining = {};
+    for (const item of LIMIT_METRICS) {
+        const rawLimit = limits[item.limit];
+        if (rawLimit === undefined)
+            continue;
+        const limit = finiteNonNegative(rawLimit);
+        const actual = item.actual(usage);
+        remaining[item.limit] = Math.max(0, limit - actual);
+        if (actual > limit)
+            violations.push({ metric: item.limit, limit, actual, overBy: actual - limit });
+    }
+    return { ok: violations.length === 0, withinBudget: violations.length === 0, violations, remaining, usage };
+}
+class BudgetExceededError extends Error {
+    result;
+    constructor(result) {
+        const detail = result.violations
+            .map((violation) => `${violation.metric}=${violation.actual} exceeds ${violation.limit}`)
+            .join(", ");
+        super(`Budget exceeded: ${detail}`);
+        this.name = "BudgetExceededError";
+        this.result = result;
+    }
+}
+exports.BudgetExceededError = BudgetExceededError;
+function assertWithinBudget(usage, limits, pending) {
+    const result = checkBudget(usage, limits, pending);
+    if (!result.ok)
+        throw new BudgetExceededError(result);
+    return result;
+}
+class BudgetGuard {
+    ledger;
+    limits;
+    reserved = { ...ZERO_USAGE };
+    reservations = new Map();
+    sequence = 0;
+    constructor(limits, ledger = new UsageLedger()) {
+        this.limits = { ...limits };
+        this.ledger = ledger;
+    }
+    check(pending) {
+        const withReservations = addUsage(this.ledger.snapshot(), this.reserved);
+        return checkBudget(withReservations, this.limits, pending);
+    }
+    assert(pending) {
+        const result = this.check(pending);
+        if (!result.ok)
+            throw new BudgetExceededError(result);
+        return result;
+    }
+    record(event) {
+        this.assert(event);
+        return this.ledger.record(event);
+    }
+    reserve(pending) {
+        this.assert(pending);
+        const usage = usageFrom(pending);
+        this.sequence += 1;
+        const id = `reservation_${this.sequence}`;
+        this.reservations.set(id, usage);
+        this.reserved = addUsage(this.reserved, usage);
+        return id;
+    }
+    release(reservationId) {
+        const usage = this.reservations.get(reservationId);
+        if (!usage)
+            return;
+        this.reservations.delete(reservationId);
+        this.reserved = {
+            providerCalls: Math.max(0, this.reserved.providerCalls - usage.providerCalls),
+            modelCalls: Math.max(0, this.reserved.modelCalls - usage.modelCalls),
+            domainRequests: Math.max(0, this.reserved.domainRequests - usage.domainRequests),
+            namespaceRequests: Math.max(0, this.reserved.namespaceRequests - usage.namespaceRequests),
+            searchQueries: Math.max(0, this.reserved.searchQueries - usage.searchQueries),
+            fetchedPages: Math.max(0, this.reserved.fetchedPages - usage.fetchedPages),
+            inputTokens: Math.max(0, this.reserved.inputTokens - usage.inputTokens),
+            cachedInputTokens: Math.max(0, this.reserved.cachedInputTokens - usage.cachedInputTokens),
+            reasoningTokens: Math.max(0, this.reserved.reasoningTokens - usage.reasoningTokens),
+            outputTokens: Math.max(0, this.reserved.outputTokens - usage.outputTokens),
+            estimatedUsd: Math.max(0, this.reserved.estimatedUsd - usage.estimatedUsd),
+            cacheHits: Math.max(0, this.reserved.cacheHits - usage.cacheHits),
+            retries: Math.max(0, this.reserved.retries - usage.retries),
+            failures: Math.max(0, this.reserved.failures - usage.failures),
+            latencyMs: Math.max(0, this.reserved.latencyMs - usage.latencyMs),
+            events: Math.max(0, this.reserved.events - usage.events),
+        };
+    }
+    commit(reservationId, event) {
+        this.release(reservationId);
+        return this.record(event);
+    }
+}
+exports.BudgetGuard = BudgetGuard;

package/dist/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+"use strict";
+// Thin stdio entry: environment parsing plus transport wiring only. The
+// McpServer construction and all tool registrations live in server-core.ts so
+// the remote Streamable HTTP endpoint at /mcp serves the identical contract.
+Object.defineProperty(exports, "__esModule", { value: true });
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const server_core_1 = require("./server-core");
+const apiBase = (process.env.NAMING_SIGNAL_API_URL?.trim() || process.env.NAME_LEDGER_API_URL?.trim() || server_core_1.DEFAULT_API_URL).replace(/\/+$/, "");
+const apiKey = process.env.NAMING_SIGNAL_API_KEY?.trim();
+async function main() {
+    const server = (0, server_core_1.createNamingSignalMcpServer)({ baseUrl: apiBase, apiKey });
+    await server.connect(new stdio_js_1.StdioServerTransport());
+    console.error(`NamingSignal MCP connected over stdio; API: ${apiBase}`);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});