yakuter/ugin-mcp

Ugin MCP Server

A Model Context Protocol (MCP) server for the Ugin web framework. This server provides AI assistants (Claude, Gemini, etc.) with tools to help developers scaffold projects, generate code, and follow best practices when building web applications with Ugin.

🌟 Dual Mode Support

• MCP/stdio Mode: For Claude Desktop and MCP-compatible clients
• HTTP REST API Mode: For Google Gemini, web interfaces, and any HTTP client

Features

Tools Available

1. scaffold_project - Create a new Ugin project with proper structure and boilerplate code
2. create_route - Generate code for new HTTP route handlers
3. create_middleware - Generate custom middleware code
4. create_model - Generate model structs with optional JSON/DB tags and CRUD methods
5. generate_crud_handler - Generate complete CRUD handlers for a resource (List, Get, Create, Update, Delete)
6. create_config - Generate configuration file templates (environment, database, server)
7. get_example - Get example code for common use cases
8. get_best_practices - Get best practices for various development topics

Installation

Prerequisites

• Go 1.23 or higher
• An MCP-compatible client (like Claude Desktop)

Build from Source

git clone https://github.com/yakuter/ugin-mcp.git
cd ugin-mcp
go mod tidy
go build -o ugin-mcp

Usage

Running the Server

Mode 1: MCP/stdio (for Claude Desktop)

# Default mode - for MCP clients like Claude Desktop
./ugin-mcp

# Or explicitly specify stdio mode
./ugin-mcp --mode=stdio

Mode 2: HTTP REST API (for Gemini and others)

# HTTP mode on port 8080
./ugin-mcp --mode=http --port=8080

# Or use a different port
./ugin-mcp --mode=http --port=3000

Test the HTTP server:

curl http://localhost:8080/health

Configuration for Claude Desktop

Add this to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ugin": {
      "command": "/path/to/ugin-mcp",
      "args": []
    }
  }
}

Replace /path/to/ugin-mcp with the actual path to your built binary.

Configuration for Google Gemini

1. Start the HTTP server:

   ./ugin-mcp --mode=http --port=8080
   

2. Use with Gemini Function Calling:

   See for detailed instructions including:

   • Python integration examples
   • Function declarations for Gemini
   • Web interface examples
   • Complete code samples

Quick example:

import requests

# Call any tool via HTTP
response = requests.post('http://localhost:8080/api/generate_crud_handler', 
    json={
        "resource_name": "User",
        "route_prefix": "/api/users"
    })
    
result = response.json()
print(result['data'])

Tool Documentation

scaffold_project

Creates a complete new Ugin project with directory structure, configuration files, and starter code.

Input:

{
  "project_name": "my-api",
  "module_path": "github.com/user/my-api",
  "directory": "./projects"
}

Output:

• Project directory with complete structure
• go.mod and main.go
• Directory structure (handlers/, middleware/, models/, config/, utils/)
• README.md and .gitignore

create_route

Generates handler code for a new HTTP route.

Input:

{
  "method": "POST",
  "path": "/api/users",
  "handler_name": "CreateUser",
  "description": "Creates a new user"
}

Output:

• Handler function code
• Route registration code

create_middleware

Generates custom middleware code.

Input:

{
  "name": "RateLimiter",
  "description": "Rate limiting middleware to prevent abuse"
}

Output:

• Complete middleware function with usage example

create_model

Generates model struct code with optional tags and methods.

Input:

{
  "model_name": "User",
  "fields": {
    "id": "int",
    "email": "string",
    "created_at": "time.Time"
  },
  "with_json": true,
  "with_db": true,
  "with_methods": true
}

Output:

• Model struct with requested tags
• CRUD method stubs (if requested)

get_example

Retrieves complete example code for common patterns.

Available Examples:

• basic-server - Basic Ugin server setup
• crud-api - Complete CRUD API implementation
• middleware - Custom middleware examples
• auth - Authentication system with registration/login
• websocket - WebSocket implementation with chat example

Input:

{
  "example_type": "crud-api"
}

generate_crud_handler

Generates complete CRUD (Create, Read, Update, Delete) handlers for a resource.

Input:

{
  "resource_name": "Product",
  "route_prefix": "/api/products",
  "with_db": true
}

Output:

• Complete handler code with all CRUD operations
• Route registration code
• Model example structure

create_config

Generates configuration file templates for various purposes.

Available Config Types:

• env - Environment variables template (.env.example)
• database - Database configuration code
• server - Server configuration code

Input:

{
  "config_type": "database"
}

Output:

• Configuration code
• Recommended filename

get_best_practices

Provides best practices for various development topics.

Available Topics:

• structure - Project structure and organization
• error-handling - Error handling patterns
• security - Security best practices
• validation - Input validation
• logging - Logging best practices
• performance - Performance optimization
• testing - Testing strategies

Input:

{
  "topic": "security"
}

Example Workflow

Here's how an AI assistant might use these tools to help a developer:

1. Create a new project:

   User: "Create a new API project called user-service"
   AI uses: scaffold_project
   

2. Add a new endpoint:

   User: "Add a POST endpoint for creating users"
   AI uses: create_route
   

3. Create a model:

   User: "Create a User model with id, email, and password fields"
   AI uses: create_model
   

4. Add middleware:

   User: "Add authentication middleware"
   AI uses: create_middleware or get_example with "auth"
   

5. Get guidance:

   User: "What are the security best practices?"
   AI uses: get_best_practices with topic "security"
   

Development

Project Structure

ugin-mcp/
├── main.go           # MCP server implementation
├── go.mod           # Go module definition
├── README.md        # This file
└── examples/        # Example configurations (optional)

Adding New Tools

To add a new tool to the MCP server:

1. Define input and output structs
2. Implement the tool function with signature:

   func ToolName(ctx context.Context, req *mcp.CallToolRequest, input InputType) (
       *mcp.CallToolResult,
       OutputType,
       error,
   )
   

3. Register the tool in main():

   mcp.AddTool(
       server,
       &mcp.Tool{
           Name:        "tool_name",
           Description: "Tool description",
       },
       ToolName,
   )
   

HTTP API Endpoints

When running in HTTP mode, the following endpoints are available:

All POST endpoints accept and return JSON. See for examples.

About Ugin

Ugin is a lightweight, high-performance web framework for Go, inspired by Gin. It provides:

• Fast HTTP routing
• Middleware support
• JSON validation
• Error management
• Group routing
• And more...

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related Links

• Ugin Framework
• MCP Go SDK
• Model Context Protocol
• Google Gemini
• - How to use with Google Gemini