@going-haywire/farmhand4claude 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 going-haywire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @going-haywire/farmhand4claude
+
+The **Farmhand** MCP proxy — a stdio↔HTTP bridge that connects Claude Code (or
+any MCP client) to a running [Haywire](https://github.com/going-haywire/haywire)
+studio, so the studio's tools appear mid-session with no reconnect.
+
+> This npm package is just the proxy binary. The full beginner experience —
+> onboarding skills that take you from a bare machine to a running studio — ships
+> as the **`farmhand4claude` Claude Code plugin**, which runs this proxy for you.
+> See the [plugin repo](https://github.com/going-haywire/farmhand4claude).
+
+## What it does
+
+Claude Code spawns this over stdio at session start (it always starts, even when
+no studio is running). Behind it, the proxy dials the Haywire studio's
+streamable-HTTP `/mcp` endpoint:
+
+- **Studio down** → exposes a single sentinel tool, `farmhand_studio_status`.
+- **Studio comes up mid-session** → the proxy forwards the studio's tools and
+  resources and re-emits `list_changed`, so they appear with **no reconnect**.
+- **Studio dies** → a liveness poll returns the proxy to down-mode and re-emits
+  `list_changed` again.
+
+All logs go to stderr; stdout carries only MCP frames.
+
+## Usage (as a Claude Code plugin)
+
+You normally don't run this directly — install the plugin and it runs the proxy:
+
+```
+/plugin marketplace add going-haywire/farmhand4claude
+/plugin install farmhand4claude
+```
+
+## Configuration (environment variables)
+
+| Variable              | Default                              | Purpose                                            |
+| --------------------- | ------------------------------------ | -------------------------------------------------- |
+| `FARMHAND_URL`        | `http://127.0.0.1:8082/mcp`          | The studio's streamable-HTTP MCP endpoint.         |
+| `FARMHAND_TOKEN_PATH` | *(derived from the workspace)*       | Explicit path to the bearer-token file.            |
+| `HAYWIRE_WORKSPACE`   | —                                    | Workspace root; token read from `<ws>/.haywire/farmhand_token`. |
+| `CLAUDE_PROJECT_DIR`  | *(set by Claude Code)*               | Fallback workspace root when the plugin runs it.   |
+| `FARMHAND_POLL_MS`    | `2000`                               | Studio discovery / liveness poll interval.         |
+
+The bearer token is read **lazily** — the file does not exist until the studio
+has run once.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * Farmhand stdio<->HTTP MCP proxy.
+ *
+ * Claude Code connects to THIS over stdio at session start (always succeeds,
+ * because this process is trivially up). Behind it we dial the Haywire studio's
+ * streamable-HTTP /mcp endpoint, which may not exist yet. When the studio comes
+ * up mid-session we forward its tool/resource lists and re-emit list_changed so
+ * the tools appear in Claude Code with no reconnect. When the studio dies, the
+ * poll's liveness probe returns us to down-mode and re-emits list_changed.
+ *
+ * Facts pinned to primary sources (@modelcontextprotocol/sdk@1.29.0):
+ *   - StreamableHTTPClientTransport(url, { requestInit: { headers } })  — src/client/streamableHttp.ts:100,149
+ *   - low-level Server.sendToolListChanged()/sendResourceListChanged()  — src/server/index.ts:656,662
+ *   - client.setNotificationHandler(ToolListChangedNotificationSchema)  — example simpleStreamableHttp.ts
+ *   - stdio MUST NOT write non-MCP data to stdout (spec/transports)     — hence all logs -> stderr
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ResourceListChangedNotificationSchema, ToolListChangedNotificationSchema, } from "@modelcontextprotocol/sdk/types.js";
+// ---- config (env-overridable; sensible Haywire defaults) --------------------
+const UPSTREAM_URL = process.env.FARMHAND_URL ?? "http://127.0.0.1:8082/mcp";
+const POLL_MS = Number(process.env.FARMHAND_POLL_MS ?? 2000);
+/**
+ * Candidate token paths, in priority order. The token lives at
+ * `<workspace>/.haywire/farmhand_token`, so the whole game is knowing the
+ * workspace. Claude Code does NOT run the MCP server with cwd = workspace
+ * (it inherits the launch dir / $HOME — see CC issues #17565, #75266), so we
+ * do NOT trust process.cwd(). Instead we read the workspace from env vars that
+ * CC exports to the MCP subprocess and interpolates in plugin.json's env block:
+ * FARMHAND_TOKEN_PATH (explicit override) > HAYWIRE_WORKSPACE >
+ * CLAUDE_PROJECT_DIR. homedir() is a last resort for manual/standalone runs.
+ */
+function tokenCandidates() {
+    const paths = [];
+    const add = (base) => {
+        if (base)
+            paths.push(resolve(`${base}/.haywire/farmhand_token`));
+    };
+    if (process.env.FARMHAND_TOKEN_PATH)
+        paths.push(resolve(process.env.FARMHAND_TOKEN_PATH));
+    add(process.env.HAYWIRE_WORKSPACE);
+    add(process.env.CLAUDE_PROJECT_DIR);
+    add(homedir());
+    return paths;
+}
+const TOKEN_PATHS = tokenCandidates();
+const log = (...a) => console.error("[farmhand-proxy]", ...a); // stderr only
+// ---- upstream connection state ----------------------------------------------
+let upstream = null;
+let upstreamTools = [];
+let upstreamResources = [];
+/**
+ * Read the bearer token LAZILY — the file doesn't exist until the studio has
+ * run once. Try each candidate path and return the first non-empty token; also
+ * return which path it came from (for diagnostics).
+ */
+function readTokenFrom() {
+    for (const p of TOKEN_PATHS) {
+        try {
+            const t = readFileSync(p, "utf8").trim();
+            if (t.length > 0)
+                return { token: t, path: p };
+        }
+        catch {
+            /* try the next candidate */
+        }
+    }
+    return null;
+}
+function readToken() {
+    return readTokenFrom()?.token ?? null;
+}
+/** The stdio-facing server Claude Code talks to. Created first, always up. */
+const proxy = new Server({ name: "farmhand-mcp-server", version: "0.1.0" }, { capabilities: { tools: { listChanged: true }, resources: { listChanged: true } } });
+// Sentinel so the model has an affordance while the studio is down.
+const STATUS_TOOL = {
+    name: "farmhand_studio_status",
+    description: "Report whether the Haywire studio (Farmhand MCP server) is reachable. " +
+        "Always available, even when the studio is down.",
+    inputSchema: { type: "object", properties: {} },
+};
+// ---- request handlers: forward to upstream, or answer locally when down ------
+proxy.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: upstream ? upstreamTools : [STATUS_TOOL] };
+});
+proxy.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return { resources: upstream ? upstreamResources : [] };
+});
+proxy.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+    if (!upstream)
+        throw new Error("Haywire studio not running — cannot read resources yet.");
+    return upstream.readResource({ uri: req.params.uri });
+});
+proxy.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    if (name === "farmhand_studio_status") {
+        const up = upstream !== null;
+        const found = readTokenFrom();
+        const text = up
+            ? `Haywire studio reachable at ${UPSTREAM_URL}; ${upstreamTools.length} tools available.`
+            : `Haywire studio not running (no connection to ${UPSTREAM_URL}). ` +
+                (found
+                    ? `Token present (${found.path}).`
+                    : `No token found. Looked in: ${TOKEN_PATHS.join(", ")}.`);
+        return { content: [{ type: "text", text }], structuredContent: { up, url: UPSTREAM_URL } };
+    }
+    if (!upstream) {
+        return {
+            isError: true,
+            content: [
+                { type: "text", text: `Studio not running — cannot call '${name}'. Start it, then retry.` },
+            ],
+        };
+    }
+    // Straight passthrough. Upstream's own errors flow back as-is.
+    return upstream.callTool({ name, arguments: args ?? {} });
+});
+// ---- upstream lifecycle: connect when studio appears, drop when it dies ------
+async function tryConnectUpstream() {
+    if (upstream)
+        return; // already connected
+    const token = readToken();
+    const transport = new StreamableHTTPClientTransport(new URL(UPSTREAM_URL), {
+        requestInit: token ? { headers: { Authorization: `Bearer ${token}` } } : undefined,
+    });
+    const client = new Client({ name: "farmhand-proxy-client", version: "0.1.0" });
+    // Re-emit upstream list_changed across the stdio boundary — the whole point.
+    client.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+        await refreshTools();
+        await proxy.sendToolListChanged();
+    });
+    client.setNotificationHandler(ResourceListChangedNotificationSchema, async () => {
+        await refreshResources();
+        await proxy.sendResourceListChanged();
+    });
+    try {
+        await client.connect(transport);
+    }
+    catch (e) {
+        // Studio still down / token wrong. Stay in "down" mode; poll will retry.
+        await transport.close().catch(() => { });
+        return;
+    }
+    upstream = client;
+    // Fast-path teardown for the streaming case: if the transport carries a
+    // held-open stream, onclose fires the moment it drops. (For a stateless
+    // studio there is no such stream — the poll's liveness probe catches it.)
+    client.onclose = () => {
+        if (upstream !== client)
+            return; // already dropped by the probe
+        log("upstream closed — back to down mode");
+        dropUpstream();
+    };
+    await refreshTools();
+    await refreshResources();
+    log(`connected upstream: ${upstreamTools.length} tools, ${upstreamResources.length} resources`);
+    // Tell Claude Code the real tools are here now — no reconnect needed.
+    await proxy.sendToolListChanged();
+    await proxy.sendResourceListChanged();
+}
+/** Return to down-mode: forget upstream, clear caches, re-emit list_changed. */
+function dropUpstream() {
+    const c = upstream;
+    upstream = null;
+    upstreamTools = [];
+    upstreamResources = [];
+    if (c)
+        void c.close().catch(() => { });
+    void proxy.sendToolListChanged();
+    void proxy.sendResourceListChanged();
+}
+/**
+ * Poll authority for BOTH directions. When down, try to connect. When up,
+ * probe liveness (a cheap listTools) — a stateless HTTP studio has no
+ * held-open stream to trigger onclose, so the probe is what notices it died.
+ */
+async function pollUpstream() {
+    if (!upstream) {
+        await tryConnectUpstream();
+        return;
+    }
+    try {
+        upstreamTools = (await upstream.listTools()).tools;
+    }
+    catch (e) {
+        log("upstream probe failed — back to down mode:", e instanceof Error ? e.message : e);
+        dropUpstream();
+    }
+}
+async function refreshTools() {
+    if (!upstream)
+        return;
+    upstreamTools = (await upstream.listTools()).tools;
+}
+async function refreshResources() {
+    if (!upstream)
+        return;
+    try {
+        upstreamResources = (await upstream.listResources()).resources;
+    }
+    catch {
+        upstreamResources = []; // upstream may not advertise resources
+    }
+}
+// ---- main -------------------------------------------------------------------
+async function main() {
+    await proxy.connect(new StdioServerTransport());
+    log(`up. bridging stdio -> ${UPSTREAM_URL} (poll ${POLL_MS}ms). token candidates: ${TOKEN_PATHS.join(", ")}`);
+    // Poll so tools auto-appear the moment the studio comes up mid-session,
+    // and disappear the moment it dies.
+    const tick = async () => {
+        try {
+            await pollUpstream();
+        }
+        catch (e) {
+            log("poll error:", e instanceof Error ? e.message : e);
+        }
+    };
+    await tick();
+    setInterval(() => void tick(), POLL_MS).unref();
+}
+main().catch((e) => {
+    log("fatal:", e);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@going-haywire/farmhand4claude",
+  "version": "0.1.0",
+  "description": "Farmhand — the AI harness for Haywire. A stdio↔HTTP MCP proxy that bridges Claude Code to a running Haywire studio, so studio tools appear mid-session with no reconnect.",
+  "type": "module",
+  "bin": {
+    "farmhand4claude": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "npm run build && npm run build:test && node dist-test/harness.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "haywire",
+    "farmhand",
+    "proxy"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/going-haywire/farmhand4claude.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2",
+    "zod": "^3.25.76"
+  }
+}