@developkiko/desktop-commander

🇷🇺 Русская версия

<br />

<div align="center"> <h1>🖥️ @developkiko/desktop-commander</h1> <p><strong>MCP server for terminal operations and file editing</strong></p> <p>Fork of <a href="https://github.com/wonderwhy-er/DesktopCommanderMCP">Desktop Commander</a> with critical fixes for large file handling</p>

<p> <a href="https://www.npmjs.com/package/@developkiko/desktop-commander"> <img src="https://img.shields.io/npm/v/@developkiko/desktop-commander?style=for-the-badge&logo=npm&color=cb3837" alt="npm version" /> </a> <a href="https://github.com/developkiko/DsktpCmndr/blob/main/LICENSE"> <img src="https://img.shields.io/github/license/developkiko/DsktpCmndr?style=for-the-badge&color=blue" alt="MIT License" /> </a> <a href="https://github.com/developkiko/DsktpCmndr"> <img src="https://img.shields.io/github/stars/developkiko/DsktpCmndr?style=for-the-badge&logo=github&color=gold" alt="GitHub Stars" /> </a> <br /> <a href="https://nodejs.org/"> <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?style=for-the-badge&logo=node.js" alt="Node Version" /> </a> <a href="https://www.typescriptlang.org/"> <img src="https://img.shields.io/badge/built%20with-TypeScript-3178C6?style=for-the-badge&logo=typescript" alt="TypeScript" /> </a> <img src="https://img.shields.io/badge/MCP-server-6C47FF?style=for-the-badge&logo=anthropic" alt="MCP Server" /> </p> </div>

---

📋 Table of Contents

• What is this?
• ✨ What's Fixed?
• 📦 Installation
• ⚙️ Configuration in Chatbox AI
• 🔧 Available Tools
• 💡 Usage Examples
• 📚 Why This Fork?
• 🔗 Links

---

🧐 What is this?

Desktop Commander is an MCP (Model Context Protocol) server that gives AI assistants like Claude, Chatbox, Cursor, and others direct access to your computer's file system and terminal.

With it, an LLM agent can:

• 📁 Create, read, edit, and delete files and folders
• 🔍 Search for files and text across your project
• 🖥️ Run terminal commands and Python scripts
• 📄 Work with PDFs, Excel files, and images
• ✏️ Perform surgical text replacements with edit_block

This is a maintained fork with critical bug fixes — see below.

---

✨ What's Fixed?

The original Desktop Commander had a critical issue: no content size limits in file operations. When an AI tried to write files larger than ~500 lines, the entire content was sent as a single MCP JSON-RPC message, causing:

❌ Unterminated string in JSON at position 37769

🔴 Problem 1: write_file buffer overflow

Before (original): Writing 5000 lines → 1 giant JSON-RPC string → stdio buffer overflows → JSON.parse crash

After (fixed): Content is automatically split into 30-line chunks, each written in a separate MCP call:

Chunk	Mode	Content
#1	rewrite	Lines 1–30
#2	append	Lines 31–60
#3	append	Lines 61–90
...	append	...
#167	append	Lines 4971–5000

🔴 Problem 2: No size validation for read/write

Before: writeFile() could receive 500MB+ in one call → OOM. readFile() could load a 2GB file → heap overflow.

After: Explicit byte limits with clear error messages:

• writeFile(): 10 MB max content size
• readFileInternal(): 50 MB max file size
• handleWriteFile(): 10,000 lines hard cap with auto-chunking up to that limit

🔴 Problem 3: Windows path handling

Paths are now properly normalized regardless of slash direction (/ vs \).

---

📦 Installation

Option A: Via npx (recommended)

npx @developkiko/desktop-commander@latest

Option B: Global install

npm install -g @developkiko/desktop-commander
desktop-commander

Option C: Local development

# Clone and build
git clone https://github.com/developkiko/DsktpCmndr.git
cd DsktpCmndr
npm install
npm run build

# Run directly
node dist/index.js

---

⚙️ Configuration in Chatbox AI

To use this server in Chatbox AI:

1. Open Settings → MCP Servers
2. Click Add MCP Server (or edit existing)
3. Fill in:

Field	Value
Name	DsktpCmndr
Type	stdio
Command	npx
Args	@developkiko/desktop-commander@latest
Env	(leave empty unless needed)

4. Save and restart Chatbox

Or, for the local build:

• Command: node
• Args: E:\LLM\mcps\DsktpCmndr\dist\index.js

---

🔧 Available Tools

#	Tool	Description
1	read_file	Read files (text, PDF, Excel, images) with offset/length pagination
2	read_multiple_files	Read multiple files at once
3	write_file	Auto-chunking! Writes files with automatic splitting for large content
4	edit_block	Surgical find-and-replace in files
5	create_directory	Create folders (recursive)
6	list_directory	List folder contents with configurable depth
7	move_file	Move or rename files
8	get_file_info	Get file metadata (size, dates, line count, sheets)
9	write_pdf	Create and modify PDF files
10	start_process	Run terminal commands and REPLs (Python, Node.js, etc.)
11	read_process_output	Read process output with pagination
12	interact_with_process	Send input to a running process
13	force_terminate	Stop a running process
14	kill_process	Kill a process by PID
15	start_search	Search files by name or content (streaming)
16	get_config	View server configuration
17	set_config_value	Modify server configuration

---

💡 Usage Examples

📁 Creating a project structure

"Create folders for a React project: src/components, src/pages, src/hooks, public, and a blank README.md"

flowchart LR
    A["🖥️ You ask AI"] --> B["create_directory('src/components')"]
    A --> C["create_directory('src/pages')"]
    A --> D["create_directory('src/hooks')"]
    A --> E["create_directory('public')"]
    A --> F["write_file('README.md','# My Project')"]

🔍 Searching for text in files

"Find all .ts files in E:\WORK\my\GameDev that contain GameLoop and show the first 10 lines"

1. start_search(path="E:\WORK\my\GameDev", pattern="GameLoop", searchType="content", filePattern="*.ts")
2. get_more_search_results(sessionId)
3. For each result: read_file(path, offset=0, length=10)

📊 Analyzing a large CSV

Bad approach: ❌ "Read this 500MB CSV file" → MCP buffer overflow

Good approach: ✅ "Read the first 5 lines of sales.csv to see headers, then start Python and analyze with pandas"

1. read_file("sales.csv", offset=0, length=5)  → shows headers
2. start_process("python -i")
3. import pandas as pd
4. df = pd.read_csv("E:/DATA/sales.csv")       ← Python reads directly
5. df.groupby("Region")["Amount"].sum()         ← analysis in Python

🐍 Running a Python script

"Run E:\scripts\backup.py and tell me what it outputs"

1. start_process("python E:\scripts\backup.py")
2. read_process_output(pid)

✏️ Replacing text across files

"Replace console.log with logger.info in all .js files in E:\WORK\app"

1. start_search(path="E:\WORK\app", pattern="console.log", filePattern="*.js")
2. For each match: edit_block(file, old="console.log", new="logger.info")

---

📚 Why This Fork?

The original Desktop Commander by wonderwhy-er is a fantastic project. This fork exists to:

1. Fix the critical auto-chunking bug — large files would crash the MCP transport
2. Add proper size validation — prevent OOM from accidental giant file reads/writes
3. Provide ongoing maintenance — as an independent community fork
4. Ensure Windows compatibility — proper path handling for Windows users

All credit for the original architecture goes to wonderwhy-er and contributors.

---

🔗 Links

Resource	Link
📦 npm	@developkiko/desktop-commander
🐙 GitHub	github.com/developkiko/DsktpCmndr
🏠 Original	Desktop Commander by wonderwhy-er
💬 MCP Protocol	modelcontextprotocol.io

---

<div align="center"> _{Built with ❤️ by <strong>Kiko</strong> — MIT License} </div>