tare-mcp 0.2.0 → 0.3.0

package/README.md

@@ -1,42 +1,54 @@
 # tare-mcp
 
-[![Build](https://github.com/nishantmodak/tare-mcp/actions/workflows/publish-npm.yml/badge.svg)](https://github.com/nishantmodak/tare-mcp/actions/workflows/publish-npm.yml)
-[![Version](https://img.shields.io/github/package-json/v/nishantmodak/tare-mcp?label=version)](package.json)
+[![Build](https://github.com/nishantmodak/tare-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/nishantmodak/tare-mcp/actions/workflows/ci.yml)
 [![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
-pnpm install
-pnpm build
-node dist/cli.js
+npm install tare-mcp
 ```
 
-MCP made tools easy to connect.
-It did not make them cheap to carry.
+```ts
+import { measureTools } from "tare-mcp";
 
-`tare-mcp` inspects your MCP setup and shows:
+const tools = await mcpClient.listTools();
+const report = await measureTools(tools, { budget: 40_000 });
+
+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
+- how much context those tools consume, estimated for Claude and OpenAI cl100k
 - which servers dominate the budget
 - which tools overlap and compete for model attention
 - whether your setup exceeds a context budget
 
-Think of it as:
+Use the CLI when you want to inspect config-discovered MCP servers locally:
 
 ```bash
-du -sh node_modules
+npx tare-mcp
 ```
 
-but for agent tool context.
+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)
-- [Current Status](#current-status)
-- [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)
@@ -74,25 +86,82 @@ If three servers all expose tools that look like "search", the model has to choo
 - what your tools weigh
 - where your tools overlap
 
-## Current status
+## Using tare-mcp in your agent
 
-Current repository version: `0.2.0`.
+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.
 
-The CLI is implemented as `tare-mcp`, and the package is configured for npm as `tare-mcp`. Until the first npm release is published, run it from this repository with `node dist/cli.js` after building. Once published, the same commands work through `npx tare-mcp` or an npm install.
+Use `measureTools()` when you already have the tool definitions in memory:
 
-Most examples below use `npx tare-mcp` because that is the intended published interface. Before the first npm release, replace `npx tare-mcp` with `node /path/to/tare-mcp/dist/cli.js`.
+```ts
+import { measureTools } from "tare-mcp";
 
-## Quickstart
+const tools = await mcpClient.listTools();
+const report = await measureTools(tools);
 
-Run from source:
+console.log(
+  `MCP tool surface: ${report.summary.tools} tools, ~${report.summary.estimatedTokens.claude} Claude tokens`
+);
+```
 
-```bash
-pnpm install
-pnpm build
-node dist/cli.js
+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
+});
 ```
 
-After the npm package is published:
+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:
 
 ```bash
 npx tare-mcp
@@ -120,26 +189,20 @@ Context window usage:
 
 If the output is empty or shows "Config files found: 0", see [Config discovery](#config-discovery).
 
-Install it in a project after the npm release:
+Install it in a project:
 
 ```bash
 npm install --save-dev tare-mcp
 npx tare-mcp
 ```
 
-Install it globally after the npm release:
+Install it globally:
 
 ```bash
 npm install --global tare-mcp
 tare-mcp
 ```
 
-For local development, keep using the source command:
-
-```bash
-pnpm dev
-```
-
 Static-only mode parses config without starting servers or calling hosted endpoints:
 
 ```bash
@@ -159,6 +222,14 @@ Emit JSON for CI or other tools:
 npx tare-mcp --json
 ```
 
+For local development from this repository:
+
+```bash
+pnpm install
+pnpm build
+pnpm dev
+```
+
 ## Hosted MCP Quickstart
 
 Use this when you want to inspect a real hosted MCP endpoint.
@@ -166,7 +237,19 @@ Use this when you want to inspect a real hosted MCP endpoint.
 ```bash
 mkdir -p /tmp/tare-mcp-hosted
 cd /tmp/tare-mcp-hosted
-cp /path/to/tare-mcp/examples/scenarios/hosted-streamable-http.mcp.json .mcp.json
+cat > .mcp.json <<'JSON'
+{
+  "mcpServers": {
+    "last9": {
+      "type": "http",
+      "url": "https://mcp.last9.io/mcp",
+      "headers": {
+        "Authorization": "Bearer ${LAST9_MCP_TOKEN}"
+      }
+    }
+  }
+}
+JSON
 export LAST9_MCP_TOKEN="..."
 npx tare-mcp --timeout 10000
 ```
@@ -302,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.
 
@@ -345,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
 
@@ -500,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.
 
@@ -567,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:
 
@@ -587,7 +672,7 @@ npm publish --access public --provenance
 
 The npm package is named `tare-mcp` because the unscoped `tare` package name is already occupied on npm.
 
-After the first npm release, users can install it with:
+Users can install it with:
 
 ```bash
 npm install --save-dev tare-mcp
@@ -644,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
@@ -661,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.0";
+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.0";
+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.0",
+  "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": {