S&P 500 MCP Server

S&P 500 MCP Server

An MCP (Model Context Protocol) server and Next.js web app for querying S&P 500 company data from Supabase. It exposes MCP tools for company fundamentals, annual financial metrics, historical price data, news sentiment, officers, and SEC filings, plus a web UI and embedded MCP App resources for browsing and testing those tools.

Tools

search_companies is an internal symbol resolver, not an exposed MCP tool. User queries are resolved through getCompanySymbol.

Tech Stack

• Workspace: pnpm 10.33.3 + Turborepo
• Runtime: Node 22 (.nvmrc)
• Web app: Next.js 16 App Router, React 19, TypeScript strict mode (apps/web)
• MCP Apps: Vite single-file React pages built from apps/web-app and served as tool UI resources
• MCP: mcp-handler at apps/web/app/[transport]/route.ts; /sse is the public SSE endpoint
• Database: Supabase client at apps/web/app/[transport]/utils/supabase.ts
• UI: shared shadcn/Tailwind primitives in packages/ui

Getting Started

Prerequisites

• Node.js 22
• pnpm 10
• Supabase project with the S&P 500 data tables used by the tools

Local Development

1. Install dependencies:

pnpm install

2. Create a local env file with Supabase credentials:

SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key
MCP_MAX_DURATION=60
REDIS_URL=your_redis_url
LOGO_DEV_TOKEN=your_logo_dev_publishable_key

SUPABASE_URL and SUPABASE_ANON_KEY are required. REDIS_URL is only needed for production SSE. LOGO_DEV_TOKEN is required for the /api/logo/* proxy.

3. Build the embedded MCP App HTML resources:

pnpm --filter @apps/web-app build

4. Start the apps:

pnpm dev

The Next.js web app runs on http://localhost:3000; the MCP endpoint is http://localhost:3000/sse. The apps/web-app dev server proxies /sse to port 3000 when run separately.

Commands

pnpm dev        # Start apps/* dev tasks via Turbo
pnpm build      # Build apps/web and apps/web-app via Turbo
pnpm start      # Start production server for apps/web
pnpm type-check # Type-check apps/web and apps/web-app
pnpm lint       # ESLint + Prettier rule checks

Focused commands:

pnpm --filter @apps/web dev
pnpm --filter @apps/web-app dev
pnpm --filter @apps/web-app build
pnpm exec tsc -p apps/web/tsconfig.json --noEmit
pnpm exec tsc -p apps/web-app/tsconfig.json --noEmit
pnpm exec tsc -p packages/ui/tsconfig.json --noEmit

Testing

Tests are integration tests that connect a real MCP client to http://localhost:3000/sse, so start the dev server first:

pnpm --filter @apps/web-app build
pnpm dev
pnpm test

Run a single tool test:

pnpm vitest run apps/web/tests/tools/get-company-info-tool.test.ts

Generate coverage:

pnpm coverage

Project Layout

apps/web/
  app/[transport]/route.ts      MCP GET/POST/DELETE handler
  app/[transport]/tools/        MCP tool registrations
  app/[transport]/utils/        Supabase, symbol resolution, summaries
  app/api/tools/call/route.ts   HTTP proxy for the web tool tester
  app/tools/                    Tool catalog page
  components/                   App-specific UI
  tests/tools/                  MCP integration tests
apps/web-app/
  src/pages/                    Embedded MCP App pages, one per tool
  src/components/               MCP App UI components
  scripts/build-pages.js        Builds each page into dist/*.html
  dist/                         Generated single-file HTML resources
packages/ui/
  src/components/               Shared shadcn UI primitives
  src/styles/globals.css        Shared Tailwind CSS

apps/web/app/[transport]/tools/app-resource.ts reads generated HTML from apps/web-app/dist, so rebuild apps/web-app after changing embedded MCP App pages.

Vercel Deployment

• Requires Fluid compute
• MCP_MAX_DURATION defaults to 60; set a higher duration for long-running production calls when your Vercel plan supports it
• SSE is enabled (disableSse: false); production SSE requires Redis via REDIS_URL

Docs

Full guides and examples: https://sp500-mcp.vercel.app/

Contributing

Feel free to dive in! Open an issue or submit PRs.

Standard Readme follows the Contributor Covenant Code of Conduct.

Contributors

This project exists thanks to all the people who contribute.

License

GNU Affero General Public License v3.0 © MichaelSun