chelydra
/
metal-kompanion
4
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
metal-kompanion/AGENTS.md

2.9 KiB
Raw Permalink Blame History

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.

source dev.env for envrionment variables.

MCP Usage

  • This project uses agentic-control-framework Use this for task planning

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.
  • docs/third_party is a symlink to reference code and apidocs.
  • Place sample payloads or fixtures under tests/ (currently tests/schemas/ for JSON samples). Generated artifacts live in build/.
  • src/cli is a command line prompt interface that tests the memory integration and pattern substiton.
  • tools

Build, Test, and Development Commands

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.