Docs & Usage Guide

Developer MCP Server

A general purpose Model Context Protocol (MCP) server that provides comprehensive developer tools for file editing, shell command execution, and screen capture capabilities. Built using the rmcp crate.

🚀 Features

📝 Text Editor

View files with language detection for markdown formatting
Write/create files with automatic directory creation
String replacement with precise matching
Undo functionality with edit history
File size protection (400KB limit for text files)

🖥️ Shell Integration

Cross-platform command execution (PowerShell on Windows, bash/zsh on Unix)
Combined stdout/stderr output as it appears in terminal
Output size protection (400KB limit)
Platform-specific optimizations

📸 Screen Capture

Full display screenshots with monitor selection
Window-specific capture by title
Automatic image optimization (768px max width)
Base64 encoded PNG output

🖼️ Image Processing

Image file processing from disk
Automatic resizing while maintaining aspect ratio
Format conversion to PNG
macOS screenshot filename handling

🔄 Workflow Management

Multi-step problem solving with sequential progression
Branching workflows for alternative solution paths
Step revision capability to update previous steps
Context preservation across complex reasoning processes

🔒 Security Features

Gitignore integration - respects .gitignore patterns for file access control
Path validation - requires absolute paths to prevent directory traversal
File size limits - prevents memory exhaustion attacks
Access pattern filtering - blocks access to sensitive files

📋 Requirements

Rust 1.70+ (for building from source)
Claude Desktop or compatible MCP client
Operating System: macOS, Linux, or Windows

🛠️ Installation

Option 1: Build from Source (Recommended)

Clone the repository:

git clone [email protected]:VertexStudio/developer.git
cd developer

Build the project:
```
cargo build --release
```
The binary will be available at:
```
target/release/developer
```

Option 2: Development Build

For development/testing purposes:

cargo build
# Binary at: target/debug/developer

⚙️ Configuration

Claude Desktop Setup

Open Claude Desktop configuration file:

macOS/Linux:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

code %APPDATA%\Claude\claude_desktop_config.json

Add the developer server configuration:

{
  "mcpServers": {
    "developer": {
      "command": "/path/to/your/developer/target/release/developer",
      "args": []
    }
  }
}

Example configurations:

Development build:

{
  "mcpServers": {
    "developer": {
      "command": "/Users/rozgo/vertex/developer/target/debug/developer",
      "args": []
    }
  }
}

Production build:

{
  "mcpServers": {
    "developer": {
      "command": "/Users/rozgo/vertex/developer/target/release/developer",
      "args": []
    }
  }
}

Restart Claude Desktop to load the new configuration.

File Access Control (Optional)

Create a .gitignore file in your working directory to control which files the server can access:

# Sensitive files
.env
.env.*
secrets.*
private/
*.key
*.pem

# Build artifacts
target/
node_modules/
dist/

The server will automatically respect these patterns and block access to matching files.

🎯 Usage Examples

Once configured, you can use these tools directly in Claude Desktop:

Text Editing

"Can you view the contents of /path/to/my/file.rs?"

"Please create a new file at /path/to/hello.py with a simple hello world script"

"Replace the line 'old_function()' with 'new_function()' in /path/to/main.rs"

"Undo the last edit to /path/to/main.rs"

Shell Commands

"Run 'ls -la' to show me the current directory contents"

"Execute 'cargo test' to run the test suite"

"Run 'git status' to check the repository status"

Screen Capture

"Take a screenshot of my main display"

"Capture a screenshot of the window titled 'VS Code'"

"Show me what windows are available for capture"

Image Processing

"Process the image at /path/to/screenshot.png and show it to me"

"Load and display the image from /Users/me/Desktop/diagram.jpg"

Workflow Management

"Start a workflow to implement a new feature with 5 steps"

"Create a branch from step 3 to explore an alternative approach"

"Revise step 2 to use a different algorithm"

🏗️ Architecture

Developer MCP Server
├── Text Editor     → File viewing, editing, string replacement, undo
├── Shell           → Cross-platform command execution  
├── Screen Capture  → Display and window screenshots
├── Image Processor → File-based image processing
├── Workflow        → Multi-step problem solving with branching
└── Security Layer  → Gitignore integration, path validation

🔧 Tool Reference

text_editor

Commands: view, write, str_replace, undo_edit
Parameters: path (required), file_text, old_str, new_str
Limits: 400KB file size, absolute paths only

shell

Parameters: command (required)
Features: Platform detection, output redirection, size limits
Limits: 400KB output size

screen_capture

Parameters: display (optional), window_title (optional)
Output: Base64 PNG image, 768px max width

list_windows

Parameters: None
Output: List of capturable window titles

image_processor

Parameters: path (required)
Features: Auto-resize, format conversion, macOS compatibility
Limits: 10MB file size

workflow

Parameters: step_description, step_number, total_steps, next_step_needed (required), is_step_revision, revises_step, branch_from_step, branch_id, needs_more_steps (optional)
Features: Sequential progression, branching, step revision
Output: JSON workflow status

🐛 Troubleshooting

Common Issues

"Tool not found" errors:

Ensure the binary path in your configuration is correct
Verify the binary exists and is executable
Check Claude Desktop logs for detailed error messages

"File access denied" errors:

Check if the file is blocked by .gitignore patterns
Ensure you're using absolute paths (not relative paths)
Verify file permissions

"Command failed" errors:

Ensure the command exists and is in your system PATH
Check if the command requires special permissions
Verify the command syntax for your operating system

Debug Mode

Build with debug info for troubleshooting:

cargo build
# Use target/debug/developer in your configuration

MCP Inspector

Use the official MCP inspector to debug and test tools:

npx @modelcontextprotocol/inspector target/debug/developer

This will open a web interface where you can:

Inspect available tools and their schemas
Test tool calls interactively
Debug server responses
Validate MCP protocol compliance

Tools Schema Export

Export the tools JSON schema for debugging or integration:

# Save tools schema to file
cargo run toolbox > tools.json

# Pretty print tools schema
cargo run toolbox | jq .

🤝 Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass: cargo test
Submit a pull request

📝 License

MIT

🔗 Related Projects

Model Context Protocol - The protocol specification
Claude Desktop - Official Claude desktop application
MCP Servers - Official MCP server implementations

Developer