Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/zeromicro/mcp-zero

Model Context Protocol (MCP) server for go-zero framework - Generate APIs, RPC services, and models with AI assistance.
https://github.com/zeromicro/mcp-zero

ai-tools code-generation go-zero golang grpc mcp microservices model-context-protocol web-development

Last synced: 1 day ago
JSON representation

Model Context Protocol (MCP) server for go-zero framework - Generate APIs, RPC services, and models with AI assistance.

Awesome Lists containing this project

README 

          
# Go-Zero MCP Tool



A Model Context Protocol (MCP) tool that helps developers quickly scaffold and generate go-zero projects with ease.



## Quick Start



**New to mcp-zero?** Check out our [Quick Start Guide](QUICKSTART.md) for a step-by-step tutorial on getting started!



The quickstart covers:



- Installation and configuration

- Creating your first API service

- Common use cases and workflows

- Integration with Claude Desktop



## Features



### Core Service Generation



- **Create API Services**: Generate new REST API services with customizable ports and styles

- **Create RPC Services**: Generate gRPC services from protobuf definitions

- **Generate API Code**: Convert API specification files to Go code

- **Generate Models**: Create database models from various sources (MySQL, PostgreSQL, MongoDB, DDL)

- **Create API Specs**: Generate sample API specification files



### Advanced Features



- **Analyze Projects**: Analyze existing go-zero projects to understand structure and dependencies

- **Manage Configuration**: Generate configuration files with proper structure validation

- **Generate Templates**: Create middleware, error handlers, and deployment templates

- **Query Documentation**: Access go-zero concepts and migration guides from other frameworks

- **Validate Input**: Comprehensive validation for API specs, protobuf definitions, and configurations



## Prerequisites



1. **Go** (1.19 or later)



2. **go-zero CLI (goctl)**: Install with `go install github.com/zeromicro/go-zero/tools/goctl@latest`



3. **Claude Desktop** (or other MCP-compatible client)



For detailed installation instructions, see the [Quick Start Guide](QUICKSTART.md).



## Installation



1. Create a new directory for your MCP tool:



   ```bash

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

   ```



2. Initialize Go module:



   ```bash

   go mod init go-zero-mcp

   ```



3. Install dependencies:



   ```bash

   go get github.com/modelcontextprotocol/go-sdk

   go get gopkg.in/yaml.v3

   ```



4. Save the main tool code as `main.go`



5. Build the tool:



   ```bash

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

   ```



## Configuration for Claude Desktop



Add this configuration to your Claude Desktop MCP settings:



### macOS



Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:



```json

{

  "mcpServers": {

    "mcp-zero": {

      "command": "/path/to/your/mcp-zero",

      "env": {

        "GOCTL_PATH": "/Users/yourname/go/bin/goctl"

      }

    }

  }

}

```



### Linux



Edit `~/.config/Claude/claude_desktop_config.json`:



```json

{

  "mcpServers": {

    "mcp-zero": {

      "command": "/path/to/your/mcp-zero",

      "env": {

        "GOCTL_PATH": "/usr/local/bin/goctl"

      }

    }

  }

}

```



### Windows



Edit `%APPDATA%\Claude\claude_desktop_config.json`:



```json

{

  "mcpServers": {

    "mcp-zero": {

      "command": "C:\\path\\to\\your\\mcp-zero.exe",

      "env": {

        "GOCTL_PATH": "C:\\Go\\bin\\goctl.exe"

      }

    }

  }

}

```



## Available Tools



### 1. create_api_service



Creates a new go-zero API service.



**Parameters:**



- `service_name` (required): Name of the API service

- `port` (optional): Port number (default: 8888)

- `style` (optional): Code style - "go_zero" or "gozero" (default: "go_zero")

- `output_dir` (optional): Output directory (default: current directory)



### 2. create_rpc_service



Creates a new go-zero RPC service from protobuf definition.



**Parameters:**



- `service_name` (required): Name of the RPC service

- `proto_content` (required): Protobuf definition content

- `output_dir` (optional): Output directory (default: current directory)



### 3. generate_api_from_spec



Generates go-zero API code from an API specification file.



**Parameters:**



- `api_file` (required): Path to the .api specification file

- `output_dir` (optional): Output directory (default: current directory)

- `style` (optional): Code style - "go_zero" or "gozero" (default: "go_zero")



### 4. generate_model



Generates database model code from database schema.



**Parameters:**



- `source_type` (required): Source type - "mysql", "postgresql", "mongo", or "ddl"

- `source` (required): Database connection string or DDL file path

- `table` (optional): Specific table name (for database sources)

- `output_dir` (optional): Output directory (default: "./model")



### 5. create_api_spec



Creates a sample API specification file.



**Parameters:**



- `service_name` (required): Name of the API service

- `endpoints` (required): Array of endpoint objects with method, path, and handler

- `output_file` (optional): Output file path (default: service_name.api)



### 6. analyze_project



Analyzes an existing go-zero project structure and dependencies.



**Parameters:**



- `project_dir` (required): Path to the project directory

- `analysis_type` (optional): Type of analysis - "api", "rpc", "model", or "full" (default: "full")



### 7. generate_config



Generates configuration files for go-zero services.



**Parameters:**



- `service_name` (required): Name of the service

- `service_type` (required): Service type - "api" or "rpc"

- `config_type` (optional): Configuration type - "dev", "test", or "prod" (default: "dev")

- `output_file` (optional): Output file path (default: etc/{service_name}.yaml)



### 8. generate_template



Generates common code templates for go-zero services.



**Parameters:**



- `template_type` (required): Template type - "middleware", "error_handler", "dockerfile", "docker_compose", or "kubernetes"

- `service_name` (required): Name of the service

- `output_path` (optional): Output file path (uses defaults based on template type)



### 9. query_docs



Queries go-zero documentation and migration guides.



**Parameters:**



- `query` (required): Natural language query about go-zero concepts or migration

- `doc_type` (optional): Documentation type - "concept", "migration", or "both" (default: "both")



### 10. validate_input



Validates API specs, protobuf definitions, or configuration files.



**Parameters:**



- `input_type` (required): Input type - "api_spec", "proto", or "config"

- `content` (required): Content to validate

- `strict` (optional): Enable strict validation mode (default: false)



## Usage Examples



### Creating a New API Service



```text

Please create a new go-zero API service called "user-service" on port 8080

```



### Creating an RPC Service



```text

Create a new go-zero RPC service called "auth-service" with this protobuf definition:



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;

}

```



### Generating Models from Database



```text

Generate go-zero models from my MySQL database with connection string "user:password@tcp(localhost:3306)/mydb"

```



### Creating an API Specification



```text

Create an API specification for a "blog-service" with these endpoints:

- GET /api/posts (handler: GetPostsHandler)

- POST /api/posts (handler: CreatePostHandler)

- GET /api/posts/:id (handler: GetPostHandler)

- PUT /api/posts/:id (handler: UpdatePostHandler)

- DELETE /api/posts/:id (handler: DeletePostHandler)

```



### Analyzing a Project



```text

Analyze my go-zero project in /path/to/myproject to understand its structure

```



### Generating Configuration



```text

Generate a production configuration file for my "order-service" API service

```



### Generating Templates



```text

Generate a middleware template for my "auth-service"

```



### Querying Documentation



```text

How do I implement JWT authentication in go-zero?

```



```text

How do I migrate from Express.js to go-zero?

```



### Validating Input



```text

Validate this API spec file at /path/to/service.api with strict mode enabled

```



## Project Structure



After building, your MCP server will have the following structure:



```text

mcp-zero/

├── main.go                    # Entry point and tool registration

├── tools/                     # Tool implementations

│   ├── 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/                  # Internal packages

│   ├── analyzer/             # Project analysis

│   ├── validation/           # Input validation

│   ├── security/             # Credential handling

│   ├── templates/            # Code templates

│   ├── docs/                 # Documentation database

│   ├── logging/              # Structured logging

│   └── metrics/              # Performance metrics

└── tests/                     # Test suites

    ├── integration/

    └── unit/

```



## Architecture



The MCP server is built with:



- **MCP SDK**: Uses github.com/modelcontextprotocol/go-sdk for protocol implementation

- **Transport**: stdio-based communication with Claude Desktop

- **Code Generation**: Leverages go-zero's goctl CLI tool for generating production-ready code

- **Validation**: Comprehensive input validation for safety and correctness

- **Security**: Safe credential handling with environment variable substitution

- **Observability**: Built-in logging and metrics for monitoring tool performance



## Best Practices



1. **Service Naming**: Use lowercase with hyphens (e.g., "user-service", "auth-api")

2. **Port Configuration**: Choose unique ports for each service (8080-8090 range recommended)

3. **Code Style**: Stick to "go_zero" style for consistency with official conventions

4. **Configuration**: Use environment-specific configs (dev, test, prod)

5. **Documentation**: Query docs regularly to stay aligned with go-zero best practices

6. **Validation**: Always validate inputs before generation to catch errors early



## Troubleshooting



### Common Issues



1. **goctl command not found**: Make sure goctl is installed and in your PATH

2. **Permission denied**: Ensure the MCP tool executable has proper permissions

3. **Database connection errors**: Verify connection strings and database accessibility



### Debug Mode



To enable debug logging, set the environment variable:



```bash

export MCP_DEBUG=1

```



## Contributing



Feel free to extend this tool with additional go-zero features such as:



- Dockerfile generation

- Kubernetes manifest generation

- Docker Compose file creation

- API documentation generation

- Testing template creation



## License



MIT License - see [LICENSE](LICENSE) file for details.



Copyright (c) 2025 go-zero team