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

# Install dependencies
bun install

# Build TypeScript
bun run build

# Run the server
bun run start

Development

# 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

{
  "model": "gpt-5.1-codex-mini",
  "reasoning": "medium",
  "command": "codex"
}

Example with Codex

{
  "oracle": {
    "model": "gpt-5.1-codex-mini",
    "reasoning": "high",
    "command": "codex"
  }
}

Example with Claude Code

{
  "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