diffler-mcp 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# diffler-mcp
+
+A tiny stdio↔HTTP bridge that lets Claude Code (or any stdio MCP client) talk to
+the MCP server embedded in a running [diffler](https://github.com/matheusfillipe/diffler)
+review session.
+
+diffler's MCP server runs **inside the TUI** as a streamable-HTTP endpoint
+(`http://127.0.0.1:8417/mcp` by default) because it serves the live review state
+on the app's main loop. This proxy is spawned by Claude over stdio and forwards
+every tool call to that endpoint — it owns no state itself.
+
+## Use it with Claude Code
+
+Run diffler in your repo (it prints the connect hint and writes
+`.diffler/mcp.json` with the live port), then:
+
+```bash
+claude mcp add diffler -- npx -y diffler-mcp
+```
+
+Or in a checked-in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "diffler": {
+      "command": "npx",
+      "args": ["-y", "diffler-mcp"]
+    }
+  }
+}
+```
+
+Run Claude from the repo root and the proxy auto-discovers the port from
+`.diffler/mcp.json`. No diffler running ⇒ the proxy exits with a clear error.
+
+## Configuration
+
+Resolution order (first match wins):
+
+1. `--url <url>` / `DIFFLER_MCP_URL` — full endpoint, e.g. `http://127.0.0.1:8417/mcp`
+2. `--port <n>` / `DIFFLER_MCP_PORT` and `--host <h>` / `DIFFLER_MCP_HOST`
+3. the live port in `<repo>/.diffler/mcp.json` (`--repo <path>`, default: cwd)
+4. `http://127.0.0.1:8417/mcp`
+
+```json
+{
+  "mcpServers": {
+    "diffler": {
+      "command": "npx",
+      "args": ["-y", "diffler-mcp", "--port", "8417"],
+      "env": { "DIFFLER_MCP_HOST": "127.0.0.1" }
+    }
+  }
+}
+```
+
+## Prefer HTTP directly?
+
+Claude Code speaks HTTP natively, so you can skip this proxy entirely:
+
+```bash
+claude mcp add --transport http diffler http://127.0.0.1:8417/mcp
+```
+
+The proxy exists for the `npx`, zero-config, auto-port-discovery ergonomics.

package/index.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// stdio↔HTTP MCP proxy: Claude Code spawns this over stdio, and it forwards
+// every tool call to the streamable-HTTP MCP server embedded in a running
+// diffler TUI. diffler's MCP serves the live review state, so the proxy never
+// owns state — it only bridges transports.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 8417;
+
+function parseArgs(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const take = () => argv[(i += 1)];
+    switch (arg) {
+      case "--url":
+        opts.url = take();
+        break;
+      case "--host":
+        opts.host = take();
+        break;
+      case "--port":
+        opts.port = take();
+        break;
+      case "--repo":
+        opts.repo = take();
+        break;
+      default:
+        // unknown flags are ignored so future diffler args don't break older proxies
+        break;
+    }
+  }
+  return opts;
+}
+
+// The port may differ from the configured one after an ephemeral fallback, so
+// diffler publishes the live endpoint to .diffler/mcp.json in the repo.
+function discoverPort(repo) {
+  try {
+    const raw = readFileSync(join(repo, ".diffler", "mcp.json"), "utf8");
+    const port = JSON.parse(raw).port;
+    return typeof port === "number" ? port : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveUrl() {
+  const opts = parseArgs(process.argv.slice(2));
+  const env = process.env;
+  const explicit = opts.url || env.DIFFLER_MCP_URL;
+  if (explicit) {
+    return explicit;
+  }
+  const host = opts.host || env.DIFFLER_MCP_HOST || DEFAULT_HOST;
+  const repo = opts.repo || process.cwd();
+  const port =
+    opts.port || env.DIFFLER_MCP_PORT || discoverPort(repo) || DEFAULT_PORT;
+  return `http://${host}:${port}/mcp`;
+}
+
+async function main() {
+  const url = resolveUrl();
+
+  const client = new Client({ name: "diffler-mcp-proxy", version: "0.1.0" });
+  try {
+    await client.connect(new StreamableHTTPClientTransport(new URL(url)));
+  } catch (err) {
+    process.stderr.write(
+      `diffler-mcp: cannot reach a diffler MCP server at ${url}\n` +
+        `Is diffler running in this repo? (${err.message ?? err})\n`,
+    );
+    process.exit(1);
+  }
+
+  const server = new Server(
+    { name: "diffler", version: "0.1.0" },
+    { capabilities: { tools: {} } },
+  );
+  server.setRequestHandler(ListToolsRequestSchema, () => client.listTools());
+  server.setRequestHandler(CallToolRequestSchema, (request) =>
+    client.callTool(request.params),
+  );
+
+  // when diffler exits the HTTP side drops; tear down so Claude sees the close
+  client.onclose = () => {
+    void server.close().finally(() => process.exit(0));
+  };
+
+  await server.connect(new StdioServerTransport());
+}
+
+main().catch((err) => {
+  process.stderr.write(`diffler-mcp: ${err.stack ?? err}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "diffler-mcp",
+  "version": "0.1.0",
+  "description": "stdio↔HTTP MCP proxy bridging Claude Code (or any stdio MCP client) to a running diffler review session",
+  "type": "module",
+  "bin": {
+    "diffler-mcp": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/matheusfillipe/diffler.git",
+    "directory": "npm/diffler-mcp"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "diffler",
+    "code-review",
+    "claude"
+  ],
+  "scripts": {
+    "prepublishOnly": "node --check index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}