safe-dev-mcp

A minimal MCP server that gives an editor LLM a fixed set of abilities: lint, test, git status, git diff, git log, git show.

Requirements

Python 3.11 or newer (the config parser is the standard library tomllib).

On macOS the built-in python3 is 3.9, which is too old for both this server and the mcp package. If pip install mcp reports "No matching distribution found", that is the cause. Install a current Python with Homebrew:

brew install python@3.12

Related MCP server: MCP ToolHub

One-time setup

Create a virtualenv inside this clone from the newer interpreter and install the MCP SDK:

cd /path/to/safe-dev-mcp
/opt/homebrew/bin/python3.12 -m venv .venv
.venv/bin/pip install mcp

Register the server once at Claude Code user scope. The Claude agent in Zed is Claude Code running over the Agent Client Protocol, so it reads this config:

claude mcp add --scope user safe-dev-tools -- \
  /path/to/safe-dev-mcp/.venv/bin/python \
  /path/to/safe-dev-mcp/server.py

If you prefer to configure it in Zed itself, add the same command to ~/.config/zed/settings.json. Zed forwards these to external agents:

{
  "context_servers": {
    "safe-dev-tools": {
      "command": "/path/to/safe-dev-mcp/.venv/bin/python",
      "args": ["/path/to/safe-dev-mcp/server.py"]
    }
  }
}

Then, in the agent's permissions, allow this server's tools and leave general terminal access denied.

Per-repo configuration

In each repo where you want lint or test tools:

cp /path/to/safe-dev-mcp/safe-dev.example.toml .safe-dev.toml
echo .safe-dev.toml >> .git/info/exclude

Edit .safe-dev.toml for that repo. Commands are grouped into targets. A target is a part of the repo with its own lint and test commands. Every key is optional, and a tool is only offered when at least one target defines it.

Single-surface repos

Top-level lint and test define one target that owns every path:

lint = ["ruff", "check", "."]
test = ["pytest", "-q"]

Monorepos

Use one [[targets]] table per surface instead:

[[targets]]
name = "frontend"
path_prefix = "apps/frontend"
cwd = "apps/frontend"
lint = ["yarn", "lint"]
test = ["yarn", "test"]

[[targets]]
name = "backend"
path_prefix = "apps/backend"
cwd = "apps/backend"
test = ["yarn", "test"]

[[targets]]
name = "e2e"
path_prefix = "e2e"
test = ["yarn", "test:e2e"]
timeout_seconds = 600

Top-level keys must appear before the first [[targets]] table, which is a TOML rule.

How the tools behave with targets:

• run_tests(path) runs only the target whose path_prefix owns that path. When several match, the longest prefix wins. If none match, the tool returns an error naming the configured targets rather than guessing.

• The scoped path is rewritten relative to the target's cwd before it is appended, and dropped entirely when it is the cwd itself. This matters for workspace scripts: yarn workspace backend test runs Vitest inside apps/backend, so a repo-relative path would be doubled. Set cwd to the workspace and call the script directly, as in the example above.

• run_tests() with no path runs every target that has a test command and returns a summary line followed by a section per target.

• run_lint() runs every target that has a lint command, skips the rest, and reports per target the same way.

• The tool descriptions shown to the model list the target names and prefixes, so it knows which paths route where.

Repos that only need the read-only git tools need no config file at all.

Git worktrees

Because .safe-dev.toml is excluded from git, a linked worktree created with git worktree add does not get a copy. When the server starts in a worktree that has no config of its own, it follows the worktree's .git pointer back to the main worktree and reads the config there. path_prefix and cwd still resolve against the worktree you are in, so commands run on that worktree's files. Put a .safe-dev.toml inside a worktree to override the shared one for that worktree only.

The tool list is fixed when the server starts, so restart the agent thread after editing the config.

How the server finds the repo

First match wins:

1. SAFE_DEV_REPO_ROOT environment variable, for manual testing.

2. CLAUDE_PROJECT_DIR, which Claude Code sets for every MCP server it launches. User-scope servers run with ~/.claude as their working directory, so this is what makes a global registration work per repo.

3. Walk up from the current working directory until a directory containing .git or .safe-dev.toml is found.

4. The current working directory.

Testing it standalone

The MCP Inspector lets you see the tool list and call tools by hand. Launch it from inside the repo you want to test so the server resolves that repo as its root:

cd /path/to/some/repo
npx @modelcontextprotocol/inspector \
  /path/to/safe-dev-mcp/.venv/bin/python \
  /path/to/safe-dev-mcp/server.py

The SDK's mcp dev shortcut is not used here because it always launches the server through uv, which fails if uv is not installed.

Troubleshooting

On startup the server writes two lines to stderr: the repo root it resolved and the tools it registered. Run it directly from inside a repo to see them, then press Ctrl-C:

cd /path/to/some/repo
/path/to/safe-dev-mcp/.venv/bin/python /path/to/safe-dev-mcp/server.py

A malformed lint or test value (for example a plain string instead of a list) is reported on stderr and that tool is left out. The server still starts.

Extending it

To add another safe capability (git blame, a formatter check, a type checker), add a plain function following the same pattern and register it in _register_tools, conditionally if it depends on config. Fixed command list, validated and bounded parameters, no shell string concatenation. Resist the temptation to add a generic "run this git subcommand" tool. Enumerate the ones you actually want.