# CLAUDE.md

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

## Project Overview

Nexus MCP is a Model Context Protocol server providing AI-powered web search via OpenRouter's Perplexity Sonar models. It's designed for zero-install deployment via `npx nexus-mcp`.

## Essential Commands

```bash
bun run dev              # Watch mode with type checking
bun run build            # Production build
bun run test             # Full test suite (unit + integration)
bun run test:unit        # Unit tests only
bun run test:watch       # Watch mode for development

# Single test execution
bun run test -- tests/unit/clients/openrouter.test.ts
bun run test -- --grep "OpenRouter"
```

## Architecture

### Request Flow

```
Client Request → STDIO Transport → MCP Server (src/index.ts)
    → Correlation ID → Input Validation (Zod) → Deduplication → Cache Check
    → OpenRouter Client (src/clients/openrouter.ts) → Response Optimization
    → Structured Response with Metadata
```

### Key Directories

- `src/index.ts` - MCP server entry point with tool/resource handlers
- `src/tools/search.ts` - Search tool with caching, deduplication, retry logic
- `src/clients/openrouter.ts` - OpenRouter API client with error handling
- `src/config/` - Configuration management with JSON schema validation
- `src/utils/` - Shared utilities (caching, deduplication, error handling, logging)
- `src/schemas/` - Zod validation schemas
- `src/types/` - TypeScript type definitions

### Testing Structure

- `tests/unit/` - Component tests with mocking
- `tests/integration/` - End-to-end MCP server tests
- `tests/fixtures/` - Test data and mock responses
- Coverage threshold: 80%

## Environment Variables

- `OPENROUTER_API_KEY` - Required for OpenRouter API access
- `NODE_ENV` - Environment (development, production, test)
- `LOG_LEVEL` - Logging verbosity (debug, info, warn, error)