# Oracle MCP Server

A Model Context Protocol (MCP) server that provides a unified interface for consulting oracle AI models (Codex or Claude) via CLI.

## Features

- **Unified Oracle Tool**: Single `consult_oracle` tool that works with either Codex or Claude Code
- **Configurable Models**: Supports custom oracle models and reasoning levels via `~/.oracle-mcp.json`
- **Testable Architecture**: Pure functions for argument construction and CLI invocation
- **Proper Error Handling**: Comprehensive error handling with descriptive messages
- **Type Safe**: Full TypeScript with explicit typing and safe error handling

## Setup

```bash
# Install dependencies
bun install

# Build TypeScript
bun run build

# Run the server
bun run start
```

## Development

```bash
# Run directly with hot reload
bun run dev

# Run test suite
bun test
```

## Tools

### consult_oracle

Consult the oracle for expert reasoning and analysis on complex problems.

**When to use:**
- Planning complex tasks with multiple tradeoffs
- You are ≤90% confident in your approach
- You need analysis of architectural decisions or design patterns

**Parameters:**
- `prompt` (string, required): The question or problem to consult the oracle about. Be specific about context, constraints, and what decision or analysis you need.

**Example prompts:**
- "What's the best approach to structure a TypeScript MCP server for tool integration?"
- "Should we use a monolithic or microservices architecture for this new feature?"
- "What are the tradeoffs between different error handling patterns?"

## Configuration

The server reads `~/.oracle-mcp.json` if it exists to customize behavior. If the file doesn't exist, defaults are used.

### Default Configuration
```json
{
  "model": "gpt-5.1-codex-mini",
  "reasoning": "medium",
  "command": "codex"
}
```

### Example with Codex
```json
{
  "oracle": {
    "model": "gpt-5.1-codex-mini",
    "reasoning": "high",
    "command": "codex"
  }
}
```

### Example with Claude Code
```json
{
  "oracle": {
    "model": "opus",
    "command": "claude"
  }
}
```

## Implementation Details

### CLI Invocation Formats

**Codex:**
```
codex exec --model <model> [-c reasoning_level=<level>] "<prompt>"
```

**Claude:**
```
claude -p --model <model> "<prompt>"
```

### Architecture

- **Single-file server** (`src/index.ts`) implementing the MCP protocol
- **Pure functions** for testability:
  - `buildOracleArgs()`: Constructs CLI arguments as an array (avoiding shell escaping issues)
  - `invokeOracle()`: Executes CLI via `spawnSync` and returns structured result
- **MCP Handlers**:
  - `ListToolsRequestSchema`: Describes `consult_oracle` tool with dynamic descriptions based on config
  - `CallToolRequestSchema`: Handles tool invocation, captures stdout, and returns properly formatted responses
- **Error Handling**: Try-catch with fallback to `String(error)` for non-Error objects
- **Response Format**: All responses wrapped as `{ content: [{ type: "text", text: string }], isError?: boolean }`

### Dependencies

- `@modelcontextprotocol/sdk`: Official MCP protocol implementation and stdio transport

### Testing

Comprehensive test suite (42+ tests) covering:
- Argument construction for both Codex and Claude
- Special character handling (quotes, backticks, dollar signs, newlines)
- Configuration loading and defaults
- Tool description generation
- Error handling and response formatting
- Type safety and MCP protocol compliance