Skip to content

CLAUDE.md

Latest commit

 

History

History
139 lines (105 loc) · 4.61 KB

CLAUDE.md

File metadata and controls

139 lines (105 loc) · 4.61 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an MCP (Model Context Protocol) server that provides access to the Prediction Market Metadata API. The server wraps the REST API defined in llms_dflow.json and exposes it as MCP tools for use with Claude Desktop, Cursor, and other MCP clients.

Base API URL: https://prediction-markets-api.dflow.net

Commands

Development

# Start server in development mode with hot reload
bun run dev

# Start server in production mode
bun start

# Build the project
bun run build

# Run tests
bun run test

Running the server directly

bun run src/index.ts

Architecture

Single-File MCP Server

The entire server implementation is contained in src/index.ts. This is intentional for simplicity - the server is a thin wrapper around the external API.

Key components:

  1. DFlowAPIClient (lines 23-85): HTTP client that handles all API communication

    • Implements request timeout handling (30s default)
    • Constructs URLs with query parameters
    • Handles GET and POST requests
    • Returns parsed JSON responses

  2. TOOLS array (lines 103-696): Complete tool definitions

    • Each tool maps to one API endpoint
    • Tool definitions include JSON schemas for parameter validation
    • Organized by endpoint category (events, markets, trades, forecasts, candlesticks, live data, series, utilities)

  3. Request handlers (lines 698-849):

    • ListToolsRequestSchema: Returns all available tools
    • CallToolRequestSchema: Routes tool calls to appropriate API endpoints using a large switch statement
    • Error handling returns descriptive messages

API Endpoint Categories

The server exposes 25 tools across 8 categories:

  • Events: Get individual events, paginated event lists, search events
  • Markets: Get markets by ticker or mint address, batch queries
  • Trades: Query trade history with filtering and pagination
  • Forecasts: Historical forecast percentile data
  • Candlesticks: OHLC data for events and markets
  • Live Data: Real-time milestone information
  • Series: Series templates and metadata
  • Utilities: Outcome mints, filtering, tags, and search

MCP Transport

The server uses stdio transport (line 853), which is the standard for MCP servers. This means:

  • Communication happens over stdin/stdout
  • The server must be launched as a subprocess by the MCP client
  • No HTTP server or network configuration needed

Configuration Files

  • package.json: Dependencies include @modelcontextprotocol/sdk for MCP protocol implementation
  • tsconfig.json: Standard TypeScript config targeting ES2022 with ESNext modules and bundler resolution
  • llms_dflow.json: OpenAPI specification for the underlying REST API (not used at runtime, serves as documentation)
  • bun.lock: Bun's lockfile (not bun.lockb, this is a text-based lock format)
  • .gitignore: Standard Node.js gitignore that excludes node_modules, dist, logs, and environment files

Tool Implementation Pattern

When adding or modifying tools, follow this pattern:

  1. Add tool definition to TOOLS array with name, description, and inputSchema
  2. Add corresponding case to the switch statement in the CallToolRequestSchema handler
  3. Use apiClient.get() or apiClient.post() to make the API request
  4. Extract path parameters from args and pass remaining args as query params or request body

Example:

// Tool definition
{
  name: 'get_event',
  description: 'Get a single event by ticker',
  inputSchema: {
    type: 'object',
    properties: {
      event_id: { type: 'string', description: 'Event ticker' },
      withNestedMarkets: { type: 'boolean', description: 'Include nested markets' }
    },
    required: ['event_id']
  }
}

// Handler implementation
case 'get_event':
  result = await apiClient.get(`/api/v1/event/${args.event_id}`, {
    withNestedMarkets: args.withNestedMarkets,
  });
  break;

Testing the Server

To test the server manually with MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "dflow-mcp": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/dflow-mcp/src/index.ts"]
    }
  }
}

Key Technical Details

  • Runtime: Designed for Bun but compatible with Node.js 18+
  • MCP SDK Version: @modelcontextprotocol/sdk ^0.5.0
  • Request Timeout: 30 seconds (configurable via DEFAULT_TIMEOUT)
  • Error Handling: HTTP errors and timeouts are caught and returned as MCP error responses
  • JSON Serialization: Handles BigInt values by converting to strings