una/tools/AGENTS.md

Tools

CLI MCP servers for coding agents. Run them inside the php service from the repository root, with the stack up (docker compose up -d).

Each file is an MCP server (stdio, protocol 2026-07-28). Messages are one JSON-RPC object per line. Every request includes _meta.io.modelcontextprotocol/protocolVersion (2026-07-28) and _meta.io.modelcontextprotocol/clientCapabilities. The server answers server/discover, tools/list, and tools/call.

Language keys

add_lang_key.php adds a missing English or Russian string. Do not insert keys by hand into language XML, sys_localization_keys, or sys_localization_strings. Read .agents/skills/language-keys/SKILL.md before adding one.

It writes the key into the language XML next to the closest existing keys, inserts it into the database when that language is installed, and recompiles the language cache. An existing translation is left unchanged.

docker compose exec -T -w /opt/una php php tools/add_lang_key.php <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"add","arguments":{"language":"en","key":"_sys_example","translation":"Hello"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}
EOF

A successful add result has content (a short status) and structuredContent (file, xml of added or already_present, keptExisting, languageInstalled, keyCreated, translationStatus of added, already_present, or skipped, keyId, category, recompiled). A failure comes back as isError: true. When the language is not installed, the XML is still written and languageInstalled is false.

Database

db.php queries the installed UNA database. It reads the host, name, user, and password from inc/header.inc.php and connects directly. Run it inside the php service so that host (mysql) resolves. A tools/call of the query tool runs the statement on the live database for this instance.

docker compose exec -T -w /opt/una php php tools/db.php <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"query","arguments":{"sql":"SELECT id, name FROM sys_modules LIMIT 5"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}
EOF

A successful query result has content (tab-separated text; the word NULL stands for a null) and structuredContent.results (column names and rows, JSON null for a null). Several statements separated by semicolons run in one transaction and commit together. If a later statement fails, earlier statements in that transaction are rolled back and the error says so. A statement that commits by itself, such as a schema change, stays applied; the error then includes the results of the statements that already committed. A statement that changes rows reports affected. A result set contains at most 1000 rows. A truncated set has truncated true and the text says it was truncated. A SQL failure comes back as isError: true.