@korso/shepherd 0.6.1 → 0.6.3

package/README.md

@@ -2,7 +2,7 @@
 
 Shepherd's stdio MCP server. Gives any MCP-capable agent (Claude Code, Codex, etc.) four advisory coordination tools backed by the shared hub: `work`, `done`, `announce`, and `sync`. The agent **joins the workspace automatically** on startup (no `join` tool), and the server ships standing instructions so the agent self-coordinates without the user prompting it.
 
-> **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.
+> **New here?** The [developer quickstart](https://github.com/Korso-AI/shepherd/blob/main/docs/shepherd-mcp-quickstart.md) is the fastest path. TL;DR: `npx -y --package=@korso/shepherd shepherd-mcp` with the env vars below.
 
 ---
 
@@ -20,7 +20,7 @@ The server is published to npm and runs via `npx` — no clone or build required
 (Node 18+):
 
 ```sh
-npx -y @korso/shepherd
+npx -y --package=@korso/shepherd shepherd-mcp
 ```
 
 You won't normally run that by hand; you put it in your MCP client config (below)
@@ -45,14 +45,14 @@ Missing either causes an immediate startup failure with a clear error on stderr
 listing which vars are absent. (No other var triggers this.)
 
 **Everything else is optional** — each identity field is resolved at startup as
-**env var → git detection → fallback**, so a plain `npx -y @korso/shepherd` with
+**env var → git detection → fallback**, so a plain `npx -y --package=@korso/shepherd shepherd-mcp` with
 just the two required vars produces a valid, fully-identified session. Set an
 override only to replace what's detected:
 
 | Variable | If omitted | Example |
 |---|---|---|
 | `WORKSPACE` | defaults to `default` (**must match hub's `ALLOWED_WORKSPACE` if overridden**) | `shepherd` |
-| `REPO` | `git remote origin` → `owner/repo`, else repo folder name, else `unknown-repo` | `Korsoai/shepherd` |
+| `REPO` | `git remote origin` → `owner/repo`, else repo folder name, else `unknown-repo` | `Korso-AI/shepherd` |
 | `BRANCH` | `git rev-parse --abbrev-ref HEAD`, else `HEAD` | `main` |
 | `BASE_BRANCH` | `origin/HEAD`, else `origin/main` / `origin/master` (used for the change-awareness heads-up) | `origin/main` |
 | `HUMAN` | git `user.name`, else local-part of `user.email`, else this device's **cached** last-detected name, else a generated name | `daichi` |
@@ -110,7 +110,7 @@ uses (override both with `SHEPHERD_INBOX_DIR` if you relocated it):
   "mcpServers": {
     "shepherd": {
       "command": "npx",
-      "args": ["-y", "@korso/shepherd"],
+      "args": ["-y", "--package=@korso/shepherd", "shepherd-mcp"],
       "env": {
         "HUB_URL": "https://shepherd.example.com",
         "TEAM_TOKEN": "tok_abc123"
@@ -122,7 +122,7 @@ uses (override both with `SHEPHERD_INBOX_DIR` if you relocated it):
       {
         "matcher": "*",
         "hooks": [
-          { "type": "command", "command": "npx -y -p @korso/shepherd shepherd-inbox-hook" }
+          { "type": "command", "command": "npx -y --package=@korso/shepherd shepherd-inbox-hook" }
         ]
       }
     ]
@@ -143,9 +143,9 @@ or MCP calls. Hooks must be enabled with `features.hooks = true`. In
 hooks = true
 
 [[hooks.UserPromptSubmit]]
-command = ["npx", "-y", "-p", "@korso/shepherd", "shepherd-inbox-hook"]
+command = ["npx", "-y", "--package=@korso/shepherd", "shepherd-inbox-hook"]
 # On Windows use command_windows instead:
-# command_windows = ["cmd", "/c", "npx -y -p @korso/shepherd shepherd-inbox-hook"]
+# command_windows = ["cmd", "/c", "npx -y --package=@korso/shepherd shepherd-inbox-hook"]
 ```
 
 ### Pi — extension
@@ -191,7 +191,7 @@ line-continuation does not work). Minimal: just the two required vars (identity
 is auto-detected from git):
 
 ```powershell
-claude mcp add shepherd -s user -e HUB_URL=https://shepherd.example.com -e TEAM_TOKEN=tok_abc123 -- npx -y @korso/shepherd
+claude mcp add shepherd -s user -e HUB_URL=https://shepherd.example.com -e TEAM_TOKEN=tok_abc123 -- npx -y --package=@korso/shepherd shepherd-mcp
 ```
 
 Add any optional overrides from §2 with extra `-e` flags (e.g. `-e MODEL=claude-sonnet-4-6 -e HUMAN=daichi`).
@@ -204,7 +204,7 @@ Alternative — a `.mcp.json` at the **root of the repo you're working in**
   "mcpServers": {
     "shepherd": {
       "command": "npx",
-      "args": ["-y", "@korso/shepherd"],
+      "args": ["-y", "--package=@korso/shepherd", "shepherd-mcp"],
       "env": {
         "HUB_URL": "https://shepherd.example.com",
         "TEAM_TOKEN": "tok_abc123",
@@ -228,7 +228,7 @@ The table is `mcp_servers` with an **underscore** (`mcp-servers`/`mcpServers` ar
 silently ignored). Either run `codex mcp add`:
 
 ```sh
-codex mcp add shepherd --env HUB_URL=https://shepherd.example.com --env TEAM_TOKEN=tok_abc123 --env PROGRAM=codex -- npx -y @korso/shepherd
+codex mcp add shepherd --env HUB_URL=https://shepherd.example.com --env TEAM_TOKEN=tok_abc123 --env PROGRAM=codex -- npx -y --package=@korso/shepherd shepherd-mcp
 ```
 
 …or add the table directly:
@@ -236,7 +236,7 @@ codex mcp add shepherd --env HUB_URL=https://shepherd.example.com --env TEAM_TOK
 ```toml
 [mcp_servers.shepherd]
 command = "npx"
-args = ["-y", "@korso/shepherd"]
+args = ["-y", "--package=@korso/shepherd", "shepherd-mcp"]
 env = { HUB_URL = "https://shepherd.example.com", TEAM_TOKEN = "tok_abc123", PROGRAM = "codex", MODEL = "o4-mini" }
 ```
 
@@ -249,7 +249,7 @@ Pi uses a JSON `mcpServers` block (project config overrides global):
   "mcpServers": {
     "shepherd": {
       "command": "npx",
-      "args": ["-y", "@korso/shepherd"],
+      "args": ["-y", "--package=@korso/shepherd", "shepherd-mcp"],
       "env": {
         "HUB_URL": "https://shepherd.example.com",
         "TEAM_TOKEN": "tok_abc123",
@@ -260,6 +260,32 @@ Pi uses a JSON `mcpServers` block (project config overrides global):
 }
 ```
 
+### Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`)
+
+Cursor reads the same JSON `mcpServers` shape — global at `~/.cursor/mcp.json`,
+or per-project at `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "shepherd": {
+      "command": "npx",
+      "args": ["-y", "--package=@korso/shepherd", "shepherd-mcp"],
+      "env": {
+        "HUB_URL": "https://shepherd.example.com",
+        "TEAM_TOKEN": "tok_abc123",
+        "PROGRAM": "cursor"
+      }
+    }
+  }
+}
+```
+
+Confirm under **Settings → MCP** that `shepherd` is listed with its tools.
+Announcement push: Cursor has no hook equivalent (see the hooks above for
+Claude Code/Codex/Pi), so announcements arrive via the universal drainer — on
+the agent's next Shepherd tool call — rather than pushed between calls.
+
 ---
 
 ## 4. Verify the server starts (quick smoke test)
@@ -270,10 +296,10 @@ PowerShell (set env vars, then run):
 ```powershell
 $env:HUB_URL = "https://shepherd.example.com"
 $env:TEAM_TOKEN = "tok_abc123"
-npx -y @korso/shepherd
+npx -y --package=@korso/shepherd shepherd-mcp
 ```
 
-bash/zsh: `HUB_URL=https://shepherd.example.com TEAM_TOKEN=tok_abc123 npx -y @korso/shepherd`
+bash/zsh: `HUB_URL=https://shepherd.example.com TEAM_TOKEN=tok_abc123 npx -y --package=@korso/shepherd shepherd-mcp`
 
 No stderr output and the process blocking on stdin = healthy. Press Ctrl+C to exit.
 
@@ -298,7 +324,7 @@ 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
+git clone https://github.com/Korso-AI/shepherd.git
 cd shepherd
 npm install
 npm run build         # tsc -b — compiles the workspace for dev + tests

package/dist/index.js

@@ -537,6 +537,9 @@ var CreateWorkspaceRequest = z2.object({
 var ListWorkspacesResponse = z2.object({
   workspaces: z2.array(WorkspaceSummary)
 });
+var DeleteWorkspaceResponse = z2.object({
+  deleted: z2.literal(true)
+});
 var MintTokenRequest = z2.object({
   name: z2.string().min(1).optional()
 });

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@korso/shepherd",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Shepherd MCP server — gives any MCP-capable agent (Claude Code, Codex, etc.) four advisory cross-session coordination tools (work/done/announce/sync) backed by the shared Shepherd hub. Joins the workspace automatically and ships standing instructions so the agent self-coordinates.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
+    "shepherd": "dist/index.js",
     "shepherd-mcp": "dist/index.js",
     "shepherd-inbox-hook": "dist/inboxHook.js"
   },