Skip to content
Back to search

agent-relay-mcp

Local-first cross-session coding agent bridge, cooperative TTL file-lease guard, and non-blocking human question inbox.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pie527645-cloud--agent-relay-mcp/badge.svg)](/listings/pie527645-cloud--agent-relay-mcp)

HTML

<a href="/listings/pie527645-cloud--agent-relay-mcp"><img src="/api/listings/pie527645-cloud--agent-relay-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone the repository, install dependencies, and compile the TypeScript build:

git clone https://github.com/pie527645-cloud/agent-relay-mcp.git
cd agent-relay-mcp
npm install
npm run build

Verify both entrypoints after building:

node ./dist/cli.js --help
node ./dist/mcp.js --help

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 211 lines
  1. # @pie527645-cloud/agent-relay-mcp
  2. Local-first cross-session coding agent bridge, cooperative file-lease guard, and non-blocking human question inbox built on the Model Context Protocol (MCP).
  3. When running multiple coding agents side by side on the same workstation (such as terminal sessions, IDE agents, and background workers), sessions ordinarily cannot see what sibling sessions are editing and stall whenever they block waiting for human terminal input. `agent-relay-mcp` solves these three coordination gaps using an atomic local JSON store with zero cloud dependencies and zero native C++ addons:
  4. 1. **Monotonic Channel Relay** (`post_message`, `read_messages`) — Lightweight append-only local channels with strictly monotonic sequence numbers (`seq`) and cursor-based polling (`sinceSeq`).
  5. 2. **Cooperative File-Lease Guard** (`acquire_file_lease`, `release_file_lease`) — Exclusive time-bounded file leases (default 120s TTL, max 3600s) that prevent two agents from editing the same file simultaneously, automatically expire stale leases, and report active lease holders on conflict instead of silently overwriting.
  6. 3. **Non-Blocking Human Question Inbox** (`ask_human_async`, `check_human_reply`) — Agents enqueue questions and continue unblocked work while a human operator answers asynchronously from the `agent-relay` CLI or the local `127.0.0.1` web dashboard.
  7. ---
  8. ## Architecture
  9. ```mermaid
  10. flowchart LR
  11. subgraph Sessions["Local Coding Agent Sessions"]
  12. A1["Agent Session A (stdio MCP)"]
  13. A2["Agent Session B (stdio MCP)"]
  14. end
  15. subgraph Server["@pie527645-cloud/agent-relay-mcp"]
  16. MCP["MCP Server (dist/mcp.js)"]
  17. CLI["Operator CLI (dist/cli.js)"]
  18. WEB["Local Web UI (127.0.0.1:4317)"]
  19. LOCK["Cross-Process wx Lock + Stale Recovery"]
  20. end
  21. subgraph Store["Local State (~/.agent-relay)"]
  22. CH["channels/*.json (seq logs)"]
  23. LS["leases.json (TTL file leases)"]
  24. IN["inbox.json (async human Q&A)"]
  25. end
  26. A1 <--> MCP
  27. A2 <--> MCP
  28. MCP --> LOCK
  29. CLI --> LOCK
  30. WEB --> LOCK
  31. LOCK --> CH
  32. LOCK --> LS
  33. LOCK --> IN
  34. ```
  35. ---
  36. ## Requirements
  37. - **Node.js** `>= 20.18.1` (tested in CI across Ubuntu and Windows on Node `20.x` and `22.x`)
  38. - Pure TypeScript / JavaScript runtime dependencies (`@modelcontextprotocol/sdk`, `zod`) — **zero `node-gyp` or native C++ compilation required**
  39. ---
  40. ## Installation From Source
  41. Clone the repository, install dependencies, and compile the TypeScript build:
  42. ```bash
  43. git clone https://github.com/pie527645-cloud/agent-relay-mcp.git
  44. cd agent-relay-mcp
  45. npm install
  46. npm run build
  47. ```
  48. Verify both entrypoints after building:
  49. ```bash
  50. node ./dist/cli.js --help
  51. node ./dist/mcp.js --help
  52. ```
  53. ---
  54. ## Configuring MCP Clients
  55. Point your MCP-compatible coding client to the compiled `dist/mcp.js` entrypoint using an absolute path.
  56. ### Claude Desktop / Cursor / Windsurf (`mcpServers` JSON)
  57. ```json
  58. {
  59. "mcpServers": {
  60. "agent-relay": {
  61. "command": "node",
  62. "args": [
  63. "/abs/path/to/agent-relay-mcp/dist/mcp.js"
  64. ],
  65. "env": {
  66. "AGENT_RELAY_DIR": "/Users/yourname/.agent-relay"
  67. }
  68. }
  69. }
  70. }
  71. ```
  72. On Windows, use your Windows path (for example `"C:\\path\\to\\agent-relay-mcp\\dist\\mcp.js"`). You may omit `AGENT_RELAY_DIR` to use the default `~/.agent-relay` directory, or pass `"--dir", "/custom/state/path"` in `args`.
  73. ---
  74. ## MCP Tools Reference (6 Tools)
  75. ### 1. `post_message`
  76. Append a timestamped message with a monotonic sequence number (`seq`) to a local coordination channel.
  77. - **Parameters:**
  78. - `channel` (`string`, required): Channel identifier matching `[a-zA-Z0-9_-]{1,64}`.
  79. - `sender` (`string`, required): Identifier of the agent or session posting the message (`1..128` chars).
  80. - `body` (`string`, required): Plain-text message content (`1..32768` chars).
  81. - `tags` (`string[]`, optional): Up to 16 classification tags (`1..64` chars each).
  82. - **Returns:** `{ message: { seq, channel, sender, body, tags, createdAt }, headSeq }`
  83. ### 2. `read_messages`
  84. Read channel messages strictly after `sinceSeq` along with the latest `headSeq` cursor.
  85. - **Parameters:**
  86. - `channel` (`string`, required): Channel identifier matching `[a-zA-Z0-9_-]{1,64}`.
  87. - `sinceSeq` (`integer`, optional, default `0`): Return messages where `seq > sinceSeq`.
  88. - `limit` (`integer`, optional, default `50`, max `500`): Maximum messages returned in ascending `seq` order.
  89. - **Returns:** `{ channel, sinceSeq, headSeq, count, hasMore, messages }`
  90. ### 3. `acquire_file_lease`
  91. Claim or renew an exclusive cooperative lease on a workspace file path.
  92. - **Parameters:**
  93. - `path` (`string`, required): Workspace-scoped file path (normalized across `/` and `\`; rejects `..` traversal, UNC paths, and control characters).
  94. - `owner` (`string`, required): Identifier of the requesting session (`1..128` chars).
  95. - `ttlSeconds` (`integer`, optional, default `120`, range `1..3600`): Lease duration before automatic expiration.
  96. - **Behavior:**
  97. - Automatically prunes expired leases before evaluating conflicts.
  98. - Re-acquiring a lease already held by the same `owner` renews its `expiresAt` timestamp (`renewed: true`).
  99. - If held by another active owner, returns `{ acquired: false, renewed: false, path, holder, expiresAt }` without overwriting the existing lease.
  100. ### 4. `release_file_lease`
  101. Release a cooperative file lease cleanly when editing finishes.
  102. - **Parameters:**
  103. - `path` (`string`, required): Leased file path.
  104. - `owner` (`string`, required): Lease owner identifier.
  105. - **Behavior:** Verifies ownership before removing an active lease; idempotently succeeds (`alreadyExpiredOrMissing: true`) if the lease already expired.
  106. ### 5. `ask_human_async`
  107. Enqueue a non-blocking question in the shared human inbox and return immediately without reading or blocking terminal `stdin`.
  108. - **Parameters:**
  109. - `sender` (`string`, required): Agent or session asking the question.
  110. - `question` (`string`, required): Question text (`1..8192` chars).
  111. - `options` (`string[]`, optional): Up to 20 suggested answer choices.
  112. - `priority` (`"low" | "normal" | "high" | "urgent"`, optional, default `"normal"`).
  113. - **Returns:** `{ questionId, status: "pending", priority, createdAt }`
  114. ### 6. `check_human_reply`
  115. Poll the status of a previously queued human question by `questionId`.
  116. - **Parameters:**
  117. - `questionId` (`string`, required): Identifier returned by `ask_human_async`.
  118. - **Returns:** `{ questionId, status: "pending" | "answered", sender, question, options, priority, createdAt, answer, answeredAt }`
  119. ---
  120. ## Operator CLI Reference
  121. Run commands directly via `node /abs/path/to/agent-relay-mcp/dist/cli.js` (or `agent-relay` if linked locally via `npm link`). Every command supports `--dir <path>` and `--json`.
  122. ```bash
  123. # View pending human questions and active cooperative file leases
  124. node ./dist/cli.js inbox
  125. # Include previously answered questions and emit JSON
  126. node ./dist/cli.js inbox --all --json
  127. # Reply to a queued agent question
  128. node ./dist/cli.js reply q_m8abc12_9f01c2d3 "Use the expand-contract migration."
  129. # Tail recent messages in a channel (or pass --since <seq> --limit <n>)
  130. node ./dist/cli.js tail backend --limit 20
  131. # Inspect active file leases or release a specific lease
  132. node ./dist/cli.js leases
  133. node ./dist/cli.js leases --release src/auth/middleware.ts --owner claude-code
  134. # Launch the local-only HTTP dashboard on 127.0.0.1:4317
  135. node ./dist/cli.js web --port 4317
  136. ```
  137. ---
  138. ## Security and Concurrency Design
  139. - **Cross-Process Atomic State:** State mutations acquire an exclusive `'wx'` (`O_CREAT | O_EXCL`) lockfile per resource with jittered retry backoff and automatic stale/dead-PID lock eviction, then write to a process-unique temporary file, `datasync` to disk, and atomically rename into place.
  140. - **Strict Input & Path Sanitization:** Channel names are restricted to `[a-zA-Z0-9_-]{1,64}`. File lease keys use null-prototype lookup maps, normalize slashes (plus case-insensitive key matching on Windows and macOS), and reject parent directory traversal (`..`), null/control characters, UNC paths, and NTFS alternate data stream colons.
  141. - **Localhost-Only Web UI Hardening:** `agent-relay web` binds strictly to `127.0.0.1` (never `0.0.0.0`), validates `Host` (`127.0.0.1:<port>`, `localhost:<port>`, `[::1]:<port>`), `Origin`, `Referer`, and `Sec-Fetch-Site` headers (returning HTTP `403 Forbidden` on untrusted values to block DNS rebinding and cross-site form submissions), applies a strict `Content-Security-Policy` (`default-src 'none'`), and HTML-escapes all rendered text against XSS.
  142. ---
  143. ## Development and Verification
  144. ```bash
  145. npm run lint
  146. npm run build
  147. npm test
  148. ```
  149. ## License
  150. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.