@agentistics/mcp 1.3.3

package/README.md

@@ -0,0 +1,58 @@
+# @agentistics/mcp
+
+MCP server that exposes your [Claude Code](https://claude.ai/code) analytics as tools for Claude Desktop, Claude Code agents, and any MCP-compatible client.
+
+## What it does
+
+Reads data from `~/.claude/` (the same data [agentistics](https://github.com/blpsoares/agentistics) visualizes) and exposes it as 12 structured MCP tools.
+
+## Usage
+
+### With agentistics server (recommended)
+
+The MCP server is included and auto-registered when you run `agentop server`. No separate install needed.
+
+### Standalone with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "agentistics": {
+      "command": "npx",
+      "args": ["-y", "@agentistics/mcp"],
+      "env": {
+        "AGENTISTICS_API": "http://localhost:47291"
+      }
+    }
+  }
+}
+```
+
+The `AGENTISTICS_API` env var must point to a running agentistics server.
+
+## Available tools
+
+| Tool | Returns |
+|------|---------|
+| `agentistics_summary` | All-time totals: tokens, cost, sessions, streak, cache hit rate |
+| `agentistics_projects` | Per-project token and cost breakdown |
+| `agentistics_sessions` | Recent sessions with duration, model, cost |
+| `agentistics_costs` | Model pricing breakdown and cache savings |
+| `agentistics_component_catalog` | Available dashboard components |
+| `agentistics_get_layouts` | Current custom page layouts |
+| `agentistics_build_layout` | Create a full layout from a component list |
+| `agentistics_add_component` | Add one component to an existing layout |
+| `agentistics_remove_component` | Remove a component by instance ID |
+| `agentistics_create_layout` | Create a new empty layout |
+| `agentistics_set_active_layout` | Switch the active /custom layout |
+| `agentistics_delete_layout` | Delete a layout permanently |
+
+## Requirements
+
+Requires a running agentistics server (`agentop server` or the Windows desktop app). The MCP server proxies requests to `http://localhost:47291` by default.
+
+## License
+
+MIT — part of the [agentistics](https://github.com/blpsoares/agentistics) project.

package/dist/agentistics-mcp.js

@@ -0,0 +1,625 @@
+#!/usr/bin/env node
+
+// agentistics-mcp.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// ../core/src/types.ts
+var MODEL_PRICING = {
+  "claude-opus-4-7": { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+  "claude-opus-4-6": { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+  "claude-sonnet-4-6": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+  "claude-haiku-4-5-20251001": { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+  "claude-opus-4-5-20251101": { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+  "claude-opus-4-1-20250805": { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+  "claude-opus-4-20250514": { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+  "claude-sonnet-4-5-20250929": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+  "claude-sonnet-4-20250514": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+  "claude-haiku-3-5-20241022": { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1 },
+  "claude-3-haiku-20240307": { input: 0.25, output: 1.25, cacheRead: 0.03, cacheWrite: 0.3 }
+};
+function getModelPrice(modelId) {
+  if (MODEL_PRICING[modelId])
+    return MODEL_PRICING[modelId];
+  for (const [key, price] of Object.entries(MODEL_PRICING)) {
+    if (modelId.startsWith(key) || key.startsWith(modelId))
+      return price;
+  }
+  return { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 };
+}
+function calcCost(usage, modelId) {
+  const price = getModelPrice(modelId);
+  return usage.inputTokens / 1e6 * price.input + usage.outputTokens / 1e6 * price.output + usage.cacheReadInputTokens / 1e6 * price.cacheRead + usage.cacheCreationInputTokens / 1e6 * price.cacheWrite;
+}
+// agentistics-mcp.ts
+var API = process.env.AGENTISTICS_API ?? "http://localhost:47291";
+function calcCostUSD(input, output, cacheRead, cacheWrite, model) {
+  return calcCost({
+    inputTokens: input,
+    outputTokens: output,
+    cacheReadInputTokens: cacheRead,
+    cacheCreationInputTokens: cacheWrite,
+    webSearchRequests: 0,
+    costUSD: 0
+  }, model);
+}
+var CATALOG = [
+  { id: "kpi.messages", label: "Messages", category: "kpi", defaultW: 3, defaultH: 3, minW: 2, minH: 2, description: "Total message count in selected period" },
+  { id: "kpi.sessions", label: "Sessions", category: "kpi", defaultW: 3, defaultH: 3, minW: 2, minH: 2, description: "Session count + avg msgs/session" },
+  { id: "kpi.tool-calls", label: "Tool calls", category: "kpi", defaultW: 3, defaultH: 3, minW: 2, minH: 2, description: "Total tool execution count" },
+  { id: "kpi.cost", label: "Estimated cost", category: "kpi", defaultW: 3, defaultH: 3, minW: 2, minH: 2, description: "Estimated USD cost" },
+  { id: "kpi.streak", label: "Streak", category: "kpi", defaultW: 3, defaultH: 3, minW: 2, minH: 2, description: "Consecutive days streak" },
+  { id: "kpi.longest-session", label: "Longest session", category: "kpi", defaultW: 3, defaultH: 3, minW: 2, minH: 2, description: "Duration of longest session" },
+  { id: "kpi.commits", label: "Commits", category: "kpi", defaultW: 3, defaultH: 3, minW: 2, minH: 2, description: "Git commits via Claude" },
+  { id: "kpi.files", label: "Files modified", category: "kpi", defaultW: 3, defaultH: 3, minW: 2, minH: 2, description: "Files modified + line diff" },
+  { id: "kpi.input-tokens", label: "Input tokens", category: "kpi", defaultW: 3, defaultH: 3, minW: 2, minH: 2, description: "Input tokens sent to model" },
+  { id: "kpi.output-tokens", label: "Output tokens", category: "kpi", defaultW: 3, defaultH: 3, minW: 2, minH: 2, description: "Output tokens generated by model" },
+  { id: "activity.chart", label: "Activity chart (full)", category: "activity", defaultW: 8, defaultH: 7, minW: 4, minH: 4, description: "Full activity chart with all metrics" },
+  { id: "activity.chart.messages", label: "Activity — Messages only", category: "activity", defaultW: 6, defaultH: 6, minW: 3, minH: 3, description: "Daily messages bar chart" },
+  { id: "activity.chart.sessions", label: "Activity — Sessions only", category: "activity", defaultW: 6, defaultH: 6, minW: 3, minH: 3, description: "Daily sessions bar chart" },
+  { id: "activity.chart.tools", label: "Activity — Tool calls only", category: "activity", defaultW: 6, defaultH: 6, minW: 3, minH: 3, description: "Daily tool calls bar chart" },
+  { id: "activity.chart.overlay", label: "Activity — Overlay", category: "activity", defaultW: 8, defaultH: 6, minW: 4, minH: 3, description: "Overlay visualization of all metrics" },
+  { id: "activity.heatmap", label: "Activity heatmap", category: "activity", defaultW: 6, defaultH: 6, minW: 3, minH: 3, description: "Calendar heatmap of daily activity" },
+  { id: "activity.hours", label: "Usage by hour", category: "activity", defaultW: 8, defaultH: 6, minW: 4, minH: 3, description: "Hourly usage breakdown" },
+  { id: "costs.models", label: "Model usage", category: "costs", defaultW: 12, defaultH: 7, minW: 6, minH: 4, description: "Cost and token breakdown by model" },
+  { id: "costs.budget", label: "Budget & forecast", category: "costs", defaultW: 6, defaultH: 7, minW: 4, minH: 4, description: "Monthly budget progress and cost forecast" },
+  { id: "costs.cache", label: "Cache efficiency", category: "costs", defaultW: 6, defaultH: 7, minW: 4, minH: 4, description: "Cache hit rate and savings" },
+  { id: "projects.top", label: "Top projects", category: "projects", defaultW: 7, defaultH: 7, minW: 4, minH: 4, description: "Most active projects ranked by metrics" },
+  { id: "projects.languages", label: "Languages", category: "projects", defaultW: 5, defaultH: 6, minW: 3, minH: 3, description: "Language distribution word cloud" },
+  { id: "tools.metrics", label: "Tool metrics (full)", category: "tools", defaultW: 12, defaultH: 8, minW: 6, minH: 4, description: "Full breakdown of tool usage by type" },
+  { id: "tools.metrics.calls", label: "Tool metrics — calls only", category: "tools", defaultW: 8, defaultH: 7, minW: 4, minH: 4, description: "Tool call counts chart" },
+  { id: "tools.metrics.tokens", label: "Tool metrics — tokens only", category: "tools", defaultW: 8, defaultH: 7, minW: 4, minH: 4, description: "Tokens consumed per tool type" },
+  { id: "tools.agents", label: "Agent metrics", category: "tools", defaultW: 12, defaultH: 8, minW: 6, minH: 4, description: "Sub-agent invocation metrics, durations, costs" },
+  { id: "sessions.highlights", label: "Highlights", category: "sessions", defaultW: 12, defaultH: 6, minW: 6, minH: 3, description: "Record-breaking sessions" },
+  { id: "sessions.recent", label: "Recent sessions", category: "sessions", defaultW: 12, defaultH: 7, minW: 6, minH: 4, description: "List of most recent sessions" }
+];
+async function apiGet(path) {
+  const res = await fetch(`${API}${path}`);
+  if (!res.ok)
+    throw new Error(`agentistics API ${path} → HTTP ${res.status}`);
+  return res.json();
+}
+async function getPrefs() {
+  return apiGet("/api/preferences");
+}
+async function putPrefs(patch) {
+  const res = await fetch(`${API}/api/preferences`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(patch)
+  });
+  if (!res.ok)
+    throw new Error(`PUT /api/preferences → HTTP ${res.status}`);
+  return res.json();
+}
+function nextId(items) {
+  let max = 0;
+  for (const item of items) {
+    const n = parseInt(item.i, 10);
+    if (!isNaN(n) && n > max)
+      max = n;
+  }
+  return String(max + 1);
+}
+function autoPosition(items, newW = 3, gridW = 12) {
+  if (items.length === 0)
+    return { x: 0, y: 0 };
+  const maxBottom = Math.max(...items.map((i) => i.y + i.h));
+  for (let y = 0;y <= maxBottom; y++) {
+    const blocks = items.filter((i) => i.y <= y && i.y + i.h > y).map((i) => ({ start: i.x, end: i.x + i.w })).sort((a, b) => a.start - b.start);
+    let x = 0;
+    for (const block of blocks) {
+      if (block.start >= x + newW)
+        break;
+      if (block.end > x)
+        x = block.end;
+    }
+    if (x + newW <= gridW)
+      return { x, y };
+  }
+  return { x: 0, y: maxBottom };
+}
+function fillGaps(items, gridW = 12) {
+  for (const item of items) {
+    const rightEdge = item.x + item.w;
+    if (rightEdge >= gridW)
+      continue;
+    const hasRightNeighbour = items.some((other) => other !== item && other.x >= rightEdge && other.y < item.y + item.h && other.y + other.h > item.y);
+    if (!hasRightNeighbour) {
+      item.w = gridW - item.x;
+    }
+  }
+}
+var server = new Server({ name: "agentistics", version: "1.0.0" }, { capabilities: { tools: {} } });
+var TOOLS = [
+  {
+    name: "agentistics_summary",
+    description: "Get an overview of Claude Code usage metrics: total tokens, estimated cost, sessions, streak, most used model, and top project. Good starting point for any metrics question.",
+    inputSchema: { type: "object", properties: {}, required: [] }
+  },
+  {
+    name: "agentistics_projects",
+    description: "List all Claude Code projects with session counts, message counts, token usage, estimated cost, and last active date.",
+    inputSchema: { type: "object", properties: {}, required: [] }
+  },
+  {
+    name: "agentistics_sessions",
+    description: "Get the most recent Claude Code sessions with project path, duration, message count, token usage, and model.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "number",
+          description: "Max sessions to return (default 20, max 50)"
+        }
+      }
+    }
+  },
+  {
+    name: "agentistics_costs",
+    description: "Get cost breakdown by model: token counts (input/output/cache read/write) and estimated USD cost per model.",
+    inputSchema: { type: "object", properties: {}, required: [] }
+  },
+  {
+    name: "agentistics_component_catalog",
+    description: "List all components available for the custom layout page, with IDs, categories, descriptions, and default grid sizes. Call this before building or modifying a layout.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: {
+          type: "string",
+          description: "Filter by category: kpi, activity, costs, projects, tools, sessions"
+        }
+      }
+    }
+  },
+  {
+    name: "agentistics_get_layouts",
+    description: "Get all custom layouts: names, components in each, which is active, and each component's instance ID for removal.",
+    inputSchema: { type: "object", properties: {}, required: [] }
+  },
+  {
+    name: "agentistics_create_layout",
+    description: "Create a new empty named layout on the custom page.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Name for the new layout" }
+      },
+      required: ["name"]
+    }
+  },
+  {
+    name: "agentistics_add_component",
+    description: "Add a single component to a layout. Use agentistics_component_catalog to get valid componentId values. Positioned automatically at the bottom of the grid unless x/y are given.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        layoutName: {
+          type: "string",
+          description: "Target layout name. Omit to use the currently active layout."
+        },
+        componentId: {
+          type: "string",
+          description: "Component ID from the catalog (e.g. 'kpi.cost', 'activity.chart')"
+        },
+        x: {
+          type: "number",
+          description: "Column (0–11). Optional — auto-placed if omitted."
+        },
+        y: {
+          type: "number",
+          description: "Row. Optional — auto-placed if omitted."
+        },
+        w: {
+          type: "number",
+          description: "Width in grid units (1–12). Optional — uses default."
+        },
+        h: {
+          type: "number",
+          description: "Height in grid units. Optional — uses default."
+        }
+      },
+      required: ["componentId"]
+    }
+  },
+  {
+    name: "agentistics_remove_component",
+    description: "Remove a component from a layout by its instance ID (the 'instanceId' field from agentistics_get_layouts).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        layoutName: {
+          type: "string",
+          description: "Layout name. Omit to use the active layout."
+        },
+        itemId: {
+          type: "string",
+          description: "Instance ID of the item to remove"
+        }
+      },
+      required: ["itemId"]
+    }
+  },
+  {
+    name: "agentistics_set_active_layout",
+    description: "Switch the active layout shown on the /custom page.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Name of the layout to activate" }
+      },
+      required: ["name"]
+    }
+  },
+  {
+    name: "agentistics_delete_layout",
+    description: "Delete a named layout. Cannot delete the last remaining layout.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Name of the layout to delete" }
+      },
+      required: ["name"]
+    }
+  },
+  {
+    name: "agentistics_export_pdf",
+    description: "Generate a PDF report of Claude Code usage. Returns a URL that, when opened in a browser, automatically opens the PDF export modal pre-configured with the requested options. The user can review settings and click Download to save the PDF.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        range: {
+          type: "string",
+          enum: ["7d", "30d", "90d", "all"],
+          description: "Date range for the report (default: all)"
+        }
+      }
+    }
+  },
+  {
+    name: "agentistics_build_layout",
+    description: "Build a complete layout in one call: creates it, adds all requested components with auto-positioning, and optionally activates it. Ideal for setting up a themed dashboard from scratch.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Name for the layout" },
+        componentIds: {
+          type: "array",
+          items: { type: "string" },
+          description: "Ordered array of component IDs to add"
+        },
+        activate: {
+          type: "boolean",
+          description: "Set as active layout after building (default true)"
+        }
+      },
+      required: ["name", "componentIds"]
+    }
+  }
+];
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  try {
+    switch (name) {
+      case "agentistics_summary": {
+        const data = await apiGet("/api/data");
+        const sc = data.statsCache ?? {};
+        const totals = sc.allTimeTotals ?? {};
+        const models = sc.modelUsage ?? {};
+        const topModel = Object.entries(models).sort(([, a], [, b]) => (b.totalTokens ?? 0) - (a.totalTokens ?? 0))[0]?.[0] ?? "—";
+        const projects = data.projects ?? [];
+        const topProject = [...projects].sort((a, b) => (b.sessions?.length ?? 0) - (a.sessions?.length ?? 0))[0]?.name ?? "—";
+        const allSessions = data.sessions ?? [];
+        let totalCostUSD = 0;
+        let totalInput = 0, totalOutput = 0, totalCacheRead = 0, totalCacheWrite = 0;
+        for (const s of allSessions) {
+          const inp = s.input_tokens ?? 0;
+          const out = s.output_tokens ?? 0;
+          const cr = s.cache_read_input_tokens ?? 0;
+          const cw = s.cache_creation_input_tokens ?? 0;
+          totalInput += inp;
+          totalOutput += out;
+          totalCacheRead += cr;
+          totalCacheWrite += cw;
+          totalCostUSD += calcCostUSD(inp, out, cr, cw, s.model ?? "");
+        }
+        const finalInput = totalInput || (totals.inputTokens ?? 0);
+        const finalOutput = totalOutput || (totals.outputTokens ?? 0);
+        const finalCacheRead = totalCacheRead || (totals.cacheReadTokens ?? 0);
+        const finalCacheWrite = totalCacheWrite || (totals.cacheWriteTokens ?? 0);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              totalInputTokens: finalInput,
+              totalOutputTokens: finalOutput,
+              totalCacheReadTokens: finalCacheRead,
+              totalCacheWriteTokens: finalCacheWrite,
+              estimatedCostUSD: Math.round(totalCostUSD * 100) / 100,
+              totalSessions: allSessions.length,
+              totalProjects: projects.length,
+              topModel,
+              topProject,
+              activeDays: sc.activeDays ?? 0,
+              currentStreak: sc.currentStreak ?? 0
+            }, null, 2)
+          }]
+        };
+      }
+      case "agentistics_projects": {
+        const data = await apiGet("/api/data");
+        const allSessions = data.sessions ?? [];
+        const byPath = {};
+        for (const s of allSessions) {
+          const key = s.project_path;
+          if (!key)
+            continue;
+          if (!byPath[key])
+            byPath[key] = { inputTokens: 0, outputTokens: 0, cacheRead: 0, cacheWrite: 0, costUSD: 0, messages: 0, lastActive: "", languages: [] };
+          const agg = byPath[key];
+          const inp = s.input_tokens ?? 0;
+          const out = s.output_tokens ?? 0;
+          const cr = s.cache_read_input_tokens ?? 0;
+          const cw = s.cache_creation_input_tokens ?? 0;
+          agg.inputTokens += inp;
+          agg.outputTokens += out;
+          agg.cacheRead += cr;
+          agg.cacheWrite += cw;
+          agg.costUSD += calcCostUSD(inp, out, cr, cw, s.model ?? "");
+          agg.messages += (s.user_message_count ?? 0) + (s.assistant_message_count ?? 0);
+          if (!agg.lastActive || (s.start_time ?? "") > agg.lastActive)
+            agg.lastActive = s.start_time ?? "";
+          for (const lang of s.languages ?? [])
+            if (!agg.languages.includes(lang))
+              agg.languages.push(lang);
+        }
+        const projects = data.projects ?? [];
+        const summary = projects.map((p) => {
+          const agg = byPath[p.path] ?? { inputTokens: 0, outputTokens: 0, cacheRead: 0, cacheWrite: 0, costUSD: 0, messages: 0, lastActive: "", languages: [] };
+          return {
+            name: p.name,
+            path: p.path,
+            sessions: (p.sessions ?? []).length,
+            messages: agg.messages,
+            inputTokens: agg.inputTokens,
+            outputTokens: agg.outputTokens,
+            totalTokens: agg.inputTokens + agg.outputTokens,
+            estimatedCostUSD: Math.round(agg.costUSD * 1e4) / 1e4,
+            lastActive: agg.lastActive || null,
+            languages: agg.languages
+          };
+        }).sort((a, b) => b.totalTokens - a.totalTokens);
+        return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
+      }
+      case "agentistics_sessions": {
+        const limit = Math.min(args?.limit ?? 20, 50);
+        const data = await apiGet("/api/data");
+        const rows = (data.sessions ?? []).slice(0, limit).map((s) => {
+          const inp = s.input_tokens ?? 0;
+          const out = s.output_tokens ?? 0;
+          const cr = s.cache_read_input_tokens ?? 0;
+          const cw = s.cache_creation_input_tokens ?? 0;
+          return {
+            id: s.session_id,
+            project: s.project_path,
+            startedAt: s.start_time,
+            durationMinutes: s.duration_minutes,
+            messages: (s.user_message_count ?? 0) + (s.assistant_message_count ?? 0),
+            inputTokens: inp,
+            outputTokens: out,
+            cacheReadTokens: cr,
+            cacheWriteTokens: cw,
+            totalTokens: inp + out + cr + cw,
+            estimatedCostUSD: Math.round(calcCostUSD(inp, out, cr, cw, s.model ?? "") * 1e4) / 1e4,
+            model: s.model ?? null
+          };
+        });
+        return { content: [{ type: "text", text: JSON.stringify(rows, null, 2) }] };
+      }
+      case "agentistics_costs": {
+        const data = await apiGet("/api/data");
+        const usage = data.statsCache?.modelUsage ?? {};
+        const breakdown = Object.entries(usage).map(([model, u]) => ({
+          model,
+          inputTokens: u.inputTokens ?? 0,
+          outputTokens: u.outputTokens ?? 0,
+          cacheReadTokens: u.cacheReadTokens ?? 0,
+          cacheWriteTokens: u.cacheWriteTokens ?? 0,
+          totalTokens: u.totalTokens ?? 0,
+          estimatedCostUSD: u.costUSD ?? 0
+        })).sort((a, b) => b.totalTokens - a.totalTokens);
+        return { content: [{ type: "text", text: JSON.stringify(breakdown, null, 2) }] };
+      }
+      case "agentistics_component_catalog": {
+        const category = args?.category;
+        const items = category ? CATALOG.filter((c) => c.category === category) : CATALOG;
+        return { content: [{ type: "text", text: JSON.stringify(items, null, 2) }] };
+      }
+      case "agentistics_get_layouts": {
+        const prefs = await getPrefs();
+        const layouts = prefs.layouts ?? {};
+        const active = prefs.activeLayout ?? "";
+        const summary = Object.entries(layouts).map(([layoutName, items]) => ({
+          name: layoutName,
+          isActive: layoutName === active,
+          componentCount: items.length,
+          components: items.map((item) => ({
+            instanceId: item.i,
+            componentId: item.componentId,
+            x: item.x,
+            y: item.y,
+            w: item.w,
+            h: item.h
+          }))
+        }));
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ activeLayout: active, layouts: summary }, null, 2)
+          }]
+        };
+      }
+      case "agentistics_create_layout": {
+        const layoutName = args.name;
+        const prefs = await getPrefs();
+        const layouts = { ...prefs.layouts ?? {} };
+        if (layouts[layoutName]) {
+          return { content: [{ type: "text", text: `Layout "${layoutName}" already exists.` }] };
+        }
+        layouts[layoutName] = [];
+        await putPrefs({ layouts, activeLayout: prefs.activeLayout });
+        return { content: [{ type: "text", text: `Layout "${layoutName}" created.` }] };
+      }
+      case "agentistics_add_component": {
+        const a = args;
+        const prefs = await getPrefs();
+        const layouts = { ...prefs.layouts ?? {} };
+        const targetName = a.layoutName ?? prefs.activeLayout ?? "";
+        if (!targetName)
+          throw new Error("No active layout. Create one first with agentistics_create_layout.");
+        if (!layouts[targetName])
+          throw new Error(`Layout "${targetName}" not found.`);
+        const catalogItem = CATALOG.find((c) => c.id === a.componentId);
+        if (!catalogItem)
+          throw new Error(`Unknown componentId "${a.componentId}". Use agentistics_component_catalog to list valid IDs.`);
+        const current = layouts[targetName];
+        const pos = a.x !== undefined && a.y !== undefined ? { x: a.x, y: a.y } : autoPosition(current, a.w ?? catalogItem.defaultW);
+        const newItem = {
+          i: nextId(current),
+          componentId: a.componentId,
+          x: pos.x,
+          y: pos.y,
+          w: a.w ?? catalogItem.defaultW,
+          h: a.h ?? catalogItem.defaultH,
+          minW: catalogItem.minW,
+          minH: catalogItem.minH
+        };
+        layouts[targetName] = [...current, newItem];
+        await putPrefs({ layouts });
+        return {
+          content: [{
+            type: "text",
+            text: `Added "${a.componentId}" to layout "${targetName}" at (${newItem.x}, ${newItem.y}), size ${newItem.w}×${newItem.h}. Instance ID: ${newItem.i}`
+          }]
+        };
+      }
+      case "agentistics_remove_component": {
+        const a = args;
+        const prefs = await getPrefs();
+        const layouts = { ...prefs.layouts ?? {} };
+        const targetName = a.layoutName ?? prefs.activeLayout ?? "";
+        if (!targetName || !layouts[targetName])
+          throw new Error(`Layout "${targetName}" not found.`);
+        const before = layouts[targetName].length;
+        layouts[targetName] = layouts[targetName].filter((item) => item.i !== a.itemId);
+        if (layouts[targetName].length === before) {
+          return { content: [{ type: "text", text: `Item "${a.itemId}" not found in layout "${targetName}".` }] };
+        }
+        await putPrefs({ layouts });
+        return { content: [{ type: "text", text: `Removed item "${a.itemId}" from layout "${targetName}".` }] };
+      }
+      case "agentistics_set_active_layout": {
+        const layoutName = args.name;
+        const prefs = await getPrefs();
+        const layouts = prefs.layouts ?? {};
+        if (!layouts[layoutName]) {
+          throw new Error(`Layout "${layoutName}" not found. Available: ${Object.keys(layouts).join(", ")}`);
+        }
+        await putPrefs({ activeLayout: layoutName });
+        return { content: [{ type: "text", text: `Active layout set to "${layoutName}".` }] };
+      }
+      case "agentistics_delete_layout": {
+        const layoutName = args.name;
+        const prefs = await getPrefs();
+        const layouts = { ...prefs.layouts ?? {} };
+        if (!layouts[layoutName])
+          throw new Error(`Layout "${layoutName}" not found.`);
+        if (Object.keys(layouts).length === 1)
+          throw new Error("Cannot delete the last remaining layout.");
+        delete layouts[layoutName];
+        let active = prefs.activeLayout ?? "";
+        if (active === layoutName)
+          active = Object.keys(layouts)[0] ?? "";
+        await putPrefs({ layouts, activeLayout: active });
+        return {
+          content: [{
+            type: "text",
+            text: `Deleted layout "${layoutName}". Active layout is now "${active}".`
+          }]
+        };
+      }
+      case "agentistics_export_pdf": {
+        const a = args;
+        const range = a?.range ?? "all";
+        const uiBase = API.replace(/:\d+$/, ":47292");
+        const params = new URLSearchParams({ export: "pdf" });
+        if (range !== "all")
+          params.set("range", range);
+        const url = `${uiBase}/?${params.toString()}`;
+        const rangeLabel = range === "all" ? "all-time" : `last ${range}`;
+        return {
+          content: [{
+            type: "text",
+            text: `[⬇ Download PDF — ${rangeLabel}](pdf:${url})`
+          }]
+        };
+      }
+      case "agentistics_build_layout": {
+        const a = args;
+        const layoutName = a.name;
+        const componentIds = a.componentIds;
+        const activate = a.activate !== false;
+        for (const id of componentIds) {
+          if (!CATALOG.find((c) => c.id === id)) {
+            throw new Error(`Unknown componentId "${id}". Use agentistics_component_catalog to list valid IDs.`);
+          }
+        }
+        const prefs = await getPrefs();
+        const layouts = { ...prefs.layouts ?? {} };
+        const items = [];
+        for (const componentId of componentIds) {
+          const cat = CATALOG.find((c) => c.id === componentId);
+          const pos = autoPosition(items, cat.defaultW);
+          items.push({
+            i: nextId(items),
+            componentId,
+            x: pos.x,
+            y: pos.y,
+            w: cat.defaultW,
+            h: cat.defaultH,
+            minW: cat.minW,
+            minH: cat.minH
+          });
+        }
+        fillGaps(items);
+        layouts[layoutName] = items;
+        const patch = { layouts };
+        if (activate)
+          patch.activeLayout = layoutName;
+        await putPrefs(patch);
+        return {
+          content: [{
+            type: "text",
+            text: `Layout "${layoutName}" built with ${items.length} components: ${componentIds.join(", ")}${activate ? ". Now active." : "."}`
+          }]
+        };
+      }
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true
+    };
+  }
+});
+var transport = new StdioServerTransport;
+await server.connect(transport);

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@agentistics/mcp",
+  "version": "1.3.3",
+  "description": "Agentistics MCP server — Claude Code analytics for Claude Desktop and Claude Code",
+  "type": "module",
+  "main": "./dist/agentistics-mcp.js",
+  "bin": {
+    "agentistics-mcp": "dist/agentistics-mcp.js"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build agentistics-mcp.ts --outfile dist/agentistics-mcp.js --external @modelcontextprotocol/sdk --target node && chmod +x dist/agentistics-mcp.js",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "claude-code",
+    "analytics",
+    "agentistics"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blpsoares/agentistics.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/blpsoares/agentistics"
+}