@yawlabs/tokenmeter-mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Token Meter MCP Client
+ *
+ * This is the ONLY code distributed to users.
+ * It is a thin API client — all business logic runs on tokenmeter.sh.
+ *
+ * The client:
+ * 1. Connects to the user's MCP host (Claude, Cursor, Yaw, etc.)
+ * 2. Registers tools by fetching the tool list from the API
+ * 3. When a tool is called, proxies the request to api.tokenmeter.sh
+ * 4. Returns the response to the MCP host
+ *
+ * No provider translation, routing, cost calculation, or pricing data
+ * is included in this package.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * Token Meter MCP Client
+ *
+ * This is the ONLY code distributed to users.
+ * It is a thin API client — all business logic runs on tokenmeter.sh.
+ *
+ * The client:
+ * 1. Connects to the user's MCP host (Claude, Cursor, Yaw, etc.)
+ * 2. Registers tools by fetching the tool list from the API
+ * 3. When a tool is called, proxies the request to api.tokenmeter.sh
+ * 4. Returns the response to the MCP host
+ *
+ * No provider translation, routing, cost calculation, or pricing data
+ * is included in this package.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const API_BASE = process.env.TOKENMETER_API_URL ?? "https://api.tokenmeter.sh";
+const API_KEY = process.env.TOKENMETER_API_KEY ?? "";
+async function apiCall(endpoint, params = {}) {
+    const res = await fetch(`${API_BASE}${endpoint}`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            ...(API_KEY ? { authorization: `Bearer ${API_KEY}` } : {}),
+        },
+        body: JSON.stringify(params),
+    });
+    if (!res.ok) {
+        const error = await res.text().catch(() => "Unknown error");
+        throw new Error(`Token Meter API error (${res.status}): ${error}`);
+    }
+    return res.json();
+}
+function text(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+async function main() {
+    if (!API_KEY) {
+        console.error("TOKENMETER_API_KEY is required. Get your key at https://tokenmeter.sh/settings");
+        process.exit(1);
+    }
+    const server = new McpServer({ name: "tokenmeter", version: "0.1.0" });
+    // ─── Free Tier ───────────────────────────────────────────
+    server.tool("get_spend_summary", "Get total LLM spend for today, this week, and this month, broken down by provider.", {}, async () => text(await apiCall("/v1/tools/get_spend_summary")));
+    server.tool("get_session_cost", "Get the cost of the current conversation/session.", {}, async () => text(await apiCall("/v1/tools/get_session_cost")));
+    server.tool("get_model_pricing", "Get current per-token pricing for any model or provider.", {
+        model: z.string().optional().describe("Model ID"),
+        provider: z.string().optional().describe("Provider name"),
+    }, async (params) => text(await apiCall("/v1/tools/get_model_pricing", params)));
+    server.tool("get_budget_status", "Check current spend against configured budget limits.", {}, async () => text(await apiCall("/v1/tools/get_budget_status")));
+    server.tool("get_providers", "List connected LLM providers and their status.", {}, async () => text(await apiCall("/v1/tools/get_providers")));
+    // ─── Pro Tier ────────────────────────────────────────────
+    server.tool("get_spend_breakdown", "Detailed spend breakdown with filters by provider, model, project, and date range.", {
+        provider: z.string().optional(),
+        days: z.number().optional().default(7),
+    }, async (params) => text(await apiCall("/v1/tools/get_spend_breakdown", params)));
+    server.tool("get_cost_trend", "Show daily spend over time to identify trends.", {
+        days: z.number().optional().default(14),
+    }, async (params) => text(await apiCall("/v1/tools/get_cost_trend", params)));
+    server.tool("get_top_models", "Rank models by spend or token volume.", {
+        sortBy: z.enum(["cost", "tokens"]).optional().default("cost"),
+        days: z.number().optional().default(30),
+    }, async (params) => text(await apiCall("/v1/tools/get_top_models", params)));
+    server.tool("get_cost_estimate", "Estimate cost for a given number of tokens on specified models.", {
+        models: z.array(z.string()),
+        inputTokens: z.number(),
+        outputTokens: z.number().optional().default(500),
+        useCache: z.boolean().optional().default(false),
+    }, async (params) => text(await apiCall("/v1/tools/get_cost_estimate", params)));
+    server.tool("compare_models", "Compare models on cost for a specific workload.", {
+        inputTokens: z.number(),
+        outputTokens: z.number(),
+        callsPerDay: z.number().optional().default(100),
+        provider: z.string().optional(),
+    }, async (params) => text(await apiCall("/v1/tools/compare_models", params)));
+    server.tool("get_anomalies", "Flag unusual spend spikes compared to historical average.", {}, async () => text(await apiCall("/v1/tools/get_anomalies")));
+    server.tool("set_budget_alert", "Create a spend threshold notification or hard cap.", {
+        name: z.string(),
+        limit: z.number(),
+        period: z.enum(["daily", "weekly", "monthly"]),
+        hardCap: z.boolean().optional().default(false),
+    }, async (params) => text(await apiCall("/v1/tools/set_budget_alert", params)));
+    server.tool("set_budget_cap", "Set a hard spending cap that blocks requests when hit.", {
+        limit: z.number(),
+        period: z.enum(["daily", "weekly", "monthly"]),
+    }, async (params) => text(await apiCall("/v1/tools/set_budget_cap", params)));
+    server.tool("tag_session", "Label the current session with a project name for cost attribution.", {
+        project: z.string(),
+    }, async (params) => text(await apiCall("/v1/tools/tag_session", params)));
+    server.tool("export_report", "Generate a spend report for a date range.", {
+        days: z.number().optional().default(30),
+        format: z.enum(["json", "csv"]).optional().default("json"),
+    }, async (params) => text(await apiCall("/v1/tools/export_report", params)));
+    // ─── Gateway Tier ────────────────────────────────────────
+    server.tool("get_rate_limits", "Show current rate limit status per provider and model.", {}, async () => text(await apiCall("/v1/tools/get_rate_limits")));
+    server.tool("get_routing_status", "Show which providers are healthy, degraded, or rate-limited.", {}, async () => text(await apiCall("/v1/tools/get_routing_status")));
+    server.tool("set_routing_rule", "Configure routing preferences (cheapest, fastest, specific provider).", {
+        name: z.string(),
+        strategy: z.enum(["cheapest", "fastest", "specific"]),
+        provider: z.string().optional(),
+        model: z.string().optional(),
+    }, async (params) => text(await apiCall("/v1/tools/set_routing_rule", params)));
+    server.tool("set_fallback_chain", "Define provider failover order.", {
+        chain: z.array(z.object({
+            provider: z.string(),
+            model: z.string(),
+        })),
+    }, async (params) => text(await apiCall("/v1/tools/set_fallback_chain", params)));
+    server.tool("set_project_quota", "Set a hard spend cap per project.", {
+        project: z.string(),
+        limit: z.number(),
+        period: z.enum(["daily", "weekly", "monthly"]),
+    }, async (params) => text(await apiCall("/v1/tools/set_project_quota", params)));
+    server.tool("get_latency_report", "Show P50/P95/P99 latency per provider and model.", {
+        days: z.number().optional().default(7),
+    }, async (params) => text(await apiCall("/v1/tools/get_latency_report", params)));
+    server.tool("set_model_alias", "Map a friendly name to a routing rule.", {
+        alias: z.string(),
+        provider: z.string(),
+        model: z.string(),
+    }, async (params) => text(await apiCall("/v1/tools/set_model_alias", params)));
+    // ─── Team Tier ───────────────────────────────────────────
+    server.tool("get_team_spend", "Get aggregated spend across all team members.", {
+        days: z.number().optional().default(30),
+    }, async (params) => text(await apiCall("/v1/tools/get_team_spend", params)));
+    server.tool("set_team_budget", "Set an organization-level budget cap.", {
+        limit: z.number(),
+        period: z.enum(["daily", "weekly", "monthly"]),
+    }, async (params) => text(await apiCall("/v1/tools/set_team_budget", params)));
+    // Connect
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@yawlabs/tokenmeter-mcp",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Token Meter MCP client — LLM spend tracking, smart routing, and rate limit management",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "tokenmeter-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "keywords": ["mcp", "llm", "tokens", "cost", "pricing", "ai"],
+  "author": "Yaw Labs",
+  "license": "UNLICENSED",
+  "homepage": "https://tokenmeter.sh",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+
+/**
+ * Token Meter MCP Client
+ *
+ * This is the ONLY code distributed to users.
+ * It is a thin API client — all business logic runs on tokenmeter.sh.
+ *
+ * The client:
+ * 1. Connects to the user's MCP host (Claude, Cursor, Yaw, etc.)
+ * 2. Registers tools by fetching the tool list from the API
+ * 3. When a tool is called, proxies the request to api.tokenmeter.sh
+ * 4. Returns the response to the MCP host
+ *
+ * No provider translation, routing, cost calculation, or pricing data
+ * is included in this package.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const API_BASE = process.env.TOKENMETER_API_URL ?? "https://api.tokenmeter.sh";
+const API_KEY = process.env.TOKENMETER_API_KEY ?? "";
+
+async function apiCall(endpoint: string, params: Record<string, unknown> = {}): Promise<unknown> {
+  const res = await fetch(`${API_BASE}${endpoint}`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...(API_KEY ? { authorization: `Bearer ${API_KEY}` } : {}),
+    },
+    body: JSON.stringify(params),
+  });
+
+  if (!res.ok) {
+    const error = await res.text().catch(() => "Unknown error");
+    throw new Error(`Token Meter API error (${res.status}): ${error}`);
+  }
+
+  return res.json();
+}
+
+function text(data: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+}
+
+async function main() {
+  if (!API_KEY) {
+    console.error("TOKENMETER_API_KEY is required. Get your key at https://tokenmeter.sh/settings");
+    process.exit(1);
+  }
+
+  const server = new McpServer({ name: "tokenmeter", version: "0.1.0" });
+
+  // ─── Free Tier ───────────────────────────────────────────
+
+  server.tool(
+    "get_spend_summary",
+    "Get total LLM spend for today, this week, and this month, broken down by provider.",
+    {},
+    async () => text(await apiCall("/v1/tools/get_spend_summary"))
+  );
+
+  server.tool(
+    "get_session_cost",
+    "Get the cost of the current conversation/session.",
+    {},
+    async () => text(await apiCall("/v1/tools/get_session_cost"))
+  );
+
+  server.tool(
+    "get_model_pricing",
+    "Get current per-token pricing for any model or provider.",
+    {
+      model: z.string().optional().describe("Model ID"),
+      provider: z.string().optional().describe("Provider name"),
+    },
+    async (params) => text(await apiCall("/v1/tools/get_model_pricing", params))
+  );
+
+  server.tool(
+    "get_budget_status",
+    "Check current spend against configured budget limits.",
+    {},
+    async () => text(await apiCall("/v1/tools/get_budget_status"))
+  );
+
+  server.tool(
+    "get_providers",
+    "List connected LLM providers and their status.",
+    {},
+    async () => text(await apiCall("/v1/tools/get_providers"))
+  );
+
+  // ─── Pro Tier ────────────────────────────────────────────
+
+  server.tool(
+    "get_spend_breakdown",
+    "Detailed spend breakdown with filters by provider, model, project, and date range.",
+    {
+      provider: z.string().optional(),
+      days: z.number().optional().default(7),
+    },
+    async (params) => text(await apiCall("/v1/tools/get_spend_breakdown", params))
+  );
+
+  server.tool(
+    "get_cost_trend",
+    "Show daily spend over time to identify trends.",
+    {
+      days: z.number().optional().default(14),
+    },
+    async (params) => text(await apiCall("/v1/tools/get_cost_trend", params))
+  );
+
+  server.tool(
+    "get_top_models",
+    "Rank models by spend or token volume.",
+    {
+      sortBy: z.enum(["cost", "tokens"]).optional().default("cost"),
+      days: z.number().optional().default(30),
+    },
+    async (params) => text(await apiCall("/v1/tools/get_top_models", params))
+  );
+
+  server.tool(
+    "get_cost_estimate",
+    "Estimate cost for a given number of tokens on specified models.",
+    {
+      models: z.array(z.string()),
+      inputTokens: z.number(),
+      outputTokens: z.number().optional().default(500),
+      useCache: z.boolean().optional().default(false),
+    },
+    async (params) => text(await apiCall("/v1/tools/get_cost_estimate", params))
+  );
+
+  server.tool(
+    "compare_models",
+    "Compare models on cost for a specific workload.",
+    {
+      inputTokens: z.number(),
+      outputTokens: z.number(),
+      callsPerDay: z.number().optional().default(100),
+      provider: z.string().optional(),
+    },
+    async (params) => text(await apiCall("/v1/tools/compare_models", params))
+  );
+
+  server.tool(
+    "get_anomalies",
+    "Flag unusual spend spikes compared to historical average.",
+    {},
+    async () => text(await apiCall("/v1/tools/get_anomalies"))
+  );
+
+  server.tool(
+    "set_budget_alert",
+    "Create a spend threshold notification or hard cap.",
+    {
+      name: z.string(),
+      limit: z.number(),
+      period: z.enum(["daily", "weekly", "monthly"]),
+      hardCap: z.boolean().optional().default(false),
+    },
+    async (params) => text(await apiCall("/v1/tools/set_budget_alert", params))
+  );
+
+  server.tool(
+    "set_budget_cap",
+    "Set a hard spending cap that blocks requests when hit.",
+    {
+      limit: z.number(),
+      period: z.enum(["daily", "weekly", "monthly"]),
+    },
+    async (params) => text(await apiCall("/v1/tools/set_budget_cap", params))
+  );
+
+  server.tool(
+    "tag_session",
+    "Label the current session with a project name for cost attribution.",
+    {
+      project: z.string(),
+    },
+    async (params) => text(await apiCall("/v1/tools/tag_session", params))
+  );
+
+  server.tool(
+    "export_report",
+    "Generate a spend report for a date range.",
+    {
+      days: z.number().optional().default(30),
+      format: z.enum(["json", "csv"]).optional().default("json"),
+    },
+    async (params) => text(await apiCall("/v1/tools/export_report", params))
+  );
+
+  // ─── Gateway Tier ────────────────────────────────────────
+
+  server.tool(
+    "get_rate_limits",
+    "Show current rate limit status per provider and model.",
+    {},
+    async () => text(await apiCall("/v1/tools/get_rate_limits"))
+  );
+
+  server.tool(
+    "get_routing_status",
+    "Show which providers are healthy, degraded, or rate-limited.",
+    {},
+    async () => text(await apiCall("/v1/tools/get_routing_status"))
+  );
+
+  server.tool(
+    "set_routing_rule",
+    "Configure routing preferences (cheapest, fastest, specific provider).",
+    {
+      name: z.string(),
+      strategy: z.enum(["cheapest", "fastest", "specific"]),
+      provider: z.string().optional(),
+      model: z.string().optional(),
+    },
+    async (params) => text(await apiCall("/v1/tools/set_routing_rule", params))
+  );
+
+  server.tool(
+    "set_fallback_chain",
+    "Define provider failover order.",
+    {
+      chain: z.array(z.object({
+        provider: z.string(),
+        model: z.string(),
+      })),
+    },
+    async (params) => text(await apiCall("/v1/tools/set_fallback_chain", params))
+  );
+
+  server.tool(
+    "set_project_quota",
+    "Set a hard spend cap per project.",
+    {
+      project: z.string(),
+      limit: z.number(),
+      period: z.enum(["daily", "weekly", "monthly"]),
+    },
+    async (params) => text(await apiCall("/v1/tools/set_project_quota", params))
+  );
+
+  server.tool(
+    "get_latency_report",
+    "Show P50/P95/P99 latency per provider and model.",
+    {
+      days: z.number().optional().default(7),
+    },
+    async (params) => text(await apiCall("/v1/tools/get_latency_report", params))
+  );
+
+  server.tool(
+    "set_model_alias",
+    "Map a friendly name to a routing rule.",
+    {
+      alias: z.string(),
+      provider: z.string(),
+      model: z.string(),
+    },
+    async (params) => text(await apiCall("/v1/tools/set_model_alias", params))
+  );
+
+  // ─── Team Tier ───────────────────────────────────────────
+
+  server.tool(
+    "get_team_spend",
+    "Get aggregated spend across all team members.",
+    {
+      days: z.number().optional().default(30),
+    },
+    async (params) => text(await apiCall("/v1/tools/get_team_spend", params))
+  );
+
+  server.tool(
+    "set_team_budget",
+    "Set an organization-level budget cap.",
+    {
+      limit: z.number(),
+      period: z.enum(["daily", "weekly", "monthly"]),
+    },
+    async (params) => text(await apiCall("/v1/tools/set_team_budget", params))
+  );
+
+  // Connect
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "declaration": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}