# 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"]}

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

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

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

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

 .

**

## The draft output got some garbled words. Need to fix. We should not have "No hay" repetitive. Let me carefully produce a clean finished translation from here.

Given the manual drafting is frustrating, I'll output a clean final without any malapropisms.

We'll start over in the specific sections:

## Cómo funciona

Conviene entenderlo antes de que algo empiece a fallar. **La dirección es una sola — `/mcp`;** no hay un endpoint por herramienta; cuál herramienta se ha invocado está escrito en el cuerpo de la solicitud, no en la ruta.

Después, dos mecanismos distintos, que no se deben confundir:

| | Descripciones de las herramientas | Datos |
|---|---|---|
| Cuándo | una sola vez, al conectar | en cada llamada |
| Quién lanza | el cliente, sin participación del modelo | el modelo, por su decisión |
| Método | `POST initialize` y luego `POST tools/list` | `POST tools/call` |
| Dónde va | al desarrollo del sistema, what model | al cuerpo de la conversación |
| Precio | de pago, ocupa todo el tiempo de la sesión | por cada llamada |

Al conectar, el cliente envía `POST initialize`: servidor responde con el nombre, la version, the instructions, and with `mcp-session-id` in the heading; then `POST tools/list` returns all the tools once: sense, description, JSON schema, rules for model. The model does not "go top".

Wait "инструкция" — "the text `instructions`" Keep code `instructions` preserved.

Let's refine.

At conectar, the client does `POST initialize` — server responds "название", "версия", "instructions" and returns `mcp-session-id` in a header. Then `POST tools/list` gives all tools at once: name, description, JSON-schema params. All this goes to the context of the model before a person typed the first word. The model doesn't fetch the description when it needs it; it already needs it.

Thus: "De ahí se desprende un consequence — **occupy space in the window all the session, regardless of whether the model calls any instrument at least one or no one.**"

We need fix "клиент сам, без участия модели" "proprio".

Let's write the final answer now, clean and complete. I'll update all segments and ensure no erroneous placeholders. It will be a bit long but okay.

Let's compose final text as a complete output. We'll use precise Spanish.

---

In the final, the Title.

Also, note that I earlier wrote "T" headings have anchor "#" but good.

Let's structure:

# Servidor MCP de la estructura de configuraciones 1С

Referencia ....

...

At the bottom end with "El modelo doesn't need..." etc.

Let's ensure no untranslated Russian except prod names and code.

## Important: The item list "2. Conexión" will be heading "## 2. Conexión del agente".

## "Como это работает" -> "## Cómo funciona".

## If so, " if not

**Siempre hay siete herramientas, sin importar qué esté cargado.** El conjunto es un contrato, no una variable: las herramientas están vinculadas entre sí, y en el servidor de trabajo están cargadas las tres fuentes — configuraciones, ayuda de la plataforma, lenguaje de consultas. El contrato `tools/list` más `instructions` — **alrededor de 3 900 tokens**, y esta cifra no depende del estado del registro.

De aquí se deriva una consecuencia directa que hay que conocer de antemano: **si la fuente no está cargada, igual pagas por sus herramientas.** Sin la ayuda de la plataforma, `search_syntax` y `get_syntax` están en el contexto y cuestan 1 185 tokens, respondiendo «ayuda no conectada»; `compare_configurations` con una sola configuración — 262 tokens para la respuesta «se necesitan al menos dos». Esto se soluciona cargando la fuente, no seleccionando herramientas: la selección se probó el 2026-08-19 y se canceló — detalles y cifras en [«Pospuesto»](docs/TASKBOARD.md).

Por eso las descripciones se escriben de forma densa, y los detalles van a la salida de la propia herramienta: por ellos se paga solo cuando se necesitan.

`GET /mcp` — no es un «POST incorrecto», sino el tercer método en la misma dirección: abre un flujo de mensajes **del servidor al cliente** y requiere un `mcp-session-id` ya obtenido. `DELETE /mcp` cierra la sesión.

## Si el cliente no se conecta

El código de respuesta en el registro (`docker logs -f mcp1c`) indica la causa:

| Código                        | Qué está mal                                                                                                  |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `406`                         | el cliente no envía `Accept: application/json, text/event-stream` — se necesitan ambos tipos                   |
| `400 Missing session ID`      | el cliente no devolvió el encabezado `mcp-session-id` recibido en `initialize`                                |
| `400` en el primer `GET /mcp` | el cliente comenzó el handshake con `GET` — habla con el transporte antiguo HTTP+SSE, y en esta dirección está streamable-http |
| `404` en `/sse`               | lo mismo: el transporte antiguo no está expuesto al exterior                                                   |
| `401`                         | no se envió `X-Api-Token` cuando `API_TOKEN` está definido                                                    |
| el registro está vacío         | el cliente no envió ninguna solicitud — el problema está en su configuración, no llegó al servidor            |

Caso real: **Qwen Code** no se conectaba porque en su configuración estaba la clave `url` — en la familia Gemini CLI (Qwen hereda el formato) significa el transporte SSE antiguo, y el cliente comenzaba con `GET`, recibiendo `400`. Con `httpUrl` — es decir, streamable-http — la conexión se establece de inmediato.

## Token: qué añadir a la configuración del cliente

**Si en el servidor está definido `API_TOKEN`, cada cliente está obligado a enviarlo como encabezado. Sin el encabezado, `/mcp` responde `401`, y el agente simplemente no verá las herramientas.**

Sirve cualquiera de los dos encabezados — el servidor acepta ambos:

GXP7

Tres cosas con las que se tropieza:

* **Solo ASCII.** Los encabezados HTTP se codifican en latin-1, un token en cirílico no llegará a través de ellos. Generar así:
  `python3 -c "import secrets; print(secrets.token_urlsafe(32))"`.
* **En el cliente se coloca `API_TOKEN`, no `ADMIN_TOKEN`.** El de administrador también lo aceptarán, pero la configuración del cliente va a git y a las copias de seguridad: un token de lectura filtrado permite ver, un token de administrador filtrado permite eliminar fuentes.
* **`stdio` no requiere token en absoluto.** Allí el cliente inicia el proceso él mismo, la red no participa y no hay nada que verificar. Si el cliente no sabe definir encabezados — esta es una solución alternativa viable.

Verificar que el servidor ve el token, antes de cualquier configuración del cliente:

GXP8

`200` — token aceptado. `401` — token incorrecto o el encabezado no llegó.

### Cómo no commitear un secreto

`.mcp.json` y archivos similares suelen estar en el repositorio. Opciones:

1. **Sustitución de variable** — si el cliente lo soporta (Claude Code lo soporta):
   `"X-Api-Token": "${MCP1C_API_TOKEN}"`, y la variable en sí en `~/.zshrc`.
   A git va el nombre de la variable, no el valor.
2. **Sacar el archivo de git:**
   `git rm --cached .mcp.json && echo ".mcp.json" >> .gitignore`.
3. **Mantener la configuración no en el proyecto, sino en la configuración de usuario del cliente** — entonces el repositorio no tiene nada que ver.

## Claude Code

Archivo `.mcp.json` en la raíz del proyecto:

GXP9

El bloque `headers` solo se necesita si en el servidor está definido `API_TOKEN`. El valor se toma de la variable de entorno para que el archivo pueda estar en el repositorio:

GXP10

O mediante comando:

GXP11

## Codex CLI

`~/.codex/config.toml` o `.codex/config.toml` en el proyecto:

GXP12

## Cursor

`.cursor/mcp.json`:

GXP13

## VS Code (Copilot)

`.vscode/mcp.json` — aquí la clave se llama `servers`:

GXP14

## Qwen Code

Formato de Gemini CLI, y **la clave elige el transporte** — este es el único detalle:

GXP15

`httpUrl` — streamable-http, nuestro caso. `url` en este formato significa el transporte SSE antiguo: el cliente comenzará el handshake con `GET /mcp`, recibirá `400 Missing session ID` y no se conectará.

## Otros clientes

Windsurf, Antigravity, Cline, Roo Code, agentes de consola — el formato de escritura es el mismo: tipo de transporte, URL y, si está definido `API_TOKEN`, bloque de encabezados. Las diferencias están solo en el nombre del archivo y en la clave de nivel superior (`mcpServers` o `servers`) — consulte la documentación del cliente específico.

El cliente no sabe definir encabezados — no es un callejón sin salida: conéctese a través de `stdio`, allí no se necesita token, porque no hay red.

## Ejecución local a través de stdio

Cuando el cliente debe levantar el servidor él mismo. **Aquí no se necesita token**: el proceso lo inicia el cliente, la comunicación va por los canales del proceso, no por la red — no hay nada que verificar ni de qué protegerse.

GXP16

***

# 3. Herramientas

El conjunto es fijo y deliberadamente pequeño: cada herramienta está constantemente en el contexto del agente. Una nueva fuente de datos enriquece las respuestas de las existentes, no añade las suyas propias.

| Herramienta                                  | Función                                                                 |
| -------------------------------------------- | ----------------------------------------------------------------------- |
| `list_configurations`                        | qué está cargado, qué proveedores están disponibles para cada configuración |
| `search_objects(query, config, kind, limit)` | formulación humana → nombre exacto del objeto                            |
| `get_object(full_name, config, detail)`      | composición del objeto; `detail`: `brief` / `fields` / `full`            |
| `get_related(full_name, config)`             | movimientos, referencias, dependencias — **solo directas**               |
| `compare_configurations(full_name, configs)` | un objeto en dos configuraciones                                         |
| `search_syntax(query, config, kind, limit)`  | búsqueda en la ayuda de la plataforma **y en el lenguaje de consultas**  |
| `get_syntax(name, config, detail)`           | firma, parámetros, disponibilidad, versión, reemplazo para plataforma antigua |

`config` es obligatorio cuando hay más de una configuración cargada: el servidor deliberadamente no la sustituye en silencio — de lo contrario el agente escribiría código basado en una base ajena, y nadie se enteraría.

Un mismo nombre puede vivir en dos dominios a la vez: `СтрНайти` existe tanto en la plataforma (desde 8.3.6) como en el lenguaje de consultas. Entonces `get_syntax` enumera los homónimos con la dirección de cada uno ya preparada, y se puede repetir la llamada con una cadena de la salida:

GXP17

El calificador `Запрос.` es necesario porque un elemento del lenguaje de consultas no tiene propietario: no se puede nombrar como `Объект.Член`, como uno de plataforma.

## Orden de las llamadas — y qué se pierde si se viola

GXP18

**El paso `get_object` no se puede omitir.** La búsqueda devuelve solo nombres y contadores; todo lo que afecta al código vive en la ficha del objeto:

* **tipo y periodicidad del registro.** `СрезПоследних` solo existe en un registro de información periódico, y los no periódicos son **566 de 603**;
* **nombres listos de los campos de tablas virtuales.** En la consulta, el recurso `Количество` se llama `КоличествоОстаток`, `КоличествоОборот`, `КоличествоПриход` — en el configurador estos nombres no se ven en ningún lugar, los genera la plataforma;
* **límite de subconto, correspondencia, recursos del gráfico** — sin ellos no hay con qué nombrar campos del tipo `СубконтоДт1`;
* **cadenas de longitud ilimitada.** Marcadas directamente en el tipo:
  `Строка (неогр. — только через ПОДСТРОКА)` frente a `Строка(200)`. Un campo así no se puede poner en la consulta tal cual — la plataforma no permitirá ni compararlo, ni agruparlo, ni ordenarlo. Estos campos son del 23% al 38% de los campos de cadena en configuraciones reales, por eso en las fichas donde aparecen (2 474 de 20 522), **antes de la lista de campos** se imprime una advertencia con la receta.

Una consulta escrita inmediatamente después de `search_objects` parece correcta y falla con «campo no encontrado». Ejemplo de lo que solo llega desde `get_object`:

GXP19

Un segundo igual — y se encontró con un fallo real del 2026-08-18. El agente agrupó la consulta por una cadena sin límite de longitud; los datos los dimos correctos, pero la diferencia solo se leía por la ausencia del número entre paréntesis:

GXP20

**La receta está tanto en la advertencia como en la propia cadena del campo, y no es redundancia.** La primera redacción imprimía la advertencia como último párrafo de la ficha. Un agente real del 2026-08-18 llamó a `get_object` con `detail=fields`, la recibió completa — y aun así agrupó por ese campo. La advertencia estaba 721 tokens después de la cadena del campo, y la decisión se toma donde se copia el nombre. La misma lección ya estaba escrita en las descripciones de las herramientas: la regla funciona donde se lee, no donde es más prolijo colocarla.

Cada prohibición está verificada: las agregadas — cita de la ayuda, las otras cinco — ejecuciones en base real con textos de errores registrados. La ayuda conoce la limitación solo en tres funciones agregadas de seis y calla sobre la agrupación, el ordenamiento, `РАЗЛИЧНЫЕ`, `ОБЪЕДИНИТЬ` y la comparación — es decir, un agente que la leyera honestamente no podría enterarse. El desglose por origen — en [docs/data-sources.md](docs/data-sources.md), sección «Advertencias en la ficha».

**Antes de llamar a una función de la plataforma en una configuración antigua — `get_syntax`.**
Lo no disponible se marca, y allí mismo está la receta de reemplazo, si está registrada.

## Las fuentes son independientes

Son tres, y cada una se conecta por separado:

| Fuente                  | Archivo                        | Qué aporta                                                  | Sin ella                                          |
| ----------------------- | ------------------------------ | ----------------------------------------------------------- | ------------------------------------------------- |
| Metadatos de configuración | `СтруктураКонфигурации_*.zip` | objetos, atributos, relaciones, movimientos                 | `search_objects` y `get_object` no responden      |
| Ayuda de la plataforma  | `shcntx_ru.hbk`                | métodos, propiedades, firmas, disponibilidad, versiones     | `search_syntax` dice «fuente no conectada»        |
| Lenguaje de consultas   | `shquery_ru.hbk`               | `ВЫБРАТЬ`, `ЛЕВОЕ СОЕДИНЕНИЕ`, `ИТОГИ ПО`, `РАЗНОСТЬДАТ`    | las construcciones del lenguaje de consultas no se encuentran |

| Qué está cargado        | Qué funciona                                            |
| ----------------------- | ------------------------------------------------------- |
| Las tres                | todo                                                     |
| Solo configuración      | metadatos; la sintaxis responde «fuente no conectada»    |
| **Solo ayuda**          | sintaxis sin filtrado por versión, `config` no es necesario |
| Nada                    | `list_configurations` explica qué cargar                 |

## El lenguaje de consultas — una fuente separada

`shquery_ru.hbk` del mismo directorio de instalación de la plataforma. 127 páginas: 52 funciones, 67 palabras clave, 8 artículos. Se carga como una fuente normal y entra en **el mismo índice de búsqueda** que la ayuda de la plataforma — no hace falta buscar con una herramienta separada, `search_syntax` encuentra ambas cosas.

**En el propio archivo no hay versiones** — verificado en las 129 páginas: cero menciones de «8.3.x» y «a partir de la versión». Pero el lenguaje de consultas **cambia**: la versión 8.3.20 añadió 25 funciones, entre ellas `СтрНайти`, `Лев`, `Прав`, `ВРег`, `НРег`, `СтрЗаменить`, `Окр`, `Цел` y toda la trigonometría.

No hay de dónde sacar la versión: la ayuda de la plataforma no describe en absoluto las funciones del lenguaje de consultas (`ПОДСТРОКА` — cero coincidencias en 25 511 elementos). Por eso las versiones las asigna la tabla curada `query_versions.py`, según la lista de 1C «Funciones agregadas al lenguaje de consultas a partir de la versión 8.3.20». A las otras 27 funciones no se les asigna versión: siempre existieron.

Luego funciona un filtro normal: una configuración en 8.3.5 no verá estas funciones, en 8.3.23 las verá.

La tabla se verifica con datos: comparando dos ayudas de plataformas distintas. Lo que no está en la antigua y está en la nueva, apareció entre ambas, y eso debe tener una versión:

GXP21

Ejecución del 2026-08-19, 8.3.5.1570 contra la actual: aparecieron 29, cubiertas 29, falsos positivos 0. Un falso positivo es el peor de los errores: un elemento que ya estaba en la ayuda antigua pero está marcado con versión, se ocultará de una configuración donde sí existe.

Hay una instancia por servidor: volver a cargar reemplaza la anterior.

**Las tablas de las páginas se muestran, pero no se buscan.** En esta ayuda, las celdas de las tablas están marcadas con párrafos dentro de `<TD>`, y sin un análisis separado, la tarjeta imprimía la tabla como una columna de valores: «Товар / Количество / Номер / Сантехника / 104 / …» dos docenas de líneas seguidas. Ahora las tablas se procesan en un campo separado — 51 tabla en 31 páginas de 127 — y se imprimen en su lugar dentro del texto: una página con dos ejemplos muestra cada resultado debajo de su ejemplo. El contenido de las tablas no entra en el índice de búsqueda.

Las tablas de esta ayuda son de dos naturalezas distintas y se procesan de manera diferente:

| Qué                                                          | Cuántas            | Cómo se ve en la tarjeta                 |
| ------------------------------------------------------------ | ------------------ | --------------------------------------- |
| tabla de datos — resultado de una consulta de ejemplo        | 51 en 31 páginas   | como tabla markdown                     |
| diagrama sintáctico dibujado — gramática de la construcción | 21 en 17 páginas   | en escalera con sangría según el nivel de ramificación |

Se distinguen por el marcado, no por la clase CSS: `class=SimplyTable` no está en todas — 7 tablas reales no lo tienen. La señal es la geometría: en una tabla de datos todas las filas tienen el mismo ancho; en un diagrama los anchos son irregulares y hay celdas de una sola barra vertical (es una línea dibujada, no un valor).

**El marcado dañado se anuncia en voz alta.** Una página con `<TABLE>` sin cerrar se procesa sin tablas, pero no se pierde, y su nombre aparece en las advertencias de la fuente: como una línea en la salida de carga (`mcp1c.cli reg-add`) y como una línea separada en la página «Fuentes» del panel. No se puede entregar silenciosamente una tarjeta más pobre de lo normal: eso sería indistinguible de una ayuda que simplemente no lo tiene.

La mitad de los nombres coincide con los nombres de la plataforma (57 de 127) — `ГОД`, `МЕСЯЦ`, `ПРЕДСТАВЛЕНИЕ` están en ambas. Para que una pregunta sobre consultas no derive al método de la plataforma, expresiones como «en la consulta», «en el texto de la consulta», «en la selección» dan a los elementos del lenguaje de consultas un impulso suave. Suave a propósito: cuando la ventaja es clara, el elemento de la plataforma sigue siendo el primero — «cómo pasar un parámetro en una consulta» puede ser sobre `Запрос.УстановитьПараметр`.

**El parámetro `config` es obligatorio si hay más de una configuración cargada.** Por defecto no se sustituye nada: la elección silenciosa hace que el agente escriba código sobre una configuración ajena sin que nadie lo note.

## La respuesta depende de la versión de la plataforma

La misma llamada, dos configuraciones:

GXP22

Para la plataforma 8.3.5 se eliminaron 6 539 elementos de los resultados; para 8.3.23, 874. No con una advertencia, sino con filtrado: el agente puede ignorar una advertencia, pero un método ausente de los resultados, no.

El campo **Disponibilidad** (servidor / cliente fino / cliente web / móviles) hay que leerlo sí o sí: una llamada a un método de servidor desde un contexto de cliente no compila.

## Las ayudas de varias versiones se fusionan en un solo índice

Una sola ayuda reciente sobre una configuración antigua **miente**. Medido en 8.3.5: el servidor declararía inexistentes 199 elementos, 117 los devolvería con una firma ajena (`ЗаписьXML.ОткрытьФайл` en 8.3.5 toma dos parámetros, en 8.3.27 — tres), 410 con una disponibilidad ajena. Todo esto son errores de compilación, no imprecisiones.

Por eso las ayudas de distintas versiones se colocan una al lado de la otra y se fusionan en un solo índice con los límites `since` y `until`, y la respuesta se arma para la versión de una configuración concreta. **Se necesitan tantas ayudas como plataformas tengan las configuraciones cargadas** — dos extremas intermedias no las reemplazan.

El costo se midió y es bajo: fusionar tres versiones da 25 691 claves contra 24 777 de una sola, es decir, menos del uno por ciento. Un contenedor separado por versión también funciona y queda como vía de emergencia, pero como opción principal perdió en números: 300–450 MB y una dirección propia por cada versión.

El propio servidor indica qué ayudas faltan y cuáles sobran, en la salida de `list_configurations`.

## Reemplazo en lugar de prohibición

Decir «la función no existe» es la mitad de la respuesta. La otra mitad es con qué reemplazarla, y no se deduce de la ayuda: la marca de obsoleto está en 15 páginas de 25 mil.

Por eso existe la tabla de reemplazos (`replacements.py`), actualmente 6 entradas — funciones de cadena que aparecieron en 8.3.6. En lugar de prohibir, `get_syntax` devuelve una receta:

GXP23

**La salvedad es obligatoria.** El reemplazo casi nunca es equivalente, y colar silenciosamente una función parecida es peor que no sugerir nada.

La tabla se completa con casos reales, no a ciegas: no tiene sentido inventar soluciones para funciones que nadie ha pedido.

***

# 4. Gestión de datos

## Añadir una fuente

GXP24

Más simple: colocar el archivo en `data/bootstrap/` — se tomará en el siguiente inicio.

## Aplicar cambios sin reiniciar

El servidor en ejecución mantiene el registro en memoria, por lo que después de `reg-add` hay que empujarlo. O bien reiniciar (`docker compose restart mcp1c`, unos 2 segundos), o bien el manejador de administración:

GXP25

## Diccionario: cómo se habla contra cómo se llama

La principal dificultad de la búsqueda es la brecha entre las palabras de la persona y los nombres en la configuración. «Заказ клиента» — y el objeto se llama `ЗаказПокупателя`. El diccionario está en `data/dictionary.json` y se edita sin reconstruir la imagen.

Dos mecanismos, y son diferentes.

**Sinónimos de palabras** — comunes a todas las configuraciones:

GXP26

**Alias de objetos** — la indicación directa de «cuando digo esto, me refiero a estos objetos», con un peso superior a cualquier coincidencia textual. Dos docenas de frases típicas («archivos», «productos», «clientes», «empleados», «tareas») están integradas y funcionan de inmediato; si el objeto no existe en la configuración, el alias no se aplica. Los propios se agregan vinculados a la configuración:

GXP27

GXP28

La existencia de los objetos se verifica al agregar: un alias no sirve para un error tipográfico. Para ver el contenido: `dict-show`, para eliminar: `dict-alias «frase» --remove`.

Los cambios se aplican reiniciando el contenedor o con `POST /admin/reload` — no es necesario reconstruir la imagen.

**Las claves de búsqueda del lenguaje de consultas** son el tercer mecanismo, y solo se editan en el código (`search_keys.py`, en git con revisión). La breza aquí es de otra naturaleza: la persona no llama a la construcción con una palabra ajena, sino que **describe la tarea**. «Cantidad de días entre dos fechas» frente a `РАЗНОСТЬДАТ`, «quitar duplicados» frente a `РАЗЛИЧНЫЕ» — cero palabras en común, y un sinónimo no ayuda, no hay nada que reemplazar.

Por eso a 116 de 127 páginas se les han asignado formulaciones con las que se las busca, y entran en el índice de búsqueda como un campo separado. En tiempo de ejecución no pesan nada. El resultado con un conjunto real: **57,9 % → 94,7 %** en el primer lugar, sin regresión en 61 mil consultas automáticas.

Las claves **las hemos inventado nosotros, no se han extraído**, y de ahí tres limitaciones:

* viven en una capa separada en git, no se asignan al elemento analizado;
* **no llegan al agente en la respuesta** — la respuesta se sigue armando solo con la ayuda; las claves funcionan exclusivamente para acertar con el artículo correcto;
* están vinculadas a las páginas por identificador, y si la ayuda da otro conjunto de páginas, la discrepancia se anuncia al cargar, no se manifiesta silenciosamente con una búsqueda degradada.

La regla completa está en [docs/data-sources.md](docs/data-sources.md), sección «Capas generadas sobre las fuentes».

## Ver qué hay cargado

GXP29

GXP30

Puede que no haya configuraciones en absoluto; el servidor funciona si hay al menos una ayuda cargada: responden `search_syntax` y `get_syntax`, no es necesario indicar `config`. En ese caso, `reg-list` enumera lo conectado y devuelve 0:

GXP31

Con el registro completamente vacío — «Nada cargado.» y código de retorno 1. Cualquier comando que necesite una configuración dirá allí mismo qué falta exactamente y con qué se soluciona.

## Depuración sin agente — `mcp1c.cli`

La CLI accede al mismo registro y a las mismas funciones que las herramientas MCP. Si responde correctamente, el problema está en la configuración del cliente, no en el servidor.

Los comandos se dividen en tres grupos. **Sobre el registro** — lo mismo que ve el agente:

GXP32

`reg-search` sin `--syntax` busca por metadatos; con él, por la ayuda y el lenguaje de consultas.

**Directamente sobre el archivo, sin registro** — para ver la exportación antes de que vaya al servidor:

GXP33

La ruta es un ZIP o un directorio descomprimido; el formato se determina por el manifiesto.

**Diccionario de búsqueda** — sinónimos comunes, alias vinculados a la configuración:

GXP34

`dict-show` muestra el origen de cada regla — así empieza el análisis de «por qué la búsqueda se comporta así».

## Medición de la calidad de búsqueda — `mcp1c.bench`

Un banco de pruebas aparte, porque «mejoró» sin cifras es una opinión.

GXP35

| Clave              | Qué hace                                                             |
| ----------------- | ---------------------------------------------------------------------- |
| `--sets nombre,nombre`  | conjuntos manuales de `tests/queries/*.json`, sin extensión                |
| `--auto`          | conjuntos automáticos según la ayuda: nombres exactos y homónimos           |
| `--config`        | configuración; obligatoria si hay varias cargadas                    |
| `--limit`         | profundidad de los resultados, por defecto 10                        |
| `--save ruta`     | guardar la ejecución para comparar; por convenio `data/bench/AAAA-MM-DD.json` |
| `--baseline ruta` | comparar con la ejecución anterior — nombrará uno a uno quién cambió de lugar       |
| `--check-notes`   | contrastar las notas del conjunto con el lugar que ocupó la consulta |

Imprime P\@1/P\@3/P\@5/P\@10, MRR, la proporción de «dominio ajeno primero» y la separación mediana del primer resultado respecto del segundo. No hay umbrales en los assert a propósito: los conjuntos de consultas no son pruebas; los porcentajes se romperían con cada edición del diccionario. Un código de retorno distinto de cero solo ocurre con una discrepancia en las notas — eso no es calidad de búsqueda, es una mentira en el archivo.

La comparación de dos ejecuciones se ve así (las regresiones primero):

GXP36

**Los conjuntos no entran en la imagen** (`tests/` en `.dockerignore`) — ejecutar desde la copia de trabajo, no desde el contenedor.

## El servidor manualmente — `mcp1c.server`

GXP37

`--transport sse` está en el código y funciona, pero no se ha expuesto: el SDK levanta un transporte por proceso, y todo nuestro estado está en memoria — el segundo transporte costaría casi lo mismo que el primero. El propio SSE en MCP está declarado obsoleto en favor de streamable-http.

## De dónde salen los datos de origen

**La estructura de la configuración** — mediante el procesamiento de [`exporter-1c/`](exporter-1c/README.md). Cuatro variantes del módulo para formulario normal y gestionado, XML y JSON; las variantes XML son compatibles con 8.3.5. Dos procesamientos ya vienen compilados y se abren tal cual: `ВыгрузкаСтруктурыКонфигурации_ОбычнаяФорма_XML.epf` (8.3.5 y superiores) y `ВыгрузкаСтруктурыКонфигурации_УправляемаяФорма_XML_JSON.epf` (8.3.6 y superiores, el formato se elige en el formulario).

**La ayuda de la plataforma** — el archivo `shcntx_ru.hbk` del directorio de instalación de 1C:

GXP38

**El nombre debe coincidir por completo.** En el mismo directorio hay cientos de archivos `.hbk` — 38 ayudas distintas, cada una en unas veinte lenguas. Similares a la buscada:

| Archivo             | Qué es                                   | Por qué no sirve                                                                                                                          |
| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `shcntx_root.hbk`   | la misma ayuda, parte independiente del idioma | 25 508 elementos, pero **ni una sola descripción**: solo el árbol de páginas e identificadores en inglés, sin versiones de aparición |
| `shlang_ru.hbk`     | descripción del lenguaje integrado        | no es un contenedor de 1C en absoluto                                                                                                    |
| `shquery_ru.hbk`    | lenguaje de consultas                     | lo mismo                                                                                                                                  |
| `config_ru.hbk`     | ayuda del configurador                    | es un contenedor, pero no contiene páginas del asistente de sintaxis                                                                      |
| `1cv8_ru.hbk`       | manual de usuario                         | no es un contenedor                                                                                                                       |

Por tamaño no se distinguen: `shcntx_root.hbk` pesa 33 MB frente a los 39 MB del correcto. El sufijo `_ru` es el idioma, `_root` es la parte común sin textos.

Si el archivo no es el correcto, el servidor explica por qué y deja la ayuda anterior en su lugar.

Basta **una** ayuda de la plataforma más reciente disponible: cada elemento lleva la versión de aparición, y para configuraciones antiguas lo sobrante se filtra. Si la versión no está en la ruta, se deduce de los propios datos.

**Las ayudas de plataformas antiguas también se aceptan**: están marcadas de otra manera (secciones en `div` en lugar de `p`), y esto se ha tenido en cuenta. Será útil si se levanta un servidor independiente para implementaciones antiguas: la ayuda de 8.3.5 da 18 936 elementos y no contiene `СтрНайти`, `СтрРазделить`, `ЗаписьJSON`; en 8.3.5 no existían. Pero esa ayuda no informa de su versión: no hay marcas de "desde la versión" porque entonces todo era actual. Por eso **la versión se toma del nombre del archivo o del directorio**: colóquela como `8.3.5.1570.hbk` o en `data/hbk/8.3.5.1570/`; de lo contrario, la correspondencia con la configuración no funcionará.

***

# 5. Cómo está organizado

GXP39

**Un solo modelo para dos formatos.** XML y JSON son serializaciones diferentes de un mismo esquema; el cargador reduce ambos a un mismo diccionario. Comprobado: ambas exportaciones dan el mismo conjunto de 30 claves.

**El grafo lo construye el cargador, no 1C.** Las aristas se deducen de los tipos de atributos, movimientos de documentos, bases de entrada, propietarios, manejadores de suscripciones y métodos de tareas programadas. Las reglas se pueden cambiar sin volver a exportar.

**Aristas débiles.** Atributos como `ЗначениеДоступа` enumeran cientos de tipos y conectan casi todo con todo. Esas relaciones se marcan como débiles y están ocultas por defecto; de lo contrario, las útiles se pierden entre ellas.

**Niveles de detalle.** La descripción completa de `Документ.ЧекККМ` (50 atributos, 17 secciones tabulares) consume todo el contexto. `brief` son un par de líneas, `fields` es la composición, `full` es con relaciones.

**Sin bases de datos externas.** Cinco configuraciones con su ayuda se mantienen en la memoria de un solo proceso: 628 MB, carga desde disco en 9,4 s. Elasticsearch, el almacenamiento vectorial y la base de datos de grafos se consideraron y se rechazaron con cifras: el análisis está en [docs/TASKBOARD.md](docs/TASKBOARD.md), sección «Aplazado». En resumen: medio millón de documentos es poco para ES, y todo el coste del vector no está en el almacenamiento, sino en el modelo codificador en tiempo de ejecución (+185–620 MB a la imagen por torch, codificación de la consulta en 16–32 ms frente a los 0,18–1,4 ms actuales para toda la búsqueda).

## Medido con datos reales: 2026-08-18

Qué hay cargado en el servidor de trabajo:

| Configuración                    | Plataforma  | Objetos   | Aristas    |
| -------------------------------- | ----------- | --------- | ---------- |
| Contabilidad para Kazajistán     | 8.3.27.1936 | 3 492     | 84 426     |
| Gestión documental KORP          | 8.3.27.1936 | 4 596     | 50 554     |
| Nóminas y gestión de personal    | 8.3.27.1936 | 5 181     | 100 136    |
| Retail para Kazajistán           | 8.3.23.1997 | 5 637     | 58 345     |
| Casa de comercio de joyería      | 8.3.5.1570  | 1 616     | 29 288     |
| **Total**                        |             | **20 522**| **322 749**|

Además, la ayuda de la plataforma: un índice combinado de tres versiones (8.3.5, 8.3.23, 8.3.27), **25 691 elementos**, y el lenguaje de consultas: **127 páginas** como fuente independiente.

El arranque desde caché tarda **9,4 s** en todo esto. El primer arranque es más lento: se analizan las fuentes, se construyen los índices y se guardan en `data/index/cache/` (12 MB); las ayudas analizadas, en `data/index/syntax/` (11 MB). Después se cargan desde ahí.

La caché es derivada y desechable: está vinculada a la versión de Python, a la huella del código del paquete y al hash de la fuente. Si algo no coincide, los índices se reconstruyen. El directorio se puede eliminar en cualquier momento; se regenerará solo.

La memoria del contenedor en ejecución es de **628 MB**. Los postings del índice se almacenan en arrays de `numpy`; el contenido permanece en diccionarios y se libera justo después de la congelación. La imagen pesa **354 MB**.

### Textos de los módulos: prospección, aún no hay proveedor

El proveedor `modules` no está hecho; el servidor no ofrece herramientas sobre el código. El coste se midió de antemano con la exportación de «Retail» 2.3.10.5 a archivos (2 063 MB, 33 188 archivos, 7 878 módulos, 136 909 procedimientos):

| Capa                                   | En disco | En memoria |
| -------------------------------------- | -------- | ---------- |
| firmas y direcciones de procedimientos | 18,1 MB  | 65 MB      |
| búsqueda en todos los procedimientos   | —        | 473 MB     |
| búsqueda solo en los exportados (49 068) | —        | 156 MB     |
| formularios: 3 194 archivos, 69 769 elementos | 5,8 MB   | 44 MB      |

La latencia de búsqueda es de 0,4–1,2 ms. El análisis del corpus, de 7 a 10 s.

Existen dos exportaciones a archivos diferentes, y la segunda se midió por separado: «Casa de comercio de joyería» 10.5.1.3 en 8.3.5: estructura plana, módulos en `.txt`, código de formularios normales dentro de contenedores binarios `.Form`. 2 603 módulos, 33 555 procedimientos, análisis en 1,1 s, búsqueda en los 94 MB completos con una mediana de 0,2 ms. Este formato no contiene estructuras de formulario, y parte de los módulos comunes se suministran compilados: no contienen código fuente en absoluto.

Los scripts de medición están en `tools/lab/`; son exploratorios y se eliminarán cuando aparezca un proveedor real. Por ahora, con ellos se reproduce cada cifra anterior:

GXP40

El análisis completo, incluida la estructura de las extensiones de configuración, está en [docs/modules-and-extensions-2026-08-18.md](docs/modules-and-extensions-2026-08-18.md).

### Calidad de búsqueda

Se mide con el banco de pruebas y se reproduce con un solo comando:

GXP41

| Conjunto                | Consultas | P\@1  | P\@3  | P\@5  | MRR    | Distancia |
| ----------------------- | --------- | ----- | ----- | ----- | ------ | --------- |
| Lenguaje de consultas   | 19        | 94,7% | 94,7% | 100%  | 0,958  | 35,0%     |
| Metadatos de Retail     | 21        | 90,5% | 95,2% | 95,2% | 0,934  | 94,0%     |
| Nombres exactos de ayuda| 50 926    | 97,1% | 98,3% | 98,7% | 0,978  | 91,7%     |
| Homónimos               | 10 544    | 98,8% | 99,8% | 99,9% | 0,993  | 93,8%     |

Los dos primeros conjuntos son manuales, a partir de fallos reales. Los otros dos se construyen a partir de los propios datos: el nombre del elemento como consulta y también como respuesta esperada.

«Distancia» indica cuánto se separa el primer resultado del segundo, en mediana. Responde a la pregunta «¿acertamos con seguridad o de milagro?»: un 35 % en el lenguaje de consultas frente al 91,7 % en la ayuda significa que esas victorias se sostienen tres veces peor y un ajuste de la clasificación podría revertirlas sin mover ni un punto porcentual de P\@1.

La latencia de búsqueda es de 0,18 a 1,4 ms por consulta según el conjunto.

**Los conjuntos de consultas no se incluyen en la imagen** (`tests/` en `.dockerignore`): hay que medir desde la copia de trabajo, no desde el contenedor.

## Pruebas

GXP42

No dependen del contenido de `data/`: no hay exportaciones propietarias en el repositorio; todo lo necesario se genera sintéticamente en `tests/conftest.py`.

La calidad de búsqueda **no se comprueba** con pruebas: se mide con el banco de pruebas (`mcp1c.bench`, consulte «Medido»). Los umbrales porcentuales se romperían con cada cambio en el diccionario, por lo que el banco imprime cifras y la decisión la toma una persona. `pytest` verifica el comportamiento observable: «el índice no se ha reconstruido», «los resultados coinciden», «el arranque no ha fallado».

***

# 6. Seguridad

Dos tokens, ambos se definen mediante variables de entorno. **Mientras no se defina el token, el acceso correspondiente está abierto a cualquiera que alcance la dirección.**

| Variable      | Qué protege                                                                 | Si no está definida                                  |
| ------------- | --------------------------------------------------------------------------- | ---------------------------------------------------- |
| `API_TOKEN`   | lectura: herramientas MCP y páginas del panel                                | la estructura de configuraciones está abierta a todos |
| `ADMIN_TOKEN` | escritura: carga y borrado de fuentes, edición del diccionario, `/admin/reload` | estas rutas están desactivadas y responden 404       |

La diferencia entre «abierto» y «desactivado» es intencionada. La lectura sin token funciona: en tu propia máquina es cómodo y no supone ningún riesgo. La escritura sin token **no funciona en absoluto**: una sola edición fallida del diccionario rompe silenciosamente la búsqueda para todos los que estén conectados al servidor compartido.

El token se envía en la cabecera, ya sea `X-Api-Token` o `Authorization: Bearer <token>`. El administrativo también sirve para lectura: de lo contrario, el propietario tendría que mantener dos cabeceras en el cliente en lugar de una.

**El token debe estar en caracteres latinos.** Las cabeceras HTTP se codifican en latin-1 y un token cirílico no llega físicamente al servidor: a través del formulario de inicio de sesión del navegador funcionará, pero a través de la cabecera del cliente no.

Se omiten dos rutas en la comprobación: `/health` (por donde pasa el healthcheck del contenedor y no revela más información de la que otorga el permiso de lectura) y `/login`; de lo contrario, el formulario de inicio de sesión quedaría detrás de esa misma autorización que él mismo proporciona.

Dos reglas más, que no son sobre tokens:

* **El endpoint MCP devuelve la estructura completa de configuraciones.** Defina `API_TOKEN` en cualquier despliegue fuera de su máquina; el acceso de red no es suficiente.
* **El directorio `data/` está completo en `.gitignore`**, tanto los `.hbk` con las exportaciones como los índices analizados. El índice de ayuda es el mismo contenido de la empresa «1C», solo que descomprimido. Una vez llegó a estar ahí y permaneció durante 20 commits; se reescribió el historial con `git filter-repo` y la regla se reformuló por directorio, no por extensiones: no hay que comprobar «¿es un `.hbk`?», sino «¿está dentro de `data/`?».

***

# 7. Documentos

| Archivo                                                              | Sobre qué                                                                 |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [AGENTS.md](AGENTS.md)                                                | reglas de trabajo en el proyecto                                          |
| [CHANGELOG.md](CHANGELOG.md)                                          | qué se ha hecho y qué se ha descubierto sobre 1C                          |
| [docs/TASKBOARD.md](docs/TASKBOARD.md)                                | planes, prioridades y propuestas rechazadas con sus motivos               |
| [docs/schema-v1.md](docs/schema-v1.md)                                | contrato del formato de exportación                                       |
| [docs/data-sources.md](docs/data-sources.md)                          | qué fuente se utiliza para qué                                           |
| [docs/query-language-design.md](docs/query-language-design.md)        | estructura de la fuente del lenguaje de consultas                         |
| [docs/dashboard-design.md](docs/dashboard-design.md)                  | estructura del panel                                                      |
| [docs/market-review-2026-08-17.md](docs/market-review-2026-08-17.md)  | revisión de alternativas y qué se ha tomado de ellas                      |
| [exporter-1c/README.md](exporter-1c/README.md)                        | procesamiento de la exportación para 1C                                   |

La sección «Aplazado» del tablero de tareas contiene propuestas rechazadas con cifras: base de datos externa, vectores, base de datos de grafos, SSE hacia afuera, carga diferida. Antes de volver a proponer algo de esto, conviene leer: estas decisiones las revierten nuevas mediciones, no nuevas consideraciones.