@systemdox/mcp-server 0.1.18 → 0.1.20

package/README.md

@@ -1,8 +1,38 @@
 # @systemdox/mcp-server
 
-MCP server that exposes your SystemDox context — checks, specs, docs, tech
-stack, project rules, and prompt templates — to AI coding tools (Claude Code,
-Cursor, and any MCP-compatible client).
+> Your architecture, in your agents' context window.
+
+[SystemDox](https://www.systemdox.com) is the document plane for AI-assisted
+engineering: your standards — specs, architecture decision records, checks,
+project rules, docs — versioned in git and delivered into your coding agents'
+context at write time. This MCP server is how Claude Code, Cursor, and any
+MCP-compatible tool read that context — and write decisions back.
+
+**Why teams use it**
+
+- **Write-time context** — `get_context` ranks the checks, specs, and docs
+  relevant to the task at hand and fetches their bodies within a token budget,
+  so the agent starts from your architecture instead of guessing it.
+- **Both directions** — agents call `report_decision` and `update_spec` as they
+  work, so decision records exist as a by-product of shipping, not as
+  archaeology afterwards.
+- **One source for every agent** — no per-developer rules-file forks; every
+  session in every repository starts from the same governed, versioned context.
+- **Scoped by key** — the API key is the boundary: a department-scoped key sees
+  only its own space's checks, specs, and docs.
+
+**Get started in about a minute**
+
+1. [Create a SystemDox workspace](https://app.systemdox.com/signup) — the free
+   tier covers one repository, permanently.
+2. Connect a GitHub repository and generate an API key (workspace settings).
+3. Add the server to your tool — hosted (Option A) or local (Option B) below.
+
+Docs: [MCP setup guide](https://www.systemdox.com/guides/mcp-setup) ·
+[Documentation standard](https://www.systemdox.com/guides/documentation-standard) ·
+[Why write-time context](https://www.systemdox.com/blog/architecture-only-exists-at-write-time)
+
+---
 
 There are two ways to run it. Both authenticate with a SystemDox API key
 (generate one on your SystemDox settings page) and act strictly as the caller —

package/dist/cli.js

@@ -1979,7 +1979,7 @@ var init_server = __esm({
     init_create_project_rule();
     init_get_prompt_templates();
     init_create_prompt_template();
-    SERVER_VERSION = true ? "0.1.18" : "0.0.0-dev";
+    SERVER_VERSION = true ? "0.1.20" : "0.0.0-dev";
   }
 });
 

package/dist/http.js

@@ -117,6 +117,41 @@ var SystemDoxApiClient = class {
   }
 };
 
+// src/lib/metrics.ts
+var NAMESPACE = "SystemDox/Mcp";
+var METRIC_NAME = "McpToolCall";
+function buildMcpToolCallMetric(tenant, tool, timestamp = Date.now()) {
+  return {
+    _aws: {
+      Timestamp: timestamp,
+      CloudWatchMetrics: [
+        {
+          Namespace: NAMESPACE,
+          Dimensions: [["tenant"]],
+          Metrics: [{ Name: METRIC_NAME, Unit: "Count" }]
+        }
+      ]
+    },
+    tenant,
+    tool,
+    [METRIC_NAME]: 1
+  };
+}
+function emitMcpToolCalls(tenant, rawBody, log = console.log) {
+  try {
+    const parsed = JSON.parse(rawBody);
+    const messages = Array.isArray(parsed) ? parsed : [parsed];
+    for (const message of messages) {
+      if (typeof message === "object" && message !== null && message.method === "tools/call") {
+        const params = message.params;
+        const tool = typeof params?.name === "string" ? params.name : "unknown";
+        log(JSON.stringify(buildMcpToolCallMetric(tenant || "unknown", tool)));
+      }
+    }
+  } catch {
+  }
+}
+
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
@@ -1790,7 +1825,7 @@ function registerCreatePromptTemplate(server, apiClient) {
 }
 
 // src/server.ts
-var SERVER_VERSION = true ? "0.1.18" : "0.0.0-dev";
+var SERVER_VERSION = true ? "0.1.20" : "0.0.0-dev";
 function createServer(apiClient) {
   const server = new McpServer({
     name: "systemdox-mcp-server",
@@ -1836,9 +1871,9 @@ function jsonError(statusCode, message) {
 async function handler(event) {
   const headers = lowercaseHeaders(event.headers);
   const host = (headers["host"] ?? "").toLowerCase();
+  const keyTenant = event.requestContext?.authorizer?.tenant_slug ?? "";
   if (host.endsWith(MCP_HOST_SUFFIX)) {
     const hostTenant = host.slice(0, -MCP_HOST_SUFFIX.length);
-    const keyTenant = event.requestContext?.authorizer?.tenant_slug ?? "";
     if (!hostTenant || hostTenant.includes(".") || hostTenant !== keyTenant) {
       return jsonError(403, "API key does not belong to this tenant");
     }
@@ -1860,6 +1895,7 @@ async function handler(event) {
     return jsonError(401, "Missing bearer API key");
   }
   const rawBody = event.isBase64Encoded ? Buffer.from(event.body ?? "", "base64").toString("utf8") : event.body ?? "";
+  emitMcpToolCalls(keyTenant, rawBody);
   const apiClient = new SystemDoxApiClient({
     apiKey,
     apiUrl: process.env.SYSTEMDOX_API_URL ?? "https://api.puglieseweb.com/systemdox",

package/dist/index.js

@@ -1806,7 +1806,7 @@ function registerCreatePromptTemplate(server2, apiClient2) {
 }
 
 // src/server.ts
-var SERVER_VERSION = true ? "0.1.18" : "0.0.0-dev";
+var SERVER_VERSION = true ? "0.1.20" : "0.0.0-dev";
 function createServer(apiClient2) {
   const server2 = new McpServer({
     name: "systemdox-mcp-server",

package/dist/lib/metrics.d.ts

@@ -0,0 +1,41 @@
+/**
+ * CloudWatch EMF telemetry for hosted MCP tool calls (issue #978).
+ *
+ * One metric answers two standing questions:
+ *  - activation: "which tenants had ≥1 agent MCP call this week?" —
+ *    `McpToolCall` dimensioned by `tenant`, joined against the repo
+ *    `connectedAt` cohort in DynamoDB;
+ *  - the deprecated-alias removal gate (README "Deprecated tool names"):
+ *    per-tool-name counts come from the `tool` property via Logs Insights,
+ *    kept out of the dimensions so metric cardinality stays = tenants.
+ *
+ * EMF is a formatted console.log — no SDK dependency, no latency, and the
+ * Lambda's existing log group is the transport. Telemetry must never break
+ * the request path: emitters swallow their own failures.
+ */
+declare const METRIC_NAME = "McpToolCall";
+export interface McpToolCallMetric {
+    _aws: {
+        Timestamp: number;
+        CloudWatchMetrics: {
+            Namespace: string;
+            Dimensions: string[][];
+            Metrics: {
+                Name: string;
+                Unit: string;
+            }[];
+        }[];
+    };
+    tenant: string;
+    tool: string;
+    [METRIC_NAME]: number;
+}
+/** Build the EMF envelope for a single tool call. Pure — unit-testable. */
+export declare function buildMcpToolCallMetric(tenant: string, tool: string, timestamp?: number): McpToolCallMetric;
+/**
+ * Parse a JSON-RPC request body (single message or batch) and emit one EMF
+ * line per `tools/call`. Anything unparseable or non-tool (initialize,
+ * tools/list, notifications) is ignored. Never throws.
+ */
+export declare function emitMcpToolCalls(tenant: string, rawBody: string, log?: (line: string) => void): void;
+export {};

package/dist/lib/metrics.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+// src/lib/metrics.ts
+var NAMESPACE = "SystemDox/Mcp";
+var METRIC_NAME = "McpToolCall";
+function buildMcpToolCallMetric(tenant, tool, timestamp = Date.now()) {
+  return {
+    _aws: {
+      Timestamp: timestamp,
+      CloudWatchMetrics: [
+        {
+          Namespace: NAMESPACE,
+          Dimensions: [["tenant"]],
+          Metrics: [{ Name: METRIC_NAME, Unit: "Count" }]
+        }
+      ]
+    },
+    tenant,
+    tool,
+    [METRIC_NAME]: 1
+  };
+}
+function emitMcpToolCalls(tenant, rawBody, log = console.log) {
+  try {
+    const parsed = JSON.parse(rawBody);
+    const messages = Array.isArray(parsed) ? parsed : [parsed];
+    for (const message of messages) {
+      if (typeof message === "object" && message !== null && message.method === "tools/call") {
+        const params = message.params;
+        const tool = typeof params?.name === "string" ? params.name : "unknown";
+        log(JSON.stringify(buildMcpToolCallMetric(tenant || "unknown", tool)));
+      }
+    }
+  } catch {
+  }
+}
+export {
+  buildMcpToolCallMetric,
+  emitMcpToolCalls
+};

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@systemdox/mcp-server",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "type": "module",
-  "description": "MCP server that exposes SystemDox checks, specs, docs, and tech stack to AI coding tools",
+  "description": "Give AI coding agents your architecture context over MCP — checks, specs, ADRs, project rules, and docs from SystemDox, delivered at write time",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
@@ -44,11 +44,18 @@
   "keywords": [
     "mcp",
     "model-context-protocol",
+    "mcp-server",
     "systemdox",
     "ai",
     "claude",
+    "claude-code",
+    "cursor",
+    "context",
+    "architecture",
+    "adr",
     "checks",
-    "specs"
+    "specs",
+    "governance"
   ],
   "author": "Emanuele Pugliese",
   "license": "ISC",