Oracle MCP Server

Instructions

Implementation Reference

• src/index.ts:159-216 (handler)

  The main execution logic for the 'consult_oracle' tool. It extracts the prompt, tries multiple oracle configurations and models in sequence with fallback logic, invokes the CLI using helpers, and returns the stdout as text content or accumulated errors if all fail.

  if (name === "consult_oracle") {
    const prompt = (args as Record<string, unknown>).prompt as string;
    const errors: string[] = [];
  
    // Try each oracle in sequence, and within each oracle try each model (fallback)
    for (let oracleIdx = 0; oracleIdx < oracleConfigs.length; oracleIdx++) {
      const cfg = oracleConfigs[oracleIdx];
      const models = normalizeModels(cfg);
  
      for (let modelIdx = 0; modelIdx < models.length; modelIdx++) {
        const model = models[modelIdx];
        try {
          const cmdName = cfg.command || "oracle";
          const spawnArgs = buildOracleArgs(
            cmdName,
            model,
            cfg.reasoning,
            prompt
          );
  
          const result = invokeOracle(cmdName, spawnArgs);
  
          if (result.error) {
            throw result.error;
          }
  
          if (result.status !== 0) {
            throw new Error(`Command failed with status ${result.status}`);
          }
  
          return {
            content: [
              {
                type: "text",
                text: result.stdout,
              } as TextContent,
            ],
          };
        } catch (error) {
          const errorMsg = error instanceof Error ? error.message : String(error);
          errors.push(
            `Oracle ${oracleIdx + 1}, model ${modelIdx + 1} (${model}): ${errorMsg}`
          );
        }
      }
    }
  
    // All oracles and models failed, return accumulated errors
    return {
      content: [
        {
          type: "text",
          text: `All oracles failed:\n${errors.join("\n")}`,
        } as TextContent,
      ],
      isError: true,
    };
  }

• src/index.ts:135-152 (registration)

  Registers the 'consult_oracle' tool in the ListToolsRequestSchema handler, including its name, dynamic description based on config, and input schema requiring a 'prompt' string.

  return {
    tools: [
      {
        name: "consult_oracle",
        description: fullDescription,
        inputSchema: {
          type: "object",
          properties: {
            prompt: {
              type: "string",
              description: "The question or problem to consult the oracle about. Be specific about context, constraints, and what decision or analysis you need.",
            },
          },
          required: ["prompt"],
        },
      },
    ],
  };

• src/index.ts:140-150 (schema)

  Input schema definition for the 'consult_oracle' tool, specifying an object with a required 'prompt' string property.

    inputSchema: {
      type: "object",
      properties: {
        prompt: {
          type: "string",
          description: "The question or problem to consult the oracle about. Be specific about context, constraints, and what decision or analysis you need.",
        },
      },
      required: ["prompt"],
    },
  },

• src/index.ts:86-97 (helper)

  Helper function that invokes the oracle CLI command using Node.js child_process.spawnSync synchronously, returning stdout, exit status, and any error.

  export function invokeOracle(
    command: string,
    args: string[]
  ): { stdout: string; status: number; error?: Error } {
    const result = spawnSync(command, args, { encoding: "utf-8" });
  
    return {
      stdout: result.stdout,
      status: result.status ?? 1,
      error: result.error,
    };
  }

• src/index.ts:59-80 (helper)

  Helper function to construct CLI argument arrays tailored to different oracle commands (codex, gemini, claude), handling model, reasoning level, and prompt.

  export function buildOracleArgs(
    command: string,
    model: string,
    reasoning: string | undefined,
    prompt: string
  ): string[] {
    if (command === "codex" || command.includes("codex")) {
      // Codex: codex exec --model <model> [-c reasoning_level=<level>] "<prompt>"
      const args = ["exec", "--model", model];
      if (reasoning) {
        args.push("-c", `reasoning_level=${reasoning}`);
      }
      args.push(prompt);
      return args;
    } else if (command === "gemini" || command.includes("gemini")) {
      // Gemini: gemini -p --model <model> "<prompt>"
      return ["-p", "--model", model, prompt];
    } else {
      // Claude: claude -p --model <model> "<prompt>"
      return ["-p", "--model", model, prompt];
    }
  }