@clavero/mcp-server 2.0.0

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@clavero/mcp-server",
+  "version": "2.0.0",
+  "description": "MCP server for Clavero — gives AI agents direct access to your product's strategic context",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "clavero": "src/index.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.25.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+
+const API_URL = process.env.CLAVERO_API_URL || "https://www.clavero.ai";
+const API_KEY = process.env.CLAVERO_API_KEY;
+
+async function api(path, options = {}) {
+  if (!API_KEY) throw new Error("CLAVERO_API_KEY not set");
+  const res = await fetch(`${API_URL}${path}`, {
+    ...options,
+    headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json", ...options.headers },
+  });
+  const ct = res.headers.get("content-type") || "";
+  if (ct.includes("application/json")) {
+    const data = await res.json();
+    if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
+    return data;
+  }
+  const text = await res.text();
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return text;
+}
+
+const ok = (text) => ({ content: [{ type: "text", text }] });
+const err = (msg) => ({ content: [{ type: "text", text: `Error: ${msg}` }], isError: true });
+
+const server = new McpServer({ name: "clavero", version: pkg.version });
+
+server.tool("clavero_get_beliefs", "Get all active strategic beliefs with confidence levels and evidence counts.", {}, async () => {
+  try {
+    const data = await api("/api/v1/beliefs");
+    if (!data.beliefs?.length) return ok("No active beliefs.");
+    return ok(data.beliefs.map((b) => `- [${b.confidence}] ${b.statement} (${b.evidenceCount || 0} evidence)`).join("\n"));
+  } catch (e) { return err(e.message); }
+});
+
+server.tool("clavero_check_beliefs", "Check if any beliefs have changed since a given date.", {
+  since: z.string().optional().describe("ISO date. Defaults to 24h ago."),
+}, async ({ since }) => {
+  const sinceDate = since || new Date(Date.now() - 86400000).toISOString();
+  try {
+    const data = await api(`/api/v1/beliefs/changes?since=${sinceDate}`);
+    if (!data.changes?.length) return ok("No belief changes since " + sinceDate);
+    return ok("Belief changes:\n" + data.changes.map((c) => `- [${c.confidence}] ${c.statement}`).join("\n"));
+  } catch (e) { return err(e.message); }
+});
+
+server.tool("clavero_get_context", "Search context entries in the workspace.", {
+  query: z.string().optional().describe("Search query"),
+  limit: z.number().optional().default(10).describe("Max results"),
+}, async ({ query, limit }) => {
+  try {
+    const params = new URLSearchParams();
+    if (query) params.set("q", query);
+    if (limit) params.set("limit", String(limit));
+    const data = await api(`/api/v1/context?${params}`);
+    if (!data.entries?.length) return ok("No context entries found.");
+    return ok(data.entries.map((e) => `### ${e.title}${e.source ? ` (${e.source})` : ""}\n${e.content}\n`).join("\n"));
+  } catch (e) { return err(e.message); }
+});
+
+server.tool(
+  "clavero_get_design_principles",
+  "DEPRECATED — prefer clavero_get_guiding_principles. This tool now returns a flattened view of the workspace's guiding principles (statement + rationale only). The guiding principles system has categories, severity, and scope — use the newer tool to see them.",
+  {},
+  async () => {
+    try {
+      const data = await api("/api/v1/design-principles");
+      if (!data.principles?.length) return ok("No principles set.");
+      return ok(data.principles.map((p) => `- ${p.statement}${p.rationale ? ` — ${p.rationale}` : ""}`).join("\n"));
+    } catch (e) { return err(e.message); }
+  }
+);
+
+server.tool(
+  "clavero_get_guiding_principles",
+  "Get the workspace's guiding principles — rules that govern execution. Three categories: directional (what to build toward), boundary (what NOT to build — the most important category), and standard (how to build). Each principle has a severity (hard/soft/advisory). ALWAYS respect these when making implementation decisions.",
+  {
+    themeId: z.string().optional().describe("Optional theme ID for theme-scoped principles alongside global"),
+  },
+  async ({ themeId }) => {
+    try {
+      const url = themeId
+        ? `/api/v1/guiding-principles?themeId=${encodeURIComponent(themeId)}`
+        : `/api/v1/guiding-principles`;
+      const data = await api(url);
+
+      const formatCategory = (principles, icon, label) => {
+        if (!principles?.length) return "";
+        const lines = principles.map((p) => {
+          let line = `- [${p.severity}] ${p.statement}`;
+          if (p.explanation) line += `\n    ${p.explanation}`;
+          if (p.violationExample) line += `\n    ⚠ Violation: ${p.violationExample}`;
+          if (p.test) line += `\n    ? Test: ${p.test}`;
+          return line;
+        }).join("\n");
+        return `${icon} ${label}:\n${lines}\n`;
+      };
+
+      const globalSections = [
+        formatCategory(data.global?.directional, "→", "Directional"),
+        formatCategory(data.global?.boundary, "⛔", "Boundaries"),
+        formatCategory(data.global?.standard, "⚙", "Standards"),
+      ].filter(Boolean).join("\n");
+
+      const themeSections = themeId
+        ? [
+            formatCategory(data.themeScoped?.directional, "→", "Directional"),
+            formatCategory(data.themeScoped?.boundary, "⛔", "Boundaries"),
+            formatCategory(data.themeScoped?.standard, "⚙", "Standards"),
+          ].filter(Boolean).join("\n")
+        : "";
+
+      if (!globalSections && !themeSections) return ok("No guiding principles set.");
+
+      let text = "GUIDING PRINCIPLES\n\nRules governing execution. Pay special attention to boundary principles with 'hard' severity — violations must be reviewed before shipping.\n\n";
+      if (globalSections) text += globalSections;
+      if (themeSections) text += `\nArea-specific principles:\n${themeSections}`;
+      return ok(text);
+    } catch (e) { return err(e.message); }
+  }
+);
+
+server.tool(
+  "clavero_get_investment_areas",
+  "Get active investment areas. These are the PM's current priorities — where the team should invest energy. Each area includes: why, beliefs, success signals, direction, boundaries, and anti-patterns. Use this to understand what to build and how to build it correctly.",
+  {
+    priority: z.enum(["high", "medium", "low"]).optional().describe("Filter by priority"),
+    status: z.enum(["active", "paused", "completed", "archived"]).optional().describe("Filter by status (default: active)"),
+  },
+  async ({ priority, status }) => {
+    try {
+      const params = new URLSearchParams();
+      if (priority) params.set("priority", priority);
+      if (status) params.set("status", status);
+      const data = await api(`/api/v1/investment-areas?${params}`);
+
+      if (!data.areas?.length) return ok("No investment areas found.");
+
+      const formatted = data.areas.map((area) => {
+        let text = `\n${"━".repeat(60)}\n`;
+        text += `${area.priority.toUpperCase()} | ${area.name} | ${area.timeframe} | ${area.status}\n`;
+        text += `${"━".repeat(60)}\n\n`;
+        if (area.context) text += `WHY:\n${area.context}\n\n`;
+        if (area.beliefs?.length) {
+          text += `BELIEFS:\n${area.beliefs.map((b) => `  [${b.confidence}] ${b.statement}`).join("\n")}\n\n`;
+        }
+        if (area.successSignals?.length) {
+          text += `SUCCESS SIGNALS:\n${area.successSignals.map((s) => {
+            const progressIcon = s.progress === "improving" ? "↑" : s.progress === "declining" ? "↓" : s.progress === "steady" ? "→" : "?";
+            let line = `  ${progressIcon} ${s.signal}`;
+            if (s.metric) line += ` (metric: ${s.metric})`;
+            if (s.target) line += ` (target: ${s.target})`;
+            if (s.progress) line += ` [${s.progress}]`;
+            return line;
+          }).join("\n")}\n\n`;
+        }
+        if (area.directionalPrinciples?.length) {
+          text += `DIRECTION:\n${area.directionalPrinciples.map((p) => `  → [${p.severity}] ${p.statement}`).join("\n")}\n\n`;
+        }
+        if (area.boundaryPrinciples?.length) {
+          text += `BOUNDARIES:\n${area.boundaryPrinciples.map((p) => {
+            let line = `  ⛔ [${p.severity}] ${p.statement}`;
+            if (p.violationExample) line += `\n     Violation: ${p.violationExample}`;
+            return line;
+          }).join("\n")}\n\n`;
+        }
+        if (area.antiPatterns?.length) {
+          text += `ANTI-PATTERNS:\n${area.antiPatterns.map((a) => `  ✗ ${a.description}`).join("\n")}\n\n`;
+        }
+        if (area.standardPrinciples?.length) {
+          text += `STANDARDS:\n${area.standardPrinciples.map((p) => `  ⚙ [${p.severity}] ${p.statement}`).join("\n")}\n`;
+        }
+        return text;
+      }).join("\n");
+
+      return ok(`ACTIVE INVESTMENT AREAS\n\nBuild within these areas, respecting direction and boundaries.\n${formatted}`);
+    } catch (e) { return err(e.message); }
+  }
+);
+
+server.tool(
+  "clavero_check_compliance",
+  "Check whether a proposed feature or change complies with the workspace's guiding principles and aligns with active investment areas. Returns violations (hard breaches), concerns (soft breaches), aligned principles, area alignment, and suggested alternatives. ALWAYS call this before implementing any non-trivial feature to catch strategically-wrong work before it ships.",
+  {
+    proposal: z.string().describe("Description of what you want to build or change — free text, a spec draft, or a sentence."),
+    themeId: z.string().optional().describe("Investment area ID if this proposal relates to a specific area"),
+  },
+  async ({ proposal, themeId }) => {
+    try {
+      const data = await api("/api/v1/compliance-check", {
+        method: "POST",
+        body: JSON.stringify({ proposal, themeId }),
+      });
+      return ok(data.assessment || "Compliance check returned no assessment.");
+    } catch (e) { return err(e.message); }
+  }
+);
+
+server.tool("clavero_capture_context", "Save a piece of strategic context to Clavero.", {
+  title: z.string().describe("Short descriptive title"),
+  content: z.string().describe("The insight or signal to capture"),
+  source: z.string().optional().default("Claude conversation").describe("Source"),
+}, async ({ title, content, source }) => {
+  try {
+    const data = await api("/api/v1/context", { method: "POST", body: JSON.stringify({ title, content, source }) });
+    let response = `Captured: "${data.title}"`;
+    if (data.beliefSuggestions?.length) {
+      response += `\n${data.beliefSuggestions.length} belief link${data.beliefSuggestions.length > 1 ? "s" : ""} suggested:`;
+      data.beliefSuggestions.forEach((s) => {
+        response += `\n  - ${s.direction === "supports" ? "↑" : s.direction === "challenges" ? "↓" : "→"} ${s.beliefStatement} (${s.strength})`;
+      });
+    }
+    return ok(response);
+  } catch (e) { return err(e.message); }
+});
+
+server.tool("clavero_generate_spec", "Generate a detailed implementation spec grounded in strategic context.", {
+  decisionId: z.string().optional().describe("Decision ID from the decision log"),
+  description: z.string().optional().describe("Free-text description of what to build"),
+}, async ({ decisionId, description }) => {
+  if (!decisionId && !description) return err("Provide either decisionId or description.");
+  try {
+    const data = await api("/api/v1/generate-spec", { method: "POST", body: JSON.stringify({ decisionId, description }) });
+    return ok(data.spec || "Spec generated.");
+  } catch (e) { return err(e.message); }
+});
+
+server.tool("clavero_list_decisions", "List recent decisions from the decision log.", {
+  limit: z.number().optional().default(10).describe("Max results"),
+}, async ({ limit }) => {
+  try {
+    const data = await api(`/api/v1/decisions?limit=${limit}`);
+    if (!data.decisions?.length) return ok("No decisions recorded.");
+    return ok(data.decisions.map((d) => `- [${d.reflectionStatus}] ${d.title}\n  Reasoning: ${(d.reasoning || "").slice(0, 100)}...`).join("\n\n"));
+  } catch (e) { return err(e.message); }
+});
+
+server.tool("clavero_log_decision", "Log a decision with reasoning.", {
+  title: z.string().describe("What was decided"),
+  reasoning: z.string().describe("Why"),
+  alternatives: z.string().optional().describe("Alternatives considered"),
+  assumptions: z.string().optional().describe("Key assumptions"),
+}, async ({ title, reasoning, alternatives, assumptions }) => {
+  try {
+    await api("/api/v1/decisions", { method: "POST", body: JSON.stringify({ title, reasoning, alternatives, assumptions }) });
+    return ok(`Decision logged: "${title}". Reflection due in 30 days.`);
+  } catch (e) { return err(e.message); }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`Clavero MCP server v${pkg.version} running`);