orionbelt-semantic-layer-mcp: Instructions file for Codex

AGENTS.md

This file provides guidance to coding agents when working with code in this repository.

What this is

A thin MCP server that wraps the OrionBelt Semantic Layer (OBSL) REST API. It contains no semantic engine and no business logic — every tool delegates over HTTP to the API and formats the response. All meaning lives in the API repo, which is the source of truth for endpoints, schemas, and behavior:

• API repo: ../orionbelt-semantic-layer (GitHub: ralforion/orionbelt-semantic-layer)

The entire implementation is a single module, server.py (~3k lines). Tests live in tests/test_server.py. The hatch build ships only server.py.

Commands

uv run pytest                              # full suite
uv run pytest tests/test_server.py::NAME   # single test (NAME = test function or Class::method)
uv run pytest -q -k SUBSTRING              # filter by name substring
uv run ruff check .                        # lint  (must be clean before done)
uv run ruff format server.py tests/        # format
./scripts/setup-hooks.sh                   # install pre-commit hooks (runs ruff)
uv run server.py                           # run locally (reads .env; see .env.example)

Tests mock the API with respx (httpx interception) and pytest-asyncio in auto mode — they never hit a live API. When changing an endpoint call, update its respx mock in the same test.

Architecture (the non-obvious parts)

Delegation layer. Tools call thin request helpers, never httpx directly: _api_request (base, with one-shot retry on session expiry) → _session_request (multi-model, prefixes /v1/sessions/{id}/models/{mid}) and _shortcut_request (single-model, top-level /v1/...). _parse_json / _raise_api_error normalize responses and surface API error detail as ToolError.

Two API modes, detected once at startup via GET /v1/settings (_detect_api_mode), then frozen:

• single-model — the API has one pre-loaded model; tools hit shortcut routes (/v1/schema, /v1/query/execute, …) and model_id is implicit.
• multi-model — tools operate on session-scoped routes and take a model_id; sessions are auto-created (_ensure_session) and deleted on shutdown.