polybrain-mcp: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

Polybrain MCP Server is a stateless HTTP-based Model Context Protocol (MCP) server that enables communication with multiple LLM models. It maintains per-request conversation isolation with application-level conversation state management.

Architecture

Core Components

1. HTTP Server (src/http-server.ts): Express-based stateless server using StreamableHTTPServerTransport

   • Creates a new transport instance per HTTP request (stateless design)
   • Accepts POST requests to /mcp endpoint with Accept: application/json, text/event-stream header
   • Returns JSON responses directly in HTTP body (not SSE streams)
   • Cleans up transport on request completion

2. MCP Server (src/index.ts): Initializes and manages the MCP server

   • Registers tools: chat, list_models, conversation_history
   • Handles both HTTP transport (stateless mode) and stdio transport

3. Conversation Manager (src/conversation-manager.ts): In-memory conversation storage

   • Maps conversation IDs to message history
   • Handles conversation cloning when switching models mid-conversation
   • Supports message truncation for context management

4. OpenAI Client (src/openai-client.ts): LLM API integration

   • Supports any OpenAI-compatible API endpoint (OpenRouter, Azure, local servers)
   • Per-model API keys from configuration
   • Handles reasoning/extended-thinking responses (optional)

5. Configuration (src/config.ts): Dual-mode config system

   • Simple environment variables (single model): POLYBRAIN_BASE_URL, POLYBRAIN_API_KEY, POLYBRAIN_MODEL_NAME
   • YAML configuration (multiple models): ~/.polybrain.yaml or POLYBRAIN_CONFIG_PATH
   • Environment variable substitution in YAML: ${ENV_VAR_NAME}

Critical Design: Stateless HTTP Protocol

The server uses StreamableHTTPServerTransport with these key settings:

• sessionIdGenerator: undefined - No session persistence
• enableJsonResponse: true - Returns JSON responses instead of SSE streams
• Per-request transport lifecycle - Each HTTP request gets a fresh transport instance