1c-mcp

Give an AI agent eyes into your 1C:Enterprise 8.3 base — read metadata & data, run queries, and diagnose why a document won't post — over one extension HTTP service.

Why

Most 1C automation tooling either reads metadata or reads data. The thing an analyst actually gets stuck on — "this document won't post, why?" — needs both, plus the ability to run the posting logic and capture the error. 1c-mcp does exactly that.

It exposes your base as MCP tools through a thin HTTP service in a configuration extension. The MCP server stays a small, strict TypeScript client; the reasoning about how to fix a broken document is left to the agent (Claude) — no LLM baked into the server, no API keys to manage.

• 🔎 Metadata introspection — objects, attributes, tabular sections, register records

• 📄 Data & queries — read objects by ref, run 1C query-language, list documents, read register movements

• 🩺 Document diagnosis — test-post a document inside a rolled-back transaction, capture the fill errors, the exception text, the failing attribute, and the movements it tried to make — the whole context an agent needs to explain and fix it

• 🔒 Read-only by default — write tools (object_update, document_post) exist but only register when ONEC_ALLOW_WRITE=1

• 🪶 TypeScript, ESM, MIT — 2 runtime deps (@modelcontextprotocol/sdk, zod), no 1C secrets in the repo

Related MCP server: 1C MCP Server

How document diagnosis works

document_diagnose(ref) is the headline. The extension runs, inside a transaction it always rolls back:

1. ПроверитьЗаполнение() — collects required-field / validation problems

2. Записать(…Проведение) in a Попытка/Исключение — captures the posting exception and every Сообщить()

3. reads back the register movements it would have made

…then returns one structured object. The agent gets the error text, the exact attribute/row that failed, the document data, the object's metadata, and the attempted movements — and works out the fix:

document_diagnose   # ref → { filled, fillErrors, posts, errorText, messages, wouldMove, data, metadata }
                    # agent reads it, explains the cause, proposes the change
object_update       # (if ONEC_ALLOW_WRITE=1) apply the fix
document_post       # (if ONEC_ALLOW_WRITE=1) post for real

Because the transaction is always rolled back, diagnosis has zero side effects on the base.

Requirements

1. 1C:Enterprise 8.3 base published on a web server with HTTP services enabled.

2. A configuration extension exposing the HTTP service mcp (see The 1C side — this is the part you build, against a fixed contract).

3. A 1C user for the MCP to authenticate as (Basic Auth).

4. Node ≥ 18.

Setup

npm install
cp .env.example .env      # set ONEC_URL / ONEC_USER / ONEC_PASSWORD
npm run build

Register it with your MCP client:

{
  "mcpServers": {
    "1c": {
      "command": "node",
      "args": ["D:/projects/1c-mcp/dist/index.js"],
      "env": {
        "ONEC_URL": "http://localhost/mybase/hs/mcp",
        "ONEC_USER": "mcp",
        "ONEC_PASSWORD": "secret",
        "ONEC_ALLOW_WRITE": "0"
      }
    }
  }
}

The env prefix is ONEC_ (not 1C_) on purpose — a var name starting with a digit breaks in POSIX shells.

Tools

⚑ — registered only when ONEC_ALLOW_WRITE=1.

The 1C side

The MCP talks to one HTTP service. You implement it in a configuration extension, against this contract.

Root: http://<host>/<base>/hs/mcp. Every method: POST, JSON body, Basic Auth. Errors: non-2xx with body { "error": { "code": string, "message": string } } (the client turns this into a tool error).

/document/diagnose response

{
  "ref": "guid",
  "presentation": "Реализация 0001 от 01.01.2026",
  "filled": false,
  "fillErrors": [{ "field": "Организация", "message": "Поле не заполнено" }],
  "posts": false,
  "errorText": "Недостаточно 5 шт номенклатуры X на складе Y",
  "messages": [{ "text": "...", "field": "Товары", "dataPath": "Товары[2].Количество" }],
  "wouldMove": [{ "register": "ТоварыНаСкладах", "records": [{ "...": "..." }] }],
  "data": { "Организация": null, "Товары": [{ "...": "..." }] },
  "metadata": { "attributes": [], "tabularSections": [], "registerRecords": [] }
}

Extension setup checklist

1. Create a configuration extension, add an HTTP service with root URL mcp.

2. Implement the URL templates from the contract (method POST, JSON in/out).

3. The key handler /document/diagnose — a side-effect-free test-post:

   Объект = Ссылка.ПолучитьОбъект();
   Результат = Новый Структура("filled, fillErrors, posts, errorText, messages, wouldMove, data, metadata");
   
   НачатьТранзакцию();
   Попытка
       Результат.filled = Объект.ПроверитьЗаполнение();     // messages collected below
       Попытка
           Объект.Записать(РежимЗаписиДокумента.Проведение);
           Результат.posts = Истина;
       Исключение
           Результат.posts = Ложь;
           Результат.errorText = ОписаниеОшибки();
       КонецПопытки;
       Результат.messages = ПолучитьСообщенияПользователю(Истина);
   Исключение
       Результат.errorText = ОписаниеОшибки();
   КонецПопытки;
   ОтменитьТранзакцию();   // always roll back — the base is never changed

   Fill data / metadata / wouldMove and return the JSON above.

4. Publish the base on a web server, enable HTTP services, create the ONEC_USER user.

5. Smoke test: curl -u user:pass -X POST http://host/base/hs/mcp/metadata/list -d "{}".

Development

npm test          # vitest — config, HTTP client, write-tool gating (no live 1C needed)
npm run build     # tsc → dist/
npx tsc --noEmit  # typecheck

The design spec and implementation plan live in docs/superpowers/.

Security

• document_diagnose always runs inside a rolled-back transaction — zero side effects.

• Write tools register only when ONEC_ALLOW_WRITE=1.

• 1C credentials come from the environment only; .env is git-ignored and never committed.

Contributing

PRs welcome. Good first ideas:

• a bundled reference extension (.xml sources of the HTTP-service module)

• OData transport as a read-only fallback (no extension required)

• richer wouldMove shaping / typed diagnose result

• Russian README

1. Fork and branch: git checkout -b feature/my-change

2. npm install; npm run build and npx tsc --noEmit must pass; npm test green

3. Never commit secrets (.env, passwords) or real base data

4. Open a PR describing what and why

License

MIT