AI Dev Assistant

A production-ready Model Context Protocol (MCP) Server that bridges Claude Desktop directly to your local Windows 10 development environment. Give Claude the ability to read your code, run scripts, search docs, and execute safe terminal commands — all without leaving the chat.

---

✨ What It Does

This server extends Claude Desktop with four powerful developer tools:

Tool	What It Does
github_repo_reader	Recursively reads any local repo (ignores .git, node_modules, binaries)
code_executor	Runs Python or Node.js snippets in isolated child processes
doc_search	Full-text keyword search across your local docs/ folder
terminal_commander	Executes safe CMD/PowerShell commands via a strict allowlist

---

🏗️ Project Structure

ai-dev-assistant-mcp/
├── main.py                      ← MCP server entry point & tool implementations
├── pyproject.toml               ← Python project configuration
├── claude_desktop_config.json   ← Example Claude Desktop config block
└── README.md

---

⚙️ Setup (Windows 10)

Prerequisites

• Python 3.8+ — verify with python --version
• Node.js (optional, only needed for the code_executor Node.js runtime)
• Claude Desktop installed
• uv (optional, for faster installs) or pip

Step 1 — Clone / Place the Project

Place this project folder somewhere permanent, for example:

C:\ai-dev-assistant-mcp\

⚠️ Do not move the folder later — Claude Desktop will reference the script path.

Step 2 — Install Dependencies

Open a terminal in the project root and run:

cd C:\ai-dev-assistant-mcp
pip install -e .

Or with uv:

uv pip install -e .

Step 3 — Configure Claude Desktop

Open (or create) the Claude Desktop config file at:

%APPDATA%\Claude\claude_desktop_config.json

Paste in the following block (adjust the path if you placed the project elsewhere):

{
  "mcpServers": {
    "ai-dev-assistant": {
      "command": "python",
      "args": [
        "C:\\ai-dev-assistant-mcp\\main.py"
      ],
      "env": {}
    }
  }
}

💡 Already have other MCP servers? Just add the "ai-dev-assistant" key inside your existing "mcpServers" object.

Step 4 — Restart Claude Desktop

Fully quit and relaunch Claude Desktop. You should see the 🔧 tools icon in the chat input bar — click it to confirm all four tools appear.

---

🔒 Security Architecture

Terminal Commander Safe List

The terminal_commander tool will refuse to run any command whose base name is not on the explicit allowlist in main.py:

SAFE_COMMANDS_ALLOWLIST = {
    "dir", "ls", "git", "node", "npm", "npx", "python",
    "tsc", "docker", "ipconfig", "ping", "whoami", ...
}

Additionally, even allowlisted commands are blocked if they match any dangerous pattern:

rm -rf     del /s     format C:     shutdown
taskkill   net user   netsh         Invoke-Expression
curl | bash           registry edits   UAC elevation ...

To add a new command, edit SAFE_COMMANDS_ALLOWLIST in main.py.

Code Executor Sandbox

• Scripts run in isolated temp files — no persistent state between calls
• 15-second hard timeout — runaway processes are killed automatically
• 64 KB output cap — prevents memory exhaustion from verbose output
• Temp files are deleted immediately after execution

Repo Reader Limits

• Ignores: .git, node_modules, .next, dist, __pycache__, .venv, etc.
• Skips: binary files, images, archives, .lock files
• 500 KB per-file cap — large generated files are skipped automatically
• 500 file maximum per call

---

🛠️ Usage Examples

Once connected to Claude Desktop, you can ask Claude:

"Read my repo at C:\Projects\my-api and explain the architecture."

"Run this Python script and tell me the output:
  import json; print(json.dumps({'status': 'ok', 'count': 42}))"

"Search my docs folder at C:\Projects\my-api\docs for 'authentication'"

"Run git status in C:\Projects\my-api"

"What files are in C:\Projects? Run dir."

---

🔧 Development

Run Directly

python main.py

Add a New Tool

1. Add a new @Tool() decorated function in main.py
2. The server will automatically register it

---

🪟 Windows Path Notes

Windows paths use backslashes. In JSON config files, always double-escape them:

"C:\\Users\\YourName\\Projects\\my-repo"

In Claude prompts, you can use either style — the tools normalize paths internally using pathlib.Path.resolve().

---

📦 Tech Stack

Layer	Technology
Language	Python 3.8+
MCP SDK	mcp
Process execution	asyncio.subprocess
Transport	stdio (standard MCP transport)

---

🤝 How It Bridges Claude and Windows

┌─────────────────────────────────────────────────┐
│                  Claude Desktop                  │
│  ┌─────────────────────────────────────────────┐ │
│  │   Claude AI (Claude Sonnet / Opus)          │ │
│  │   → Decides which tool to call              │ │
│  └─────────────┬───────────────────────────────┘ │
└────────────────┼────────────────────────────────┘
                 │ MCP Protocol (stdio JSON-RPC)
┌────────────────▼────────────────────────────────┐
│           AI Dev Assistant MCP Server            │
│  ┌──────────────┐  ┌──────────────────────────┐  │
│  │ Repo Reader  │  │     Code Executor         │  │
│  │ (pathlib)    │  │  (asyncio.subprocess)     │  │
│  └──────────────┘  └──────────────────────────┘  │
│  ┌──────────────┐  ┌──────────────────────────┐  │
│  │  Doc Search  │  │   Terminal Commander      │  │
│  │ (os.walk)    │  │   (cmd.exe / pwsh.exe)   │  │
│  └──────────────┘  └──────────────────────────┘  │
└─────────────────────────────┬───────────────────┘
                              │
              ┌───────────────▼───────────────┐
              │     Windows 10 File System    │
              │     Python / Node Runtimes    │
              │     Git / npm / Docker        │
              └───────────────────────────────┘

Claude sends a tool-call request over stdio. The MCP server validates it, executes the appropriate handler, and returns formatted Markdown back to Claude — which presents it naturally in the conversation.

---

📄 License

MIT — free to use, modify, and build upon.