| 1 | import type { DocsMcpDict } from "../types"; |
| 2 | |
| 3 | /** |
| 4 | * English reference dictionary for `app/[locale]/docs/mcp/page.tsx` |
| 5 | * ("Connect tools with MCP"). Commands and flags are checked against |
| 6 | * `McpCommand` in crates/tui/src/lib.rs and docs/MCP.md; the code-mode |
| 7 | * section against crates/tui/src/tools/codemode.rs and |
| 8 | * crates/tui/src/features.rs (`code_mode`: Experimental, default off). |
| 9 | */ |
| 10 | export const docsMcp: DocsMcpDict = { |
| 11 | metaTitle: "Connect tools with MCP · Codewhale Docs", |
| 12 | metaDescription: |
| 13 | "Add Model Context Protocol servers so Codewhale can use more tools, sign in to remote servers, run Codewhale itself as an MCP server, and try code mode.", |
| 14 | bodyClassName: "text-ink-soft leading-relaxed", |
| 15 | title: "Connect tools with MCP", |
| 16 | lede: |
| 17 | "MCP servers give Codewhale more tools — a database, an issue tracker, a browser. Add a local server that Codewhale starts for you, or a remote server by URL. Its tools then go through the same approvals as built-in ones.", |
| 18 | sections: [ |
| 19 | { |
| 20 | id: "add", |
| 21 | title: "Add a server", |
| 22 | blocks: [ |
| 23 | { |
| 24 | code: `codewhale mcp add git --command "uvx" --arg "mcp-server-git" |
| 25 | codewhale mcp add docs --url "https://example.com/mcp" |
| 26 | codewhale mcp list |
| 27 | codewhale mcp validate`, |
| 28 | lang: "Terminal", |
| 29 | }, |
| 30 | { |
| 31 | p: "`--command` starts a local server over stdio; repeat `--arg` for each argument. `--url` connects to a remote server over Streamable HTTP, with legacy SSE as a fallback. `mcp validate` checks the config and the servers you require.", |
| 32 | }, |
| 33 | { |
| 34 | p: "Inside a session, `/mcp` opens the MCP manager: each server's state, transport, timeouts, errors, and discovered tools. The same actions are available there, for example `/mcp add stdio <name> <command>` and `/mcp add http <name> <url>`.", |
| 35 | }, |
| 36 | { |
| 37 | note: "An MCP server runs with your permissions. Add only servers you trust, as you would any program you install.", |
| 38 | }, |
| 39 | ], |
| 40 | }, |
| 41 | { |
| 42 | id: "remote-auth", |
| 43 | title: "Sign in to a remote server", |
| 44 | blocks: [ |
| 45 | { |
| 46 | p: "For a server that uses OAuth, add it by URL and log in. For a bearer token, keep the token in an environment variable instead of the config file:", |
| 47 | }, |
| 48 | { |
| 49 | code: `codewhale mcp login docs |
| 50 | codewhale mcp add tracker --url "https://example.com/mcp" --bearer-token-env-var TRACKER_TOKEN`, |
| 51 | lang: "Terminal", |
| 52 | }, |
| 53 | { |
| 54 | p: "An explicit Authorization header always wins: headers from config apply first, then the bearer-token variable, then a stored OAuth login. `codewhale mcp logout <name>` removes the stored login on this machine; the provider may keep its own grant until you revoke it there.", |
| 55 | }, |
| 56 | ], |
| 57 | }, |
| 58 | { |
| 59 | id: "config", |
| 60 | title: "Edit the config file", |
| 61 | blocks: [ |
| 62 | { |
| 63 | p: "Servers live in `~/.codewhale/mcp.json`. `codewhale mcp init` writes a starter file. The `mcpServers` key used by other clients works too, so you can paste an existing entry.", |
| 64 | }, |
| 65 | { |
| 66 | code: `{ |
| 67 | "servers": { |
| 68 | "example": { |
| 69 | "command": "node", |
| 70 | "args": ["./path/to/your-mcp-server.js"], |
| 71 | "env": {}, |
| 72 | "disabled": false |
| 73 | } |
| 74 | } |
| 75 | }`, |
| 76 | lang: "mcp.json", |
| 77 | }, |
| 78 | { |
| 79 | p: "After editing the file, run `/mcp reload` in the session; no restart is needed. A server starts only when a turn needs one of its tools, unless you mark it `\"required\": true` to connect at startup.", |
| 80 | }, |
| 81 | ], |
| 82 | }, |
| 83 | { |
| 84 | id: "tool-names", |
| 85 | title: "Find the tools", |
| 86 | blocks: [ |
| 87 | { |
| 88 | p: "Each tool appears to the model as `mcp_<server>_<tool>`: a server named `git` with a `status` tool becomes `mcp_git_status`. `codewhale mcp tools <server>` lists what a server offers. A server that fails to connect or is disabled never shows up as an available tool.", |
| 89 | }, |
| 90 | { |
| 91 | p: "MCP tools follow your [approval setting](/docs/modes): listing and reading a server's resources and prompts can run without a prompt when policy allows, and tools with side effects ask first. Full Access does not override repository rules or managed policy.", |
| 92 | }, |
| 93 | ], |
| 94 | }, |
| 95 | { |
| 96 | id: "serve", |
| 97 | title: "Run Codewhale as an MCP server", |
| 98 | blocks: [ |
| 99 | { |
| 100 | p: "Other MCP clients — including another Codewhale session — can use Codewhale's tools. Register it once:", |
| 101 | }, |
| 102 | { |
| 103 | code: `codewhale mcp add-self |
| 104 | codewhale mcp tools codewhale`, |
| 105 | lang: "Terminal", |
| 106 | }, |
| 107 | { |
| 108 | p: "`add-self` writes an entry that runs `codewhale serve --mcp` over stdio. Each client starts its own process; no network port is opened. `codewhale serve --http` is a different thing — the [Runtime API](/docs/runtime-api) for apps.", |
| 109 | }, |
| 110 | ], |
| 111 | }, |
| 112 | { |
| 113 | id: "code-mode", |
| 114 | title: "Compose tool calls with code mode (experimental)", |
| 115 | blocks: [ |
| 116 | { |
| 117 | p: "Code mode lets the model write one short JavaScript program that calls several tools, loops, and filters results, instead of making each call as a separate step. Only the program's final value goes back to the model, which keeps long lookups compact. It is off by default. Try it for one session, or turn it on in config:", |
| 118 | }, |
| 119 | { |
| 120 | code: `codewhale --enable code_mode |
| 121 | |
| 122 | # ~/.codewhale/config.toml |
| 123 | [features] |
| 124 | code_mode = true`, |
| 125 | lang: "Terminal / config.toml", |
| 126 | }, |
| 127 | { |
| 128 | list: [ |
| 129 | "Only read-only tools that need no approval can run inside a program. Anything that writes, runs a shell command, or would ask you stops the program and reports which call it refused.", |
| 130 | "MCP tools cannot be called from a program yet. Use them as ordinary tool calls.", |
| 131 | "Limits per program: 50 tool calls, 4 at a time, 30 seconds, and 16 KiB returned.", |
| 132 | "Code mode is not available in Plan mode.", |
| 133 | ], |
| 134 | }, |
| 135 | ], |
| 136 | }, |
| 137 | ], |
| 138 | next: [ |
| 139 | { |
| 140 | href: "/docs/hooks", |
| 141 | label: "Run commands on events", |
| 142 | note: "Check or rewrite a tool call before it runs, including MCP tools.", |
| 143 | }, |
| 144 | { |
| 145 | href: "/docs/modes", |
| 146 | label: "Set modes and approvals", |
| 147 | note: "Decide which MCP calls stop for your approval.", |
| 148 | }, |
| 149 | { |
| 150 | href: "/docs/runtime-api", |
| 151 | label: "Automate with the Runtime API", |
| 152 | note: "Drive Codewhale from your own app or script over HTTP.", |
| 153 | }, |
| 154 | ], |
| 155 | sourceNote: |
| 156 | "Source documents: docs/MCP.md, crates/tui/src/tools/codemode.rs · Update docs-map.ts when changing.", |
| 157 | }; |
| 158 |