1C AI MCP - 1С:Напарник용 MCP 서버

IDE를 1С:Напарник API와 통합하기 위한 MCP 서버(Model Context Protocol)입니다. FastMCP(Python) 기반으로 구축되었으며 Docker로 패키징되었습니다. Cursor, Claude Code 및 모든 MCP 호환 클라이언트에서 작동합니다.

12개 도구: 코드 분석(검사, 리뷰, 리팩토링) 및 문서 검색(ITS, 플랫폼, 구성).

comol/1c-code-checker의 아이디어를 기반으로 하며, SteelMorgan/spring-mcp-1c-copilot에서 가져온 API 형식 수정(422 오류)이 적용되었습니다.

사전 요구 사항

• Docker(또는 Docker Desktop)

• 1С:Напарник 토큰 - code.1c.ai에서 획득(ITS 구독 필요)

Related MCP server: 1C_MCP_SERVER_OWN

빠른 시작

옵션 A: Docker Hub의 준비된 이미지(권장)

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

또는 Docker Compose를 통해 - 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

옵션 B: 소스에서 빌드

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

작동 확인

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

IDE 연결

Cursor

~/.cursor/mcp.json에 추가하세요:

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

Claude Code

~/.claude/settings.json에 추가하세요:

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

기타 MCP 클라이언트

엔드포인트: http://localhost:8007/mcp 전송: Streamable HTTP(기본값) 또는 SSE(USESSE=true).

도구

코드 분석

check_1c_code

1C 코드 검사: 구문, 논리, 성능. direct 모드에서는 구문이 upstream syntax-checker를 통해 검사됩니다.

ask_1c_ai

1С:Напарник에 임의의 질문. 호출 간 대화 컨텍스트를 저장합니다.

review_1c_code

코드 리뷰: 스타일, ITS 표준, 명명, 구조, 가독성. 구문은 검사하지 않습니다.

rewrite_1c_code

AI가 변경 사항에 대한 설명과 함께 개선된 코드 버전을 제안합니다.

modify_1c_code

명시적 지시에 따른 코드 수정. 코드가 지정되지 않은 경우 - 새 코드를 생성합니다.

explain_1c_syntax

1C 구문의 특정 요소 설명.

문서 및 도움말

its_help

ITS 지식 베이스 검색(표준, 방법론, 기사). fetch_its용 문서 ID를 반환합니다.

fetch_its

식별자로 ITS 문서 읽기. its_help 이후에 사용됩니다.

search_1c_documentation

특정 버전에 대한 1C:Enterprise 플랫폼 문서 검색.

onec_help

플랫폼 문서 검색(최신 버전). search_1c_documentation과 동일하지만 버전을 지정하지 않습니다.

diff_1c_documentation_versions

두 버전 간 플랫폼 문서 비교.

config_help

애플리케이션 구성 문서 검색(ERP, 회계, ЗУП, УТ 등).

구성

모든 매개변수는 환경 변수를 통해 전달됩니다.

* ONEC_AI_TOKEN 또는 ONEC_AI_TOKEN_FILE이 필수입니다.

Docker Secrets

프로덕션 환경의 경우 토큰을 파일을 통해 전달할 수 있습니다:

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

MCP_TOOL_CALL_MODE=direct인 경우 문서 도구와 check_1c_code(syntax)는 텍스트 프롬프트 대신 1С:Напарник upstream 도구를 이름으로 직접 호출합니다. 더 정확한 결과를 제공합니다.

Upstream 도구:

• mcp__knowledge-hub__Search_ITS - its_help용

• mcp__knowledge-hub__Fetch_ITS - fetch_its용

• mcp__knowledge-hub__Search_Documentation - search_1c_documentation, onec_help용

• mcp__knowledge-hub__Diff_Documentation_Versions - diff_1c_documentation_versions용

• mcp__syntax-checker__validate - check_1c_code(syntax)용

direct 호출 실패 시 프롬프트 모드로 자동 폴백됩니다. 기본값은 하위 호환성을 위한 standard입니다.

아키텍처

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

두 가지 작동 모드

• Standard 모드(기본값): 도구가 텍스트 프롬프트를 구성하여 API로 전송합니다. 문서 도구는 tool chain을 사용합니다 - 모델이 어떤 서버 도구를 호출할지 스스로 결정합니다.

• Direct 모드(MCP_TOOL_CALL_MODE=direct): 도구가 특정 upstream 도구를 이름으로 명시적으로 요청하고, 응답을 매칭하여 호출을 확인합니다. 실패 시 - standard 모드로 자동 폴백됩니다.

SSE 파서

세 가지 API 응답 형식을 지원합니다:

추가로:

• 응답에서 <thinking>/ thinking 블록 자동 제거

• 유니코드 정규화 및 제어 문자 정리

• tool_calls 수신 시 폴백 - skill_name="raw"로 요청 재시도

• ONEC_AI_INPUT_MAX_LENGTH에 따른 입력 데이터 잘라내기

개발

Docker 없이 로컬 실행

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

프로젝트 구조

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

감사의 말

• comol/1c-code-checker - 원래 아이디어(저장소 비공개)

• SteelMorgan/spring-mcp-1c-copilot - 올바른 API 알고리즘

• FastMCP - MCP 서버 프레임워크

라이선스

MIT - LICENSE 참조