StableMCP

StableMCP

Stable Diffusion を使用して画像を生成するための Model Context Protocol（MCP）サーバーです。

• StableMCP
  • 機能
  • プロジェクト構成
  • 前提条件
  • はじめに
  • 設定
    • 設定オプション
    • カスタム設定ファイルの使用
  • API の使用方法
    • 画像を生成する
  • 開発
  • ライセンス

機能

• JSON-RPC 2.0 ベースの Model Context Protocol（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 は、LLM ベースのツールやサービス向けの標準的な JSON-RPC 2.0 ベースのプロトコルである Model Context Protocol（MCP）を実装しています。この実装は、以下の要素で構成されています。

コアコンポーネント

• 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 リリースを作成します
  • GitHub Container Registry に Docker イメージを公開します
  • Homebrew tap に公開します（設定されている場合）

• Security Scan：毎週実行され、手動で実行することもできます。

  • govulncheck を実行して、依存関係の脆弱性を確認します
  • gosec を実行して Go のセキュリティチェックを行います
  • nancy を実行して、依存関係の脆弱性をスキャンします
  • trivy を実行して、包括的な脆弱性スキャンを行います
  • 結果を GitHub Security タブに報告します

• Issue & PR Labeler：イシューと 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 ライセンス