Spring MCP 1c Copilot

🚀 Spring Boot MCP Server для 1С:Напарник

這是一個功能完備的 MCP（Model Context Protocol）服務器，用於與 1С:Напарник API 進行集成，能助力開發者更高效地開展工作。

📄 許可證：本項目採用開源許可證，允許個人和非商業用途使用。商業使用需獲得作者許可。

✨ 主要特性

• 🎯 MCP 協議支持：全面支持 MCP 協議，可與 AI 助手實現無縫集成。
• 🤖 1С:Напарник 集成：通過正確的端點與 1С:Напарник API 直接集成。
• ⚡ SSE 支持：支持 Server-Sent Events，實現即時通信。
• 🌐 REST API：提供額外的 REST 端點，方便直接交互。
• 📚 Swagger UI：具備交互式 API 文檔，便於開發者查看和測試。
• 🐳 Docker 就緒：提供現成的 Docker 配置，方便部署。
• 🔐 授權機制：支持使用 Bearer 令牌訪問 1С:Напарник API。

🛠️ MCP 工具

1. ask_1c_ai

向 1С:Напарник AI 提問。

• question（必填）：向 AI 提出的問題。
• programming_language（可選）：編程語言。
• create_new_session（可選）：是否創建新會話。

2. explain_1c_syntax

解釋 1С 元素的語法。

• syntax_element（必填）：需要解釋的語法元素。
• context（可選）：使用上下文。

3. check_1c_code

檢查 1С 代碼是否存在錯誤。

• code（必填）：需要檢查的 1С 代碼。
• check_type（可選）：檢查類型（語法、邏輯、性能）。

🚀 快速開始

要求

• Java 17 及以上版本。
• 建議安裝 Docker。
• 獲取 1С:Напарник API 訪問令牌。

1. 獲取 1С:Напарник 令牌

1. 在 code.1c.ai 上註冊賬號。
2. 在個人控制面板中獲取訪問令牌。
3. 將令牌保存，以便在環境變量中使用。

2. 本地啟動

# 克隆倉庫
git clone <repository-url>
cd spring-mcp-1c-copilot

# 設置環境變量
export ONEC_AI_TOKEN="your_token_here"
export ONEC_AI_BASE_URL="https://code.1c.ai"

# 啟動應用程序
./gradlew bootRun

3. Docker 啟動（推薦）

# 構建鏡像
docker build -f Dockerfile.build -t spring-mcp-1c-copilot .

# 運行容器
docker run -d --name spring-mcp-1c-copilot -p 8000:8000 \
  -e ONEC_AI_TOKEN="your_token_here" \
  spring-mcp-1c-copilot

📡 API 端點

MCP 端點

• POST /mcp - 主要的 MCP 端點，用於處理 JSON-RPC 請求。
• GET /mcp - 為 MCP 客戶端提供 SSE 流。

REST API 端點

• POST /api/ask-ai - 向 1С:Напарник AI 提問。
• POST /api/explain-syntax - 解釋 1С 語法。
• POST /api/check-code - 檢查 1С 代碼錯誤。
• GET /api/health - 檢查服務器狀態。

文檔

• http://localhost:8000/swagger-ui.html - Swagger UI 交互式文檔。
• http://localhost:8000/api-docs - OpenAPI JSON 模式。

⚙️ 配置

環境變量

application.yml

onec:
  ai:
    token: ${ONEC_AI_TOKEN:}
    base-url: ${ONEC_AI_BASE_URL:https://code.1c.ai}
    timeout: ${ONEC_AI_TIMEOUT:30}

server:
  port: ${SSE_PORT:8000}

springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html
    enabled: true

🔗 與 Cursor IDE 集成

在 ~/.cursor/mcp.json 中添加以下內容：

{
  "servers": {
    "1c-copilot-proxy": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

完成上述操作後，在 Cursor IDE 中即可使用所有與 1С:Напарник 相關的工具。

🏗️ 項目結構

src/main/kotlin/ru/alkoleft/copilot/
├── McpCopilotApplication.kt          # 應用程序主類
├── config/
│   ├── McpConfiguration.kt           # MCP 配置
│   └── OpenApiConfig.kt              # Swagger 配置
├── controller/
│   ├── McpController.kt              # MCP 控制器
│   └── RestApiController.kt          # REST API 控制器
└── service/
    ├── OneCApiClient.kt              # 1С:Напарник API 客戶端
    └── OneCCopilotService.kt         # 包含 MCP 工具的服務

🧪 測試

MCP 初始化測試

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {"tools": true}
    }
  }'

REST API 測試

curl -X POST "http://localhost:8000/api/ask-ai?question=Как создать справочник в 1С?"

🔧 開發

構建項目

./gradlew build

運行測試

./gradlew test

本地開發

./gradlew bootRun --args='--spring.profiles.active=dev'

📋 日誌與調試

查看 Docker 容器日誌

docker logs spring-mcp-1c-copilot --follow

日誌級別

• DEBUG - 詳細的開發日誌。
• INFO - 主要事件日誌（默認級別）。
• WARN - 警告日誌。
• ERROR - 錯誤日誌。

🚀 生產部署

詳細的服務器部署指南請參考 DEPLOYMENT.md。

🙏 致謝

本項目基於以下倉庫的工作成果進行開發：

• artesk/1copilot_MCP - 最初的基於 Python 的 1С:Напарник MCP 服務器。
• rentgengl/copilot-1c-proxy - 用於向 1С:Напарник 發送請求的代理服務器。

衷心感謝這些項目的作者！🎉

本 Spring Boot MCP Server 在這些項目的基礎上進行了拓展，新增了以下特性：

• 採用 Spring Boot 和 Kotlin 構建的現代架構。
• 全面支持帶有 SSE 的 MCP 協議。
• 集成 Swagger UI 文檔。
• 提供生產環境可用的配置。
• 實現部署自動化。

🤝 貢獻代碼

1. Fork 本倉庫。
2. 創建功能分支 (git checkout -b feature/amazing-feature)。
3. 提交更改 (git commit -m 'Add amazing feature')。
4. 將分支推送到遠程倉庫 (git push origin feature/amazing-feature)。
5. 發起 Pull Request。

📄 許可證

許可證：開源（個人和非商業用途）

• ✅ 個人使用 - 免費。
• ✅ 非商業使用 - 免費。
• ✅ 教育用途 - 免費。
• ❌ 商業使用 - 需獲得作者許可。

如需商業使用許可，請聯繫作者。

相關項目許可證：

• artesk/1copilot_MCP - Unlicense
• rentgengl/copilot-1c-proxy - MIT License

🆘 支持

若您遇到問題，請按以下步驟解決：

1. 查看 Issues。
2. 確保 1С:Напарник 令牌有效。
3. 查看容器日誌：docker logs spring-mcp-1c-copilot。
4. 若問題仍未解決，請創建新的 Issue 並詳細描述問題。

🎉 祝您通過 MCP 愉快地使用 1С:Напарник！