konflux-devlake-mcp: Instructions file for Codex

Konflux DevLake MCP Server - Agent Quick Reference

Python MCP server providing engineering metrics tools for Konflux DevLake databases.

Data Flow

Request -> server/handlers/tool_handler.py (security) -> tools/tools_manager.py (routing) -> tools/devlake/<tool>.py (SQL + logic) -> utils/db.py (async MySQL pool, type conversion) -> toon_encode() response

Key Paths

tools/devlake/ metric tools | tools/base/base_tool.py BaseTool ABC | tools/tools_manager.py registry server/ MCP core | utils/db.py async MySQL pool | utils/security.py SQL injection detection skills/ Claude Code skills (must stay in sync with tools) | tests/conftest.py shared fixtures

Adding a Tool

1. Create tools/devlake/my_tool.py extending BaseTool
2. get_tools() -> List[mcp.types.Tool] with JSON inputSchema
3. async call_tool() -> toon_encode(result, {"delimiter": ",", "indent": 2, "lengthMarker": ""})
4. Register in tools/tools_manager.py _tool_modules list
5. Add unit test: tests/unit/test_my_tool.py with @pytest.mark.unit
6. Update skills/devlake/ if tool interface or SQL changed (see Skill Update Rule)

Test Suite

Every tool in tools/tools_manager.py _tool_modules (12 modules) must have a dedicated tests/unit/test_<name>.py. Each test file validates: get_tools() returns correct tool names and schemas, call_tool() with mocked DB rows returns toon_decode()-parseable results with success: True, error paths return success: False, and filter/limit arguments are respected. Integration tests in tests/integration/ use real MySQL and clean_database fixture.

When investigating a bug or adding a feature, verify tests/unit/test_<name>.py exists and covers call_tool() execution with expected computed values (scores, averages, classifications) -- not just response structure. If tests are missing or incomplete, add them. Commands: make test-unit (mocked DB) | make test-integration (docker compose MySQL) | make test-e2e (requires GEMINI_API_KEY, seeds from testdata/mysql/)