tare-mcp 0.2.1 → 0.3.0

package/README.md

@@ -4,16 +4,30 @@
 [![npm](https://img.shields.io/npm/v/tare-mcp?label=npm)](https://www.npmjs.com/package/tare-mcp)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-See what your MCP tools weigh before your agent does anything.
+Measure the MCP tool surface your agent is about to send to a model.
 
 ```bash
-npx tare-mcp
+npm install tare-mcp
 ```
 
-MCP made tools easy to connect.
-It did not make them cheap to carry.
+```ts
+import { measureTools } from "tare-mcp";
+
+const tools = await mcpClient.listTools();
+const report = await measureTools(tools, { budget: 40_000 });
 
-`tare-mcp` inspects your MCP setup and shows, in one local run:
+console.log(
+  `MCP tool surface: ${report.summary.tools} tools, ~${report.summary.estimatedTokens.claude} Claude tokens`
+);
+
+if (report.metadata.budgetExceeded) {
+  throw new Error("MCP tool surface exceeds budget");
+}
+```
+
+MCP made tools easy to connect. It did not make them cheap to carry.
+
+`tare-mcp` shows, from inside your agent or from the CLI:
 
 - how many tools your agent sees
 - how much context those tools consume, estimated for Claude and OpenAI cl100k
@@ -21,36 +35,20 @@ It did not make them cheap to carry.
 - which tools overlap and compete for model attention
 - whether your setup exceeds a context budget
 
-Use it once to see the current cost:
+Use the CLI when you want to inspect config-discovered MCP servers locally:
 
 ```bash
 npx tare-mcp
 ```
 
-Use it in CI to catch MCP bloat before merge:
-
-```bash
-# one time
-mkdir -p .tare
-npx tare-mcp --json > .tare/baseline.json
-git add .tare/baseline.json
-
-# on every PR
-npx tare-mcp --json > tare-report.json
-npx tare-mcp diff \
-  --base .tare/baseline.json \
-  --head tare-report.json \
-  --max-token-increase 5000 \
-  --max-tool-increase 20
-```
-
 Think of it as `du -sh node_modules`, but for agent tool context.
 
 ## Table of Contents
 
 - [Why This Matters](#why-this-matters)
 - [Why Token Count Is Not the Whole Problem](#why-token-count-is-not-the-whole-problem)
-- [Quickstart](#quickstart)
+- [Using tare-mcp in your agent](#using-tare-mcp-in-your-agent)
+- [CLI Quickstart](#cli-quickstart)
 - [Hosted MCP Quickstart](#hosted-mcp-quickstart)
 - [Scenario Examples](#scenario-examples)
 - [Example Output](#example-output)
@@ -88,7 +86,80 @@ If three servers all expose tools that look like "search", the model has to choo
 - what your tools weigh
 - where your tools overlap
 
-## Quickstart
+## Using tare-mcp in your agent
+
+Production agents often do not have a stable `.mcp.json` file to inspect. They connect to MCP servers, call `tools/list`, and pass those tool definitions to the model on each request.
+
+Use `measureTools()` when you already have the tool definitions in memory:
+
+```ts
+import { measureTools } from "tare-mcp";
+
+const tools = await mcpClient.listTools();
+const report = await measureTools(tools);
+
+console.log(
+  `MCP tool surface: ${report.summary.tools} tools, ~${report.summary.estimatedTokens.claude} Claude tokens`
+);
+```
+
+For multiple MCP servers, add `server` per tool so overlap warnings and per-server totals remain useful:
+
+```ts
+import { measureTools } from "tare-mcp";
+
+const last9Tools = await last9Client.listTools();
+const githubTools = await githubClient.listTools();
+
+const report = await measureTools([
+  ...last9Tools.map((tool) => ({ ...tool, server: "last9" })),
+  ...githubTools.map((tool) => ({ ...tool, server: "github" }))
+]);
+```
+
+For unattributed tools, pass a fallback server name:
+
+```ts
+const report = await measureTools(tools, {
+  serverName: "agent"
+});
+```
+
+Budget checks are metadata, not exceptions. That keeps the library easy to use in request paths, logs, and CI:
+
+```ts
+const report = await measureTools(tools, { budget: 40_000 });
+
+if (report.metadata.budgetExceeded) {
+  throw new Error(
+    `MCP tool surface exceeds budget: ~${report.summary.estimatedTokens.claude} Claude tokens`
+  );
+}
+```
+
+Structured logging example:
+
+```ts
+logger.info("mcp.tool_surface", {
+  tools: report.summary.tools,
+  servers: report.summary.servers,
+  tokens_claude: report.summary.estimatedTokens.claude,
+  tokens_openai_cl100k: report.summary.estimatedTokens.openaiCl100k,
+  overlap_clusters: report.overlapClusters.length,
+  budget_exceeded: report.metadata.budgetExceeded ?? false
+});
+```
+
+The programmatic API is local-first. It does not read config files, spawn MCP servers, or call cloud tokenization APIs by default. API-backed Claude token counting is opt-in:
+
+```ts
+const report = await measureTools(tools, {
+  claudeTokenizerMode: "api",
+  anthropicApiKey: process.env.ANTHROPIC_API_KEY
+});
+```
+
+## CLI Quickstart
 
 Run it without installing:
 
@@ -314,10 +385,11 @@ Recommendations:
 
 ## Supported transports
 
-v0.2 supports live inspection for:
+v0.3 supports:
 
 - stdio MCP servers
 - Streamable HTTP MCP servers
+- programmatic tool definitions through `measureTools()`
 
 SSE may be supported best-effort later.
 
@@ -357,12 +429,12 @@ That mode requires `ANTHROPIC_API_KEY` and uses Anthropic's `POST /v1/messages/c
 
 Environment variables that control tokenization:
 
-| Variable | Values | Default | Description |
-|---|---|---|---|
-| `ANTHROPIC_API_KEY` | string | — | Required for `--claude-tokenizer api` |
-| `TARE_CLAUDE_TOKENIZER` | `local`, `api` | `local` | Override `--claude-tokenizer` via env |
-| `TARE_ANTHROPIC_MODEL` | model ID | `claude-sonnet-4-6` | Model used for API-backed token counting |
-| `TARE_DISABLE_ANTHROPIC_TOKEN_API` | `1` | unset | Disable API-backed counting even when requested |
+| Variable                           | Values         | Default             | Description                                     |
+| ---------------------------------- | -------------- | ------------------- | ----------------------------------------------- |
+| `ANTHROPIC_API_KEY`                | string         | —                   | Required for `--claude-tokenizer api`           |
+| `TARE_CLAUDE_TOKENIZER`            | `local`, `api` | `local`             | Override `--claude-tokenizer` via env           |
+| `TARE_ANTHROPIC_MODEL`             | model ID       | `claude-sonnet-4-6` | Model used for API-backed token counting        |
+| `TARE_DISABLE_ANTHROPIC_TOKEN_API` | `1`            | unset               | Disable API-backed counting even when requested |
 
 ## Security model
 
@@ -512,11 +584,11 @@ When a growth is intentional, regenerate `.tare/baseline.json` on the accepted s
 
 Exit codes:
 
-| Code | Meaning |
-|---:|---|
-| `0` | Diff completed and thresholds passed, or no thresholds were set. |
-| `1` | A configured regression threshold was exceeded. |
-| `2` | Invalid usage or invalid input, including missing files, invalid JSON, or missing report fields. |
+| Code | Meaning                                                                                          |
+| ---: | ------------------------------------------------------------------------------------------------ |
+|  `0` | Diff completed and thresholds passed, or no thresholds were set.                                 |
+|  `1` | A configured regression threshold was exceeded.                                                  |
+|  `2` | Invalid usage or invalid input, including missing files, invalid JSON, or missing report fields. |
 
 Estimates are still estimates. The value of the baseline workflow is consistency: the same tool estimates are compared over time, so accidental MCP bloat becomes visible during review.
 
@@ -579,6 +651,7 @@ npx tare-mcp --no-exec --json
 ## Publishing to npm
 
 This repository includes [`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml).
+Maintainers should use the [release checklist](https://github.com/nishantmodak/tare-mcp/blob/main/docs/releasing.md).
 
 To publish from GitHub Actions:
 
@@ -656,15 +729,23 @@ Options:
 
 ## Roadmap
 
+v0.3:
+
+- [x] Programmatic API for running agents through `measureTools()`
+- [x] Programmatic JSON reports compatible with `tare-mcp diff`
+
 v0.2:
+
 - [x] PR diff/regression mode for JSON reports
 - [x] Threshold flags for token, tool, server, and overlap growth
 
 Next:
+
 - [ ] Per-tool schema breakdown
 - [ ] Context budget config file (`tare.config.json`)
 
 Later:
+
 - [ ] Better SSE fallback
 - [ ] Improved Claude local token estimator
 - [ ] Opt-in API-backed token counting improvements
@@ -673,7 +754,7 @@ Later:
 - [ ] MCP profile generator
 - [ ] `tare-mcp --fix` to generate lean MCP profiles
 
-Dashboards, profile generation, and auto-fix are intentionally not part of v0.2.
+Dashboards, profile generation, and auto-fix are intentionally not part of v0.3.
 
 ## License
 

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+import { Command } from 'commander';
+
+declare function createProgram(): Command;
+
+export { createProgram };

package/dist/cli.js

@@ -5,7 +5,7 @@ import { Command } from "commander";
 import { z as z4 } from "zod";
 
 // src/version.ts
-var VERSION = "0.2.1";
+var VERSION = "0.3.0";
 
 // src/utils/stableJson.ts
 function stableValue(value) {
@@ -387,7 +387,7 @@ async function analyzeServers(inspectedServers, tokenEstimator, options) {
         estimatedTokens: analyzedTool.estimatedTokens,
         hasInputSchema: analyzedTool.hasInputSchema
       });
-      if (server.inspectionMode === "live") {
+      if (server.inspectionMode === "live" || server.inspectionMode === "programmatic") {
         liveToolsForOverlap.push(analyzedTool);
       }
     }
@@ -444,7 +444,9 @@ async function analyzeServers(inspectedServers, tokenEstimator, options) {
           openaiCl100k: windowUsage(totalOpenAi, 2e5)
         }
       },
-      insufficientServers: analyzedServers.filter((server) => server.inspectionMode !== "live").length
+      insufficientServers: analyzedServers.filter(
+        (server) => server.inspectionMode === "static-insufficient" || server.inspectionMode === "fallback-static-insufficient"
+      ).length
     },
     servers: analyzedServers,
     overlapClusters,
@@ -452,7 +454,7 @@ async function analyzeServers(inspectedServers, tokenEstimator, options) {
     warnings,
     metadata: {
       staticOnly: options.staticOnly,
-      inspectionMode: options.staticOnly ? "static-only" : "live default"
+      inspectionMode: options.inspectionMode ?? (options.staticOnly ? "static-only" : "live default")
     }
   };
   report.recommendations = buildRecommendations(report);
@@ -996,13 +998,18 @@ var TareReportSchema = z3.object({
     z3.object({
       name: z3.string(),
       sourceConfigPath: z3.string(),
-      transport: z3.enum(["stdio", "streamable-http", "sse", "unknown"]),
+      transport: z3.enum(["stdio", "streamable-http", "sse", "programmatic", "unknown"]),
       command: z3.string().optional(),
       args: z3.array(z3.string()).optional(),
       urlHost: z3.string().optional(),
       toolCount: z3.number(),
       estimatedTokens: TokenTotalsSchema,
-      inspectionMode: z3.enum(["live", "static-insufficient", "fallback-static-insufficient"]),
+      inspectionMode: z3.enum([
+        "live",
+        "programmatic",
+        "static-insufficient",
+        "fallback-static-insufficient"
+      ]),
       confidence: z3.enum(["high", "medium", "low"]),
       warnings: z3.array(z3.string()),
       tools: z3.array(
@@ -1025,7 +1032,10 @@ var TareReportSchema = z3.object({
   warnings: z3.array(z3.string()),
   metadata: z3.object({
     staticOnly: z3.boolean(),
-    inspectionMode: z3.enum(["live default", "static-only"])
+    inspectionMode: z3.enum(["live default", "static-only", "programmatic"]),
+    budgetExceeded: z3.boolean().optional(),
+    budgetTokens: z3.number().optional(),
+    budgetTokenizer: z3.literal("claude").optional()
   }).passthrough()
 }).passthrough();
 var ReportLoadError = class extends Error {
@@ -1908,7 +1918,9 @@ function renderHumanReport(report) {
       }
     }
   }
-  const insufficientServers = report.servers.filter((server) => server.inspectionMode !== "live");
+  const insufficientServers = report.servers.filter(
+    (server) => server.inspectionMode === "static-insufficient" || server.inspectionMode === "fallback-static-insufficient"
+  );
   if (insufficientServers.length > 0) {
     lines.push("");
     lines.push("Insufficient data:");

package/dist/index.d.ts

@@ -0,0 +1,425 @@
+import { z } from 'zod';
+
+declare const VERSION = "0.3.0";
+
+type TransportKind = "stdio" | "streamable-http" | "http" | "sse" | "unknown";
+type ReportTransportKind = "stdio" | "streamable-http" | "sse" | "programmatic" | "unknown";
+type InspectionMode = "live" | "programmatic" | "static-insufficient" | "fallback-static-insufficient";
+type Confidence = "high" | "medium" | "low";
+type NormalizedServer = {
+    name: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+    disabled?: boolean;
+    sourceConfigPath: string;
+    transport?: TransportKind;
+};
+type McpToolDefinition = {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    annotations?: unknown;
+    outputSchema?: unknown;
+    metadata?: unknown;
+};
+type InspectedServer = {
+    name: string;
+    sourceConfigPath: string;
+    transport: ReportTransportKind;
+    command?: string;
+    args?: string[];
+    urlHost?: string;
+    toolDefinitions: McpToolDefinition[];
+    inspectionMode: InspectionMode;
+    confidence: Confidence;
+    warnings: string[];
+};
+type InspectorOptions = {
+    timeoutMs: number;
+    fetch?: typeof globalThis.fetch;
+};
+type ToolContextPayload = {
+    server: string;
+    transport: ReportTransportKind;
+    tool: {
+        name: string;
+        description?: string;
+        inputSchema?: unknown;
+        annotations?: unknown;
+        outputSchema?: unknown;
+        metadata?: unknown;
+    };
+};
+
+declare function getDefaultConfigCandidates(cwd?: string, home?: string): string[];
+type DiscoverConfigResult = {
+    paths: string[];
+    warnings: string[];
+};
+declare function discoverConfigs(cwd?: string, home?: string): Promise<DiscoverConfigResult>;
+
+type ParsedConfig = {
+    path: string;
+    servers: NormalizedServer[];
+    warnings: string[];
+};
+declare function parseConfigText(text: string, sourceConfigPath: string): ParsedConfig;
+declare function parseConfigFile(filePath: string): Promise<ParsedConfig>;
+
+type NormalizeResult = {
+    server?: NormalizedServer;
+    warnings: string[];
+};
+declare function normalizeServer(name: string, rawConfig: unknown, sourceConfigPath: string): NormalizeResult;
+
+declare function createStaticInspection(server: NormalizedServer, mode?: InspectionMode, warnings?: string[]): InspectedServer;
+
+declare function buildServerEnv(server: NormalizedServer): Record<string, string>;
+declare function inspectStdioServer(server: NormalizedServer, options: InspectorOptions): Promise<InspectedServer>;
+
+declare function inspectStreamableHttpServer(server: NormalizedServer, options: InspectorOptions): Promise<InspectedServer>;
+
+type TokenEstimate = {
+    tokenizer: "claude-estimate" | "claude-api" | "openai-cl100k" | "fallback-char-ratio";
+    tokens: number;
+    confidence: "high" | "medium" | "low";
+    warning?: string;
+};
+interface TokenCounter {
+    count(text: string): Promise<TokenEstimate>;
+}
+type DualTokenEstimate = {
+    claude: TokenEstimate;
+    openaiCl100k: TokenEstimate;
+};
+type ClaudeTokenizerMode = "local" | "api";
+
+type CountTokensOptions = {
+    claudeTokenizerMode: ClaudeTokenizerMode;
+    anthropicApiKey?: string;
+    anthropicModel?: string;
+    anthropicDisabled?: boolean;
+    timeoutMs?: number;
+    onWarning?: (warning: string) => void;
+};
+declare class TokenEstimator {
+    private readonly options;
+    private readonly cache;
+    private readonly openAiCounter;
+    private readonly anthropicQueue;
+    private anthropicApiUnavailable;
+    private emittedMissingKeyWarning;
+    private emittedDisabledWarning;
+    private emittedApiFailureWarning;
+    constructor(options: CountTokensOptions);
+    count(text: string): Promise<DualTokenEstimate>;
+    private countClaude;
+    private countClaudeWithApi;
+}
+
+type AnalyzedTool = {
+    server: string;
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    estimatedTokens: {
+        claude: number;
+        openaiCl100k: number;
+    };
+    hasInputSchema: boolean;
+};
+type OverlapCluster = {
+    label: string;
+    score: number;
+    reason: string;
+    signals: Array<"tfidf" | "intent-heuristic">;
+    tools: Array<{
+        server: string;
+        name: string;
+        description?: string;
+        estimatedTokens?: {
+            claude?: number;
+            openaiCl100k?: number;
+        };
+    }>;
+    recommendation: string;
+};
+type TareReport = {
+    version: string;
+    generatedAt: string;
+    summary: {
+        configFiles: number;
+        servers: number;
+        tools: number;
+        estimatedTokens: {
+            claude: number;
+            openaiCl100k: number;
+        };
+        contextWindows: {
+            "64000": {
+                claude: number;
+                openaiCl100k: number;
+            };
+            "128000": {
+                claude: number;
+                openaiCl100k: number;
+            };
+            "200000": {
+                claude: number;
+                openaiCl100k: number;
+            };
+        };
+        insufficientServers: number;
+    };
+    servers: Array<{
+        name: string;
+        sourceConfigPath: string;
+        transport: ReportTransportKind;
+        command?: string;
+        args?: string[];
+        urlHost?: string;
+        toolCount: number;
+        estimatedTokens: {
+            claude: number;
+            openaiCl100k: number;
+        };
+        inspectionMode: InspectionMode;
+        confidence: Confidence;
+        warnings: string[];
+        tools: Array<{
+            name: string;
+            description?: string;
+            estimatedTokens: {
+                claude: number;
+                openaiCl100k: number;
+            };
+            hasInputSchema: boolean;
+        }>;
+    }>;
+    overlapClusters: OverlapCluster[];
+    recommendations: Array<{
+        type: string;
+        message: string;
+    }>;
+    warnings: string[];
+    metadata: {
+        staticOnly: boolean;
+        inspectionMode: "live default" | "static-only" | "programmatic";
+        budgetExceeded?: boolean;
+        budgetTokens?: number;
+        budgetTokenizer?: "claude";
+    };
+};
+
+type AnalyzeOptions = {
+    configFiles: number;
+    staticOnly: boolean;
+    warnings?: string[];
+    inspectionMode?: "live default" | "static-only" | "programmatic";
+};
+declare function analyzeServers(inspectedServers: InspectedServer[], tokenEstimator: TokenEstimator, options: AnalyzeOptions): Promise<TareReport>;
+
+type McpToolInput = {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    annotations?: unknown;
+    outputSchema?: unknown;
+    metadata?: unknown;
+};
+type AttributedMcpToolInput = McpToolInput & {
+    server: string;
+};
+type MeasureToolsOptions = {
+    serverName?: string;
+    budget?: number;
+    claudeTokenizerMode?: ClaudeTokenizerMode;
+    anthropicApiKey?: string;
+    anthropicModel?: string;
+    timeoutMs?: number;
+};
+
+declare function measureTools(tools: readonly (McpToolInput | AttributedMcpToolInput)[], options?: MeasureToolsOptions): Promise<TareReport>;
+
+declare class OverlapDetector {
+    private readonly threshold;
+    constructor(threshold?: number);
+    detect(tools: AnalyzedTool[]): OverlapCluster[];
+}
+
+declare function buildRecommendations(report: Pick<TareReport, "summary" | "overlapClusters" | "servers">): TareReport["recommendations"];
+
+declare class OpenAICl100kCounter implements TokenCounter {
+    count(text: string): Promise<TokenEstimate>;
+}
+
+declare class LocalClaudeEstimator implements TokenCounter {
+    private readonly openAiCount?;
+    constructor(openAiCount?: (() => Promise<TokenEstimate>) | undefined);
+    count(text: string): Promise<TokenEstimate>;
+}
+
+type BudgetTokenizer = "claude" | "openai";
+declare function renderHumanReport(report: TareReport): string;
+declare function renderBudgetFailure(report: TareReport, budget: number, tokenizer: BudgetTokenizer): string;
+
+declare function renderJsonReport(report: TareReport): string;
+
+declare const TareReportSchema: z.ZodType<TareReport>;
+type LoadedTareReport = {
+    path: string;
+    report: TareReport;
+};
+declare class ReportLoadError extends Error {
+    readonly path: string;
+    constructor(filePath: string, message: string);
+}
+declare function loadReport(filePath: string): Promise<LoadedTareReport>;
+
+type DiffTokenizer = "claude" | "openai";
+type DiffTokenTotals = {
+    claude: number;
+    openaiCl100k: number;
+};
+type NumericDelta = {
+    base: number;
+    head: number;
+    delta: number;
+};
+type TokenDelta = {
+    base: DiffTokenTotals;
+    head: DiffTokenTotals;
+    delta: DiffTokenTotals;
+};
+type ValueDelta<T> = {
+    base: T;
+    head: T;
+    changed: boolean;
+};
+type DiffServer = {
+    name: string;
+    sourceConfigPath: string;
+    transport: ReportTransportKind;
+    command?: string;
+    args?: string[];
+    urlHost?: string;
+    toolCount: number;
+    estimatedTokens: DiffTokenTotals;
+    inspectionMode: InspectionMode;
+    confidence: Confidence;
+};
+type DiffTool = {
+    server: string;
+    name: string;
+    description?: string;
+    estimatedTokens: DiffTokenTotals;
+    hasInputSchema: boolean;
+};
+type DiffServerChange = {
+    name: string;
+    toolCount: NumericDelta;
+    estimatedTokens: TokenDelta;
+    transport: ValueDelta<ReportTransportKind>;
+    sourceConfigPath: ValueDelta<string>;
+    command: ValueDelta<string | null>;
+    args: ValueDelta<string[] | null>;
+    urlHost: ValueDelta<string | null>;
+    inspectionMode: ValueDelta<InspectionMode>;
+    confidence: ValueDelta<Confidence>;
+};
+type DiffToolChange = {
+    server: string;
+    name: string;
+    estimatedTokens: TokenDelta;
+    descriptionChanged: boolean;
+    inputSchemaPresenceChanged: boolean;
+};
+type DiffOverlapCluster = {
+    id: string;
+    label: string;
+    score: number;
+    tools: Array<{
+        server: string;
+        name: string;
+    }>;
+    recommendation: string;
+};
+type ThresholdResult = {
+    flag: string;
+    tokenizer?: DiffTokenizer;
+    allowed: number;
+    actual: number;
+    exceeded: boolean;
+};
+type TareDiffReport = {
+    version: string;
+    generatedAt: string;
+    base: {
+        path: string;
+        reportVersion: string;
+        generatedAt: string;
+    };
+    head: {
+        path: string;
+        reportVersion: string;
+        generatedAt: string;
+    };
+    summary: {
+        servers: NumericDelta;
+        tools: NumericDelta;
+        estimatedTokens: TokenDelta;
+        overlapClusters: NumericDelta;
+    };
+    servers: {
+        added: DiffServer[];
+        removed: DiffServer[];
+        changed: DiffServerChange[];
+    };
+    tools: {
+        added: DiffTool[];
+        removed: DiffTool[];
+        changed: DiffToolChange[];
+    };
+    overlapClusters: {
+        added: DiffOverlapCluster[];
+        removed: DiffOverlapCluster[];
+    };
+    thresholds: ThresholdResult[];
+    recommendations: Array<{
+        type: string;
+        message: string;
+    }>;
+    warnings: string[];
+};
+type DiffThresholdOptions = {
+    maxTokenIncrease?: number;
+    maxToolIncrease?: number;
+    maxServerIncrease?: number;
+    maxOverlapIncrease?: number;
+    tokenizer: DiffTokenizer;
+};
+
+type DiffReportsOptions = {
+    basePath: string;
+    headPath: string;
+    generatedAt?: string;
+};
+type ReportOverlapCluster = TareReport["overlapClusters"][number];
+declare function diffReports(baseReport: TareReport, headReport: TareReport, options: DiffReportsOptions): TareDiffReport;
+declare function overlapClusterIdentity(cluster: ReportOverlapCluster): string;
+
+declare function evaluateDiffThresholds(report: TareDiffReport, options: DiffThresholdOptions): ThresholdResult[];
+declare function hasThresholdFailure(report: Pick<TareDiffReport, "thresholds">): boolean;
+
+type DiffHumanReporterOptions = {
+    tokenizer: DiffTokenizer;
+};
+declare function renderDiffHumanReport(report: TareDiffReport, options: DiffHumanReporterOptions): string;
+declare function renderDiffThresholdFailure(report: TareDiffReport, options: DiffHumanReporterOptions): string;
+
+declare function renderDiffJsonReport(report: TareDiffReport): string;
+
+export { type AnalyzedTool, type AttributedMcpToolInput, type ClaudeTokenizerMode, type Confidence, type DiffHumanReporterOptions, type DiffOverlapCluster, type DiffReportsOptions, type DiffServer, type DiffServerChange, type DiffThresholdOptions, type DiffTokenTotals, type DiffTokenizer, type DiffTool, type DiffToolChange, type DualTokenEstimate, type InspectedServer, type InspectionMode, LocalClaudeEstimator, type McpToolDefinition, type McpToolInput, type MeasureToolsOptions, type NormalizedServer, type NumericDelta, OpenAICl100kCounter, type OverlapCluster, OverlapDetector, ReportLoadError, type ReportTransportKind, type TareDiffReport, type TareReport, TareReportSchema, type ThresholdResult, type TokenCounter, type TokenDelta, type TokenEstimate, TokenEstimator, type ToolContextPayload, type TransportKind, VERSION, type ValueDelta, analyzeServers, buildRecommendations, buildServerEnv, createStaticInspection, diffReports, discoverConfigs, evaluateDiffThresholds, getDefaultConfigCandidates, hasThresholdFailure, inspectStdioServer, inspectStreamableHttpServer, loadReport, measureTools, normalizeServer, overlapClusterIdentity, parseConfigFile, parseConfigText, renderBudgetFailure, renderDiffHumanReport, renderDiffJsonReport, renderDiffThresholdFailure, renderHumanReport, renderJsonReport };

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/version.ts
-var VERSION = "0.2.1";
+var VERSION = "0.3.0";
 
 // src/discovery/discoverConfigs.ts
 import os2 from "os";
@@ -1017,7 +1017,7 @@ async function analyzeServers(inspectedServers, tokenEstimator, options) {
         estimatedTokens: analyzedTool.estimatedTokens,
         hasInputSchema: analyzedTool.hasInputSchema
       });
-      if (server.inspectionMode === "live") {
+      if (server.inspectionMode === "live" || server.inspectionMode === "programmatic") {
         liveToolsForOverlap.push(analyzedTool);
       }
     }
@@ -1074,7 +1074,9 @@ async function analyzeServers(inspectedServers, tokenEstimator, options) {
           openaiCl100k: windowUsage(totalOpenAi, 2e5)
         }
       },
-      insufficientServers: analyzedServers.filter((server) => server.inspectionMode !== "live").length
+      insufficientServers: analyzedServers.filter(
+        (server) => server.inspectionMode === "static-insufficient" || server.inspectionMode === "fallback-static-insufficient"
+      ).length
     },
     servers: analyzedServers,
     overlapClusters,
@@ -1082,7 +1084,7 @@ async function analyzeServers(inspectedServers, tokenEstimator, options) {
     warnings,
     metadata: {
       staticOnly: options.staticOnly,
-      inspectionMode: options.staticOnly ? "static-only" : "live default"
+      inspectionMode: options.inspectionMode ?? (options.staticOnly ? "static-only" : "live default")
     }
   };
   report.recommendations = buildRecommendations(report);
@@ -1288,6 +1290,121 @@ var TokenEstimator = class {
   }
 };
 
+// src/api/measureTools.ts
+var DEFAULT_SERVER_NAME = "agent";
+var PROGRAMMATIC_SOURCE = "programmatic";
+async function measureTools(tools, options = {}) {
+  validateTools(tools);
+  const normalizedOptions = validateOptions(options);
+  const tokenWarnings = [];
+  const inspectedServers = inspectedServersFromTools(tools, normalizedOptions.serverName);
+  const report = await analyzeServers(
+    inspectedServers,
+    new TokenEstimator({
+      claudeTokenizerMode: normalizedOptions.claudeTokenizerMode ?? "local",
+      anthropicApiKey: normalizedOptions.anthropicApiKey,
+      anthropicModel: normalizedOptions.anthropicModel,
+      timeoutMs: normalizedOptions.timeoutMs,
+      onWarning: (warning) => tokenWarnings.push(warning)
+    }),
+    {
+      configFiles: 0,
+      staticOnly: false,
+      inspectionMode: "programmatic"
+    }
+  );
+  report.warnings.push(...tokenWarnings);
+  if (normalizedOptions.budget !== void 0) {
+    report.metadata.budgetTokens = normalizedOptions.budget;
+    report.metadata.budgetTokenizer = "claude";
+    report.metadata.budgetExceeded = report.summary.estimatedTokens.claude > normalizedOptions.budget;
+  }
+  return report;
+}
+function inspectedServersFromTools(tools, fallbackServerName) {
+  const groups = /* @__PURE__ */ new Map();
+  const defaultServerName = normalizeServerName(fallbackServerName) ?? DEFAULT_SERVER_NAME;
+  for (const tool of tools) {
+    const serverName = serverNameForTool(tool, defaultServerName);
+    const group = groups.get(serverName) ?? [];
+    group.push(toToolDefinition(tool));
+    groups.set(serverName, group);
+  }
+  return [...groups.entries()].map(([name, toolDefinitions]) => ({
+    name,
+    sourceConfigPath: PROGRAMMATIC_SOURCE,
+    transport: "programmatic",
+    toolDefinitions,
+    inspectionMode: "programmatic",
+    confidence: "high",
+    warnings: []
+  }));
+}
+function serverNameForTool(tool, fallbackServerName) {
+  return isAttributedTool(tool) ? normalizeServerName(tool.server) ?? fallbackServerName : fallbackServerName;
+}
+function toToolDefinition(tool) {
+  return {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    annotations: tool.annotations,
+    outputSchema: tool.outputSchema,
+    metadata: tool.metadata
+  };
+}
+function isAttributedTool(tool) {
+  return "server" in tool && typeof tool.server === "string" && tool.server.trim().length > 0;
+}
+function normalizeServerName(serverName) {
+  const trimmed = serverName?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : void 0;
+}
+function validateTools(tools) {
+  if (!Array.isArray(tools)) {
+    throw new TypeError("measureTools expected tools to be an array.");
+  }
+  for (const [index, tool] of tools.entries()) {
+    if (!tool || typeof tool !== "object") {
+      throw new TypeError(`measureTools expected tools[${index}] to be an object.`);
+    }
+    if (typeof tool.name !== "string" || tool.name.trim().length === 0) {
+      throw new TypeError(`measureTools expected tools[${index}].name to be a non-empty string.`);
+    }
+    if ("server" in tool && tool.server !== void 0 && (typeof tool.server !== "string" || tool.server.trim().length === 0)) {
+      throw new TypeError(
+        `measureTools expected tools[${index}].server to be a non-empty string when provided.`
+      );
+    }
+  }
+}
+function validateOptions(options) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("measureTools expected options to be an object when provided.");
+  }
+  if (options.serverName !== void 0 && normalizeServerName(options.serverName) === void 0) {
+    throw new TypeError("measureTools expected options.serverName to be a non-empty string.");
+  }
+  if (options.budget !== void 0 && (!Number.isFinite(options.budget) || options.budget < 0)) {
+    throw new TypeError("measureTools expected options.budget to be a non-negative number.");
+  }
+  if (options.timeoutMs !== void 0 && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
+    throw new TypeError("measureTools expected options.timeoutMs to be a positive number.");
+  }
+  if (options.claudeTokenizerMode !== void 0 && options.claudeTokenizerMode !== "local" && options.claudeTokenizerMode !== "api") {
+    throw new TypeError(
+      'measureTools expected options.claudeTokenizerMode to be "local" or "api".'
+    );
+  }
+  if (options.anthropicApiKey !== void 0 && typeof options.anthropicApiKey !== "string") {
+    throw new TypeError("measureTools expected options.anthropicApiKey to be a string.");
+  }
+  if (options.anthropicModel !== void 0 && typeof options.anthropicModel !== "string") {
+    throw new TypeError("measureTools expected options.anthropicModel to be a string.");
+  }
+  return options;
+}
+
 // src/reporters/humanReporter.ts
 import pc from "picocolors";
 function formatNumber(value) {
@@ -1381,7 +1498,9 @@ function renderHumanReport(report) {
       }
     }
   }
-  const insufficientServers = report.servers.filter((server) => server.inspectionMode !== "live");
+  const insufficientServers = report.servers.filter(
+    (server) => server.inspectionMode === "static-insufficient" || server.inspectionMode === "fallback-static-insufficient"
+  );
   if (insufficientServers.length > 0) {
     lines.push("");
     lines.push("Insufficient data:");
@@ -1483,13 +1602,18 @@ var TareReportSchema = z3.object({
     z3.object({
       name: z3.string(),
       sourceConfigPath: z3.string(),
-      transport: z3.enum(["stdio", "streamable-http", "sse", "unknown"]),
+      transport: z3.enum(["stdio", "streamable-http", "sse", "programmatic", "unknown"]),
       command: z3.string().optional(),
       args: z3.array(z3.string()).optional(),
       urlHost: z3.string().optional(),
       toolCount: z3.number(),
       estimatedTokens: TokenTotalsSchema,
-      inspectionMode: z3.enum(["live", "static-insufficient", "fallback-static-insufficient"]),
+      inspectionMode: z3.enum([
+        "live",
+        "programmatic",
+        "static-insufficient",
+        "fallback-static-insufficient"
+      ]),
       confidence: z3.enum(["high", "medium", "low"]),
       warnings: z3.array(z3.string()),
       tools: z3.array(
@@ -1512,7 +1636,10 @@ var TareReportSchema = z3.object({
   warnings: z3.array(z3.string()),
   metadata: z3.object({
     staticOnly: z3.boolean(),
-    inspectionMode: z3.enum(["live default", "static-only"])
+    inspectionMode: z3.enum(["live default", "static-only", "programmatic"]),
+    budgetExceeded: z3.boolean().optional(),
+    budgetTokens: z3.number().optional(),
+    budgetTokenizer: z3.literal("claude").optional()
   }).passthrough()
 }).passthrough();
 var ReportLoadError = class extends Error {
@@ -2186,6 +2313,7 @@ export {
   inspectStdioServer,
   inspectStreamableHttpServer,
   loadReport,
+  measureTools,
   normalizeServer,
   overlapClusterIdentity,
   parseConfigFile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tare-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Local-first CLI for analyzing MCP context weight and tool ambiguity.",
   "license": "MIT",
   "type": "module",
@@ -8,8 +8,12 @@
   "bin": {
     "tare-mcp": "./dist/cli.js"
   },
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./dist/index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "main": "./dist/index.js",
   "repository": {