Droid MCP Rs

🚀 droid-mcp-rs

A high-performance Rust MCP server that encapsulates Factory.ai Droid CLI to provide AI-assisted programming capabilities.

🚀 Quick Start

# 1. Clone the repository
git clone https://github.com/zcg/droid-mcp-rs.git
cd droid-mcp-rs

# 2. Build the release version
cargo build --release

# 3. Configure Claude Code
claude mcp add droid-rs -s user --transport stdio -- ./target/release/droid-mcp-rs

# 4. Restart the Claude Code MCP service
claude mcp restart

# 5. Start using!

Now you can directly use the droid tool in Claude Code! 🎉

✨ Features

✅ Core Capabilities

1. MCP Protocol Support - Seamlessly integrate with Claude Code and other MCP clients.
2. Full Droid Integration - Support all droid exec command-line parameters.
3. Autonomy Level Control - Fine-grained permission management (DEFAULT/low/medium/high).
4. Session Management - Multi-turn conversations and session recovery (SESSION_ID).
5. DROID.md Support - Automatically inject project-specific context.
6. Custom Model System - Automatically read the configuration from ~/.factory/config.json.
7. Security First - Read-only by default, permissions need to be explicitly specified.
8. Resource Limitation - Automatic timeout and size limitations.
9. Cross-platform - Support Windows, Linux, and macOS.

✅ Advanced Features

1. Reasoning Mode (reasoning_effort) - Three levels of reasoning depth: low/medium/high.
2. Specification Mode (use_spec + spec_model) - Plan before execution.
3. Permission Bypass (skip_permissions_unsafe) - Execute without restrictions in an isolated environment (Dangerous!).
4. Output Format (output_format) - stream-json (default) or stream-jsonrpc.
5. File Input (file) - Read task prompts from a file.
6. Tool Control (enabled_tools / disabled_tools) - Fine-grained control over available tools.

📦 Installation

Build from Source

git clone https://github.com/zcg/droid-mcp-rs.git
cd droid-mcp-rs
cargo build --release

Binary file locations:

• Linux/macOS: target/release/droid-mcp-rs
• Windows: target/release/droid-mcp-rs.exe

Configure Claude Code

claude mcp add droid-rs -s user --transport stdio -- /path/to/droid-mcp-rs

Configure Claude Desktop

Edit settings.json:

{
  "mcpServers": {
    "droid": {
      "command": "/path/to/droid-mcp-rs"
    }
  }
}

🎨 Complete Parameter List

Mutually exclusive parameters:

• PROMPT and file cannot be specified simultaneously.
• skip_permissions_unsafe and auto cannot be specified simultaneously.

🔐 Autonomy Levels

⚠️ Important Note

By default, auto=high. You can disable it by setting allow_high_autonomy=false in the configuration file.

💻 Usage Examples

Scenario 1️⃣: Basic Query (Using All Default Values)

await use_mcp_tool("droid", {
  PROMPT: "Analyze the code quality of this project"
});
// Automatically use: auto=high, the first GPT model, stream-json

Scenario 2️⃣: Deep Reasoning + Specification Mode

await use_mcp_tool("droid", {
  PROMPT: "Refactor the authentication module to improve security",
  reasoning_effort: "high",  // Deep reasoning
  use_spec: true,            // Plan before execution
  spec_model: "gpt-5.1"      // Use GPT-5.1 for planning
});

Scenario 3️⃣: Multi-turn Conversation

// First turn: Start the task
const result1 = await use_mcp_tool("droid", {
  PROMPT: "Create user authentication functionality"
});

// Second turn: Continue the conversation
const result2 = await use_mcp_tool("droid", {
  PROMPT: "Add unit tests",
  SESSION_ID: result1.SESSION_ID  // Restore the context
});

// Third turn: Continue to improve
const result3 = await use_mcp_tool("droid", {
  PROMPT: "Optimize performance",
  SESSION_ID: result2.SESSION_ID
});

Scenario 4️⃣: Read Task from a File

// Content of prompt.md:
// # Task
// Refactor the entire project architecture...

await use_mcp_tool("droid", {
  file: "./prompt.md",      // Read from a file
  reasoning_effort: "high"
});

Scenario 5️⃣: Custom Model

await use_mcp_tool("droid", {
  PROMPT: "Generate API documentation",
  model: "custom:Sonnet-4.5-[88code]-0"  // Use a custom model
});

Scenario 6️⃣: Unrestricted Execution in an Isolated Environment

// ⚠️ Only use in an isolated environment such as a Docker container!
await use_mcp_tool("droid", {
  PROMPT: "System-level configuration modification",
  skip_permissions_unsafe: true  // Skip all permission checks
});

Scenario 7️⃣: Fine-grained Tool Control

await use_mcp_tool("droid", {
  PROMPT: "Analyze the code but do not modify it",
  enabled_tools: "read,grep,find",   // Only allow read-only tools
  disabled_tools: "write,edit,bash"  // Disable write-related tools
});

⚙️ Configuration System

Configuration File: droid-mcp.config.json

Create it in the working directory (or specify it through the DROID_MCP_CONFIG_PATH environment variable):

{
  "additional_args": [],
  "timeout_secs": 600,
  "max_timeout_secs": 3600,
  "default_auto": "high",
  "default_model": "claude-opus-4-5-20251101",
  "allow_high_autonomy": true
}

Field Description:

Environment Variables

🎭 Custom Model System

Configuration File Location

• Linux/macOS: ~/.factory/config.json
• Windows: C:\Users\<user>\.factory\config.json

Configuration Format

{
  "custom_models": [
    {
      "model_display_name": "Sonnet 4.5 1M [88code]",
      "model": "claude-sonnet-4-5-20250929-thinking[1m]",
      "base_url": "https://www.88code.org/droid",
      "api_key": "your-api-key",
      "provider": "anthropic"
    },
    {
      "model_display_name": "GPT-5.1-Codex [88code]",
      "model": "gpt-5.1-codex",
      "base_url": "https://www.88code.org/droid/v1",
      "api_key": "your-api-key",
      "provider": "openai"
    }
  ]
}

Use a Custom Model

The model reference format is: custom:Display-Name-Index

// The first model (index 0)
await use_mcp_tool("droid", {
  PROMPT: "Code analysis",
  model: "custom:Sonnet-4.5-1M-[88code]-0"
});

// The second model (index 1)
await use_mcp_tool("droid", {
  PROMPT: "Generate documentation",
  model: "custom:GPT-5.1-Codex-[88code]-1"
});

Features:

• ✅ Automatically list all available models in the MCP tool description.
• ✅ Display the used model in the log before execution.
• ✅ Return model information (model_info field) in the result.
• ✅ Support switching between different models for each task to achieve the best results.
• ✅ Prioritize GPT models by default (intelligent model selection).

Log Example:

droid-mcp-rs: Sonnet 4.5 1M [88code] [anthropic] (claude-sonnet-4-5-20250929-thinking[1m])

📝 DROID.md System Prompt

Place a DROID.md file in the working directory to define project-specific context:

# Project Context

This is a TypeScript project using React and Next.js.

## Development Guidelines
- Use functional components and Hooks.
- Follow the existing file structure.
- Write tests for new features.
- Use TypeScript strict mode.

Features:

• The content is automatically injected as <system_prompt>...</system_prompt> before each prompt.
• Maximum size: 1 MB.
• Automatically truncate if the limit is exceeded (safe at UTF-8 character boundaries).

🔒 Security Features

• ✅ Read-only by Default - Only allow read operations without the auto parameter.
• ✅ Explicit Permissions - Need to explicitly specify the auto level to make modifications.
• ✅ Forced Timeout - Prevent infinite execution (default: 10 minutes).
• ✅ High Permission Protection - The high level needs to be allowed in the configuration file.
• ✅ Resource Limitation - Automatic size and memory limitations.
  • Agent messages: 10 MB
  • All messages: 50 MB
  • DROID.md: 1 MB
  • stderr: 100 KB

🛠️ Development Guide

Build Commands

cargo build              # Debug build
cargo build --release    # Optimized build (enable LTO)
cargo clean              # Clean build artifacts

Testing and Code Quality

cargo test               # Run tests
cargo clippy             # Code inspection
cargo fmt                # Code formatting
cargo check              # Quick type checking

Development Requirements

• Rust 1.70+
• Droid CLI installed and in the PATH.

🏗️ Architecture Overview

Data Flow

Claude Code (MCP Client)
    ↓ stdio transport
MCP Server (main.rs)
    ↓ clap CLI parsing
Tool Handler (server.rs::droid)
    ↓ parameter validation + MCP protocol
CLI Wrapper (droid.rs::run)
    ↓ async process spawn + JSON stream parsing
droid exec CLI (subprocess)

Core Files

Key Design Patterns

1. Lazy Configuration Loading - Use OnceLock to cache static configurations.
2. Stream Processing - Asynchronously parse JSON streams line by line.
3. Size Limitation - Multi-layer truncation boundaries (10MB/50MB/1MB).
4. Timeout Wrapper - Use tokio::time::timeout to enforce timeouts.
5. Custom Model System - Intelligent GPT prioritization + index referencing.

📁 Summary of Configuration File Locations

🎉 Functionality Completeness Check

✓ Core Features

• [x] Full support for the MCP protocol
• [x] Mapping of all droid exec parameters
• [x] Session management (SESSION_ID)
• [x] Custom model system
• [x] DROID.md injection
• [x] Intelligent model selection (GPT prioritization)

✓ Advanced Features

• [x] Reasoning mode (reasoning_effort)
• [x] Specification mode (use_spec)
• [x] Permission bypass (skip_permissions_unsafe)
• [x] Output format control (output_format)
• [x] File input (file)
• [x] Tool control (enabled_tools/disabled_tools)

✓ Quality Assurance

• [x] Compile with zero warnings
• [x] Pass all Clippy checks
• [x] Cross-platform support (Windows/Linux/macOS)
• [x] Complete error handling
• [x] Resource limitation and security control

📄 License

MIT License - See LICENSE for details.

🔗 Related Projects

• codex-mcp-rs - Codex CLI MCP wrapper
• gemini-mcp-rs - Gemini CLI MCP wrapper
• Factory.ai Droid - Official Droid CLI tool

💬 Support and Feedback

• Report issues: GitHub Issues
• MCP documentation: modelcontextprotocol.io
• Droid documentation: docs.factory.ai