{
  "markdown": "# cryptozavr\n\nRisk-first crypto market research plugin for Claude Code, OpenAI Codex, OpenCode, Cursor, and Gemini CLI. 16 MCP tools over KuCoin and CoinGecko with Supabase-backed cache, realtime cache invalidation, observability, provenance tracking, and auditable reasoning.\n\n## What's in the box\n\n**MCP tools (16)**\n\n*Market data (5)*\n- `get_ticker(venue, symbol, force_refresh)` — last / bid / ask / 24h stats\n- `get_ohlcv(venue, symbol, timeframe, limit, force_refresh)` — OHLCV candles (1m..1w)\n- `get_order_book(venue, symbol, depth, force_refresh)` — bids / asks / spread_bps; KuCoin `depth` snaps to `{20, 100}`\n- `get_trades(venue, symbol, limit, force_refresh)` — recent trade ticks\n- `resolve_symbol(user_input, venue)` — fuzzy symbol resolution\n\n*Analytics (4) + history (1)*\n- `compute_vwap(...)` — VWAP + bars_used + confidence\n- `identify_support_resistance(...)` — swing-pivot S/R + `pivots_found` + cluster means\n- `volatility_regime(...)` — ATR-based classifier (calm/normal/high/extreme)\n- `analyze_snapshot(...)` — composite VWAP + S/R + volatility with one OHLCV fetch\n- `fetch_ohlcv_history(...)` — streaming history with `paginator:clipped_to_window` guarantee\n\n*Catalog (5, `structuredContent` — no escape)*\n- `list_venues`, `list_symbols(venue)`, `list_trending`, `list_categories`, `get_venue_health`\n\n*Plus `echo` for smoke.*\n\n**MCP resources (4 + 1 URI-template)**\n- `cryptozavr://venues`, `cryptozavr://symbols/{venue}`, `cryptozavr://trending`, `cryptozavr://categories`, `cryptozavr://venue_health`\n\n**MCP prompts (2, cross-client portable)**\n- `research_symbol(venue, symbol)` — 4-tool parallel research template\n- `risk_check(venue, symbol)` — data-quality pre-decision check\n\n**Slash commands (8)**\n- `/cryptozavr:ticker`, `/cryptozavr:ohlcv`, `/cryptozavr:research`, `/cryptozavr:resolve`, `/cryptozavr:trending`, `/cryptozavr:analyze`, `/cryptozavr:history`, `/cryptozavr:health`\n\n**Subagent**\n- `crypto-researcher` — multi-step market research specialist (calm, explainable, no advice)\n\n**Skills (4)**\n- `crypto-research` — when-to-invoke + tool-selection matrix\n- `interpreting-market-data` — field-by-field legend + red flags\n- `venue-debug` — walk the 5-layer L2 chain to pinpoint failures\n- `post-session-reflection` — disciplined 3-bullet wrap-up (produced / decided / next)\n\n**SessionStart hook** — prints a plugin-loaded banner with command cheat-sheet and venue health pointer.\n\n**Every response carries**\n- `reason_codes` audit trail (5-handler chain: `venue → symbol → cache → provider`; plus `paginator:clipped_to_window` for streamed history)\n- `staleness` + `cache_hit` — so you always know if data is fresh\n- For catalog & analytics tools — `structuredContent` in the MCP response (no escaped JSON strings)\n\n## Install\n\nPick your platform:\n- [Claude Code](docs/README.claude-code.md)\n- [OpenAI Codex](docs/README.codex.md)\n- [OpenCode](docs/README.opencode.md)\n- [Cursor](.cursor-plugin/README.md)\n- [Gemini CLI](gemini-extension.json) — wired via the same mcpServers config\n\n## Env setup\n\nCopy `.env.example` → `.env` and fill:\n- `SUPABASE_URL` — your Supabase project URL\n- `SUPABASE_SERVICE_ROLE_KEY` — from Dashboard → API Keys → `service_role`\n- `SUPABASE_DB_URL` — PostgreSQL connection string (session pooler, port 5432)\n\nThe cryptozavr MCP server needs Python 3.12 + `uv`. Install with:\n\n    uv sync --all-extras\n\n## Philosophy\n\n1. **Risk-first, not signal-first.** Audit trail + provenance before prediction.\n2. **Calm execution.** Dispassionate, institutional-minded. No FOMO.\n3. **Declarative over ad-hoc.** Settings, thresholds, rate limits in config, not prompts.\n4. **Explainability and auditability.** Every answer contains `data`, `quality`, `reasoning`.\n5. **Safe agent design.** LLM proposes; human approves; deterministic code executes.\n\nSee [docs/superpowers/specs/2026-04-21-cryptozavr-mvp-design.md](docs/superpowers/specs/2026-04-21-cryptozavr-mvp-design.md) for the full MVP design.\n\n## Architecture\n\n- **Domain (L3)** — `src/cryptozavr/domain/`: frozen dataclasses (Ticker, OHLCVSeries, OrderBookSnapshot, TradeTick) + DataQuality envelope.\n- **Infrastructure (L2)** — `src/cryptozavr/infrastructure/`: CCXT adapter (KuCoin) with `trades_to_domain` + `_snap_order_book_depth`, CoinGecko HTTP client with `id→category_id` mapping, Supabase gateway (asyncpg + supabase-py realtime), **5 decorators** (Retry / RateLimit / InMemoryCache / Logging / Metrics), 5-handler chain of responsibility, `MetricsRegistry` (Prometheus-compatible counters + cumulative histograms).\n- **Application (L4)** — `src/cryptozavr/application/services/`: `TickerService`, `OhlcvService`, `OrderBookService`, `TradesService`, `AnalyticsService`, `SymbolResolver`, `DiscoveryService`, plus `HealthMonitor` + `TickerSyncWorker` + `CacheInvalidator` (async tasks started from lifespan).\n- **MCP (L5)** — `src/cryptozavr/mcp/`: FastMCP v3 server with dict-lifespan, 16 tools, 4 + 1-template resources, 2 prompts, `cryptozavr://venue_health` observability endpoint.\n\n**15 GoF patterns** applied: Template Method, Adapter, Bridge, **Decorator (5 layered, incl. MetricsDecorator)**, Chain of Responsibility (5 handlers), State (venue health), Factory Method, Singleton via DI, Flyweight (SymbolRegistry), Facade (SupabaseGateway), Iterator (OHLCVPaginator), Strategy (MarketAnalyzer), plus **Observer** (Supabase Realtime → `CacheInvalidator`).\n\n## Tests\n\n    uv run pytest tests/unit tests/contract -m \"not integration\"   # 440 unit + contract, ~4s\n    uv run pytest tests/integration                                 # 14 live tests, ~40s (needs .env)\n\n## Status\n\n**v0.3.0** — MVP + Phase 1.5 (Realtime + Observability) shipped. `MetricsRegistry`, `HealthMonitor`, `TickerSyncWorker`, `CacheInvalidator`, `venue_health` resource + 5 catalog tools with `structuredContent`. Next: Phase 2 — signals / triggers / alerts with Elicit-based approval flows.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 5940,
  "sha": "99a1cc2a653fc4442dcb29f05e674efa60f18c3cb4be0ce0f38ad939bd003bdb",
  "repo_slug": "evgenygurin/cryptozavr",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_evgenygurin_cryptozavr_dc0742dc/readme"
}