clawbackai-mcp 1.0.0

package/README.md

@@ -0,0 +1,115 @@
+# clawbackai-mcp
+
+LLM cost optimization tools for AI agents via the Model Context Protocol. Audit your spend, activate smart routing, and track savings without changing your code.
+
+## Quick start
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "clawback": {
+      "url": "https://clawback.run/mcp"
+    }
+  }
+}
+```
+
+## Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "clawback": {
+      "command": "npx",
+      "args": ["clawbackai-mcp"]
+    }
+  }
+}
+```
+
+## Claude Code
+
+```bash
+claude mcp add clawback -- npx clawbackai-mcp
+```
+
+## CrewAI
+
+```python
+from crewai import Agent
+from crewai_tools import MCPServerAdapter
+
+mcp_adapter = MCPServerAdapter({"url": "https://clawback.run/mcp"})
+
+agent = Agent(
+    role="LLM Cost Optimizer",
+    tools=mcp_adapter.tools
+)
+```
+
+## LangGraph
+
+```python
+from langchain_mcp_adapters.client import MultiServerMCPClient
+
+client = MultiServerMCPClient({
+    "clawback": {
+        "url": "https://clawback.run/mcp",
+        "transport": "streamable_http",
+    }
+})
+
+tools = await client.get_tools()
+```
+
+## Vercel AI SDK
+
+```typescript
+import { experimental_createMCPClient } from "ai";
+
+const mcp = await experimental_createMCPClient({
+  transport: { type: "sse", url: "https://clawback.run/mcp" },
+});
+
+const tools = await mcp.tools();
+```
+
+## Tools
+
+| Tool | Description | Auth |
+|------|-------------|------|
+| `start_audit` | Start a free LLM cost audit. Set one env var, Clawback observes your API calls and generates a savings report. | API key |
+| `get_audit_status` | Check audit progress, call count, report URL, and routing recommendations. | API key |
+| `activate_routing` | Activate smart routing after audit completes. Strategies: balanced, max_savings, conservative. | API key |
+| `optimize_llm_call` | Route a completion to the best price-performance model for the task type. | API key |
+| `get_frontier` | Get the efficient frontier (best quality per dollar) by task type. | None |
+| `check_savings` | Check monthly and all-time routing value. | API key |
+| `get_model_recommendation` | Get a model recommendation for a task type without making an API call. | None |
+| `set_agent_budget` | Set a monthly budget limit per agent with action on exceed (block, downgrade, alert). | API key |
+
+## How it works
+
+1. **Audit first.** Call `start_audit` to register. Set your `OPENAI_BASE_URL` to `https://clawback.run/v1`. Your API calls flow through Clawback's proxy — zero latency impact, your keys, your data.
+
+2. **Get your report.** At 50 calls, Clawback generates an audit report. It replays your calls against cheaper models, scores quality per task type, and tells you exactly how much you can save.
+
+3. **Activate routing.** Review the report. If the savings are real, call `activate_routing`. Every subsequent call gets routed to the optimal model on the efficient frontier.
+
+4. **Track savings.** Use `check_savings` to see your monthly routing value. Free until routing value exceeds $500/month, then 15% of the price difference per routed call.
+
+## Pricing
+
+- Free audit, always
+- Smart routing: 15% of the price difference per routed call
+- Free until routing value exceeds $500/month
+- You keep 85% of every dollar saved
+
+## Links
+
+- Website: [clawback.run](https://clawback.run)
+- Efficient Frontier: [clawback.run/frontier](https://clawback.run/frontier)
+- Security: [clawback.run/security](https://clawback.run/security)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const CLAWBACK_MCP_URL = "https://clawback.run/mcp";
+async function callClawback(toolName, args) {
+    const res = await fetch(CLAWBACK_MCP_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: Date.now(),
+            method: "tools/call",
+            params: { name: toolName, arguments: args },
+        }),
+    });
+    const body = await res.json();
+    if (body.error)
+        throw new Error(body.error.message);
+    const text = body.result?.content?.[0]?.text;
+    return text ? JSON.parse(text) : body.result;
+}
+const server = new McpServer({
+    name: "clawback",
+    version: "1.0.0",
+});
+// Step 1: Start audit
+server.tool("start_audit", "Start a free Clawback audit. Registers your API key for traffic observation. Route 50+ calls through clawback.run/v1 to trigger the audit automatically.", {
+    api_key: z.string().describe("Your provider API key (hashed for identification, never stored raw)"),
+    email: z.string().optional().describe("Optional email for report delivery"),
+}, async (args) => {
+    const result = await callClawback("start_audit", args);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// Step 2: Check audit status
+server.tool("get_audit_status", "Check audit progress. Returns calls logged, report URL when ready, routing recommendations, and next steps. Share the report URL with a human decision maker.", {
+    api_key: z.string().describe("Your API key"),
+}, async (args) => {
+    const result = await callClawback("get_audit_status", args);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// Step 3: Activate routing (after audit review)
+server.tool("activate_routing", "Activate smart routing after reviewing audit results. Only call after get_audit_status shows a completed report.", {
+    api_key: z.string().describe("Your API key"),
+    strategy: z.enum(["balanced", "max_savings", "conservative"]).optional().describe("Routing strategy"),
+}, async (args) => {
+    const result = await callClawback("activate_routing", args);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// Step 4: Use optimized routing
+server.tool("optimize_llm_call", "Route a completion to the best model. Requires routing to be activated first via the audit flow.", {
+    model: z.string().describe("The model you would normally use"),
+    messages: z.array(z.any()).describe("OpenAI-format messages array"),
+    temperature: z.number().optional(),
+    max_tokens: z.number().int().optional(),
+    api_key: z.string().describe("Your provider API key"),
+}, async (args) => {
+    const result = await callClawback("optimize_llm_call", args);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// Read-only tools (no auth required)
+server.tool("get_frontier", "Get the efficient frontier — best quality per dollar by task type. No API key needed.", {
+    task_type: z.enum(["general", "coding", "classification"]).optional().describe("Task type"),
+}, async (args) => {
+    const result = await callClawback("get_frontier", args);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("check_savings", "Check monthly and all-time routing value (price difference captured per routed call).", {
+    api_key: z.string().describe("Your API key"),
+}, async (args) => {
+    const result = await callClawback("check_savings", args);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("get_model_recommendation", "Get the recommended model for a task type without making an API call. No key needed.", {
+    task_type: z.string().optional().describe("Task type"),
+    max_cost_per_million: z.number().optional().describe("Max cost per million tokens"),
+    min_quality: z.number().optional().describe("Minimum quality score (0-100)"),
+}, async (args) => {
+    const result = await callClawback("get_model_recommendation", args);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("set_agent_budget", "Set per-agent monthly budget. Requires routing to be active.", {
+    api_key: z.string().describe("Your API key"),
+    agent_name: z.string().describe("Agent name"),
+    monthly_budget_usd: z.number().describe("Monthly budget in USD"),
+    action_on_exceed: z.enum(["block", "downgrade", "alert"]).optional(),
+}, async (args) => {
+    const result = await callClawback("set_agent_budget", args);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "clawbackai-mcp",
+  "version": "1.0.0",
+  "mcpName": "io.github.Rckl88/clawbackai-mcp",
+  "description": "Clawback MCP server — LLM cost optimization tools for AI agents. Audit your LLM spend, activate smart routing, and track savings via the Model Context Protocol.",
+  "main": "dist/index.js",
+  "bin": { "clawbackai-mcp": "dist/index.js" },
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Alex Crabbe",
+    "email": "alex@clawback.run",
+    "url": "https://clawback.run"
+  },
+  "homepage": "https://clawback.run",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Rckl88/clawbackai"
+  },
+  "keywords": [
+    "mcp",
+    "llm",
+    "cost-optimization",
+    "model-routing",
+    "ai-agents",
+    "efficient-frontier",
+    "openai",
+    "anthropic",
+    "model-context-protocol",
+    "clawback"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}