serve Command
The serve
command starts SwissArmyHammer as a Model Context Protocol (MCP) server, making your prompts available to Claude Code and other MCP clients.
Usage
swissarmyhammer serve [OPTIONS]
Overview
The serve command:
- Starts an MCP server that provides access to your prompt library
- Loads prompts from various directories (built-in, user, local)
- Watches for file changes and automatically reloads prompts
- Provides real-time access to prompts for Claude Code integration
Options
--port <PORT>
- Description: Port number for MCP communication
- Default: Automatically assigned by the system
- Example:
--port 8080
swissarmyhammer serve --port 8080
--host <HOST>
- Description: Host address to bind the server to
- Default:
localhost
- Example:
--host 127.0.0.1
swissarmyhammer serve --host 127.0.0.1
--prompts <DIRECTORY>
- Description: Additional directories to load prompts from
- Default: Standard locations (
~/.swissarmyhammer/prompts
,./prompts
) - Repeatable: Can be used multiple times
- Example:
--prompts ./custom-prompts
# Single custom directory
swissarmyhammer serve --prompts ./project-prompts
# Multiple directories
swissarmyhammer serve --prompts ./prompts --prompts ~/.custom-prompts
--builtin <BOOLEAN>
- Description: Include built-in prompts in the library
- Default:
true
- Values:
true
,false
- Example:
--builtin false
# Disable built-in prompts
swissarmyhammer serve --builtin false
# Explicitly enable built-in prompts
swissarmyhammer serve --builtin true
--watch <BOOLEAN>
- Description: Enable file watching for automatic prompt reloading
- Default:
true
- Values:
true
,false
- Example:
--watch false
# Disable file watching (for performance)
swissarmyhammer serve --watch false
--debug
- Description: Enable debug logging for troubleshooting
- Default: Disabled
- Output: Detailed logs to stdout
swissarmyhammer serve --debug
--config <FILE>
- Description: Path to configuration file
- Default:
~/.swissarmyhammer/config.toml
- Example:
--config ./custom-config.toml
swissarmyhammer serve --config ./project-config.toml
Examples
Basic Server
Start a basic MCP server with default settings:
swissarmyhammer serve
This loads:
- Built-in prompts
- User prompts from
~/.swissarmyhammer/prompts/
- Local prompts from
./prompts/
(if exists) - Enables file watching
Development Server
For development with debug logging:
swissarmyhammer serve --debug
Output includes:
- Prompt loading details
- MCP protocol messages
- File watching events
- Error stack traces
Custom Prompt Directory
Serve prompts from a specific directory:
swissarmyhammer serve --prompts /path/to/my/prompts
Multiple Directories
Load prompts from multiple locations:
swissarmyhammer serve \
--prompts ./project-prompts \
--prompts ~/.shared-prompts \
--prompts /team/common-prompts
Project-Only Prompts
Serve only local project prompts (no built-in or user prompts):
swissarmyhammer serve \
--prompts ./prompts \
--builtin false
Performance-Optimized
For large prompt collections, disable file watching:
swissarmyhammer serve \
--watch false \
--prompts ./large-prompt-collection
Custom Port and Host
Specify network settings:
swissarmyhammer serve \
--host 0.0.0.0 \
--port 9000
Prompt Loading Order
SwissArmyHammer loads prompts in this order:
-
Built-in prompts (if
--builtin true
)- Located in the binary
- Categories: development, writing, analysis, etc.
-
User prompts (always loaded)
- Location:
~/.swissarmyhammer/prompts/
- Your personal prompt library
- Location:
-
Custom directories (from
--prompts
flags)- Processed in order specified
- Can override earlier prompts with same name
-
Local prompts (always checked)
- Location:
./prompts/
in current directory - Project-specific prompts
- Location:
Prompt Override Behavior
When prompts have the same name:
- Later sources override earlier ones
- Local prompts have highest priority
- Built-in prompts have lowest priority
Example hierarchy:
./prompts/code-review.md (highest priority)
~/.custom/code-review.md (from --prompts ~/.custom)
~/.swissarmyhammer/prompts/code-review.md (user prompts)
built-in:code-review (lowest priority)
File Watching
When file watching is enabled (--watch true
), the server automatically:
Detects Changes
- New prompt files added
- Existing prompt files modified
- Prompt files deleted
- Directory structure changes
Reloads Prompts
- Parses updated files
- Validates YAML front matter
- Updates the prompt library
- Notifies connected MCP clients
Handles Errors
- Invalid YAML syntax
- Missing required fields
- Template compilation errors
- Logs errors without stopping the server
Performance Considerations
File watching uses system resources:
- Memory: Stores file metadata
- CPU: Processes file system events
- Disk I/O: Reads modified files
For large prompt collections (1000+ files), consider:
# Disable watching for better performance
swissarmyhammer serve --watch false
MCP Protocol Details
Server Capabilities
SwissArmyHammer advertises these MCP capabilities:
{
"capabilities": {
"prompts": {
"listChanged": true
},
"tools": {
"listChanged": false
}
}
}
Prompt Exposure
Each prompt becomes an MCP prompt with:
- Name: From prompt’s
name
field - Description: From prompt’s
description
field - Arguments: From prompt’s
arguments
array
Example MCP Prompt
A SwissArmyHammer prompt:
---
name: code-review
title: Code Review Assistant
description: Reviews code for best practices and issues
arguments:
- name: code
description: Code to review
required: true
- name: language
description: Programming language
required: false
default: auto-detect
---
Becomes this MCP prompt:
{
"name": "code-review",
"description": "Reviews code for best practices and issues",
"arguments": [
{
"name": "code",
"description": "Code to review",
"required": true
},
{
"name": "language",
"description": "Programming language",
"required": false
}
]
}
Integration with Claude Code
Configuration
Add SwissArmyHammer to Claude Code’s MCP configuration:
claude mcp add swissarmyhammer swissarmyhammer serve
Custom Configuration
Add with specific options:
claude mcp add project_sah swissarmyhammer serve --prompts ./project-prompts --debug
Multiple Servers
Run different SwissArmyHammer instances:
# Global prompts
claude mcp add sah_global swissarmyhammer serve
# Project-specific prompts
claude mcp add sah_project swissarmyhammer serve --prompts ./prompts --builtin false
Logging and Output
Standard Output
Normal operation logs:
2024-03-20T10:30:00Z INFO SwissArmyHammer MCP Server starting
2024-03-20T10:30:00Z INFO Loaded 25 prompts from 3 directories
2024-03-20T10:30:00Z INFO Server listening on localhost:8080
2024-03-20T10:30:00Z INFO MCP client connected
Debug Output
With --debug
flag:
2024-03-20T10:30:00Z DEBUG Loading prompts from: ~/.swissarmyhammer/prompts
2024-03-20T10:30:00Z DEBUG Found prompt file: code-review.md
2024-03-20T10:30:00Z DEBUG Parsed prompt: code-review (Code Review Assistant)
2024-03-20T10:30:00Z DEBUG MCP request: prompts/list
2024-03-20T10:30:00Z DEBUG MCP response: 25 prompts returned
Error Handling
The server continues running even with errors:
2024-03-20T10:30:00Z ERROR Failed to parse prompt: invalid-prompt.md
2024-03-20T10:30:00Z ERROR YAML error: missing required field 'description'
2024-03-20T10:30:00Z INFO Continuing with 24 valid prompts
Troubleshooting
Server Won’t Start
Check port availability:
# Try a specific port
swissarmyhammer serve --port 8080
# Check if port is in use
lsof -i :8080 # macOS/Linux
netstat -an | findstr 8080 # Windows
Check permissions:
# Run with debug to see detailed errors
swissarmyhammer serve --debug
Prompts Not Loading
Verify directories exist:
# Check default directories
ls -la ~/.swissarmyhammer/prompts
ls -la ./prompts
# Check custom directories
ls -la /path/to/custom/prompts
Validate prompt syntax:
# Test individual prompts
swissarmyhammer test prompt-name
# Validate all prompts
swissarmyhammer doctor
Performance Issues
Large prompt collections:
# Disable file watching
swissarmyhammer serve --watch false
# Limit to specific directories
swissarmyhammer serve --prompts ./essential-prompts --builtin false
Memory usage:
# Monitor memory usage
top -p $(pgrep swissarmyhammer) # Linux
top | grep swissarmyhammer # macOS
Connection Issues
MCP client can’t connect:
# Check server is running
ps aux | grep swissarmyhammer
# Test with different host/port
swissarmyhammer serve --host 127.0.0.1 --port 8080
# Check firewall settings
Debug MCP communication:
# Enable debug logging
swissarmyhammer serve --debug
# Save logs to file
swissarmyhammer serve --debug > server.log 2>&1
Configuration File
Create a configuration file for persistent settings:
# ~/.swissarmyhammer/config.toml
[server]
host = "localhost"
port = 8080
debug = false
[prompts]
builtin = true
watch = true
directories = [
"~/.swissarmyhammer/prompts",
"./prompts",
"/team/shared-prompts"
]
Use with:
swissarmyhammer serve --config ~/.swissarmyhammer/config.toml
Environment Variables
Configure through environment variables:
export SWISSARMYHAMMER_HOST=localhost
export SWISSARMYHAMMER_PORT=8080
export SWISSARMYHAMMER_DEBUG=true
export SWISSARMYHAMMER_PROMPTS_DIR=/custom/prompts
swissarmyhammer serve
Best Practices
1. Use Consistent Directory Structure
~/.swissarmyhammer/prompts/
├── development/
├── writing/
├── analysis/
└── productivity/
2. Enable Debug During Development
swissarmyhammer serve --debug
3. Use Project-Specific Servers
# In each project
claude mcp add project_sah swissarmyhammer serve --prompts ./prompts
4. Monitor Performance
# For large collections
swissarmyhammer serve --watch false --debug
5. Version Control Integration
# .gitignore
.swissarmyhammer/cache/
.swissarmyhammer/logs/
# Keep prompts in version control
git add prompts/
Next Steps
- Learn about Claude Code Integration setup
- Explore Configuration options
- See Troubleshooting for common issues
- Check Built-in Prompts reference