github/cc-switch
1
0 Fork 0
mirror of https://github.com/farion1231/cc-switch.git synced 2026-10-26 01:34:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(manual): update the user manual for v4.0

Browse Source 
Bring the zh, en and ja user manuals up to the v4.0.4 interface: the
sidebar layout, the six Settings groups, the Direct / Routing /
Aggregation connection modes, Accounts, and the Apps page. Old
Settings paths (Advanced, Routing, Auth) and takeover wording are gone.

- Add 4.6 Aggregation Mode in all three languages and list it in the
  manual indexes.
- Rewrite 1.3 Interface Overview and 1.5 Settings around the new
  layout; refresh provider, extension, routing, usage and FAQ pages.
- Use the v4.0 release screenshots where they fit and leave
  TODO(v4 screenshot) markers elsewhere.
- Update the version section of each manual index to v4.0.4.
- Remove the 40 v3 screenshots that are no longer referenced.
This commit is contained in:
Jason committed 2026-10-07 20:42:08 +08:00
1 parent a40adef3f7
commit efd236a474
121 files changed
+3567 -3864
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/user-manual/en/3-extensions/3.1-mcp.md
+58 -40
View File
@@ -11,48 +11,62 @@ MCP (Model Context Protocol) is a protocol that allows AI tools to access extern
## Open the MCP Panel
Click the **MCP** icon button in the top navigation bar (its hover tooltip reads "MCP Management"; it is visible on the Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, Hermes, and MiniMax Code pages).
Click **MCP** in the left sidebar. It is a global page that does not belong to any one app: whichever app is currently selected, you open the same panel (Claude Desktop has no MCP of its own, so it has no column here either).
## Panel Overview
![image-20260108005723522](../../assets/image-20260108005723522.png)
<!-- TODO(v4 screenshot): Full MCP page: one MCP per row, per-app switches in columns on the right, and a page header with "Import from apps", "Add MCP" and the ⋯ menu -->
The page is a matrix table: **one row per MCP server, one column per app**. The switch in each cell means "this MCP is enabled in this app".
- Page header: "Import from apps", "Add MCP", and a ⋯ menu ("Rewrite every app's config from these switches", "Copy all as mcpServers JSON")
- Search box: filters by name, command, or URL
- Only the columns for apps set to show on the sidebar's "Apps" page are displayed; hiding only affects the UI, and configuration already written to a hidden app is kept and still synced
- Each row has an "Edit" button on the right and a ⋯ menu (Copy as JSON, Open docs, Enable in all apps, Turn off everywhere, Delete)
- If writing to an app fails, the row marks the failed app and you can click "Retry"
## Add MCP Server
### Using Preset Templates
### Using a Template
1. Click the **+** button in the top-right corner
2. Select a template from the "Preset" dropdown
3. Modify the configuration as needed
4. Click "Save"
1. Click **Add MCP** in the page header; a drawer opens on the right
2. Under "Start from a template", pick a template, or leave it empty and fill things in yourself
3. Adjust as needed, and tick the apps to enable under "Write to"
4. Click Add
![image-20260108005739731](../../assets/image-20260108005739731.png)
<!-- TODO(v4 screenshot): Add MCP drawer: templates, paste a config, connection, write to -->
### Common Presets
### Paste a Config
| Preset | Package Name | Description |
|--------|-------------|-------------|
"Paste a config" in the drawer accepts a block of JSON or TOML directly. It recognizes `mcpServers`, Codex's `[mcp_servers.name]`, and OpenCode's local / remote format, and fills in the form below. If you paste several servers at once, the entries are listed as "New" or "Name already exists", and for same-name entries you can choose Skip or Replace.
### Common Templates
| Template | Package Name | Description |
|----------|-------------|-------------|
| fetch | mcp-server-fetch | HTTP request tool that enables AI to fetch web content |
| time | mcp-server-time | Time tool that provides current time information |
| time | mcp-server-time (run via `uvx`) | Time tool that provides current time information |
| memory | @modelcontextprotocol/server-memory | Memory tool that enables AI to store and retrieve information |
| sequential-thinking | @modelcontextprotocol/server-sequential-thinking | Chain-of-thought tool that enhances AI reasoning |
| context7 | @upstash/context7-mcp | Documentation search tool for querying technical docs |
### Custom Configuration
After selecting "Custom", fill in:
If you don't pick a template and fill things in yourself, you need:
| Field | Required | Description |
|-------|----------|-------------|
| Server ID | Yes | Unique identifier |
| Name | No | Display name |
| Description | No | Function description |
| Transport Type | Yes | stdio / http / sse |
| Command | Yes* | Required for stdio type |
| Arguments | No | Command-line arguments |
| URL | Yes* | Required for http/sse type |
| Headers | No | Request headers for http/sse type |
| Environment Variables | No | Environment variables passed to the server |
| Name | Yes | The key written into each app's config file; no spaces allowed. It can't be changed after saving; to rename, create a new one and delete the old one |
| Transport | Yes | Local command (stdio) / HTTP / SSE |
| Command | Yes* | Required for local command type; enter only the program (such as `npx` or `uvx`), and put arguments in their own field |
| Arguments | No | Command-line arguments, one per line |
| Environment variables | No | Environment variables passed to the server |
| Working directory | No | Optional for local command type; if left empty, the app decides |
| URL | Yes* | Required for HTTP / SSE type; must start with `http://` or `https://` |
| Headers | No | Request headers for HTTP / SSE type |
| Display name, Description, Tags, Homepage, Docs | No | Grouped under "Description & links"; shown only in CC Switch and not written to app configs |
You can also click "Edit in JSON" to edit the whole configuration directly. It is the same data as the form and stays in sync when you switch; the values of environment variables and headers appear as `••••••••` in JSON, and the original values are kept when you save.
## Transport Types
@@ -84,7 +98,7 @@ Communicates with a remote server via HTTP protocol.
### sse (Server-Sent Events)
Communicates with a server via SSE protocol, supporting real-time push.
Communicates with a server via SSE protocol, supporting real-time push. Pi does not support the SSE type.
```json
{
@@ -94,23 +108,24 @@ Communicates with a server via SSE protocol, supporting real-time push.
## App Binding
Each MCP server can independently control which apps it is enabled for.
Each MCP server can independently control which apps it is enabled for: click the switch in that row and app column of the matrix.
### Toggle Description
### App Columns
| Toggle | Effect | Configuration File Path |
| App | Effect | Configuration File Path |
|--------|--------|------------------------|
| Claude | Sync to Claude Code | `~/.claude.json`'s `mcpServers` |
| Claude Code | Sync to Claude Code | `~/.claude.json`'s `mcpServers` |
| Codex | Sync to Codex | `~/.codex/config.toml`'s `[mcp_servers]` |
| Gemini | Sync to Gemini CLI | `~/.gemini/settings.json`'s `mcpServers` |
| Gemini CLI | Sync to Gemini CLI | `~/.gemini/settings.json`'s `mcpServers` |
| Grok Build | Sync to Grok Build | `~/.grok/config.toml`'s `[mcp_servers]` |
| OpenCode | Sync to OpenCode | `~/.config/opencode/opencode.json`'s `mcp` |
| Hermes | Sync to Hermes | `~/.hermes/config.yaml`'s `mcp_servers` |
| Pi | Sync to Pi (requires Pi 1.0 or later) | `~/.pi/agent/mcp.json` |
| MiniMax Code | Sync to MiniMax Code | `~/.minimax/mcp.json` |
> ⚠️ **Note**: OpenClaw, Pi, and Claude Desktop do not currently support CC Switch MCP sync. The MCP panel is a single unified panel shared by all apps; opening it from the Claude Desktop page shows the same panel, which has no Claude Desktop toggle. MCP functionality is supported for Claude, Codex, Gemini, Grok Build, OpenCode, Hermes, and MiniMax Code.
> ⚠️ **Note**: Claude Desktop and OpenClaw do not support CC Switch MCP sync, so the table has no columns for them. MCP is supported for the 8 apps above.
The MCP panel can enable or disable all servers for an app in one click.
Click a column header for bulk actions on that column: "Enable the other N", "Enable all", and "Turn all off". They apply only to the entries in the current list (or only to the results after a search or filter), and you can click "Undo" afterwards. Each row's ⋯ menu also has "Enable in all apps" and "Turn off everywhere".
### Toggle Implementation
@@ -126,18 +141,19 @@ When disabling an app's toggle, CC Switch will:
2. **Remove from live configuration**: Delete the server from the app's configuration file
3. **Take effect immediately**: The MCP server is no longer loaded the next time the CLI tool starts
> 💡 CC Switch only manages servers that exist in its database; servers you added by hand in a tool's configuration and never imported into CC Switch are left untouched. **MiniMax Code is the exception**: during a bulk sync, servers that are not enabled for MiniMax Code are not deleted from `mcp.json`; they are removed only when you explicitly turn them off or delete them in CC Switch.
> 💡 CC Switch only manages servers that exist in its database; servers you added by hand in a tool's configuration and never imported into CC Switch are left untouched; however, if you edit an entry with the same name as one in CC Switch directly in an app's configuration, it is overwritten and CC Switch's version wins. **MiniMax Code and Pi are the exceptions**: during a bulk sync, servers that are not enabled for them are not deleted from `mcp.json`; they are removed only when you explicitly turn them off or delete them in CC Switch.
### Sync Conditions
MCP server sync only executes when the corresponding app is installed:
- **Claude**: Requires `~/.claude/` directory or `~/.claude.json` file to exist
- **Claude Code**: Requires `~/.claude/` directory or `~/.claude.json` file to exist
- **Codex**: Requires `~/.codex/` directory to exist
- **Gemini**: Requires `~/.gemini/` directory to exist
- **Gemini CLI**: Requires `~/.gemini/` directory to exist
- **Grok Build**: Requires `~/.grok/` directory to exist
- **OpenCode**: Requires `~/.config/opencode/` directory to exist
- **Hermes**: Requires `~/.hermes/` directory to exist
- **Pi**: Writes to `~/.pi/agent/mcp.json` (the Pi configuration directory can be set with `PI_CODING_AGENT_DIR`)
> 💡 **Tip**: If a CLI tool is not installed, enabling its toggle will not cause an error, but the configuration will not be written. MiniMax Code is the exception: CC Switch does not check whether it is installed and writes `~/.minimax/mcp.json` directly, creating the directory if it does not exist.
@@ -146,27 +162,29 @@ When the toggle is disabled, the configuration is removed from the file.
## Edit Server
1. Click the "Edit" button on the right side of the server row
2. Modify the configuration
2. Modify the configuration in the drawer (the name can't be changed)
3. Click "Save"
Changes are immediately synced to enabled app configuration files.
## Delete Server
1. Click the "Delete" button on the right side of the server row
1. Click "Delete" in the ⋯ menu on the right side of the server row
2. Confirm deletion
After deletion, the configuration is removed from all app configuration files.
Deletion cannot be undone. The configuration is removed from CC Switch and from the configuration files of every app it was enabled for.
## Import Existing Configurations
If you have already configured MCP servers in CLI tools, you can import them into CC Switch:
1. Click the "Import Existing" button at the top of the MCP page
2. CC Switch reads the existing configuration of every MCP-capable app (Claude / Codex / Gemini / Grok Build / OpenCode / Hermes / MiniMax Code) in one pass and imports it
3. When finished, it shows how many servers were imported; if no new servers are found, it tells you so
1. Click the "Import from apps" button at the top of the MCP page
2. CC Switch reads the existing configuration of every MCP-capable app (Claude Code / Codex / Gemini CLI / Grok Build / OpenCode / Hermes / Pi / MiniMax Code) in one pass and imports it
3. When finished, an "Import finished" dialog lists which MCP servers were added and which files were read; if no new servers are found, it tells you no new MCP servers were found
Imported servers are automatically enabled for the app they came from. When importing from MiniMax Code, the enabled status follows the `enabled` field in `mcp.json`; entries that conflict with an existing server's configuration or are invalid are not imported, in which case a message appears saying N servers were imported but import failed for some apps, along with the reasons.
Import reads only user-level configuration: MCP servers that `claude mcp add` adds to a project by default in Claude Code, and MCP servers bundled with plugins, are not imported.
Imported servers are automatically enabled for the app they came from; for servers with the same name as an existing one, only the switch for the corresponding app is turned on, and the configuration stays as it is in CC Switch. When importing from MiniMax Code, the enabled status follows the `enabled` field in `mcp.json`; entries that conflict with an existing server's configuration or are invalid are not imported, in which case a message "Some apps couldn't be read" appears along with the reasons.
## Configuration File Formats