aesop / mcp
CLAUDE.md2 starsChanged 31 days agoMITView on GitHub
Purpose: Expose Aesop fleet operational status as a Model Context Protocol (JSON-RPC 2.0) server over stdio. File: mcp/server.mjs — Stdio-transport JSON-RPC 2.0 server, Node.js (no npm dependencies, stdlib only). Protocol version: initialize advertises protocolVersion 2025-11-25 (the LATEST_PROTOCOL_VERSION of @modelcontextprotocol/sdk 1.32.1). Metadata author in mcp/package.json matches the root package. Guarded by tests/mcp-metadata.test.mjs. Environment variables (override defaults): - AESOP_ROOT — Fleet root directory (default: $HOME/aesop) - AESOP_STATE_ROOT — State directory (default: $AESOP_ROOT/state) - AESOP_TRANSCRIPTS_ROOT — Transcript directory (default: $HOME/.claude/projects) Also reads $AESOP_ROOT/aesop.config.json…
In this repository21 other files it gives its agents.
- auth/CLAUDE.mdCLAUDE.md
- bin/CLAUDE.mdCLAUDE.md
- chat/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- daemons/CLAUDE.mdCLAUDE.md
- dash/CLAUDE.mdCLAUDE.md
- driver/CLAUDE.mdCLAUDE.md
- hooks/CLAUDE.mdCLAUDE.md
- monitor/CLAUDE.mdCLAUDE.md
- scan/CLAUDE.mdCLAUDE.md
- skills/CLAUDE.mdCLAUDE.md
- state_store/CLAUDE.mdCLAUDE.md
- stdio/CLAUDE.mdCLAUDE.md
- tests/CLAUDE.mdCLAUDE.md
- tools/CLAUDE.mdCLAUDE.md
- ui/CLAUDE.mdCLAUDE.md
- buildsystemSkill
- dashboardSkill
- fleetSkill
- healthcheckSkill
- powerSkill
The file
We split this CLAUDE.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 144
Run: npm run test:node or node --test tests/mcp*.test.mjs.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
mcp/ — Read-Only Fleet State MCP Server
Purpose: Expose Aesop fleet operational status as a Model Context Protocol (JSON-RPC 2.0) server over stdio.
Universal rules (every domain)
- Feature branch only, never main; push gated by secret_scan.py; tests never pollute cwd/git config; ABSOLUTE paths in worktrees; docs updated with code.
Server & Configuration
File: mcp/server.mjs — Stdio-transport JSON-RPC 2.0 server, Node.js (no npm dependencies, stdlib only).
Protocol version: initialize advertises protocolVersion 2025-11-25 (the LATEST_PROTOCOL_VERSION of @modelcontextprotocol/sdk 1.32.1). Metadata author in mcp/package.json matches the root package. Guarded by tests/mcp-metadata.test.mjs.
Launch:
node mcp/server.mjs [--root /path/to/aesop]Environment variables (override defaults):
AESOP_ROOT— Fleet root directory (default:$HOME/aesop)AESOP_STATE_ROOT— State directory (default:$AESOP_ROOT/state)AESOP_TRANSCRIPTS_ROOT— Transcript directory (default:$HOME/.claude/projects)
Also reads $AESOP_ROOT/aesop.config.json for optional state_root, transcripts_root, config.limits.max_wave_tokens overrides.
Tools (All Strictly Read-Only, No Mutations)
fleet_status
Get daemon/monitor heartbeats, orchestrator status, alert count.
Input: {} (no args).
Output: { watchdog: { alive: "ALIVE"|"STALE", age_seconds, threshold_seconds } | { alive: "MISSING", path } | { alive: "UNKNOWN", reason, path? }, monitor: { ... }, orchestrator: {...}|null, alerts: { count, sample_lines } }.
Design: Watchdog beat is read from CONDUCTOR_ROOT/state/.watchdog-heartbeat (mirrors monitor/collect-signals.mjs resolveWatchdogHeartbeat; CONDUCTOR_ROOT env wins, else sibling conductor3 only when AESOP_ROOT basename is aesop). Never STATE_ROOT: the daemon writes nowhere else. Unresolved root → UNKNOWN; no file → MISSING; unparseable → UNKNOWN. A missing beat is never reported ALIVE. Other missing files → null; never crashes. Monitor heartbeat age computed from file mtime bucketed into brackets.
fleet_agents
List active Claude agents from AESOP_TRANSCRIPTS_ROOT. Invokes dash-extra.mjs --json passthrough with 5s timeout.
Input: {}.
Output: { absent: bool, agents: [{ project, taskLabel, promptFull, runtimeSeconds, tokensUsed, startedAt, lastActivity }] }.
Design: On timeout/error, returns empty agents list (no crash).
fleet_tracker
Get work items by lane from state/tracker.json.
Input: {}.
Output: { absent: bool, by_lane: { ranked: [...], in-progress: [...], done: [...], proposed: [...] } }.
Design: Each item: { id, title, priority: "P0"|"P1"|"P2", status: "todo"|"in-progress"|"done", tags }. Lanes present only if items exist.
fleet_cost
Per-model token totals from ledger (markdown table at state/ledger/OUTCOMES-LEDGER.md).
Input: {}.
Output: { absent: bool, by_model: { "claude-haiku-4": { tokens_in, tokens_out, total_tokens, count }, ... }, total_tokens_in, total_tokens_out }.
Design: Reports token counts only (no dollar figures, no invented costs). Gracefully skips malformed rows.
fleet_cost_by_wave
Per-wave token totals (group by 9th column, "wave"). Same ledger file.
Input: {}.
Output: { absent: bool, by_wave: { "wave-1": { tokens_in, tokens_out, total_tokens, count }, ... }, total_tokens_in, total_tokens_out }.
Design: Parses markdown table. Reports token counts only. Missing/malformed rows skipped (no error).
fleet_budget
Cost budget status: ceiling from config, spent from ledger, remaining headroom, halt status.
Input: {}.
Output: { period: "wave", ceiling: int|null, spent: int, remaining: int|null, halted: bool, halt_reason: string|null, halt_timestamp: string|null }.
Design: Reads config.limits.max_wave_tokens from aesop.config.json (null = unconfigured). Sums all ledger rows. Checks state/.HALT sentinel for halt status. Reports token counts only (no dollars). Gracefully handles missing config or ledger.
fleet_cost_trend
Per-wave token usage trend over the last N waves.
Input: { n: int } (optional, default 10).
Output: { absent: bool, trend: [{ wave, total_tokens, tokens_in, tokens_out, count }, ...], period_count: int }.
Design: Parses markdown ledger table, groups by wave column, returns last N waves in chronological order. If ledger empty/missing, returns absent: true. Reports token counts only (no dollars).
fleet_verify_stats
Defect escape stats (first-try-green rate, fix-forward rate) if available.
Input: {}.
Output: { absent: bool, first_try_green: float|null, fix_forward_rate: float|null, source: string|null }.
Design: Reads pre-computed state/verify-stats.json if available (e.g., generated by tools/defect_escape.py --json output). If file absent, returns absent: true. Gracefully handles missing data.
fleet_instances (NEW — Wave-???)
Get active and stale instances with heartbeat age for multi-instance coordination.
Input: {} (no args).
Output: { absent: bool, reason?: string, instances: [{ id, hostname, pid, status, registered_at, last_heartbeat, heartbeat_age_seconds, stale: bool }], stale_threshold_seconds: int }.
Design: Spawns mcp/instances-claims.py helper (state_store list_active_instances()/detect_stale_instances()); sorted by registration time; stale true when heartbeat age exceeds stale_threshold_seconds (300s); missing state_store returns absent: true with explanation.
fleet_claims (NEW — Wave-???)
Get all current file claims by instance from multi-instance coordination layer.
Input: {} (no args).
Output: { absent: bool, reason?: string, by_instance: { instance_id: [file_path, ...], ... } }.
Design: Spawns mcp/instances-claims.py helper which reads from state_store via state_store.instance_projection.get_all_claimed_files(). Returns a map of instance ID to list of claimed file paths (absolute paths). Only includes instances with active claims (empty claim sets omitted). Missing state_store returns absent: true.
fleet_multibox_summary (NEW — Wave-???)
Dashboard-ready summary of multi-instance status.
Input: {} (no args).
Output: { absent: bool, instance_count: int, active_count: int, stale_count: int, claim_count: int }.
Design: Spawns mcp/instances-claims.py helper, aggregating fleet_instances + fleet_claims counts for a dashboard tile; missing state_store returns all zeros with absent: true.
ci_job_status (NEW)
Query GitHub Actions run history for a CI job: status, conclusion, duration, flake signal.
Input: { job_name: string, branch?: string, lookback_days?: int } (job_name required).
Output: { runs: [{status, conclusion, started_at, duration_s, event}...], never_executed: bool, avg_duration_s: number, failure_rate: number, flake_signal: number }.
Error: { error: string, runs: [] } (structured error, no crash).
Design: Spawns gh run list subprocess with branch and history lookback; no shell:true, with 10s timeout. Parses JSON from gh. Test mode via TEST_GH_MOCK_DATA env var for unit testing. Returns: never_executed: true if no runs found | failure_rate ratio of failures to total runs | flake_signal count of pass/fail alternations (alternation index) | on error (gh missing/auth/network) returns structured error, never crashes.
Multibox Coordination Helper
File: mcp/instances-claims.py (--db <db> [--root <aesop_root>] [--config <path>]) — spawned by the three fleet_instances/fleet_claims/fleet_multibox_summary tools above; resolves coordination backend config via the same precedence as tools/multibox_config (env → aesop.config.json → default) and reports mode (advisory|local-lease|fs-claim-log), transport, shared dir, TTL; read-only (opens the DB mode=ro via ReadOnlyEventSource, never runs DDL/PRAGMA, never creates a missing state.db; tracker e9a72d86760f), structured absent/reason on error. The interpreter is resolved once per process (resolvePython: AESOP_PYTHON, then python3, python, py -3, probed with --version); when none runs the three tools return error (with absent: false, empty arrays), never a silent empty fleet. Tests: tests/mcp-python-resolver.test.mjs.
DB resolution (F-06, 2026-10-14): the instances/claims tools open state.db via INSTANCES_DB_FILENAME (mcp/server.mjs, mirrors state_store/paths.py), the file tools/instance_manager.py writes. aesop.db had no writer and always reported absent. Tracker DB paths resolve through state_store/paths.py::resolve_db_path.
Core Invariants
- Strictly read-only — all tools are read-only; zero state mutations, zero file writes (except dash-extra.mjs invocation, which is sandboxed with timeout).
- No shell execution except the minimal dash-extra.mjs passthrough with 5s timeout — minimizes injection surface.
- JSON-RPC 2.0 compliant — standard request/response framing, proper error codes.
- Graceful absent:true — missing files → empty results with
absent: true, never a crash. - No invented dollars — all cost reporting is tokens only; no fee calculations.
- Node.js stdlib only — server.mjs imports only
fs,path,os,child_process,readline; no npm packages. - Portable paths — all paths resolved from env vars or config; no hardcoded
/home/user/...strings.
Staleness Guarantees
Data is accurate as of the last successful state_store read. SQLite WAL ensures atomic appends and isolated concurrent readers. MCP tools are suitable for operational dashboards (3-5s staleness acceptable); for sub-500ms coordination use direct state_store polling.
Tool List (for MCP clients)
Server registers these tools for tools/list and tools/call:
fleet_status(0 args)fleet_agents(0 args)fleet_tracker(0 args)fleet_cost(0 args)fleet_cost_by_wave(0 args)fleet_budget(0 args)fleet_cost_trend(1 arg:n, default 10)fleet_verify_stats(0 args)fleet_instances(0 args) — NEW: active/stale instances with heartbeatfleet_claims(0 args) — NEW: file claims by instancefleet_multibox_summary(0 args) — NEW: dashboard summaryci_job_status(1 required arg:job_name, 2 optional:branchdefault "main",lookback_daysdefault 30) — NEW: GitHub Actions run history
Testing
Test files:
tests/mcp-fleet.test.mjs— Spawns server over stdio, drives JSON-RPC initialize + tools/list/call round-trips, validates read-only behavior (11 test cases).tests/mcp-ci-status.test.mjs— Tests ci_job_status tool with mocked gh subprocess: normal history, empty history (never_executed), gh failure → structured error (4 test cases).tests/mcp-metadata.test.mjs— Assertsmcp/package.jsonauthor equals root package author and that the live server's initializeprotocolVersionis2025-11-25.
Run: npm run test:node or node --test tests/mcp*.test.mjs.
See /CLAUDE.md for domain map.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

