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.

License

MIT © Emma Huang — see LICENSE.