36 lines
2.6 KiB
Markdown
36 lines
2.6 KiB
Markdown
# Repository Guidelines
|
|
This guide supports new agents contributing to `metal-kompanion`, the MCP backend for Kompanion. Follow these practices to keep the service buildable, testable, and easy to review.
|
|
|
|
## Project Structure & Module Organization
|
|
- `src/` holds C++ code: `mcp/` for server facade and tool routing, `memory/` for embeddings contracts, `dal/` for persistence, and `policy/` for capability rules.
|
|
- `docs/` hosts design notes; `runtime/kom_runner.py` is the Python orchestrator for agent execution against Ollama; `db/` and `sql/` capture Postgres schemas.
|
|
- Place sample payloads or fixtures under `tests/` (currently `tests/schemas/` for JSON samples). Generated artifacts live in `build/`.
|
|
|
|
## Build, Test, and Development Commands
|
|
```bash
|
|
cmake -S . -B build # configure with CMake 3.22+, targets C++20
|
|
cmake --build build -j # compile the kom_mcp executable
|
|
ctest --test-dir build # run CTest suites once they are defined
|
|
python3 runtime/kom_runner.py # exercise the runtime loop (requires OLLAMA_BASE)
|
|
```
|
|
Run the Python runtime from a virtualenv seeded with `pip install -r runtime/requirements.txt`.
|
|
|
|
## Coding Style & Naming Conventions
|
|
- C++20, clang/gcc friendly, 4-space indentation, braces on the same line (`class KomMcpServer {`).
|
|
- Classes use PascalCase; methods camelCase; private members keep the trailing underscore (`tools_`). Prefer `std::` types and RAII helpers over raw pointers.
|
|
- Keep headers lean: forward declare where possible and document non-obvious behavior with concise comments.
|
|
|
|
## Testing Guidelines
|
|
- Add unit or schema validation tests under `tests/`, mirroring the source tree (e.g., `tests/mcp/` for dispatcher tests).
|
|
- Register new tests with CTest via `add_test` in `CMakeLists.txt`; verify they pass with `ctest --output-on-failure`.
|
|
- Provide realistic JSON samples for new tools alongside schema updates to guard against regressions.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
- Follow the existing `scope: message` pattern from git history (`docker: fix host ollama port`); keep messages imperative and present tense.
|
|
- Each PR should state intent, link relevant issues, and include before/after notes or screenshots when UI-adjacent runtime behavior changes.
|
|
- Mention how to reproduce test runs (`cmake --build`, `ctest`) and flag configuration or migration steps (e.g., `sql/` changes).
|
|
|
|
## Security & Configuration Tips
|
|
- Do not commit secrets; runtime state lives beneath XDG paths (`~/.local/state/kompanion`). Document any new env vars in `docs/`.
|
|
- When integrating new tools, ensure access control aligns with `policy/` capabilities and record expected journal entries in `runtime` docs.
|