🤖 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/
├── src/
│   ├── index.ts                  ← MCP server entry point & tool registry
│   └── tools/
│       ├── repoReader.ts         ← GitHub Repo Reader tool
│       ├── codeExecutor.ts       ← Code Executor tool
│       ├── docSearch.ts          ← Doc Search tool
│       └── terminalCommander.ts  ← Terminal Commander tool
├── dist/                         ← Compiled JavaScript (generated by `npm run build`)
├── claude_desktop_config.json    ← Example Claude Desktop config block
├── package.json
├── tsconfig.json
└── README.md

---

⚙️ Setup (Windows 10)

Prerequisites

• Node.js v18 or higher — verify with node --version
• Python 3 (optional, only needed for the code_executor Python runtime)
• Claude Desktop installed

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 compiled path.

Step 2 — Install Dependencies

Open a terminal in the project root and run:

cd C:\ai-dev-assistant-mcp
npm install

Step 3 — Build the TypeScript

npm run build

This compiles src/ → dist/. You should see dist/index.js appear.

Step 4 — 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": "node",
      "args": [
        "C:\\ai-dev-assistant-mcp\\dist\\index.js"
      ],
      "env": {}
    }
  }
}

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

Step 5 — 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 src/tools/terminalCommander.ts:

const SAFE_COMMANDS_ALLOWLIST: Set<string> = new Set([
  "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 src/tools/terminalCommander.ts, then rebuild:

npm run build

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

Watch Mode (auto-recompile on save)

npm run watch

Run Without Building (ts-node)

npm run dev

Add a New Tool

1. Create src/tools/myTool.ts — export a function returning { name, description, inputSchema, handler }
2. Import it in src/index.ts and add it to the tools array
3. Run npm run build
4. Restart Claude Desktop

---

🪟 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 Node's path.resolve().

---

📦 Tech Stack

Layer	Technology
Language	TypeScript 5.x
Runtime	Node.js 18+
MCP SDK	@modelcontextprotocol/sdk
Process execution	Node.js child_process.spawn
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         │  │
│  │ (fs module)  │  │  (child_process.spawn)    │  │
│  └──────────────┘  └──────────────────────────┘  │
│  ┌──────────────┐  ┌──────────────────────────┐  │
│  │  Doc Search  │  │   Terminal Commander      │  │
│  │ (fs + regex) │  │   (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.