1C AI MCP - Servidor MCP para 1С:Напарник

Servidor MCP (Model Context Protocol) para integrar IDE con la API de 1С:Напарник. Construido sobre FastMCP (Python), empaquetado en Docker. Funciona con Cursor, Claude Code y cualquier cliente compatible con MCP.

12 herramientas: análisis de código (verificación, revisión, refactorización) y búsqueda en documentación (ITS, plataforma, configuraciones).

Basado en la idea de comol/1c-code-checker con correcciones del formato de API (errores 422), tomadas de SteelMorgan/spring-mcp-1c-copilot.

Requisitos previos

• Docker (o Docker Desktop)

• Token de 1С:Напарник - obtener en code.1c.ai (se requiere suscripción a ITS)

Related MCP server: 1C_MCP_SERVER_OWN

Inicio rápido

Opción A: Imagen lista de Docker Hub (recomendada)

docker run -d --name 1c-ai-mcp -p 8007:8007 \
  -e ONEC_AI_TOKEN="ваш-токен" \
  desko77/1c-ai-mcp:latest

O mediante Docker Compose - cree el archivo docker-compose.yml:

services:
  1c-ai-mcp:
    image: desko77/1c-ai-mcp:latest
    container_name: 1c-ai-mcp
    ports:
      - "8007:8007"
    environment:
      ONEC_AI_TOKEN: "${ONEC_AI_TOKEN}"
    restart: always

# Создать .env с токеном (не попадает в git)
echo 'ONEC_AI_TOKEN=ваш-токен' > .env

# Запустить
docker compose up -d

Opción B: Compilación desde el código fuente

git clone https://github.com/Desko77/1c-ai-mcp.git
cd 1c-ai-mcp

# Создать .env с токеном
echo 'ONEC_AI_TOKEN=ваш-токен' > .env

# Собрать и запустить
docker compose up -d --build

Verificación de funcionamiento

# Должен вернуть HTTP 200
curl http://localhost:8007/mcp

Conexión a IDE

Cursor

Agregue en ~/.cursor/mcp.json:

{
  "mcpServers": {
    "1c-naparnik": {
      "url": "http://localhost:8007/mcp"
    }
  }
}

Claude Code

Agregue en ~/.claude/settings.json:

{
  "mcpServers": {
    "1c-naparnik": {
      "url": "http://localhost:8007/mcp"
    }
  }
}

Otros clientes MCP

Endpoint: http://localhost:8007/mcp Transporte: Streamable HTTP (por defecto) o SSE (USESSE=true).

Herramientas

Análisis de código

check_1c_code

Verificación de código 1С: sintaxis, lógica, rendimiento. En modo directo, la sintaxis se verifica mediante el verificador de sintaxis upstream.

ask_1c_ai

Pregunta arbitraria a 1С:Напарник. Guarda el contexto del diálogo entre llamadas.

review_1c_code

Revisión de código: estilo, estándares ITS, nomenclatura, estructura, legibilidad. No verifica sintaxis.

rewrite_1c_code

La IA propone su versión mejorada del código con explicación de los cambios.

modify_1c_code

Modificación del código según instrucción explícita. Si no se especifica código, genera uno nuevo.

explain_1c_syntax

Explicación de un elemento específico de la sintaxis de 1С.

Documentación y ayuda

its_help

Búsqueda en la base de conocimientos ITS (estándares, metodologías, artículos). Devuelve IDs de documentos para fetch_its.

fetch_its

Lectura de un documento ITS por identificador. Se usa después de its_help.

search_1c_documentation

Búsqueda en la documentación de la plataforma 1С:Предприятие para una versión específica.

onec_help

Búsqueda en la documentación de la plataforma (última versión). Como search_1c_documentation, pero sin especificar versión.

diff_1c_documentation_versions

Comparación de la documentación de la plataforma entre dos versiones.

config_help

Búsqueda de documentación sobre configuraciones aplicadas (ERP, Бухгалтерия, ЗУП, УТ, etc.).

Configuración

Todos los parámetros se pasan mediante variables de entorno.

* Es obligatorio ONEC_AI_TOKEN o ONEC_AI_TOKEN_FILE.

Docker Secrets

Para entornos de producción, el token se puede pasar mediante un archivo:

services:
  1c-ai-mcp:
    image: desko77/1c-ai-mcp:latest
    environment:
      ONEC_AI_TOKEN_FILE: /run/secrets/onec_token
    secrets:
      - onec_token

secrets:
  onec_token:
    file: ./onec_token.txt

Modo Directo

Con MCP_TOOL_CALL_MODE=direct, las herramientas de documentación y check_1c_code (syntax) llaman directamente a las herramientas upstream de 1С:Напарник por nombre, en lugar de prompts de texto. Esto da resultados más precisos.

Herramientas upstream:

• mcp__knowledge-hub__Search_ITS - para its_help

• mcp__knowledge-hub__Fetch_ITS - para fetch_its

• mcp__knowledge-hub__Search_Documentation - para search_1c_documentation, onec_help

• mcp__knowledge-hub__Diff_Documentation_Versions - para diff_1c_documentation_versions

• mcp__syntax-checker__validate - para check_1c_code (syntax)

Ante un fallo de la llamada directa, se produce un fallback automático al modo prompt. Por defecto es standard para compatibilidad inversa.

Arquitectura

MCP-клиент (Cursor / Claude Code)
  -> FastMCP HTTP endpoint (:8007/mcp)
    -> mcp_server.py (обработчики инструментов)
      -> OneCApiClient (HTTP-клиент)
        -> code.1c.ai API (SSE-стриминг)
          -> парсинг ответа -> возврат клиенту

Dos modos de funcionamiento

• Modo estándar (por defecto): las herramientas forman prompts de texto y los envían a la API. Las herramientas de documentación usan la cadena de herramientas: el modelo decide qué herramienta del servidor llamar.

• Modo directo (MCP_TOOL_CALL_MODE=direct): las herramientas solicitan explícitamente una herramienta upstream específica por nombre, comparan la respuesta y confirman la llamada. Ante un fallo, se produce un fallback automático al modo estándar.

Analizador SSE

Soporta tres formatos de respuesta de la API:

Además:

• Eliminación automática de bloques <thinking>/ thinking de las respuestas

• Normalización Unicode y limpieza de caracteres de control

• Fallback al recibir tool_calls - repetición de la solicitud con skill_name="raw"

• Recorte de datos de entrada según ONEC_AI_INPUT_MAX_LENGTH

Desarrollo

Ejecución local sin Docker

pip install -r requirements.txt
export ONEC_AI_TOKEN="ваш-токен"
python main.py

Estructura del proyecto

main.py                       # Точка входа
src/
  mcp_server.py                # MCP-инструменты (@mcp.tool)
  onec_api_client.py           # HTTP-клиент к API 1С:Напарник
Dockerfile                     # Dockerfile
docker-compose.yml             # Compose для сборки из исходников
tests/                         # Тестовые скрипты
.github/workflows/
  docker-publish.yml           # CI: сборка и публикация в Docker Hub

Agradecimientos

• comol/1c-code-checker - idea original (repositorio cerrado)

• SteelMorgan/spring-mcp-1c-copilot - algoritmos correctos de la API

• FastMCP - framework de servidores MCP

Licencia

MIT - ver LICENSE