README.md•3.46 kB
# 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