jquants-mcp: Instructions file for Claude Code

CLAUDE.md

Project Overview

jquants-mcp is an MCP server that retrieves Japanese stock market data via J-Quants API v2. The server is stdio-only and is built on the official mcp SDK's mcp.server.fastmcp.FastMCP (server.py + tools/). The standalone FastMCP v3 package (fastmcp) is no longer a dependency: its last in-repo users — the HTTP/OAuth surface (auth.py, settings/, oauth_kv_store.py, the non-stdio branch of run_server()) and scripts/smoke_test.py's client — were deleted or ported to the official SDK in #568. httpx, SQLite cache. Multi-user OAuth is terminated upstream by the Cloud Run gateway (oauth2-proxy + mcp-stdio serve), not in this process — see "Deployment Targets".

Commands

uv sync --dev          # Install dependencies
uv run pytest -v       # Run tests
uv run ruff check src/ tests/   # Lint
uv run ruff format src/ tests/  # Format

uv run python scripts/smoke_test.py            # Exercise every tool against real data
uv run python scripts/smoke_test.py --only earnings --traceback   # Debug one tool

Architecture

• src/jquants_mcp/ — Main package
  • server.py — Official-SDK FastMCP server (stdio), per-user client management, tool registration
  • client.py — httpx async client with rate limiting, retry, pagination
  • config.py — configparser + env vars hybrid configuration
  • cache/store.py — 2-tier SQLite cache (Tier1: row-level, Tier2: response-level with TTL); background PRAGMA quick_check integrity verification (verify_and_record) with a (dev, ino)-keyed sidecar (cache.db.verified.json) so a fresh per-message CacheStore reuses a prior generation's verdict instead of re-running the multi-second check on every claude.ai message
  • tools/ — Tool modules registered via register(mcp, get_client, get_cache) pattern
  • crypto.py — AES-256-GCM encryption for user API keys
  • db/users.py — Per-user API key storage (SQLite, encrypted)
  • validators.py — Input validation (code, date, sector)
  • allowlist.py — JQUANTS_ALLOWED_EMAILS gate; the gateway-injected principal is the verified email, so server.py passes it straight to is_email_allowed
  • request_context.py — Request-scoped plan contextvar; read by CacheStore._effective_plan as a fallback before its plan_resolver (see below), so each user's plan date window applies without threading plan through tools
• scripts/ — Operational scripts
  • daily_fetch.py — Daily data fetch (cron / scheduled-task companion for cache population)
  • bulk_fetch_all.py — Historical data bulk fetch via J-Quants Bulk API
  • gcs_sync.py — Cloud Run cache.db startup download from GCS (--init-cache). Skips the download (and the atomic replace that always allocates a new inode, which would invalidate CacheStore's (dev, ino) integrity sidecar) when the GCS generation of the effective object -- whichever cache.db.zst/cache.db the zst-then-fallback precedence would actually use -- is unchanged since the last successful download, tracked in a cache.db.generation.json sidecar. On Cloud Run that skip is dormant since #584 removed the periodic poll it was written for (a cold start always starts from an empty cache dir), but it stays correct and load-bearing for repeat --init-cache runs against a populated dir. Auth DBs are no longer synced here: users.db/oauth_state.db moved to Firestore on Cloud Run, so _DOWNLOAD_FILES/_UPLOAD_FILES are empty and --init/--daemon are auth-DB no-ops
  • gcs_export_cache.py — Export cache.db to GCS (used by the daily publisher)
  • verify_cache.py — Stand-alone cache-integrity prewarm CLI: runs the same verify_and_record quick_check the CacheStore sidecar uses, ahead of the next request, so a freshly downloaded cache.db already has a warm (dev, ino) sidecar by the time the first per-message child process connects. Invoked by entrypoint-stdio.sh (backgrounded after the synchronous startup download)
  • rotate_encryption_key.py — Re-encrypt user API keys during MCP_ENCRYPTION_KEY rotation
  • collect_metrics.py / load_test.py — Cloud Run sizing helpers
  • smoke_test.py — Live smoke test: runs every registered tool against real data (in-process, or --url against a deployment) and fails on empty/stale/error answers. smoke_harness.py is the server-agnostic engine; smoke_probes.py holds the per-tool specs. Needs a populated cache + API key, so it runs on the host that has them — not in CI. CI enforces only the coverage half (tests/test_smoke_probes.py: a new tool without a probe spec fails the build)
  • entrypoint-compose.sh — the Dockerfile's default ENTRYPOINT, for the self-hosted compose.yml path. Runs mcp-stdio serve in front of the stdio server with no OAuth and no GCS; auth is an optional static bearer token read from MCP_STDIO_SERVE_TOKEN. Replaced the streamable-http entrypoint.sh, which had crash-looped since #566 (#601). Refuses to start when K_SERVICE is set — booting it on Cloud Run would publish an unauthenticated /mcp behind oauth2-proxy's skip-auth route for /mcp
  • entrypoint-stdio.sh — Docker/Cloud Run entrypoint for the jquants service (mcp-stdio serve, behind an oauth2-proxy sidecar); downloads cache.db synchronously at startup, then backgrounds verify_cache.py to warm the integrity sidecar. It has no in-container refresh mechanism (#584 removed the 15-minute cache-poll.crontab supercronic poll): with min-instances=0 every cold start already re-downloads a current cache.db, and the only window a refresh could help is an instance staying warm across the publisher's once-a-weekday export. There, not-yet-cached days fall through to the live API (correct, just slower), while corrections to already-cached rows do not — the cache-vs-API decision is presence-based and Tier 1 get_rows applies no TTL, so a restated statement or retroactive split adjustment stays stale until the instance recycles (measured lifetimes 15-26 min under min-instances=0, i.e. the same order as the 15-minute poll it replaces). The retired entrypoint.sh's Pub/Sub-pushed reload route has no equivalent here because a stdio-only server exposes no HTTP route for a push to land on; push-based alternatives were designed and rejected as not worth the moving parts (see #584)
• tests/ — pytest + pytest-asyncio tests (1272 tests as of 2026-08, after the HTTP/OAuth removal in #568)