Skip to main content
Glama
README.md
<p align="center">
  <img src="images/muse-mascot-coding.gif" alt="Muse mascot coding - muse-relay-mcp" width="420">
</p>

<h1 align="center">muse-relay-mcp</h1>

<p align="center">
  <a href="https://github.com/99apps-id/muse-relay-mcp"><img src="https://img.shields.io/badge/release-v0.1.1-blue" alt="Release"></a>
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18-339933" alt="Node"></a>
  <a href="#license"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License: Apache 2.0"></a>
  <img src="https://img.shields.io/badge/dependencies-none-brightgreen" alt="Dependencies">
</p>

An MCP server that exposes **your personal Muse at [muse.ai](https://muse.ai)** as tools for other coding agents — terminal coding agents, IDEs, and other MCP hosts. Questions travel through the **muse-relay** file relay: the server writes a request file, a polling hook on the Muse side wakes a Muse worker, and the answer comes back as a file that the server returns as the tool result.

> **Not an official Meta product.** Muse personal has no public API and cannot act as an MCP server natively — this bridge is the workaround. Answers come from your personal Muse, with its long-term memory of your projects, not from a raw model API.

> **Separate project.** This server is a standalone project, independent from the **Muse Companion** VS Code extension. The two share nothing but the relay folder: the extension does not contain this server, and this server does not need the extension — only the relay folders and the Muse-side polling hook (see [Requirements](#requirements)).

<a id="screenshot"></a>

A real JSON-RPC session against `server.js` — handshake, tool list, an async question, and its answer arriving through the relay:

<p align="center">
  <img src="images/terminal-session.png" alt="Terminal session with the muse-relay MCP server" width="880">
</p>

## Table of Contents

- [Quick Start](#quick-start)
- [For AI Agents (Automated Setup)](#for-ai-agents-automated-setup)
- [Tools](#tools)
- [Screenshot](#screenshot)
- [Blocking vs Async](#blocking-vs-async)
- [How It Works](#how-it-works)
- [Requirements](#requirements)
- [Installation](#installation)
  - [Part A — Get the server](#part-a--get-the-server)
  - [Part B — Make sure the relay is running](#part-b--make-sure-the-relay-is-running)
  - [Part C — Register it in your MCP host](#part-c--register-it-in-your-mcp-host)
- [Usage](#usage)
- [Use Cases](#use-cases)
- [Configuration](#configuration)
- [Relay Protocol](#relay-protocol)
- [Security and Privacy](#security-and-privacy)
- [Limitations](#limitations)
- [Troubleshooting](#troubleshooting)
- [Changelog](#changelog)
- [License](#license)

## Quick Start

Every step is labelled with its difficulty. If the relay already runs on your machine — for example because you installed the Muse Companion extension first — this is a five-minute job; the only hard part is the one-time relay setup, and most of that is done by Muse itself.

| Step | What you get | Difficulty | Time |
| --- | --- | --- | --- |
| Relay check ([Part B](#part-b--set-up-the-relay-first-time-and-make-sure-it-is-running), step 5) | Confirmation the relay is live and not paused | 🟢 **Easy** | ~2 min |
| [Part A — Get the server](#part-a--get-the-server) | `server.js` on your machine — no build, no `npm install` | 🟢 **Easy** — clone + one check command | ~5 min |
| [Part B — Set up the relay](#part-b--set-up-the-relay-first-time-and-make-sure-it-is-running) *(only if no relay exists yet)* | The one-time relay behind the server | 🔴 **Advanced, one-time** — any SSH route from Muse to this machine (e.g. reverse SSH tunnel `ssh -R`, jump host, Tailscale/WireGuard, or direct IP) + SSH key; the polling hook is created by Muse on request | ~20–30 min |
| [Part C — Register it in your MCP host](#part-c--register-it-in-your-mcp-host) | The `ask_muse` tools in your agent | 🟡 **Moderate** — paste a JSON snippet, restart the host | ~5 min |

The shortest path: relay live → **Part A** → **Part C** → restart the host → ask its agent to call `ask_muse_start` with a test question, then `ask_muse_check` until the answer arrives.

*Not a terminal person?* The relay setup is the only steep part — open [muse.ai](https://muse.ai) and ask Muse to set up the `muse-relay-inbox` hook with you. Muse writes the hook and the worker instructions; your part is enabling an SSH route to your machine (Tailscale is optional — any SSH tunnel, reverse SSH `ssh -R`, VPN, or jump host works).

## For AI Agents (Automated Setup)

If an operator gives you (an AI coding agent such as **Claude Code, OpenAI Codex CLI, Google Antigravity, VS Code Copilot, Cursor, Windsurf, or Gemini CLI**) this repository URL and asks you to install or set it up for them, follow this exact checklist:

1. **Dependencies & Prerequisites (Zero npm packages required):**
   - Runtime required: **Node.js `>= 18`** (`node --version`) and **`git`** (or download `server.js` directly).
   - **Do NOT run `npm install` or any build step** — `server.js` uses only built-in Node.js modules (`fs`, `os`, `path`, `readline`).
   - **Tailscale is NOT required:** the relay only needs *any* working SSH path from Muse's environment to the relay folder on this machine (e.g. reverse SSH tunnel `ssh -R` via a VPS/jump host, Cloudflare Tunnel, WireGuard, ZeroTier, Tailscale, or direct IP). Do not install Tailscale unless the operator specifically asks for it.
2. **Clone the repository & create the local relay directories:**
   - Clone `https://github.com/99apps-id/muse-relay-mcp.git` into a persistent folder (e.g. `~/muse-relay-mcp` or the operator's preferred directory) and note the absolute path to `server.js`.
   - Ensure the three relay directories exist (`~/muse-relay/inbox`, `~/muse-relay/outbox`, `~/muse-relay/archive`):
     - **Windows (PowerShell):**
       ```powershell
       New-Item -ItemType Directory -Force "$env:USERPROFILE\muse-relay\inbox", "$env:USERPROFILE\muse-relay\outbox", "$env:USERPROFILE\muse-relay\archive"
       ```
     - **macOS / Linux (Bash):**
       ```bash
       mkdir -p "$HOME/muse-relay/inbox" "$HOME/muse-relay/outbox" "$HOME/muse-relay/archive"
       ```
3. **Smoke-test `server.js` locally:**
   - Run `node --check server.js` and pipe the JSON-RPC `initialize` + `tools/list` smoke test from [Part A, step 3](#part-a--get-the-server) into `node server.js` to confirm `ask_muse`, `ask_muse_start`, and `ask_muse_check` are listed.
4. **Register `muse-relay` in the operator's MCP host config (merge safely — never overwrite existing MCP servers):**
   - **VS Code (`%APPDATA%\Code\User\mcp.json` or `.vscode/mcp.json`):** add under top-level `"servers"` with `"type": "stdio"`, `"command": "node"`, `"args": ["<ABSOLUTE_PATH_TO_SERVER_JS>"]`.
   - **Claude Code:** run `claude mcp add muse-relay -- node "<ABSOLUTE_PATH_TO_SERVER_JS>"` (or merge into `~/.claude.json` under `"mcpServers"`).
   - **OpenAI Codex CLI (`~/.codex/config.toml`):** append the TOML table `[mcp_servers.muse-relay]` with `command = "node"` and `args = ["<ABSOLUTE_PATH_TO_SERVER_JS>"]`.
   - **Google Antigravity (`~/.gemini/antigravity/mcp_config.json`), Claude Desktop, Cursor (`~/.cursor/mcp.json`), Windsurf (`~/.codeium/windsurf/mcp_config.json`), Gemini CLI (`~/.gemini/settings.json`):** merge `"muse-relay": { "command": "node", "args": ["<ABSOLUTE_PATH_TO_SERVER_JS>"] }` under `"mcpServers"`.
5. **Report clearly to the operator:**
   - Tell the operator to **restart their IDE / agent session** so the new `muse-relay` MCP tools load.
   - Check whether `~/muse-relay/control.json` or `~/muse-relay/applied.json` already exists:
     - If they exist, the Muse-side SSH relay is already configured — remind the operator to ensure the relay is not paused (`"paused": false` in `control.json`) and that the `muse-relay-inbox` hook is enabled on muse.ai.
     - If they do not exist yet, inform the operator that the local MCP server and relay folders are ready, and point them to the one-time SSH reachability + `muse-relay-inbox` hook setup in [Part B](#part-b--set-up-the-relay-first-time-and-make-sure-it-is-running).

## Tools

| Tool | Mode | Behaviour |
| --- | --- | --- |
| `ask_muse` | Blocking | Ask a question and wait for the answer in one call (default timeout 600 s, adjustable 5–3600 s via `timeoutSecs`). Uses filesystem event watchers (`fs.watch`) so the answer returns **immediately** the instant Muse finishes. On timeout the question is **not** cancelled — you receive a `PENDING` result with the ticket id to continue waiting via `ask_muse_check`. |
| `ask_muse_start` | Async | Submit a question and return immediately with a ticket id. |
| `ask_muse_check` | Async / Long-Poll | Fetch or wait for a ticket id. If the answer is already in the outbox, returns immediately (0 ms). Otherwise watches the outbox in real time up to `waitSecs` (default 25 s, configurable 0–600 s), returning the instant Muse finishes or `PENDING` if still working. Safe to call repeatedly. |

Shared arguments: `prompt` (required), `workspaceRoot` (optional), `answerLanguage` (`en` / `id`).

## Blocking vs Async

- **Instant delivery when Muse is fast:** Both `ask_muse` and `ask_muse_check` attach an OS filesystem watcher (`fs.watch`) to the relay `outbox` and `archive` folders. Whether Muse takes 8 seconds or 8 minutes, the tool returns within milliseconds of the answer file landing.
- **Blocking** (`ask_muse`) is simple: the agent asks and waits in a single tool call (up to `timeoutSecs`, max 3600 s / 1 hour), while sending MCP `notifications/progress` heartbeats when requested by the host. If the call reaches `timeoutSecs` first, it returns a non-error `PENDING` response containing the ticket id so the agent can seamlessly continue waiting with `ask_muse_check`.
- **Async + Long-Polling** (`ask_muse_start` + `ask_muse_check`) is immune to strict MCP host tool-call timeouts (such as 60–120 s limits in Cursor, Codex, or Claude Code). Each `ask_muse_check` call can hold for `waitSecs` (default 25 s, or pass e.g. `waitSecs: 45` / `60`) so the agent can patiently wait for long tasks without burning dozens of rapid polling turns.

## How It Works

```text
MCP host (agent)          your machine                      Muse side
----------------          ------------                      -----------
tool call          ---->  server.js (stdio, this repo)
                          write req-mcp-<id>.json  ---->    ~/muse-relay/inbox/
                                                            polling hook (SSH tunnel)
                                                            wakes a Muse worker
tool result        <----  read res-mcp-<id>.json   <----    worker answers, archives req
                          (outbox, then archived)
```

The server is a single dependency-free Node script speaking line-delimited JSON-RPC over stdio, exactly like a regular MCP server. All the latency and queueing live in the relay behind it.

## Requirements

- Node.js 18 or newer, available as `node`.
- A working **muse-relay** on the same machine:
  - Relay folders `~/muse-relay/{inbox,outbox,archive}` (Windows: `C:\Users\<WINDOWS_USER>\muse-relay\...`), overridable with the `MUSE_RELAY_DIR` environment variable.
  - A network path from Claude's environment to this machine. The hook polls the relay folders **over SSH**, so this machine must be reachable from Claude's side. The reference setup uses [Tailscale](https://tailscale.com/download) (install it on both ends, log in with the same account) plus an SSH server on this machine; any equivalent route — LAN, another VPN, a jump host — works just as well. Tailscale itself is not mandatory; SSH reachability is.
  - A polling hook named `muse-relay-inbox` enabled on the Muse side, which wakes a worker for new request files. A reference setup (folders, SSH/Tailscale reachability, the hook, and the worker instructions) is documented in the companion extension's README, Part B.
  - The relay must not be paused (`control.json` in the relay folder). While paused, every tool refuses fast with a `PAUSED` error.

Throughout this document, replace the placeholders with your own values:

| Placeholder | Meaning | Example |
| --- | --- | --- |
| `<INSTALL_DIR>` | Folder where you put this project | `C:\Project\muse-relay-mcp` |
| `<WINDOWS_USER>` | Your Windows account name | `alice` |

## Installation

### Part A — Get the server

1. Clone this repository (or copy the project folder) to your install directory:

   ```bash
   git clone https://github.com/99apps-id/muse-relay-mcp.git muse-relay-mcp
   cd muse-relay-mcp
   ```

2. Verify the script parses and Node is new enough:

   ```bash
   node --version          # v18 or newer
   node --check server.js  # no output = OK
   ```

   There is nothing to install — no `npm install`, no build step.

3. (Optional smoke test) Pipe a handshake and a tool list into the server:

   ```bash
   printf '%s\n%s\n%s\n' \
     '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1.0.0"}}}' \
     '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
     '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
     | node server.js
   ```

   You should see two responses, the second listing `ask_muse`, `ask_muse_start`, and `ask_muse_check`.

### Part B — Set up the relay (first time) and make sure it is running

The MCP server is only the front door — without a running relay behind it, questions queue forever. If the relay already runs on this machine (for example because you installed the companion extension first), only step 5 applies. If you are starting from this server alone, work through all five steps:

1. **Create the relay folders** on this machine (Windows PowerShell):

   ```powershell
   New-Item -ItemType Directory -Force "$env:USERPROFILE\muse-relay\inbox"
   New-Item -ItemType Directory -Force "$env:USERPROFILE\muse-relay\outbox"
   New-Item -ItemType Directory -Force "$env:USERPROFILE\muse-relay\archive"
   ```

2. **Make this machine reachable from Claude's environment.** Install Tailscale on this machine and on the machine Muse runs on (or its jump host) from [tailscale.com/download](https://tailscale.com/download); log in with the **same Tailscale account** on both ends. Verify with `tailscale status`, and note this machine's mesh address via `tailscale ip -4` — Muse's side needs it as its SSH target. Another VPN, a plain LAN route, or a jump host is equally fine; only SSH reachability matters, Tailscale is simply the reference route.
3. **Enable SSH into this machine** and install Muse's public key (ask Muse for it in the muse.ai chat). On Windows, in an elevated PowerShell:

   ```powershell
   Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
   Start-Service sshd
   Set-Service -Name sshd -StartupType Automatic
   ```

   Place the key in `C:\Users\<WINDOWS_USER>\.ssh\authorized_keys` — one key per line. If `<WINDOWS_USER>` is an administrator account, Windows OpenSSH reads `C:\ProgramData\ssh\administrators_authorized_keys` instead.
4. **Create the polling hook on the Muse side.** In the muse.ai chat, ask Muse to create an event hook named `muse-relay-inbox` that polls the relay inbox over the SSH path from step 2 every 5 seconds, wakes a worker for each new `req-*.json`, and re-wakes a request that stays unanswered for 15 minutes (watchdog, max 2 retries). The worker reads the request, does the work, writes `res-<id>.json` to the outbox, and moves the request to the archive. A fuller reference — exact worker instructions and settings sync — is Part B of the companion extension's README.
5. **Confirm it is live:** in the muse.ai chat, confirm the `muse-relay-inbox` hook is **enabled** — if it is disabled, questions queue silently and calls time out. Also make sure the relay is not paused (`control.json` in the relay folder; if you use the companion extension, check its panel). Then verify end-to-end in Part C, step 5.

### Part C — Register it in your MCP host

Below are ready-to-use configurations for **VS Code**, **Claude Code**, **Claude Desktop**, **OpenAI Codex CLI**, **Google Antigravity**, **Cursor / Windsurf**, and **Gemini CLI**. On Windows, escape backslashes in JSON paths (`C:\\Project\\muse-relay-mcp\\server.js`), or use forward slashes (`C:/Project/muse-relay-mcp/server.js`).

#### 1. VS Code (GitHub Copilot)

VS Code uses the top-level `"servers"` key in `%APPDATA%\Code\User\mcp.json` (global) or `.vscode/mcp.json` (workspace):

```json
{
  "servers": {
    "muse-relay": {
      "type": "stdio",
      "command": "node",
      "args": ["<INSTALL_DIR>\\server.js"]
    }
  }
}
```

#### 2. Claude Code (CLI)

Register with a single command:

```bash
claude mcp add muse-relay -- node "<INSTALL_DIR>/server.js"
```

Or add to `~/.claude.json` (user scope) or `.mcp.json` (project scope):

```json
{
  "mcpServers": {
    "muse-relay": {
      "command": "node",
      "args": ["<INSTALL_DIR>\\server.js"]
    }
  }
}
```

#### 3. Claude Desktop

Add to `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "muse-relay": {
      "command": "node",
      "args": ["<INSTALL_DIR>\\server.js"]
    }
  }
}
```

#### 4. OpenAI Codex CLI

Codex CLI uses **TOML** in `~/.codex/config.toml` (or `%USERPROFILE%\.codex\config.toml` on Windows):

```toml
[mcp_servers.muse-relay]
command = "node"
args = ["<INSTALL_DIR>/server.js"]
```

*(Optional)* If your relay folder is custom, add `env = { MUSE_RELAY_DIR = "D:/path/to/muse-relay" }` under `[mcp_servers.muse-relay]`.

#### 5. Google Antigravity

Add to `%USERPROFILE%\.gemini\antigravity\mcp_config.json`:

```json
{
  "mcpServers": {
    "muse-relay": {
      "command": "node",
      "args": ["<INSTALL_DIR>\\server.js"]
    }
  }
}
```

#### 6. Cursor, Windsurf, Cline, Gemini CLI & Other MCP Hosts

Most other MCP hosts (`~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, `~/.gemini/settings.json`, termigo, ODON) use the standard `"mcpServers"` schema:

```json
{
  "mcpServers": {
    "muse-relay": {
      "command": "node",
      "args": ["<INSTALL_DIR>\\server.js"]
    }
  }
}
```

#### Custom Relay Folder (`MUSE_RELAY_DIR`)

If your relay folder is not the default `~/muse-relay`, pass `MUSE_RELAY_DIR` via `"env"`:

```json
{
  "command": "node",
  "args": ["<INSTALL_DIR>\\server.js"],
  "env": {
    "MUSE_RELAY_DIR": "D:\\path\\to\\muse-relay"
  }
}
```

#### Restart & Verify

1. **Restart the host app or start a new session** — MCP hosts read their server list at startup, so the new tools appear only afterwards.
2. **Verify end-to-end:** ask the host's agent to call `ask_muse_start` with a question only your personal Muse can answer (something about your own projects or earlier decisions), then `ask_muse_check` until the answer arrives. As soon as Muse finishes, `ask_muse_check` returns immediately.

## Usage

- Prefer the **async pair** for coding agents: `ask_muse_start`, keep working, then `ask_muse_check` every so often.
- Use **blocking** `ask_muse` for quick questions from hosts with generous tool-call timeouts. If it times out, take the ticket id from the response and continue with `ask_muse_check` — the question stays alive.
- Each call is a **one-shot question**, not a conversation thread: include the context the question needs in `prompt` (and `workspaceRoot` when relevant). Follow-up questions are new calls.
- Answers typically take **1–10 minutes** (relay polling + a serial worker queue + the work itself). The relay watchdog re-wakes a request that stays unanswered for 15 minutes, at most 2 times.

## Use Cases

The point of the bridge is that the answer comes from **your personal Muse** — with its connected accounts, its own tools, and its long-term memory of your projects — not from a raw model that can only see the current workspace. Four patterns from real use:

### 1. Pull your Instagram or Threads into the coding chat

Building a content tool, a landing page, or a social dashboard, and the data you need lives in your social accounts? Let the coding agent ask Muse instead of copy-pasting between apps:

```text
ask_muse_start: "Fetch my 10 most recent Instagram posts with their like and
comment counts, and summarize what performed best this week."

ask_muse_start: "Read my Threads direct messages from the last 3 days, group
them by topic, and list anything that still needs a reply."
```

Muse reads the connected account, does the summarizing, and the result lands as a tool result **inside the chat UI of your coding app** — VS Code, Claude Code, Antigravity, a terminal agent — right next to the code it is relevant to. This needs the account connected to your Muse; Muse reads only what the prompt asks for.

### 2. Post to Instagram or Threads without leaving the editor

The same path works in the other direction. The coding agent composes the request, Muse does the publishing:

```text
ask_muse: "Draft a short announcement for the v0.2 release (notes attached in
the prompt) and post it to my Threads and Instagram."
```

Muse prepares the draft and shows you the **exact text for approval in its own chat** before anything is posted — a coding agent's say-so is never enough to publish under your name. Once you approve, Muse posts it and the confirmation comes back through the relay into the coding chat.

### 3. Delegate a long, web-heavy errand to a Muse worker — a real run

On 19 Nov 2026, an Antigravity agent (Opus 5.5) delegated a multi-step audit to a Muse worker through this bridge: find CCTV streams for three cities for a streaming-directory project, validate that every stream really plays, update the allowlist and the data file. The agent kept working locally; the Muse worker did the web research and validation.

<p align="center">
  <img src="images/delegated-task.png" alt="A real delegated task through muse-relay: an Antigravity agent asks a Muse worker to audit CCTV streams, and the result comes back by ticket" width="880">
</p>
<p align="center"><em>Rendered from the actual relay files of that run (ticket <code>mcp-mwnasqwq96ux4</code>), excerpted. The honest result — 0 new cameras passed, 79 existing entries re-verified — is exactly why the async pattern exists: the job took 23 minutes, far beyond any blocking tool-call timeout.</em></p>

### 4. Borrow Muse's memory of your other projects

A coding agent sees one workspace. Your Muse remembers the decisions, preferences, and history across all of them:

```text
ask_muse: "In my other terminal-agent project, why did we pin the parser
library to a single version last month — and does that apply here?"
```

Second opinions, cross-project context, "what did I decide about X" — questions no amount of grepping the current repo can answer.

## Configuration

| Setting | Where | Default | Notes |
| --- | --- | --- | --- |
| Relay folder | `MUSE_RELAY_DIR` env var | `%USERPROFILE%\muse-relay` (Windows) / `~/muse-relay` | Must match the folder the hook and panel use |
| Blocking timeout | `timeoutSecs` argument of `ask_muse` | 600 (range 5–3600) | Timeout never cancels the question; returns ticket id for `ask_muse_check` |
| Long-poll wait per check | `waitSecs` argument of `ask_muse_check` | 25 (range 0–600) | Returns immediately when answer arrives; returns `PENDING` after `waitSecs` |
| Answer language | `answerLanguage` argument | `id` | Sent with each request; the worker answers in this language |

## Relay Protocol

Requests are files named `req-<ticket>.json` in the relay inbox; the ticket id is the file id (`mcp-…`):

```json
{
  "id": "mcp-mwn78gdy9yvl2",
  "createdAt": "2026-11-19T06:58:41.000Z",
  "prompt": "What did the watchdog change in the relay hook?",
  "answerLanguage": "en",
  "workspaceRoot": null,
  "source": "mcp"
}
```

Answers are `res-<ticket>.json` in the outbox (`{ "id", "answeredAt", "answer" }`). `ask_muse_check` looks in the outbox first, then the archive (the VS Code panel may archive a response before you check), and moves an outbox answer to the archive after returning it. `source: "mcp"` distinguishes bridge requests from panel requests (`source: "panel"`).

## Security and Privacy

- The server makes **no network calls** and collects nothing; it only reads and writes JSON files in the relay folder on your own machine.
- Any local process that can write to the relay inbox can ask your Muse questions — treat the relay folder as trusted local state, and keep the Muse-side worker rule: no irreversible actions (git pushes, deletions) unless the prompt explicitly asks.
- Never publish your real infrastructure details (hostnames, IPs, usernames) in a fork of this README — use the placeholders.

## Limitations

- Latency is minutes, not seconds; there is no streaming.
- One worker lane on the Muse side: simultaneous questions are answered one at a time, in order. A single worker execution is capped at about 10 minutes by the platform; the watchdog covers failures after that.
- One-shot Q&A only — no multi-turn session state is kept by the server.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Tool returns `PAUSED` immediately | Relay paused (panel or `control.json`) | Resume the relay in the VS Code panel, or set `"paused": false` in `control.json` |
| `ask_muse_check` stays `PENDING` forever | Muse-side hook disabled | Enable the `muse-relay-inbox` hook in the muse.ai chat; queued questions are answered once it runs |
| First install, nothing ever answers | Relay prerequisite not set up yet (folders, SSH reachability, hook) | Work through Part B steps 1–4 |
| Blocking call times out | Normal for long answers | Use the returned ticket with `ask_muse_check`, or switch to the async pair |
| Host does not list the tools | Hosts load MCP config at startup | Restart the app or start a new session; re-check the JSON for trailing commas |
| Server fails to start | `node` not on PATH for the host | Use the absolute path to the Node binary as `command` |
| Answers land in the panel but not the tool | Relay folder mismatch | Make sure `MUSE_RELAY_DIR` matches the folder the hook/panel actually use |

## Changelog

### 0.1.1

- **Instant delivery via `fs.watch`** — `ask_muse` and `ask_muse_check` watch `outbox/` and `archive/` with OS filesystem events so answers return within milliseconds of Muse finishing
- **Long-polling on `ask_muse_check` (`waitSecs`)** — waits up to `waitSecs` (default 25 s, range 0–600 s) before returning `PENDING`, letting coding agents wait for long tasks without hitting host tool-call timeouts or burning rapid poll turns
- **Soft `PENDING` timeout on `ask_muse` + MCP progress heartbeats** — `timeoutSecs` now extends up to 3600 s, emits `notifications/progress` when a `progressToken` is supplied, and returns a non-error `PENDING` message with the ticket id on timeout
- **Relay safety & cross-agent compatibility** — atomic request file writes (`.tmp-req-*.json` → rename), 10 s grace period for in-flight SSH partial response writes, ticket ID path-traversal validation, `notifications/cancelled` support, clean shutdown on stdio close, MCP tool `annotations` (`readOnlyHint`, `idempotentHint`, etc.), `additionalProperties: false` for strict schemas, and ready-to-paste setup guides for VS Code, Claude Code, Claude Desktop, OpenAI Codex CLI (TOML), Google Antigravity, Cursor, Windsurf, and Gemini CLI

### 0.1.0 — first public release

- Three tools: `ask_muse` (blocking, ticket survives timeout), `ask_muse_start`, `ask_muse_check`
- Fast `PAUSED` refusal while the relay is paused
- Outbox-then-archive answer lookup; answers archived after delivery
- Zero dependencies; single-file Node stdio server

## License

Apache License 2.0 — see the `LICENSE` file in this repository. Attribution notices live in the `NOTICE` file; redistributions must preserve them (Apache License, Section 4(d)).

Unofficial project. Muse and muse.ai are products of Meta; this server is not affiliated with or endorsed by Meta.