Oracle MCP Tool Standards

This document defines the standardization layer for all Oracle MCP tools, ensuring consistency, quality, and maintainability across the current 60-tool surface.

Architecture

Tool Registration

All tools are registered directly via server.registerTool() in each category module under src/mcp/tools/. Each module exports a createToolDefinitions() function that returns an array of tool definitions, collected and registered in src/mcp/server.ts.

interface ToolDefinition {
  name: string;                          // oracle_*
  category: ToolCategory;                // 'consult' | 'memory' | 'docs' | ...
  title: string;                         // Short title
  description: string;                   // Full description
  inputSchema: z.ZodType<any>;          // Zod validation schema
  outputSchema: z.ZodType<any>;         // Output validation schema
  keywords?: string[];                   // Search keywords
  rateLimitPerMin?: number;              // Rate limiting
  cacheable?: boolean;                   // Memoization support
  handler: (input: any) => Promise<any>; // Implementation
}

Error Handling

Errors use OracleError / serializeOracleError from src/errors.ts, returning { code, message, detail, context }:

import { OracleError, serializeOracleError } from "../../errors.js";

if (!skillRegistry.has(skillName)) {
  throw new OracleError(
    "INVALID_SKILL",
    `Unknown skill: ${skillName}`,
    `Run oracle_skills to see available options`,
    { available: skillRegistry.names() }
  );
}

Caching Layer

ToolCache memoizes expensive operations (skill lookup, docs search, wiki builds) with a configurable TTL:

const cache = new ToolCache(); // 5min default TTL

const skills = await cache.getOrCompute(
  "skills-list",
  () => skillRegistry.list(),
  5 * 60 * 1000
);
cache.invalidatePattern("skill-.*");

Tool Categories

1. Ask & Agent (5 tools)

Standards (oracle_ask):

Standards (oracle_agent):

2. Memory (18 tools)

Standards:

3. Messaging (8 tools)

Standards:

4. Task Planning & Tracking (8 tools)

Standards:

5. Docs (4 tools)

Standards:

6. Web (3 tools)

Standards:

7. Identity (3 tools)

Standards:

8. Oracle Profiles (3 tools)

Standards:

9. Session (4 tools)

Standards:

10. Util (1 tool)

Standards:

Runtime boundary

The Scheduler is exposed through oracle schedule, the authenticated loopback Runtime API, and its WebSocket event stream. It is not registered as an MCP tool category. Tasks and run history live in ~/.oracle/runtime/oracle.db; cron expressions are validated on create and update. See runtime.md.

Input Validation

All inputs use Zod validators with .describe() for every field:

inputSchema: {
  question: z
    .string()
    .min(1)
    .max(50000)
    .describe("The question or what you're stuck on"),
  oracle: z
    .string()
    .optional()
    .describe("Oracle profile name (e.g. 'coding'). Auto-scopes memory to this profile"),
  files: z
    .array(z.string())
    .optional()
    .describe("File glob patterns to include when the answer needs real code"),
}

Rules:

Output Response Format

All tools return:

{
  success: boolean,
  data?: any,                         // Payload (on success)
  error?: string,                     // Error message (on failure)
  metadata?: Record<string, unknown>  // Stats, session IDs, etc.
}

Example:

{
  "success": true,
  "data": {
    "output": "Analysis result...",
    "sessionId": "session-123",
    "filesIncluded": 42
  },
  "metadata": {
    "provider": "claude-opus",
    "preset": "security"
  }
}

Rate Limiting & Caching

Tool Rate Limit Cacheable TTL
oracle_ask 10/min No —
oracle_agent 5/min No —
oracle_agent_checkpoints — Yes 1min
oracle_agent_checkpoint_delete — No —
oracle_memory_* — Yes (update clears) 5min
oracle_docs_search 20/min Yes 10min
oracle_web_* 5/min Yes (fetch) 30min
oracle_identity_* — Yes session
oracle_skills — Yes 5min
oracle_init — No —
oracle_task_* — No —
oracle_schedule_* — Yes 1min
oracle_history_* — Yes 5min

Error Handling Checklist

Example:

if (!skillRegistry.has(skillName)) {
  throw new OracleError(
    "INVALID_SKILL",
    `Unknown skill: ${skillName}`,
    `Run oracle_skills to see available options`,
    { available: skillRegistry.names() }
  );
}

Tool Module Structure

New tools go in src/mcp/tools/<category>.ts:

src/mcp/tools/
  ├── agent.ts       (oracle_agent, oracle_agent_checkpoints, oracle_agent_checkpoint_delete)
  ├── consult.ts     (oracle_ask)
  ├── memory.ts      (oracle_memory_*, oracle_memory_wiki_*, oracle_memory_graph_*)
  ├── messaging.ts   (oracle_msg_*)
  ├── task.ts        (oracle_task_*)
  ├── docs.ts        (oracle_docs_*)
  ├── web.ts         (oracle_web_*)
  ├── identity.ts    (oracle_identity_*, oracle_persona_set)
  ├── oracle.ts      (oracle_oracle_*, oracle_init)
  ├── session.ts     (oracle_sessions, oracle_session_get, oracle_skills)
  ├── history.ts     (oracle_history_sources, oracle_history_search)
  ├── util.ts        (oracle_doctor)
  └── scheduler.ts   (oracle_schedule_*)

Each module exports a createToolDefinitions() function, registered in server.ts:

const toolDefs = [
  ...createConsultTools(),
  ...createMemoryTools(),
  ...createMessagingTools(),
  ...createTaskTools(),
  // ...
];
registry.registerAll(server);

Migration Guide (Legacy → Standardized)

Old pattern:

server.registerTool("oracle_example", {
  title: "...",
  description: "...",
  inputSchema: { prompt: z.string() } // no .describe()
}, async ({ prompt }) => {
  try { /* logic */ } catch (e) { return failure(e); }
});

New pattern:

const toolDef: ToolDefinition = {
  name: "oracle_example",
  category: "consult",
  title: "...",
  description: "...",
  inputSchema: z.object({
    prompt: z.string().describe("The prompt text")
  }),
  outputSchema: z.object({
    success: z.boolean(),
    data: z.object({ result: z.string() }).optional()
  }),
  handler: async ({ prompt }) => {
    if (!prompt.trim()) {
      throw new OracleError(
        "INVALID_REQUEST",
        "Prompt cannot be empty"
      );
    }
    return toolSuccess({ result: "..." });
  }
};

Testing

All tools pass:

Before shipping a new tool:

npm run typecheck
npm run build
npm test
# Verify the tool manually via oracle_doctor + oracle-mcp

Last updated: 2026-07-24 Tool count: 73 MCP version: OpenAI-compatible (MCP SDK)

Oracle — A persistent coordination layer for AI coding agents https://github.com/OraclePersonal/Oracle