MCP Zero

🚀 Go-Zero MCP 工具

Go-Zero MCP 工具是一款模型上下文協議（MCP）工具，它能助力開發者輕鬆、快速地搭建和生成 Go-Zero 項目。

🚀 快速開始

初次使用 mcp-zero？ 查看我們的 快速開始指南，獲取詳細的入門教程！

快速開始指南涵蓋以下內容：

• 安裝與配置
• 創建首個 API 服務
• 常見用例與工作流程
• 與 Claude Desktop 集成

✨ 主要特性

核心服務生成

• 創建 API 服務：生成新的 REST API 服務，支持自定義端口和樣式。
• 創建 RPC 服務：根據 Protobuf 定義生成 gRPC 服務。
• 生成 API 代碼：將 API 規範文件轉換為 Go 代碼。
• 生成模型：從多種數據源（MySQL、PostgreSQL、MongoDB、DDL）創建數據庫模型。
• 創建 API 規範：生成示例 API 規範文件。

高級特性

• 項目分析：分析現有的 Go-Zero 項目，以瞭解其結構和依賴關係。
• 配置管理：生成具有正確結構驗證的配置文件。
• 模板生成：創建中間件、錯誤處理程序和部署模板。
• 文檔查詢：訪問 Go-Zero 概念和其他框架的遷移指南。
• 輸入驗證：對 API 規範、Protobuf 定義和配置進行全面驗證。

📦 安裝指南

前提條件

1. Go（版本 1.19 或更高）
2. Go-Zero CLI（goctl）：使用命令 go install github.com/zeromicro/go-zero/tools/goctl@latest 進行安裝。
3. Claude Desktop（或其他支持 MCP 的客戶端）

詳細的安裝說明，請參閱 快速開始指南。

安裝步驟

1. 為 MCP 工具創建一個新目錄：

   mkdir go-zero-mcp && cd go-zero-mcp
   

2. 初始化 Go 模塊：

   go mod init go-zero-mcp
   

3. 安裝依賴項：

   go get github.com/modelcontextprotocol/go-sdk
   go get gopkg.in/yaml.v3
   

4. 將主工具代碼保存為 main.go。
5. 構建工具：

   go build -o go-zero-mcp main.go
   

Claude Desktop 配置

將以下配置添加到你的 Claude Desktop MCP 設置中：

macOS

編輯 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-zero": {
      "command": "/path/to/your/mcp-zero",
      "env": {
        "GOCTL_PATH": "/Users/yourname/go/bin/goctl"
      }
    }
  }
}

Linux

編輯 ~/.config/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-zero": {
      "command": "/path/to/your/mcp-zero",
      "env": {
        "GOCTL_PATH": "/usr/local/bin/goctl"
      }
    }
  }
}

Windows

編輯 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-zero": {
      "command": "C:\\path\\to\\your\\mcp-zero.exe",
      "env": {
        "GOCTL_PATH": "C:\\Go\\bin\\goctl.exe"
      }
    }
  }
}

💻 使用示例

創建新的 API 服務

請創建一個名為 "user-service" 的新 Go-Zero API 服務，端口為 8080

創建 RPC 服務

使用以下 Protobuf 定義創建一個名為 "auth-service" 的新 Go-Zero RPC 服務：

syntax = "proto3";

package auth;

option go_package = "./auth";

service AuthService {
  rpc Login(LoginRequest) returns (LoginResponse);
  rpc Logout(LogoutRequest) returns (LogoutResponse);
}

message LoginRequest {
  string username = 1;
  string password = 2;
}

message LoginResponse {
  string token = 1;
  int64 expires_at = 2;
}

message LogoutRequest {
  string token = 1;
}

message LogoutResponse {
  bool success = 1;
}

從數據庫生成模型

從我的 MySQL 數據庫（連接字符串為 "user:password@tcp(localhost:3306)/mydb"）生成 Go-Zero 模型

創建 API 規範

為 "blog-service" 創建一個 API 規範，包含以下端點：
- GET /api/posts（處理程序：GetPostsHandler）
- POST /api/posts（處理程序：CreatePostHandler）
- GET /api/posts/:id（處理程序：GetPostHandler）
- PUT /api/posts/:id（處理程序：UpdatePostHandler）
- DELETE /api/posts/:id（處理程序：DeletePostHandler）

分析項目

分析我位於 /path/to/myproject 的 Go-Zero 項目，以瞭解其結構

生成配置

為我的 "order-service" API 服務生成一個生產環境配置文件

生成模板

為我的 "auth-service" 生成一箇中間件模板

查詢文檔

如何在 Go-Zero 中實現 JWT 身份驗證？

如何從 Express.js 遷移到 Go-Zero？

驗證輸入

啟用嚴格模式，驗證位於 /path/to/service.api 的 API 規範文件

📚 詳細文檔

可用工具

1. create_api_service

創建一個新的 Go-Zero API 服務。 參數：

• service_name（必填）：API 服務的名稱
• port（可選）：端口號（默認值：8888）
• style（可選）：代碼風格 - "go_zero" 或 "gozero"（默認值："go_zero"）
• output_dir（可選）：輸出目錄（默認值：當前目錄）

2. create_rpc_service

根據 Protobuf 定義創建一個新的 Go-Zero RPC 服務。 參數：

• service_name（必填）：RPC 服務的名稱
• proto_content（必填）：Protobuf 定義內容
• output_dir（可選）：輸出目錄（默認值：當前目錄）

3. generate_api_from_spec

根據 API 規範文件生成 Go-Zero API 代碼。 參數：

• api_file（必填）：.api 規範文件的路徑
• output_dir（可選）：輸出目錄（默認值：當前目錄）
• style（可選）：代碼風格 - "go_zero" 或 "gozero"（默認值："go_zero"）

4. generate_model

根據數據庫模式生成數據庫模型代碼。 參數：

• source_type（必填）：源類型 - "mysql"、"postgresql"、"mongo" 或 "ddl"
• source（必填）：數據庫連接字符串或 DDL 文件路徑
• table（可選）：特定表名（針對數據庫源）
• output_dir（可選）：輸出目錄（默認值："./model"）

5. create_api_spec

創建一個示例 API 規範文件。 參數：

• service_name（必填）：API 服務的名稱
• endpoints（必填）：包含方法、路徑和處理程序的端點對象數組
• output_file（可選）：輸出文件路徑（默認值：service_name.api）

6. analyze_project

分析現有的 Go-Zero 項目結構和依賴關係。 參數：

• project_dir（必填）：項目目錄的路徑
• analysis_type（可選）：分析類型 - "api"、"rpc"、"model" 或 "full"（默認值："full"）

7. generate_config

為 Go-Zero 服務生成配置文件。 參數：

• service_name（必填）：服務的名稱
• service_type（必填）：服務類型 - "api" 或 "rpc"
• config_type（可選）：配置類型 - "dev"、"test" 或 "prod"（默認值："dev"）
• output_file（可選）：輸出文件路徑（默認值：etc/{service_name}.yaml）

8. generate_template

為 Go-Zero 服務生成常見的代碼模板。 參數：

• template_type（必填）：模板類型 - "middleware"、"error_handler"、"dockerfile"、"docker_compose" 或 "kubernetes"
• service_name（必填）：服務的名稱
• output_path（可選）：輸出文件路徑（根據模板類型使用默認值）

9. query_docs

查詢 Go-Zero 文檔和遷移指南。 參數：

• query（必填）：關於 Go-Zero 概念或遷移的自然語言查詢
• doc_type（可選）：文檔類型 - "concept"、"migration" 或 "both"（默認值："both"）

10. validate_input

驗證 API 規範、Protobuf 定義或配置文件。 參數：

• input_type（必填）：輸入類型 - "api_spec"、"proto" 或 "config"
• content（必填）：要驗證的內容
• strict（可選）：啟用嚴格驗證模式（默認值：false）

項目結構

構建完成後，你的 MCP 服務器將具有以下結構：

mcp-zero/
├── main.go                    # 入口點和工具註冊
├── tools/                     # 工具實現
│   ├── create_api_service.go
│   ├── create_rpc_service.go
│   ├── generate_api.go
│   ├── generate_model.go
│   ├── create_api_spec.go
│   ├── analyze_project.go
│   ├── generate_config.go
│   ├── generate_template.go
│   ├── query_docs.go
│   └── validate_input.go
├── internal/                  # 內部包
│   ├── analyzer/             # 項目分析
│   ├── validation/           # 輸入驗證
│   ├── security/             # 憑證處理
│   ├── templates/            # 代碼模板
│   ├── docs/                 # 文檔數據庫
│   ├── logging/              # 結構化日誌記錄
│   └── metrics/              # 性能指標
└── tests/                     # 測試套件
    ├── integration/
    └── unit/

架構

MCP 服務器基於以下組件構建：

• MCP SDK：使用 github.com/modelcontextprotocol/go-sdk 實現協議。
• 傳輸：基於標準輸入輸出與 Claude Desktop 進行通信。
• 代碼生成：藉助 Go-Zero 的 goctl CLI 工具生成生產就緒的代碼。
• 驗證：進行全面的輸入驗證，確保安全性和正確性。
• 安全：通過環境變量替換安全處理憑證。
• 可觀測性：內置日誌記錄和指標，用於監控工具性能。

最佳實踐

1. 服務命名：使用小寫字母和連字符（例如，"user-service"、"auth-api"）。
2. 端口配置：為每個服務選擇唯一的端口（建議範圍：8080 - 8090）。
3. 代碼風格：遵循 "go_zero" 風格，以保持與官方約定一致。
4. 配置管理：使用特定環境的配置（開發、測試、生產）。
5. 文檔查詢：定期查詢文檔，以遵循 Go-Zero 最佳實踐。
6. 輸入驗證：在生成代碼之前始終驗證輸入，以便儘早捕獲錯誤。

故障排除

常見問題

1. 找不到 goctl 命令：確保 goctl 已安裝，並已添加到系統的 PATH 環境變量中。
2. 權限被拒絕：確保 MCP 工具可執行文件具有正確的權限。
3. 數據庫連接錯誤：驗證連接字符串和數據庫的可訪問性。

調試模式

要啟用調試日誌記錄，請設置環境變量：

export MCP_DEBUG=1

貢獻

歡迎擴展此工具，添加更多 Go-Zero 特性，例如：

• Dockerfile 生成
• Kubernetes 清單文件生成
• Docker Compose 文件創建
• API 文檔生成
• 測試模板創建

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

版權所有 (c) 2025 Go-Zero 團隊