🤖 Dev Assistant MCP

A Model Context Protocol (MCP) server that gives AI assistants like Claude full developer superpowers — read/write files, search codebases, analyze architecture, scan for secrets, get AI-powered refactoring suggestions, run sandboxed commands, and manage multi-step workflows, all through natural conversation.

Built with TypeScript + the official Anthropic MCP SDK. AI features powered by Google Gemini 2.0 Flash Lite (free-tier friendly).

---

✨ Tools — 27 total

Core (no API key required)

system_info · read_file · write_file · list_directory · summarize_repo · search_code · git_status · git_diff · git_log

AI-Powered (requires Gemini API key)

analyze_code · analyze_architecture · refactor_code · security_scan (local, no API call) · semantic_search · explain_error

Platform & Orchestration

Tool	What it does
run_command	Risk-assessed, Docker-sandboxed shell execution
sandbox_status	Check if Docker sandboxing is active
validate_repo	Run build/test/lint/runtime checks on demand
workflow_run / workflow_status / workflow_abort / workflow_history	Plan and execute multi-step goals, with SQLite-backed persistence across restarts
impact_analysis	"If I change this file, what's affected?" — real parsed dependency graph
dependency_graph / architecture_map	Import graph exploration, fan-in/fan-out, circular dependency detection
repo_context	Detected language, frameworks, build/test/lint commands
metrics_snapshot	Live tool-call metrics for the session

Highlights: workflows survive server crashes/restarts (SQLite), commands run in disposable Docker containers with resource limits, dependency graph is built with the real TypeScript compiler API (not regex), and a live dashboard runs at localhost:4477 by default.

---

🚀 Getting Started

git clone https://github.com/KeyboardNoMouse/dev-assistant-mcp.git
cd dev-assistant-mcp
npm install
cp env.example .env   # add your GEMINI_API_KEY
npm run build
npm start

The 9 core tools work with no API key. Only the 6 AI-powered tools need GEMINI_API_KEY (free at aistudio.google.com).

---

🔌 Connecting to Claude

Claude Desktop — add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop after saving.

Claude.ai (Web) — Settings → Integrations → Add MCP server → point to your running server.

---

💬 Example Usage

"Read lines 40–80 of src/auth/middleware.ts"
"Scan my whole project for hardcoded secrets"
"Analyze src/db/queries.ts focusing on security"
"If I change auth.ts, what's affected?"
"Explain this error: TypeError: Cannot read properties of undefined (reading 'map')"

---

⚙️ Environment Variables

Variable	Required	Description
GEMINI_API_KEY	For AI tools only	Free key from aistudio.google.com
DEV_ASSISTANT_DB_PATH	No	SQLite location (default ./data/dev-assistant.db)
DEV_ASSISTANT_SANDBOX_IMAGE	No	Docker image for sandboxed execution (default node:20-bookworm-slim)
DEV_ASSISTANT_DASHBOARD	No	Set off to disable the observability dashboard
DEV_ASSISTANT_DASHBOARD_PORT	No	Dashboard port (default 4477)

---

🛠️ Tech Stack

TypeScript · @modelcontextprotocol/sdk · Google Gemini API · better-sqlite3 · Docker (optional, auto-detected) · simple-git · zod · fs-extra · glob

---

📜 Scripts

npm run dev — dev mode (ts-node) · npm run build — compile · npm start — run compiled server

---

📄 License

MIT

👨‍💻 Author

Built by @KeyboardNoMouse