clawborrator-mcp 0.0.30 → 0.0.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +25 -20
  2. package/package.json +2 -3
package/README.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # clawborrator-mcp (channel_v1)
2
2
 
3
3
  MCP server that connects each running Claude Code instance to a
4
- [`hub_v1`](https://github.com/clawborrator/hub_v1) over WebSocket.
5
- Designed to be invoked by Claude Code via `.mcp.json`; runs as both
6
- a long-lived stdio MCP server AND a short-lived hook spawn (selected
7
- by the `--hook=<HookName>` CLI flag).
4
+ clawborrator [`hub`](https://github.com/clawborrator/hub_v1) over
5
+ WebSocket. Designed to be invoked by Claude Code via `.mcp.json`;
6
+ runs as both a long-lived stdio MCP server AND a short-lived hook
7
+ spawn (selected by the `--hook=<HookName>` CLI flag).
8
8
 
9
9
  Published as [`clawborrator-mcp`](https://www.npmjs.com/package/clawborrator-mcp)
10
10
  on npm.
@@ -40,12 +40,18 @@ Set in your project's `.mcp.json`:
40
40
  | `CLAWBORRATOR_REUSE_SESSION_ID` | no | Opt-in: reconnect rebinds to a known session id rather than creating a fresh one |
41
41
  | `CLAWBORRATOR_LOG_LEVEL` | no | `debug`, `info`, `warn`, `error`; default `info` |
42
42
 
43
- Get the snippet pre-filled with the right URL + token via:
43
+ Get the snippet pre-filled with the right URL + token via the
44
+ [`clawborrator-cli`](https://www.npmjs.com/package/clawborrator-cli):
44
45
 
45
46
  ```bash
46
- claw token mint --kind=channel --name=mbp --mcp-snippet
47
+ npx clawborrator-cli token mint --kind=channel --name=mbp --mcp-snippet --out .mcp.json
47
48
  ```
48
49
 
50
+ If you're running the [desktop daemon](https://github.com/clawborrator/desktop_v1)
51
+ (`clawborrator-supervisor`), it mints channel tokens server-side
52
+ when it spawns managed Claude Code sessions for you — the `.mcp.json`
53
+ ends up in the spawned project automatically.
54
+
49
55
  ---
50
56
 
51
57
  ## What it does
@@ -68,7 +74,9 @@ claw token mint --kind=channel --name=mbp --mcp-snippet
68
74
  5. Echoes stdin to stdout so Claude's hook chain stays intact.
69
75
  6. Exits cleanly even if the hub is unreachable — never breaks the operator's actual Claude flow.
70
76
 
71
- Hooks are installed with `claw session init` from inside a project — see hub_v1 README.
77
+ Hooks are auto-installed on first MCP startup: `clawborrator-mcp` reconciles
78
+ `.claude/settings.json` to add (or refresh) the entries that point at
79
+ `dist-hook/clawborrator-tail.mjs`. No separate install step.
72
80
 
73
81
  ---
74
82
 
@@ -117,7 +125,8 @@ for the dispatcher-pattern setup.
117
125
  ## Hook coverage
118
126
 
119
127
  Maps each Claude Code hook to a hub event. The hook script is
120
- `dist-hook/clawborrator-tail.mjs`; install via `claw session init`.
128
+ `dist-hook/clawborrator-tail.mjs`; auto-installed on first MCP
129
+ startup (no separate install step).
121
130
 
122
131
  | Hook | Hub event | Notes |
123
132
  |---|---|---|
@@ -127,27 +136,23 @@ Maps each Claude Code hook to a hub event. The hook script is
127
136
  | `PostToolUseFailure` | `tail/PostToolUseFailure` | |
128
137
  | `Stop` | `tail/Stop` (+ `chat/reply` if assistant_text present) | Turn-end signal. |
129
138
  | `Notification` | `tail/Notification` | CC user notifications (idle / permission). |
130
- | `SessionStart` / `SessionEnd` | `tail/SessionStart` / `tail/SessionEnd` | |
131
139
  | `TaskCreated` / `TaskCompleted` | `tail/TaskCreated` / `tail/TaskCompleted` | Carries `task_id`, `task_subject`, `task_description`. |
132
140
  | `SubagentStart` / `SubagentStop` | `tail/SubagentStart` / `tail/SubagentStop` | SubagentStop carries `last_assistant_message` recap. |
133
141
 
142
+ `SessionStart` / `SessionEnd` are intentionally **not** hooked by
143
+ this MCP. The hook spawn had a fundamental race — the sidecar
144
+ isn't written yet at SessionStart, and is already gone by SessionEnd
145
+ — so lifecycle is now emitted server-side from the `/channel` WS
146
+ welcome / close transitions (`hub_v1/server/src/ws/channel.ts`).
147
+ Hub-authoritative, captures actual channel liveness, no hook timing
148
+ involved.
149
+
134
150
  The tail reads the CC transcript file directly to enrich `PreToolUse`
135
151
  with the assistant's pre-reply text (which CC doesn't put on the
136
152
  hook payload directly). See `transcript.ts` for the walker.
137
153
 
138
154
  ---
139
155
 
140
- ## Phases (all shipped)
141
-
142
- - **Phase A** ✓ — connect / register / heartbeat / reconnect
143
- - **Phase B** ✓ — hooks + event forwarding via sidecar
144
- - **Phase C** ✓ — bidirectional permission relay (channel → hub → operator → back)
145
- - **Phase D** ✓ — MCP tools (above)
146
- - **Phase E** ✓ — public-agent dispatch (`dispatch_to_agent`, `list_agents`); 15-min timeouts; cyclomatic-complexity refactor
147
- - **Phase F** ✓ — streaming `reply_chunk` (incremental output), `read_file` / `download_to_path` for cross-session file exchange
148
-
149
- ---
150
-
151
156
  ## Local dev (linked to a sibling hub_v1 checkout)
152
157
 
153
158
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "clawborrator-mcp",
3
- "version": "0.0.30",
3
+ "version": "0.0.32",
4
4
  "type": "module",
5
5
  "description": "clawborrator channel for hub_v1 — MCP server that connects Claude Code to a hub over WebSocket, with hooks for activity capture and tools for cross-session routing.",
6
6
  "license": "MIT",
@@ -19,8 +19,7 @@
19
19
  "websocket",
20
20
  "remote",
21
21
  "ai",
22
- "agent",
23
- "hub-v1"
22
+ "agent"
24
23
  ],
25
24
  "main": "dist/index.js",
26
25
  "bin": {