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/tools/call	Browser-safe route for dashboard read-only tool calls
/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