MCP server for 1C configuration structures

A reference for the metadata of several 1C configurations, for the platform syntax and for the query language — for agents writing BSL code. It returns a minimally sufficient slice: resolving a human wording into the exact object name, searching for ready-made procedures in a code dump, their signatures, limited windows of bodies and back-references from calls, metadata and forms, the object structure at the required level of detail, its links, descriptions of platform methods taking into account the version of the specific configuration and query language constructs.

It does not replace grep over the project's working sources: the server searches for procedures only in the loaded configuration dump into files and does not see unloaded edits. The boundary of sources is fixed in docs/data-sources.md.

Status — as of 2026-08-21

The final image size was checked on 2026-08-21: the command docker image ls mcp1c:latest --format '{{.Size}}' output 357MB. This is the size displayed by the Docker CLI. The command docker image inspect mcp1c:latest --format '{{.Size}}' returned 77950901 bytes of the internal field; this is a different metric, not a second measurement of the displayed size.

There are no restrictions on the configuration. Any one loads — standard (accounting, payroll, document flow, retail) and industry-specific: the dump processing walks the metadata rather than knowing it by heart. Whatever was dumped gets parsed.

What matters is the platform version on which the configuration runs: it determines what get_syntax will show as available and what it will hide as later. Verified on 8.3.5 and 8.3.23 — these are the boundaries of what has been encountered; the help is merged from three versions, 8.3.5, 8.3.23 and 8.3.27. The dump processing, meanwhile, must compile on 8.3.5: the lower boundary is set by it, not by the server.

Related MCP server: 1C_MCP_SERVER_OWN

Contents

1. Running — Docker, dashboard, link graph, without Docker

2. Connecting an agent — how MCP works, if it does not connect, token, client configs: Claude Code, Codex CLI, Cursor, VS Code, Qwen Code, stdio

3. Tools — call order, sources, query language, platform versions, help merging, replacements

4. Data management — sources, configuration dump into files, dictionary and search keys, CLI, benchmark stand, server manually, where to get data

5. How it is built — modules, measurements, tests

6. Security — tokens, what is open without them

7. Documents

8. License — Apache 2.0, relation to the "1C" company

1. Running

Docker (main method)

# 1. Положить исходные данные
mkdir -p data/bootstrap
cp ВыгрузкаКонфигурации.zip                     data/bootstrap/
cp /opt/1cv8/8.3.27.2130/shcntx_ru.hbk          data/bootstrap/

# 2. Поднять
docker compose up -d --build

# 3. Проверить
curl http://localhost:5001/health

{"status":"ok",
 "configurations_total":2,
 "syntax_loaded":true,
 "query_language_loaded":true,
 "configurations":["РозницаДляКазахстана","ОтраслеваяКонфигурация"],
 "syntax":["8.3.5.1570","8.3.23.1997","8.3.27"]}

The platform help and the query language are different sources and different fields: syntax_loaded refers only to the former, syntax lists the versions of the loaded help. Configuration names and help versions are returned only to a request that passed the read check; without a token, status, the counter and two flags remain.

Everything in data/bootstrap/ is indexed at startup: *.zip — configuration dumps, *.hbk — platform help. The same file is not parsed twice: verification is by hash.

A configuration dump into files placed in bootstrap/ out of habit does not fit — the server recognizes it by the archive contents (code is present, the manifest.json / manifest.xml manifest is not) and does not try to parse it: these are gigabytes, and running them at every startup is not possible. Instead of an error, the startup message list names the file with a reminder of where to put such files — data/incoming/, section “Configuration dump into files” below.

The ./data directory is mounted into the container as /data. Inside it the server keeps sources, indexes, cache and registry.json; paths in the registry are relative, so the directory can be moved between the developer machine and the container.

data/ is entirely outside git — it is a volume, not part of the repository. It is moved by copying the directory. Therefore, after cloning, the help must be placed by yourself: the repository does not contain it and cannot contain it — this is content of the "1C" company.

After changing the code, the container must be recreated, not restarted:

docker compose up -d --build --force-recreate

restart will bring up the old container on the old image, and the edits will not apply.

About the port. The server is exposed externally on 5001, inside the container it listens on 8000 — the 5001:8000 forward is in docker-compose.yml. All addresses in this file are external, that is, 5001. If it is taken by another service — change the left side of the forward, do not touch the right side: EXPOSE and the image healthcheck depend on it.

Dashboard

http://localhost:5001/ — six pages:

Loading — what is visible and when

Loading happens in two stages, and they are shown differently.

File transfer — with a bar on the "Sources" page: percentage, volume, speed and estimated remaining time. The browser counts it, and this is not a whim. The server does not see the transfer progress: await request.form() returns control only when the body has arrived in full, and the job is created only after that. Verified on a live socket: 40 MB took 8.1 s, and during that time 32 polls of /sources from a second connection did not see a single job. On localhost there is no difference; on a remote server this is minutes of an empty screen.

At the same time, the 500 MB limit is checked before sending: previously an oversized file was uploaded in full and only then got a refusal.

Parsing — with the "Loading" table on the same page: "accepting" → "parsing" → "ready" or "error" with a reason. While the work is in progress, the page refreshes itself (meta refresh, every 2 s).

The bar requires JS, the table does not. With JS disabled, the form works like a regular one: the file goes out, the job is created, the state is visible in the table — only the bar during transfer is missing.

Links — object graph

/graph draws the object neighborhood: color by kind, arrow by link direction, edge label on hover. Clicking a node builds a graph around it, dragging moves it, the wheel zooms. The neighbor limit is chosen on the page (15…400), the truncation is named by a number — "shown 30 of 102".

It answers "what breaks if I touch this": a register surrounded by orange documents immediately tells who moves it.

Depth is always one step. At two steps from a common catalog, a thousand objects are reached, at three — a third of the configuration; further, the link goes through common mechanisms like additional attributes, which connect almost everything to everything. Cutting them off with a threshold by the number of links is impossible: such a node has 34 of them, while a meaningful Справочник.Пользователи has 323. Therefore, a human expands nodes, not a heuristic — they see where it is not worth going.

The agent intentionally has no such tool. In two steps the graph grows to a thousand objects, and common mechanisms cannot be cut off with a simple threshold: a meaningful node may have more connections than a technical one. A separate tool will only be returned together with a measurable output-limiting rule; for now, the exact next step is chosen by a human in the interactive graph.

A miss is fixed without leaving the browser: on the requests page, each phrase has a link "not that — create an alias", which leads to the dictionary with the phrase already filled in. The edit takes effect immediately — indexes are not rebuilt, no restart is needed.

Reads are closed with API_TOKEN, writes with ADMIN_TOKEN. While API_TOKEN is not set, anyone who can reach the address can read — including the structure of configurations and refinements. This is acceptable for localhost, but not for a server on a network.

The tokens are separated because the read token lives in every MCP client's config and leaks along with it; the agent should not have the right to delete sources. The admin token also works as a read token — there is no need to keep two headers.

// .mcp.json — как клиент передаёт токен
{"mcpServers": {"1c": {"type": "http", "url": "http://localhost:5001/mcp",
                       "headers": {"X-Api-Token": "..."}}}}

ASCII only: HTTP headers are encoded in latin-1, Cyrillic will not get through them. /health remains open for healthchecks, but it only returns configuration names when given a token.

Loading, deleting, and editing the dictionary require ADMIN_TOKEN — the same one as for /admin/reload; without it these endpoints do not exist, rather than "they are closed". The token is entered once in the form; what goes to the browser is not the token but a session identifier.

It is set via .env next to docker-compose.yml — a template with all variables is in .env.example:

cp .env.example .env
python3 -c "import secrets; print(secrets.token_urlsafe(32))"   # значение
docker compose up -d --force-recreate

The name in the results is a link to the card: for an object this is the requisites with types, tabular sections, and movements; for a platform element — the signature, parameters, availability, and version of introduction. The same text the agent receives, with a brief / fields / full toggle. A requisite has no card of its own — the link leads to the owner object.

The "Requests" page answers the question "why did the server return exactly this": next to each hit there is a reason — exact match, alias from dictionary, all query words. From it you can see how to treat a miss — with a synonym, an alias, or a weight.

Parsing the help takes a few seconds: the page responds after it, but MCP clients are not delayed — indexing goes into a separate thread.

Without Docker

From a repository copy — the same way tests and CLI are run:

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
PYTHONPATH=src .venv/bin/python -m mcp1c.server --host 0.0.0.0 --port 5001

Or as a package — then PYTHONPATH is not needed, and three commands appear alongside:

pip install .

mcp1c-server --host 0.0.0.0 --port 5001   # = python -m mcp1c.server
mcp1c reg-list --data data                # = python -m mcp1c.cli
mcp1c-bench --help                        # = python -m mcp1c.bench

Module launch (python -m mcp1c.server) remains working in this case too: the commands are the same entry points under a different name. All keys are described in the section «Data management».

2. Connecting the agent

The server implements the MCP protocol with the standard transports of the official SDK, so it suits any MCP client. No wrappers around HTTP are required.

Both supported transports are verified with the official MCP client: the initialize handshake, tools/list, tools/call, protocol 2025-11-25.

The legacy HTTP+SSE transport is not supported: --transport sse is rejected as an invalid value before reading data and starting the server. An old client needs streamable-http mode or a local launch via stdio.

How it works

It is useful to understand before something fails to connect. The address is one — /mcp, there is no per-tool endpoint; which tool is called is written in the request body, not in the path.

From here on there are two different mechanics, and they should not be confused:

On connection, the client makes POST initialize — the server responds with the name, version, and text of instructions, and returns mcp-session-id in the header. Then POST tools/list returns the tools all at once: name, description, JSON parameter schema. All of this goes into the model's context before the human has typed the first word. The model does not go for the description when it needs it — it already has it.

Hence a consequence important when editing descriptions: they take up space in the window for the whole session, regardless of whether the model calls a single tool or none.

There are always ten tools, regardless of what is loaded. The set is a contract, not a variable: the tools are interconnected, and on a working server the sources of configuration, code, platform help, and query language can be loaded independently. The size of the tools/list contract plus instructions does not depend on the state of the registry.

From this follows a direct consequence you need to know in advance: if a source is not loaded, you still pay for its tools. Without platform help, search_syntax and get_syntax sit in the context and cost 1,185 tokens, answering "help is not connected"; compare_configurations with one configuration — 262 tokens for the answer "at least two are needed". This is treated by loading the source, not by filtering tools: a dynamic set was tried on 2026-08-19 and abandoned, because independent sources must keep a single session contract.

Descriptions are therefore written densely, and details go into the tool's own output: you pay for them only when they are needed.

GET /mcp is not a "wrong POST", but a third method on the same address: it opens a message stream from the server to the client and requires an already obtained mcp-session-id. DELETE /mcp closes the session.

If the client does not connect

The response code in the log (docker logs -f mcp1c) names the reason:

A real case: Qwen Code did not connect because its config had the key url — in the Gemini CLI family (Qwen inherits the format) it means the old SSE transport, and the client started with GET, getting 400. With httpUrl — that is, streamable-http — the connection succeeds immediately.

Token: what to add to client settings

If API_TOKEN is set on the server, every client must send it as a header. Without the header, /mcp responds 401, and the agent simply will not see the tools.

Either of the two headers works — the server accepts both:

X-Api-Token: <токен>
Authorization: Bearer <токен>

Three things people stumble over:

• ASCII only. HTTP headers are encoded in latin-1, a Cyrillic token will not get through them. Generate like this: python3 -c "import secrets; print(secrets.token_urlsafe(32))".

• The client gets API_TOKEN, not ADMIN_TOKEN. The admin one will also be accepted, but the client config goes into git and backups: a leaked read token gives viewing, a leaked admin one — the right to delete sources.

• stdio requires no token at all. There the client starts the process itself, the network is not involved and there is nothing to check. If the client cannot set headers — this is a working workaround.

To check that the server sees the token, before any client setup:

curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  -H 'x-api-token: ВАШ_ТОКЕН' \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  http://localhost:5001/mcp

200 — the token is accepted. 401 — wrong token or the header did not get through.

How not to commit a secret

.mcp.json and similar files usually live in the repository. Options:

1. Variable substitution — if the client supports it (Claude Code does): "X-Api-Token": "${MCP1C_API_TOKEN}", and the variable itself in ~/.zshrc. What goes into git is the variable name, not the value.

2. Move the file out from under git: git rm --cached .mcp.json && echo ".mcp.json" >> .gitignore.

3. Keep the setting not in the project but in the client's user config — then the repository is not involved at all.

Claude Code

The file .mcp.json in the project root:

{
  "mcpServers": {
    "1c": {
      "type": "http",
      "url": "http://localhost:5001/mcp",
      "headers": { "X-Api-Token": "${MCP1C_API_TOKEN}" }
    }
  }
}

The headers block is needed only if API_TOKEN is set on the server. The value is taken from an environment variable so the file can be kept in the repository:

echo 'export MCP1C_API_TOKEN=ваш_токен' >> ~/.zshrc && source ~/.zshrc

Or by command:

claude mcp add --transport http 1c http://localhost:5001/mcp \
  --header "X-Api-Token: $MCP1C_API_TOKEN"

Codex CLI

~/.codex/config.toml or .codex/config.toml in the project:

[mcp_servers.mcp1c]
url = "http://localhost:5001/mcp"

# Только если задан API_TOKEN. Имя ключа для заголовков у Codex менялось между
# версиями — сверьтесь со своей (`codex --help`, раздел MCP). Не подхватилось —
# используйте stdio, там токен не нужен вовсе.
[mcp_servers.mcp1c.http_headers]
X-Api-Token = "ваш_токен"

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "1c": {
      "type": "streamable-http",
      "url": "http://localhost:5001/mcp",
      "headers": { "X-Api-Token": "ваш_токен" }
    }
  }
}

VS Code (Copilot)

.vscode/mcp.json — here the key is called servers:

{
  "servers": {
    "1c": {
      "type": "http",
      "url": "http://localhost:5001/mcp",
      "headers": { "X-Api-Token": "ваш_токен" }
    }
  }
}

Qwen Code

The format is from Gemini CLI, and the key chooses the transport — this is the only subtlety:

{
  "mcpServers": {
    "1c": {
      "httpUrl": "http://localhost:5001/mcp",
      "headers": { "X-Api-Token": "ваш_токен" }
    }
  }
}

httpUrl — streamable-http, our case. url in this format means the old SSE transport: the client will start the handshake with GET /mcp, get 400 Missing session ID, and will not connect.

Other clients

Windsurf, Antigravity, Cline, Roo Code, console agents — the record format is the same: transport type, URL, and, if API_TOKEN is set, a headers block. The differences are only in the file name and in the top-level key (mcpServers or servers) — check the documentation of the specific client.

The client cannot set headers — not a dead end: connect via stdio, where no token is needed because there is no network.

Local launch via stdio

When the client must start the server itself. No token is needed here: the process is started by the client, communication goes through the process channels, not through the network — there is nothing to check and nothing to defend against.

{
  "mcpServers": {
    "1c": {
      "command": "python3",
      "args": ["-m", "mcp1c.server", "--transport", "stdio", "--data", "/путь/к/data"],
      "env": { "PYTHONPATH": "/путь/к/проекту/src" }
    }
  }
}

3. Tools

The set is fixed and deliberately small: each tool constantly hangs in the agent's context. A new tool appears only for a separate user task, not for every internal index.

config is required when more than one configuration is loaded: the server deliberately does not fill it in silently — otherwise the agent would write code against someone else's database without anyone knowing.

list_configurations shows the actual state of the code index for the main configuration and each extension: ready, building with stage and progress, error, or code not loaded. For a ready extension it outputs the number of overlaps across the four annotations, the count of affected modules and own procedures, and a ready extension parameter for addressing its code. A ready corpus with an unknown or corrupted variant is called the "ready with restrictions" state. All three shells receive exact aggregates of a single generation but display them according to their own task. list_configurations and reg-list keep detailed diagnostics: categories, the first 20 problems in stable order, and the exact count of the remainder; for an unaddressable candidate only the ordinal number is output, without the physical name and local path. /sources instead of an address feed shows three cross-checkable tables with count, percentage, and explicit denominator: modules and procedures, form structures, form modules.

The full list of each corpus is atomically stored in a single current file data/logs/code-<sha256 source_id>.json. The main configuration and each extension have different logs; a reload replaces only its own file, deleting a source removes its file. A log that is broken, from a different generation, or substantively diverging from the current indexes is not shown as current and is rebuilt from the ready indexes. Form structures separately show how many are fully, partially, and not read. The contract and invariants of schema v1 are described below. The warning stands above an incomplete answer and states directly: a zero counter does not prove the absence of hidden data.

Code coverage log — schema v1

One file belongs to one independently removable source <Configuration>:modules or <Configuration>:ext:<Extension>. The source name is not included in the path: the file is named by the full sha256 source_id.

{
  "schema_version": 1,
  "kind": "module_coverage",
  "source": {
    "id": "Отраслевая конфигурация:modules",
    "kind": "modules",
    "sha256": "...",
    "loaded_at": "2026-08-24T12:00:00+00:00",
    "selection_version": 4,
    "locator_generation": 3,
    "code_version": "1.0.0"
  },
  "identity": {
    "source_id": "Отраслевая конфигурация:modules",
    "source_sha256": "...",
    "generation": 3
  },
  "coverage": {
    "modules": {
      "total": 2,
      "source_available": 1,
      "empty": 0,
      "partial": 0,
      "unreadable": 0,
      "conflict": 0,
      "compiled_without_source": 1
    },
    "procedures": {"total": 1, "full": 1, "partial": 0},
    "form_structures": {
      "total": 1, "full": 0, "partial": 1, "unavailable": 0
    },
    "form_modules": {
      "total": 1, "read": 1, "empty": 0, "missing": 0, "unreadable": 0
    },
    "limitations": {
      "categories": {"compiled_without_source": 1, "unknown_marker": 1},
      "occurrences_total": 2,
      "problem_rows_total": 2,
      "unknown_markers": 1,
      "known_markers_incomplete": 0,
      "unsupported_addresses": 0,
      "broken_containers": 0,
      "unreadable_bodies": 0,
      "budget_exceeded": 0,
      "body_conflicts": 0,
      "compiled_without_source": 1
    }
  },
  "problems": [
    {
      "category": "unknown_marker",
      "address": "ОбщаяФорма.Пример",
      "ordinal": 0,
      "reason": "маркер form не поддержан",
      "marker": 99
    },
    {
      "category": "compiled_without_source",
      "address": "ОбщийМодуль.Пример",
      "ordinal": 0,
      "reason": "скомпилированный модуль без исходника",
      "marker": null
    }
  ]
}

The categories modules, procedures, form_structures, and form_modules must in total equal their total; both form tables have one denominator; problem_rows_total equals the length of the full problems. address is null if a canonical address cannot be proven, in which case ordinal is the deterministic candidate number. marker stores the read marker of a form structure or null if the problem does not relate to it. identity links the log to the sha256 and generation of the locator catalog.

The file never contains absolute paths, raw exceptions, tracebacks, tokens, BSL bodies, or the raw form record. The catalog is opened without following a symbolic link; a temporary file is created inside it and atomically replaces the final one. A write failure does not cancel the corpus readiness.

get_object adds code information depending on detail: on brief it does not call the code provider, on fields it gives one line with counters, on full it lists the modules and all forms of the object without their contents. A form remains visible by any evidence: a standalone XML descriptor, Form.xml, Form.bin, a flat .Form, or a single form module. If the index is building, finished with an error, or not loaded, the object metadata is still returned together with the honest code state. get_related marks related objects whose procedures are actually overlapped by any loaded extension; an extension's own procedure does not create such a mark. On fields and full the object card lists, without a common limit, the reasons related to its forms, so an unread form does not turn into a false "no forms". The procedure and relation tools also place a warning above a partial result; a generation change repeats the entire answer together with counters and problems.

search_procedures combines two levels. An exact name match finds any procedure, including non-exported ones; search by words, inflections, and the header comment works only on exported ones. At each level limit is set separately and must be an integer from 1 to 50. The response includes the address Module::Name, the signature from disk, export status, line number, the number of confirmed call sites, and a separate counter of same-name sites whose target could not be resolved. The boolean index of the extension annotation is called neutrally: it does not pass off &After or &Before as a full overlap of the original procedure. Signatures and bodies are not kept in memory. Hierarchical .bsl, flat .txt, and the module record of the source containers Form.bin/.Form go through the same lexer; search and the subsequent card use a locator of one generation rather than reconstructing the path from the address.

Without scope the search is global. An explicit scope="Document.CashReceipt" raises all modules of the object, and scope="CommonModule.CommonPurpose" or another exact address — a single module; the rest of the results stay below. The scope is not guessed from query. extension selects exactly one loaded extension; without it the search runs only over the main configuration.

get_procedure accepts an exact address from the search. A module address without :: returns a table of contents without bodies; Module::Name — the signature, compilation context, and body. start_line starts at 0, lines must be an integer from 1 to 200; a long answer contains a ready call for the next window without skipping lines. For the selected extension, &After, &Before, and &Instead show its body; &ChangeAndControl — the body of the main configuration and only the verbatim #Insert/#Delete blocks. The tool warns about other loaded extensions above the body but does not mix their code into the answer. Signatures and bodies are read from disk for a single answer and do not remain in memory. The same locator survives the cache and a restart: if the source is replaced during reading, the entire answer is repeated against the new generation, and parts of two generations are not mixed.

get_callers accepts only an exact Module::Name address. First it groups confirmed call sites by module and names the owner procedure, then shows event subscriptions and scheduled jobs from the metadata graph, after them — the form item and event from Form.xml. limit must be an integer from 1 to 50; after truncation the exact numbers of sites and modules remain. A descriptor or container record by itself does not prove the absence of a handler: with unproven positional semantics the tool reports partial coverage. The Form.xml status is stored separately, so intact XML bindings remain available even with a defect in a neighboring container. Calls to a same-name procedure without a resolved module are output separately and are not attributed to the requested address. If two procedures lie on the same physical line, the owner is not guessed. The tool does not read module texts. An empty answer reminds that string calls through Execute, DescriptionOfAlert, and ConnectWaitHandler are not indexed.

What the provider does not know

• Word search runs only over exported procedures. A non-exported one can be found by exact name or through the table of contents of a known module.

• Dynamic calls where the name is passed as a string to Execute, DescriptionOfAlert, or ConnectWaitHandler are not indexed.

• A compiled common module has no available source: the address itself is visible, but not the procedures, calls, signatures, and bodies inside it.

• In the container structure Form.bin/.Form, including the flat export, the bracket grammar and the root markers 19, 20, 23, 25, 26, 27 are proven so far, but not the purpose of the positional fields. Therefore such a form is visible as partially read, and its attributes, items, and events are not guessed. The full composition and bindings are still available only from Form.xml; the XML descriptor separately gives the UUID, name, synonym, and form type.

• A same-name call that is not resolved to an exact module is not attributed to the requested procedure and is shown separately.

One name can live in two domains at once: StrFind exists both in the platform (since 8.3.6) and in the query language. Then get_syntax lists same-name entries with a ready address for each, and the call can be repeated with a string from the output:

get_syntax("СтрНайти")                    → Одноимённых элементов: 2
                                            - `Глобальный контекст.СтрНайти` — Метод, с 8.3.6
                                            - `Запрос.СтрНайти` — Функция запроса
get_syntax("Запрос.СтрНайти")             → карточка функции языка запросов

The Query. qualifier is needed because a query language element has no owner: it cannot be named via Object.Member like a platform one.

Call order — and what is lost if it is violated

list_configurations
├─ search_objects → get_object → get_related
├─ search_procedures → get_procedure → get_callers
└─ search_syntax → get_syntax

In the code chain each step adds information that the previous one lacks. Without search_procedures you need to know the exact address in advance and lose search by purpose and scope. Without get_procedure the signature, compilation context, procedure body, and exact extension semantics are not shown. Without get_callers there is no check of the direct consequences of an edit: confirmed call sites, metadata bindings, and form events.

The get_object step must not be skipped. Search returns only names and counters; everything the code depends on lives in the object card:

• the type and periodicity of the register. SliceLast exists only for a periodic information register, and non-periodic ones are 566 of 603;

• ready field names of virtual tables. In a query the resource Quantity is called QuantityRemainder, QuantityTurnover, QuantityReceipt — such names are not visible anywhere in the configurator; the platform generates them;

• the subconto limit, correspondence, schedule resources — without them there is nothing to name fields like SubcontoDt1;

• unlimited-length strings. Marked directly in the type: String (unlim. — only via SUBSTRING) versus String(200). Such a field cannot be placed in a query as is — the platform will not let it be compared, grouped, or ordered. Such fields make up 23% to 38% of string fields in live configurations, so on cards where they occur (2,474 of 20,522), before the field list a disclaimer with a recipe is printed.

A query written right after search_objects looks correct and fails with "field not found". An example of what comes only from get_object:

## Таблицы запроса
- `РегистрНакопления.ТоварыНаСкладах.Остатки`
  измерения: Склад, Номенклатура, Характеристика
  ресурсы: КоличествоОстаток, РезервОстаток

A second one like it — and it was found by a live miss on 2026-08-18. The agent grouped the query by an unlimited-length string; we returned correct data, but the difference was readable only by the absence of the number in parentheses:

> **Строки неограниченной длины** помечены `(неогр.)`. Платформа не даёт их
> сравнивать, группировать и упорядочивать и не пускает в РАЗЛИЧНЫЕ,
> ОБЪЕДИНИТЬ и агрегатные КОЛИЧЕСТВО, МИНИМУМ, МАКСИМУМ. Ограничивайте
> длину — одинаково в списке выборки и в группировке:
>
>     ПОДСТРОКА(КодСкидки, 1, 100) КАК КодСкидки
>
> Длину подбирайте по смыслу поля: 100 — не универсальное число.

## Реквизиты

- `КодСкидки` — Строка (неогр. — только через ПОДСТРОКА) // Код скидки
- `КодМаркировки` — Строка(200) // Код маркировки

The caveat appears both in the note and in the field's own row, and that is not redundancy. The first revision printed the caveat as the last paragraph of the card. A live agent on 2026-08-18 called get_object with detail=fields, received it in full — and still grouped by that field. The caveat sat 721 tokens after the field row, and the decision is made where the name is copied. The same lesson had already been recorded on tool descriptions: a rule works where it is read, not where it is tidiest to put it.

Each prohibition has been verified: aggregate ones — a quote from the help, the other five — runs against a live database with recorded error texts. The help knows about the restriction in only three aggregate functions out of six and says nothing about grouping, ordering, DISTINCT, UNION, and comparison — meaning an agent that honestly read it could not have learned about it. The breakdown by origin is in docs/data-sources.md, section "Caveats in the card".

Before calling a platform function on an old configuration — get_syntax. What is unavailable is flagged, and the replacement recipe, if recorded, sits right there.

Sources are independent

There are five of them, and each is attached separately:

Query language is a separate source

shquery_ru.hbk from the same platform installation directory. 127 pages: 52 functions, 67 keywords, 8 articles. It loads like a regular source and lands in the same search index as the platform help — no separate tool is needed to search it, search_syntax finds both.

There are no versions in the file itself — verified across all 129 pages: zero mentions of "8.3.x" and "as of version". But the query language does change: release 8.3.20 added 25 functions, among them StrFind, Left, Right, InReg, NReg, StrReplace, Round, Int, and all of trigonometry.

There is nowhere to take the version from: the platform help does not describe query language functions at all (SUBSTRING — zero matches across 25,511 items). So versions are set by the curated table query_versions.py — based on 1C's list "Functions added to the query language as of release 8.3.20". The remaining 27 functions get no version: they have always existed.

The usual filter then applies: a configuration on 8.3.5 will not see these functions, one on 8.3.23 will.

The table is verified against data — by comparing two help files from different platforms. What is absent in the old one and present in the new one appeared in between, and it must have a version:

python3 tools/lab/compare_query_help.py <старая.hbk> <новая.hbk>

Run on 2026-08-19, 8.3.5.1570 against the current one: 29 appeared, 29 covered, 0 false positives. A false positive is the worst kind of error: an item that was already in the old help but is marked with a version will hide from a configuration where it exists.

There is one instance per server: a repeated load replaces the previous one.

Page tables are displayed but not searched. In this help, table cells are marked up as paragraphs inside <TD>, and without separate parsing the card printed a table as a column of values: "Product / Quantity / Number / Plumbing / 104 / …" two dozen rows in a row. Now tables are parsed into a separate field — 51 tables across 31 of 127 pages — and printed in their places in the text: a page with two examples shows each result under its own example. Table contents do not enter the search index.

The tables in this help are of two different natures and are parsed differently:

They differ by markup, not by CSS class: class=SimplyTable is not on all of them — 7 real tables go without it. The distinguishing feature is geometry: in a data table all rows have the same width, in a diagram the widths are ragged and there are cells made of a single vertical bar (that is a drawn line, not a value).

Corrupted markup is named out loud. A page with an unclosed <TABLE> is parsed without tables but is not lost, and its name lands in the source's warnings: as a line in the load output (mcp1c.cli reg-add) and as a separate line on the "Sources" page of the dashboard. Silently handing out a card poorer than usual is not allowed: that would be indistinguishable from help that simply does not have it.

Half the names match platform names (57 of 127) — YEAR, MONTH, REPRESENTATION exist in both. So that a question about a query does not lead to a platform method, phrasings like "in a query", "in the query text", "in a selection" give query language items a soft boost. Soft on purpose: with a confident lead, the platform item stays first — "how to set a parameter in a query" can also be about Query.SetParameter.

The config parameter is mandatory if more than one configuration is loaded. Nothing is substituted by default: a silent choice leads to the agent writing code against someone else's configuration, and nobody notices.

The answer depends on the platform version

The same call, two configurations:

get_syntax("СтрШаблон", config="Розница")     → 8.3.23
# Метод: Глобальный контекст.СтрШаблон
с версии платформы 8.3.6
Доступность: ТонкийКлиент, ВебКлиент, Сервер, ТолстыйКлиент, …

get_syntax("СтрШаблон", config="Отраслевая")  → 8.3.5
# `Глобальный контекст.СтрШаблон` недоступен в этой конфигурации
Элемент существует, но появился в 8.3.6, а конфигурация работает на 8.3.5.1570.
Использовать нельзя — код не скомпилируется.

For platform 8.3.5, 6,539 items were removed from the output, for 8.3.23 — 874. Not by warning but by filtering: the agent will skip a warning, but a method absent from the output — no.

The Availability field (server / thin client / web client / mobile) must be read: calling a server method from a client context does not compile.

Help files of several versions merge into one index

A single fresh help file on an old configuration lies. Measured on 8.3.5: 199 items the server would declare nonexistent, 117 it would return with a foreign signature (XMLWriter.OpenFile on 8.3.5 takes two parameters, on 8.3.27 — three), 410 — with foreign availability. All of these are compilation errors, not inaccuracies.

So help files of different versions are placed side by side and merged into one index with since and until boundaries, and the answer is assembled for the version of the specific configuration. You need as many help files as there are platforms among the loaded configurations — two extreme ones do not replace the intermediate ones.

The cost is measured and small: merging three versions yields 25,691 keys versus 24,777 for one, that is, less than a percent. A separate container per version also works and remains the fallback path, but as the primary one it lost on the numbers — 300–450 MB and its own address for each version.

The server itself names which help files are missing and which are extra — in the list_configurations output.

Replacement instead of prohibition

Saying "the function does not exist" is half the answer. The other half is what to replace it with, and that cannot be derived from the help: the deprecation mark sits on 15 pages out of 25 thousand.

So there is a replacement table (replacements.py), currently 6 entries — string functions that appeared in 8.3.6. Instead of a prohibition, get_syntax returns a recipe:

get_syntax("СтрРазделить", config="Отраслевая")   → 8.3.5
# `СтрРазделить` недоступна: появилась в 8.3.6

Замена: РазложитьСтрокуВМассивПодстрок(<Строка>, <Разделитель>)
Оговорка: разделитель у `СтрРазделить` — набор символов, каждый из которых
самостоятельный разделитель; у замены это одна строка целиком.

The caveat is mandatory. A replacement is almost never equivalent, and silently slipping in a similar function is worse than suggesting nothing.

The table is filled from live cases, not blindly: inventing workarounds for functions nobody has asked about makes no sense.

4. Data management

Add a source

# в Docker
docker compose exec mcp1c python -m mcp1c.cli reg-add /data/bootstrap/Выгрузка.zip --data /data
docker compose exec mcp1c python -m mcp1c.cli reg-add /data/bootstrap/shcntx_ru.hbk --data /data

# без Docker
PYTHONPATH=src python3 -m mcp1c.cli reg-add Выгрузка.zip

Simpler: put a file in data/bootstrap/ — it will be picked up at the next start.

Configuration dump to files

The second kind of source is not metadata (СтруктураКонфигурации_*.zip) but the configuration dump to files itself: module and form code. The server builds and caches internal indexes of procedures, calls, and forms; search_procedures searches against the ready set. On a cache miss, the indexes are built in the background: tools that do not depend on code keep responding, while code tools show stage X/4 and the actually processed N of M items of the current stage. The ready set is published as a whole, without an intermediate state from different versions. Background building does not overwrite registry.json while startup is still restoring the next sources. If startup terminated abruptly, the previous full snapshot on disk remains intact; a partially restored source list is not saved on top of it.

Four expendable cache files keep safe locators, coverage aggregates, and the first 20 anonymized problems with the exact count of the rest. Module bodies, procedure signatures, and the raw form record do not go there. On a warm start, the source's sha256, the selection version, the locator generation, each index's internal invariants, and their consistency with a single directory are checked. Therefore a structurally or semantically damaged set counts as a miss as a whole, not as a source of a partially stale answer. A damaged or read-only cache does not bring the source down: the server performs a cold rebuild in memory and publishes full diagnostics, even if the new cache cannot be written. Published cold and warm answers match on all counters and reason categories. Local reasons for each form are stored separately from the limited list: thanks to this, get_object after a restart shows all form problems of the selected object without turning the general /sources into an unlimited response. The reader does not read a cache file larger than 256 MiB and does not unpack a payload larger than 512 MiB; exceeding either limit is an ordinary cache miss before marshal.loads, not an attempt to exhaust memory.

Final live acceptance of selection v4 was completed on 2026-08-21 on four anonymized code sources (three main exports and one extension):

PYTHONPATH=src .venv/bin/python \
  tools/lab/measure_modules_acceptance.py --data data --timeout 120

The script prints a single JSON without names or paths. Warm startup took 3.676 s, startup_problems_total = 0, process peak — 856.2 MiB. The catalog proved 8,650 hierarchical .bsl files, 828 modules from Form.bin, 1,523 flat .txt files, 1,079 modules from .Form, and 7 compiled modules without source. 6,150 forms were found: 3,331 fully, 1,330 partially, and 1,489 not read. Exact constraint categories: descriptor_only=671, invalid_syntax=1598, known_marker_semantics_incomplete=659, form_structure_missing=561, compiled_without_source=7; there are no unknown markers, budget overruns, broken containers, or conflicts in this corpus. Zero here is the result of measuring precisely these sources, not a promise of support for any future format.

Previous background responsiveness measurement on 2026-08-21 on a cold cache of three code sources: in 72.12 s, 73 one-second calls of each path were made, no failures. This timer starts after /health readiness, whereas the container measurement of 125 s below goes from container start to ready of all code sources. /health responded with a median of 5.76 ms and a worst time of 171.01 ms; the real search_objects — 8.11 and 172.49 ms respectively. The container reached healthy, all 12 cache files were published. To repeat, mount a copy of data/ without index/cache/*.modules-* into a separate container and run:

.venv/bin/python tools/lab/measure_background_responsiveness.py \
  http://127.0.0.1:5002 /путь/к/копии/data

Memory of the final image was re-measured on 2026-08-21 after selection v4: four code sources and 16 module index cache files. Cold startup after removing only the expendable cache took 111.216 s, warm restart of the same container with unchanged dev, ino, size, and mtime_ns of all 16 files — 11.495 s.

Both times the container reached healthy; restart_count = 0, oom_killed = false. In each of the two final runs there were exactly 0 lines with each of the terms traceback, exception, critical, and error. cgroup values include the kernel page cache, so they naturally differ from the process RSS and the docker stats reading. This is a reference point for the size of precisely this corpus, not a basis for assigning mem_limit.

The script prints a single JSON with only aggregates: duration, number of sources and caches, cgroup and PID 1 fields, docker stats, health, restarts, OOM, and journal term counters. Source names, local paths, and journal lines are not printed. In cold mode it builds the final image, first stops the container, and removes only the exact files modules-toc, modules-calls, modules-forms, and modules-search, computed by the working name function for the current sources. The index/cache directory and the targets themselves cannot be symbolic links; an extra or mixed set of names is not considered ready. After stopping, the directory is opened with O_NOFOLLOW, and its dev/ino are verified against the initially checked directory. Targets are listed and verified via dir_fd; only exact base names are removed through the same descriptor: replacing the parent with a symbolic link does not lead outside, and a hard link loses only the internal link. Then the script does --force-recreate. The measurer itself does not remove or replace sources, unpacked code, or registry.json. A running server routinely atomically updates registry.json states during startup and background build; the measurement accounts for these records in the generation marker. Readiness requires not only healthy, but also unchanged sha256, loaded_at, and the binding of the code source itself, the same sha256 of the owner configuration, the ready state, and the exact set of four caches per source. On a normal restart, configuration metadata is parsed again and gets a new runtime loaded_at; the measurer allows only this transition, and then requires two identical snapshots of the new generation. After reading memory, docker stats, and the journal, the final check reads the registry, then the cache, and again the registry; both markers must match the ready generation. The marker also includes dev, ino, size, and mtime_ns of registry.json itself, so even writing the same bytes counts as a new generation. In warm mode, before stopping, it remembers dev, ino, size, and mtime_ns of each exact cache file. Immediately after docker stop, before docker start, it reopens the directory with O_NOFOLLOW, verifies its dev/ino and the entire file snapshot through the held dir_fd; the same snapshot is required at readiness and in the final check. A rebuild, overwrite, or corruption of a file invalidates the entire result. --timeout and --poll-interval are finite positive seconds; the single timeout remainder limits each Docker command.

.venv/bin/python tools/lab/measure_container_memory.py --mode cold --data data \
  --timeout 300 --poll-interval 0.5
.venv/bin/python tools/lab/measure_container_memory.py --mode warm --data data \
  --timeout 300 --poll-interval 0.5

The extension export is placed in the same place, in data/incoming/, and is parsed with the same button. The server determines the export type itself, by Configuration.xml inside the archive — the person still selects only the configuration to which the extension is attached, not a separate button or an "this is an extension" field. The extension is created as a separate source <ConfigurationName>:ext:<ExtensionName> (type extension), not <ConfigurationName>:modules: the extension name is taken from the Name tag of its own export, not invented by a person. The code goes into its own directory data/extensions/<ConfigurationName>/<ExtensionName>/ — next to data/modules/<ConfigurationName>/, but not inside it, so a second export does not erase the first. A single configuration can have any number of extensions — while configuration modules still have exactly one export, as before.

The extension's identity is the Name tag inside its export, not the file name and not the entire content. A person can rename the archive however they like: two files with different names but the same Name re-parse ONE and the same source — the second parse simply updates the code and origin (the name of the last parsed file); the key and directory do not change. The flip side of the same rule: if the Name of two DIFFERENT extensions, after cleaning of characters invalid for a path, coincides (for example, Price/Retail and Price:Retail produce the same directory name), they too collapse into one source — the second parse overwrites the code of the first. For ordinary names (without characters outside letters, digits, hyphen, underscore, period, and space), cleaning changes nothing and such a collision does not occur.

Recognition is a positive rule on both sides, and the check order matters. Erring in favor of a configuration is more dangerous: it means going into the modules branch and destroying the already parsed configuration code entirely. Therefore, first they look at strong extension indicators (ObjectBelonging, ConfigurationExtensionPurpose) — if at least one is visible, there is no path to the modules branch under any CompatibilityMode: then the decision is only between "extension" (all four conditions met: both strong indicators, non-empty NamePrefix, absence of CompatibilityMode) and rejection. And only when there is no strong extension indicator at all does CompatibilityMode decide: non-empty — configuration, empty or tag absent — rejection. Everything else is also a rejection with an explanation, without touching anything on disk: Configuration.xml was not found (searched not only in the archive root, but also in the single top-level directory — this is how an archive is built with the zip -r archive.zip folder command, and the service __MACOSX/ with .DS_Store of a Finder archive on macOS does not interfere), cannot be read (broken CRC, truncated record), does not parse as XML, does not carry a recognizable structure, or the declared file size is implausibly large.

Where to put it. In data/incoming/, on the disk, not through the upload form on "Sources" — it has no field for this. The server itself creates the directory at startup, so it is in place from the first run. Then on the "Sources" page (only for someone logged in under ADMIN_TOKEN), an "Incoming exports" block appears with a "parse" button.

Only the directory itself is scanned, without nested subdirectories. An archive placed in data/incoming/Retail/ will not be seen by the server — and it will not say anything about it, because there will be nothing to show.

While the file is being copied, there is no button. cp of one and a half gigabytes takes minutes, and the file is visible in the directory from the first second: for an archive modified less than five seconds ago, the state is shown with the note "file is still being copied", sha256 is not computed at all (it would be outdated anyway), and parsing such a file is rejected with an explanation. Wait for the copy to finish and refresh the page.

Re-parsing overwrites the entire directory — but only after success. For an updated export, the button is labeled "re-parse": the old contents of data/modules/<ConfigurationName>/ (or the extension directory) are replaced with the new one entirely, otherwise files that are absent in the new export (a deleted object, a renamed module) would remain there forever and the two exports would mix. Unpacking goes into a temporary directory nearby and does not affect the previous parse: if extract fails midway (broken CRC of a module, disk full, permissions) or selects zero files, writing to the working directory never happens at all — the registry and disk do not diverge. The replacement is not a teardown of the old in place, but a swap ("rename old aside → rename new into its place → remove the set-aside"): if moving the new into the old's place fails, the server tries to return the old to where it was. If that also fails (the nature of the failure of both renames is usually the same — permissions, the same bind-mount), the parse fails explicitly and names both paths in the text: where the previous parse physically lies and where the empty or partially unpacked new one is, so the directory can be restored by hand; the server will not silently show "parsed" for a directory that does not exist. Remnants of a process interrupted midway (.tmp-*) are removed before the next parse of the same configuration or extension — the saved copy of the previous parse (.old-*), if it came to that, is not removed by itself: the decision about it is left to the person. Re-parsing does not change directory permissions — the new directory gets the permissions of the previous one (or the usual ones, if the directory did not exist yet), not the reduced ones with which the temporary one is created.

Concurrent parses of one source are executed sequentially: a new request immediately cancels the previous generation, but waits for its work with the temporary directory to finish. Therefore, one parse cannot delete another's active .tmp-*, and the working directory and cache are received only by the last generation. A cancelled request ends with an explicit error; a waiting stale request does not start unpacking at all. Different configurations and extensions with different source keys do not delay each other.

"Selection is outdated" — a state for when it's not the file that changes, but the rule. Every parsed source remembers the version of the selection rule (internal SELECTION_VERSION: what we take from the archive and where we put it). If the code on disk was parsed with an old version of the rule, the source is shown as "selection outdated" rather than "parsed" — even though the archive on incoming/ is the same file with the same sha256. The button is labeled "re-parse", as with an updated export: the code on disk is overwritten anew, this time according to the current rule. The previous parse itself is not rewritten — a person sees the selection rule change only after pressing the button. A source parsed before this field existed (a record without selection_version in the old registry.json) is also considered outdated: its version is unknown, not "definitely fresh" — otherwise a person would never see "re-parse" for code that never went through the current rule. The current version 4 preserves XML form descriptors and hierarchical Ext/Form.bin; a version 3 source is therefore necessarily shown as outdated and receives these files only after an explicit re-parse. The selection version is part of the cache stamp: an old cache is not accepted even for the same unchanged ZIP. Before replacing the directory, the server writes a short rotation log; after an emergency stop, the next launch reads registry.json and either completes the new generation or restores the previous directory.

Finder archiver junk on macOS does not get into the code. An archive assembled with the "Compress Objects" command carries a service __MACOSX/ with copies of each file's resource forks (._Name, the same suffix as the original) — selection skips them, as it does any name starting with ._, wherever it lies.

The archive wrapper is not reproduced in the path on disk. An archive packed with the zip -r archive.zip folder command or via Finder ("Compress Objects") — the entire export lies inside a single top-level directory — does not repeat that level when laid out on disk: the code goes to data/modules/<ConfigurationName>/Catalogs/…, not data/modules/<ConfigurationName>/folder/Catalogs/…. The wrapper recognition rule is shared with the search for Configuration.xml inside it (the same place in the paragraph above, "Recognition"): the service __MACOSX/ and the root .DS_Store do not count, and several top-level directories are not considered a wrapper — the server will not guess which of them is "the one". Path sanitization (refusing members that lead outside the root) is applied after unwrapping, not instead of it.

Deleting a source takes the code with it. The "delete" button on a <ConfigurationName>:modules source removes data/modules/<ConfigurationName>/, and on an extension source <ConfigurationName>:ext:<ExtensionName> — only its own directory data/extensions/<ConfigurationName>/<ExtensionName>/: configuration modules and other extensions of the same configuration are not touched. Otherwise hundreds of megabytes would remain occupied invisibly: they are not shown in the "Source files" section, which only has data/sources/.

An archive in which neither modules nor forms were found is rejected. A metadata structure export is also a .zip, and without this check it would create a source with zero files in the "parsed" state. It is submitted via the "Upload" form on this same page.

Why not through the browser. The archive weighs over a gigabyte — for the typical retail sales configuration 2.3.10.5 that is 1,380 MB. The upload form on "Sources" is built for metadata in the range of a few megabytes and fails on such a file for three reasons at once: the upload limit of 500 MB; triple copying with a peak of about 4 GB — the request body receive buffer, a temporary copy in mkdtemp(), and a copy onto the volume itself; and the transfer itself of over a gigabyte over HTTP with no way to resume after an interruption. A file on the volume bypasses all three limits: it is copied with an ordinary cp, and the server reads the archive member by member, never unpacking it in full.

What remains on disk. Not the whole archive — only modules (.bsl for a hierarchical export, .txt and canonical compiled CommonModules/<Name>.Module or CommonModule.<Name>.Module for a flat one) and forms: the XML descriptor, Form.xml and Form.bin for hierarchical, the .Form container in its entirety for flat. Form.bin and .Form are preserved unchanged as a source for the code provider; a derived .bsl is not created on intake. Text templates *.Template.txt are not accepted as modules. The container is saved as is, together with the binary form record: the code of a regular form lies inside it as a module record, and parsing the container on intake would mean dragging 1C format parsing in here.

After unpacking, the physical tree is enumerated once into an immutable catalog of canonical addresses and safe locators. The table of contents, calls, forms, and search all get the same snapshot: ordinary .bsl/.txt files are read as files, Form.bin/.Form code — as the module record of the original container, a compiled .Module remains an address without an invented body. Identical texts of one address are deduplicated after common normalization; different ones do not get silent priority and are excluded as a conflict.

Configuration code goes to data/modules/<ConfigurationName>/, extension code — to its own directory data/extensions/<ConfigurationName>/<ExtensionName>/; current coverage logs — to data/logs/. All three kinds are protected by the **/modules/, **/extensions/, and **/logs/ rules in .gitignore. Measurement python3 tools/lab/measure_intake.py <archive>..., run 2026-08-19:

A live run of the intake itself on the same files — not an estimate from the zip directory, but a real call to intake.planned_size, intake.enough_space, and intake.extract, measurement python3 tools/lab/measure_intake_run.py <unpack directory> <archive>..., run 2026-08-19: the required space estimate on a 1.4 GB archive — 0.15 s (only the zip central directory is read, the body is not touched at all), unpacking — 3.1 s, process RSS peak — 111 MB. The files and bytes returned by extract() and what actually landed on disk are equal in number — the script verifies this itself.

The server does not delete the source. The data/incoming/ directory is forbidden for the server to delete — the file stays in place even after a successful parse; a re-parse of the same archive does not touch it, verification goes by sha256 against the cache on the page (hashing a gigabyte on every list refresh is not possible).

A source is created under the key <ConfigurationName>:modules, not the configuration name: the same key as metadata would displace them from the registry on upload. Which configuration owns the export is decided by a person. If exactly one is loaded in the registry, no choice is needed: there is no field next to the button on the page, the parse takes the only one itself. If two or more are loaded, a dropdown of loaded names appears next to the button — whichever is selected, the code is bound to that one. The name from the form is verified against the list of loaded ones: an unknown one is rejected before the parse begins, with an explanation. Automatic binding by the export manifest (without human involvement) is not done yet. The platform of a module source is taken from the configuration it is bound to — the export itself does not contain an exact platform build in its files, only the compatibility mode, and that is a different number. For an extension, the configuration choice works the same way (see "An extension export goes to the same place" above); the export kind — modules or extension — the server distinguishes itself by Configuration.xml, there is no separate field or button for this on the page.

Lack of space — refusal before the start. After choosing the configuration and source kind, the registry checks the free space on the volume before unpacking. The required amount is the safely selected files plus an index reserve: 15% rounded up, but no less than 25 MB. The formula is the same for the first upload and a re-parse: the volume occupied by the old root is already excluded from the free space value, it cannot be added again. Not enough — the parse does not start, and the reason with both figures in megabytes stays on the "Sources" page and survives a restart. A direct registry call goes through the same check; on error or volume fill-up, the previous parse stays in place.

A compiled *.Module is visible in the summary and in the module list as CommonModule.<Name>, but it has no procedures or body: search_procedures, get_procedure, and get_callers say so directly and do not pass off an empty index as proof that a procedure is absent.

The "parse" button requires ADMIN_TOKEN — like any other write: without the token this route does not exist, not "it is closed".

Apply changes without a restart

A running server keeps the registry in memory, so after reg-add it needs a nudge. Either a restart (docker compose restart mcp1c, about 2 seconds), or the admin endpoint:

# включается переменной ADMIN_TOKEN; без неё маршрут отключён
ADMIN_TOKEN=секрет docker compose up -d
curl -X POST -H "x-admin-token: секрет" http://localhost:5001/admin/reload

Dictionary: how people speak versus how it is named

The main difficulty of search is the gap between a person's words and the names in the configuration. "Customer order" — but the object is called CustomerOrder. The dictionary lives in data/dictionary.json and is edited without rebuilding the image.

Two mechanisms, and they are different.

Word synonyms — common to all configurations:

python3 -m mcp1c.cli dict-synonyms клиент покупатель заказчик

Object aliases — a direct statement "when I say this, I mean these objects", weight higher than any textual match. Two dozen typical phrases ("files", "goods", "customers", "employees", "tasks") are built in and work right away; if the object is not in the configuration, the alias is not applied. Your own are added bound to a configuration:

python3 -m mcp1c.cli dict-alias "справочник физлиц" \
    Справочник.ФизическиеЛица Справочник.Пользователи \
    --config РозницаДляКазахстана

«справочник физлиц»
    Справочник.ФизическиеЛица     псевдоним из словаря
    Справочник.Пользователи       псевдоним из словаря

Object existence is checked on addition — an alias for a typo is useless. View the contents: dict-show, delete: dict-alias "phrase" --remove.

Changes are applied by restarting the container or POST /admin/reload — no need to rebuild the image. The reload runs outside the event loop, so /health and MCP requests keep being served during recovery.

Search keys of the query language — a third mechanism, and it is edited only in code (search_keys.py) with the usual change review. The gap here is of a different nature: a person does not call a construct by someone else's word, but describes the task. "Number of days between two dates" versus DATEDIFF, "remove duplicates" versus DISTINCT — zero common words, and a synonym will not help, there is nothing to replace.

That is why 116 pages out of 127 have phrasings attached by which they are asked, and they get into the search index as a separate field. At runtime they weigh nothing. Result on a live set: 57.9% → 94.7% first place, no regression on 61 thousand automated queries.

The keys are composed by us, not exported, and from this come three constraints:

• they live as a separate layer in git, not attached to a parsed element;

• they do not get into the response to the agent — the response is still assembled only from the help text, the keys work solely on hitting the right article;

• they are bound to pages by identifier, and if the help produces a different set of pages, the discrepancy is named at load time, not silently manifesting as a degraded search.

The whole rule is in docs/data-sources.md, section "Generated layers over sources".

See what is loaded

docker compose exec mcp1c python -m mcp1c.cli reg-list --data /data

РозницаДляКазахстана  2.3.10.5  платформа 8.3.23.1997
  объектов 5637, связей 44034, загружено 2026-08-18T12:22:16+00:00
  метаданные : да
  синтаксис  : справка 8.3.27, новее конфигурации, скрыто 874
  модули     : не загружен
  язык запросов: подключён, 127 страниц

There may be no configurations at all — the server still works in that case if at least one help is loaded: search_syntax and get_syntax answer, no config needs to be specified. reg-list in this case lists what is connected and returns 0:

Конфигурации не загружены. Подключено:
  язык запросов, 127 страниц
Работают search_syntax и get_syntax, без фильтра по версии.

On a completely empty registry — "Nothing loaded." and exit code 1. Any command that needs configuration will say right there what exactly is missing and where each piece comes from. reg-list does not wait for a cold build: for the main configuration and each extension it shows the same atomic state as /sources and list_configurations — ready counters, stage and progress, an error, or the absence of a code.

Debugging without an agent — mcp1c.cli

The CLI goes to the same registry and the same functions as the MCP tools. If it answers correctly, the problem is in the client setup, not the server.

Commands fall into three groups. Registry — the same thing the agent sees:

PYTHONPATH=src python3 -m mcp1c.cli reg-list  [--data data]
PYTHONPATH=src python3 -m mcp1c.cli reg-add   Выгрузка.zip     [--data data]
PYTHONPATH=src python3 -m mcp1c.cli reg-add   shcntx_ru.hbk    [--data data]
PYTHONPATH=src python3 -m mcp1c.cli reg-search "чек ккм"  --config РозницаДляКазахстана
PYTHONPATH=src python3 -m mcp1c.cli reg-search "разделить строку" --syntax --limit 5
PYTHONPATH=src python3 -m mcp1c.cli reg-search-procedures "провести документ" \
    --config Пример --scope Документ.Чек --limit 10
PYTHONPATH=src python3 -m mcp1c.cli reg-get-procedure \
    'Документ.Чек.МодульОбъекта::ОбработкаПроведения' \
    --config Пример --start-line 0 --lines 200
PYTHONPATH=src python3 -m mcp1c.cli reg-get-callers \
    'Документ.Чек.МодульОбъекта::ОбработкаПроведения' \
    --config Пример --limit 20

reg-search without --syntax searches by metadata; with it, by help text and the query language. Three code commands mirror the eponymous MCP tools and print the same response: reg-search-procedures QUERY accepts --config, --extension, --scope, --limit (default 10); reg-get-procedure ADDRESS — --config, --extension, --start-line (0) and --lines (200); reg-get-callers ADDRESS — --config, --extension and --limit (20). For all three, --data defaults to data. On a cold one-off run, these commands wait for the background build no more than 90 seconds, so the process does not terminate daemon threads before the result and the writing of four cache files. If the limit was not enough, the command returns an explicit error; the server does not use this wait and keeps showing progress.

Directly from a file, without the registry — inspect an export before it goes to the server:

PYTHONPATH=src python3 -m mcp1c.cli info    Выгрузка.zip
PYTHONPATH=src python3 -m mcp1c.cli stats   Выгрузка.zip
PYTHONPATH=src python3 -m mcp1c.cli show    Выгрузка.zip Документ.ЧекККМ --detail full
PYTHONPATH=src python3 -m mcp1c.cli related Выгрузка.zip Документ.ЧекККМ --depth 2
PYTHONPATH=src python3 -m mcp1c.cli find    Выгрузка.zip реализация --limit 10

The path is a ZIP or an unpacked directory; the format is determined by the manifest.

Search dictionary — synonyms are common, aliases are tied to a configuration:

PYTHONPATH=src python3 -m mcp1c.cli dict-show                       # правила и их происхождение
PYTHONPATH=src python3 -m mcp1c.cli dict-show --all --config Розница...
PYTHONPATH=src python3 -m mcp1c.cli dict-synonyms чек ккм касса     # группа взаимозаменяемых слов
PYTHONPATH=src python3 -m mcp1c.cli dict-synonyms чек ккм --remove
PYTHONPATH=src python3 -m mcp1c.cli dict-alias "справочник физлиц" Справочник.ФизическиеЛица
PYTHONPATH=src python3 -m mcp1c.cli dict-alias "справочник физлиц" --remove

dict-show shows the origin of each rule — that is where the analysis of "why search behaves this way" begins.

Search quality measurement — mcp1c.bench

A separate stand, because "it got better" without numbers is an opinion.

PYTHONPATH=src .venv/bin/python -m mcp1c.bench \
    --data data --config РозницаДляКазахстана \
    --auto --sets query-language,roznica-metadata,modules-procedures \
    --check-notes

Each manual JSON contains schema_version: 1, an explicit domain — syntax, metadata, or procedures — and a cases array. The file name does not select the index. In a procedure set, expected stores bare BSL names without module names; the stand expands the name case-insensitively into all exact addresses of the selected corpus. This allows publishing reproducible formulations without revealing the structure of a specific deployment. Optional expected_miss: true and zero-based expected_rank machine-verify the recorded baseline with --check-notes; this is not a pytest quality threshold. The old root JSON array and old baselines without a version are rejected explicitly: they need to be recreated. --save first atomically replaces the report file and only then prints results: a write error leaves no partial report either on disk or in stdout.

It prints P@1/P@3/P@5/P@10, MRR, the share of "foreign domain first", and the median gap between the first and second result. There are deliberately no thresholds in asserts: query sets are not tests, percentages would break on every dictionary edit. Exit code 1 means a note mismatch; code 2 means the entire measurement is canceled before printing and saving due to an invalid set, ambiguous selection, or an unready index. When the code changes during a procedure set, the entire set is repeated from the beginning on one index generation.

Comparing two runs looks like this (regressions first):

=== сравнение с прошлым прогоном ===
  - «как прибавить месяц к дате в запросе»: 1 -> промах
  - «как отсортировать результат запроса»: 1 -> 5
  + «в чем разница между внутренним и левым соединением»: 5 -> 4

Sets are not included in the image (tests/ in .dockerignore) — run from a working copy, not from a container.

Server manually — mcp1c.server

PYTHONPATH=src python3 -m mcp1c.server --data data          # streamable-http на :8000/mcp
PYTHONPATH=src python3 -m mcp1c.server --transport stdio    # локальному клиенту
PYTHONPATH=src python3 -m mcp1c.server --host 0.0.0.0 --port 5001

There are no other values for --transport. The legacy HTTP+SSE is fully disabled: the --transport sse flag is rejected before reading data and starting the server.

Where the source data comes from

Configuration structure — by processing from exporter-1c/. Four module variants for regular and managed forms, XML and JSON; XML variants are compatible with 8.3.5. Two processings are already built and open as is: ВыгрузкаСтруктурыКонфигурации_ОбычнаяФорма_XML.epf (8.3.5 and above) and ВыгрузкаСтруктурыКонфигурации_УправляемаяФорма_XML_JSON.epf (8.3.6 and above, the format is selected on the form).

Platform help — the shcntx_ru.hbk file from the 1C installation directory:

/opt/1cv8/<версия>/shcntx_ru.hbk
C:\Program Files\1cv8\<версия>\bin\shcntx_ru.hbk

The name must match exactly. The same directory contains hundreds of .hbk files — 38 different help systems, each in two dozen languages. Ones similar to the needed file:

They cannot be told apart by size: shcntx_root.hbk weighs 33 MB against 39 MB for the needed one. The _ru suffix is the language, _root is the common part without texts.

If the file is wrong, the server explains exactly why and leaves the previous help in place.

One help from the newest available platform is enough: each item carries an appearance version, and for old configurations the excess is filtered out. If the version is not in the path, it is derived from the data itself.

Help from old platforms is also accepted — it is marked up differently (sections on div instead of p), and that is accounted for. It is useful when standing up a separate server for old deployments: help from 8.3.5 gives 18,936 items and does not contain СтрНайти, СтрРазделить, ЗаписьJSON — which did not exist in 8.3.5. But such help does not report its version: there are no "starting with version" marks in it, because back then everything was current. Therefore the version is taken from the file or directory name — put it as 8.3.5.1570.hbk or in data/hbk/8.3.5.1570/, otherwise matching with the configuration will not work.

5. How it is structured

src/mcp1c/
  v8container.py     контейнер 1С — общий для .hbk, .cf, .epf
  syntax_parser.py   разбор справки платформы
  syntax_model.py    модель элемента справки, виды, границы версий
  syntax_merge.py    слияние справок разных версий в один индекс
  query_parser.py    разбор справки по языку запросов (shquery_ru.hbk)
  replacements.py    чем заменить функцию, которой нет в старой платформе
  virtual_tables.py  таблицы запроса регистров и имена их полей
  loader.py          чтение выгрузок, XML и JSON в одну модель
  model.py           модель конфигурации
  graph.py           граф связей
  graph_view.py      окрестность объекта для картинки на дашборде
  search.py          лексический поиск
  search_keys.py     формулировки, которыми спрашивают язык запросов
  synonyms.py        встроенный словарь: как говорят против того, как названо
  dictionary.py      локальный словарь поверх встроенного
  index_cache.py     кэш поисковых индексов, расходный
  modules_index.py   оглавление, вызовы и формы для get_callers
  store.py           чтение и запись разобранных справок
  render.py          markdown-карточки объектов и элементов
  intake.py          отбор и распаковка выгрузки в файлы, санитизация имён
  incoming.py        состояние data/incoming: кэш sha256, причина отказа
  registry.py        реестр источников, сопоставление версий
  tools.py           десять инструментов, без зависимости от MCP
  server.py          протокольный слой (единственная внешняя зависимость)
  dashboard.py       веб-интерфейс: реестр, запросы, словарь
  cli.py             отладочный CLI
  bench.py           стенд замеров качества поиска

One model for two formats. XML and JSON are different serializations of one schema; the loader reduces both to the same dictionary. Verified: both exports give the same set of 30 keys.

The graph is built by the loader, not by 1C. Edges are derived from attribute types, document movements, entry bases, owners, subscription handlers, and scheduled job methods. Rules can be changed without re-exporting.

Weak edges. Attributes like ЗначениеДоступа enumerate hundreds of types and connect almost everything to everything. Such links are marked weak and hidden by default — otherwise the useful ones drown in them.

Detail levels. A full description of Документ.ЧекККМ (50 attributes, 17 tabular sections) consumes the entire context. brief — a couple of lines, fields — the composition, full — with links.

No external databases. Production indexes stay in one process: compact code arrays respond without a separate network hop, and search takes 0.18–1.5 ms. Elasticsearch, a vector store, and a graph database do not pay off as a separate process and maintenance at this volume. Vector search would additionally require an encoder model (+185–620 MB to the image) and 16–32 ms just to encode the query.

Measured on real data — 2026-08-18

What is loaded on the working server:

The set is random — it is what happened to be at hand. What matters is not the configuration itself but the platform spread: 8.3.5, 8.3.23, and 8.3.27 in one registry, and each configuration answers according to its own.

Plus the platform help — a merged index of three versions (8.3.5, 8.3.23, 8.3.27), 25,691 items, and the query language — 127 pages as a separate source.

Warm start of the final image with 12 module index cache files — 19 s on the working corpus measured on 2026-08-21. On a cold start, sources are parsed, indexes are built and placed into data/index/cache/, parsed help — into data/index/syntax/. After that they are loaded from there.

The cache is derived and expendable: tied to the Python version, the package code fingerprint, and the source hash. If anything does not match, indexes are rebuilt. The directory can be deleted at any time; it will restore itself. If the cache volume is read-only, the inability to delete a stale file does not interrupt removing a source from accounting.

The order of records in registry.json does not matter: code is restored only after its configuration. If its record is missing, was deleted, or replaced during startup, an old module or extension record is not published without an owner.

Search index postings live in numpy arrays; temporary dictionary population is freed immediately after freezing. The server's total RSS cannot be obtained by summing isolated layers: the cold peak and the warmed container state are captured separately after all sources are up.

Module texts — code tools connected

The acceptance of configuration export to files is implemented — section «Exporting configuration to files» above: code and forms land on disk, the source is accounted for in the registry, four internal indexes are built and cached. search_procedures searches exact names and exported procedures by words, get_procedure returns a module table of contents or a card with a body window, and get_callers combines confirmed call sites, metadata bindings, and form handlers without reading bodies.

The current production slice of the main configuration as of 2026-08-21: 137,116 procedures, 619,029 call sites, 3,194 forms, 89,528 form items, and 24,202 event binding lines.

Reproducible on its own export without printing its name or path:

MODULES_ROOT=/путь/к/выгрузке
.venv/bin/python tools/lab/measure_modules_cache.py "$MODULES_ROOT"

The meter prints JSON aggregates with keys procedures, calls, forms, elements, and event_rows. The last counter is raw <Event> rows before grouping and deduplication in public bindings.

The historical prototype snapshot was taken 2026-08-20 on an anonymized hierarchical export to files: 7,878 modules, 137,115 procedures, and 260 MB of text. The numbers below are exactly those, not the current aggregates.

Search latency is 1.2–1.5 ms. A full cold build of the four indexes with cache write takes about 50 s.

There are two different file exports, and the second was measured separately — an industry configuration 10.5.1.3 on 8.3.5: flat layout, modules in .txt, ordinary form code inside binary .Form containers. 2,603 modules, 33,555 procedures, parsing 1.1 s, search across all 94 MB at a median of 0.2 ms. This format does not contain form structures, and some common modules are shipped compiled — they have no source at all. Such modules are visible at ОбщийМодуль.<Имя>, but the procedures and calls inside them cannot be read. Therefore summaries, search, the table of contents of an ordinary module, reverse search, and overlap information warn above the result that the aggregates are given only for the available sources and may be incomplete.

The measurement scripts live in tools/lab/; they reproduce every figure above:

.venv/bin/python tools/lab/measure_modules_cache.py <каталог выгрузки в файлы>
.venv/bin/python tools/lab/measure_modules.py <каталог выгрузки в файлы>
.venv/bin/python tools/lab/measure_resident.py <каталог> <файл индекса> собрать
.venv/bin/python tools/lab/measure_search.py <файл индекса> экспортные
.venv/bin/python tools/lab/measure_forms.py <каталог>
.venv/bin/python tools/lab/measure_flat.py <каталог плоской выгрузки>
.venv/bin/python tools/lab/measure_container_memory.py --mode cold --data data \
  --timeout 300 --poll-interval 0.5
.venv/bin/python tools/lab/measure_container_memory.py --mode warm --data data \
  --timeout 300 --poll-interval 0.5

Search quality

Measured by a bench, reproduced with a single command:

PYTHONPATH=src .venv/bin/python -m mcp1c.bench \
    --data data --config РозницаДляКазахстана \
    --auto --sets query-language,roznica-metadata,modules-procedures \
    --check-notes

The whole table was captured 2026-08-21 with the exact command above in read-only mode, without --save; the command exited with code 0. The three manual sets were assembled from live phrasings and misses, the last two are built from the data itself. Procedures have ranks [miss, miss, 7]. This is a baseline for improvements, not an acceptance threshold.

The procedures row is reproduced faster separately:

PYTHONPATH=src .venv/bin/python -m mcp1c.bench \
    --data data --config РозницаДляКазахстана \
    --sets modules-procedures

"Gap" — how far the first result is from the second, by median. It answers the question "confident hit or a fluke": 35% for the query language versus 91.7% for help means those wins hold three times weaker and a ranking tweak can flip them without moving a single percentage point of P@1.

Search latency is 0.18–1.4 ms per query depending on the set.

Query sets are not included in the image (tests/ in .dockerignore): measure from a working copy, not from the container.

Tests

.venv/bin/pip install -r requirements-dev.txt
.venv/bin/python -m pytest          # 1100 тестов (прогон 2026-08-21)

They do not depend on the contents of data/: there are no proprietary exports in the repository, everything needed is built synthetically in tests/conftest.py.

Search quality is not checked by tests — it is measured by the bench (mcp1c.bench, see "Measured"). Percentage thresholds would break on every dictionary edit, so the bench prints numbers and a human makes the decision. pytest checks observable behavior: "index was not rebuilt", "results matched", "startup did not crash".

6. Security

Two tokens, both set via environment variables. While a token is not set, the corresponding access is open to anyone who can reach the address.

The difference between "open" and "disabled" is intentional. Reading without a token works — on your own machine that is convenient and harmless. Writing without a token does not work at all: a single bad dictionary edit quietly breaks search for everyone connected to the shared server.

The token is passed via a header — either X-Api-Token or Authorization: Bearer <token>. The admin token also works for reading: otherwise the owner would have to keep two headers in the client instead of one.

The token must be in Latin characters. HTTP headers are encoded in latin-1, and a Cyrillic token physically never reaches the server: through the browser login form it will work, through a client header it will not.

Two paths are skipped past the check: /health (the container healthcheck uses it, and it returns nothing beyond read rights) and /login — otherwise the login form would be behind the very authorization it issues.

Two more rules, not about tokens:

• The MCP endpoint returns the configuration structure in full. Set API_TOKEN for any deployment beyond your own machine; network access alone is not enough.

• The data/ directory is entirely in .gitignore — both .hbk with exports and parsed indexes. The help index is the same 1C company content, just unpacked. It once got in and sat there for 20 commits; the history was rewritten with git filter-repo, and the rule was reformulated by directory rather than by extensions: the check should not be "is this .hbk?" but "is this in data/?".

7. Documents

Six self-contained contract documents are published: the export format, the source boundary, the structure of the query language and dashboard, code export intake, and the code provider. Every link from a public file must lead to material that is also in the repository.

External DB, vectors, graph DB, SSE transport, and lazy loading were rejected by measurements on the current corpus. They can only return with new measurements that refute the previous cost or show a new live scenario.

8. License

Apache License 2.0. It is also worth reading NOTICE separately — there are two things there that the license itself does not say:

• the project was developed independently and is not affiliated with 1C LLC; "1C" and "1C:Enterprise" are trademarks of 1C LLC, and the license grants no rights to them (Apache 2.0, section 6);

• the repository contains no platform help and no configuration exports — neither in source form nor parsed. These are 1C company content and data from specific deployments; everyone takes them from their own distribution and puts them in data/. The license covers the code, not the data you load into it.