Skip to content

docs: add English translations of configuration.md and mcp.md #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
qorzj merged 2 commits into from
May 15, 2026
+374 −7
Merged

docs: add English translations of configuration.md and mcp.md #56

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0c6b054
docs: translate configuration.md and mcp.md to English
rock-solid-sites May 13, 2026
309a887
docs: restructure translations as _en.md siblings per maintainer requ…
rock-solid-sites May 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 172 additions & 0 deletions docs/configuration_en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
# Deep Code Configuration

## Configuration Hierarchy

Configuration is applied in the following priority order (lower-numbered sources are overridden by higher-numbered ones):

| Layer | Configuration Source | Description |
| ----- | -------------------- | ---------------------------------------------- |
| 1 | Defaults | Hardcoded defaults within the application |
| 2 | User settings file | Global settings for the current user |
| 3 | Project settings file| Project-specific settings |
| 4 | Environment variables| System-wide or session-specific variables |

## Settings File

Deep Code uses the `settings.json` file for persistent configuration, supporting two storage locations:

| File Type | Location | Scope |
| ------------------- | ----------------------------------------- | --------------------------------------------------------------------- |
| User settings file | `~/.deepcode/settings.json` | Applies to all Deep Code sessions for the current user. |
| Project settings file | `<project root>/.deepcode/settings.json` | Takes effect only when running Deep Code in that specific project. Project settings override user settings. |

### Available Settings in `settings.json`

The following are all the top-level fields supported in `settings.json`, along with the sub-fields inside `env`:

| Field | Type | Description |
| ------------------ | ------- | --------------------------------------------------------------------------- |
| `env` | object | Group of environment variables (see sub-field table below) |
| `model` | string | Model name. Takes precedence over `env.MODEL` |
| `thinkingEnabled` | boolean | Whether to enable thinking mode (enabled by default for DeepSeek V4 series)|
| `reasoningEffort` | string | Reasoning intensity, either `"high"` or `"max"` (default `"max"`) |
| `debugLogEnabled` | boolean | Enable debug log output (default `false`) |
| `notify` | string | Full path to a task-completion notification script (e.g., Slack notification script) |
| `webSearchTool` | string | Full path to a custom web search script |
| `mcpServers` | object | MCP server configurations (keys are service names, values are McpServerConfig objects) |

#### `env` Sub-fields

| Field | Type | Description |
| ----------------- | ------ | ---------------------------------------------------------------- |
| `MODEL` | string | Model name, e.g. `"deepseek-v4-pro"`, `"deepseek-v4-flash"` |
| `BASE_URL` | string | Base URL for API requests, e.g. `"https://api.deepseek.com"` |
| `API_KEY` | string | API key |
| `THINKING_ENABLED`| string | Enable thinking mode |
| `REASONING_EFFORT`| string | Reasoning intensity |
| `DEBUG_LOG_ENABLED`| string| Enable debug log output |
| `<any other KEY>` | string | Custom environment variable |

#### `thinkingEnabled` — Thinking Mode

Whether to enable DeepSeek thinking mode. Set to `true` to enable, `false` to disable.

- For `deepseek-v4-pro` and `deepseek-v4-flash`, thinking mode is **enabled by default**.
- For other models, thinking mode is **disabled by default**.

#### `reasoningEffort` — Reasoning Intensity

When thinking mode is enabled, controls the depth of the model’s reasoning:

| Value | Description |
| ------ | --------------------------------------------------------- |
| `max` | Maximum reasoning depth (default) |
| `high` | Higher reasoning depth with relatively lower token usage |

#### `notify` — Task Completion Notification

Set a full path to a shell script. When the AI assistant finishes a round of tasks, the script is executed automatically, which can be used to send notifications (e.g., a Slack message).

```json
{
"notify": "/path/to/slack-notify.sh"
}
```

#### `webSearchTool` — Custom Web Search

Deep Code has a built-in, free-to-use Web Search tool. If you need custom search logic, set `webSearchTool` to the full path of an executable script:

```json
{
"webSearchTool": "/path/to/my-search-script.sh"
}
```

The script receives a search query as an argument and outputs results in JSON format for the AI.

#### `mcpServers` — MCP Servers

Configuration for MCP (Model Context Protocol) servers. The value is a key-value pair, where the key is the service name and the value is a server configuration object.

```json
{
"mcpServers": {
"<service name>": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
}
}
}
}
```

| McpServerConfig field | Type | Required | Description |
| --------------------- | -------- | -------- | ------------------------------------------------------------------------ |
| `command` | string | Yes | Executable path or command (e.g. `npx`, `node`, `python`) |
| `args` | string[] | No | List of arguments passed to the command |
| `env` | object | No | Environment variables passed to the MCP server process |

> When `command` is `npx`, Deep Code automatically prepends `-y` to the arguments.

For detailed MCP usage instructions, refer to [mcp.md](mcp.md).

#### `debugLogEnabled` — Debug Log

Set to `true` to enable detailed debug logging (default `false`), useful for troubleshooting API calls and tool execution.

## Environment Variable Priority

Environment variables are a common way to configure applications, especially for sensitive information (such as api-key) or settings that may change between environments.

### Priority Principle

Environment variable priority follows the logic of “the more specific and localized the configuration, the higher the priority”, and the override rule of “env files protect existing environment by default, system variables override env files”. (The `env` object in settings.json can be thought of as a type of env file.)

Priority levels (from lowest to highest):
1. `env` defined at the top level of `settings.json` – this is a general configuration for the entire tool and all its subprocesses (global variables). Can be overridden by outer environment variables, but the environment variable KEY has the `DEEPCODE_` prefix removed.
2. `env` defined inside `mcpServers` in `settings.json` – this is the most specific configuration for a particular MCP service (local variables). Can be overridden by outer environment variables, but the KEY has the `MCP_` prefix removed.
3. Shell/system environment variables – operating system level.

### Scenarios

#### 1. Setting the model’s api_key and base_url

Applied in the following priority order (lower-numbered sources are overridden by higher-numbered ones) – using api_key as an example:

1. Hardcoded default: `""`
2. User-level settings.json: `{"env": {"API_KEY": "abc123"}}`
3. Project-level settings.json: `{"env": {"API_KEY": "abc123"}}`
4. System environment variable: `DEEPCODE_API_KEY=abc123 deepcode`

#### 2. Setting model, thinkingEnabled, and reasoningEffort

Applied in the following priority order (lower-numbered overridden by higher-numbered) – using thinkingEnabled as an example:

1. Hardcoded default: `true`
2. User-level settings.json: `{"env": {"THINKING_ENABLED": "true"}}`
3. User-level settings.json: `{"thinkingEnabled": true}`
4. Project-level settings.json: `{"env": {"THINKING_ENABLED": "true"}}`
5. Project-level settings.json: `{"thinkingEnabled": true}`
6. System environment variable: `DEEPCODE_THINKING_ENABLED=true deepcode`

#### 3. Setting environment variables for external scripts like notify and webSearchTool

Applied in the following priority order (lower-numbered overridden by higher-numbered) – using notify as an example:

1. Hardcoded default: `os.environ.get('WEBHOOK', '...') # notify script code`
2. User-level settings.json: `{"env": {"WEBHOOK": "..."}}`
3. Project-level settings.json: `{"env": {"WEBHOOK": "true"}}`
4. System environment variable: `DEEPCODE_WEBHOOK=... deepcode`

#### 4. Setting environment variables for an MCP Service

Applied in the following priority order (lower-numbered overridden by higher-numbered) – using a GitHub MCP server as an example:

1. User-level settings.json: `{"mcpServers":{"github":{"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"..."}}}}`
2. User-level settings.json: `{"env": {"MCP_GITHUB_PERSONAL_ACCESS_TOKEN": "..."}}`
3. Project-level settings.json: `{"mcpServers":{"github":{"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"..."}}}}`
4. Project-level settings.json: `{"env": {"MCP_GITHUB_PERSONAL_ACCESS_TOKEN": "..."}}`
5. System environment variable: `DEEPCODE_MCP_GITHUB_PERSONAL_ACCESS_TOKEN=... deepcode`
9 changes: 2 additions & 7 deletions docs/mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,12 +146,7 @@ MCP 工具在 Deep Code 中的命名格式为 `mcp__<服务名>__<工具名>`，

## 使用 MCP

配置完成后，启动 `deepcode`，使用 `/mcp` 命令管理 MCP 连接：

- `/mcp` — 查看已配置的 MCP 服务器状态
- `/mcp add` — 添加新的 MCP 服务器
- `/mcp remove` — 移除 MCP 服务器
- `/mcp list` — 列出所有已连接的 MCP 服务器及其工具
配置完成后，启动 `deepcode`，在聊天中输入 `/mcp` 即可查看所有已配置的 MCP 服务器状态以及每个服务器提供的工具列表。

在对话中直接使用 MCP 工具名称即可调用，例如：

Expand All @@ -172,7 +167,7 @@ MCP 工具名称由三部分组成：`mcp__<服务名>__<工具名>`
| playwright | browser_navigate | `mcp__playwright__browser_navigate` |
| playwright | browser_take_screenshot | `mcp__playwright__browser_take_screenshot` |

你可以通过 `/mcp list` 查看每个服务器提供的具体工具列表。
你可以通过 `/mcp` 查看每个服务器提供的具体工具列表。

## 故障排查

Expand Down
200 changes: 200 additions & 0 deletions docs/mcp_en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,200 @@
# Deep Code CLI MCP Configuration Guide

Deep Code CLI supports MCP (Model Context Protocol), enabling AI assistants to connect with external tools and services such as GitHub, browsers, databases, and more.

## Overview

Once MCP is configured, Deep Code can:

- Operate on GitHub repositories (view issues, create PRs, search code, etc.)
- Control browsers (screenshots, clicks, form filling, etc.)
- Access the file system
- Connect to databases and APIs
- ...and any external service compatible with the MCP protocol

MCP tools are named in Deep Code using the format `mcp__<service_name>__<tool_name>`, for example `mcp__github__search_code`.

## Configuring MCP Servers

Edit `~/.deepcode/settings.json` and add the `mcpServers` field:

```json
{
"env": {
"MODEL": "deepseek-v4-pro",
"BASE_URL": "https://api.deepseek.com",
"API_KEY": "sk-..."
},
"thinkingEnabled": true,
"reasoningEffort": "max",
"mcpServers": {
"<service_name>": {
"command": "<executable>",
"args": ["<arg1>", "<arg2>"],
"env": {
"<env_var>": "<value>"
}
}
}
}
```

### Configuration Fields

| Field | Type | Required | Description |
| --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `command` | string | Yes | Path or command of the MCP server executable (e.g., `npx`, `node`, `python`). When the command is `npx`, Deep Code automatically prepends `-y` to the arguments. |
| `args` | string[] | No | List of arguments to pass to the command |
| `env` | object | No | Environment variables (e.g., API keys) to pass to the MCP server process |

## Common MCP Examples

### GitHub MCP

Allows Deep Code to directly operate on GitHub repositories (search code, manage issues/PRs, read/write files, etc.):

```json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
}
}
}
}
```

> Generate a GitHub Personal Access Token at [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens).

### Browser Control (Playwright)

Lets Deep Code control a browser for screenshots, page interactions, etc.:

```json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
```

### File System

Enables Deep Code to read and write files within a specified directory:

```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
}
}
}
```

### Custom Python MCP

```json
{
"mcpServers": {
"my-tool": {
"command": "python",
"args": ["-m", "my_mcp_server"],
"env": {
"API_KEY": "xxx"
}
}
}
}
```

## Full Configuration Example

Below is a complete `~/.deepcode/settings.json` with both GitHub and Playwright MCP servers configured:

```json
{
"env": {
"MODEL": "deepseek-v4-pro",
"BASE_URL": "https://api.deepseek.com",
"API_KEY": "sk-xxxxxxxxxxxx"
},
"thinkingEnabled": true,
"reasoningEffort": "max",
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
}
},
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
```

## Using MCP

After configuration, start `deepcode` and type `/mcp` in the chat to view the status of all configured MCP servers and the list of tools each server provides.

Simply use the MCP tool name in your conversation to invoke it, for example:

```
Help me search for issues in the deepcode-cli repository on GitHub
```

The AI will automatically invoke the `mcp__github__search_issues` tool to complete the action.

## Tool Naming Convention

An MCP tool name consists of three parts: `mcp__<service_name>__<tool_name>`

| Service | Tool Name | Full Invocation Name |
| ---------- | ----------------------- | ------------------------------------------- |
| github | search_code | `mcp__github__search_code` |
| github | create_pull_request | `mcp__github__create_pull_request` |
| playwright | browser_navigate | `mcp__playwright__browser_navigate` |
| playwright | browser_take_screenshot | `mcp__playwright__browser_take_screenshot` |

You can view the list of tools provided by each server using `/mcp`.

## Troubleshooting

### Startup Failure

If an MCP server fails to start, check:

1. Whether `command` is installed (e.g., `npx` requires Node.js)
2. Whether environment variables in `env` are correct (e.g., `GITHUB_PERSONAL_ACCESS_TOKEN`)
3. Whether the terminal running `deepcode` has network access

### Tools Not Showing Up

1. Verify that the `mcpServers` field in `settings.json` is correctly formatted
2. After starting deepcode, use `/mcp` to check server status
3. If the server status shows an error, debug based on the error message

### Windows Users

On Windows, Deep Code CLI automatically adds shell support for `.cmd` commands. If your MCP command is a batch script, ensure the filename ends with `.cmd`.

## Writing Your Own MCP Server

MCP servers follow the [Model Context Protocol](https://modelcontextprotocol.io/) specification and communicate using JSON‑RPC 2.0. You can write an MCP server in any language as long as it implements the following methods:

1. `initialize` — Handshake and protocol negotiation
2. `tools/list` — Return the list of available tools
3. `tools/call` — Execute a tool call

For more information, see the [official MCP documentation](https://modelcontextprotocol.io/).