mcp-dev-toolbox

Ask your AI agent about your codebase in plain English — and get answers grounded in your actual code and git history.

An MCP server for Claude Desktop, Claude Code, Cursor and any other MCP client. Its headline feature is local semantic code search: find code by meaning ("where do we validate auth tokens?") using on-device embeddings — no API key, no code leaving your machine. Alongside it you get git history, diffs, blame, file inspection, and ready-made prompts for code review and commit messages.

Why use it

• 🔍 Semantic search, fully local — all-MiniLM-L6-v2 embeddings indexed per function/class, stored on disk, no external API calls.
• 🕰️ Git-aware — the agent can read log, diff, status and blame instead of guessing what changed.
• 🔒 Sandboxed by design — every path is confined to WORKSPACE_ROOT; git runs without a shell.
• 🧩 Uses the whole MCP spec — 12 tools, 3 resources and 4 prompts, not just tools.
• ☁️ Local or cloud — stdio for desktop clients, SSE + Dockerfile for one-click Railway deploys.

Quick start

git clone https://github.com/walter789/MCP-dev-toolbox.git
cd MCP-dev-toolbox
pip install -r requirements.txt

Then point your MCP client at server.py with WORKSPACE_ROOT set to the project you want to explore (full config below), and ask:

"Build the index, then find where we handle database connection errors."

Features

Setup

1. Clone and install

git clone https://github.com/walter789/MCP-dev-toolbox.git
cd MCP-dev-toolbox
pip install -r requirements.txt

2. Configure environment

cp .env.example .env

Edit .env:

WORKSPACE_ROOT=/absolute/path/to/your/project
EXCLUDED_DIRS=.git,__pycache__,.venv,node_modules

WORKSPACE_ROOT is the codebase you want to analyze. All tools operate within this boundary — paths outside it are rejected.

3. Add to Claude Desktop

Open your Claude Desktop config (claude_desktop_config.json) and add:

{
  "mcpServers": {
    "dev-toolbox": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-dev-toolbox/server.py"],
      "env": {
        "WORKSPACE_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

Restart Claude Desktop. You'll see the toolbox icon appear in the toolbar.

Claude Code:

claude mcp add dev-toolbox -e WORKSPACE_ROOT=/absolute/path/to/your/project -- python /absolute/path/to/MCP-dev-toolbox/server.py

Cursor: add the same mcpServers block to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

Tools Reference

Git Tools

File Tools

Code Tools

Semantic Search Tools

Resources Reference

Prompts Reference

Semantic Search

Unlike search_in_files (regex), semantic search finds code by meaning.

# First, build the index (once per project)
→ build_index

# Then search naturally
→ semantic_search("user authentication logic")
→ semantic_search("database connection setup")
→ semantic_search("error handling in API calls")

The index is stored under .mcp_index/ (gitignored) and persists across sessions. Re-run build_index after major code changes.

Model used: all-MiniLM-L6-v2 (~80 MB, runs fully locally — no API key needed).

Cloud Deploy (Railway)

The server supports two transports controlled by the TRANSPORT env var:

Deploy to Railway (free tier)

1. Push this repo to GitHub
2. Go to railway.app → New Project → Deploy from GitHub repo
3. Railway auto-detects the Dockerfile and builds it
4. Set these environment variables in Railway dashboard:

   TRANSPORT=sse
   WORKSPACE_ROOT=/app
   

5. Railway gives you a public URL — copy it from Settings → Domains. It includes a generated hash suffix: https://mcp-dev-toolbox-production-<hash>.up.railway.app

Note: Railway ships your source as a zip archive (not git clone), so .git is never in the build context. The Dockerfile handles this by running git fetch at build time, giving the container the last 50 commits of history for git tools to work.

Connect Claude Desktop to the cloud server

Claude Desktop requires mcp-remote as a bridge for SSE servers:

{
  "mcpServers": {
    "dev-toolbox-cloud": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-app-production-<hash>.up.railway.app/sse"
      ]
    }
  }
}

Replace the URL with your exact Railway domain. Do not add --transport sse — it is not a valid mcp-remote flag.

Verify the server is reachable before configuring Claude Desktop by opening https://your-url/sse in a browser. A healthy server responds with:

event: endpoint
data: /messages/?session_id=...

Example Conversations

"Show me what changed this week"

Claude calls git_log(since_days=7) and summarizes the commits.

"Find all TODO comments in the src/ folder"

Claude calls find_todos(path="src", extensions=["py"]).

"What's the largest file by line count?"

Claude calls count_lines_by_language() then get_file_stats() on the top result.

"Review my authentication module"

Claude uses the code_review prompt → reads file://src/auth.py → returns structured review.

"Write a commit message for my staged changes"

Claude calls git_diff(staged=True) then uses the commit_message prompt.

Security

• All file operations validate that the resolved path is within WORKSPACE_ROOT before reading.
• Git subprocess calls run in WORKSPACE_ROOT with no shell interpolation (create_subprocess_exec, not shell=True).
• Binary files are detected and skipped rather than returned as garbled text.

Project Structure

mcp-dev-toolbox/
├── server.py                  # Thin launcher: `python server.py` from a source checkout
├── mcp_dev_toolbox/
│   ├── server.py              # FastMCP app + main() — wires all modules
│   ├── config.py              # Loads .env, exposes WORKSPACE_ROOT + EXCLUDED_DIRS
│   ├── tools/
│   │   ├── git_tools.py       # 4 git tools (async subprocess)
│   │   ├── file_tools.py      # 4 file analysis tools
│   │   ├── code_tools.py      # 2 code analysis tools
│   │   └── semantic_search.py # 2 semantic search tools (build_index, semantic_search)
│   ├── indexer/
│   │   ├── chunker.py         # Code by function/class, Markdown by heading, capped chunk size
│   │   └── embedder.py        # Embeds chunks with all-MiniLM-L6-v2, cosine similarity search
│   ├── resources/
│   │   └── handlers.py        # 3 resource handlers
│   └── prompts/
│       └── templates.py       # 4 prompt templates
├── tests/                     # pytest suite (`python -m pytest`)
├── scripts/make_demo_gif.py   # Regenerates docs/demo.gif from real tool output
├── pyproject.toml             # Package metadata + `mcp-dev-toolbox` command
├── Dockerfile                 # CPU-only torch; fetches git history at build time
├── requirements.txt
├── .env.example
└── LICENSE

Development

pip install -e ".[dev]"
python -m pytest

License

MIT © 2026 Prateek Pal