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