local-dev-tools

tests python license

A small, production-quality MCP (Model Context Protocol) server built on FastMCP. It gives any MCP client — Claude Code, Claude Desktop, or your own — three read-only introspection tools for everyday local development.

sqlite_query(db_path="./app.db", query="SELECT id, email FROM users LIMIT 10")
check_port(port=5432)                       # is local Postgres up?
git_diff_summary(repo_path=".")             # what have I touched?

Tools

Tool	Signature	Returns
`sqlite_query`	`(db_path: str, query: str) -> str`	Aligned text table, capped at 50 rows with a truncation note
`check_port`	`(port: int, host: str = "127.0.0.1") -> dict`	`{host, port, open, message}`
`git_diff_summary`	`(repo_path: str = ".") -> dict`	`{repo_path, modified, added, deleted, renamed, untracked, total_changes}` or `{error}`

Design

Every tool is total. Tools validate inputs and catch all internal exceptions, returning a structured error value ("Error: ..." or {"error": ...}) instead of raising. A bad argument produces a readable message rather than killing the server process the client depends on.
Read-only by construction. sqlite_query uses three independent layers: path and file-header validation (the file must begin with the SQLite magic bytes), query screening (statement allowlist + keyword blocklist applied after comments and quoted literals are blanked out), and a file:...?mode=ro connection — so SQLite itself refuses writes even if the screening were bypassed.
Bounded output and time. Results cap at 50 rows and 200-character cells; port probes time out after 1s, git subprocesses after 15s. No tool can flood the context or hang the server.
Discoverable. Numpydoc docstrings put purpose, return shape, and failure conditions into the tool description and per-parameter JSON Schema that the model sees at discovery time.

Quick Start

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate.bat
pip install -r requirements.txt    # or requirements-dev.txt to include pycodestyle

python server.py                   # start the server (stdio transport)
python test_server.py              # run the test suite

Dependencies are pinned in requirements.txt (fastmcp==3.4.5).

Register with Claude Code

claude mcp add local-dev-tools -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

For Claude Desktop configuration, usage examples, and extension guidance, see CLAUDE.md.

Testing

28 unittest tests covering each tool's happy path, input validation, and failure modes — plus end-to-end checks that the tools are discoverable and callable over the real MCP protocol via an in-memory FastMCP client. All fixtures (SQLite databases, temporary Git repositories, listening sockets) are created in temp directories and cleaned up; nothing is written outside tempfile.gettempdir().

.venv/bin/python test_server.py
# Ran 28 tests — OK

Continuous integration runs the suite, a pycodestyle check, and a stdio startup smoke test against Python 3.10, 3.11, 3.12, and 3.13 on every push and pull request — see .github/workflows/tests.yml.

See NIGHTLY_BUILD_REPORT.md for the full test matrix, environment details, and known limitations.

Requirements

Python 3.10+ (developed on 3.14; CI verifies 3.10–3.13), fastmcp 3.x, and git on PATH for git_diff_summary.