{
  "markdown": "# onec-odata-mcp\n\n[![npm](https://img.shields.io/npm/v/onec-odata-mcp.svg)](https://www.npmjs.com/package/onec-odata-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-blue)](https://github.com/modelcontextprotocol/registry)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)\n\n## Подключи 1С к Claude за 5 минут\n\nДаёт Claude (Desktop, Code, любой MCP-клиент) доступ на чтение к базе 1С:Предприятие через стандартный OData. Вместо выгрузки в Excel или ручного написания OData-урлов — спрашиваешь по-русски, получаешь структурированные данные из справочников и документов.\n\nРаботает с любой конфигурацией 1С, где опубликован OData (Бухгалтерия, ERP, Управление торговлей, самописные конфигурации).\n\n> 📸 TODO: скриншот/видео 5-минутной настройки — добавить после первого прогона с реальной базой.\n\n### Шаг 1 — установка\n\nНичего ставить локально не нужно, `npx` подтянет пакет при первом запуске:\n\n**One-liner (after npm publish):**\n\n```bash\nnpx -y onec-odata-mcp\n```\n\nSet `ONEC_BASE_URL`, `ONEC_USERNAME`, and `ONEC_PASSWORD` in your MCP client config (see below).\n\n**From source:**\n\n```bash\nnpx -y onec-odata-mcp\n```\n\n(Для разработки из исходников: `npm install && npm run build`.)\n\n### Шаг 2 — подключи к Claude\n\n**Вариант А — командой `claude mcp add` (Claude Code):**\n\n```bash\nclaude mcp add onec-odata \\\n  -e ONEC_BASE_URL=https://1c.example.com/your_db/odata/standard.odata \\\n  -e ONEC_USERNAME=odata_user \\\n  -e ONEC_PASSWORD=your_password \\\n  -- npx -y onec-odata-mcp\n```\n\n**Вариант Б — вручную в `claude_desktop_config.json`** (Claude Desktop: Settings → Developer → Edit Config):\n\n```json\n{\n  \"mcpServers\": {\n    \"onec-odata\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"onec-odata-mcp\"],\n      \"env\": {\n        \"ONEC_BASE_URL\": \"https://1c.example.com/your_db/odata/standard.odata\",\n        \"ONEC_USERNAME\": \"odata_user\",\n        \"ONEC_PASSWORD\": \"your_password\"\n      }\n    }\n  }\n}\n```\n\nГотовый сниппет лежит в [`examples/claude_desktop_config.json`](./examples/claude_desktop_config.json).\n\nОпционально: `ONEC_DATABASE` (подсказка имени базы), `ONEC_METADATA_CACHE_TTL_MS` (TTL кэша метаданных, по умолчанию 1 час), `ONEC_WRITABLE=true` (разрешить реальную запись через `odata_write`; по умолчанию false). Либо вместо переменных окружения — JSON-файл `~/.onec-odata/onec-config.json` с полями `baseUrl`, `username`, `password` (и опционально `\"writable\": true`), путь к которому задаётся через `ONEC_CONFIG_PATH`.\n\n### Шаг 3 — первый запрос\n\nПерезапусти Claude и спроси:\n\n> «Какие справочники и документы есть в базе 1С?»\n\nClaude вызовет `odata_list_entities`, увидит список и дальше сам подберёт нужные инструменты под конкретный вопрос — без знания синтаксиса OData с твоей стороны.\n\nБольше готовых промптов — в [`examples/prompts.md`](./examples/prompts.md).\n\n## Инструменты\n\n| Инструмент | Что делает | Пример вопроса |\n|---|---|---|\n| `odata_config` | Проверяет статус подключения и настройки | «Проверь, подключена ли 1С» |\n| `odata_list_entities` | Список всех доступных OData-сущностей | «Какие справочники и документы есть в базе?» |\n| `odata_metadata` | Типы и наборы сущностей из `$metadata` (кэш, TTL 1ч) | вызывается автоматически перед сложными запросами |\n| `odata_explain_entity` | Поля, типы, ключи, связи конкретной сущности | «Какие поля у справочника Контрагенты?» |\n| `odata_build_query` | Строит и проверяет `$filter`/`$select`/`$orderby` из структурированных параметров запроса | вызывается автоматически — Claude сам переводит «за июнь» в даты, тул собирает и валидирует фильтр |\n| `odata_query` | Запрос к сущности с готовыми OData-параметрами | «Покажи остатки по счёту 51 за июнь» |\n| `odata_count` | Количество записей, опционально с фильтром | «Сколько контрагентов зарегистрировано в этом году?» |\n| `odata_write` | Создание/изменение/удаление сущности (POST/PATCH/DELETE) | «Создай контрагента…» — сначала dry-run-превью |\n| `odata_financial_summary` | Автообнаружение типовых финансовых сущностей + счётчики | «Дай сводку по счетам, реализациям и контрагентам» |\n\nОбычно агент сам комбинирует `odata_build_query` → `odata_query`/`odata_count`, тебе достаточно спросить своими словами.\n\n## Безопасность\n\n- **По умолчанию только чтение.** Флаг `writable` в конфиге базы (env `ONEC_WRITABLE=true` / `\"writable\": true` в `~/.onec-odata/onec-config.json`) по умолчанию **false**. Без него реальные `POST`/`PATCH`/`DELETE` не уходят в 1С.\n- **Запись — только через `odata_write`.** У инструмента `dryRun` по умолчанию **true**: всегда сначала превью `{dryRun: true, wouldExecute: …}` без сетевого вызова. Реальная запись требует **и** `writable: true` на этой базе, **и** явного `dryRun: false`.\n- **Пароль** передаётся Basic Auth (base64 в заголовке каждого запроса — как требует OData) и хранится либо в env-переменных конфига твоего MCP-клиента (рекомендуется), либо в локальном файле `~/.onec-odata/onec-config.json`. Сервер не логирует и не возвращает пароль в ответах инструментов.\n- **Поля-секреты** (`password`, `token`, `apikey`, `secret` и т.п. в названиях) автоматически исключены из подсказок «возможно, вы имели в виду» (`src/query/fuzzy.ts`), чтобы агент не подсвечивал их случайно.\n- **Рекомендация:** заведи в 1С отдельного OData-пользователя с ролью только на чтение для обычной работы; writable-учётку и `ONEC_WRITABLE=true` включай только осознанно.\n\n## Требования\n\n- Node.js ≥ 18\n- 1С:Предприятие с опубликованным OData-интерфейсом (веб-публикация → `standard.odata`)\n\n## Разработка\n\n```bash\nnpm install\nnpm run build   # type-check + сборка в dist/\nnpm test\n```\n\nДетали и правила вклада — в [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## License\n\nMIT\n\n---\n\n## English (short)\n\nMCP server giving Claude (or any MCP client) access to a 1C:Enterprise database via its standard OData endpoint. **Read-only by default** (`writable: false`); writes go through `odata_write` and always dry-run first unless you explicitly enable `writable: true` and pass `dryRun: false`. No spreadsheet exports, no hand-written OData URLs — ask in natural language, get structured data from catalogs and documents.\n\n```bash\nnpx -y onec-odata-mcp\n```\n\nConfigure via `ONEC_BASE_URL` / `ONEC_USERNAME` / `ONEC_PASSWORD` env vars (see the Russian quick-start above for `claude mcp add` and `claude_desktop_config.json` snippets — the JSON is language-agnostic). Optional: `ONEC_WRITABLE=true` to allow real writes. Published on npm as [`onec-odata-mcp`](https://www.npmjs.com/package/onec-odata-mcp) and listed in the official MCP Registry as `io.github.alexgrebeshok-coder/onec-odata-mcp`.\n",
  "bytes": 6573,
  "sha": "1032edf66d3b249f20373e85f85887675df0fd292c275451cbebbb25348c1ea8",
  "repo_slug": "pyrfor/onec-odata-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_alexgrebeshok_coder_onec_odata_9f0936ab/readme"
}