mcp-metsuke-crunchtools

Stateful reports catalog MCP server. Metsuke (目付 — the Sengoku intelligence officer who gathered field reports and compiled them for the daimyō) is the durable, cross-agent home for report definitions and their gathered outputs.

An autonomous gatherer reads a definition, sweeps the configured sources, and writes findings — each carrying its own source URL. A compiler later reads the freshest output to draft a fully cited report. This replaces ad-hoc, run-scoped research caches with a real, queryable store.

Features

• Definitions + outputs — separate what-to-gather from what-was-gathered
• Built-in scheduler — Metsuke fires each definition's gather when its cron schedule comes due, or on demand via trigger_report — no external timer
• Run lifecycle — every fire opens a durable run with a second-granularity run_id: a provisional row is recorded before the callback (a fire is never lost), and a per-report concurrency lock keeps two gathers from racing
• Cited findings — payloads carry per-finding source URLs for one-click checking
• Re-homeable gathering — owner_agent makes the gatherer identity data, not code
• Local-first — plain SQLite (WAL), no external services, no per-seat fees
• Three transports — stdio, SSE, streamable-http

Install

uvx (recommended)

uvx mcp-metsuke-crunchtools

pip

pip install mcp-metsuke-crunchtools

Container

podman run --rm -v ~/.local/share/mcp-metsuke:/data:Z \
  quay.io/crunchtools/mcp-metsuke \
  --transport streamable-http --host 0.0.0.0 --port 8009

Claude Code Integration

claude mcp add mcp-metsuke-crunchtools -- uvx mcp-metsuke-crunchtools

Tools (10)

Definitions (4)

Outputs (6)

Environment Variables

The scheduler runs only under the sse and streamable-http transports (the long-lived production processes), never under stdio.

Data Model

• report_definitions — name (PK), gather_prompt, owner_agent, schedule (cron), timezone (IANA), source_config (JSON), last_fired_at, updated_at
• report_outputs (one row per run) — id, report_name (FK), run_id (second-granularity identity), trigger (scheduled/manual/direct), gathered_at, finished_at, window_start/window_end, payload (JSON findings with source URLs), status (gathering/ready/compiled/failed), gatherer_run_ref, detail. A partial unique index on (report_name) WHERE status='gathering' is the per-report concurrency lock.

MCP Registry

io.github.crunchtools/metsuke

License

AGPL-3.0-or-later

Sweeps

A definition can opt into a deterministic pre-gather by adding sweep to its source_config:

{"sweep": {"timezone": "America/New_York", "window_hour": 6, "steps": [
  {"section": "slack", "collector": "slack_waiting",
   "options": {"user_id": "U9VN3S1ST", "handle": "smccarty"}},
  {"section": "work_email", "collector": "gmail_waiting",
   "options": {"backend": "gw-work", "account": "smccarty@redhat.com"}},
  {"section": "calendar", "collector": "calendar_day",
   "options": {"backend": "gw-work", "account": "smccarty@redhat.com"}},
  {"section": "rss", "collector": "feed_entries",
   "options": {"categories": {"1": 20, "5": 20}}}]}}

On fire, Metsuke runs each step in order through the Trentina gateway (as its own read-only profile), stores the results on the run, then dispatches the callback with sweep_status. The gatherer reads records with get_sweep instead of calling the sources, so the gathering LLM only selects, phrases and delivers. A failing step is recorded and the sweep continues. Results Trentina flags are stored as metadata only, with their text withheld.

Collector options

Every step is {"section": "<name>", "collector": "<collector>", "options": {...}}. Section names are [a-z0-9_-], unique, up to 12 steps. Top-level timezone (IANA, default America/New_York) and window_hour (0-23, default 6) set the window: from that hour on the previous weekday until the run.

Collectors are code in sweep/collectors.py, not configuration: a definition can only pick and parameterize them. A bad spec is rejected at upsert_definition time.