checko-mcp: Instructions file for Codex

AGENTS.md — Руководство для AI-агентов и разработчиков

Этот файл описывает структуру проекта, соглашения по коду и инструкции для AI-агентов, работающих над этим репозиторием.

---

Обзор проекта

checko-mcp — Python MCP-сервер для Checko.ru API v2. Предоставляет AI-ассистентам и MCP-клиентам:

• 12 инструментов (tools) — вызовы эндпоинтов API.
• 6 готовых сценариев (prompts) — типовые workflow с зашитой последовательностью вызовов.
• 5 справочных ресурсов (resources) — agent guide, правовая справка, методология аудита.

Стек:

• Python 3.10+ (CI: 3.10/3.11/3.12/3.13)
• mcp[cli] — Python MCP SDK (stdio-транспорт)
• httpx — async HTTP-клиент (один экземпляр на жизнь сервера)
• python-dotenv — загрузка переменных окружения
• pytest + pytest-asyncio — тесты
• ruff — линтер
• Docker / docker-compose — контейнеризация (приоритетный способ запуска)

---

Структура репозитория

checko-mcp/
├── src/
│   └── checko_mcp/
│       ├── __init__.py        — версия пакета
│       ├── __main__.py        — точка входа: asyncio.run(run())
│       ├── _validation.py     — require_any, check_format, coerce_bool, ValidationError
│       ├── client.py          — CheckoClient (httpx.AsyncClient + CheckoAPIError)
│       ├── tools.py           — реестр TOOLS: список ToolSpec(name, endpoint, schema, pre)
│       ├── resources.py       — реестр RESOURCES + загрузка markdown (package data + dev fallback)
│       ├── prompts.py         — реестр PROMPTS: 6 готовых сценариев
│       ├── server.py          — MCP Server: list_tools/call_tool, list_resources/read_resource,
│       │                         list_prompts/get_prompt, run
│       └── _resources/        — package data: канонические markdown-файлы (force-include в wheel)
├── tests/
│   ├── conftest.py            — фикстуры: подмена API-ключа, фабрика клиента с MockTransport
│   ├── test_validation.py     — валидаторы
│   ├── test_client.py         — HTTP-клиент (httpx.MockTransport)
│   ├── test_tools.py          — реестр инструментов и pre-валидаторы
│   ├── test_resources.py      — реестр ресурсов и загрузка markdown
│   └── test_prompts.py        — реестр promptов и шаблоны
├── docs/
│   ├── api/                   — справочник по эндпоинтам Checko API
│   │   ├── README.md
│   │   ├── search.md, company.md, entrepreneur.md, person.md
│   │   ├── finances.md, legal-cases.md, contracts.md, inspections.md
│   │   ├── bank.md, timeline.md, fedresurs.md, bankruptcy-messages.md
│   └── instructions/
│       └── agent-guide.md     — каноничный текст ресурса checko://docs/agent-guide
├── playbooks/
│   ├── README.md
│   └── audit/                 — методология/чеклист/шаблон (= ресурсы checko://playbooks/audit/*)
├── .github/
│   ├── workflows/ci.yml       — lint + tests на 4 версиях Python + docker build
│   ├── ISSUE_TEMPLATE/
│   └── PULL_REQUEST_TEMPLATE.md
├── Dockerfile                 — multi-stage, python:3.13-slim
├── docker-compose.yml         — приоритетный способ запуска (env_file: .env)
├── pyproject.toml             — hatchling, ruff, pytest, [project.optional-dependencies] dev
├── .env.example
├── README.md                  — пользовательская документация
├── AGENTS.md                  — этот файл
├── CHANGELOG.md               — Keep a Changelog + SemVer
├── CONTRIBUTING.md            — как внести вклад
├── SECURITY.md                — политика приёма уязвимостей
├── LEGAL.md                   — правовые основания (152-ФЗ, 149-ФЗ)
└── LICENSE                    — MIT