diffler-mcp 0.17.0 → 0.19.0

package/README.md

@@ -1,13 +1,11 @@
 # 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.
+A stdio↔HTTP bridge from Claude Code (or any stdio MCP client) to the MCP
+server of a running [diffler](https://github.com/matheusfillipe/diffler).
 
-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.
+diffler serves MCP from inside the TUI as a streamable-HTTP endpoint
+(`http://127.0.0.1:8417/mcp` by default). The proxy forwards every tool call
+to that endpoint and keeps no state of its own.
 
 ## Use it with Claude Code
 
@@ -31,8 +29,8 @@ Or in a checked-in `.mcp.json`:
 }
 ```
 
-Start Claude anywhere inside the repo and the proxy auto-discovers the port
-from `.diffler/mcp.json`. No diffler running ⇒ every tool call reports which
+Start Claude anywhere inside the repo and the proxy finds the port in
+`.diffler/mcp.json`. With no diffler running, every tool call reports which
 directory it searched.
 
 ## Configuration
@@ -50,29 +48,15 @@ Resolution order (first match wins):
    `use_instance` switches; several are listed by `list_instances`
 
 `use_instance` connects before it answers, so a bad target never gets bound.
-When diffler isn't running yet, the proxy keeps retrying quietly and announces
-its tools once one appears, so a human can start Claude first and diffler
-second. A call diffler doesn't answer within 110 s fails with that instance
-named.
+When diffler isn't running yet, the proxy keeps retrying and announces its
+tools once one appears, so you can start Claude before diffler. A call diffler
+doesn't answer within 110 s fails with that instance named.
 
-Discovery covers the normal case, so nothing needs configuring:
-
-```json
-{
-  "mcpServers": {
-    "diffler": {
-      "command": "npx",
-      "args": ["-y", "diffler-mcp"]
-    }
-  }
-}
-```
-
-Reach for `--port`, `--host` or `--repo` when diffler runs somewhere the walk-up
+Use `--port`, `--host` or `--repo` when diffler runs somewhere the walk-up
 cannot see, such as another machine over a tunnel.
 
-A human's diffler and an agent's shell are often in different repos. Two
-proxy-owned tools handle that, always available alongside diffler's own:
+A human's diffler and an agent's shell are often in different repos. The proxy
+adds two tools for that, alongside diffler's own:
 
 - **list_instances**: every running diffler this proxy can reach, across all
   repos, from the registry.
@@ -81,10 +65,8 @@ proxy-owned tools handle that, always available alongside diffler's own:
 
 ## Prefer HTTP directly?
 
-Claude Code speaks HTTP natively, so you can skip this proxy entirely:
+Claude Code speaks HTTP, so you can skip the proxy and use a fixed port:
 
 ```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

@@ -85,10 +85,8 @@ function pidAlive(pid) {
   }
 }
 
-// Each diffler publishes its live port under its own repo root, so the walk-up
-// finds the instance owning the directory the editor launched from. Returns
-// null both when nothing is found and when the closest file names a dead
-// process, so the caller falls through to the cross-repo registry either way.
+// We return null for a dead process too, so the caller falls through to the
+// cross-repo registry.
 function findLocalEndpoint(from) {
   let dir = resolve(from);
   for (;;) {
@@ -98,7 +96,7 @@ function findLocalEndpoint(from) {
         return pidAlive(pid) ? port : null;
       }
     } catch {
-      // unreadable or malformed reads like absent: keep walking up
+      // We treat an unreadable or malformed file as absent and keep walking up.
     }
     const parent = dirname(dir);
     if (parent === dir) {
@@ -115,8 +113,6 @@ function registryDir() {
   return join(base, "diffler", "instances");
 }
 
-// Every running diffler that isn't the one found by the walk-up: read from
-// the registry, dropping (and deleting) entries whose process has exited.
 function liveRegistry() {
   let files;
   try {
@@ -154,6 +150,19 @@ function describeInstances(instances) {
   return instances.map((i) => `${i.repo} (port ${i.port})`).join(", ");
 }
 
+// One diffler with several project tabs registers each project under the
+// same url: one entry per url is one instance.
+function distinctInstances(instances) {
+  const byUrl = new Map();
+  for (const instance of instances) {
+    const seen = byUrl.get(instance.url);
+    if (!seen || instance.mtimeMs > seen.mtimeMs) {
+      byUrl.set(instance.url, instance);
+    }
+  }
+  return [...byUrl.values()];
+}
+
 function matchInstances(instances, { repo, port }) {
   if (port != null) {
     return instances.filter((i) => i.port === Number(port));
@@ -168,8 +177,6 @@ function matchInstances(instances, { repo, port }) {
   return instances.filter((i) => i.repo.endsWith(`/${repo}`) || i.repo.endsWith(`\\${repo}`));
 }
 
-// Best-effort label for an error message: which repo (and port) a URL names,
-// falling back to the port alone when the registry doesn't know it.
 function describeUrl(url) {
   const match = liveRegistry().find((i) => i.url === url);
   if (match) {
@@ -185,8 +192,8 @@ function describeUrl(url) {
 class CallDeadline extends Error {}
 
 // Dropping the `upstream` reference alone leaves the transport's
-// AbortController and reconnection timer alive, so every place that
-// abandons a client closes it first.
+// AbortController and reconnection timer alive, so we close every client we
+// abandon.
 function closeQuietly(client) {
   if (!client) {
     return;
@@ -194,10 +201,6 @@ function closeQuietly(client) {
   client.close().catch(() => {});
 }
 
-// A call to the upstream that never answers must not hang the client
-// forever; racing it against a timer is what lets the proxy give up and
-// report it. `fn` is what to race (a tool call, a tools/list), so both share
-// the same deadline and reconnect handling in `withUpstream` below.
 function withDeadline(client, fn, meta) {
   let timer;
   const timeout = new Promise((_, reject) => {
@@ -223,13 +226,10 @@ function unreachableError(err) {
   return toolError(`diffler isn't reachable. Is it running in this repo? (${err.message ?? err})${extra}`);
 }
 
-// Set by the use_instance tool; overrides every other resolution source for
-// the rest of this proxy process.
 let overrideUrl = null;
 
-// `ambiguous` marks the one resolution path with no explicit say-so from the
-// human or the caller: more than one diffler is running and the newest was
-// picked for them. `forwardCall` uses it to tell the agent once per bind.
+// `ambiguous` means we picked the newest of several instances with nobody
+// choosing, so `forwardCall` tells the agent once per bind.
 function resolveUrl(opts) {
   if (overrideUrl) {
     return { url: overrideUrl, ambiguous: false };
@@ -248,7 +248,7 @@ function resolveUrl(opts) {
   if (local !== null) {
     return { url: `http://${host}:${local}/mcp`, ambiguous: false };
   }
-  const instances = liveRegistry();
+  const instances = distinctInstances(liveRegistry());
   if (instances.length === 1) {
     return { url: instances[0].url, ambiguous: false };
   }
@@ -275,20 +275,16 @@ async function main() {
   let upstreamMeta = null;
   let connecting = null;
   let retryActive = false;
-  // Set on an ambiguous auto-bind (several instances, newest picked with no
-  // say-so); `forwardCall` reports it on the first result after and clears
-  // it. A resolution the caller or the human chose leaves this null.
   let pendingBindNotice = null;
 
   const connect = async () => {
     const { url, ambiguous } = resolveUrl(opts);
     const client = new Client({ name: "diffler-mcp-proxy", version: "0.1.0" });
     await client.connect(new StreamableHTTPClientTransport(new URL(url)));
-    // One round trip before caching: a registered pid can be alive while the
-    // MCP server behind it is not (mid-restart, a crashed listener), and this
-    // is what tells the two apart.
+    // A registered pid can be alive while its MCP server is not (mid-restart,
+    // a crashed listener), so we make one round trip before caching.
     await client.listTools();
-    // cache synchronously after the await so a later close can't race ahead of it
+    // We cache synchronously after the await so a later close can't race ahead of it.
     upstream = client;
     upstreamMeta = describeUrl(url);
     pendingBindNotice = ambiguous
@@ -317,10 +313,8 @@ async function main() {
     return connecting;
   };
 
-  // Runs `fn` against the live upstream client under the deadline above; a
-  // deadline drops the upstream and fails outright, no second wait on the
-  // same call, while any other failure gets one reconnect-and-retry. Shared
-  // by tools/list and tools/call, so a hung diffler fails either one alike.
+  // A missed deadline drops the upstream and fails at once, so a hung diffler
+  // costs one wait; any other failure gets one reconnect and retry.
   const withUpstream = async (fn) => {
     let client;
     const attempt = async () => {
@@ -348,9 +342,8 @@ async function main() {
     }
   };
 
-  // Lets a human start Claude first and diffler second: a `tools/list` that
-  // finds nothing arms this, and it keeps trying quietly until diffler
-  // appears (or ten minutes pass), announcing the new tools once it does.
+  // A human may start Claude before diffler, so we keep retrying after an
+  // empty `tools/list` and announce the tools once diffler appears.
   const startRetryingUpstream = () => {
     if (retryActive) {
       return;
@@ -375,8 +368,6 @@ async function main() {
     setTimeout(attempt, RETRY_MS);
   };
 
-  // Forwards one tool call, appending the ambiguous-bind notice to the first
-  // result after such a bind (once only: it clears itself here).
   const forwardCall = async (params) => {
     try {
       const result = await withUpstream((client) => client.callTool(params));
@@ -418,7 +409,7 @@ async function main() {
         `no running instance matches ${JSON.stringify(args)}. Choices: ${describeInstances(instances) || "none running"}.`,
       );
     }
-    if (matches.length > 1) {
+    if (distinctInstances(matches).length > 1) {
       return toolError(
         `${JSON.stringify(args)} matches more than one instance: ${describeInstances(matches)}. Be more specific.`,
       );
@@ -463,8 +454,8 @@ async function main() {
   });
 
   await server.connect(new StdioServerTransport());
-  // stdout is the MCP channel, so the startup diagnosis goes to stderr, where
-  // clients surface it; the proxy stays up and reconnects when diffler starts
+  // stdout is the MCP channel, so we write the startup diagnosis to stderr and
+  // stay up to reconnect when diffler starts.
   void ensureUpstream().catch((err) => {
     process.stderr.write(`diffler-mcp: ${err.message ?? err}\n`);
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffler-mcp",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "stdio↔HTTP MCP proxy bridging Claude Code (or any stdio MCP client) to a running diffler review session",
   "type": "module",
   "bin": {