使用说明

稳定MCP

用于使用稳定扩散生成图像的模型上下文协议（MCP）服务器。

稳定MCP

特性

基于JSON-RPC 2.0的模型上下文协议（MCP）实现
用于图像生成的符合MCP的API端点
与稳定扩散图像生成模型集成
支持各种图像参数（大小、样式、提示）
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

先决条件

达到1.22或更高
正在运行的稳定扩散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提供了一个灵活的配置系统，由蝰蛇。您可以通过多个源配置应用程序，这些源按以下优先级顺序（从高到低）应用：

命令行标志 （最高优先级）
环境变量 随着 STABLEMCP_ 前缀
配置文件 指定为 --config 旗帜
标准配置文件 命名 .stablemcp.yaml 或 .stablemcp.json:
- ./configs/.stablemcp.yaml （项目目录）
- $HOME/.config/.stablemcp.yaml （用户主目录）
- /etc/.stablemcp.yaml （全系统）
默认值 （最低优先级）

命令行标志

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按优先顺序应用配置值。例如：

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

MCP实施

StableMCP实施模型上下文协议（MCP）是一种基于JSON-RPC 2.0的标准协议，用于基于LLM的工具和服务。实施包括：

核心组件

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

服务器初始化

// 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操作的CI/CD

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

工作流

CI公司：触发推送 main 和 develop 分支和拉取请求。
- 运行linting
- 运行具有覆盖率报告的测试
- 为多个平台（Linux、macOS、Windows）构建二进制文件
发布：当按下新标签时触发。
- 为所有平台创建包含二进制文件的GitHub版本
- 将Docker镜像发布到GitHub容器注册表
- 发布到Homebrew水龙头（如果已配置）
安全扫描：每周运行一次，可以手动触发。
- 跑 govulncheck 检查依赖关系中的漏洞
- 跑 gosec Go安全检查
- 跑 nancy 用于依赖性漏洞扫描
- 跑 trivy 用于全面的漏洞扫描
- 将结果报告到GitHub安全选项卡
问题与公关标签：自动为问题和PR添加标签。
- 基于标题和内容的标签
- 根据修改后的文件标记PR

创建发布

要创建新版本，请执行以下操作：

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

# Push the tag
git push origin v0.1.2

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

许可证

MIT许可证