# 🤖 AI Dev Assistant — MCP Server

> 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+](https://python.org/) — verify with `python --version`
- [Node.js](https://nodejs.org/) (optional, only needed for the `code_executor` Node.js runtime)
- [Claude Desktop](https://claude.ai/download) installed
- [uv](https://github.com/astral-sh/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:

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

Or with uv:

```cmd
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):

```json
{
  "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`:

```python
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

```cmd
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:

```json
"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.