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С:Напарник！