StableMCP

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

• StableMCP
  • 特性
  • 项目结构
  • 前提条件
  • 快速开始
  • 配置
    • 配置选项
    • 使用自定义配置文件
  • API 使用
    • 生成图像
  • 开发
  • 许可

特性

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

项目结构

.
├── api           # API 定义、路由和文档
├── bin           # 构建产物
├── cmd           # 应用程序入口点
├── configs       # 配置文件
├── examples      # 使用示例
├── internal      # 私有应用程序代码
│   ├── config    # 配置处理
│   ├── models    # 数据模型
│   └── helpers   # 辅助函数
├── pkg           # 公共包
│   ├── auth      # 身份验证/授权
│   ├── handlers  # 请求处理程序
│   ├── mcp       # MCP 协议实现
│   │   ├── server.go   # 服务器实现
│   │   └── types.go    # 协议类型定义
│   └── stablediffusion # Stable Diffusion 客户端
└── scripts       # 实用脚本

前提条件

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

快速开始

# 克隆仓库
git clone https://github.com/yourusername/stablemcp.git
cd stablemcp

# 创建默认配置文件
make config

# 构建服务器
make build

# 使用默认配置运行
make run

# 使用自定义配置运行
make run-config

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

# 构建服务器
go build -o bin/stablemcp ./main.go

# 使用默认配置运行
./bin/stablemcp server

# 使用自定义配置运行
./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_ 前缀的环境变量进行设置：

# 示例
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"                    # 服务器主机地址（默认值："localhost"）
  port: 8080                           # 服务器端口（默认值：8080）
  tls:
    enabled: false                     # 启用/禁用 TLS（默认值：false）
    # 以下选项没有默认值，因此如果启用了 TLS，则必须设置这些选项
    cert: "/path/to/cert.pem"          # TLS 证书路径（默认值：""）
    key: "/path/to/key.pem"            # TLS 密钥路径（默认值：""）

logging:
  level: "info"                        # 日志级别：debug、info、warn、error（默认值："info"）
  format: "json"                       # 日志格式：json、text（默认值："json"）

debug: false                           # 启用调试模式（默认值：false）
timeout: "30s"                         # 请求超时（默认值："30s"）

telemetry:
  metrics:
    enabled: false                     # 启用指标收集（默认值：false）
    port: 9090                         # 指标服务器端口（默认值：9090）
    path: "/metrics"                   # 指标端点路径（默认值："/metrics"）
  tracing:
    enabled: false                     # 启用分布式追踪（默认值：false）
    port: 9091                         # 追踪服务器端口（默认值：9091）
    path: "/traces"                    # 追踪端点路径（默认值："/traces"）

# OpenAI 配置
openai:
  apiKey: "your-openai-api-key"        # 用于 API 调用的 OpenAI API 密钥（默认值：""）
  model: "gpt-3.5-turbo"               # 要使用的模型（默认值："gpt-3.5-turbo"）
  baseUrl: "https://api.openai.com/v1" # API 调用的基本 URL

# 生成图像的下载路径
downloadPath: "~/Downloads"            # 将保存生成图像的路径（默认值："~/Downloads"）

使用自定义配置文件

您可以在运行服务器时指定自定义配置文件：

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

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

# 在您的项目目录中
touch configs/.stablemcp.yaml

# 在您的主目录中
touch ~/.config/.stablemcp.yaml

# 系统范围（需要 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 的标准协议，用于基于 LLM 的工具和服务。 该实现包括：

核心组件

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

服务器初始化

// 使用版本包中的自动版本创建一个新的 MCP 服务器
server := mcp.NewMCPServer("StableMCP")

// 或者使用自定义版本创建
// server := mcp.NewMCPServerWithVersion("StableMCP", "0.1.1")

// 注册功能/工具
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：

# 运行所有测试
make test

# 运行特定测试
make test-one TEST=TestConfigLoading

# 格式化代码
make fmt

# 运行 linter
make lint

# 清理构建产物
make clean

# 检查版本信息
make version

# 查看所有可用命令
make help

版本管理

StableMCP 遵循语义版本控制，并通过 version 包提供版本信息：

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

// 获取当前版本
fmt.Println("StableMCP version:", version.Version)

// 获取所有版本信息
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 输出（默认）
./bin/stablemcp version

# 文本输出
./bin/stablemcp --output text version
# 或
./bin/stablemcp -o text version

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

# 运行测试
go test ./...

# 格式化代码
go fmt ./...

# 运行 linter
golangci-lint run

使用 GitHub Actions 进行 CI/CD

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

工作流程

• CI: 在推送到 main 和 develop 分支以及拉取请求时触发。

  • 运行 linting
  • 运行带有覆盖率报告的测试
  • 为多个平台（Linux、macOS、Windows）构建二进制文件

• Release: 在推送新标签时触发。

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

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

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

• Issue & PR Labeler: 自动将标签添加到 issue 和 PR。

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

创建发布

要创建新版本：

# 标记一个新版本
git tag -a v0.1.2 -m "Release v0.1.2"

# 推送标签
git push origin v0.1.2

发布工作流程将自动构建和发布版本。

许可

MIT 许可证