AGENTS.md•3.65 kB
# Agent Guidelines for oracle-mcp
## Build & Run Commands
- `bun install` - Install dependencies
- `bun run build` - Compile TypeScript to dist/
- `bun run dev` - Run server with hot reload
- `bun run start` - Run compiled server
- `bun test` - Run test suite
## Architecture
Single-file MCP server (src/index.ts) that provides one tool for consulting an oracle AI model via CLI:
- **consult_oracle**: Invokes any of:
- `codex exec --model <model> [-c reasoning_level=<level>] "<prompt>"` (for Codex)
- `gemini -p --model <model> "<prompt>"` (for Gemini)
- `claude -p --model <model> "<prompt>"` (for Claude Code)
Tool usage: For planning complex tasks or when <=90% confident on the best approach.
Uses @modelcontextprotocol/sdk for MCP protocol implementation and stdio transport.
## Configuration
The server reads `~/.oracle-mcp.json` if it exists to customize oracle models, reasoning support, and command names. Supports:
- Single oracle: `oracle` field (backward compatible)
- Multiple oracles with fallback: `oracles` array (tries each oracle in sequence on failure)
- Multiple models per oracle: each oracle can have `models` array (tries each model within oracle before moving to next oracle)
- Backward compatible: still accepts single `model` field (normalized to `models` array internally)
Default (when no config exists): single Codex oracle with models=["gpt-5.1-codex-mini"], reasoning=medium
Example `~/.oracle-mcp.json` with single Codex:
```json
{
"oracle": {
"model": "gpt-5.1",
"reasoning": "high",
"command": "codex"
}
}
```
Example with fallback chain (tries Codex, then Gemini, then Claude):
```json
{
"oracles": [
{
"model": "gpt-5.1-codex-mini",
"reasoning": "medium",
"command": "codex"
},
{
"model": "gemini-2.5-pro",
"command": "gemini"
},
{
"model": "opus",
"command": "claude"
}
]
}
```
Example with multiple models per oracle (tries gpt-5.1, then gpt-5.1-codex-max within Codex):
```json
{
"oracles": [
{
"models": ["gpt-5.1", "gpt-5.1-codex-max"],
"reasoning": "medium",
"command": "codex"
},
{
"models": ["gemini-2.5-pro", "gemini-1.5-pro"],
"command": "gemini"
},
{
"models": ["opus", "sonnet"],
"command": "claude"
}
]
}
```
Example with single Gemini:
```json
{
"oracle": {
"model": "gemini-2.5-pro",
"command": "gemini"
}
}
```
Example with single Claude:
```json
{
"oracle": {
"model": "opus",
"command": "claude"
}
}
```
## Code Style
- **Language**: TypeScript (ES2020, ESNext modules)
- **Imports**: Use ES6 imports with absolute paths to .js files
- **Types**: Use `as const` for string literals, explicit Record<string, unknown> for dynamic objects
- **Error Handling**: Use try-catch with error.message || String(error) fallback
- **Naming**: camelCase for functions/variables, snake_case for tool/schema names
- **Tool Definitions**: JSON schemas with `type: "object"`, explicit `properties` and `required` fields
- **Formatting**: 2-space indents via prettier (via tsconfig implicit)
- **Return Types**: Wrap tool responses in `{ content: [{ type: "text", text: string }], isError?: boolean }`
## Testing
- **Test Framework**: Bun test (built-in)
- **Test Files**: `src/**/*.test.ts`
- **Coverage**: 84+ tests across pure functions, MCP protocol handlers, error handling, and response formatting
- **Pure Functions**: `buildOracleArgs()` and `invokeOracle()` are fully tested without mocking
- **No Integration Tests**: Real CLI invocation tests validate return structure only (don't call actual oracle)