prediction-mcp: Instructions file for Claude Code

Prediction Markets MCP Server

For users: Install via npm with npx prediction-mcp. See README.md for setup instructions.

This file is for contributors developing the server itself.

API Reference

Always consult these docs when working with platform APIs:

Platform	Documentation
Kalshi	https://docs.kalshi.com/api-reference
Polymarket Gamma	https://docs.polymarket.com/developers/gamma-markets-api/overview
Polymarket CLOB	https://docs.polymarket.com/#clob-api
MCP Protocol	https://modelcontextprotocol.io/specification

Development Workflow

Testing Changes

All functional changes must be tested by invoking the MCP tools directly.

1. Run bun run scripts/bootstrap.ts to register your worktree's server in .mcp.json
2. Exit and resume your Claude Code session — the server won't reload until restart
3. Invoke the tools you modified to verify they work correctly
4. Run bun test to ensure all tests pass

Critical: Session Restart Required

MCP servers are loaded when the Claude Code session starts. If you:

• Add MCP config for the first time
• Update server code and need to test changes
• Modify tool definitions or handlers

You must exit and resume the session to load the updated server.

The bootstrap script reminds you of this, but it's easy to forget when iterating on code changes.

Worktree Setup

Each git worktree needs its own .mcp.json pointing to its index.ts:

cd /path/to/your-worktree
bun install
bun run scripts/bootstrap.ts
# Exit and resume Claude Code session

Architecture

index.ts                    Server entry point
src/
  clients/
    kalshi.ts               Kalshi SDK wrapper with bulk fetch
    polymarket.ts           Gamma API (REST) + CLOB SDK
  search/
    index.ts                Exports for search module
    cache.ts                Kalshi tokenized search with scoring
    service.ts              Kalshi search: lazy init, refresh
    polymarket-cache.ts     Polymarket tokenized search cache
    polymarket-service.ts   Polymarket search service
    scoring.ts              Shared scoring utilities
  env.ts                    Environment config (Zod + t3-env)
  logger.ts                 Pino logger configuration
  tools.ts                  MCP tool handlers
  validation.ts             Zod v4 schemas (generate JSON Schema)
scripts/
  bootstrap.ts              Register server with MCP clients
  docs.ts                   Generate/check docs (subcommands)
docs/                       Auto-generated—do not edit