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クライアント

Endpoint: http://localhost:8007/mcp トランスポート: Streamable HTTP（デフォルト）またはSSE（USESSE=true）。

ツール

コード分析

check_1c_code

1Сコードのチェック：構文、ロジック、パフォーマンス。directモードでは、構文はupstreamのsyntax-checkerを通じて検証されます。

ask_1c_ai

1С:Напарникへの任意の質問。呼び出し間でダイアログのコンテキストを保持します。

review_1c_code

コードレビュー：スタイル、ITS標準、命名、構造、可読性。構文はチェックしません。

rewrite_1c_code

AIが変更の説明付きで改善されたコードのバージョンを提案します。

modify_1c_code

明示的な指示に基づくコードの修正。コードが指定されていない場合は、新しいコードを生成します。

explain_1c_syntax

1С構文の特定の要素の説明。

ドキュメントとヘルプ

its_help

ITSナレッジベースの検索（標準、方法論、記事）。fetch_its用のドキュメントIDを返します。

fetch_its

IDによるITSドキュメントの読み取り。its_helpの後に使用します。

search_1c_documentation

特定のバージョンの1С:Предприятиеプラットフォームのドキュメントを検索します。

onec_help

プラットフォームのドキュメントの検索（最新バージョン）。search_1c_documentationと同じですが、バージョンの指定はありません。

diff_1c_documentation_versions

2つのバージョン間のプラットフォームドキュメントの比較。

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-стриминг)
          -> парсинг ответа -> возврат клиенту

2つの動作モード

• Standardモード（デフォルト）：ツールはテキストプロンプトを生成してAPIに送信します。ドキュメントツールはツールチェーンを使用します - モデルがどのサーバーツールを呼び出すかを自ら決定します。

• Directモード（MCP_TOOL_CALL_MODE=direct）：ツールは特定のupstreamツールを名前で明示的に要求し、応答をマッチングして呼び出しを確認します。失敗時はstandardモードに自動フォールバックします。

SSEパーサー

API応答の3つの形式をサポートします：

さらに：

• 応答からの<thinking>/ thinkingブロックの自動削除

• Unicode正規化と制御文字のクリーンアップ

• 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を参照