@korso/shepherd 0.1.0

package/README.md

@@ -0,0 +1,203 @@
+# @korso/shepherd — Shepherd MCP Server
+
+Shepherd's stdio MCP server. Gives any MCP-capable agent (Claude Code, Codex, etc.) five advisory coordination tools backed by the shared hub: `join`, `work`, `done`, `announce`, and `sync`.
+
+> **New here?** The [developer quickstart](https://github.com/Korsoai/shepherd/blob/main/docs/shepherd-mcp-quickstart.md) is the fastest path. TL;DR: `npx -y @korso/shepherd` with the env vars below.
+
+---
+
+## CRITICAL: WORKSPACE must match the hub exactly
+
+> **Everyone must set `WORKSPACE` to the identical string, and that string must equal the hub's `ALLOWED_WORKSPACE` env var.**
+
+If `WORKSPACE` does not match, the server's `join` call to the hub returns HTTP 400 immediately. The error is loud on purpose — you will see it in stderr the moment the first tool is called. This is the most common silent onboarding mistake; the guard turns it into a loud, immediate failure.
+
+---
+
+## Install
+
+The server is published to npm and runs via `npx` — no clone or build required
+(Node 18+):
+
+```sh
+npx -y @korso/shepherd
+```
+
+You won't normally run that by hand; you put it in your MCP client config (below)
+with the required env vars. `npx` caches the package, so startup is fast after the
+first fetch, and `@korso/shepherd@latest` picks up updates automatically.
+
+> Hacking on the server itself? See **[Develop from source](#develop-from-source)**
+> at the bottom.
+
+---
+
+## 2. Required environment variables
+
+Every instance of the MCP server needs these eight env vars set in its client config:
+
+| Variable | Description | Example |
+|---|---|---|
+| `HUB_URL` | Base URL of the deployed hub | `https://shepherd.example.com` |
+| `TEAM_TOKEN` | Shared bearer token accepted by the hub | `tok_abc123` |
+| `WORKSPACE` | **Must match hub's `ALLOWED_WORKSPACE` exactly** | `shepherd` |
+| `REPO` | Repository slug (used for scoping claims) | `shepherd` |
+| `BRANCH` | Git branch name | `main` |
+| `HUMAN` | Founder name — identifies you in the presence feed | `daichi` |
+| `PROGRAM` | Agent program name | `claude-code` |
+| `MODEL` | Model ID being used | `claude-sonnet-4-6` |
+
+All eight are required. Missing any one causes an immediate startup failure with a clear error on stderr listing which vars are absent.
+
+---
+
+## 3. MCP client configuration
+
+### Claude Code
+
+> **Do not use `~/.claude/mcp.json` — Claude Code does not read it** (a config
+> there loads silently into nothing). Use `claude mcp add` (user scope, applies
+> everywhere) or a project-root `.mcp.json`. Confirm with `claude mcp list`,
+> which should show `shepherd … ✔ Connected`.
+
+Recommended — register once at user scope (works identically on Windows/macOS/Linux):
+
+```sh
+claude mcp add shepherd -s user \
+  -e HUB_URL=https://shepherd.example.com \
+  -e TEAM_TOKEN=tok_abc123 \
+  -e WORKSPACE=shepherd \
+  -e REPO=shepherd -e BRANCH=main -e HUMAN=daichi \
+  -e PROGRAM=claude-code -e MODEL=claude-sonnet-4-6 \
+  -- npx -y @korso/shepherd
+```
+
+Alternative — a `.mcp.json` at the **root of the repo you're working in**:
+
+```json
+{
+  "mcpServers": {
+    "shepherd": {
+      "command": "npx",
+      "args": ["-y", "@korso/shepherd"],
+      "env": {
+        "HUB_URL": "https://shepherd.example.com",
+        "TEAM_TOKEN": "tok_abc123",
+        "WORKSPACE": "shepherd",
+        "REPO": "shepherd",
+        "BRANCH": "main",
+        "HUMAN": "daichi",
+        "PROGRAM": "claude-code",
+        "MODEL": "claude-sonnet-4-6"
+      }
+    }
+  }
+}
+```
+
+> Windows note: the server is a thin stdio client to the Linux-hosted hub, and
+> `npx` works the same on every OS — no file paths to escape. The hub itself runs
+> on Linux (Postgres), so the Windows-native durability concerns from the spike
+> don't apply to clients.
+
+### Codex (`~/.codex/config.json` or `codex.json`)
+
+Codex uses the same MCP stdio protocol. Add a server entry under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "shepherd": {
+      "command": "npx",
+      "args": ["-y", "@korso/shepherd"],
+      "env": {
+        "HUB_URL": "https://shepherd.example.com",
+        "TEAM_TOKEN": "tok_abc123",
+        "WORKSPACE": "shepherd",
+        "REPO": "shepherd",
+        "BRANCH": "main",
+        "HUMAN": "alex",
+        "PROGRAM": "codex",
+        "MODEL": "o4-mini"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 4. Verify the server starts (quick smoke test)
+
+Run with all env vars set to confirm it connects and idles on stdin:
+
+```sh
+HUB_URL=https://shepherd.example.com \
+TEAM_TOKEN=tok_abc123 \
+WORKSPACE=shepherd \
+REPO=shepherd \
+BRANCH=main \
+HUMAN=daichi \
+PROGRAM=claude-code \
+MODEL=claude-sonnet-4-6 \
+npx -y @korso/shepherd
+```
+
+No stderr output and the process blocking on stdin = healthy. Press Ctrl+C to exit.
+
+**Missing env vars:** if you deliberately omit a var, you will see:
+
+```
+[shepherd] Configuration error — missing or invalid env vars:
+  HUB_URL: HUB_URL is required
+  TEAM_TOKEN: TEAM_TOKEN is required
+  ...
+```
+
+and the process exits 1 immediately. This is by design.
+
+**Wrong WORKSPACE:** the server starts and connects, but the first tool call (`work`, `sync`, etc.) returns a 400 from the hub. Check that your `WORKSPACE` value exactly matches the hub's `ALLOWED_WORKSPACE`.
+
+---
+
+## Develop from source
+
+Only needed if you're changing the MCP server itself. Clone the monorepo and
+point your client at a local build instead of npx:
+
+```sh
+git clone https://github.com/Korsoai/shepherd.git
+cd shepherd
+npm install
+npm run build         # tsc -b — compiles the workspace for dev + tests
+```
+
+For an exact preview of the published artifact (a single self-contained bundle
+with `@shepherd/shared` inlined), build the package directly:
+
+```sh
+npm run build --workspace=@korso/shepherd   # runs tsup → packages/mcp-server/dist/index.js
+```
+
+Then use `node /absolute/path/to/shepherd/packages/mcp-server/dist/index.js` as
+the `command` in your MCP config (Windows: escape backslashes in JSON).
+
+### Publishing a new version
+
+```sh
+# bump "version" in packages/mcp-server/package.json, then:
+npm publish --workspace=@korso/shepherd   # prepublishOnly runs tsup automatically
+```
+
+`publishConfig.access` is `public`, so the scoped package publishes publicly.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `Configuration error — missing or invalid env vars` | One or more of the 8 env vars is absent | Add the missing vars to your client's `env` block |
+| Hub returns 400 on first tool call | `WORKSPACE` mismatch between client and hub | Set `WORKSPACE` to exactly match the hub's `ALLOWED_WORKSPACE` |
+| `npm error 404 … @korso/shepherd` | Package not published yet, or name typo | `npm view @korso/shepherd version` to confirm it's live |
+| Process exits immediately with no error | Rare; check for node version incompatibility | Requires Node 18+ (ESM support) |

package/dist/index.js

@@ -0,0 +1,438 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config.ts
+import { z } from "zod";
+var ConfigSchema = z.object({
+  HUB_URL: z.string().min(1, "HUB_URL is required"),
+  TEAM_TOKEN: z.string().min(1, "TEAM_TOKEN is required"),
+  WORKSPACE: z.string().min(1, "WORKSPACE is required"),
+  REPO: z.string().min(1, "REPO is required"),
+  BRANCH: z.string().min(1, "BRANCH is required"),
+  HUMAN: z.string().min(1, "HUMAN is required"),
+  PROGRAM: z.string().min(1, "PROGRAM is required"),
+  MODEL: z.string().min(1, "MODEL is required")
+});
+function parseConfig(env) {
+  return ConfigSchema.parse({
+    HUB_URL: env["HUB_URL"],
+    TEAM_TOKEN: env["TEAM_TOKEN"],
+    WORKSPACE: env["WORKSPACE"],
+    REPO: env["REPO"],
+    BRANCH: env["BRANCH"],
+    HUMAN: env["HUMAN"],
+    PROGRAM: env["PROGRAM"],
+    MODEL: env["MODEL"]
+  });
+}
+function loadConfig(env = process.env) {
+  try {
+    return parseConfig(env);
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      const messages = err.issues.map((e) => `  ${e.path.join(".")}: ${e.message}`).join("\n");
+      process.stderr.write(`[shepherd] Configuration error \u2014 missing or invalid env vars:
+${messages}
+`);
+    } else {
+      process.stderr.write(`[shepherd] Unexpected configuration error: ${String(err)}
+`);
+    }
+    process.exit(1);
+  }
+}
+
+// src/hubClient.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+var HubUnreachable = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.name = "HubUnreachable";
+    if (cause !== void 0) {
+      this.cause = cause;
+    }
+  }
+};
+var HubRequestError = class extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.name = "HubRequestError";
+    this.status = status;
+  }
+};
+function createHubClient({
+  hubUrl,
+  teamToken,
+  timeoutMs = DEFAULT_TIMEOUT_MS
+}) {
+  const baseUrl = hubUrl.replace(/\/$/, "");
+  return {
+    async post(path, body) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      let response;
+      try {
+        response = await fetch(`${baseUrl}${path}`, {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${teamToken}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(body),
+          signal: controller.signal
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        const message = err instanceof DOMException && err.name === "AbortError" ? `Hub request timed out after ${timeoutMs}ms (${path})` : `Hub unreachable at ${baseUrl}${path}: ${String(err)}`;
+        throw new HubUnreachable(message, err);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (!response.ok) {
+        throw new HubRequestError(
+          response.status,
+          `Hub returned HTTP ${response.status} for ${path}`
+        );
+      }
+      return response.json();
+    }
+  };
+}
+
+// ../shared/dist/contract.js
+import { z as z2 } from "zod";
+var IsoTimestamp = z2.string();
+var DbId = z2.number();
+var Claim = z2.object({
+  workItemId: z2.string().uuid(),
+  agentName: z2.string(),
+  human: z2.string().min(1),
+  intent: z2.string().min(1).max(2048),
+  pathGlobs: z2.array(z2.string().min(1).max(512)).min(1).max(64),
+  // ISO timestamp string; see IsoTimestamp note above
+  expiresAt: IsoTimestamp
+});
+var Announcement = z2.object({
+  // bigint PK serialised as number; see DbId note above
+  id: DbId,
+  fromAgentName: z2.string(),
+  fromHuman: z2.string().min(1),
+  body: z2.string().min(1).max(8192),
+  targetAgentName: z2.string().nullable(),
+  // ISO timestamp string; see IsoTimestamp note above
+  createdAt: IsoTimestamp
+});
+var Landscape = z2.object({
+  conflicts: z2.array(Claim),
+  activeClaims: z2.array(Claim),
+  // The caller's OWN active claims. `activeClaims` deliberately excludes the
+  // caller's session, so without this an agent has no way to confirm its own
+  // claim is live. Optional with a default so an older client talking to a
+  // newer hub (or vice-versa) never fails validation on its absence.
+  yourClaims: z2.array(Claim).default([]),
+  announcements: z2.array(Announcement)
+});
+var JoinRequest = z2.object({
+  workspace: z2.string().min(1),
+  repo: z2.string().min(1),
+  branch: z2.string().min(1),
+  human: z2.string().min(1),
+  program: z2.string().min(1),
+  model: z2.string().min(1)
+});
+var JoinResponse = z2.object({
+  agentName: z2.string(),
+  sessionId: z2.string().uuid()
+});
+var WorkRequest = z2.object({
+  sessionId: z2.string().uuid(),
+  intent: z2.string().min(1).max(2048),
+  pathGlobs: z2.array(z2.string().min(1).max(512)).min(1).max(64),
+  ttlSeconds: z2.number().int().positive().optional()
+});
+var WorkResponse = z2.object({
+  workItemId: z2.string().uuid(),
+  landscape: Landscape
+});
+var DoneRequest = z2.object({
+  sessionId: z2.string().uuid(),
+  workItemId: z2.string().uuid()
+});
+var DoneResponse = z2.object({
+  ok: z2.literal(true)
+});
+var AnnounceRequest = z2.object({
+  sessionId: z2.string().uuid(),
+  body: z2.string().min(1).max(8192),
+  // absent or null => broadcast to all agents in the workspace
+  targetAgentName: z2.string().nullable().optional()
+});
+var AnnounceResponse = z2.object({
+  ok: z2.literal(true),
+  // bigint PK serialised as number; see DbId note above
+  announcementId: DbId
+});
+var SyncRequest = z2.object({
+  sessionId: z2.string().uuid()
+});
+var SyncResponse = z2.object({
+  landscape: Landscape
+});
+var WorkAgentInput = WorkRequest.omit({ sessionId: true });
+var AnnounceAgentInput = AnnounceRequest.omit({ sessionId: true });
+var DoneAgentInput = DoneRequest.omit({ sessionId: true });
+var JoinAgentInput = z2.object({});
+var SyncAgentInput = z2.object({});
+
+// src/tools.ts
+function formatLandscape(landscape) {
+  const lines = [];
+  if (landscape.conflicts.length > 0) {
+    lines.push("CONFLICTS (files overlapping with your claim):");
+    for (const c of landscape.conflicts) {
+      lines.push(
+        `  [${c.agentName} / ${c.human}] "${c.intent}" \u2014 globs: ${c.pathGlobs.join(", ")}`
+      );
+    }
+  } else {
+    lines.push("CONFLICTS: none");
+  }
+  if (landscape.activeClaims.length > 0) {
+    lines.push("ACTIVE CLAIMS (other agents currently working):");
+    for (const c of landscape.activeClaims) {
+      lines.push(
+        `  [${c.agentName} / ${c.human}] "${c.intent}" \u2014 globs: ${c.pathGlobs.join(", ")}`
+      );
+    }
+  } else {
+    lines.push("ACTIVE CLAIMS: none");
+  }
+  const yourClaims = landscape.yourClaims ?? [];
+  if (yourClaims.length > 0) {
+    lines.push("YOUR ACTIVE CLAIMS:");
+    for (const c of yourClaims) {
+      lines.push(
+        `  "${c.intent}" \u2014 globs: ${c.pathGlobs.join(", ")} (workItemId: ${c.workItemId})`
+      );
+    }
+  } else {
+    lines.push("YOUR ACTIVE CLAIMS: none");
+  }
+  if (landscape.announcements.length > 0) {
+    lines.push("ANNOUNCEMENTS:");
+    for (const a of landscape.announcements) {
+      const target = a.targetAgentName ? ` \u2192 ${a.targetAgentName}` : " (broadcast)";
+      lines.push(`  [${a.fromAgentName}${target}] ${a.body}`);
+    }
+  } else {
+    lines.push("ANNOUNCEMENTS: none");
+  }
+  return lines.join("\n");
+}
+function degradedResult(err) {
+  const detail = err instanceof HubUnreachable || err instanceof HubRequestError ? err.message : String(err);
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Coordination hub unreachable \u2014 proceeding uncoordinated. ${detail}`
+      }
+    ]
+  };
+}
+function registerTools(server, deps) {
+  const { hubClient, config } = deps;
+  let sessionId = null;
+  let joinInFlight = null;
+  async function awaitJoin() {
+    if (joinInFlight) await joinInFlight;
+  }
+  server.registerTool(
+    "join",
+    {
+      title: "Join coordination hub",
+      description: "Register yourself with the team coordination hub at the start of a session. Call once before any other coordination tool. Returns your assigned agent name and session ID that the other tools use automatically.",
+      inputSchema: JoinAgentInput.shape
+    },
+    async (_args) => {
+      try {
+        const body = {
+          workspace: config.WORKSPACE,
+          repo: config.REPO,
+          branch: config.BRANCH,
+          human: config.HUMAN,
+          program: config.PROGRAM,
+          model: config.MODEL
+        };
+        const pending = hubClient.post("/join", body);
+        joinInFlight = pending.then((r) => {
+          sessionId = r.sessionId;
+        }).catch(() => {
+        });
+        const result = await pending;
+        sessionId = result.sessionId;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Joined as ${result.agentName}.`
+            }
+          ]
+        };
+      } catch (err) {
+        if (err instanceof HubUnreachable || err instanceof HubRequestError) {
+          return degradedResult(err);
+        }
+        throw err;
+      }
+    }
+  );
+  server.registerTool(
+    "work",
+    {
+      title: "Claim a unit of work",
+      description: "Call this BEFORE you start a unit of work. It atomically checks whether any teammate's agent is already touching the same files and claims the work for you, returning any conflicts and what others are working on. Always call this before editing files.",
+      inputSchema: WorkAgentInput.shape
+    },
+    async (args) => {
+      await awaitJoin();
+      if (sessionId === null) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: "Call join first \u2014 no active session." }]
+        };
+      }
+      try {
+        const body = { sessionId, ...args };
+        const result = await hubClient.post("/work", body);
+        const text = `Work claimed (workItemId: ${result.workItemId})
+
+` + formatLandscape(result.landscape);
+        return { content: [{ type: "text", text }] };
+      } catch (err) {
+        if (err instanceof HubUnreachable || err instanceof HubRequestError) {
+          return degradedResult(err);
+        }
+        throw err;
+      }
+    }
+  );
+  server.registerTool(
+    "done",
+    {
+      title: "Release a work claim",
+      description: "Call when you finish a unit of work to release your claim so teammates know the files are free. Pass the workItemId returned by the work tool.",
+      inputSchema: DoneAgentInput.shape
+    },
+    async (args) => {
+      await awaitJoin();
+      if (sessionId === null) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: "Call join first \u2014 no active session." }]
+        };
+      }
+      try {
+        const body = { sessionId, ...args };
+        await hubClient.post("/done", body);
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Work item released."
+            }
+          ]
+        };
+      } catch (err) {
+        if (err instanceof HubUnreachable || err instanceof HubRequestError) {
+          return degradedResult(err);
+        }
+        throw err;
+      }
+    }
+  );
+  server.registerTool(
+    "announce",
+    {
+      title: "Broadcast a message to teammates",
+      description: "Broadcast a heads-up to the other agents (or hand a specific agent a finding). This is awareness only \u2014 not a task assignment. Omit targetAgentName to broadcast to everyone in the workspace.",
+      inputSchema: AnnounceAgentInput.shape
+    },
+    async (args) => {
+      await awaitJoin();
+      if (sessionId === null) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: "Call join first \u2014 no active session." }]
+        };
+      }
+      try {
+        const body = { sessionId, ...args };
+        const result = await hubClient.post("/announce", body);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Announcement sent (id: ${result.announcementId}).`
+            }
+          ]
+        };
+      } catch (err) {
+        if (err instanceof HubUnreachable || err instanceof HubRequestError) {
+          return degradedResult(err);
+        }
+        throw err;
+      }
+    }
+  );
+  server.registerTool(
+    "sync",
+    {
+      title: "Sync team landscape",
+      description: "Optional periodic pull of the latest team landscape (who's working on what, any messages for you). Also keeps your claims alive. Call this if you want to check for teammate activity without starting new work.",
+      inputSchema: SyncAgentInput.shape
+    },
+    async (_args) => {
+      await awaitJoin();
+      if (sessionId === null) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: "Call join first \u2014 no active session." }]
+        };
+      }
+      try {
+        const body = { sessionId };
+        const result = await hubClient.post("/sync", body);
+        const text = formatLandscape(result.landscape);
+        return { content: [{ type: "text", text }] };
+      } catch (err) {
+        if (err instanceof HubUnreachable || err instanceof HubRequestError) {
+          return degradedResult(err);
+        }
+        throw err;
+      }
+    }
+  );
+}
+
+// src/index.ts
+async function main() {
+  const config = loadConfig();
+  const hubClient = createHubClient({ hubUrl: config.HUB_URL, teamToken: config.TEAM_TOKEN });
+  const server = new McpServer({ name: "shepherd", version: "0.1.0" });
+  registerTools(server, { hubClient, config });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  process.stderr.write(`[shepherd] Fatal boot error: ${String(err)}
+`);
+  if (err instanceof Error && err.stack) {
+    process.stderr.write(err.stack + "\n");
+  }
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@korso/shepherd",
+  "version": "0.1.0",
+  "description": "Shepherd MCP server — gives any MCP-capable agent (Claude Code, Codex, etc.) five advisory cross-session coordination tools (join/work/done/announce/sync) backed by the shared Shepherd hub.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "shepherd-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Korsoai/shepherd.git",
+    "directory": "packages/mcp-server"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "agent",
+    "coordination"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "start": "node dist/index.js",
+    "prepublishOnly": "tsup"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29",
+    "zod": "^3"
+  },
+  "devDependencies": {
+    "@shepherd/shared": "*",
+    "tsup": "^8"
+  }
+}