@getmarrow/mcp 2.0.0 → 2.1.0

package/README.md

@@ -1,16 +1,26 @@
 # @getmarrow/mcp
 
-**Your go-to memory provider for all agents, for any AI model.**
+> **Your go-to memory provider for all agents, for any AI model.**
 
-Add Marrow to any Claude agent in 30 seconds. The hive makes every decision smarter.
+Give Claude (or any MCP-compatible agent) a memory that compounds across every session, every user, every run. Marrow connects your agent to a hive of collective intelligence — what worked, what failed, patterns discovered across thousands of agent runs.
+
+**One tool call. Your agent stops starting from zero.**
+
+---
 
 ## Install
 
 ```bash
-npm install @getmarrow/mcp
+npm install -g @getmarrow/mcp
 ```
 
-## Claude Config
+Get your API key at [getmarrow.ai](https://getmarrow.ai)
+
+---
+
+## Setup — Claude Desktop
+
+Add to your `claude_desktop_config.json`:
 
 ```json
 {
@@ -18,23 +28,188 @@ npm install @getmarrow/mcp
     "marrow": {
       "command": "npx",
       "args": ["@getmarrow/mcp"],
-      "env": { "MARROW_API_KEY": "mrw_your_key" }
+      "env": {
+        "MARROW_API_KEY": "mrw_your_api_key"
+      }
     }
   }
 }
 ```
 
+Restart Claude. That's it — Marrow is now available as a tool in every conversation.
+
+---
+
+## Setup — Any MCP-Compatible Agent
+
+```bash
+export MARROW_API_KEY=mrw_your_api_key
+npx @getmarrow/mcp
+# Listens on stdin, outputs JSON-RPC on stdout
+# Drop into any MCP framework
+```
+
+---
+
+## How It Works
+
+Your agent calls `marrow_think` before acting. Marrow queries the hive — collective intelligence from every agent that's ever done something similar — and returns what worked, what patterns emerged, what playbooks exist. When your agent is done, that experience gets committed back to the hive. Every agent gets smarter. Forever.
+
+---
+
 ## Tools
 
-### `marrow_think`
-Call before every significant action. Returns collective intelligence from the hive — what worked before, discovered patterns, proven playbooks. Pass `previous_outcome` to commit your last action and keep the hive learning.
+### `marrow_think` — The core tool
+
+Call this before every significant action. Returns collective intelligence from the hive.
+
+**Input:**
+```json
+{
+  "action": "What the agent is about to do",
+  "type": "implementation | security | architecture | process | general",
+  "previous_outcome": "What happened last time (auto-commits previous session)",
+  "previous_success": true
+}
+```
+
+**Returns:**
+```json
+{
+  "decision_id": "save this for the next call",
+  "intelligence": {
+    "similar": [
+      { "outcome": "Used incremental approach. Shipped in 2 days, 0 rollbacks.", "confidence": 0.91 }
+    ],
+    "similar_count": 3,
+    "patterns": [
+      { "pattern_id": "a1b2c3", "decision_type": "implementation", "frequency": 84, "confidence": 0.9 }
+    ],
+    "patterns_count": 2,
+    "templates": [
+      { "steps": ["Plan", "Spec", "Build", "Test", "Deploy"], "success_rate": 0.89 }
+    ],
+    "success_rate": 0.87,
+    "priority_score": 0.7,
+    "insight": "Workflow gap detected — barvis_audit missing after build",
+    "insights": [
+      {
+        "type": "workflow_gap",
+        "summary": "audit not logged after build (3 consecutive times)",
+        "action": "Run audit before reporting done",
+        "severity": "critical",
+        "count": 3
+      }
+    ],
+    "cluster_id": "818df2fa-6365-49f6-b478-bc3dcb748469"
+  },
+  "stream_url": "/v1/stream?format=sse"
+}
+```
+
+**Example prompt to Claude:**
+
+> Before starting this refactor, call `marrow_think` with action "Refactoring auth module to support OAuth 2.0" and type "implementation". Use the intelligence to guide your approach.
+
+Claude will automatically:
+1. Call `marrow_think`
+2. Read what worked for other agents doing similar refactors
+3. Apply those patterns to its approach
+4. On the next `marrow_think` call, commit this outcome back to the hive
+
+---
+
+### `marrow_commit` — Explicit commit
+
+Commit an outcome explicitly when you need more control. `marrow_think` auto-commits on the next call, so this is optional.
+
+**Input:**
+```json
+{
+  "decision_id": "from previous marrow_think",
+  "success": true,
+  "outcome": "Auth refactor complete. OAuth 2.0 working. Zero breaking changes. 2 day turnaround.",
+  "caused_by": "optional: previous decision_id to link causally"
+}
+```
+
+---
+
+### `marrow_status` — Platform health
+
+Check your agent's current performance across the hive.
+
+**Returns:**
+```json
+{
+  "success_rate": 0.87,
+  "decision_velocity": 142,
+  "patterns_discovered": 23,
+  "hive_consensus": 0.91
+}
+```
+
+---
+
+## Real Example — Claude Coding Agent
+
+**System prompt addition:**
+```
+Before starting any significant task, call marrow_think with a description of what you're about to do.
+After completing a task, the next marrow_think call will automatically record the outcome.
+Use the intelligence returned to guide your approach — especially `similar` and `patterns`.
+```
+
+**What happens in practice:**
+
+User: *"Refactor the payment service to add retry logic"*
+
+Claude calls `marrow_think`:
+```json
+{ "action": "Adding retry logic to payment service", "type": "implementation" }
+```
+
+Marrow returns:
+```json
+{
+  "intelligence": {
+    "similar": [
+      { "outcome": "Exponential backoff with jitter. 3 retries max. Idempotency key required. Zero double-charges in 6 months.", "confidence": 0.96 }
+    ],
+    "patterns": [
+      { "pattern": "Retry without idempotency key causes duplicate transactions in 23% of cases", "frequency": 156 }
+    ]
+  }
+}
+```
+
+Claude now knows — from thousands of other agents' experience — exactly what to do and what to avoid. Without Marrow, it would have guessed.
+
+---
+
+## Why Marrow for MCP?
+
+- **Zero setup friction** — one config entry, works instantly
+- **Model agnostic** — Claude, GPT, Gemini, any MCP-compatible model
+- **Compounds automatically** — every session adds to the hive, no manual curation
+- **Private by default** — your agent's decisions are anonymized before entering the hive
+- **Persistent across sessions** — memory survives context resets, model upgrades, new conversations
+
+---
+
+## Get Started
+
+```bash
+npm install -g @getmarrow/mcp
+```
 
-### `marrow_commit`
-Explicit commit when you need more control. `marrow_think` auto-commits on the next call.
+1. Get your API key at [getmarrow.ai](https://getmarrow.ai)
+2. Add the MCP server config above
+3. Tell your agent to call `marrow_think` before acting
+4. Watch collective intelligence flow in from the first call
 
-### `marrow_status`
-Full platform health — your success rate, hive activity, patterns detected.
+**Your agent inherits the experience of every agent that came before it.**
 
-## Get a Key
+---
 
-[portal.getmarrow.ai](https://portal.getmarrow.ai)
+*Compatible with Claude Desktop, Claude API, and any MCP-compatible framework.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmarrow/mcp",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Your go-to memory provider for all agents, for any AI model.",
   "bin": {
     "marrow-mcp": "dist/cli.js"
@@ -16,5 +16,9 @@
     "memory",
     "agents"
   ],
-  "license": "MIT"
-}
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}

package/src/cli.ts

@@ -1,235 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Marrow MCP stdio server — collective memory for Claude and MCP agents.
- * Exposes: marrow_think, marrow_commit, marrow_status
- */
-
-import * as readline from 'readline';
-import { marrowThink, marrowCommit, marrowStatus } from './index';
-
-const API_KEY = process.env.MARROW_API_KEY || '';
-const BASE_URL = process.env.MARROW_BASE_URL || 'https://api.getmarrow.ai';
-
-if (!API_KEY) {
-  process.stderr.write('Error: MARROW_API_KEY environment variable is required\n');
-  process.exit(1);
-}
-
-// MCP protocol types
-interface MCPRequest {
-  jsonrpc: '2.0';
-  id: string | number;
-  method: string;
-  params?: Record<string, unknown>;
-}
-
-interface MCPResponse {
-  jsonrpc: '2.0';
-  id: string | number;
-  result?: unknown;
-  error?: { code: number; message: string };
-}
-
-function send(response: MCPResponse): void {
-  process.stdout.write(JSON.stringify(response) + '\n');
-}
-
-function success(id: string | number, result: unknown): void {
-  send({ jsonrpc: '2.0', id, result });
-}
-
-function error(id: string | number, code: number, message: string): void {
-  send({ jsonrpc: '2.0', id, error: { code, message } });
-}
-
-// Tool definitions
-const TOOLS = [
-  {
-    name: 'marrow_think',
-    description:
-      'Get collective intelligence from the Marrow hive before acting. ' +
-      'Call this before every significant action. Pass previous_outcome ' +
-      'to auto-commit your last action and open a new memory session.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        action: {
-          type: 'string',
-          description: 'What the agent is about to do',
-        },
-        type: {
-          type: 'string',
-          enum: ['implementation', 'security', 'architecture', 'process', 'general'],
-          description: 'Type of action (default: general)',
-        },
-        context: {
-          type: 'object',
-          description: 'Optional metadata about the current situation',
-        },
-        previous_decision_id: {
-          type: 'string',
-          description: 'decision_id from previous think() call — auto-commits that session',
-        },
-        previous_success: {
-          type: 'boolean',
-          description: 'Did the previous action succeed?',
-        },
-        previous_outcome: {
-          type: 'string',
-          description: 'What happened in the previous action (required if previous_decision_id provided)',
-        },
-      },
-      required: ['action'],
-    },
-  },
-  {
-    name: 'marrow_commit',
-    description:
-      'Explicitly commit the result of an action to Marrow. ' +
-      'Optional — marrow_think() auto-commits if you pass previous_outcome. ' +
-      'Use when you need explicit control over commit timing.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        decision_id: {
-          type: 'string',
-          description: 'decision_id from the marrow_think call',
-        },
-        success: {
-          type: 'boolean',
-          description: 'Did the action succeed?',
-        },
-        outcome: {
-          type: 'string',
-          description: 'What happened — be specific, this trains the hive',
-        },
-        caused_by: {
-          type: 'string',
-          description: 'Optional: what caused this action',
-        },
-      },
-      required: ['decision_id', 'success', 'outcome'],
-    },
-  },
-  {
-    name: 'marrow_status',
-    description: 'Check Marrow platform health and status.',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-      required: [],
-    },
-  },
-];
-
-// Request handler
-async function handleRequest(req: MCPRequest): Promise<void> {
-  const { id, method, params } = req;
-
-  try {
-    if (method === 'initialize') {
-      success(id, {
-        protocolVersion: '2024-11-05',
-        capabilities: { tools: {} },
-        serverInfo: { name: 'marrow', version: '2.0.0' },
-      });
-      return;
-    }
-
-    if (method === 'tools/list') {
-      success(id, { tools: TOOLS });
-      return;
-    }
-
-    if (method === 'tools/call') {
-      const toolName = (params as Record<string, unknown>)?.name as string;
-      const args = ((params as Record<string, unknown>)?.arguments || {}) as Record<string, unknown>;
-
-      if (toolName === 'marrow_think') {
-        const result = await marrowThink(API_KEY, BASE_URL, {
-          action: args.action as string,
-          type: args.type as string | undefined,
-          context: args.context as Record<string, unknown> | undefined,
-          previous_decision_id: args.previous_decision_id as string | undefined,
-          previous_success: args.previous_success as boolean | undefined,
-          previous_outcome: args.previous_outcome as string | undefined,
-        });
-        success(id, {
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(result, null, 2),
-            },
-          ],
-        });
-        return;
-      }
-
-      if (toolName === 'marrow_commit') {
-        const result = await marrowCommit(API_KEY, BASE_URL, {
-          decision_id: args.decision_id as string,
-          success: args.success as boolean,
-          outcome: args.outcome as string,
-          caused_by: args.caused_by as string | undefined,
-        });
-        success(id, {
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(result, null, 2),
-            },
-          ],
-        });
-        return;
-      }
-
-      if (toolName === 'marrow_status') {
-        const result = await marrowStatus(API_KEY, BASE_URL);
-        success(id, {
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(result, null, 2),
-            },
-          ],
-        });
-        return;
-      }
-
-      error(id, -32601, `Unknown tool: ${toolName}`);
-      return;
-    }
-
-    // Unknown method
-    error(id, -32601, `Method not found: ${method}`);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    error(id, -32603, `Internal error: ${message}`);
-  }
-}
-
-// stdio server
-const rl = readline.createInterface({
-  input: process.stdin,
-  output: process.stdout,
-  terminal: false,
-});
-
-rl.on('line', (line) => {
-  const trimmed = line.trim();
-  if (!trimmed) return;
-
-  try {
-    const req = JSON.parse(trimmed) as MCPRequest;
-    handleRequest(req).catch((err) => {
-      process.stderr.write(`Unhandled error: ${err}\n`);
-    });
-  } catch {
-    process.stderr.write(`Failed to parse request: ${trimmed}\n`);
-  }
-});
-
-rl.on('close', () => {
-  process.exit(0);
-});

package/src/index.ts

@@ -1,103 +0,0 @@
-export interface MarrowIntelligence {
-  similar: Array<{ outcome: string; confidence: number }>;
-  patterns: Array<{ pattern: string; frequency: number }>;
-  templates: Array<{ steps: unknown[]; success_rate: number }>;
-  shared: Array<{ outcome: string }>;
-  causal_chain: unknown | null;
-  success_rate: number;
-  priority_score: number;
-}
-
-export interface ThinkResult {
-  decision_id: string;
-  intelligence: MarrowIntelligence;
-  stream_url: string;
-  previous_committed?: boolean;
-}
-
-export interface CommitResult {
-  committed: boolean;
-  success_rate: number;
-  insight: string | null;
-}
-
-export interface StatusResult {
-  status: string;
-  version: string;
-  tiers: number;
-  uptime_ms: number;
-}
-
-export async function marrowThink(
-  apiKey: string,
-  baseUrl: string,
-  params: {
-    action: string;
-    type?: string;
-    context?: Record<string, unknown>;
-    previous_decision_id?: string;
-    previous_success?: boolean;
-    previous_outcome?: string;
-  }
-): Promise<ThinkResult> {
-  const body: Record<string, unknown> = {
-    action: params.action,
-    type: params.type || 'general',
-  };
-  if (params.context) body.context = params.context;
-  if (params.previous_decision_id) {
-    body.previous_decision_id = params.previous_decision_id;
-    body.previous_success = params.previous_success ?? true;
-    body.previous_outcome = params.previous_outcome ?? '';
-  }
-
-  const res = await fetch(`${baseUrl}/v1/agent/think`, {
-    method: 'POST',
-    headers: {
-      'Authorization': `Bearer ${apiKey}`,
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify(body),
-  });
-
-  const json = await res.json() as { data: ThinkResult; error?: string };
-  if (json.error) throw new Error(json.error);
-  return json.data;
-}
-
-export async function marrowCommit(
-  apiKey: string,
-  baseUrl: string,
-  params: {
-    decision_id: string;
-    success: boolean;
-    outcome: string;
-    caused_by?: string;
-  }
-): Promise<CommitResult> {
-  const res = await fetch(`${baseUrl}/v1/agent/commit`, {
-    method: 'POST',
-    headers: {
-      'Authorization': `Bearer ${apiKey}`,
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify(params),
-  });
-
-  const json = await res.json() as { data: CommitResult; error?: string };
-  if (json.error) throw new Error(json.error);
-  return json.data;
-}
-
-export async function marrowStatus(
-  apiKey: string,
-  baseUrl: string
-): Promise<StatusResult> {
-  const res = await fetch(`${baseUrl}/v1/health`, {
-    headers: { 'Authorization': `Bearer ${apiKey}` },
-  });
-
-  const json = await res.json() as { data: StatusResult; error?: string };
-  if (json.error) throw new Error(json.error);
-  return json.data;
-}

package/tsconfig.json

@@ -1,18 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "commonjs",
-    "lib": ["ES2020"],
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}