DevToolkit Server

A production-quality Model Context Protocol (MCP) server that gives AI assistants like Claude 22 powerful developer tools across 5 domains.

Built with TypeScript, strict types, Zod validation, and clean modular architecture.

---

Features

📁 File Tools (6)

Tool	Description
read_file	Read file contents with optional line range
write_file	Write/append to files, auto-creates directories
list_directory	List files with metadata (size, modified date)
search_in_files	Regex search across files with glob patterns
get_file_info	File metadata: size, timestamps, permissions
delete_file	Delete files or directories (recursive optional)

🔧 Git Tools (6)

Tool	Description
git_status	Working tree status, branch info, ahead/behind
git_log	Commit history with author, date, message
git_diff	Diff between commits, branches, or working tree
git_blame	Line-by-line authorship for any file
git_branches	List all local and remote branches
git_show_commit	Full diff and metadata for a specific commit

🔍 Code Analysis Tools (6)

Tool	Description
analyze_complexity	Cyclomatic complexity, nesting depth, function count
find_todos	Find TODO/FIXME/HACK comments across a codebase
count_lines	Code vs comment vs blank line breakdown
detect_language	Identify programming language from file extension/shebang
find_duplicates	Detect duplicate code blocks across files
get_imports	Extract and categorize all import statements

🌐 HTTP Tools (4)

Tool	Description
http_request	Full HTTP client: GET/POST/PUT/PATCH/DELETE with headers/body
fetch_json	Fetch and parse JSON with optional dot-path extraction
check_url_status	Batch URL health check with response times
download_file	Download files from URLs to local paths

💻 System Tools (6)

Tool	Description
get_system_info	OS, CPU, memory, Node version, uptime
get_env	Read environment variables (sensitive values auto-masked)
run_command	Execute shell commands (allowlisted for safety)
list_processes	Running processes with CPU/memory usage
get_disk_usage	Disk usage for directories
get_network_info	Network interfaces and IP addresses

---

Installation

git clone https://github.com/your-username/devtoolkit-mcp
cd devtoolkit-mcp
npm install
npm run build

Usage with Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

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

Usage with Cursor / VS Code

Same pattern — point the MCP server config to dist/index.js.

Development

npm run dev    # Run with tsx (no build step)
npm run build  # Compile TypeScript
npm run lint   # ESLint

---

Advanced MCP Protocol Features

Beyond tools, this server implements the full 2025-06-18 MCP specification:

📂 Resources

Files are exposed as browsable MCP resources — clients (e.g. Claude Desktop) can list, read, and subscribe to changes.

• Paginated listing with cursor-based pagination (50 files/page)
• Resource templates: file:///{path} for dynamic file access
• Subscriptions: clients receive notifications/resources/updated when a file changes after a write/delete
• List-changed notifications: resource list updates after any file mutation
• Annotations: every resource includes audience, priority, and lastModified

📝 Logging

Structured log notifications sent to the client for every tool call:

• 8 RFC 5424 severity levels: debug → emergency
• Client can set minimum log level via logging/setLevel
• Logs include tool name, args preview, status, and errors
• Sensitive values never logged

🔍 Completion

Autocomplete for file paths in resource URI templates:

• Triggered when client requests completion/complete on a ref/resource
• Returns matching file paths up to 20 suggestions with hasMore flag

🗣️ Elicitation

Servers request structured user input before destructive operations:

• write_file: if the target file exists, asks user to confirm overwrite (with checkbox UI)
• delete_file: always asks user to confirm + optionally provide a reason
• Falls back gracefully if client doesn't support elicitation (proceeds without prompt)

🤖 Sampling

The server can ask the client's LLM to generate completions:

• sampleFromClient() helper exported for use in tools
• Specifies model preferences (prefers Claude Sonnet, falls back to any Claude)
• Gracefully no-ops if client doesn't support sampling

---

Architecture

src/
├── index.ts              # MCP server, capabilities, tool routing, elicitation, sampling
├── resources.ts          # Resources: list, read, subscribe, completion, pagination
├── tools/
│   ├── files.ts          # File system tools
│   ├── git.ts            # Git integration (simple-git)
│   ├── code-analysis.ts  # Static analysis tools
│   ├── http.ts           # HTTP client tools (axios)
│   └── system.ts         # OS/system tools
└── utils/
    ├── errors.ts         # Typed error classes, helpers
    └── logger.ts         # Structured log notifications (RFC 5424)

Key design decisions:

• Zod validation on every tool input — no silent failures
• Typed error classes with error codes for structured debugging
• Security: run_command has an explicit allowlist; env vars auto-mask secrets
• Cross-platform: works on Windows, macOS, and Linux

---

Tech Stack

• @modelcontextprotocol/sdk — MCP protocol
• simple-git — Git operations
• axios — HTTP client
• fast-glob — File pattern matching
• zod — Runtime schema validation
• TypeScript (strict mode)

---

License

MIT