@powforge/forge-whisper-mcp

@powforge/forge-whisper-mcp

Read another agent's live state from any MCP-compatible client.

You're running an autonomous agent that ticks every 20 minutes. You want a separate AI assistant — Claude Code in another window, Cursor, your phone bot — to answer questions about that agent without you copying state files into the conversation. "What did the loop ship in the last 5 ticks?" "What's the current hypothesis status?" "Is on-chain expensive right now?"

Today you have two options: paste logs by hand, or write a one-off API. This package is the third option.

forge-whisper-mcp is a stateless MCP server that exposes five read-only tools. Point it at a directory containing your agent's state files, and any MCP-compatible client can introspect that agent live, in machine-structured form.

The five tools

Tool	Returns
get_forge_state	Current tick number, last action, last score, streak, micro-goal, mean score per action class
get_recent_learnings(n)	Last N free-text learning notes from the activity log
get_tick_history(n)	Last N tick records with action, score, hour-of-day, learning
get_hypothesis_status	Parsed research hypotheses: title, prediction, latest status, label (untested / inconclusive / partial-confirm / confirmed / refuted)
get_bitcoin_pulse	Tip height, tip hash, fee tiers, mempool tx count — from your local Bitcoin node when reachable, mempool.space fallback otherwise

Every tool is read-only. No writes. No credentials held. No surprises.

Why an MCP server, not an HTTP API

Because MCP clients already exist. You don't have to teach Claude Code, Cursor, or Continue how to call a custom endpoint — they all speak MCP natively. Add this server to an MCP config and the five tools show up as first-class capabilities the assistant can chain into any conversation.

It's also why this is novel: an autonomous agent publishing its own operational state as MCP, so other agents can consume it. The pattern generalizes — any agent can expose its state this way.

Install

npm install -g @powforge/forge-whisper-mcp

Or use it directly via npx from your MCP config (no global install needed).

Configure your MCP client

Print a ready-to-paste config block:

npx -y @powforge/forge-whisper-mcp --install

Or paste this manually into your MCP config (e.g. ~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "powforge-forge-whisper": {
      "command": "npx",
      "args": ["-y", "@powforge/forge-whisper-mcp"],
      "env": {
        "FORGE_WHISPER_REPO_ROOT": "/absolute/path/to/your/agent/repo"
      }
    }
  }
}

Restart your MCP client. The five tools appear automatically.

Expected directory layout

FORGE_WHISPER_REPO_ROOT should point to a directory containing some or all of:

forge-state.json                              # required for get_forge_state
activity.json                                 # required for get_recent_learnings
data/tick-log.jsonl                           # required for get_tick_history
research/depth-of-identity-hypotheses.md      # required for get_hypothesis_status (default path; configurable)
scripts/lib/bitcoin-pulse.js                  # optional — used as primary source for get_bitcoin_pulse

Missing files don't crash the server. Each tool returns a structured { error, message, observed_at } envelope when its source is unavailable, so calling agents can degrade gracefully.

File format expectations

forge-state.json

{
  "tick_count": 365,
  "last_action": "build",
  "last_score": 0.92,
  "action_scores": {
    "build": { "avg_score": 0.9, "count": 111, "adjustment": 8 }
  },
  "streak": { "type": "build", "count": 2 }
}

activity.json

Newest-first array:

[
  { "time": "2026-04-29T06:30:00.000Z", "emoji": "PKG", "description": "Shipped v0.1.0. Balance: 20489 sats." }
]

If a recent description matches /balance[:\s]+(\d+)\s*sats/i, the server infers a 1k-sat micro-goal from it.

data/tick-log.jsonl

One JSON object per line, append-only:

{"ts":"2026-04-29T06:30:00Z","tick":365,"action":"build","score":0.95,"learning":"shipped"}

research/depth-of-identity-hypotheses.md

Markdown with hypothesis blocks like:

## H-DOI-1: Multi-dimensional depth is exponentially harder to fake
- **Test**: Compare grinder vs multi-dim
- **Prediction**: Multi-dim scores higher with 100x fewer events
- **Status (Day 13)**: 1-vs-1 CONFIRMED. Multi-dim scored 18.4x higher.
- **Status (Tick 361)**: STRONG CONFIRM after structural fix. AUC = 1.000.

The parser captures the LAST **Status...** line as latest_status and derives a normalized label.

What this is not

• Not a write surface. The server cannot mutate state, post events, or hold credentials.
• Not a notification stream. For live channel events on a 20-minute cadence, see the sibling forge-whisper Claude Code plugin in this repo. Different protocol, different scope.
• Not Bitcoin-only. It happens to expose a Bitcoin pulse because the agents we built it for care about on-chain economics. Swap in your own pulse if your agent's environment differs.
• Not authenticated. Anyone who can talk MCP to this server reads everything it exposes. Run it locally, scope FORGE_WHISPER_REPO_ROOT to what you want exposed, don't bind it to public networks.

Development

npm install @powforge/forge-whisper-mcp
node -e "console.log(require('@powforge/forge-whisper-mcp/src/index.js').TOOLS.map(t => t.name))"

Source ships in the published tarball. Tests use node:test, fixtures in tests/fixtures/, no network beyond mempool.space stubs.

License

MIT.