1C AI MCP - MCP-Server für 1C:Assistent

MCP-Server (Model Context Protocol) zur Integration von IDEs mit der API 1C:Assistent. Basierend auf FastMCP (Python), verpackt in Docker. Funktioniert mit Cursor, Claude Code und beliebigen MCP-kompatiblen Clients.

12 Tools: Code-Analyse (Prüfung, Review, Refactoring) und Dokumentationssuche (ITS, Plattform, Konfigurationen).

Basiert auf der Idee von comol/1c-code-checker mit Korrekturen des API-Formats (Fehler 422), übernommen aus SteelMorgan/spring-mcp-1c-copilot.

Voraussetzungen

• Docker (oder Docker Desktop)

• 1C:Assistent-Token - erhalten Sie auf code.1c.ai (ITS-Abonnement erforderlich)

Related MCP server: 1C_MCP_SERVER_OWN

Schnellstart

Variante A: Fertiges Image von Docker Hub (empfohlen)

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

Oder über Docker Compose - erstellen Sie die Datei 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

Variante B: Build aus dem Quellcode

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

Funktionsprüfung

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

Verbindung zur IDE

Cursor

Fügen Sie in ~/.cursor/mcp.json hinzu:

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

Claude Code

Fügen Sie in ~/.claude/settings.json hinzu:

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

Andere MCP-Clients

Endpoint: http://localhost:8007/mcp Transport: Streamable HTTP (Standard) oder SSE (USESSE=true).

Tools

Code-Analyse

check_1c_code

Prüfung von 1C-Code: Syntax, Logik, Performance. Im Direct-Mode wird die Syntax über den Upstream-Syntax-Checker geprüft.

ask_1c_ai

Beliebige Frage an 1C:Assistent. Speichert den Dialogkontext zwischen Aufrufen.

review_1c_code

Code-Review: Stil, ITS-Standards, Benennung, Struktur, Lesbarkeit. Prüft keine Syntax.

rewrite_1c_code

Die KI schlägt eine eigene verbesserte Version des Codes mit Erklärung der Änderungen vor.

modify_1c_code

Modifikation des Codes gemäß expliziter Anweisung. Wenn kein Code angegeben ist - wird neuer generiert.

explain_1c_syntax

Erklärung eines konkreten Syntaxelements von 1C.

Dokumentation und Hilfe

its_help

Suche in der ITS-Wissensdatenbank (Standards, Methodiken, Artikel). Gibt Dokument-IDs für fetch_its zurück.

fetch_its

Lesen eines ITS-Dokuments anhand der ID. Wird nach its_help verwendet.

search_1c_documentation

Suche in der Dokumentation der Plattform 1C:Enterprise für eine bestimmte Version.

onec_help

Suche in der Plattformdokumentation (neueste Version). Wie search_1c_documentation, aber ohne Versionsangabe.

diff_1c_documentation_versions

Vergleich der Plattformdokumentation zwischen zwei Versionen.

config_help

Suche in der Dokumentation zu angewandten Konfigurationen (ERP, Buchhaltung, ZUP, UT u. a.).

Konfiguration

Alle Parameter werden über Umgebungsvariablen übergeben.

* Erforderlich ist ONEC_AI_TOKEN oder ONEC_AI_TOKEN_FILE.

Docker Secrets

Für Produktionsumgebungen kann das Token über eine Datei übergeben werden:

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

Direct Mode

Bei MCP_TOOL_CALL_MODE=direct rufen die Dokumentationstools und check_1c_code (syntax) die Upstream-Tools von 1C:Assistent direkt beim Namen auf, statt Text-Prompts zu verwenden. Dies liefert genauere Ergebnisse.

Upstream-Tools:

• mcp__knowledge-hub__Search_ITS - für its_help

• mcp__knowledge-hub__Fetch_ITS - für fetch_its

• mcp__knowledge-hub__Search_Documentation - für search_1c_documentation, onec_help

• mcp__knowledge-hub__Diff_Documentation_Versions - für diff_1c_documentation_versions

• mcp__syntax-checker__validate - für check_1c_code (syntax)

Bei einem Fehler des Direct-Aufrufs erfolgt automatisch ein Fallback auf den Prompt-Modus. Standardmäßig standard für Abwärtskompatibilität.

Architektur

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

Zwei Betriebsmodi

• Standard-Modus (Standard): Die Tools erstellen Text-Prompts und senden sie an die API. Die Dokumentationstools verwenden eine Tool-Chain - das Modell entscheidet selbst, welches Server-Tool aufgerufen wird.

• Direct-Modus (MCP_TOOL_CALL_MODE=direct): Die Tools fordern explizit ein bestimmtes Upstream-Tool beim Namen an, matchen die Antwort und bestätigen den Aufruf. Bei einem Fehler - automatischer Fallback auf den Standard-Modus.

SSE-Parser

Unterstützt drei Antwortformate der API:

Zusätzlich:

• Automatisches Entfernen von <thinking>/ thinking-Blöcken aus Antworten

• Unicode-Normalisierung und Bereinigung von Steuerzeichen

• Fallback bei Erhalt von tool_calls - erneute Anfrage mit skill_name="raw"

• Kürzung der Eingabedaten gemäß ONEC_AI_INPUT_MAX_LENGTH

Entwicklung

Lokaler Start ohne Docker

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

Projektstruktur

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

Danksagungen

• comol/1c-code-checker - ursprüngliche Idee (Repository geschlossen)

• SteelMorgan/spring-mcp-1c-copilot - korrekte API-Algorithmen

• FastMCP - Framework für MCP-Server

Lizenz

MIT - siehe LICENSE