@lifeaitools/clauth 2.1.1 → 2.10.1

package/cli/mcp/tool-schemas.js

@@ -0,0 +1,822 @@
+// cli/mcp/tool-schemas.js
+// The MCP tool catalog: every clauth_*/fs_*/terminal_*/gws_*
+// tool schema, plus the write-tool filter. Pure data — no vault, no HTTP, no
+// session state. Extracted from serve.js as the first slice of splitting the
+// MCP interface out of the monolithic HTTP+dashboard+MCP file.
+export const MCP_TOOLS = [
+  {
+    name: "clauth_ping",
+    description: "Check if the vault is locked or unlocked, show failure count",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "clauth_unlock",
+    description: "Unlock the vault with the master password (password stays in MCP server memory only)",
+    inputSchema: { type: "object", properties: { password: { type: "string", description: "clauth master password" } }, required: ["password"], additionalProperties: false }
+  },
+  {
+    name: "clauth_lock",
+    description: "Lock the vault — clears password from memory",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "clauth_status",
+    description: "List all services with type, enabled state, key presence, and last retrieval time. Uses cached metadata and never retrieves raw secrets.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "clauth_knowledge",
+    description: "Return sanitized service metadata for agent caching. Never includes raw secrets or vault key names.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project: { type: "string", description: "Optional project scope" },
+        refresh: { type: "boolean", default: false, description: "Force one fresh status read instead of cached metadata" }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "clauth_list",
+    description: "List registered service names",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "clauth_search",
+    description: "Search registered service metadata. Redacted address hints are opt-in because they require secret reads.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search text, such as part of a service name, project, host, URL, or filesystem path" },
+        project: { type: "string", description: "Optional project scope" },
+        addresses: { type: "boolean", default: false, description: "Include redacted address hints from connstring/fileserver/oauth secrets. This may retrieve multiple secrets; leave false for normal discovery." }
+      },
+      required: ["query"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "clauth_get",
+    description: "Retrieve a secret and deliver to a temp file (default), clipboard, or stdout. Temp files auto-delete after 30 seconds.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        service: { type: "string", description: "Service name (e.g. github, anthropic, vercel)" },
+        target: { type: "string", enum: ["file", "clipboard", "stdout"], default: "file", description: "Where to deliver the secret. 'file' writes a temp file, 'clipboard' copies to clipboard, 'stdout' returns the value in the response (DANGEROUS — enters transcript)" }
+      },
+      required: ["service"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "clauth_inject",
+    description: "Retrieve a small explicit set of services into a sourceable env file. Guarded to prevent accidental bulk vault sweeps.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        services: { type: "array", items: { type: "string" }, description: "Service names to inject (e.g. ['github', 'vercel', 'anthropic']). Do not pass every service." },
+        allow_many: { type: "boolean", default: false, description: "Required when retrieving more than 5 services in one call." }
+      },
+      required: ["services"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "clauth_enable",
+    description: "Enable a service in the vault",
+    inputSchema: { type: "object", properties: { service: { type: "string" } }, required: ["service"], additionalProperties: false }
+  },
+  {
+    name: "clauth_disable",
+    description: "Disable a service in the vault",
+    inputSchema: { type: "object", properties: { service: { type: "string" } }, required: ["service"], additionalProperties: false }
+  },
+  {
+    name: "clauth_test",
+    description: "Test the HMAC handshake without retrieving any keys",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "clauth_scrub",
+    description: "Scrub secrets from Claude Code transcript .jsonl files",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: { type: "string", enum: ["latest", "all"], default: "latest", description: "Scrub the most recent transcript or all transcripts" }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "clauth_set_project",
+    description: "Set or clear the project scope on a service. Pass empty string to clear.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        service: { type: "string", description: "Service name (e.g. gmail, github)" },
+        project: { type: "string", description: "Project name to assign (empty string to clear)" }
+      },
+      required: ["service", "project"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "clauth_self_check",
+    description: "Test whether the clauth MCP connector is reachable via the Cloudflare tunnel. Returns connectivity status and tunnel URL.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "clauth_generate_token",
+    description: "Generate a cryptographically random bearer token and store it as a clauth service value",
+    inputSchema: {
+      type: "object",
+      properties: {
+        service: { type: "string", description: "Service name to store the token under (e.g. web-research-api)" },
+        prefix: { type: "string", description: "Token prefix (e.g. rdc_wr_). Default: empty string" }
+      },
+      required: ["service"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "clauth_enroll_machine",
+    description: "Create a one-time enrollment code for adding a new computer to this clauth install. Requires the vault to be unlocked.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        label: { type: "string", description: "Suggested label for the new computer" },
+        ttl_minutes: { type: "number", description: "Enrollment lifetime in minutes, 5 to 1440. Default: 60" },
+        install_id: { type: "string", description: "Optional install id override. Defaults to current machine install id." }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "call_agent",
+    description: "Call a headless Haiku agent for a single prompt or skill and get the answer back. Lean one-shot through a warm pool (model default claude-haiku-4-5, ~4-5s warm). sync mode (default) blocks and returns { ok, package, jobId, model, ms }; async returns { ok, jobId } for polling.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "The full prompt for the agent. Either this or skill_slug is required." },
+        skill_slug: { type: "string", description: "An rdc skill slug (e.g. 'rdc:status'); composed as '/<slug> <input>'." },
+        input: { type: "string", description: "Input/argument appended after skill_slug." },
+        model: { type: "string", description: "Model alias. Default claude-haiku-4-5." },
+        timeout_ms: { type: "number", description: "Hard timeout in ms. Default 120000." },
+        mode: { type: "string", enum: ["sync", "async"], description: "sync (block for answer, default) or async (return jobId)." },
+        agent_context: { type: "object", description: "Optional app/repo/runtime/task envelope. If CLAUTH_AGENT_DELEGATION is enabled and you are a call_agent worker delegating to a SUB-agent, set agent_context.delegation = { hop, max } (e.g. { hop: 1, max: 2 }) — the sub-call runs on a separate cold lane, never the warm pool, and is rejected once hop exceeds max. Omit delegation for normal (top-level) calls.", additionalProperties: true },
+        bootstrap: { type: "string", enum: ["none", "identity", "full"], description: "Startup tier (default 'identity'). 'none' = lean fast path (trivial one-shots, warmest). 'identity' = short who-am-I + how-to-get-access (clauth daemon, Supabase ref, work_items RPCs) on a neutral cwd — every default agent at least knows its identity/access. 'full' = real repo/DB work: runs in the repo cwd and points the agent at .rdc/guides/agent-bootstrap.md (creds, git rules, completion report)." },
+        repo_root: { type: "string", description: "Override the repo root for bootstrap='full' (default env CLAUTH_AGENT_REPO_ROOT or C:/Dev/regen-root)." },
+        append_system_prompt: { type: "string", description: "Optional extra system-prompt directive appended AFTER the bootstrap tier text." },
+        corpus: {
+          type: "object",
+          description: "Regen Agent corpus handoff (same shape @regen/claude-dispatch delivers). Assembled into a `## Corpus` section appended to the agent's prompt body. With bootstrap='full', .rdc/guides/agent-bootstrap.md content is auto-included inline as a Supporting Doc even if corpus is omitted.",
+          properties: {
+            product: { type: "string", description: "Product MD context." },
+            design: { type: "string", description: "Design MD context." },
+            docs: {
+              type: "array",
+              description: "Supporting documents.",
+              items: {
+                type: "object",
+                properties: {
+                  path: { type: "string", description: "Document path/identifier." },
+                  title: { type: "string", description: "Optional document title." },
+                  content: { type: "string", description: "Document content." },
+                },
+                required: ["path", "content"],
+                additionalProperties: false,
+              },
+            },
+          },
+          additionalProperties: false,
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+
+  // ── Terminal session manager ───────────────────────────────────────────
+  {
+    name: "terminal_start",
+    description: "Start a named persistent Claude session. Sessions maintain rolling context across sends. Returns session_id for subsequent sends.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name:           { type: "string", description: "Human-readable session name (e.g. 'knowledgedude-prt')" },
+        knowledge_tier: { type: "string", enum: ["db_only", "corpus", "project"], description: "Knowledge tier for the session. 'corpus' injects context_md as preamble." },
+        context_md:     { type: "string", description: "Optional markdown preamble injected as session context (used for 'corpus' tier)" },
+        cwd:            { type: "string", description: "Optional working directory. Defaults to a neutral temp directory so browser chat avoids repo hooks." },
+        use_warm:       { type: "boolean", description: "Opt into experimental pinned warm-worker mode. Defaults to false for reliable browser chat turns." },
+      },
+      required: ["name"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "terminal_send",
+    description: "Send a message to a running terminal session. Spawns a Claude worker with rolling context + message. Returns immediately — session processes async.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        session_id: { type: "string", description: "Session ID returned by terminal_start" },
+        message:    { type: "string", description: "Message to send to the session" },
+      },
+      required: ["session_id", "message"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "terminal_list",
+    description: "List all active terminal sessions with their status (ready/busy/stopped), knowledge tier, and start time.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "terminal_show",
+    description: "Reveal/focus a clauth terminal session on this Windows machine. If no live Claude process window exists, opens a visible session inspector at the session cwd.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        session_id: { type: "string", description: "Session ID returned by terminal_start" },
+      },
+      required: ["session_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "terminal_recv",
+    description: "Read the last response from a terminal session. Returns response if ready, or status='busy' if still processing. Poll every 3-5 seconds until status='ready'.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        session_id: { type: "string", description: "Session ID returned by terminal_start" },
+      },
+      required: ["session_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "terminal_stop",
+    description: "Stop a terminal session and remove it from memory. Kills any active process.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        session_id: { type: "string", description: "Session ID to stop" },
+      },
+      required: ["session_id"],
+      additionalProperties: false,
+    },
+  },
+
+  {
+    name: "channel_list",
+    description:
+      "List webhook events received via POST /channel (Coolify/GitHub deployments, pushes, etc.). " +
+      "Returns up to 100 recent events. Use 'since' to get only new events.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        since: {
+          type: "string",
+          description: "ISO 8601 timestamp — return only events created after this time",
+        },
+        limit: { type: "number", description: "Max results (1–100, default 50)" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "channel_clear",
+    description: "Clear all queued channel events.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+
+  // ── Google Workspace (gws CLI) ──────────────────────────────────────────
+  {
+    name: "gws_run",
+    description: "Run any gws CLI command for Google Workspace (Drive, Gmail, Calendar, Docs, Sheets, Slides, Tasks, People, Chat, etc.).\nCLI pattern: gws <service> <resource> [sub_resource] <method> [--params JSON] [--body JSON]",
+    inputSchema: {
+      type: "object",
+      properties: {
+        service: { type: "string", description: "Google Workspace service: drive, sheets, gmail, calendar, docs, slides, tasks, people, chat, classroom, forms, keep, meet, script" },
+        resource: { type: "string", description: "Resource noun, e.g. 'files', 'users', 'events'" },
+        sub_resource: { type: "string", description: "Optional sub-resource, e.g. 'messages' in 'users messages'" },
+        method: { type: "string", description: "Method verb: list, get, insert, update, delete, send, create" },
+        params: { type: "object", description: "Query/path params passed as --params JSON" },
+        body: { type: "object", description: "Request body passed as --json JSON" }
+      },
+      required: ["service", "resource", "method"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "gws_gmail_list",
+    description: "List Gmail messages. Supports Gmail search syntax (e.g. 'from:alice subject:meeting is:unread').",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Gmail search query" },
+        max_results: { type: "number", description: "Max messages (1-500, default 10)" }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "gws_gmail_read",
+    description: "Read a single Gmail message by ID. Returns full message with headers and body.",
+    inputSchema: {
+      type: "object",
+      properties: { message_id: { type: "string", description: "Gmail message ID" } },
+      required: ["message_id"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "gws_gmail_send",
+    description: "Send an email via Gmail.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        to: { type: "string", description: "Recipient email address" },
+        subject: { type: "string", description: "Email subject" },
+        body: { type: "string", description: "Plain-text email body" },
+        from: { type: "string", description: "Sender name/address (optional)" }
+      },
+      required: ["to", "subject", "body"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "gws_calendar_list",
+    description: "List upcoming Google Calendar events.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        calendar_id: { type: "string", description: "Calendar ID (default: primary)" },
+        max_results: { type: "number", description: "Max events (default 10)" },
+        time_min: { type: "string", description: "Start bound ISO 8601, e.g. '2026-04-10T00:00:00Z'" },
+        time_max: { type: "string", description: "End bound ISO 8601" }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "gws_drive_list",
+    description: "List files in Google Drive. Supports Drive search query syntax.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Drive search query, e.g. \"name contains 'report'\"" },
+        max_results: { type: "number", description: "Max files (default 10)" }
+      },
+      additionalProperties: false
+    }
+  },
+  // ── Filesystem tools ──
+  {
+    name: "fs_read",
+    description: "[DEPRECATED — use WebDAV: rclone cat dav:path (37x faster). Fallback only.] Read a file. Returns UTF-8 text with line numbers. Supports offset/limit for large files.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Relative path within mount (e.g. 'packages/ui/src/index.ts')" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+        offset: { type: "number", description: "Start line (0-based, default 0)" },
+        limit: { type: "number", description: "Max lines to return (default 500)" },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_write",
+    description: "Write content to a file. Creates parent directories if needed. Overwrites existing file.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Relative path within mount" },
+        content: { type: "string", description: "File content to write" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      required: ["path", "content"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_stat",
+    description: "[DEPRECATED — use WebDAV: rclone lsjson dav:path (faster). Fallback only.] Get file or directory metadata. Files include a SHA-256 hash for guarded edits.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Relative path within mount" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_append",
+    description: "Append text to a file, optionally guarded by the current file SHA-256 hash.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Relative path within mount" },
+        content: { type: "string", description: "Text to append" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+        expected_sha256: { type: "string", description: "Optional current file SHA-256. If provided and the file exists, append only when it matches." },
+      },
+      required: ["path", "content"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_write_chunk",
+    description: "Stage chunked text writes and atomically publish when all chunks arrive. Use when single write arguments are too large.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        upload_id: { type: "string", description: "Caller-chosen idempotency key for this file upload" },
+        path: { type: "string", description: "Relative path within mount" },
+        chunk_index: { type: "number", description: "Zero-based chunk index" },
+        total_chunks: { type: "number", description: "Total chunks expected" },
+        content: { type: "string", description: "Chunk text content" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+        expected_sha256: { type: "string", description: "Optional SHA-256 of the final assembled file content" },
+      },
+      required: ["upload_id", "path", "chunk_index", "total_chunks", "content"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_ingest_url",
+    description: "Download text from an http(s) URL and atomically write it inside the mount. Useful for moving cloud files into the local filesystem.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "HTTPS or HTTP URL to fetch" },
+        path: { type: "string", description: "Relative output path within mount" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+        max_bytes: { type: "number", description: "Maximum download size in bytes (default 5MB, hard max 25MB)" },
+        expected_sha256: { type: "string", description: "Optional SHA-256 of fetched content before writing" },
+      },
+      required: ["url", "path"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_import_git_files",
+    description: "Fetch a Git ref and restore only named files into the mounted repo, optionally committing just those files. Designed for Claude.ai GitHub uploads into dirty local monorepos.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        remote: { type: "string", description: "Git remote name (default: origin)" },
+        ref: { type: "string", description: "Branch, tag, or commit to fetch/restore from" },
+        paths: { type: "array", items: { type: "string" }, description: "Repo-relative file paths to import" },
+        mode: { type: "string", enum: ["new_only", "overwrite"], description: "new_only refuses existing local paths. overwrite restores named paths only." },
+        commit: { type: "boolean", description: "When true, stage only imported paths and create a local commit. Never pushes." },
+        message: { type: "string", description: "Commit subject when commit=true" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+        allowed_prefixes: { type: "array", items: { type: "string" }, description: "Optional path allowlist prefixes. Defaults to docs and agent corpus paths." },
+      },
+      required: ["ref", "paths"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_list",
+    description: "[DEPRECATED — use WebDAV: rclone ls/lsd dav:path (faster). Fallback only.] List directory contents with file type, size, and modification time.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Relative directory path (default: mount root)" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_grep",
+    description: "Search file contents using ripgrep. Returns matching lines with context. Spawns rg process.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pattern: { type: "string", description: "Regex pattern to search for" },
+        path: { type: "string", description: "Relative path to search in (default: mount root)" },
+        glob: { type: "string", description: "File glob filter (e.g. '*.ts', '*.{js,tsx}')" },
+        context: { type: "number", description: "Lines of context around matches (default 0)" },
+        max_results: { type: "number", description: "Max matches (default 50)" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      required: ["pattern"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_glob",
+    description: "Find files by glob pattern. Returns matching file paths relative to mount.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pattern: { type: "string", description: "Glob pattern (e.g. '**/*.tsx', 'apps/*/package.json')" },
+        path: { type: "string", description: "Relative base path (default: mount root)" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      required: ["pattern"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_delete",
+    description: "Delete a file or empty directory.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Relative path to delete" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_mkdir",
+    description: "[DEPRECATED — use WebDAV: rclone mkdir dav:path (faster). Fallback only.] Create a directory (recursive — creates parents if needed).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Relative directory path to create" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_edit",
+    description: "[DEPRECATED — read via WebDAV (rclone cat) + fs_write instead. Fallback only.] Replace a unique string in a file. Like Edit in Claude Code: fails if old_string is not found or matches multiple times unless replace_all=true. Atomic write. Returns new file info including sha256.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Relative path within mount" },
+        old_string: { type: "string", description: "Exact text to find (must be unique unless replace_all=true)" },
+        new_string: { type: "string", description: "Replacement text (must differ from old_string)" },
+        replace_all: { type: "boolean", description: "Replace every occurrence (default false)" },
+        expected_sha256: { type: "string", description: "Optional current file SHA-256 guard. If provided and mismatched, edit is rejected." },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      required: ["path", "old_string", "new_string"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_move",
+    description: "Move or rename a file or directory within a mount. Single syscall when possible; falls back to copy+delete across devices. Refuses to overwrite existing destination unless overwrite=true.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "Source relative path within mount" },
+        to: { type: "string", description: "Destination relative path within mount" },
+        overwrite: { type: "boolean", description: "Overwrite destination if it exists (default false)" },
+        mount: { type: "string", description: "Mount name for both from and to (default: first mount)" },
+      },
+      required: ["from", "to"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_copy",
+    description: "Copy a file or directory tree within a mount. Recursive by default. Refuses to overwrite existing destination unless overwrite=true.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "Source relative path within mount" },
+        to: { type: "string", description: "Destination relative path within mount" },
+        overwrite: { type: "boolean", description: "Overwrite destination if it exists (default false)" },
+        mount: { type: "string", description: "Mount name for both from and to (default: first mount)" },
+      },
+      required: ["from", "to"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_mounts",
+    description: "List configured filesystem mounts (fileserver services from vault).",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "fs_repo_status",
+    description: "Get the current git state of the mounted repo in ONE call: branch, HEAD sha + subject, whether the tree is clean or dirty (with changed paths), staged paths, how far ahead/behind the remote you are, and whether a merge or rebase is in progress. Call this first so you KNOW what you are working with before committing — you never have to guess whether your edits or a previous push landed. Requires 'g' (git) access on the mount.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_use_branch",
+    description: "[RETIRED — use fs_exec([\"git\", \"checkout\", \"branch\"]) instead. Known worktree bugs.] Switches to an existing branch, or creates a new one from the current HEAD when create=true. Requires 'g' (git) access on the mount.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        branch: { type: "string", description: "Branch name to switch to (or create)" },
+        create: { type: "boolean", description: "Create a new branch from current HEAD instead of switching to an existing one (default false)" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      required: ["branch"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_commit",
+    description: "Commit and push to GitHub: stages changes, commits, and PUSHES by default — usually a single call is all you need after editing. Handles the messy cases: nothing-to-commit returns cleanly (no error); a merge/rebase in progress or a detached HEAD is refused with a clear message; if the branch is behind the remote it auto-rebases and retries the push, and on conflict it aborts the rebase (restoring your tree) and keeps the commit local so nothing is lost. Refuses to push protected branches (main/master/production) — those are promoted by a human. Returns the commit sha, the exact files committed, whether the push succeeded, and ahead/behind counts, so you never need a follow-up status call. Set dry_run=true first to preview what WOULD be committed/pushed without doing it. Set expected_head to refuse committing if the base moved under you. Push auth uses the vault github token directly (never exposed). Requires 'g' (git) access on the mount.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        message: { type: "string", description: "Commit message. Required for a real commit; optional when dry_run=true." },
+        paths: { type: "array", items: { type: "string" }, description: "Repo-relative paths to commit. Omit to commit ALL current changes in the repo." },
+        push: { type: "boolean", description: "Push to the remote after committing (default true)" },
+        dry_run: { type: "boolean", description: "Preview only: returns the branch, the files that would be committed, and whether/where it would push — without staging, committing, or pushing. Use to confirm before a real push." },
+        expected_head: { type: "string", description: "Optimistic-concurrency guard: the commit SHA you believe HEAD is on. If HEAD has moved, the commit is refused so you don't build on a stale base." },
+        remote: { type: "string", description: "Git remote name (default: origin)" },
+        author_name: { type: "string", description: "Commit author name (default: clauth-fs)" },
+        author_email: { type: "string", description: "Commit author email (default: fs@clauth.local)" },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_diff",
+    description: "Show the unified diff of your changes so you can self-verify BEFORE committing/pushing — essential after large or multi-step edits. Default compares the working tree to the last commit (HEAD). Pass ref (e.g. 'origin/develop') to compare against a remote branch and catch staleness — i.e. see exactly how your working tree differs from what's on the remote, in one call. Pass staged=true to see only what's staged. Returns a --stat summary plus the patch (capped at 60KB; `truncated` flags when hit). Requires 'g' (git) access on the mount.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        paths: { type: "array", items: { type: "string" }, description: "Repo-relative paths to limit the diff to. Omit for all changes." },
+        ref: { type: "string", description: "Compare the working tree against this ref instead of HEAD (e.g. 'origin/develop', a tag, or a commit sha). Use for remote/staleness comparison." },
+        staged: { type: "boolean", description: "Show only staged changes (index vs HEAD) instead of the full working-tree diff." },
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_exec",
+    description: "Run a command on the host machine. Command[0] must be in the server-side allowlist (git, pnpm, npx, node, python3, rclone, bash, cat, grep, find, wc, sha256sum, tsc, eslint). cwd is relative to mount root; path traversal rejected. Timeout enforced server-side. Every execution is audit-logged.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+        command: { type: "array", items: { type: "string" }, description: "Exec-style array: [\"git\", \"status\"]" },
+        cwd: { type: "string", description: "Working directory relative to mount root (default: mount root)" },
+        timeout_seconds: { type: "number", description: "Hard-kill on expiry (default 30, max 300)" },
+        shell: { type: "boolean", description: "If true, uses shell (enables pipes/redirects); if false, execFile (safer). Default false." },
+        env: { type: "object", description: "Additional env vars merged into process env" },
+      },
+      required: ["command"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_hash",
+    description: "Server-side file hashing. Hash files on the host without pulling them over the network. Returns sha256 (or md5/sha1) for up to 50 files in one call.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+        paths: { type: "array", items: { type: "string" }, description: "Paths relative to mount root (max 50)" },
+        algorithm: { type: "string", description: "Hash algorithm: sha256 (default), md5, sha1" },
+      },
+      required: ["paths"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_cat_lines",
+    description: "Read a specific line range from a file. Server-side extraction — only the requested lines are returned, not the whole file. 1-indexed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+        path: { type: "string", description: "File path relative to mount root" },
+        start_line: { type: "number", description: "First line to return (1-indexed)" },
+        end_line: { type: "number", description: "Last line to return (default: EOF)" },
+      },
+      required: ["path", "start_line"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_grep_json",
+    description: "Structured grep results as JSON. Same server-side ripgrep execution as fs_grep, but returns structured [{file, line, match, before[], after[]}] instead of raw text.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+        pattern: { type: "string", description: "Regex pattern to search for" },
+        path: { type: "string", description: "Path to search in (default: mount root)" },
+        glob: { type: "string", description: "File glob filter (default: **/*)" },
+        max_results: { type: "number", description: "Max matches to return (default 50)" },
+        context_lines: { type: "number", description: "Lines of context before/after each match (default 0)" },
+      },
+      required: ["pattern"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_search",
+    description: "Combined glob + grep + stat in one call. Find files by type, modification date, and content pattern. Saves 2-3 MCP round-trips.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+        query: { type: "string", description: "Filename glob pattern (e.g. *.tsx)" },
+        file_types: { type: "array", items: { type: "string" }, description: "File extensions to include (e.g. [\".tsx\", \".ts\"])" },
+        modified_after: { type: "string", description: "ISO date — only files modified after this" },
+        modified_before: { type: "string", description: "ISO date — only files modified before this" },
+        content_pattern: { type: "string", description: "Regex to match in file content (optional)" },
+        path: { type: "string", description: "Subdirectory to search in (default: mount root)" },
+        max_results: { type: "number", description: "Max results (default 50)" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_put",
+    description: "Write binary content (base64-encoded) to a file. For text files prefer fs_write; use this for images, PDFs, DOCX, or any binary. Decodes server-side, writes atomically.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mount: { type: "string", description: "Mount name (default: first mount)" },
+        path: { type: "string", description: "File path relative to mount root" },
+        content_base64: { type: "string", description: "Base64-encoded file content" },
+        overwrite: { type: "boolean", description: "Overwrite if file exists (default false)" },
+      },
+      required: ["path", "content_base64"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "fs_dav_setup",
+    description: "Start the WebDAV bridge and return a setup script that configures rclone in the sandbox. After running the script, use rclone commands directly: rclone lsd dav:corpus/ (list), rclone cat dav:corpus/file.md (read), rclone rcat dav:dev/file.txt (write). Each command is a stateless WebDAV call — no FUSE mount, no daemon, survives across turns.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ttl_seconds: { type: "number", description: "Hint for how long the mount will stay active (default 14400 = 4 h). Does not enforce expiry — informational only in v1." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "clauth_ops_catalog",
+    description: "Return the Vultr deployment-control API catalog. Availability is still decided on Vultr.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_processes",
+    description: "Submit a scoped PM2 process-status query to the Vultr control plane. Only server-approved applications are returned.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_describe",
+    description: "Submit a scoped PM2 status query for one server-approved application.",
+    inputSchema: { type: "object", properties: { application: { type: "string" } }, required: ["application"], additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_deploy",
+    description: "Submit one manifest-scoped development deployment to Vultr. The server chooses the repository, build, PM2 process, and allowed ref.",
+    inputSchema: { type: "object", properties: { application: { type: "string" }, ref: { type: "string" } }, required: ["application"], additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_promote",
+    description: "Submit one server-allowlisted Coolify promotion and return its asynchronous job receipt.",
+    inputSchema: { type: "object", properties: { application_uuid: { type: "string" } }, required: ["application_uuid"], additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_job",
+    description: "Read the terminal or in-progress receipt for a deployment-control job.",
+    inputSchema: { type: "object", properties: { job_id: { type: "string" } }, required: ["job_id"], additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_run",
+    description: "Submit one PM2 operation through the Vultr control plane. The remote agent/admin profile decides whether the operation and target are available.",
+    inputSchema: { type: "object", properties: { operation: { type: "string" }, input: { type: "object" } }, required: ["operation"], additionalProperties: false },
+  },
+];
+
+export const MCP_WRITE_TOOL_NAMES = new Set([
+  "clauth_enable",
+  "clauth_disable",
+  "clauth_set_project",
+  "clauth_generate_token",
+  "clauth_ops_deploy",
+  "clauth_ops_promote",
+  "clauth_ops_run",
+]);
+
+export function filterMcpToolsForWriteMode(tools) {
+  if (process.env.CLAUTH_MCP_WRITE === "1") return tools;
+  return tools.filter(tool => !MCP_WRITE_TOOL_NAMES.has(tool.name));
+}