Development

Clean is small, local, and easy to hack on. Contributions are welcome at github.com/cleanmcp/clean-mcp.

Make targets

make install   # creates .venv and installs Clean + dev deps
make test      # runs the test suite (pytest)
make lint      # ruff check + format check
make format    # apply ruff fixes
make clean     # remove venv and caches

If you're not using make, create or activate your own virtualenv and run python -m pip install -e ".[dev]". The dev extra installs pytest and ruff.

Project layout

src/clean/
  core/        Config and error types
  parsing/     Tree-sitter parsers (Python, JavaScript, TypeScript)
  indexing/    File scanning, code indexing, incremental reindex
  embedding/   Local embedding model (all-MiniLM-L6-v2)
  search/      Semantic search + context expansion
  storage/     LanceDB vector store
  formatting/  Output formatters (TOON, JSON, Rich)
  db/          SQLite metadata store
  repo/        Git clone/pull manager
  mcp/         MCP shared helpers
  local/       Stdio MCP server entry point
  services/    ServiceContainer (dependency wiring)
  stats/       Token savings tracker
  util/        Logging, security, hashing

tests/
  unit/        Fast, isolated tests
  integration/ Tests with real indexing/search
  e2e/         End-to-end MCP server tests

Tests

The suite is split into unit, integration, and e2e. Run everything with make test, or target a slice with pytest directly:

python -m pytest tests/unit
python -m pytest tests/e2e/test_mcp_server.py

Language support

Parsing is powered by tree-sitter. The supported languages are Python, JavaScript, and TypeScript. Adding a language means adding a parser under src/clean/parsing/ and registering it.

License

MIT — see the LICENSE in the repo.