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

Development

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

Example with Codex

Example with Claude Code

Implementation Details

CLI Invocation Formats

Codex:

Claude:

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