infaton-1c-mcp

Servidor MCP INFATON para 1С:Предприятие

Model Context Protocol (MCP) — servidor no lado do 1С:Предприятие, que fornece 51 ferramenta para interação de assistentes de IA com o banco de dados 1С.

Protocolo: JSON-RPC 2.0 (especificação MCP)

---

📋 Composição do repositório

Arquivo	Descrição
Module.bsl	Módulo do serviço HTTP MCP — código principal, 51 ferramenta (4 263 linhas)
index.mjs	Wrapper stdio Node.js para clientes MCP (Claude Desktop, Cursor e outros)
package.json	Manifesto npm para publicação e execução via npx
glama.json	Manifesto para o catálogo Glama.ai
INFATON_MCP.cfe	Extensão de configuração 1С v2.1.0 (pacote binário)
HOW_TO_BUILD_CFE.md	Instruções de compilação e instalação do .cfe
EXAMPLES.md	Exemplos de cenários de agentes (7 casos)
CHANGELOG.md	Histórico de versões

---

🆕 Novidades na v2.1.0

Correções (9 patches)

#	Ferramenta	Bug	Correção
P1	get_list	Ausência de ПЕРВЫЕ N — retornava TODOS os registros	Adicionado ПЕРВЫЕ com parâmetro limit (padrão 100)
P2	get_document_list	Filtro por data — Дата >= sem parâmetro	Adicionado Запрос.УстановитьПараметр para datas
P3	get_object_by_ref	Referência vazia → erro confuso da plataforma	Adicionada verificação de Если НЕ ЗначениеЗаполнено(Ссылка)
P4	get_active_users / get_locks	Percorrimento direto da coleção de sessões → erro no servidor	Migração para МассивСеансов = ПолучитьСеансыИнформационнойБазы()
P5	get_event_log	Data era passada como string + campo «Metadados» em vez de representação	ПреобразоватьДату() + .МетаданныеПредставление
P6	ПреобразоватьДату	Não processava 2026-05-14, 14.05.2026, 20260514	Reescrita completa: ISO 8601 + 3 formatos
P7	fill_on_basis	Объект.Заполнить() → método correto ЗаполнитьНаОсновании()	Corrigida a chamada do método
P8	execute_batch	execute_batch aninhado → recursão infinita	Adicionado guard-flag _batch_depth
P9	—	Versão permanecia 2.0.0	Atualizada para 2.1.0

Novas ferramentas (10 itens, grupo З)

#	Ferramenta	Finalidade
42	get_balance	Saldos e movimentos do registro contábil (qualquer plano de contas)
43	get_register_totals	Totais de registros de acumulação (saldos/movimentos)
44	get_accounting_entries	Lançamentos contábeis do documento (Débito, Crédito, valor)
45	get_related_documents	Cadeia de documentos relacionados (entrada com base em)
46	validate_document	Verificação de preenchimento do documento sem lançamento
47	get_form_structure	Estrutura do formulário gerenciado (atributos, comandos)
48	get_rights	Direitos de acesso do usuário atual ao objeto
49	find_duplicates	Busca de duplicatas em diretórios por atributos
50	get_print_form	Formulários de impressão via subsistema Gerenciamento de Impressão
51	get_configuration_extensions	Lista de extensões de configuração (CFE)

---

🛠 Catálogo completo: 51 ferramenta

Grupo А — Metadados (8)

#	Ferramenta	Descrição
1	get_metadata_tree	Árvore de objetos de metadados da configuração
2	get_object_metadata	Estrutura completa do objeto (atributos, seções tabulares, módulos)
3	get_object_attributes	Lista de atributos do objeto
4	get_object_tabular_sections	Seções tabulares do objeto
5	get_enum_values	Valores de enumeração
6	get_register_dimensions	Dimensões, recursos e atributos do registro
7	get_document_movements	Movimentos do documento pelos registros
8	search_metadata	Busca em metadados (por nome/sinônimo)

Grupo Б — Leitura de dados (7)

#	Ferramenta	Descrição
9	execute_query	Execução de consulta 1С arbitrária
10	get_object_by_ref	Obtenção de objeto por referência/GUID
11	get_list	Lista de itens de diretório/documento com filtros
12	find_by_code	Busca de item por código
13	find_by_name	Busca de item por nome
14	get_register_records	Registros do registro com filtros
15	get_document_list	Lista de documentos com filtros por data/número

Grupo В — CRUD (7)

#	Ferramenta	Descrição
16	create_object	Criação de novo objeto (diretório/documento)
17	update_object	Alteração de atributos do objeto
18	delete_object	Marcação para exclusão
19	post_document	Lançamento do documento
20	unpost_document	Cancelamento do lançamento
21	copy_object	Cópia do objeto
22	set_attribute	Alteração de atributo individual

Grupo Г — Código e relatórios (4)

#	Ferramenta	Descrição
23	execute_code	Execução de código arbitrário na linguagem integrada
24	evaluate_expression	Cálculo de expressão e retorno do resultado
25	get_module_text	Obtenção do texto do módulo do objeto
26	generate_report	Geração de relatório (SKD)

Grupo Д — Administração (6)

#	Ferramenta	Descrição
27	get_active_users	Lista de usuários ativos e sessões
28	get_event_log	Log de registro com filtros
29	get_locks	Bloqueios de dados atuais
30	get_server_info	Informações sobre plataforma, configuração, servidor
31	check_references	Verificação de integridade referencial
32	run_scheduled_job	Execução de tarefa agendada

Grupo Е — Integração (3)

#	Ferramenta	Descrição
33	exchange_execute	Execução de troca de dados
34	get_exchange_log	Log de troca
35	import_data	Importação de dados de JSON

Grupo Ж — Operações avançadas v2.0 (6)

#	Ferramenta	Descrição
36	fill_on_basis	Preenchimento de documento com base em outro
37	write_register_records	Gravação de conjunto de registros do registro
38	update_tabular_section	Atualização da seção tabular do objeto
39	subscribe_events	Assinatura de eventos do log
40	execute_batch	Execução em lote de ferramentas
41	get_changes_since	Obtenção de alterações com carimbo de tempo (CDC)

Grupo З — Contabilidade, auditoria, formulários v2.1 (10) 🆕

#	Ferramenta	Descrição
42	get_balance	Saldos/movimentos do registro contábil
43	get_register_totals	Totais de registros de acumulação
44	get_accounting_entries	Lançamentos do documento (Débito/Crédito/Valor)
45	get_related_documents	Documentos relacionados (cadeia de bases)
46	validate_document	Verificação de preenchimento sem lançamento
47	get_form_structure	Estrutura do formulário gerenciado
48	get_rights	Direitos de acesso do usuário atual
49	find_duplicates	Busca de duplicatas por atributos
50	get_print_form	Formulários de impressão via Gerenciamento de Impressão
51	get_configuration_extensions	Lista de extensões de configuração (CFE)

---

🚀 Início rápido

Opção 1: Via Claude Desktop / Cursor (stdio)

Maneira А — via npx (sem clonagem)

{
  "mcpServers": {
    "1c-erp": {
      "command": "npx",
      "args": ["infaton-mcp"],
      "env": {
        "ONEC_URL": "https://your-server/base/hs/mcp/",
        "ONEC_USER": "Username",
        "ONEC_PASSWORD": "Password"
      }
    }
  }
}

Maneira Б — a partir do repositório clonado

{
  "mcpServers": {
    "1c-erp": {
      "command": "node",
      "args": ["/path/to/MCP35/index.mjs"],
      "env": {
        "ONEC_URL": "https://your-server/base/hs/mcp/",
        "ONEC_USER": "Username",
        "ONEC_PASSWORD": "Password"
      }
    }
  }
}

Opção 2: Chamada HTTP direta

1. Instale a extensão

1. Abra o Configurador do banco 1С
2. Configuração → Extensões de configuração → Adicionar
3. Selecione o arquivo INFATON_MCP.cfe (ou compile conforme instruções a partir de Module.bsl)
4. Atualize a configuração do BD (F7)

2. Verifique a conexão

curl -u 'Логин:Пароль' -X POST \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1}' \
  https://ваш-сервер/база/hs/mcp/

Resposta esperada:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "infaton-1c-mcp", "version": "2.1.0" }
  }
}

3. Chame a ferramenta

curl -u 'Логин:Пароль' -X POST \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"get_balance","arguments":{"account_code":"41.01","period_from":"2026-01-01T00:00:00","period_to":"2026-03-31T23:59:59"}}}' \
  https://ваш-сервер/база/hs/mcp/

---

📐 Arquitetura

┌─────────────────────────┐
│   AI Assistant          │  Claude / GPT / Qwen / Gemini / ...
│   (MCP Client)          │
└────────┬────────────────┘
         │ stdio (JSON-RPC 2.0)
         ▼
┌─────────────────────────┐
│   index.mjs             │  Node.js stdio → HTTP proxy
│   (MCP Transport)       │
└────────┬────────────────┘
         │ HTTP POST (Basic Auth)
         ▼
┌─────────────────────────┐
│   HTTP-сервис /hs/mcp/  │  Расширение INFATON_MCP.cfe
│   Module.bsl            │  51 инструмент (4 263 строки)
│   (MCP Server)          │
└────────┬────────────────┘
         │ Встроенный язык 1С
         ▼
┌─────────────────────────┐
│   База 1С:Предприятие   │  ERP / УПП / Бухгалтерия / УТ / КА
│   Данные, метаданные    │
└─────────────────────────┘

---

📝 Compatibilidade

Parâmetro	Valor
Plataforma 1С	8.3.20+ (testado em 8.3.27.1989)
Configurações	ERP 2.5, UPP 1.3, Contabilidade 3.0, UT 11, KA 2
Protocolo MCP	2024-11-05
Transporte	HTTP (Basic Auth), stdio (via index.mjs)
Node.js	18+ (para wrapper stdio)

---

📊 Histórico de versões

Versão	Data	Ferramentas	Alterações
v2.1.0	2026-05-14	51	+10 ferramentas (contabilidade, auditoria, formulários), 9 correções de bugs
v2.0.0	2026-05-08	41	+6 ferramentas (batch, CDC, fill_on_basis e outras)
v1.0.0	2026-04-28	35	Primeiro lançamento público

---

🔒 Segurança

Obrigatório para produção

Requisito	Por que é importante
HTTPS	Basic Auth transmite login/senha em base64. Via HTTP eles ficam visíveis para qualquer pessoa na rede
Usuário 1С separado	Crie um usuário mcp_agent com direitos mínimos — apenas os objetos necessários
ONEC_ALLOWED_TOOLS	Limite a lista de ferramentas para o cenário específico

Ferramentas perigosas

As seguintes ferramentas exigem permissão explícita e devem ser usadas com consciência:

Ferramenta	Risco	Recomendação
execute_code	Executa código BSL arbitrário em modo privilegiado	Proibir via ONEC_ALLOWED_TOOLS se não for necessário
delete_object	Marca objetos para exclusão	Proibir em cenários analíticos
run_scheduled_job	Executa tarefas agendadas	Proibir se não for necessário
import_data	Criação/alteração em massa de objetos	Proibir em cenários somente leitura
post_document / unpost_document	Altera lançamentos de documentos e movimentos de registros	Apenas para cenários operacionais

Configuração somente leitura

ONEC_ALLOWED_TOOLS="get_metadata_tree,execute_query,get_object_by_ref,get_list,find_by_code,find_by_name,get_register_records,get_document_list,get_server_info,get_event_log,get_balance,get_register_totals,get_accounting_entries,get_related_documents,get_form_structure,get_rights,find_duplicates"

Mais detalhes — ver EXAMPLES.md.

---

📄 Licença

MIT © 2024-2026 INFATON — Privalov S.Yu.

---

Instruções detalhadas de compilação do .cfe — ver HOW_TO_BUILD_CFE.md

Exemplos de cenários de agentes — ver EXAMPLES.md

Histórico de alterações — ver CHANGELOG.md

---

📰 Publicação no Infostart

Artigo no portal Infostart: INFATON MCP Server v2.1 — 51 ferramenta para integração de IA com 1С:Предприятие