@synapsor/client 0.1.5 → 0.1.6

package/README.md

@@ -181,6 +181,26 @@ The worker validates Synapsor-provided mapping metadata, only writes allowlisted
 columns, adds tenant and primary-key guards, checks optional conflict columns,
 and reports `applied`, `conflict`, or `failed` back to Synapsor idempotently.
 
+## CLI MCP Risk Review
+
+The package installs a `synapsor` CLI. Use `synapsor mcp audit <target>` for a
+static MCP database risk review of exported tool manifests, remote `tools/list`
+endpoints, or stdio MCP servers.
+
+```bash
+synapsor mcp audit ./tools-manifest.json
+synapsor mcp audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN --json
+synapsor mcp audit 'stdio:node ./server.mjs' --timeout-ms 5000
+```
+
+The audit flags patterns such as generic `execute_sql` tools, model-controlled
+tenant/table/column inputs, model-callable approval or commit tools, missing
+proposal boundaries, missing structured output schemas, and missing idempotency
+or conflict-guard metadata. It never calls business tools during the audit.
+
+This is a static MCP database risk review, not proof that an MCP server is
+secure. MCP annotations are treated as descriptive hints, not enforcement.
+
 ## API Surface
 
 - `execute(sql)` and `query(sql)`

package/bin/synapsor.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
+import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
@@ -11,6 +12,7 @@ import { stdin as input, stdout as output } from "node:process";
 const require = createRequire(import.meta.url);
 const { version: PACKAGE_VERSION } = require("../package.json");
 const DEFAULT_BASE_URL = "https://synapsor.ai";
+const MCP_AUDIT_DISCLAIMER = "This is a static MCP database risk review, not proof that an MCP server is secure.";
 const ERROR_HINTS = new Map([
   ["AUTH_REQUIRED", "Set SYNAPSOR_API_KEY or run `synapsor config set api-key`."],
   ["BILLING_REQUIRED", "Builder resources require active or trialing Builder billing."],
@@ -176,6 +178,13 @@ function boolFlag(args, name) {
   return args.includes(name);
 }
 
+function intFlag(args, name, fallback) {
+  const value = flagValue(args, name, "");
+  if (!value) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
 function resolveSecretRef(value) {
   const text = String(value || "").trim();
   if (text.startsWith("env:")) {
@@ -221,6 +230,250 @@ async function readStdinSecret() {
   return value.trim();
 }
 
+async function loadMcpAuditTarget(target, args) {
+  if (!target) throw new Error("MCP_AUDIT_TARGET_REQUIRED: usage `synapsor mcp audit <target>`");
+  const timeoutMs = intFlag(args, "--timeout-ms", 5000);
+  if (/^https?:\/\//i.test(target)) {
+    return { target, kind: "remote_tools_list", payload: await fetchRemoteMcpTools(target, args, timeoutMs) };
+  }
+  if (target.startsWith("stdio:")) {
+    const command = target.slice("stdio:".length).trim();
+    if (!command) throw new Error("MCP_STDIO_COMMAND_REQUIRED: usage `synapsor mcp audit 'stdio:node server.js'`");
+    return { target, kind: "stdio_tools_list", payload: await fetchStdioMcpTools(command, timeoutMs) };
+  }
+  const raw = await readFile(target, "utf8");
+  return { target, kind: "manifest", payload: JSON.parse(raw) };
+}
+
+async function fetchRemoteMcpTools(url, args, timeoutMs) {
+  const bearerEnv = flagValue(args, "--bearer-env", "SYNAPSOR_MCP_AUDIT_BEARER");
+  const bearer = bearerEnv ? process.env[bearerEnv] || "" : "";
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      signal: controller.signal,
+      headers: {
+        accept: "application/json",
+        "content-type": "application/json",
+        ...(bearer ? { authorization: `Bearer ${bearer}` } : {}),
+      },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }),
+    });
+    const text = await response.text();
+    const payload = text.trim() ? JSON.parse(text) : {};
+    if (!response.ok) throw new Error(`MCP_AUDIT_REMOTE_FAILED: HTTP ${response.status}`);
+    return payload;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function splitCommand(command) {
+  const parts = [];
+  const matcher = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let match;
+  while ((match = matcher.exec(command)) !== null) {
+    parts.push(match[1] ?? match[2] ?? match[3]);
+  }
+  return parts;
+}
+
+async function fetchStdioMcpTools(command, timeoutMs) {
+  const [bin, ...args] = splitCommand(command);
+  if (!bin) throw new Error("MCP_STDIO_COMMAND_REQUIRED: empty stdio command");
+  return await new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      reject(new Error(`MCP_AUDIT_TIMEOUT: tools/list did not complete within ${timeoutMs}ms`));
+    }, timeoutMs);
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+      const response = parseJsonRpcLine(stdout, 2);
+      if (response) {
+        clearTimeout(timer);
+        child.kill("SIGTERM");
+        resolve(response);
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on("close", () => {
+      const response = parseJsonRpcLine(stdout, 2);
+      if (response) return;
+      clearTimeout(timer);
+      reject(new Error(`MCP_AUDIT_STDIO_FAILED: tools/list response not found${stderr ? `: ${stderr.slice(0, 240)}` : ""}`));
+    });
+    child.stdin.write(`${JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2025-11-25",
+        capabilities: {},
+        clientInfo: { name: "synapsor-mcp-audit", version: PACKAGE_VERSION },
+      },
+    })}\n`);
+    child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} })}\n`);
+  });
+}
+
+function parseJsonRpcLine(text, id) {
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed.id === id) return parsed;
+    } catch {
+      // Ignore non-JSON logs from a local stdio server.
+    }
+  }
+  return null;
+}
+
+function extractMcpTools(payload) {
+  if (Array.isArray(payload)) return { tools: payload, source: "array_manifest" };
+  if (!payload || typeof payload !== "object") return { tools: [], source: "unknown" };
+  if (Array.isArray(payload.tools)) return { tools: payload.tools, source: "tool_manifest" };
+  if (Array.isArray(payload.result?.tools)) return { tools: payload.result.tools, source: "json_rpc_tools_list" };
+  if (Array.isArray(payload.tool_manifest?.tools)) return { tools: payload.tool_manifest.tools, source: "tool_manifest" };
+  if (payload.mcpServers && typeof payload.mcpServers === "object") {
+    return { tools: [], source: "mcp_client_config", serverCount: Object.keys(payload.mcpServers).length };
+  }
+  return { tools: [], source: "unknown" };
+}
+
+function propNames(schema) {
+  if (!schema || typeof schema !== "object") return [];
+  const properties = schema.properties && typeof schema.properties === "object" ? schema.properties : {};
+  return Object.keys(properties);
+}
+
+function schemaText(schema) {
+  try {
+    return JSON.stringify(schema || {}).toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+function hasAny(text, patterns) {
+  return patterns.some((pattern) => pattern.test(text));
+}
+
+function buildMcpAuditReport(targetInfo) {
+  const { tools, source, serverCount } = extractMcpTools(targetInfo.payload);
+  const findings = [];
+  const add = (severity, code, message, details = {}) => findings.push({ severity, code, message, ...details });
+  if (source === "mcp_client_config") {
+    add(
+      "LOW",
+      "MCP_CLIENT_CONFIG_ONLY",
+      "MCP client config found; export or query tools/list for schema-level database risk review.",
+      { evidence: `${serverCount || 0} configured MCP server(s)` },
+    );
+  }
+  if (!tools.length && source !== "mcp_client_config") {
+    add("MEDIUM", "NO_TOOLS_FOUND", "No MCP tools were found in the target manifest or tools/list response.");
+  }
+
+  for (const tool of tools) {
+    const name = String(tool.name || tool.id || tool.title || "unnamed_tool");
+    const description = String(tool.description || "");
+    const inputSchema = tool.inputSchema || tool.input_schema || tool.parameters || {};
+    const outputSchema = tool.outputSchema || tool.output_schema || tool.resultSchema || tool.result_schema || null;
+    const props = propNames(inputSchema);
+    const propsLower = props.map((prop) => prop.toLowerCase());
+    const text = `${name} ${description} ${schemaText(inputSchema)} ${schemaText(outputSchema)}`.toLowerCase();
+    const writeTool = hasAny(text, [
+      /\b(writes?|written|updates?|updated|deletes?|deleted|inserts?|inserted|upserts?|upserted|mutates?|mutated|refunds?|refunded|waives?|waived|charges?|charged|credits?|credited|commits?|committed|settles?|settled|merges?|merged)\b/,
+      /(^|[._-])(approve|close|resolve|cancel)([._-]|$)/,
+    ]);
+    const readTool = hasAny(text, [/\b(read|get|list|query|inspect|fetch|search)\b/]);
+    const proposalBoundary = hasAny(text, [/\b(proposal|propose|approval|review_required|writeback|change[-_ ]?set|diff|evidence)\b/]);
+    const idempotency = hasAny(text, [/\b(idempotency|idempotent|request_id|requestid|idempotency_key|idempotencykey)\b/]);
+    const conflictGuard = hasAny(text, [/\b(expected_version|row_version|updated_at|etag|version|conflict_guard|conflict guard|optimistic)\b/]);
+
+    if (/(^|[._-])(execute_sql|exec_sql|run_query|raw_sql|sql_query|query_sql|execute_query)([._-]|$)/.test(name.toLowerCase())) {
+      add("HIGH", "GENERIC_SQL_TOOL", "Generic execute_sql or run_query-style database tool exposed.", { tool: name });
+    }
+    if (propsLower.some((prop) => ["sql", "query", "statement", "raw_sql"].includes(prop)) && writeTool) {
+      add("HIGH", "WRITE_ACCEPTS_SQL", "Write-capable tool accepts arbitrary SQL/query/statement input.", { tool: name, evidence: props.join(", ") });
+    }
+    if (propsLower.some((prop) => ["schema", "table", "table_name", "tablename", "column", "columns", "database", "db"].includes(prop))) {
+      add("HIGH", "MODEL_CONTROLLED_IDENTIFIER", "Tool accepts schema/table/column identifiers as ordinary model input.", { tool: name, evidence: props.join(", ") });
+    }
+    if (propsLower.some((prop) => ["tenant", "tenant_id", "tenantid"].includes(prop))) {
+      add("HIGH", "MODEL_CONTROLLED_TENANT", "Tool accepts tenant_id as ordinary model input instead of trusted session context.", { tool: name, evidence: props.join(", ") });
+    }
+    if (/(^|[._-])(approve|commit|settle|merge)[._-]?(proposal|write|change)|(^|[._-])(proposal|write|change)[._-]?(approve|commit|settle|merge)([._-]|$)/.test(name.toLowerCase())) {
+      add("HIGH", "MODEL_CALLABLE_APPROVAL", "Approval or commit operation is exposed as a model-callable MCP tool.", { tool: name });
+    }
+    if (writeTool && !proposalBoundary) {
+      add("HIGH", "NO_VISIBLE_PROPOSAL_BOUNDARY", "Write-capable tool has no visible proposal, approval, evidence, or writeback boundary.", { tool: name });
+    }
+    if (!outputSchema) {
+      add("MEDIUM", "NO_STRUCTURED_OUTPUT_SCHEMA", "Tool has no structured output schema visible in the manifest.", { tool: name });
+    }
+    if (writeTool && !idempotency) {
+      add("MEDIUM", "NO_IDEMPOTENCY_KEY", "Write/proposal tool has no visible idempotency or request-key metadata.", { tool: name });
+    }
+    if (writeTool && !conflictGuard) {
+      add("MEDIUM", "NO_CONFLICT_GUARD", "Write/proposal tool has no visible row-version or conflict-guard metadata.", { tool: name });
+    }
+    if (readTool && writeTool) {
+      add("MEDIUM", "AMBIGUOUS_READ_WRITE_TOOL", "Tool mixes read and write behavior ambiguously.", { tool: name });
+    }
+    if (!tool.annotations) {
+      add("LOW", "MISSING_TOOL_ANNOTATIONS", "Tool is missing descriptive MCP annotations. Annotations are hints, not enforcement.", { tool: name });
+    }
+  }
+
+  const severityRank = { HIGH: 0, MEDIUM: 1, LOW: 2 };
+  findings.sort((a, b) => severityRank[a.severity] - severityRank[b.severity] || String(a.tool || "").localeCompare(String(b.tool || "")) || a.code.localeCompare(b.code));
+  const summary = { high: 0, medium: 0, low: 0 };
+  for (const finding of findings) summary[finding.severity.toLowerCase()] += 1;
+  return {
+    ok: true,
+    target: targetInfo.target,
+    source,
+    inspected_at: new Date().toISOString(),
+    disclaimer: MCP_AUDIT_DISCLAIMER,
+    tool_count: tools.length,
+    summary,
+    findings,
+  };
+}
+
+function printMcpAudit(report, globals) {
+  if (globals.json) return print(report, globals);
+  console.log("Static MCP database risk review");
+  console.log(`Target: ${report.target}`);
+  console.log(`Tools inspected: ${report.tool_count}`);
+  console.log(`Summary: HIGH=${report.summary.high}  MEDIUM=${report.summary.medium}  LOW=${report.summary.low}`);
+  console.log(MCP_AUDIT_DISCLAIMER);
+  if (!report.findings.length) {
+    console.log("No matching database MCP risk patterns found. This is not a security guarantee.");
+    return;
+  }
+  console.log("\nFindings:");
+  for (const finding of report.findings) {
+    const tool = finding.tool ? `  tool=${finding.tool}` : "";
+    const evidence = finding.evidence ? `  evidence=${finding.evidence}` : "";
+    console.log(`${finding.severity.padEnd(6)} ${finding.code}${tool}${evidence}`);
+    console.log(`       ${finding.message}`);
+  }
+}
+
 async function main(argv = process.argv.slice(2)) {
   const { globals, args } = parse(argv);
   const [cmd, sub, third, ...rest] = args;
@@ -375,6 +628,11 @@ async function main(argv = process.argv.slice(2)) {
     }
   }
 
+  if (cmd === "mcp" && sub === "audit") {
+    const targetInfo = await loadMcpAuditTarget(third, rest);
+    return printMcpAudit(buildMcpAuditReport(targetInfo), globals);
+  }
+
   if (cmd === "sql") {
     const db = globals.db || "";
     let sql = args.slice(1).join(" ").trim();
@@ -438,6 +696,9 @@ Usage:
   synapsor sources show app_postgres --project <project>
   synapsor sources doctor app_postgres --project <project>
   synapsor sources disable app_postgres --project <project> --yes
+  synapsor mcp audit ./tools-manifest.json
+  synapsor mcp audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN --json
+  synapsor mcp audit 'stdio:node ./server.mjs' --timeout-ms 5000
   synapsor sql --db <database> "SELECT 1;"
   synapsor sql --db <database> --file ./query.sql
   synapsor invoke <capability> --db <database> --json '{"ticket_id":"TICK-1001"}'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/client",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Node.js SDK for Synapsor, the agent-native database for auditable AI applications",
   "type": "module",
   "main": "./synapsor.mjs",

package/synapsor.mjs

@@ -19,6 +19,17 @@ export {
   PROTOCOL_VERSION,
 };
 
+export const WRITEBACK_LEASE_EXPIRED = "WRITEBACK_LEASE_EXPIRED";
+export const WRITEBACK_ALREADY_COMPLETED = "WRITEBACK_ALREADY_COMPLETED";
+export const WRITEBACK_CONFLICT = "WRITEBACK_CONFLICT";
+export const WRITEBACK_SAFETY_FAILURE = "WRITEBACK_SAFETY_FAILURE";
+export const WRITEBACK_ERROR_CODES = Object.freeze([
+  WRITEBACK_LEASE_EXPIRED,
+  WRITEBACK_ALREADY_COMPLETED,
+  WRITEBACK_CONFLICT,
+  WRITEBACK_SAFETY_FAILURE,
+]);
+
 export class SynapsorError extends Error {
   constructor(
     message,
@@ -644,6 +655,10 @@ export class Synapsor {
     });
   }
 
+  async listAdapterTools(adapter, options = {}) {
+    return this.adapterTools(adapter, options);
+  }
+
   async callAdapterTool(adapter, tool, {
     arguments: args = {},
     runId = undefined,
@@ -669,6 +684,138 @@ export class Synapsor {
     return this.request("POST", "/v1/agent/adapters/call-tool", payload);
   }
 
+  async createWritebackRunnerToken(sourceId, {
+    runnerId = undefined,
+    runner_id = undefined,
+    tokenId = undefined,
+    token_id = undefined,
+    permissions = undefined,
+    expiresAt = undefined,
+    expires_at = undefined,
+  } = {}) {
+    const payload = {};
+    const runner = runnerId ?? runner_id;
+    const token = tokenId ?? token_id;
+    const expiry = expiresAt ?? expires_at;
+    if (runner !== undefined) payload.runner_id = runner;
+    if (token !== undefined) payload.token_id = token;
+    if (permissions !== undefined) payload.permissions = permissions;
+    if (expiry !== undefined) payload.expires_at = expiry;
+    return this.request("POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/writeback-runner-tokens`, payload);
+  }
+
+  async createRunnerToken(sourceId, options = {}) {
+    return this.createWritebackRunnerToken(sourceId, options);
+  }
+
+  async listWritebackRunnerTokens(sourceId) {
+    return this.request("GET", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/writeback-runner-tokens`);
+  }
+
+  async listWritebackRunners(sourceId) {
+    return this.request("GET", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/writeback-runners`);
+  }
+
+  async listRunners(sourceId) {
+    return this.listWritebackRunners(sourceId);
+  }
+
+  async revokeWritebackRunnerToken(sourceId, tokenId, { reason = undefined } = {}) {
+    const payload = {};
+    if (reason !== undefined) payload.reason = reason;
+    return this.request("POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/writeback-runner-tokens/${encodeURIComponent(tokenId)}/revoke`, payload);
+  }
+
+  async listExternalWritebackProposals({
+    projectId = undefined,
+    project_id = undefined,
+    sourceId = undefined,
+    source_id = undefined,
+    status = undefined,
+    limit = undefined,
+  } = {}) {
+    return this.request("GET", withQuery("/v1/control/external-writebacks/proposals", {
+      project_id: projectId ?? project_id,
+      source_id: sourceId ?? source_id,
+      status,
+      limit,
+    }));
+  }
+
+  async getExternalWritebackProposal(proposalId) {
+    return this.request("GET", `/v1/control/external-writebacks/proposals/${encodeURIComponent(proposalId)}`);
+  }
+
+  async getProposal(proposalId) {
+    return this.getExternalWritebackProposal(proposalId);
+  }
+
+  async createExternalWritebackProposal(payload) {
+    return this.request("POST", "/v1/control/external-writebacks/proposals", payload);
+  }
+
+  async transitionExternalWritebackProposal(proposalId, action, payload = {}) {
+    return this.request("POST", `/v1/control/external-writebacks/proposals/${encodeURIComponent(proposalId)}/${encodeURIComponent(action)}`, payload);
+  }
+
+  async approveExternalWritebackProposal(proposalId, payload = {}) {
+    return this.transitionExternalWritebackProposal(proposalId, "approve", payload);
+  }
+
+  async rejectExternalWritebackProposal(proposalId, payload = {}) {
+    return this.transitionExternalWritebackProposal(proposalId, "reject", payload);
+  }
+
+  async recordExternalWritebackApplyResult(proposalId, payload) {
+    return this.request("POST", `/v1/control/external-writebacks/proposals/${encodeURIComponent(proposalId)}/apply-result`, payload);
+  }
+
+  async doctorWritebackRunner() {
+    return this.request("GET", "/v1/writeback/runner/doctor");
+  }
+
+  async registerRunner(payload) {
+    return this.request("POST", "/v1/runner/register", payload);
+  }
+
+  async heartbeatRunner(payload) {
+    return this.request("POST", "/v1/runner/heartbeat", payload);
+  }
+
+  async claimWritebackJob({
+    sourceId = undefined,
+    source_id = undefined,
+    limit = undefined,
+    leaseSeconds = undefined,
+    lease_seconds = undefined,
+  } = {}) {
+    const payload = {};
+    const source = sourceId ?? source_id;
+    const lease = leaseSeconds ?? lease_seconds;
+    if (source !== undefined) payload.source_id = source;
+    if (limit !== undefined) payload.limit = Number(limit);
+    if (lease !== undefined) payload.lease_seconds = Number(lease);
+    return this.request("POST", "/v1/writeback/jobs/claim", payload);
+  }
+
+  async renewWritebackLease(jobId, {
+    leaseSeconds = undefined,
+    lease_seconds = undefined,
+  } = {}) {
+    const payload = {};
+    const lease = leaseSeconds ?? lease_seconds;
+    if (lease !== undefined) payload.lease_seconds = Number(lease);
+    return this.request("POST", `/v1/writeback/jobs/${encodeURIComponent(jobId)}/heartbeat`, payload);
+  }
+
+  async completeWritebackJob(jobId, result) {
+    return this.request("POST", `/v1/writeback/jobs/${encodeURIComponent(jobId)}/result`, result);
+  }
+
+  async recordWritebackJobResult(jobId, result) {
+    return this.completeWritebackJob(jobId, result);
+  }
+
   async traceAgentRun(runId, { session = undefined } = {}) {
     return this.request("POST", "/v1/agent/runs/trace", {
       run_id: runId,
@@ -1053,6 +1200,10 @@ export class Synapsor {
     return this.request("POST", "/v1/agent/runs/replay", payload);
   }
 
+  async getReplay(runId, options = {}) {
+    return this.replayAgentRun(runId, options);
+  }
+
   async proposalLifecycle(action, proposal, { session = undefined, promoteBranch = undefined, promote_branch = undefined, targetBranch = undefined, target_branch = undefined, settlementPolicy = undefined, settlement_policy = undefined } = {}) {
     const payload = {
       proposal,
@@ -1479,6 +1630,17 @@ function identifier(value) {
   return value;
 }
 
+function withQuery(path, params) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== "") {
+      query.set(key, String(value));
+    }
+  }
+  const queryText = query.toString();
+  return queryText ? `${path}?${queryText}` : path;
+}
+
 function repoRoot() {
   return resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 }