Content
# StableMCP

A Model Context Protocol (MCP) server for generating images using Stable Diffusion.
- [StableMCP](#stablemcp)
- [Features](#features)
- [Project Structure](#project-structure)
- [Prerequisites](#prerequisites)
- [Getting Started](#getting-started)
- [Configuration](#configuration)
- [Configuration Options](#configuration-options)
- [Using a Custom Configuration File](#using-a-custom-configuration-file)
- [API Usage](#api-usage)
- [Generate an Image](#generate-an-image)
- [Development](#development)
- [License](#license)
## Features
- JSON-RPC 2.0 based Model Context Protocol (MCP) implementation
- MCP-compliant API endpoint for image generation
- Integration with Stable Diffusion image generation models
- Support for various image parameters (size, style, prompt)
- API key authentication (optional)
- Configurable image size and quality settings
- Rate limiting and request validation
- Extensible capabilities system for adding new tools
## Project Structure
```
.
├── 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
```
## Prerequisites
- Go 1.22 or higher
- A running Stable Diffusion API (local or remote)
## Getting Started
```bash
# 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
```
Alternatively, you can use Go commands directly:
```bash
# 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
```
## Configuration
StableMCP provides a flexible configuration system powered by [Viper](https://github.com/spf13/viper). You can configure the application through multiple sources, which are applied in the following order of precedence (highest to lowest):
1. **Command line flags** (highest priority)
2. **Environment variables** with `STABLEMCP_` prefix
3. **Configuration file** specified with `--config` flag
4. **Standard configuration files** named `.stablemcp.yaml` or `.stablemcp.json`:
- `./configs/.stablemcp.yaml` (project directory)
- `$HOME/.config/.stablemcp.yaml` (user home directory)
- `/etc/.stablemcp.yaml` (system-wide)
5. **Default values** (lowest priority)
### Command Line Flags
StableMCP supports these global command line flags:
```
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-specific flags:
```
Server Flags:
--host string Server host address (default: "localhost")
--port int Server port (default: 8080)
```
### Environment Variables
All configuration options can be set using environment variables with the `STABLEMCP_` prefix:
```bash
# Examples
export STABLEMCP_DEBUG=true
export STABLEMCP_LOG_LEVEL=debug
export STABLEMCP_SERVER_PORT=9000
export STABLEMCP_SERVER_HOST=0.0.0.0
```
### Configuration File Options
You can customize the application by setting the following options in your YAML configuration file:
```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")
```
### Using a Custom Configuration File
You can specify a custom configuration file when running the server:
```bash
./bin/stablemcp server --config path/to/your/config.yaml
```
Or create one of these standard configuration files:
```bash
# 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
```
### Configuration Precedence Examples
StableMCP applies configuration values in order of precedence. For example:
1. If you set `--log-level=debug` on the command line, it will override the log level in any config file
2. If you set `STABLEMCP_SERVER_PORT=9000` in the environment, it will be used unless overridden by a command line flag
3. If you have `server.port: 8000` in your config file, it will be used unless overridden by an environment variable or command line flag
## MCP Implementation
StableMCP implements the [Model Context Protocol](https://github.com/llm-protocol/model-context-protocol) (MCP), a standard JSON-RPC 2.0 based protocol for LLM-based tools and services. The implementation consists of:
### Core Components
- **JSONRPCRequest/Response**: Standard JSON-RPC 2.0 request and response structures
- **MCPServer**: Server implementation with name, version, and capabilities
- **Capabilities**: Extensible system for registering tools the server supports
### Server Initialization
```go
// 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 Usage
### Generate an Image
```bash
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 Initialize Request
```bash
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "1",
"method": "initialize",
"params": {}
}'
```
## Development
[](https://github.com/mkm29/stablemcp/actions/workflows/ci.yml)
[](https://github.com/mkm29/stablemcp/actions/workflows/release.yml)
[](https://github.com/mkm29/stablemcp/actions/workflows/security.yml)
The project includes a Makefile with common development tasks:
```bash
# 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
```
### Version Management
StableMCP follows semantic versioning and provides version information through the `version` package:
```go
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 information is embedded during build time using the following variables:
- `Version`: The current version from git tags or default (0.1.1)
- `BuildDate`: The build date in ISO 8601 format
- `GitCommit`: The git commit hash
- `GitBranch`: The git branch name
You can check the version of a built binary with:
```bash
# JSON output (default)
./bin/stablemcp version
# Text output
./bin/stablemcp --output text version
# or
./bin/stablemcp -o text version
```
Alternatively, you can use Go commands directly:
```bash
# Run tests
go test ./...
# Format code
go fmt ./...
# Run linter
golangci-lint run
```
## CI/CD with GitHub Actions
This project uses GitHub Actions for continuous integration and delivery:
### Workflows
- **CI**: Triggered on pushes to `main` and `develop` branches and pull requests.
- Runs linting
- Runs tests with coverage reporting
- Builds binaries for multiple platforms (Linux, macOS, Windows)
- **Release**: Triggered when a new tag is pushed.
- Creates a GitHub release with binaries for all platforms
- Publishes Docker images to GitHub Container Registry
- Publishes to Homebrew tap (if configured)
- **Security Scan**: Runs weekly and can be triggered manually.
- Runs `govulncheck` to check for vulnerabilities in dependencies
- Runs `gosec` for Go security checks
- Runs `nancy` for dependency vulnerability scanning
- Runs `trivy` for comprehensive vulnerability scanning
- Reports results to GitHub Security tab
- **Issue & PR Labeler**: Automatically adds labels to issues and PRs.
- Labels based on title and content
- Labels PRs based on modified files
### Creating a Release
To create a new release:
```bash
# Tag a new version
git tag -a v0.1.2 -m "Release v0.1.2"
# Push the tag
git push origin v0.1.2
```
The release workflow will automatically build and publish the release.
## License
[MIT License](LICENSE)
Connection Info
You Might Also Like
semantic-kernel
Integrate cutting-edge LLM technology quickly and easily into your apps
repomix
📦 Repomix is a powerful tool that packs your entire repository into a...
Serena
A powerful coding agent toolkit providing semantic retrieval and editing...
easy-code-reader
A powerful MCP (Model Context Protocol) server for intelligently reading...
strudel-mcp-server
A Model Context Protocol (MCP) server that gives Claude direct control over...
awesome-context-engineering
A curated list of awesome open-source libraries for context engineering...