Skip to content

Commit 368067a

Browse files
qorzjqorzj
authored
Merge pull request #56 from rock-solid-sites/add-english-doc-translations
docs: add English translations of configuration.md and mcp.md
2 parents 3ef5b8e + 309a887 commit 368067a

2 files changed

Lines changed: 372 additions & 0 deletions

File tree

‎docs/configuration_en.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# Deep Code Configuration
2+
3+
## Configuration Hierarchy
4+
5+
Configuration is applied in the following priority order (lower-numbered sources are overridden by higher-numbered ones):
6+
7+
| Layer | Configuration Source | Description |
8+
| ----- | -------------------- | ---------------------------------------------- |
9+
| 1 | Defaults | Hardcoded defaults within the application |
10+
| 2 | User settings file | Global settings for the current user |
11+
| 3 | Project settings file| Project-specific settings |
12+
| 4 | Environment variables| System-wide or session-specific variables |
13+
14+
## Settings File
15+
16+
Deep Code uses the `settings.json` file for persistent configuration, supporting two storage locations:
17+
18+
| File Type | Location | Scope |
19+
| ------------------- | ----------------------------------------- | --------------------------------------------------------------------- |
20+
| User settings file | `~/.deepcode/settings.json` | Applies to all Deep Code sessions for the current user. |
21+
| Project settings file | `<project root>/.deepcode/settings.json` | Takes effect only when running Deep Code in that specific project. Project settings override user settings. |
22+
23+
### Available Settings in `settings.json`
24+
25+
The following are all the top-level fields supported in `settings.json`, along with the sub-fields inside `env`:
26+
27+
| Field | Type | Description |
28+
| ------------------ | ------- | --------------------------------------------------------------------------- |
29+
| `env` | object | Group of environment variables (see sub-field table below) |
30+
| `model` | string | Model name. Takes precedence over `env.MODEL` |
31+
| `thinkingEnabled` | boolean | Whether to enable thinking mode (enabled by default for DeepSeek V4 series)|
32+
| `reasoningEffort` | string | Reasoning intensity, either `"high"` or `"max"` (default `"max"`) |
33+
| `debugLogEnabled` | boolean | Enable debug log output (default `false`) |
34+
| `notify` | string | Full path to a task-completion notification script (e.g., Slack notification script) |
35+
| `webSearchTool` | string | Full path to a custom web search script |
36+
| `mcpServers` | object | MCP server configurations (keys are service names, values are McpServerConfig objects) |
37+
38+
#### `env` Sub-fields
39+
40+
| Field | Type | Description |
41+
| ----------------- | ------ | ---------------------------------------------------------------- |
42+
| `MODEL` | string | Model name, e.g. `"deepseek-v4-pro"`, `"deepseek-v4-flash"` |
43+
| `BASE_URL` | string | Base URL for API requests, e.g. `"https://api.deepseek.com"` |
44+
| `API_KEY` | string | API key |
45+
| `THINKING_ENABLED`| string | Enable thinking mode |
46+
| `REASONING_EFFORT`| string | Reasoning intensity |
47+
| `DEBUG_LOG_ENABLED`| string| Enable debug log output |
48+
| `<any other KEY>` | string | Custom environment variable |
49+
50+
#### `thinkingEnabled` — Thinking Mode
51+
52+
Whether to enable DeepSeek thinking mode. Set to `true` to enable, `false` to disable.
53+
54+
- For `deepseek-v4-pro` and `deepseek-v4-flash`, thinking mode is **enabled by default**.
55+
- For other models, thinking mode is **disabled by default**.
56+
57+
#### `reasoningEffort` — Reasoning Intensity
58+
59+
When thinking mode is enabled, controls the depth of the model’s reasoning:
60+
61+
| Value | Description |
62+
| ------ | --------------------------------------------------------- |
63+
| `max` | Maximum reasoning depth (default) |
64+
| `high` | Higher reasoning depth with relatively lower token usage |
65+
66+
#### `notify` — Task Completion Notification
67+
68+
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).
69+
70+
```json
71+
{
72+
"notify": "/path/to/slack-notify.sh"
73+
}
74+
```
75+
76+
#### `webSearchTool` — Custom Web Search
77+
78+
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:
79+
80+
```json
81+
{
82+
"webSearchTool": "/path/to/my-search-script.sh"
83+
}
84+
```
85+
86+
The script receives a search query as an argument and outputs results in JSON format for the AI.
87+
88+
#### `mcpServers` — MCP Servers
89+
90+
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.
91+
92+
```json
93+
{
94+
"mcpServers": {
95+
"<service name>": {
96+
"command": "npx",
97+
"args": ["-y", "@modelcontextprotocol/server-github"],
98+
"env": {
99+
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
100+
}
101+
}
102+
}
103+
}
104+
```
105+
106+
| McpServerConfig field | Type | Required | Description |
107+
| --------------------- | -------- | -------- | ------------------------------------------------------------------------ |
108+
| `command` | string | Yes | Executable path or command (e.g. `npx`, `node`, `python`) |
109+
| `args` | string[] | No | List of arguments passed to the command |
110+
| `env` | object | No | Environment variables passed to the MCP server process |
111+
112+
> When `command` is `npx`, Deep Code automatically prepends `-y` to the arguments.
113+
114+
For detailed MCP usage instructions, refer to [mcp.md](mcp.md).
115+
116+
#### `debugLogEnabled` — Debug Log
117+
118+
Set to `true` to enable detailed debug logging (default `false`), useful for troubleshooting API calls and tool execution.
119+
120+
## Environment Variable Priority
121+
122+
Environment variables are a common way to configure applications, especially for sensitive information (such as api-key) or settings that may change between environments.
123+
124+
### Priority Principle
125+
126+
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.)
127+
128+
Priority levels (from lowest to highest):
129+
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.
130+
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.
131+
3. Shell/system environment variables – operating system level.
132+
133+
### Scenarios
134+
135+
#### 1. Setting the model’s api_key and base_url
136+
137+
Applied in the following priority order (lower-numbered sources are overridden by higher-numbered ones) – using api_key as an example:
138+
139+
1. Hardcoded default: `""`
140+
2. User-level settings.json: `{"env": {"API_KEY": "abc123"}}`
141+
3. Project-level settings.json: `{"env": {"API_KEY": "abc123"}}`
142+
4. System environment variable: `DEEPCODE_API_KEY=abc123 deepcode`
143+
144+
#### 2. Setting model, thinkingEnabled, and reasoningEffort
145+
146+
Applied in the following priority order (lower-numbered overridden by higher-numbered) – using thinkingEnabled as an example:
147+
148+
1. Hardcoded default: `true`
149+
2. User-level settings.json: `{"env": {"THINKING_ENABLED": "true"}}`
150+
3. User-level settings.json: `{"thinkingEnabled": true}`
151+
4. Project-level settings.json: `{"env": {"THINKING_ENABLED": "true"}}`
152+
5. Project-level settings.json: `{"thinkingEnabled": true}`
153+
6. System environment variable: `DEEPCODE_THINKING_ENABLED=true deepcode`
154+
155+
#### 3. Setting environment variables for external scripts like notify and webSearchTool
156+
157+
Applied in the following priority order (lower-numbered overridden by higher-numbered) – using notify as an example:
158+
159+
1. Hardcoded default: `os.environ.get('WEBHOOK', '...') # notify script code`
160+
2. User-level settings.json: `{"env": {"WEBHOOK": "..."}}`
161+
3. Project-level settings.json: `{"env": {"WEBHOOK": "true"}}`
162+
4. System environment variable: `DEEPCODE_WEBHOOK=... deepcode`
163+
164+
#### 4. Setting environment variables for an MCP Service
165+
166+
Applied in the following priority order (lower-numbered overridden by higher-numbered) – using a GitHub MCP server as an example:
167+
168+
1. User-level settings.json: `{"mcpServers":{"github":{"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"..."}}}}`
169+
2. User-level settings.json: `{"env": {"MCP_GITHUB_PERSONAL_ACCESS_TOKEN": "..."}}`
170+
3. Project-level settings.json: `{"mcpServers":{"github":{"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"..."}}}}`
171+
4. Project-level settings.json: `{"env": {"MCP_GITHUB_PERSONAL_ACCESS_TOKEN": "..."}}`
172+
5. System environment variable: `DEEPCODE_MCP_GITHUB_PERSONAL_ACCESS_TOKEN=... deepcode`

‎docs/mcp_en.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Deep Code CLI MCP Configuration Guide
2+
3+
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.
4+
5+
## Overview
6+
7+
Once MCP is configured, Deep Code can:
8+
9+
- Operate on GitHub repositories (view issues, create PRs, search code, etc.)
10+
- Control browsers (screenshots, clicks, form filling, etc.)
11+
- Access the file system
12+
- Connect to databases and APIs
13+
- ...and any external service compatible with the MCP protocol
14+
15+
MCP tools are named in Deep Code using the format `mcp__<service_name>__<tool_name>`, for example `mcp__github__search_code`.
16+
17+
## Configuring MCP Servers
18+
19+
Edit `~/.deepcode/settings.json` and add the `mcpServers` field:
20+
21+
```json
22+
{
23+
"env": {
24+
"MODEL": "deepseek-v4-pro",
25+
"BASE_URL": "https://api.deepseek.com",
26+
"API_KEY": "sk-..."
27+
},
28+
"thinkingEnabled": true,
29+
"reasoningEffort": "max",
30+
"mcpServers": {
31+
"<service_name>": {
32+
"command": "<executable>",
33+
"args": ["<arg1>", "<arg2>"],
34+
"env": {
35+
"<env_var>": "<value>"
36+
}
37+
}
38+
}
39+
}
40+
```
41+
42+
### Configuration Fields
43+
44+
| Field | Type | Required | Description |
45+
| --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
46+
| `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. |
47+
| `args` | string[] | No | List of arguments to pass to the command |
48+
| `env` | object | No | Environment variables (e.g., API keys) to pass to the MCP server process |
49+
50+
## Common MCP Examples
51+
52+
### GitHub MCP
53+
54+
Allows Deep Code to directly operate on GitHub repositories (search code, manage issues/PRs, read/write files, etc.):
55+
56+
```json
57+
{
58+
"mcpServers": {
59+
"github": {
60+
"command": "npx",
61+
"args": ["-y", "@modelcontextprotocol/server-github"],
62+
"env": {
63+
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
64+
}
65+
}
66+
}
67+
}
68+
```
69+
70+
> Generate a GitHub Personal Access Token at [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens).
71+
72+
### Browser Control (Playwright)
73+
74+
Lets Deep Code control a browser for screenshots, page interactions, etc.:
75+
76+
```json
77+
{
78+
"mcpServers": {
79+
"playwright": {
80+
"command": "npx",
81+
"args": ["@playwright/mcp@latest"]
82+
}
83+
}
84+
}
85+
```
86+
87+
### File System
88+
89+
Enables Deep Code to read and write files within a specified directory:
90+
91+
```json
92+
{
93+
"mcpServers": {
94+
"filesystem": {
95+
"command": "npx",
96+
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
97+
}
98+
}
99+
}
100+
```
101+
102+
### Custom Python MCP
103+
104+
```json
105+
{
106+
"mcpServers": {
107+
"my-tool": {
108+
"command": "python",
109+
"args": ["-m", "my_mcp_server"],
110+
"env": {
111+
"API_KEY": "xxx"
112+
}
113+
}
114+
}
115+
}
116+
```
117+
118+
## Full Configuration Example
119+
120+
Below is a complete `~/.deepcode/settings.json` with both GitHub and Playwright MCP servers configured:
121+
122+
```json
123+
{
124+
"env": {
125+
"MODEL": "deepseek-v4-pro",
126+
"BASE_URL": "https://api.deepseek.com",
127+
"API_KEY": "sk-xxxxxxxxxxxx"
128+
},
129+
"thinkingEnabled": true,
130+
"reasoningEffort": "max",
131+
"mcpServers": {
132+
"github": {
133+
"command": "npx",
134+
"args": ["-y", "@modelcontextprotocol/server-github"],
135+
"env": {
136+
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
137+
}
138+
},
139+
"playwright": {
140+
"command": "npx",
141+
"args": ["@playwright/mcp@latest"]
142+
}
143+
}
144+
}
145+
```
146+
147+
## Using MCP
148+
149+
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.
150+
151+
Simply use the MCP tool name in your conversation to invoke it, for example:
152+
153+
```
154+
Help me search for issues in the deepcode-cli repository on GitHub
155+
```
156+
157+
The AI will automatically invoke the `mcp__github__search_issues` tool to complete the action.
158+
159+
## Tool Naming Convention
160+
161+
An MCP tool name consists of three parts: `mcp__<service_name>__<tool_name>`
162+
163+
| Service | Tool Name | Full Invocation Name |
164+
| ---------- | ----------------------- | ------------------------------------------- |
165+
| github | search_code | `mcp__github__search_code` |
166+
| github | create_pull_request | `mcp__github__create_pull_request` |
167+
| playwright | browser_navigate | `mcp__playwright__browser_navigate` |
168+
| playwright | browser_take_screenshot | `mcp__playwright__browser_take_screenshot` |
169+
170+
You can view the list of tools provided by each server using `/mcp`.
171+
172+
## Troubleshooting
173+
174+
### Startup Failure
175+
176+
If an MCP server fails to start, check:
177+
178+
1. Whether `command` is installed (e.g., `npx` requires Node.js)
179+
2. Whether environment variables in `env` are correct (e.g., `GITHUB_PERSONAL_ACCESS_TOKEN`)
180+
3. Whether the terminal running `deepcode` has network access
181+
182+
### Tools Not Showing Up
183+
184+
1. Verify that the `mcpServers` field in `settings.json` is correctly formatted
185+
2. After starting deepcode, use `/mcp` to check server status
186+
3. If the server status shows an error, debug based on the error message
187+
188+
### Windows Users
189+
190+
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`.
191+
192+
## Writing Your Own MCP Server
193+
194+
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:
195+
196+
1. `initialize` — Handshake and protocol negotiation
197+
2. `tools/list` — Return the list of available tools
198+
3. `tools/call` — Execute a tool call
199+
200+
For more information, see the [official MCP documentation](https://modelcontextprotocol.io/).

0 commit comments

Comments
 (0)