MCP Desktop Tools
MCP Desktop Tools provides a minimal Model Context Protocol (MCP) server and a local CLI (mcp-tools) for inspecting source trees across configured workspaces using ripgrep and git.
Features (C1)
- Minimal MCP server registering
search_text,git_graph,repo_map,scaffold, andopen_recenttools, speaking JSON over stdin/stdout. - Workspace configuration via
workspaces.yamlwith environment overrides. - Security helpers to keep requests within declared workspace roots, including symlink escape detection.
- Persistent disk cache for
repo_mapand in-process TTL cache forsearch_text, with per-request opt-out (--no-cache). - Bounded filesystem concurrency with tunable worker pool (
--max-workers/MCPDT_MAX_WORKERS). - Rich metrics:
elapsed_ms,git_cmd_ms,fs_walk_count,bytes_scanned,cache_hit, and optional stage profiles (--profile). - Ripgrep and git adapters with configurable timeouts (
MCPDT_SUBPROC_TIMEOUT_MS) and warnings for truncated results. - Logging with configurable level through
MCPDT_LOGor the CLI--log-levelflag. - Scaffold and open_recent tools for generating project skeletons and listing recently modified files, with user template overrides (
MCPDT_TEMPLATES_USER_DIR). - New:
snapshottool composes git history, filesystem stats, and safe environment markers into a single JSON artifact that can optionally be logged to MLflow. - New: Minimal Python client (
mcp_desktop_tools.integrations.lab_client.LabClient) for invoking tools from *Lab agents.
Installation
See INSTALL.md for detailed instructions. In short:
pipx install . # or python -m pip install -e .[dev]
External binaries required:
Override discovery via MCPDT_RG_PATH / MCPDT_GIT_PATH if they are not on PATH.
Configuration
Workspaces are defined in workspaces.yaml. See CONFIG.md for schema details. Environment variables can override the configuration path and ripgrep binary.
CLI Usage
Search text with ripgrep:
mcp-tools --workspace demo search_text --query "main" --include "**/*.py" --before 1 --after 1 --json
Summarise a git repository:
mcp-tools --workspace demo git_graph --rel-path proj --last-commits 20 --with-files --json
Generate a repository map:
mcp-tools --workspace demo repo_map --rel-path proj --max-depth 5 --top-dirs 30 --yaml
Capture a repository snapshot and log it to MLflow:
mcp-tools --workspace demo snapshot --rel-path proj --run-name "$BUILD_TAG" --tag repo=proj --mlflow-uri "$MLFLOW_TRACKING_URI" --experiment homelab --artifact-path repo_snapshot.json --json
Scaffold a project using the built-in templates:
mcp-tools --workspace demo scaffold --target-rel demo --template-id pyproject_min --var project_name=demo --dry-run --json
List recently updated files:
mcp-tools --workspace demo open_recent --rel-path proj --count 20 --extensions .py --json
Use --yaml to emit YAML instead of tabular output. --profile prints stage timings to stderr and includes metrics.profile in structured outputs.
All cache-enabled commands accept --no-cache; filesystem-heavy commands accept --max-workers to cap concurrency.
Set MCPDT_SNAPSHOT_INCLUDE_ENV=1 to include safe environment markers (os, arch, python, tool versions) in snapshot outputs.
Server Usage
Start the server with:
python -m mcp_desktop_tools.server
The server accepts JSON lines on stdin with the following structure:
{"tool": "search_text", "input": {"workspace_id": "demo", "query": "main"}}
Responses follow the unified schemas documented in mcp_desktop_tools/schemas/*.json.
Detailed usage guides for the scaffold and open_recent tools, including template formats and GardenKeeper integration examples, are available in DOCS/SCAFFOLD.md, DOCS/OPEN_RECENT.md, and DOCS/TEMPLATES.md.
Logging
Set MCPDT_LOG (or --log-level for the CLI) to control verbosity. Logs include timing information recorded by the adapters and tool execution paths. Metrics such as elapsed_ms, git_cmd_ms, bytes_scanned, cache_hit, and trimming warnings are propagated in tool responses.
Testing
Run the quality suite with:
ruff check .
mypy mcp_desktop_tools
pytest -q --cov=mcp_desktop_tools
Integration tests expect both rg and git to be available.
See SECURITY.md, POLICY.md, CONFIG.md, PERF.md, and CONTRIBUTING.md for additional guidance. Tool-specific schemas are documented in DOCS/TOOLS.md, and MLflow/*Lab examples live in DOCS/INTEGRATIONS.md.
