metaphore-mcp 1.0.0

package/README.md

@@ -0,0 +1,77 @@
+# METAPHORE MCP Server
+
+**Turn any technical concept into a clear human story — right inside Claude Code.**
+
+[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc-sa/4.0/)
+
+## Setup
+
+### 1. Get your METAPHORE key
+
+Sign up at [metaphore.app](https://metaphore.app) → Account → copy your `mkey`.
+
+### 2. Add to Claude Code
+
+Run:
+
+```bash
+claude mcp add metaphore -e METAPHORE_KEY=mkey_xxxxx -- npx -y metaphore-mcp
+```
+
+Or manually add to your `.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "metaphore": {
+      "command": "npx",
+      "args": ["-y", "metaphore-mcp"],
+      "env": {
+        "METAPHORE_KEY": "mkey_xxxxx"
+      }
+    }
+  }
+}
+```
+
+Replace `mkey_xxxxx` with your actual key.
+
+### 3. Use it
+
+In Claude Code, ask it to use the metaphore tool:
+
+```
+Use metaphore to explain what a reverse proxy is
+```
+
+Or with parameters:
+
+```
+Use metaphore to explain our microservices architecture --audience ceo --depth short
+```
+
+## Parameters
+
+| Parameter | Values | Description |
+|-----------|--------|-------------|
+| `input` | any text | **Required.** The technical concept to transform |
+| `audience` | `ceo`, `junior-dev`, `12-year-old`, `founder`, `operator`, `salesperson` | Who the explanation is for |
+| `style` | `building`, `restaurant`, `postal`, `hospital`, `workshop`, `theater` | Analogy domain |
+| `depth` | `short`, `full` (default) | One paragraph vs. full 3-act story |
+| `objective` | `understand`, `decide`, `debug`, `explain-to-someone`, `learn` | What the reader needs to do next |
+| `language` | Any language code (`fr`, `es`, `de`, ...) | Override output language |
+
+## Pricing
+
+Your METAPHORE key includes **300 free IDE transforms/month**. Upgrade to Pro ($5/month) for unlimited access at [metaphore.app](https://metaphore.app).
+
+## Requirements
+
+- Node.js 18+
+- A METAPHORE key ([get one free](https://metaphore.app))
+
+## License
+
+[CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)
+
+Created by [Philippe Nerette](https://metaphore.app).

package/index.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const API_URL = process.env.METAPHORE_API_URL || "https://api.metaphore.app";
+const METAPHORE_KEY = process.env.METAPHORE_KEY;
+
+if (!METAPHORE_KEY) {
+  process.stderr.write(
+    "Error: METAPHORE_KEY environment variable is required.\n" +
+      "Get your key at https://metaphore.app → Account → METAPHORE Key (mkey)\n"
+  );
+  process.exit(1);
+}
+
+const server = new McpServer({
+  name: "metaphore",
+  version: "1.0.0",
+});
+
+server.registerTool(
+  "metaphore",
+  {
+    title: "METAPHORE",
+    description:
+      "Turn any technical concept, architecture, incident, data flow, or LLM output into a clear human story. " +
+      "Returns a structured narrative with hero, conflict, resolution, reality mapping, and moral.",
+    inputSchema: {
+      input: z
+        .string()
+        .describe(
+          "The technical concept or input to transform into a human story"
+        ),
+      audience: z
+        .enum([
+          "ceo",
+          "junior-dev",
+          "12-year-old",
+          "founder",
+          "operator",
+          "salesperson",
+        ])
+        .optional()
+        .describe("Who the explanation is for"),
+      style: z
+        .enum([
+          "building",
+          "restaurant",
+          "postal",
+          "hospital",
+          "workshop",
+          "theater",
+        ])
+        .optional()
+        .describe("Analogy domain / narrative world"),
+      depth: z
+        .enum(["short", "full"])
+        .optional()
+        .describe("Short (1 paragraph) or full (3-act story). Default: full"),
+      objective: z
+        .enum(["understand", "decide", "debug", "explain-to-someone", "learn"])
+        .optional()
+        .describe("What the reader needs to do next"),
+      language: z
+        .string()
+        .optional()
+        .describe(
+          "Output language code (e.g. fr, es, de). Auto-detected from input by default"
+        ),
+    },
+  },
+  async ({ input, audience, style, depth, objective, language }) => {
+    const body = {
+      input,
+      mkey: METAPHORE_KEY,
+      channel: "ide",
+    };
+
+    if (audience) body.audience = audience;
+    if (style) body.style = style;
+    if (depth) body.depth = depth;
+    if (objective) body.objective = objective;
+    if (language) body.language = language;
+
+    let response;
+    try {
+      response = await fetch(`${API_URL}/transform`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      });
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Connection error: could not reach ${API_URL}. Check your network.`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    if (!response.ok) {
+      const status = response.status;
+      let message;
+      try {
+        const data = await response.json();
+        message = data.error || data.message || response.statusText;
+      } catch {
+        message = response.statusText;
+      }
+
+      if (status === 401) {
+        message = `Invalid METAPHORE_KEY. Check your key at https://metaphore.app → Account.`;
+      } else if (status === 403) {
+        message = `Quota exceeded. Upgrade to Pro at https://metaphore.app or add your own LLM key.`;
+      }
+
+      return {
+        content: [{ type: "text", text: `Error ${status}: ${message}` }],
+        isError: true,
+      };
+    }
+
+    const data = await response.json();
+
+    const meta = [];
+    if (data.model) meta.push(`Model: ${data.model}`);
+    if (data.provider) meta.push(`Provider: ${data.provider}`);
+    if (data.usage) {
+      const { inputTokens, outputTokens } = data.usage;
+      if (inputTokens || outputTokens) {
+        meta.push(`Tokens: ${inputTokens || 0} in / ${outputTokens || 0} out`);
+      }
+    }
+
+    const text = meta.length
+      ? `${data.result}\n\n---\n_${meta.join(" · ")}_`
+      : data.result;
+
+    return {
+      content: [{ type: "text", text }],
+    };
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "metaphore-mcp",
+  "version": "1.0.0",
+  "description": "METAPHORE MCP server — turn any technical concept into a clear human story, right inside Claude Code",
+  "type": "module",
+  "bin": {
+    "metaphore-mcp": "index.js"
+  },
+  "main": "index.js",
+  "license": "CC-BY-NC-SA-4.0",
+  "author": "Philippe Nerette",
+  "keywords": [
+    "metaphore",
+    "mcp",
+    "claude",
+    "model-context-protocol",
+    "technical-writing",
+    "analogy",
+    "explanation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/metaphore-app/metaphore-mcp"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.25.0"
+  }
+}