Documentation
¶
Overview ¶
Package mcp provides Model Context Protocol (MCP) integration for Romancy. It allows exposing workflows as MCP tools for AI assistants like Claude.
Index ¶
- func RegisterWorkflow[I, O any](server *Server, workflow romancy.Workflow[I, O], opts ...WorkflowToolOption)
- type CancelInput
- type CancelOutput
- type ResultInput
- type ResultOutput
- type Server
- func (s *Server) App() *romancy.App
- func (s *Server) Handler() http.Handler
- func (s *Server) Initialize(ctx context.Context) error
- func (s *Server) MCPServer() *mcp.Server
- func (s *Server) RunStdio(ctx context.Context) error
- func (s *Server) Shutdown(ctx context.Context) error
- func (s *Server) Storage() storage.Storage
- type ServerOption
- type StartInput
- type StartOutput
- type StatusInput
- type StatusOutput
- type TransportMode
- type WorkflowToolOption
- func WithCancelDescription(desc string) WorkflowToolOption
- func WithDescription(desc string) WorkflowToolOption
- func WithNamePrefix(prefix string) WorkflowToolOption
- func WithResultDescription(desc string) WorkflowToolOption
- func WithStartDescription(desc string) WorkflowToolOption
- func WithStatusDescription(desc string) WorkflowToolOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RegisterWorkflow ¶
func RegisterWorkflow[I, O any](server *Server, workflow romancy.Workflow[I, O], opts ...WorkflowToolOption)
RegisterWorkflow registers a workflow with the MCP server and auto-generates four tools for interacting with it:
- {workflow}_start - Start a new workflow instance
- {workflow}_status - Get the current status of an instance
- {workflow}_result - Get the result of a completed instance
- {workflow}_cancel - Cancel a running instance
Example:
type OrderInput struct {
OrderID string `json:"order_id" jsonschema:"The order ID to process"`
Amount float64 `json:"amount" jsonschema:"Order amount in dollars"`
}
type OrderResult struct {
Status string `json:"status" jsonschema:"Order processing status"`
ConfirmNum string `json:"confirmation_number" jsonschema:"Confirmation number"`
}
mcp.RegisterWorkflow[OrderInput, OrderResult](server, &OrderWorkflow{})
This will generate tools:
- order_workflow_start(order_id, amount) -> instance_id
- order_workflow_status(instance_id) -> status
- order_workflow_result(instance_id) -> OrderResult
- order_workflow_cancel(instance_id, reason) -> success
Types ¶
type CancelInput ¶
type CancelInput struct {
InstanceID string `json:"instance_id" jsonschema:"The workflow instance ID to cancel"`
Reason string `json:"reason,omitempty" jsonschema:"Optional reason for cancellation"`
}
CancelInput is the input type for the cancel tool.
type CancelOutput ¶
type CancelOutput struct {
Success bool `json:"success" jsonschema:"Whether the cancellation was successful"`
Message string `json:"message" jsonschema:"Status message"`
}
CancelOutput is the output type for the cancel tool.
type ResultInput ¶
type ResultInput struct {
InstanceID string `json:"instance_id" jsonschema:"The workflow instance ID to get results from"`
}
ResultInput is the input type for the result tool.
type ResultOutput ¶
type ResultOutput[O any] struct { InstanceID string `json:"instance_id" jsonschema:"The workflow instance ID"` Status string `json:"status" jsonschema:"Current status of the workflow"` Output O `json:"output,omitempty" jsonschema:"The workflow output if completed"` Error string `json:"error,omitempty" jsonschema:"Error message if failed"` }
ResultOutput is the output type for the result tool.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is an MCP server that exposes Romancy workflows as tools. It wraps both a Romancy App and an MCP Server, providing a unified lifecycle management.
Example usage with stdio transport:
app := romancy.NewApp(romancy.WithDatabase("workflow.db"))
server := mcp.NewServer(app,
mcp.WithServerName("order-service"),
mcp.WithServerVersion("1.0.0"),
)
// Register workflows (auto-generates 4 tools per workflow)
mcp.RegisterWorkflow[OrderInput, OrderResult](server, &OrderWorkflow{})
// Start the server
ctx := context.Background()
if err := server.Initialize(ctx); err != nil {
log.Fatal(err)
}
defer server.Shutdown(ctx)
if err := server.RunStdio(ctx); err != nil {
log.Fatal(err)
}
Example usage with HTTP transport:
http.Handle("/mcp", server.Handler())
http.ListenAndServe(":8080", nil)
func NewServer ¶
func NewServer(app *romancy.App, opts ...ServerOption) *Server
NewServer creates a new MCP server that wraps a Romancy App.
func (*Server) App ¶
App returns the underlying Romancy App. This can be used for direct access to the workflow engine.
func (*Server) Handler ¶
Handler returns an HTTP handler for the MCP server. This can be used for REST API integration.
Example:
http.Handle("/mcp", server.Handler())
func (*Server) Initialize ¶
Initialize starts the underlying Romancy App. This must be called before running the MCP server.
func (*Server) MCPServer ¶
MCPServer returns the underlying MCP Server. This can be used for advanced customization.
func (*Server) RunStdio ¶
RunStdio runs the MCP server using stdio transport. This is the standard mode for Claude Desktop integration.
type ServerOption ¶
type ServerOption func(*serverConfig)
ServerOption configures an MCP Server.
func WithServerName ¶
func WithServerName(name string) ServerOption
WithServerName sets the MCP server name.
func WithServerVersion ¶
func WithServerVersion(version string) ServerOption
WithServerVersion sets the MCP server version.
func WithTransportMode ¶
func WithTransportMode(mode TransportMode) ServerOption
WithTransportMode sets the transport mode (stdio or http).
type StartInput ¶
type StartInput[I any] struct { Input I `json:"input" jsonschema:"The workflow input parameters"` }
StartInput is the input type for the start tool.
type StartOutput ¶
type StartOutput struct {
InstanceID string `json:"instance_id" jsonschema:"The unique ID of the started workflow instance"`
}
StartOutput is the output type for the start tool.
type StatusInput ¶
type StatusInput struct {
InstanceID string `json:"instance_id" jsonschema:"The workflow instance ID to check"`
}
StatusInput is the input type for the status tool.
type StatusOutput ¶
type StatusOutput struct {
InstanceID string `json:"instance_id" jsonschema:"The workflow instance ID"`
Status string `json:"status" jsonschema:"Current status: pending, running, completed, failed, cancelled"`
WorkflowName string `json:"workflow_name" jsonschema:"The name of the workflow"`
StartedAt string `json:"started_at" jsonschema:"When the workflow was started in RFC3339 format"`
UpdatedAt string `json:"updated_at" jsonschema:"When the workflow was last updated in RFC3339 format"`
}
StatusOutput is the output type for the status tool.
type TransportMode ¶
type TransportMode string
TransportMode defines the MCP transport type.
const ( // TransportStdio uses stdio transport (for Claude Desktop). TransportStdio TransportMode = "stdio" // TransportHTTP uses HTTP transport (for REST clients). TransportHTTP TransportMode = "http" )
type WorkflowToolOption ¶
type WorkflowToolOption func(*workflowToolConfig)
WorkflowToolOption configures workflow tool registration.
func WithCancelDescription ¶
func WithCancelDescription(desc string) WorkflowToolOption
WithCancelDescription sets the description for the cancel tool.
func WithDescription ¶
func WithDescription(desc string) WorkflowToolOption
WithDescription sets the main description for the workflow tools.
func WithNamePrefix ¶
func WithNamePrefix(prefix string) WorkflowToolOption
WithNamePrefix sets a custom name prefix for the generated tools. By default, the workflow name is used.
func WithResultDescription ¶
func WithResultDescription(desc string) WorkflowToolOption
WithResultDescription sets the description for the result tool.
func WithStartDescription ¶
func WithStartDescription(desc string) WorkflowToolOption
WithStartDescription sets the description for the start tool.
func WithStatusDescription ¶
func WithStatusDescription(desc string) WorkflowToolOption
WithStatusDescription sets the description for the status tool.
Source Files