Market Inspector

Market Inspector is a multi-asset market intelligence workflow built with Next.js 16, the Model Context Protocol (MCP), and Gemini 3.5 Flash. It monitors cryptocurrency movements, combines them with current equity data and ECB foreign-exchange reference rates, and produces structured market briefs.

The project was created for the Google × Kaggle AI Agents Intensive capstone, in the Agents for Business track.

System overview

Market Inspector exposes 11 MCP tools:

• 4 cryptocurrency tools
• 3 equity tools
• 3 foreign-exchange tools
• 1 zero-cost system status tool

Three coordinated roles divide the workflow:

| Role | Responsibility | |---|---| | Anomaly Detector | Scans the top cryptocurrency assets and classifies significant 24-hour movements. | | Orchestrator | Serializes scans, stores the latest in-memory state, and publishes updates through Server-Sent Events. | | Brief Generator | Provides Gemini with a seven-result market snapshot and eight optional MCP tools for additional context. |

Market-data fallbacks:

• Crypto price: CoinGecko → Binance when CoinGecko is rate-limited.
• Crypto global data and top movers: CoinGecko → CoinPaprika.
• Equity quotes and candles: Finnhub → Alpha Vantage → Yahoo Finance.
• Foreign exchange: Frankfurter using ECB reference rates.

Asset coverage

| Asset class | Dashboard | Automatic anomaly detection | Gemini snapshot | |---|---|---|---| | Cryptocurrency | Global metrics, top movers, ticker | Yes, every 60 seconds | Global market and top 10 assets | | Equities | Six large-cap technology quotes and ticker | No | AAPL, MSFT, NVDA, GOOGL | | Foreign exchange | Seven USD reference rates | No | USD against EUR, GBP, JPY, CHF |

Quick start

Requirements:

• Node.js 22.x
• pnpm 10.34.4

git clone https://github.com/dcosodev/market-inspector.git
cd market-inspector
corepack enable
pnpm install --frozen-lockfile
cp .env.local.example .env.local
pnpm dev

The application is available at http://localhost:3000.

Environment variables

| Variable | Purpose | Required | |---|---|---| | GEMINI_API_KEY | Manual AI briefs and the chat endpoint | For Gemini features | | FINNHUB_API_KEY | Primary equity source | Recommended | | ALPHA_VANTAGE_API_KEY | Secondary equity fallback | Optional | | LOG_LEVEL | Structured JSON logging threshold | Optional (info) | | ENABLE_PUBLIC_CHAT | Enables /api/chat in production when set to true | Optional (false) |

Yahoo Finance provides the final no-key equity fallback. CoinGecko, CoinPaprika, Binance, and Frankfurter also require no key.

Main routes

| Route | Purpose | |---|---| | / | Project overview | | /dashboard | Market dashboard and architecture view | | /api/mcp | MCP Streamable HTTP endpoint | | /api/anomalies | Current state and manual AI scan stream | | /api/stream | Continuous anomaly-state SSE stream | | /api/chat | Optional Gemini chat backed by the MCP tool catalog; disabled in production unless ENABLE_PUBLIC_CHAT=true | | /api/health | Zero-cost service health response; no external API calls |

Agent workflow

1. The deterministic detector scans cryptocurrency movements without calling Gemini.
2. A manual AI scan refreshes anomalies and preloads seven market-data results.
3. Gemini receives the snapshot and can request one or more of eight selected MCP tools when additional context is needed.
4. Execution progress, requested tools, and the final informational brief are streamed to the dashboard.
5. Source-level rate limits, caching, circuit breaking, and fallbacks reduce the effect of upstream failures.

The dashboard stores a four-scan daily demonstration quota in localStorage. The server applies a matching four-scan in-memory per-client limit over a 24-hour window. Each notable-anomaly scan uses one to five Gemini requests, so the visible worst-case budget is twenty calls. This deliberately lightweight control conserves the demo allowance; it is a demo mitigation, not authentication, billing enforcement, or a hard global limit.

Generated briefs are informational only and are not personalized financial advice. Provider data, tool output, and user text are delimited as untrusted model context.

Verification

pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm exec playwright install chromium
pnpm test:e2e

Gemini evaluation is manual and never runs in CI:

RUN_GEMINI_EVALS=1 EVAL_CASE=broad-crypto-selloff pnpm eval:gemini

Documentation

• Documentation overview
• Architecture
• Code reference
• Product specification
• BDD acceptance scenarios
• Design contract
• Repository agent rules
• Deterministic engineering protocol
• Project context skill
• Code conventions skill
• MCP tool pattern skill
• Market data API clients skill
• Gemini integration skill
• Multi-agent pattern skill
• React/Next dashboard design skill
• Code review and evaluation skill
• Manual Gemini evaluation rubric
• Code-review evaluation rubric
• Synthetic code-review calibration cases

Deployment

The repository includes a Vercel configuration for the Frankfurt region. Configure the required environment variables in the deployment platform; API keys must not be committed to the repository.

License

MIT