Content
# Tool List
A local MCP server that dispatches code work to DeepSeek TUI's `deepseek exec` non-interactive entry, with DeepSeek V4 Pro handling heavy lifting and code generation. No intermediate gateway - DeepSeek TUI connects directly to DeepSeek API.
Design goals: Move heavy lifting to asynchronous worker for execution, with the main thread only retrieving task status, changed files, check summaries, and diff outputs, reducing Codex main thread token consumption.
By default, tool responses are kept concise: returning status, changed files, check summaries, and artifact paths. Only include `include_diff`, `include_task`, `include_scoped_patch`, or `include_check_output` when the main thread needs the full context.
## Comparison with the old version (Claude Code + Gateway)
| Dimension | Old Architecture | New Architecture |
| --- | --- | --- |
| Worker Engine | Claude Code CLI | DeepSeek TUI (`deepseek exec`) |
| API Routing | Anthropic Compatible Gateway → DeepSeek V4 | DeepSeek TUI → DeepSeek V4 Pro **Direct Connection** |
| Dependencies | Claude Code + Gateway | DeepSeek TUI (`brew install deepseek-tui`) |
| Authentication | Gateway Token + Anthropic Environment Variables | DeepSeek API Key (single env var) |
| Toolset | Claude Code Tools | DeepSeek generates structured write plans, MCP server safely lands within `allowed_dirs` |
| Latency | Extra hop | One less hop, lower latency |
| Maintenance | Need to maintain gateway + Claude Code two external components | Only need to maintain DeepSeek TUI one component |
## Features
- `start` — Launch asynchronous worker task
- `get` — Get task current status
- `tail` — Return worker transcription log slice
- `wait` — Block waiting for task completion
- `cancel` — Request task cancellation
- `setup` — Output Codex Desktop and DeepSeek TUI configuration snippets
- `doctor` — Check local DeepSeek TUI and runtime environment
- `deploy` — Write local env file, run script, and Codex configuration block using `--write`
## Environment Requirements
- Node.js 20 or later
- DeepSeek TUI installed and available on `PATH`, or specified via `DEEPSEEK_TUI_BIN`
- Valid DeepSeek API Key ([platform.deepseek.com](https://platform.deepseek.com) → API Keys)
- Git workspace (if automatic `git diff --check` verification is needed)
## Installation
```bash
npm install
npm run build
```
## Quick Start
If you just want to run this project, follow these 5 steps:
1. Clone the repository and enter the directory
2. Install dependencies and build
3. Configure DeepSeek API Key
4. Run `doctor --live` for a real machine check
5. Register MCP server to Codex Desktop
Example process:
```bash
git clone https://github.com/your-name/codex-desktop-mcp-deepseek-v4-worker.git
cd codex-desktop-mcp-deepseek-v4-worker
cp .env.example .env
npm install
npm run build
set -a && source .env && set +a
node dist/src/cli.js doctor --live
codex mcp add deepseek-worker -- node /absolute/path/to/dist/src/cli.js serve
```
## Configure DeepSeek
Set the following environment variables before starting MCP server:
```bash
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export DEEPSEEK_MODEL="deepseek-v4-pro"
export DEEPSEEK_MODEL_NAME="DeepSeek V4 Pro"
export DEEPSEEK_MODEL_CAPABILITIES="thinking,interleaved_thinking"
```
Worker control (optional):
```bash
export DEEPSEEK_WORKER_PERMISSION_MODE="dontAsk"
export DEEPSEEK_WORKER_REPAIR_ATTEMPTS="0"
export DEEPSEEK_WORKER_WORKSPACE_ROOT="/absolute/path/to/repo"
export DEEPSEEK_WORKER_ALLOWED_DIRS="/absolute/path/to/repo"
export DEEPSEEK_WORKER_MAX_CONCURRENT_JOBS="2"
export DEEPSEEK_WORKER_MAX_WAIT_TOOL_MS="45000"
export DEEPSEEK_TUI_BIN="deepseek"
export DEEPSEEK_WORKER_EFFORT="high" # low | medium | high | xhigh | max
export DEEPSEEK_WORKER_CHECKS="git diff --check" # comma-separated check commands run after task completion
export DEEPSEEK_WORKER_CONTEXT_MAX_BYTES="120000"
export DEEPSEEK_WORKER_CONTEXT_MAX_FILE_BYTES="40000"
export DEEPSEEK_WORKER_CONTEXT_FILE_LIMIT="20"
```
## Codex Desktop Setup
Register server via Codex CLI:
```bash
codex mcp add deepseek-worker -- node /absolute/path/to/dist/src/cli.js serve
```
If you prefer to edit `~/.codex/config.toml`:
```toml
[mcp_servers.deepseek_worker]
command = "node"
args = ["/absolute/path/to/dist/src/cli.js", "serve"]
```
## Codex Default Delegation Policy
This repository's root contains `AGENTS.md`, which tells Codex to delegate coding tasks to DeepSeek TUI worker by default, only falling back to Codex local execution if DeepSeek returns no valid results.
Default process:
- Coding, refactoring, testing, documentation generation, etc. tasks are delegated to DeepSeek worker
- Small, simple edits can be completed locally by Codex
- Call `start` and then poll `get` / `tail`, don't block `wait` for too long
- Normal coding tasks recommend passing `repair_attempts: 1`
- Try to pass `context_files` or `context_globs` to avoid feeding the entire repository to DeepSeek
## One-Click Deployment
Preview deployment plan:
```bash
npm run deploy -- --workspace /absolute/path/to/repo --api-key 'sk-...'
```
Write local env file, run script, and Codex configuration block:
```bash
npm run deploy -- --write --workspace /absolute/path/to/repo --api-key 'sk-...'
```
Common deployment parameters:
- `--workspace` sets the worker's editing repository
- `--allowed-dirs` limits the directories DeepSeek TUI can access
- `--model` overrides the model (default `deepseek-v4-pro`)
- `--model-name` overrides the model display name
- `--permission-mode` overrides the permission mode
- `--api-key` sets the DeepSeek API Key (will be sanitized when writing env file)
- `--runner-script` chooses the Codex side packaging script's write path
- `--worker-env-file` chooses the local env file's write path
- `--codex-config` chooses the Codex configuration file to update
- `--force` allows replacing existing non-managed `deepseek_worker` configuration block
## Recommended Process for Others
If you plan to share this project with team members or publicly on GitHub, recommend delivering it like this:
1. Keep `README.md`, `.env.example`, `AGENTS.md`
2. Don't submit the real `.env`
3. Run `npm test` once
4. Run `node dist/src/cli.js doctor --live` once
5. Share the repository address and README's "Quick Start" section with users
## Worker Behavior
- Worker uses DeepSeek TUI's `deepseek exec` non-interactive entry
- Passes worker prompts via `deepseek exec "<prompt>"`, captures stdout stream JSON output
- Uses `--output-mode stream-json` for structured output
- DeepSeek returns JSON write plan, format: `{ "summary": "...", "writes": [{ "path": "relative/path", "content": "full file content" }], "patches": [{ "path": "relative/path", "diff": "unified diff" }], "deletes": ["relative/path"] }`
- MCP server only accepts relative paths, rejects absolute paths, `.deepseek-worker` internal paths, and paths outside workspace or `allowed_dirs`
- Small changes recommend using `patches`, each patch can only modify one existing file; new files or large-scale rewriting still use `writes`
- `repair_attempts` enables automatic repair after failure check for single tasks; default `0`, can also set global default via `DEEPSEEK_WORKER_REPAIR_ATTEMPTS`
- Repair loop resends original task, failed check output, current diff, and related context to DeepSeek, applies repair plan via same `allowed_dirs` safe write logic
## Commands
```bash
npm run doctor
npm run setup
npm run deploy
npm test
```
`npm test` builds the project and executes a smoke test on the running MCP server using a mock DeepSeek TUI binary.
`doctor` checks if the DeepSeek TUI binary is available and the worker system prompt file exists. Use `doctor --live` only when you need to send a minimal prompt request via DeepSeek TUI explicitly.
## Output Files
Each task writes a small file package under `.deepseek-worker/<job-id>/`:
- `job.json`
- `prompt.txt`
- `snapshot.json`
- `transcript.log`
- `stdout.log`
- `stderr.log`
- `events.jsonl`
- `diff.patch`
## Notes
- If DeepSeek TUI is not installed, `doctor` will report. Can install via Homebrew: `brew install deepseek-tui`
- If task-generated diff is large, structured results will trim diff and write full patch to disk
- This project no longer depends on Anthropic compatible gateway; DeepSeek TUI communicates directly with DeepSeek API
- DeepSeek API Key provided via `DEEPSEEK_API_KEY` environment variable or DeepSeek TUI's own configuration (`~/.deepseek/config.toml` or keychain)
