claude-octopus 1.0.0

package/src/tools/factory.ts

@@ -0,0 +1,150 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod/v4";
+import { OPTION_CATALOG } from "../constants.js";
+import {
+  sanitizeToolName,
+  deriveServerName,
+  deriveToolName,
+  serializeArrayEnv,
+} from "../lib.js";
+
+function buildEnvFromParams(
+  params: Record<string, unknown>
+): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  for (const opt of OPTION_CATALOG) {
+    const val = params[opt.key];
+    if (val === undefined || val === null) continue;
+
+    if (Array.isArray(val)) {
+      if (val.length > 0) env[opt.envVar] = serializeArrayEnv(val);
+    } else if (typeof val === "object") {
+      env[opt.envVar] = JSON.stringify(val);
+    } else if (typeof val === "boolean") {
+      env[opt.envVar] = String(val);
+    } else if (val !== "") {
+      env[opt.envVar] = String(val);
+    }
+  }
+
+  return env;
+}
+
+export function registerFactoryTool(
+  server: McpServer,
+  serverEntry: string
+) {
+  server.registerTool("create_claude_code_mcp", {
+    description: [
+      "Create a new specialized Claude Code agent as an MCP server.",
+      "WHEN TO USE: user says 'create agent', 'new agent', 'set up agent',",
+      "'configure agent', 'add a reviewer', 'add a test writer',",
+      "'make me a code reviewer', 'I need a specialized agent', etc.",
+      "DO NOT USE when user just wants to run a task — use the main tool for that.",
+      "This is a wizard: only a description is required.",
+      "Returns a ready-to-use .mcp.json config and lists all customization options.",
+      "Call again with more parameters to refine.",
+    ].join(" "),
+    inputSchema: z.object({
+      description: z.string().describe(
+        "What this agent should do, in plain language. Example: 'a strict code reviewer that only reads files'"
+      ),
+      name: z.string().optional().describe("Server name / alias (derived from description if omitted)"),
+      toolName: z.string().optional().describe("Custom tool name prefix"),
+      model: z.string().optional(),
+      systemPrompt: z.string().optional(),
+      appendPrompt: z.string().optional(),
+      allowedTools: z.array(z.string()).optional(),
+      disallowedTools: z.array(z.string()).optional(),
+      cwd: z.string().optional(),
+      additionalDirs: z.array(z.string()).optional(),
+      plugins: z.array(z.string()).optional(),
+      maxTurns: z.number().optional(),
+      maxBudgetUsd: z.number().optional(),
+      effort: z.enum(["low", "medium", "high", "max"]).optional(),
+      persistSession: z.boolean().optional(),
+      permissionMode: z.enum(["bypassPermissions", "acceptEdits", "default", "plan"]).optional(),
+      settingSources: z.array(z.string()).optional(),
+      mcpServers: z.record(z.string(), z.unknown()).optional(),
+      betas: z.array(z.string()).optional(),
+    }),
+  }, async (params) => {
+    const { description, name: nameParam, toolName: toolNameParam } = params;
+
+    const name = nameParam || deriveServerName(description);
+    const derivedToolName = toolNameParam
+      ? sanitizeToolName(toolNameParam)
+      : deriveToolName(name);
+
+    const env: Record<string, string> = {
+      CLAUDE_TOOL_NAME: derivedToolName,
+      CLAUDE_SERVER_NAME: name,
+      CLAUDE_DESCRIPTION: description,
+    };
+
+    const optionEnv = buildEnvFromParams(params);
+    Object.assign(env, optionEnv);
+
+    const configured = Object.keys(optionEnv);
+    const notConfigured = OPTION_CATALOG.filter(
+      (o) => !configured.includes(o.envVar)
+    );
+
+    const mcpEntry = {
+      [name]: {
+        command: "node",
+        args: [serverEntry],
+        env,
+      },
+    };
+
+    const sections: string[] = [];
+
+    sections.push(
+      "## Generated config",
+      "",
+      "Add to `mcpServers` in your `.mcp.json`:",
+      "",
+      "```json",
+      JSON.stringify(mcpEntry, null, 2),
+      "```"
+    );
+
+    sections.push("", "## What's configured");
+    sections.push("", `| Setting | Value |`, `|---|---|`);
+    sections.push(`| Name | \`${name}\` |`);
+    sections.push(`| Tool names | \`${derivedToolName}\`, \`${derivedToolName}_reply\` |`);
+    for (const key of configured) {
+      const opt = OPTION_CATALOG.find((o) => o.envVar === key);
+      if (opt) {
+        sections.push(`| ${opt.label} | \`${env[key]}\` |`);
+      }
+    }
+    if (configured.length === 0) {
+      sections.push(`| _(all defaults)_ | — |`);
+    }
+
+    if (notConfigured.length > 0) {
+      sections.push(
+        "",
+        "## Available customizations",
+        "",
+        "These options are not yet set. Ask the user if they'd like to configure any:",
+        ""
+      );
+      for (const opt of notConfigured) {
+        sections.push(`- **${opt.label}** — ${opt.hint}`);
+        sections.push(`  Example: ${opt.example}`);
+      }
+      sections.push(
+        "",
+        "_Call this tool again with additional parameters to refine the config._"
+      );
+    }
+
+    return {
+      content: [{ type: "text" as const, text: sections.join("\n") }],
+    };
+  });
+}

package/src/tools/query.ts

@@ -0,0 +1,171 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod/v4";
+import { resolve } from "node:path";
+import {
+  query,
+  type SDKResultMessage,
+} from "@anthropic-ai/claude-agent-sdk";
+import type { Options, InvocationOverrides } from "../types.js";
+import {
+  isDescendantPath,
+  mergeAllowedTools,
+  mergeDisallowedTools,
+  buildResultPayload,
+  formatErrorMessage,
+} from "../lib.js";
+
+async function runQuery(
+  prompt: string,
+  overrides: InvocationOverrides,
+  baseOptions: Options
+): Promise<SDKResultMessage> {
+  const options: Options = { ...baseOptions };
+
+  if (overrides.cwd) {
+    const baseCwd = baseOptions.cwd || process.cwd();
+    if (isDescendantPath(overrides.cwd, baseCwd)) {
+      options.cwd = resolve(baseCwd, overrides.cwd);
+    }
+  }
+  if (overrides.model) options.model = overrides.model;
+  if (overrides.maxTurns !== undefined && overrides.maxTurns > 0) {
+    options.maxTurns = overrides.maxTurns;
+  }
+  if (overrides.maxBudgetUsd != null)
+    options.maxBudgetUsd = overrides.maxBudgetUsd;
+  if (overrides.resumeSessionId) options.resume = overrides.resumeSessionId;
+
+  if (overrides.allowedTools?.length) {
+    options.allowedTools = mergeAllowedTools(
+      baseOptions.allowedTools,
+      overrides.allowedTools
+    );
+  }
+  if (overrides.disallowedTools?.length) {
+    options.disallowedTools = mergeDisallowedTools(
+      baseOptions.disallowedTools,
+      overrides.disallowedTools
+    );
+  }
+
+  if (overrides.systemPrompt) {
+    if (
+      typeof baseOptions.systemPrompt === "object" &&
+      baseOptions.systemPrompt?.type === "preset"
+    ) {
+      const baseAppend = baseOptions.systemPrompt.append || "";
+      options.systemPrompt = {
+        type: "preset",
+        preset: "claude_code",
+        append: [baseAppend, overrides.systemPrompt].filter(Boolean).join("\n"),
+      };
+    } else if (typeof baseOptions.systemPrompt === "string") {
+      options.systemPrompt = baseOptions.systemPrompt;
+      options.extraArgs = {
+        ...options.extraArgs,
+        "append-system-prompt": overrides.systemPrompt,
+      };
+    } else {
+      options.systemPrompt = {
+        type: "preset",
+        preset: "claude_code",
+        append: overrides.systemPrompt,
+      };
+    }
+  }
+
+  const q = query({ prompt, options });
+  let result: SDKResultMessage | undefined;
+
+  for await (const message of q) {
+    if (message.type === "result") {
+      result = message as SDKResultMessage;
+    }
+  }
+
+  if (!result) {
+    throw new Error("No result message received from Claude Code");
+  }
+
+  return result;
+}
+
+function formatResult(result: SDKResultMessage) {
+  const payload = buildResultPayload(
+    result as Parameters<typeof buildResultPayload>[0]
+  );
+  return {
+    content: [
+      { type: "text" as const, text: JSON.stringify(payload, null, 2) },
+    ],
+    isError: result.is_error,
+  };
+}
+
+function formatError(error: unknown) {
+  return {
+    content: [
+      { type: "text" as const, text: `Error: ${formatErrorMessage(error)}` },
+    ],
+    isError: true,
+  };
+}
+
+export function registerQueryTools(
+  server: McpServer,
+  baseOptions: Options,
+  toolName: string,
+  toolDescription: string
+) {
+  const replyToolName = `${toolName}_reply`;
+
+  server.registerTool(toolName, {
+    description: toolDescription,
+    inputSchema: z.object({
+      prompt: z.string().describe("Task or question for Claude Code"),
+      cwd: z.string().optional().describe("Working directory (overrides CLAUDE_CWD)"),
+      model: z.string().optional().describe('Model override (e.g. "sonnet", "opus", "haiku")'),
+      allowedTools: z.array(z.string()).optional().describe("Tool whitelist override"),
+      disallowedTools: z.array(z.string()).optional().describe("Tool blacklist override"),
+      maxTurns: z.number().int().positive().optional().describe("Max conversation turns"),
+      maxBudgetUsd: z.number().optional().describe("Max spend in USD"),
+      systemPrompt: z.string().optional().describe("Additional system prompt (appended to server default)"),
+    }),
+  }, async ({ prompt, cwd, model, allowedTools, disallowedTools, maxTurns, maxBudgetUsd, systemPrompt }) => {
+    try {
+      const result = await runQuery(prompt, {
+        cwd, model, allowedTools, disallowedTools, maxTurns, maxBudgetUsd, systemPrompt,
+      }, baseOptions);
+      return formatResult(result);
+    } catch (error) {
+      return formatError(error);
+    }
+  });
+
+  if (baseOptions.persistSession !== false) {
+    server.registerTool(replyToolName, {
+      description: [
+        `Continue a previous ${toolName} conversation by session ID.`,
+        "Use this for follow-up questions, iterative refinement,",
+        "or multi-step workflows that build on prior context.",
+      ].join(" "),
+      inputSchema: z.object({
+        session_id: z.string().describe(`Session ID from a prior ${toolName} response`),
+        prompt: z.string().describe("Follow-up instruction or question"),
+        cwd: z.string().optional().describe("Working directory override"),
+        model: z.string().optional().describe("Model override"),
+        maxTurns: z.number().int().positive().optional().describe("Max conversation turns"),
+        maxBudgetUsd: z.number().optional().describe("Max spend in USD"),
+      }),
+    }, async ({ session_id, prompt, cwd, model, maxTurns, maxBudgetUsd }) => {
+      try {
+        const result = await runQuery(prompt, {
+          cwd, model, maxTurns, maxBudgetUsd, resumeSessionId: session_id,
+        }, baseOptions);
+        return formatResult(result);
+      } catch (error) {
+        return formatError(error);
+      }
+    });
+  }
+}

package/src/types.ts

@@ -0,0 +1,22 @@
+import type { Options } from "@anthropic-ai/claude-agent-sdk";
+
+export interface InvocationOverrides {
+  cwd?: string;
+  model?: string;
+  allowedTools?: string[];
+  disallowedTools?: string[];
+  maxTurns?: number;
+  maxBudgetUsd?: number;
+  systemPrompt?: string;
+  resumeSessionId?: string;
+}
+
+export interface OptionCatalogEntry {
+  key: string;
+  envVar: string;
+  label: string;
+  hint: string;
+  example: string;
+}
+
+export type { Options };

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}