StableMCP

StableMCP

一个使用 Stable Diffusion 生成图像的模型上下文协议（MCP）服务。

• StableMCP
  • 功能
  • 项目结构
  • 前提条件
  • 开始使用
  • 配置
    • 配置选项
    • 使用自定义配置文件
  • API 用法
    • 生成图像
  • 开发
  • 许可证

功能

• 基于 JSON-RPC 2.0 的模型上下文协议（MCP）实现
• 符合 MCP 规范的图像生成 API 端点
• 集成 Stable Diffusion 图像生成模型
• 支持各种图像参数（尺寸、风格、提示词）
• API 密钥身份验证（可选）
• 可配置图像尺寸和质量设置
• 速率限制和请求验证
• 可扩展的功能系统，便于添加新工具

项目结构

.
├── api           # API definitions, routes, and documentation
├── bin           # Build artifacts
├── cmd           # Application entrypoints
├── configs       # Configuration files
├── examples      # Example usages
├── internal      # Private application code
│   ├── config    # Configuration handling
│   ├── models    # Data models
│   └── helpers   # Helper functions
├── pkg           # Public packages
│   ├── auth      # Authentication/authorization
│   ├── handlers  # Request handlers
│   ├── mcp       # MCP protocol implementation
│   │   ├── server.go   # Server implementation
│   │   └── types.go    # Protocol type definitions
│   └── stablediffusion # Stable Diffusion client
└── scripts       # Utility scripts

前提条件

• Go 1.22 或更高版本
• 正在运行的 Stable Diffusion API（本地或远程）

开始使用

# Clone the repository
git clone https://github.com/yourusername/stablemcp.git
cd stablemcp

# Create a default configuration file
make config

# Build the server
make build

# Run with default config
make run

# Run with a custom config
make run-config

或者，你也可以直接使用 Go 命令：

# Build the server
go build -o bin/stablemcp ./main.go

# Run with default config
./bin/stablemcp server

# Run with a custom config
./bin/stablemcp server --config configs/.stablemcp.yaml

配置

StableMCP 提供由 Viper 驱动的灵活配置系统。你可以通过多种来源配置应用，这些配置按以下优先级顺序（从高到低）应用：

1. 命令行标志（最高优先级）
2. 带有 STABLEMCP_ 前缀的环境变量
3. 使用 --config 标志指定的配置文件
4. 名为 .stablemcp.yaml 或 .stablemcp.json 的标准配置文件：
   • ./configs/.stablemcp.yaml（项目目录）
   • $HOME/.config/.stablemcp.yaml（用户主目录）
   • /etc/.stablemcp.yaml（系统范围）
5. 默认值（最低优先级）

命令行标志

StableMCP 支持以下全局命令行标志：

Global Flags:
  -c, --config string     Path to the configuration file
  -d, --debug             Enable debug mode (default: false)
  -h, --help              Help for stablemcp
  -l, --log-level string  Set the logging level: debug, info, warn, error (default: "info")
  -o, --output string     Output format: json, text (default: "json")
      --timeout string    Request timeout duration (default: "30s")

服务专用标志：

Server Flags:
      --host string       Server host address (default: "localhost")
      --port int          Server port (default: 8080)

环境变量

所有配置选项都可以通过带有 STABLEMCP_ 前缀的环境变量进行设置：

# Examples
export STABLEMCP_DEBUG=true
export STABLEMCP_LOG_LEVEL=debug
export STABLEMCP_SERVER_PORT=9000
export STABLEMCP_SERVER_HOST=0.0.0.0

配置文件选项

你可以在 YAML 配置文件中设置以下选项来自定义应用：

server:
  host: "localhost"                    # Server host address (default: "localhost")
  port: 8080                           # Server port (default: 8080)
  tls:
    enabled: false                     # Enable/disable TLS (default: false)
    # There are no default values for the following options, so these must be set if TLS is enabled
    cert: "/path/to/cert.pem"          # TLS certificate path (default: "")
    key: "/path/to/key.pem"            # TLS key path (default: "")

logging:
  level: "info"                        # Log level: debug, info, warn, error (default: "info")
  format: "json"                       # Log format: json, text (default: "json")

debug: false                           # Enable debug mode (default: false)
timeout: "30s"                         # Request timeout (default: "30s")

telemetry:
  metrics:
    enabled: false                     # Enable metrics collection (default: false)
    port: 9090                         # Metrics server port (default: 9090)
    path: "/metrics"                   # Metrics endpoint path (default: "/metrics")
  tracing:
    enabled: false                     # Enable distributed tracing (default: false)
    port: 9091                         # Tracing server port (default: 9091)
    path: "/traces"                    # Tracing endpoint path (default: "/traces")

# OpenAI configuration
openai:
  apiKey: "your-openai-api-key"        # OpenAI API key for API calls (default: "")
  model: "gpt-3.5-turbo"               # Model to use (default: "gpt-3.5-turbo")
  baseUrl: "https://api.openai.com/v1" # Base URL for API calls

# download path for generated images
downloadPath: "~/Downloads"            # Path where generated images will be saved (default: "~/Downloads")

使用自定义配置文件

运行服务时，你可以指定自定义配置文件：

./bin/stablemcp server --config path/to/your/config.yaml

或者，创建以下任一标准配置文件：

# In your project directory
touch configs/.stablemcp.yaml

# In your home directory
touch ~/.config/.stablemcp.yaml

# System-wide (requires sudo)
sudo touch /etc/.stablemcp.yaml

配置优先级示例

StableMCP 按优先级顺序应用配置值。例如：

1. 如果在命令行中设置 --log-level=debug，它将覆盖任何配置文件中的日志级别
2. 如果在环境中设置 STABLEMCP_SERVER_PORT=9000，除非被命令行标志覆盖，否则将使用该值
3. 如果配置文件中包含 server.port: 8000，除非被环境变量或命令行标志覆盖，否则将使用该值

MCP 实现

StableMCP 实现了 模型上下文协议（MCP），这是一种基于 JSON-RPC 2.0 的标准协议，适用于大模型工具和服务。其实现包含：

核心组件

• JSONRPCRequest/Response：标准 JSON-RPC 2.0 请求和响应结构
• MCPServer：包含名称、版本和功能的服务实现
• Capabilities：用于注册服务所支持工具的可扩展系统

服务初始化

// Create a new MCP server with auto-version from the version package
server := mcp.NewMCPServer("StableMCP")

// Or create with a custom version
// server := mcp.NewMCPServerWithVersion("StableMCP", "0.1.1")

// Register capabilities/tools
server.Capabilities.Tools["stable-diffusion"] = map[string]interface{}{
    "version": "1.0",
    "models": []string{"sd-turbo", "sdxl"},
}

API 用法

生成图像

curl -X POST http://localhost:8080/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a photo of a cat in space",
    "width": 512,
    "height": 512,
    "num_inference_steps": 50
  }'

MCP 初始化请求

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "initialize",
    "params": {}
  }'

开发

项目包含一个 Makefile，其中列出了常见的开发任务：

# Run all tests
make test

# Run a specific test
make test-one TEST=TestConfigLoading

# Format code
make fmt

# Run linter
make lint

# Clean build artifacts
make clean

# Check version information
make version

# See all available commands
make help

版本管理

StableMCP 遵循语义化版本规范，并通过 version 包提供版本信息：

import "github.com/mkm29/stablemcp/internal/version"

// Get the current version
fmt.Println("StableMCP version:", version.Version)

// Get all version info
versionInfo := version.Info()
fmt.Printf("Version: %s\nCommit: %s\nBuild Date: %s\n", 
    versionInfo["version"], versionInfo["gitCommit"], versionInfo["buildDate"])

构建时会通过以下变量嵌入版本信息：

• Version：来自 git 标签的当前版本或默认版本（0.1.1）
• BuildDate：采用 ISO 8601 格式的构建日期
• GitCommit：git 提交哈希
• GitBranch：git 分支名称

你可以通过以下命令查看已构建二进制文件的版本：

# JSON output (default)
./bin/stablemcp version

# Text output
./bin/stablemcp --output text version
# or
./bin/stablemcp -o text version

或者，你也可以直接使用 Go 命令：

# Run tests
go test ./...

# Format code
go fmt ./...

# Run linter
golangci-lint run

使用 GitHub Actions 进行 CI/CD

本项目使用 GitHub Actions 进行持续集成和交付：

工作流

• CI：在向 main 和 develop 分支推送代码，以及创建拉取请求时触发。

  • 运行代码检查
  • 运行测试并报告覆盖率
  • 为多个平台构建二进制文件（Linux、macOS、Windows）

• Release：推送新标签时触发。

  • 创建包含所有平台二进制文件的 GitHub Release
  • 将 Docker 镜像发布到 GitHub Container Registry
  • 发布到 Homebrew tap（如果已配置）

• Security Scan：每周运行一次，也可手动触发。

  • 运行 govulncheck 检查依赖项中的漏洞
  • 运行 gosec 执行 Go 安全检查
  • 运行 nancy 扫描依赖项漏洞
  • 运行 trivy 进行全面的漏洞扫描
  • 将结果报告到 GitHub Security 选项卡

• Issue & PR Labeler：自动为问题和 PR 添加标签。

  • 根据标题和内容添加标签
  • 根据修改的文件为 PR 添加标签

创建 Release

要创建新版本：

# Tag a new version
git tag -a v0.1.2 -m "Release v0.1.2"

# Push the tag
git push origin v0.1.2

Release 工作流会自动构建并发布该版本。

许可证

MIT 许可证