@essentialai/cc-bridge-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 cc-bridge-mcp-server contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,289 @@
+# @essentialai/cc-bridge-mcp-server
+
+Claude Code Bridge from Essential AI Solutions (essentialai.uk) — MCP server for inter-Claude-Code session communication.
+
+## Quick Start
+
+**Step 1:** Add `.mcp.json` to **both** project repositories:
+
+```json
+{
+  "mcpServers": {
+    "cc-bridge": {
+      "command": "npx",
+      "args": ["-y", "@essentialai/cc-bridge-mcp-server"],
+      "env": {}
+    }
+  }
+}
+```
+
+Or use the CLI:
+
+```bash
+claude mcp add --transport stdio cc-bridge -- npx -y @essentialai/cc-bridge-mcp-server
+```
+
+**Step 2:** Restart Claude Code in both repos. The bridge tools are now available.
+
+## What It Does
+
+Two Claude Code instances -- one working on a backend repo, another on a frontend repo -- need to negotiate testing scenarios and debug collaboratively in real-time without mixing their accumulated project context.
+
+```
+CC_Backend                                CC_Frontend
+    |                                         |
+    +-- .mcp.json --> @essentialai/cc-bridge-mcp-server    |
+    |                    |                    |
+    |                    +-- ~/cloud_code_bridge/cc-bridge-state.json
+    |                    |                    |
+    |                    |   <-- .mcp.json ---+
+    |                                         |
+    +-- claude --resume <sessionId> -p "msg" -+
+```
+
+Each CC instance spawns its own MCP server process via stdio transport. Shared state is persisted to `~/cloud_code_bridge/cc-bridge-state.json` with file locking so both processes see the same peer registry and message history.
+
+Messages are relayed by calling `claude --resume <sessionId> -p "message"` as a subprocess. File locking uses `fs.writeFile` with `flag: "wx"` (O_CREAT | O_EXCL), stale lock detection via `process.kill(pid, 0)`, and atomic writes via temp-file-then-rename.
+
+## Tools Reference
+
+The server exposes six tools, all prefixed with `cc_`:
+
+### cc_register_peer
+
+Register a Claude Code session as a named peer on the bridge.
+
+| Parameter   | Type   | Required | Description                                                  |
+|-------------|--------|----------|--------------------------------------------------------------|
+| `peerId`    | string | yes      | Unique identifier, e.g. `"backend"` or `"frontend"`          |
+| `sessionId` | string | yes      | Claude Code session ID (used with `--resume`)                |
+| `cwd`       | string | yes      | Absolute path to the project working directory               |
+| `label`     | string | yes      | Human-readable label, e.g. `"CC_Backend"` or `"CC_Frontend"` |
+
+### cc_deregister_peer
+
+Remove a previously registered peer from the bridge.
+
+| Parameter | Type   | Required | Description                           |
+|-----------|--------|----------|---------------------------------------|
+| `peerId`  | string | yes      | Peer ID to deregister, e.g. `"backend"` |
+
+### cc_send_message
+
+Send a message from one registered peer to another. The message is relayed by resuming the target's Claude Code session via CLI subprocess. Returns the target's response.
+
+| Parameter    | Type   | Required | Description                                |
+|--------------|--------|----------|--------------------------------------------|
+| `fromPeerId` | string | yes      | Peer ID of the sender, e.g. `"backend"`    |
+| `toPeerId`   | string | yes      | Peer ID of the recipient, e.g. `"frontend"` |
+| `message`    | string | yes      | The message content to send                |
+
+### cc_list_peers
+
+List all currently registered peers. Returns peer IDs, session IDs, working directories, labels, and a `potentiallyStale` flag for peers idle beyond the configured timeout. No parameters.
+
+### cc_get_history
+
+Retrieve the message history for the bridge. Returns messages in chronological order, most recent last.
+
+| Parameter | Type   | Required | Description                                    |
+|-----------|--------|----------|------------------------------------------------|
+| `peerId`  | string | no       | Filter history to messages involving this peer  |
+| `limit`   | number | no       | Maximum number of messages to return (default 50) |
+
+### cc_health_check
+
+Diagnose the bridge's operational status. No parameters required.
+
+**Checks performed:**
+
+- **State file** -- Can the state directory be read and written?
+- **Lock mechanism** -- Can file locks be acquired and released?
+- **Claude CLI** -- Is the `claude` binary available and responsive?
+
+**Response fields:**
+
+| Field           | Type    | Description                             |
+|-----------------|---------|-----------------------------------------|
+| `healthy`       | boolean | All checks passed                       |
+| `serverVersion` | string  | Current server version                  |
+| `statePath`     | string  | Path to state file                      |
+| `claudePath`    | string  | Path to Claude CLI                      |
+| `checks`        | object  | Per-check pass/fail with detail messages |
+| `timestamp`     | string  | ISO timestamp of the check              |
+
+## Configuration
+
+All settings are configured via environment variables with sensible defaults:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CC_BRIDGE_STATE_PATH` | `~/cloud_code_bridge` | Directory for state file and logs |
+| `CC_BRIDGE_TIMEOUT_MS` | `120000` (2 min) | CLI subprocess timeout in milliseconds |
+| `CC_BRIDGE_CHAR_LIMIT` | `0` (unlimited) | Max characters in relayed message (0 = no limit) |
+| `CC_BRIDGE_LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, `error` |
+| `CC_BRIDGE_CLAUDE_PATH` | `claude` | Path to the Claude Code CLI executable |
+| `CC_BRIDGE_STALE_TIMEOUT_MS` | `1800000` (30 min) | Idle time before peer is flagged stale (0 = disabled) |
+
+To override defaults, set environment variables in your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cc-bridge": {
+      "command": "npx",
+      "args": ["-y", "@essentialai/cc-bridge-mcp-server"],
+      "env": {
+        "CC_BRIDGE_STATE_PATH": "/custom/path",
+        "CC_BRIDGE_LOG_LEVEL": "debug"
+      }
+    }
+  }
+}
+```
+
+## Usage Workflow
+
+1. Start two Claude Code sessions, one per repo. Note each session ID.
+
+2. In CC_Backend, register both peers:
+
+   ```
+   Use cc_register_peer:
+     peerId: "backend", sessionId: "<backend-session-id>",
+     cwd: "/path/to/backend", label: "CC_Backend"
+
+   Use cc_register_peer:
+     peerId: "frontend", sessionId: "<frontend-session-id>",
+     cwd: "/path/to/frontend", label: "CC_Frontend"
+   ```
+
+3. Send a message from backend to frontend:
+
+   ```
+   Use cc_send_message:
+     fromPeerId: "backend", toPeerId: "frontend",
+     message: "What endpoint does the login form POST to?"
+   ```
+
+4. The bridge resumes the frontend CC session, delivers the message, and returns the response.
+
+5. Check message history at any time:
+
+   ```
+   Use cc_get_history to see all exchanges, or filter by peerId.
+   ```
+
+6. When done, deregister peers:
+
+   ```
+   Use cc_deregister_peer:
+     peerId: "backend"
+   ```
+
+## Troubleshooting
+
+### NVM/PATH: "npx not found" or server fails to start
+
+MCP servers are spawned as subprocesses and may not inherit your NVM configuration.
+
+**Option 1: Use absolute path to npx**
+
+Find your npx path with `which npx` (e.g., `/Users/you/.nvm/versions/node/v22.11.0/bin/npx`), then update `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cc-bridge": {
+      "command": "/Users/you/.nvm/versions/node/v22.11.0/bin/npx",
+      "args": ["-y", "@essentialai/cc-bridge-mcp-server"]
+    }
+  }
+}
+```
+
+**Option 2: Use `claude mcp add` (handles PATH automatically)**
+
+```bash
+claude mcp add --transport stdio cc-bridge -- npx -y @essentialai/cc-bridge-mcp-server
+```
+
+**Option 3: Ensure NVM loads in non-interactive shells**
+
+Add to `~/.zshrc` or `~/.bashrc`:
+
+```bash
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+```
+
+### State file location
+
+The bridge stores state at `~/cloud_code_bridge/cc-bridge-state.json` by default.
+
+- Override with: `CC_BRIDGE_STATE_PATH=/your/path`
+- Logs are stored at: `<state-path>/logs/`
+- First-run config is persisted to `~/.cc-bridge-config.json`
+
+### Common errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `CLI_NOT_FOUND` | `claude` not on PATH | Install Claude Code or set `CC_BRIDGE_CLAUDE_PATH` |
+| `CLI_TIMEOUT` | Response took > 2 min | Increase `CC_BRIDGE_TIMEOUT_MS` |
+| `LOCK_TIMEOUT` | Lock held by dead process | Delete `<state-path>/cc-bridge-state.json.lock` |
+| `STATE_CORRUPT` | Invalid JSON in state | Auto-recovers; backup saved as `.corrupt.<timestamp>` |
+| `PEER_NOT_FOUND` | Target peer not registered | Register both peers before sending messages |
+
+## Development
+
+Build from source:
+
+```bash
+git clone https://github.com/eaisdevelopment/cc-bridge-mcp-server.git
+cd cc-bridge-mcp-server
+npm install
+npm run build
+npm test
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts                 # Server entry point, registers tools, starts stdio transport
+├── config.ts                # Environment variable loading and validation (zod)
+├── constants.ts             # Server name and version from package.json
+├── errors.ts                # BridgeError class and error code enum
+├── logger.ts                # Timestamped file + stderr logger
+├── startup.ts               # First-run prompt, config loading, CLI validation
+├── types.ts                 # Core interfaces (PeerInfo, MessageRecord, etc.)
+├── services/
+│   ├── cc-cli.ts            # CLI subprocess wrapper (execFile with claude --resume)
+│   ├── health-check.ts      # State file, lock, and CLI diagnostic checks
+│   └── peer-registry.ts     # File-based shared state with locking
+└── tools/
+    ├── register-peer.ts     # cc_register_peer
+    ├── deregister-peer.ts   # cc_deregister_peer
+    ├── send-message.ts      # cc_send_message
+    ├── list-peers.ts        # cc_list_peers
+    ├── get-history.ts       # cc_get_history
+    └── health-check.ts      # cc_health_check
+```
+
+### npm Scripts
+
+| Script | Command | Description |
+|--------|---------|-------------|
+| `npm run build` | `tsc` | Compile TypeScript to `dist/` |
+| `npm run dev` | `tsx watch src/index.ts` | Development mode with auto-reload |
+| `npm start` | `node dist/index.js` | Run compiled server |
+| `npm run clean` | `rm -rf dist` | Remove build artifacts |
+| `npm test` | `vitest run` | Run test suite |
+| `npm run test:watch` | `vitest` | Run tests in watch mode |
+| `npm run test:coverage` | `vitest run --coverage` | Run tests with coverage report |
+
+## License
+
+ISC

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function runCli(): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAU5C"}

package/dist/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+export async function runCli() {
+    const command = process.argv[2];
+    if (command === "init") {
+        const { runWizard } = await import("./wizard/index.js");
+        await runWizard();
+    }
+    else {
+        // Default: start MCP server (existing behavior)
+        await import("./index.js");
+    }
+}
+runCli().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`Fatal error: ${msg}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,MAAM,CAAC,KAAK,UAAU,MAAM;IAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAEhC,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;QACxD,MAAM,SAAS,EAAE,CAAC;IACpB,CAAC;SAAM,CAAC;QACN,gDAAgD;QAChD,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC9B,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export declare const configSchema: z.ZodObject<{
+    CC_BRIDGE_STATE_PATH: z.ZodDefault<z.ZodString>;
+    CC_BRIDGE_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
+    CC_BRIDGE_CHAR_LIMIT: z.ZodDefault<z.ZodNumber>;
+    CC_BRIDGE_LOG_LEVEL: z.ZodDefault<z.ZodEnum<["debug", "info", "warn", "error"]>>;
+    CC_BRIDGE_CLAUDE_PATH: z.ZodDefault<z.ZodString>;
+    CC_BRIDGE_STALE_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    CC_BRIDGE_STATE_PATH: string;
+    CC_BRIDGE_TIMEOUT_MS: number;
+    CC_BRIDGE_CHAR_LIMIT: number;
+    CC_BRIDGE_LOG_LEVEL: "info" | "debug" | "warn" | "error";
+    CC_BRIDGE_CLAUDE_PATH: string;
+    CC_BRIDGE_STALE_TIMEOUT_MS: number;
+}, {
+    CC_BRIDGE_STATE_PATH?: string | undefined;
+    CC_BRIDGE_TIMEOUT_MS?: number | undefined;
+    CC_BRIDGE_CHAR_LIMIT?: number | undefined;
+    CC_BRIDGE_LOG_LEVEL?: "info" | "debug" | "warn" | "error" | undefined;
+    CC_BRIDGE_CLAUDE_PATH?: string | undefined;
+    CC_BRIDGE_STALE_TIMEOUT_MS?: number | undefined;
+}>;
+export type Config = z.infer<typeof configSchema>;
+export declare function loadConfig(env?: Record<string, string | undefined>): Config;
+export declare function getConfig(): Config;
+export declare function resetConfig(): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;EASvB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAIlD,wBAAgB,UAAU,CACxB,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,MAAM,CAUR;AAED,wBAAgB,SAAS,IAAI,MAAM,CAGlC;AAED,wBAAgB,WAAW,IAAI,IAAI,CAElC"}

package/dist/config.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import os from "node:os";
+import path from "node:path";
+const defaultStatePath = path.join(os.homedir(), "cloud_code_bridge");
+export const configSchema = z.object({
+    CC_BRIDGE_STATE_PATH: z.string().default(defaultStatePath),
+    CC_BRIDGE_TIMEOUT_MS: z.coerce.number().int().min(1000).default(120_000),
+    CC_BRIDGE_CHAR_LIMIT: z.coerce.number().int().min(0).default(0),
+    CC_BRIDGE_LOG_LEVEL: z
+        .enum(["debug", "info", "warn", "error"])
+        .default("info"),
+    CC_BRIDGE_CLAUDE_PATH: z.string().default("claude"),
+    CC_BRIDGE_STALE_TIMEOUT_MS: z.coerce.number().int().min(0).default(1_800_000),
+});
+let _config = null;
+export function loadConfig(env = process.env) {
+    const result = configSchema.safeParse(env);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  ${i.path.join(".")}: ${i.message}`)
+            .join("\n");
+        throw new Error(`Invalid configuration:\n${issues}`);
+    }
+    _config = Object.freeze(result.data);
+    return _config;
+}
+export function getConfig() {
+    if (!_config)
+        throw new Error("Config not loaded. Call loadConfig() first.");
+    return _config;
+}
+export function resetConfig() {
+    _config = null;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,mBAAmB,CAAC,CAAC;AAEtE,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,gBAAgB,CAAC;IAC1D,oBAAoB,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxE,oBAAoB,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/D,mBAAmB,EAAE,CAAC;SACnB,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;SACxC,OAAO,CAAC,MAAM,CAAC;IAClB,qBAAqB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC;IACnD,0BAA0B,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;CAC9E,CAAC,CAAC;AAIH,IAAI,OAAO,GAAkB,IAAI,CAAC;AAElC,MAAM,UAAU,UAAU,CACxB,MAA0C,OAAO,CAAC,GAAG;IAErD,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACjD,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACrC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAC7E,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,GAAG,IAAI,CAAC;AACjB,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const SERVER_NAME = "Claude Code Bridge from Essential AI Solutions (essentialai.uk)";
+export declare const SERVER_VERSION: string;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,WAAW,oEAAoE,CAAC;AAC7F,eAAO,MAAM,cAAc,QAAc,CAAC"}

package/dist/constants.js

@@ -0,0 +1,6 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+export const SERVER_NAME = "Claude Code Bridge from Essential AI Solutions (essentialai.uk)";
+export const SERVER_VERSION = pkg.version;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAE9D,MAAM,CAAC,MAAM,WAAW,GAAG,iEAAiE,CAAC;AAC7F,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC,OAAO,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+export declare enum BridgeErrorCode {
+    CLI_NOT_FOUND = "CLI_NOT_FOUND",
+    CLI_TIMEOUT = "CLI_TIMEOUT",
+    CLI_EXEC_FAILED = "CLI_EXEC_FAILED",
+    STATE_CORRUPT = "STATE_CORRUPT",
+    STATE_WRITE_FAILED = "STATE_WRITE_FAILED",
+    LOCK_TIMEOUT = "LOCK_TIMEOUT",
+    LOCK_STALE = "LOCK_STALE",
+    PEER_NOT_FOUND = "PEER_NOT_FOUND",
+    INVALID_INPUT = "INVALID_INPUT",
+    STARTUP_FAILED = "STARTUP_FAILED",
+    DIR_NOT_WRITABLE = "DIR_NOT_WRITABLE"
+}
+export declare class BridgeError extends Error {
+    readonly code: BridgeErrorCode;
+    readonly suggestion?: string;
+    constructor(code: BridgeErrorCode, message: string, suggestion?: string);
+}
+export declare function toolResult(text: string, isError?: boolean): {
+    isError?: true | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function errorResult(error: unknown): {
+    isError?: true | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function successResult(data: Record<string, unknown>): {
+    isError?: true | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oBAAY,eAAe;IACzB,aAAa,kBAAkB;IAC/B,WAAW,gBAAgB;IAC3B,eAAe,oBAAoB;IACnC,aAAa,kBAAkB;IAC/B,kBAAkB,uBAAuB;IACzC,YAAY,iBAAiB;IAC7B,UAAU,eAAe;IACzB,cAAc,mBAAmB;IACjC,aAAa,kBAAkB;IAC/B,cAAc,mBAAmB;IACjC,gBAAgB,qBAAqB;CACtC;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAgB,IAAI,EAAE,eAAe,CAAC;IACtC,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;gBAExB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CASxE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;;;;;;EAKzD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO;;;;;;EA8BzC;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;EAE1D"}

package/dist/errors.js

@@ -0,0 +1,53 @@
+export var BridgeErrorCode;
+(function (BridgeErrorCode) {
+    BridgeErrorCode["CLI_NOT_FOUND"] = "CLI_NOT_FOUND";
+    BridgeErrorCode["CLI_TIMEOUT"] = "CLI_TIMEOUT";
+    BridgeErrorCode["CLI_EXEC_FAILED"] = "CLI_EXEC_FAILED";
+    BridgeErrorCode["STATE_CORRUPT"] = "STATE_CORRUPT";
+    BridgeErrorCode["STATE_WRITE_FAILED"] = "STATE_WRITE_FAILED";
+    BridgeErrorCode["LOCK_TIMEOUT"] = "LOCK_TIMEOUT";
+    BridgeErrorCode["LOCK_STALE"] = "LOCK_STALE";
+    BridgeErrorCode["PEER_NOT_FOUND"] = "PEER_NOT_FOUND";
+    BridgeErrorCode["INVALID_INPUT"] = "INVALID_INPUT";
+    BridgeErrorCode["STARTUP_FAILED"] = "STARTUP_FAILED";
+    BridgeErrorCode["DIR_NOT_WRITABLE"] = "DIR_NOT_WRITABLE";
+})(BridgeErrorCode || (BridgeErrorCode = {}));
+export class BridgeError extends Error {
+    code;
+    suggestion;
+    constructor(code, message, suggestion) {
+        const fullMessage = suggestion
+            ? `${code}: ${message}. ${suggestion}`
+            : `${code}: ${message}`;
+        super(fullMessage);
+        this.name = "BridgeError";
+        this.code = code;
+        this.suggestion = suggestion;
+    }
+}
+export function toolResult(text, isError) {
+    return {
+        content: [{ type: "text", text }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+export function errorResult(error) {
+    if (error instanceof BridgeError) {
+        return toolResult(JSON.stringify({
+            success: false,
+            error: error.code,
+            message: error.message,
+            suggestion: error.suggestion,
+        }, null, 2), true);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return toolResult(JSON.stringify({
+        success: false,
+        error: "INTERNAL_ERROR",
+        message,
+    }, null, 2), true);
+}
+export function successResult(data) {
+    return toolResult(JSON.stringify(data, null, 2), false);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,CAAN,IAAY,eAYX;AAZD,WAAY,eAAe;IACzB,kDAA+B,CAAA;IAC/B,8CAA2B,CAAA;IAC3B,sDAAmC,CAAA;IACnC,kDAA+B,CAAA;IAC/B,4DAAyC,CAAA;IACzC,gDAA6B,CAAA;IAC7B,4CAAyB,CAAA;IACzB,oDAAiC,CAAA;IACjC,kDAA+B,CAAA;IAC/B,oDAAiC,CAAA;IACjC,wDAAqC,CAAA;AACvC,CAAC,EAZW,eAAe,KAAf,eAAe,QAY1B;AAED,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpB,IAAI,CAAkB;IACtB,UAAU,CAAU;IAEpC,YAAY,IAAqB,EAAE,OAAe,EAAE,UAAmB;QACrE,MAAM,WAAW,GAAG,UAAU;YAC5B,CAAC,CAAC,GAAG,IAAI,KAAK,OAAO,KAAK,UAAU,EAAE;YACtC,CAAC,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC;QAC1B,KAAK,CAAC,WAAW,CAAC,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,OAAiB;IACxD,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC;QAC1C,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,OAAO,UAAU,CACf,IAAI,CAAC,SAAS,CACZ;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,CAAC,IAAI;YACjB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,UAAU,EAAE,KAAK,CAAC,UAAU;SAC7B,EACD,IAAI,EACJ,CAAC,CACF,EACD,IAAI,CACL,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GACX,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACzD,OAAO,UAAU,CACf,IAAI,CAAC,SAAS,CACZ;QACE,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,gBAAgB;QACvB,OAAO;KACR,EACD,IAAI,EACJ,CAAC,CACF,EACD,IAAI,CACL,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAA6B;IACzD,OAAO,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAC1D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,66 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SERVER_NAME, SERVER_VERSION } from "./constants.js";
+import { runStartup } from "./startup.js";
+import { logger } from "./logger.js";
+import { registerRegisterPeerTool } from "./tools/register-peer.js";
+import { registerSendMessageTool } from "./tools/send-message.js";
+import { registerListPeersTool } from "./tools/list-peers.js";
+import { registerGetHistoryTool } from "./tools/get-history.js";
+import { registerDeregisterPeerTool } from "./tools/deregister-peer.js";
+import { registerHealthCheckTool } from "./tools/health-check.js";
+// ---------------------------------------------------------------------------
+// Global error handlers -- registered FIRST before anything else
+// ---------------------------------------------------------------------------
+process.on("uncaughtException", (err) => {
+    logger.error(`Uncaught exception: ${err.message}`, { stack: err.stack });
+    // Do NOT exit -- MCP server should try to continue
+});
+process.on("unhandledRejection", (reason) => {
+    const msg = reason instanceof Error ? reason.message : String(reason);
+    logger.error(`Unhandled rejection: ${msg}`);
+});
+// ---------------------------------------------------------------------------
+// Graceful shutdown handlers
+// ---------------------------------------------------------------------------
+process.on("SIGTERM", () => {
+    logger.info("SIGTERM received, shutting down");
+    logger.close();
+    process.exit(0);
+});
+process.on("SIGINT", () => {
+    logger.info("SIGINT received, shutting down");
+    logger.close();
+    process.exit(0);
+});
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+async function main() {
+    // Startup MUST complete before MCP transport starts
+    // (handles first-run prompt, config loading, logger init, validation)
+    await runStartup();
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    // Register all 6 tools
+    registerRegisterPeerTool(server);
+    registerDeregisterPeerTool(server);
+    registerSendMessageTool(server);
+    registerListPeersTool(server);
+    registerGetHistoryTool(server);
+    registerHealthCheckTool(server);
+    // Connect stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Startup banner: always prints regardless of log level
+    process.stderr.write(`${SERVER_NAME} v${SERVER_VERSION} running on stdio\n`);
+    logger.info("Server ready. Tools: cc_register_peer, cc_deregister_peer, cc_send_message, cc_list_peers, cc_get_history, cc_health_check");
+}
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.error(`Fatal startup error: ${msg}`);
+    // Fallback to stderr in case logger failed
+    process.stderr.write(`Fatal error: ${msg}\n`);
+    logger.close();
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/logger.d.ts

@@ -0,0 +1,22 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export declare class Logger {
+    private readonly threshold;
+    private textStream;
+    private jsonStream;
+    constructor(level: LogLevel, logDir?: string);
+    private log;
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+    close(): void;
+}
+export declare function createLogger(level: LogLevel, logDir?: string): Logger;
+/** Pre-config logger: stderr-only at info level. Replaced after startup. */
+export declare let logger: Logger;
+/**
+ * Initialize the fully-configured logger with file outputs.
+ * Replaces the module-level `logger` export.
+ */
+export declare function initLogger(level: LogLevel, logDir?: string): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAS3D,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,UAAU,CAA+B;gBAErC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM;IAsB5C,OAAO,CAAC,GAAG;IAgBX,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAI5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAI3C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAI3C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAI5C,KAAK,IAAI,IAAI;CAId;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,4EAA4E;AAC5E,eAAO,IAAI,MAAM,EAAE,MAA2B,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAGjE"}