|
| 1 | +# Contributing to codebase-memory-mcp |
| 2 | + |
| 3 | +Contributions are welcome. This guide covers setup, testing, and PR guidelines. |
| 4 | + |
| 5 | +## Build from Source |
| 6 | + |
| 7 | +**Prerequisites**: Go 1.26+, a C compiler (gcc or clang — needed for tree-sitter CGO bindings), Git. |
| 8 | + |
| 9 | +```bash |
| 10 | +git clone https://github.com/DeusData/codebase-memory-mcp.git |
| 11 | +cd codebase-memory-mcp |
| 12 | +CGO_ENABLED=1 go build -o codebase-memory-mcp ./cmd/codebase-memory-mcp/ |
| 13 | +``` |
| 14 | + |
| 15 | +macOS: `xcode-select --install` provides clang. |
| 16 | +Linux: `sudo apt install build-essential` (Debian/Ubuntu) or `sudo dnf install gcc` (Fedora). |
| 17 | + |
| 18 | +## Run Tests |
| 19 | + |
| 20 | +```bash |
| 21 | +go test ./... -count=1 |
| 22 | +``` |
| 23 | + |
| 24 | +Key test files: |
| 25 | +- `internal/pipeline/langparity_test.go` — 125+ language parity cases |
| 26 | +- `internal/pipeline/astdump_test.go` — 90+ AST structure cases |
| 27 | +- `internal/pipeline/pipeline_test.go` — integration tests |
| 28 | + |
| 29 | +## Run Linter |
| 30 | + |
| 31 | +```bash |
| 32 | +golangci-lint run ./... |
| 33 | +``` |
| 34 | + |
| 35 | +## Project Structure |
| 36 | + |
| 37 | +``` |
| 38 | +cmd/codebase-memory-mcp/ Entry point (MCP server + CLI + install/update) |
| 39 | +internal/ |
| 40 | + lang/ Language specs (35 languages, tree-sitter node types) |
| 41 | + parser/ Tree-sitter grammar loading |
| 42 | + pipeline/ Multi-pass indexing pipeline |
| 43 | + httplink/ Cross-service HTTP route matching |
| 44 | + cypher/ Cypher query engine |
| 45 | + store/ SQLite graph storage |
| 46 | + tools/ MCP tool handlers (12 tools) |
| 47 | + watcher/ Background auto-sync |
| 48 | + discover/ File discovery with .cgrignore |
| 49 | + fqn/ Qualified name computation |
| 50 | +``` |
| 51 | + |
| 52 | +## Adding or Fixing Language Support |
| 53 | + |
| 54 | +Most language issues are in `internal/lang/<name>.go` (node type configuration) or `internal/pipeline/` (extraction logic). |
| 55 | + |
| 56 | +**Workflow for language fixes:** |
| 57 | + |
| 58 | +1. Find the relevant language spec in `internal/lang/` |
| 59 | +2. Use AST dump tests to see actual tree-sitter node types: |
| 60 | + ```bash |
| 61 | + go test ./internal/pipeline/ -run TestASTDump -v |
| 62 | + ``` |
| 63 | +3. Compare configured node types vs actual AST output |
| 64 | +4. Update the language spec and add/fix parity test cases |
| 65 | +5. Verify with a real open-source repo (see `BENCHMARK_REPORT.md` for test repos per language) |
| 66 | + |
| 67 | +## Pull Request Guidelines |
| 68 | + |
| 69 | +- One logical change per PR |
| 70 | +- Include tests for new functionality |
| 71 | +- Run `go test ./... -count=1` and `golangci-lint run` before submitting |
| 72 | +- Keep PRs focused — avoid unrelated reformatting or refactoring |
| 73 | +- Reference the issue number in your PR description |
| 74 | + |
| 75 | +## Good First Issues |
| 76 | + |
| 77 | +Check [issues labeled `good first issue`](https://github.com/DeusData/codebase-memory-mcp/labels/good%20first%20issue) for beginner-friendly tasks with clear scope and guidance. |
| 78 | + |
| 79 | +## License |
| 80 | + |
| 81 | +By contributing, you agree that your contributions will be licensed under the MIT License. |
0 commit comments