Dalicore MCP Client

Streamlined Model Context Protocol (MCP) server with 8 essential tools for file operations, code editing, and command execution.

Built for efficiency based on real usage data - covers 97.5% of actual workflow with minimal overhead.

Why This Fork?

The Token Cost Problem: Every tool call in MCP consumes tokens. Desktop Commander's 25+ tools meant:

• AI models waste tokens evaluating irrelevant tools

• Increased confusion leads to wrong tool selection

• Higher API costs for every interaction

Original: Desktop Commander MCP had 25+ tools
Problem: Only 8 tools accounted for 97.5% of actual usage
Solution: Stripped down to essentials, enhanced the survivors

Data-driven design:

• Analyzed 12,302 actual tool calls across real usage

• Kept the 8 most-used tools (97.5% coverage)

• Cut 288 lines of bloat (46% reduction)

• Significantly less tool context sent with every interaction (25 → 8 tools)

Key improvements over Desktop Commander:

• System information built-in - No separate tool call needed (OS, architecture, paths, allowed directories)

• Line count tracking - read_file and write_file show actual lines processed

• Intelligent chunking - write_file automatically chunks large files (25-30 lines) to avoid token waste

• Better error messages - Clear guidance when operations fail, with suggestions for fixes

• Smart state detection - start_process detects REPL prompts and completion states automatically

Bottom line: Fewer tools = lower costs, faster responses, less confusion.

Related MCP server: MCP Custom Tools Server

The 8 Essential Tools

Process Management

start_process - Execute commands with smart state detection

• 34.4% of all usage

• Primary tool for running builds, tests, scripts

• Detects REPL prompts and completion states

File Operations

read_file - Read files with pagination, tail support, and URL fetching

• 29.2% of all usage

• Handles images (PNG, JPEG, GIF, WebP)

• Supports offset/length for large files

write_file - Write files with automatic chunking

• 2.2% of all usage

• Rewrite or append modes

• Smart 25-30 line chunks to avoid token waste

Code Editing

edit_block - Surgical text replacements with fuzzy matching

• 17.0% of all usage

• Character-level diff feedback

• Multiple occurrence support

Searching

search_code - Fast content search with ripgrep

• 11.2% of all usage

• Context lines, file patterns, regex support

• Structured output for easy parsing

search_files - Find files by name pattern

• 1.2% of all usage

• Glob pattern support

• Recursive directory traversal

File System

list_directory - List files and directories

• 2.5% of all usage

• Clear [FILE] and [DIR] markers

• Path validation

Debugging & History

tool_history - View recent tool call history with success/failure tracking

• Track what operations were performed and whether they succeeded

• See actual results (lines written, matches found, command output)

• Filter by tool type, time range, or file/command patterns

• Compact or verbose output modes with ✓/✗ status indicators

• Parses both request and result logs for complete operation history

Advanced filtering:

• filter: "edits" (write_file, edit_block only) or "all" (every tool call)

• since: Time-based filtering ("1h", "30m", "2d", or ISO timestamp)

• pathFilter: Search by file path or command content (e.g., "git push")

• showFullCommands: Display complete commands without truncation

Result tracking shows:

• Success/failure status with error messages

• Lines read/written for file operations

• Matches found for search operations

• Process output and exit status

• Actual replacements applied for edits

Use cases:

• Debug failed operations with detailed error messages

• Verify operations completed successfully

• Track command history and output

• Find all operations on specific files

• Audit recent changes by time period

What We Cut (and Why)

Removed ~18 tools that accounted for only 2.5% of usage:

❌ get_config / set_config_value → Just edit config file with edit_block
❌ read_multiple_files → Use multiple read_file calls
❌ create_directory → Use start_process("mkdir -p /path")
❌ move_file → Use start_process("mv src dst")
❌ interact_with_process / read_process_output → Use one-shot commands or temp scripts
❌ list_processes / kill_process → Use start_process("ps aux") / start_process("kill PID")
❌ And more...

Philosophy: Use start_process with OS commands instead of wrapping every shell command as a separate tool.

Smart Features

System Awareness

System info is automatically sent to the LLM on every connection:

• Operating system and architecture

• Default shell (bash, zsh, cmd, powershell)

• Allowed directories

• Path separator and case sensitivity

• OS-appropriate command guidance

No separate tool needed - Claude knows your environment automatically.

Helpful Blocked Command Messages

When you try to use a blocked command, you get helpful alternatives:

Example:

🚫 SED COMMAND BLOCKED

You tried: sed -n '100,200p' file.txt

**What to use instead:**
  ✅ read_file(path, { offset: 100, length: 101 })
  
For building files from pieces:
  ✅ start_process("head -100 file.txt > newfile.txt")
  
**You already have these tools - use them!**

Teaches best practices instead of just saying "no."

Installation

Prerequisites

• Node.js 18+

• npm

Setup

1. Clone the repository:

git clone https://github.com/Corlzee/dalicore-mcp-client.git
cd dalicore-mcp-client
npm install
npm run build

2. Add to Claude Desktop config:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "dalicore-mcp-client": {
      "command": "node",
      "args": ["/absolute/path/to/dalicore-mcp-client/dist/index.js"]
    }
  }
}

3. Restart Claude Desktop

Configuration

Config file location: ~/.config/commander-keen/config.json

Key Settings

{
  "blockedCommands": ["rm", "sudo", "chmod", "chown"],
  "defaultShell": "bash",
  "allowedDirectories": [
    "/home/user/projects",
    "/home/user/documents"
  ],
  "readOnlyDirectories": ["/home/user/reference"],
  "fileReadLineLimit": 1000,
  "fileWriteLineLimit": 50,
  "telemetryEnabled": true
}

Configuration Options

• blockedCommands: Array of prohibited shell commands

• defaultShell: Shell for start_process (bash, zsh, cmd, powershell)

• allowedDirectories: Paths accessible for file operations (empty array = all access)

• readOnlyDirectories: Paths with read-only access

• fileReadLineLimit: Max lines per read_file call

• fileWriteLineLimit: Max lines per write_file call

• telemetryEnabled: Anonymous usage tracking

Editing Config

Use edit_block on the config file:

edit_block(
  "~/.config/commander-keen/config.json",
  '"allowedDirectories": [...]',
  '"allowedDirectories": [..., "/new/path"]'
)

Usage Examples

Running Commands

start_process("npm run build", 30000)
start_process("python3 script.py", 10000, "bash")

Reading Files

// First 50 lines
read_file("/path/file.txt", { offset: 0, length: 50 })

// Last 20 lines (tail)
read_file("/path/file.txt", { offset: -20 })

// Lines 100-200
read_file("/path/file.txt", { offset: 100, length: 101 })

// From URL
read_file("https://example.com/data.json", { isUrl: true })

Writing Files

// Create new file
write_file("/path/file.txt", "content", { mode: "rewrite" })

// Append to file
write_file("/path/file.txt", "more content", { mode: "append" })

Editing Code

edit_block(
  "/path/file.js",
  "const x = 10;",
  "const x = 20;"
)

// Multiple replacements
edit_block(
  "/path/file.js",
  "console.log",
  "logger.info",
  { expected_replacements: 5 }
)

Searching

// Search code content
search_code("/path", "TODO", { 
  filePattern: "*.js",
  contextLines: 2 
})

// Find files by name
search_files("/path", "*.test.js")

Best Practices

File Writing

• Always chunk files >30 lines into multiple write_file calls

• Use rewrite for first chunk, append for rest

• Keeps token usage low and improves reliability

Path Usage

• Use absolute paths (/home/user/file.txt)

• Relative paths depend on current directory (unreliable)

• Tilde paths (~/file.txt) may not work in all contexts

Command Execution

• For one-shot tasks, use start_process directly

• For complex workflows, write temp scripts and execute

• For data analysis, write Python/Node scripts instead of trying to use REPLs

Blocked Commands

• If a command is blocked, read the error message

• It will suggest the correct tool or approach

• Commands like sed, awk, rm are blocked for safety

Architecture

Server Components

• server.ts (332 lines) - MCP protocol handler, 7 tool definitions

• schemas.ts (88 lines) - Zod validation schemas

• handlers/ - Individual tool implementations

• utils/systemInfo.ts - OS detection and info generation

• utils/blockedCommandHelp.ts - Helpful error messages

Design Principles

1. Data-driven: Keep only what's actually used

2. Helpful errors: Teach best practices when blocking

3. System aware: Automatically provide environment context

4. Minimal overhead: 7 tools, 332 lines, fast startup

Development

Build

npm run build

Watch Mode

npm run watch

Testing

npm test

Debugging

npm run start:debug

Then attach debugger on port 9229.

Statistics

Based on 12,302 actual tool calls:

• Top 5 tools: 93% of usage

• Top 7 tools: 97.5% of usage

• Other 18 tools: 2.5% of usage

Decision: Keep the 7, cut the 18.

Contributing

This is a focused, streamlined fork. If you want to add tools:

1. Check if start_process can do it

2. Provide usage data showing demand

3. Follow the "essential tools only" philosophy

License

MIT

Credits

• Original: Desktop Commander MCP by Eduard Ruzga (@wonderwhy-er)

• This Fork: Streamlined to 7 essential tools based on 12,302 actual tool calls

• Data-Driven Philosophy: Less is more (when backed by data)

Support

• Issues: https://github.com/Corlzee/dalicore-mcp-client/issues

• Docs: https://docs.claude.com (general MCP documentation)

Streamlined. Efficient. Data-driven.