@arcbridge/mcp-server 0.1.1 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # @arcbridge/mcp-server
 
-MCP server for ArcBridge — exposes 26 architecture tools to AI coding agents via the [Model Context Protocol](https://modelcontextprotocol.io).
+MCP server for ArcBridge — exposes 29 architecture tools to AI coding agents via the [Model Context Protocol](https://modelcontextprotocol.io).
 
 ## Install
 
@@ -88,6 +88,14 @@ Restart your AI agent (Claude Code, etc.) and approve the MCP server when prompt
 | `arcbridge_verify_scenarios` | Run linked tests for quality scenarios |
 | `arcbridge_run_role_check` | Run a role's quality checks against code |
 
+### Metrics
+
+| Tool | Description |
+|------|-------------|
+| `arcbridge_record_activity` | Record agent activity — model, tokens, cost, duration, quality snapshot |
+| `arcbridge_get_metrics` | Query and aggregate activity by model, task, phase, tool, or day |
+| `arcbridge_export_metrics` | Export metrics to JSON, CSV, or Markdown for git commits |
+
 ## How It Works
 
 The server communicates over stdio using the MCP protocol. Each tool call receives a `target_dir` parameter pointing to an ArcBridge-initialized project. The server manages a SQLite database (`.arcbridge/index.db`) that caches architecture docs, indexed symbols, and planning state.

package/dist/index.js

@@ -149,7 +149,7 @@ import { refreshFromDocs } from "@arcbridge/core";
 // src/helpers.ts
 import { join as join2 } from "path";
 import { existsSync as existsSync2 } from "fs";
-import { openDatabase } from "@arcbridge/core";
+import { openDatabase, migrate } from "@arcbridge/core";
 function ensureDb(ctx, targetDir) {
   if (ctx.db) return ctx.db;
   const dbPath = join2(targetDir, ".arcbridge", "index.db");
@@ -157,6 +157,7 @@ function ensureDb(ctx, targetDir) {
     return null;
   }
   ctx.db = openDatabase(dbPath);
+  migrate(ctx.db);
   ctx.projectRoot = targetDir;
   return ctx.db;
 }
@@ -762,6 +763,42 @@ function registerGetCurrentTasks(server, ctx) {
 // src/tools/update-task.ts
 import { z as z8 } from "zod";
 import { syncTaskToYaml } from "@arcbridge/core";
+
+// src/auto-record.ts
+import { loadConfig, insertActivity } from "@arcbridge/core";
+var configCache = /* @__PURE__ */ new Map();
+var CACHE_TTL_MS = 3e4;
+function isAutoRecordEnabled(projectRoot) {
+  const cached = configCache.get(projectRoot);
+  if (cached && Date.now() - cached.loadedAt < CACHE_TTL_MS) {
+    return cached.autoRecord;
+  }
+  const { config } = loadConfig(projectRoot);
+  const autoRecord2 = config?.metrics?.auto_record ?? false;
+  configCache.set(projectRoot, { autoRecord: autoRecord2, loadedAt: Date.now() });
+  return autoRecord2;
+}
+function autoRecord(db, projectRoot, params) {
+  try {
+    if (!isAutoRecordEnabled(projectRoot)) return;
+    insertActivity(db, {
+      toolName: params.toolName,
+      action: params.action,
+      taskId: params.taskId,
+      phaseId: params.phaseId,
+      durationMs: params.durationMs,
+      driftCount: params.driftCount,
+      driftErrors: params.driftErrors,
+      testPassCount: params.testPassCount,
+      testFailCount: params.testFailCount,
+      lintClean: params.lintClean,
+      typecheckClean: params.typecheckClean
+    });
+  } catch {
+  }
+}
+
+// src/tools/update-task.ts
 function registerUpdateTask(server, ctx) {
   server.tool(
     "arcbridge_update_task",
@@ -773,6 +810,7 @@ function registerUpdateTask(server, ctx) {
       notes: z8.string().optional().describe("Optional notes about the status change")
     },
     async (params) => {
+      const start = Date.now();
       const db = ensureDb(ctx, params.target_dir);
       if (!db) return notInitialized();
       const task = db.prepare("SELECT id, title, status, phase_id FROM tasks WHERE id = ?").get(params.task_id);
@@ -828,6 +866,13 @@ function registerUpdateTask(server, ctx) {
           );
         }
       }
+      autoRecord(db, params.target_dir, {
+        toolName: "arcbridge_update_task",
+        action: `${task.id}: ${oldStatus} \u2192 ${params.status}`,
+        taskId: params.task_id,
+        phaseId: task.phase_id,
+        durationMs: Date.now() - start
+      });
       return {
         content: [{ type: "text", text: lines.join("\n") }]
       };
@@ -1018,7 +1063,7 @@ import { indexProject as indexProject2, refreshFromDocs as refreshFromDocs4 } fr
 function registerReindex(server, ctx) {
   server.tool(
     "arcbridge_reindex",
-    "Re-index code symbols in the project. Supports TypeScript and C# (.NET). Incrementally processes only changed files.",
+    "Re-index the project: refreshes architecture docs from arc42/YAML files, then reindexes code symbols (TypeScript & C#/.NET). This is the first step of the sync pipeline \u2014 use it to pick up manual doc edits and code changes.",
     {
       target_dir: z11.string().describe("Absolute path to the project directory"),
       tsconfig_path: z11.string().optional().describe("Override tsconfig.json path (default: auto-detect). Only used for TypeScript projects."),
@@ -1026,6 +1071,7 @@ function registerReindex(server, ctx) {
       language: z11.enum(["typescript", "csharp", "auto"]).optional().describe("Project language. 'auto' detects from project files (default: 'auto')")
     },
     async (params) => {
+      const start = Date.now();
       const db = ensureDb(ctx, params.target_dir);
       if (!db) return notInitialized();
       try {
@@ -1049,6 +1095,11 @@ function registerReindex(server, ctx) {
           `- **Routes analyzed:** ${result.routesAnalyzed}`,
           `- **Duration:** ${result.durationMs}ms`
         ];
+        autoRecord(db, params.target_dir, {
+          toolName: "arcbridge_reindex",
+          action: `${result.symbolsIndexed} symbols, ${result.filesProcessed} files`,
+          durationMs: Date.now() - start
+        });
         return textResult(lines.join("\n"));
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -1760,6 +1811,7 @@ function registerCheckDrift(server, ctx) {
       persist: z18.boolean().default(true).describe("Write findings to drift_log table (default: true)")
     },
     async (params) => {
+      const start = Date.now();
       const db = ensureDb(ctx, params.target_dir);
       if (!db) return notInitialized();
       const entries = detectDrift(db);
@@ -1815,6 +1867,13 @@ function registerCheckDrift(server, ctx) {
           ""
         );
       }
+      autoRecord(db, params.target_dir, {
+        toolName: "arcbridge_check_drift",
+        action: `${entries.length} issues (${errors} errors)`,
+        driftCount: entries.length,
+        driftErrors: errors,
+        durationMs: Date.now() - start
+      });
       return textResult(lines.join("\n"));
     }
   );
@@ -2652,7 +2711,7 @@ import {
   inferTaskStatuses,
   applyInferences,
   verifyScenarios,
-  loadConfig,
+  loadConfig as loadConfig2,
   refreshFromDocs as refreshFromDocs5,
   syncPhaseToYaml
 } from "@arcbridge/core";
@@ -2668,6 +2727,7 @@ function registerCompletePhase(server, ctx) {
       run_tests: z23.boolean().default(false).describe("Run linked tests for quality scenarios before checking the quality gate")
     },
     async (params) => {
+      const start = Date.now();
       const db = ensureDb(ctx, params.target_dir);
       if (!db) return notInitialized();
       refreshFromDocs5(db, params.target_dir);
@@ -2715,7 +2775,7 @@ function registerCompletePhase(server, ctx) {
         const projectRoot = ctx.projectRoot ?? params.target_dir;
         let testCommand = "npx vitest run";
         let timeoutMs = 6e4;
-        const configResult = loadConfig(params.target_dir);
+        const configResult = loadConfig2(params.target_dir);
         if (configResult.config) {
           testCommand = configResult.config.testing.test_command;
           timeoutMs = configResult.config.testing.timeout_ms;
@@ -2868,6 +2928,12 @@ function registerCompletePhase(server, ctx) {
           "Resolve the issues above before completing this phase."
         );
       }
+      autoRecord(db, params.target_dir, {
+        toolName: "arcbridge_complete_phase",
+        action: `${phase.name}: ${allPass ? "PASSED" : "BLOCKED"}`,
+        phaseId: params.phase_id,
+        durationMs: Date.now() - start
+      });
       return textResult(lines.join("\n"));
     }
   );
@@ -3188,7 +3254,7 @@ function getRoleDefinition(roleId) {
 
 // src/tools/verify-scenarios.ts
 import { z as z25 } from "zod";
-import { verifyScenarios as verifyScenarios2, loadConfig as loadConfig2 } from "@arcbridge/core";
+import { verifyScenarios as verifyScenarios2, loadConfig as loadConfig3 } from "@arcbridge/core";
 function registerVerifyScenarios(server, ctx) {
   server.tool(
     "arcbridge_verify_scenarios",
@@ -3207,7 +3273,7 @@ function registerVerifyScenarios(server, ctx) {
       if (!db) return notInitialized();
       let testCommand = "npx vitest run";
       let timeoutMs = 6e4;
-      const configResult = loadConfig2(params.target_dir);
+      const configResult = loadConfig3(params.target_dir);
       if (configResult.config) {
         testCommand = configResult.config.testing.test_command;
         timeoutMs = configResult.config.testing.timeout_ms;
@@ -3702,6 +3768,232 @@ function runCustomRoleCheck(db, lines, roleDef) {
   appendDriftSection(db, lines);
 }
 
+// src/tools/record-activity.ts
+import { z as z27 } from "zod";
+import { insertActivity as insertActivity2, getSessionTotals } from "@arcbridge/core";
+function registerRecordActivity(server, ctx) {
+  server.tool(
+    "arcbridge_record_activity",
+    "Record agent activity \u2014 model, tokens, cost, duration, and optional quality snapshot. Use this to track what work was done and measure agent performance.",
+    {
+      target_dir: z27.string().describe("Absolute path to the project directory"),
+      tool_name: z27.string().describe("Name of the tool or action performed (e.g., 'arcbridge_update_task', 'code_edit')"),
+      action: z27.string().optional().describe("Human-readable label (e.g., 'implement login form')"),
+      model: z27.string().optional().describe("Model identifier (e.g., 'claude-sonnet-4-20250514')"),
+      agent_role: z27.string().optional().describe("Active ArcBridge role (e.g., 'implementer')"),
+      task_id: z27.string().optional().describe("Associated task ID"),
+      phase_id: z27.string().optional().describe("Associated phase ID"),
+      input_tokens: z27.number().int().nonnegative().optional().describe("Input/prompt tokens"),
+      output_tokens: z27.number().int().nonnegative().optional().describe("Output/completion tokens"),
+      total_tokens: z27.number().int().nonnegative().optional().describe("Total tokens (auto-computed if input+output given)"),
+      cost_usd: z27.number().nonnegative().optional().describe("Estimated cost in USD"),
+      duration_ms: z27.number().int().nonnegative().optional().describe("Wall-clock duration in ms"),
+      drift_count: z27.number().int().nonnegative().optional().describe("Current drift count"),
+      drift_errors: z27.number().int().nonnegative().optional().describe("Current drift errors"),
+      test_pass_count: z27.number().int().nonnegative().optional().describe("Passing tests"),
+      test_fail_count: z27.number().int().nonnegative().optional().describe("Failing tests"),
+      lint_clean: z27.boolean().optional().describe("Whether lint passes cleanly"),
+      typecheck_clean: z27.boolean().optional().describe("Whether typecheck passes cleanly"),
+      notes: z27.string().optional().describe("Free-form notes"),
+      metadata: z27.record(z27.unknown()).optional().describe("Additional key-value metadata")
+    },
+    async (params) => {
+      const db = ensureDb(ctx, params.target_dir);
+      if (!db) return notInitialized();
+      const rowId = insertActivity2(db, {
+        toolName: params.tool_name,
+        action: params.action,
+        model: params.model,
+        agentRole: params.agent_role,
+        taskId: params.task_id,
+        phaseId: params.phase_id,
+        inputTokens: params.input_tokens,
+        outputTokens: params.output_tokens,
+        totalTokens: params.total_tokens,
+        costUsd: params.cost_usd,
+        durationMs: params.duration_ms,
+        driftCount: params.drift_count,
+        driftErrors: params.drift_errors,
+        testPassCount: params.test_pass_count,
+        testFailCount: params.test_fail_count,
+        lintClean: params.lint_clean,
+        typecheckClean: params.typecheck_clean,
+        notes: params.notes,
+        metadata: params.metadata
+      });
+      const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+      const totals = getSessionTotals(db, today, params.model);
+      const totalTokens = params.total_tokens ?? (params.input_tokens != null && params.output_tokens != null ? params.input_tokens + params.output_tokens : null);
+      const lines = [
+        `# Activity Recorded (#${rowId})`,
+        "",
+        `- **Tool:** ${params.tool_name}`
+      ];
+      if (params.action) lines.push(`- **Action:** ${params.action}`);
+      if (params.model) lines.push(`- **Model:** ${params.model}`);
+      if (totalTokens != null) {
+        const detail = params.input_tokens != null && params.output_tokens != null ? `${params.input_tokens.toLocaleString()} in / ${params.output_tokens.toLocaleString()} out (${totalTokens.toLocaleString()} total)` : `${totalTokens.toLocaleString()} total`;
+        lines.push(`- **Tokens:** ${detail}`);
+      }
+      if (params.cost_usd != null) lines.push(`- **Cost:** $${params.cost_usd.toFixed(4)}`);
+      if (params.duration_ms != null) lines.push(`- **Duration:** ${params.duration_ms.toLocaleString()}ms`);
+      lines.push(
+        "",
+        `## Session Totals (today${params.model ? `, ${params.model}` : ""})`,
+        `- **Total cost:** $${totals.totalCost.toFixed(4)}`,
+        `- **Total tokens:** ${totals.totalTokens.toLocaleString()}`,
+        `- **Activities recorded:** ${totals.activityCount}`
+      );
+      return textResult(lines.join("\n"));
+    }
+  );
+}
+
+// src/tools/get-metrics.ts
+import { z as z28 } from "zod";
+import { queryMetrics } from "@arcbridge/core";
+function registerGetMetrics(server, ctx) {
+  server.tool(
+    "arcbridge_get_metrics",
+    "Query agent activity metrics \u2014 filter by model, task, phase, or time range. Group by model/task/phase/tool/day for aggregated views.",
+    {
+      target_dir: z28.string().describe("Absolute path to the project directory"),
+      task_id: z28.string().optional().describe("Filter by task ID"),
+      phase_id: z28.string().optional().describe("Filter by phase ID"),
+      model: z28.string().optional().describe("Filter by model name"),
+      agent_role: z28.string().optional().describe("Filter by agent role"),
+      tool_name: z28.string().optional().describe("Filter by tool name"),
+      since: z28.string().optional().describe("ISO 8601 timestamp \u2014 activity after this time"),
+      until: z28.string().optional().describe("ISO 8601 timestamp \u2014 activity before this time"),
+      group_by: z28.enum(["model", "task", "phase", "tool", "day", "none"]).default("none").describe("Group results for aggregation"),
+      limit: z28.number().int().min(1).max(500).default(50).describe("Max rows in detail view (group_by=none)")
+    },
+    async (params) => {
+      const db = ensureDb(ctx, params.target_dir);
+      if (!db) return notInitialized();
+      const result = queryMetrics(db, {
+        taskId: params.task_id,
+        phaseId: params.phase_id,
+        model: params.model,
+        agentRole: params.agent_role,
+        toolName: params.tool_name,
+        since: params.since,
+        until: params.until,
+        groupBy: params.group_by,
+        limit: params.limit
+      });
+      if (result.totals.activityCount === 0) {
+        return textResult("No agent activity recorded yet. Use `arcbridge_record_activity` to log agent work.");
+      }
+      const lines = [];
+      if (result.grouped) {
+        const rows = result.rows;
+        lines.push(
+          `# Agent Metrics (grouped by ${params.group_by})`,
+          "",
+          `| ${capitalize(params.group_by)} | Activities | Total Tokens | Avg Tokens | Total Cost | Avg Duration |`,
+          `|${"-".repeat(20)}|-----------|-------------|-----------|-----------|-------------|`
+        );
+        for (const r of rows) {
+          lines.push(
+            `| ${mdCell(r.groupKey)} | ${r.activityCount} | ${r.sumTokens?.toLocaleString() ?? "-"} | ${r.avgTokens?.toLocaleString() ?? "-"} | ${r.sumCost != null ? "$" + r.sumCost.toFixed(4) : "-"} | ${r.avgDuration != null ? Math.round(r.avgDuration) + "ms" : "-"} |`
+          );
+        }
+      } else {
+        const rows = result.rows;
+        lines.push(
+          "# Agent Activity (recent)",
+          "",
+          "| Time | Tool | Action | Model | Tokens | Cost | Duration |",
+          "|------|------|--------|-------|--------|------|----------|"
+        );
+        for (const r of rows) {
+          lines.push(
+            `| ${r.recorded_at.slice(0, 19)} | ${mdCell(r.tool_name)} | ${mdCell(r.action)} | ${mdCell(r.model)} | ${r.total_tokens?.toLocaleString() ?? ""} | ${r.cost_usd != null ? "$" + r.cost_usd.toFixed(4) : ""} | ${r.duration_ms != null ? r.duration_ms.toLocaleString() + "ms" : ""} |`
+          );
+        }
+      }
+      const q = result.qualitySnapshot;
+      if (q.capturedAt) {
+        lines.push(
+          "",
+          "## Latest Quality Snapshot",
+          ""
+        );
+        if (q.driftCount != null) lines.push(`- **Drift:** ${q.driftCount} issues (${q.driftErrors ?? 0} errors)`);
+        if (q.testPassCount != null) lines.push(`- **Tests:** ${q.testPassCount} pass / ${q.testFailCount ?? 0} fail`);
+        if (q.lintClean != null) lines.push(`- **Lint:** ${q.lintClean ? "clean" : "errors"}`);
+        if (q.typecheckClean != null) lines.push(`- **Typecheck:** ${q.typecheckClean ? "clean" : "errors"}`);
+      }
+      lines.push(
+        "",
+        "## Totals",
+        "",
+        `- **Activities:** ${result.totals.activityCount}`,
+        `- **Total cost:** $${result.totals.totalCost.toFixed(4)}`,
+        `- **Total tokens:** ${result.totals.totalTokens.toLocaleString()}`
+      );
+      if (result.timeSpan) {
+        lines.push(`- **Time span:** ${result.timeSpan.first.slice(0, 10)} \u2192 ${result.timeSpan.last.slice(0, 10)}`);
+      }
+      return textResult(lines.join("\n"));
+    }
+  );
+}
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function mdCell(val) {
+  if (val == null) return "";
+  return val.replace(/\|/g, "\\|").replace(/\r?\n|\r/g, " ");
+}
+
+// src/tools/export-metrics.ts
+import { z as z29 } from "zod";
+import { exportMetrics } from "@arcbridge/core";
+function registerExportMetrics(server, ctx) {
+  server.tool(
+    "arcbridge_export_metrics",
+    "Export agent activity metrics to a file (JSON, CSV, or Markdown) in .arcbridge/metrics/ for git commits or reporting.",
+    {
+      target_dir: z29.string().describe("Absolute path to the project directory"),
+      format: z29.enum(["json", "csv", "markdown"]).default("json").describe("Export format"),
+      task_id: z29.string().optional().describe("Filter by task ID"),
+      phase_id: z29.string().optional().describe("Filter by phase ID"),
+      model: z29.string().optional().describe("Filter by model name"),
+      agent_role: z29.string().optional().describe("Filter by agent role"),
+      tool_name: z29.string().optional().describe("Filter by tool name"),
+      since: z29.string().optional().describe("ISO 8601 \u2014 activity after this time"),
+      until: z29.string().optional().describe("ISO 8601 \u2014 activity before this time"),
+      max_rows: z29.number().int().min(1).default(1e5).describe("Maximum rows to export (default: 100,000)")
+    },
+    async (params) => {
+      const db = ensureDb(ctx, params.target_dir);
+      if (!db) return notInitialized();
+      const filePath = exportMetrics(
+        db,
+        params.target_dir,
+        params.format,
+        {
+          taskId: params.task_id,
+          phaseId: params.phase_id,
+          model: params.model,
+          agentRole: params.agent_role,
+          toolName: params.tool_name,
+          since: params.since,
+          until: params.until
+        },
+        params.max_rows
+      );
+      return textResult(
+        `Metrics exported to: ${filePath}
+
+You can commit this file to preserve the activity record in git.`
+      );
+    }
+  );
+}
+
 // src/server.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -3737,6 +4029,9 @@ function createArcBridgeServer() {
   registerActivateRole(server, ctx);
   registerVerifyScenarios(server, ctx);
   registerRunRoleCheck(server, ctx);
+  registerRecordActivity(server, ctx);
+  registerGetMetrics(server, ctx);
+  registerExportMetrics(server, ctx);
   return server;
 }