mcp

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 26, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package mcp implements the Model Context Protocol server for GoatFlow. This enables AI assistants to interact with GoatFlow via API tokens.

Index

Constants

View Source
const (
	ErrCodeParse          = -32700
	ErrCodeInvalidRequest = -32600
	ErrCodeMethodNotFound = -32601
	ErrCodeInvalidParams  = -32602
	ErrCodeInternal       = -32603
)

Standard JSON-RPC error codes

View Source
const (
	ProtocolVersion = "2024-11-05"
	ServerName      = "goatflow-mcp"
	ServerVersion   = "0.6.5"
)

Variables

View Source
var ToolRegistry = []Tool{
	{
		Name:        "list_tickets",
		Description: "List tickets with optional filters. Returns ticket ID, number, title, state, queue, priority, and owner.",
		InputSchema: InputSchema{
			Type: "object",
			Properties: map[string]Property{
				"queue_id": {
					Type:        "integer",
					Description: "Filter by queue ID",
				},
				"state_id": {
					Type:        "integer",
					Description: "Filter by state ID (1=new, 2=open, 3=pending, 4=closed)",
				},
				"owner_id": {
					Type:        "integer",
					Description: "Filter by owner user ID",
				},
				"customer_id": {
					Type:        "string",
					Description: "Filter by customer ID",
				},
				"limit": {
					Type:        "integer",
					Description: "Maximum number of tickets to return (default 20, max 100)",
					Default:     20,
				},
				"offset": {
					Type:        "integer",
					Description: "Offset for pagination",
					Default:     0,
				},
			},
		},
	},
	{
		Name:        "get_ticket",
		Description: "Get detailed information about a specific ticket including articles/messages.",
		InputSchema: InputSchema{
			Type: "object",
			Properties: map[string]Property{
				"ticket_id": {
					Type:        "integer",
					Description: "The ticket ID to retrieve",
				},
				"ticket_number": {
					Type:        "string",
					Description: "The ticket number (TN) to retrieve",
				},
				"include_articles": {
					Type:        "boolean",
					Description: "Include ticket articles/messages (default true)",
					Default:     true,
				},
			},
		},
	},
	{
		Name:        "create_ticket",
		Description: "Create a new ticket in the system.",
		InputSchema: InputSchema{
			Type: "object",
			Properties: map[string]Property{
				"title": {
					Type:        "string",
					Description: "Ticket title/subject",
				},
				"queue_id": {
					Type:        "integer",
					Description: "Queue ID to create the ticket in",
				},
				"priority_id": {
					Type:        "integer",
					Description: "Priority ID (1=low, 2=normal, 3=high, 4=urgent)",
				},
				"state_id": {
					Type:        "integer",
					Description: "Initial state ID (default: 1=new)",
				},
				"customer_user": {
					Type:        "string",
					Description: "Customer user login or email",
				},
				"body": {
					Type:        "string",
					Description: "Initial article/message body",
				},
			},
			Required: []string{"title", "queue_id", "body"},
		},
	},
	{
		Name:        "update_ticket",
		Description: "Update ticket attributes (state, priority, queue, owner, etc.).",
		InputSchema: InputSchema{
			Type: "object",
			Properties: map[string]Property{
				"ticket_id": {
					Type:        "integer",
					Description: "The ticket ID to update",
				},
				"title": {
					Type:        "string",
					Description: "New ticket title",
				},
				"state_id": {
					Type:        "integer",
					Description: "New state ID",
				},
				"priority_id": {
					Type:        "integer",
					Description: "New priority ID",
				},
				"queue_id": {
					Type:        "integer",
					Description: "Move to new queue ID",
				},
				"owner_id": {
					Type:        "integer",
					Description: "Assign to new owner user ID",
				},
			},
			Required: []string{"ticket_id"},
		},
	},
	{
		Name:        "add_article",
		Description: "Add a note/article to an existing ticket.",
		InputSchema: InputSchema{
			Type: "object",
			Properties: map[string]Property{
				"ticket_id": {
					Type:        "integer",
					Description: "The ticket ID to add the article to",
				},
				"subject": {
					Type:        "string",
					Description: "Article subject (optional, defaults to ticket title)",
				},
				"body": {
					Type:        "string",
					Description: "Article body content",
				},
				"article_type": {
					Type:        "string",
					Description: "Article type",
					Enum:        []string{"note-internal", "note-external", "email-external"},
					Default:     "note-internal",
				},
			},
			Required: []string{"ticket_id", "body"},
		},
	},
	{
		Name:        "list_queues",
		Description: "List all queues the authenticated user has access to.",
		InputSchema: InputSchema{
			Type:       "object",
			Properties: map[string]Property{},
		},
	},
	{
		Name:        "list_users",
		Description: "List agent users in the system.",
		InputSchema: InputSchema{
			Type: "object",
			Properties: map[string]Property{
				"valid": {
					Type:        "boolean",
					Description: "Filter by valid/active users only (default true)",
					Default:     true,
				},
				"limit": {
					Type:        "integer",
					Description: "Maximum number of users to return",
					Default:     50,
				},
			},
		},
	},
	{
		Name:        "search_tickets",
		Description: "Full-text search across tickets.",
		InputSchema: InputSchema{
			Type: "object",
			Properties: map[string]Property{
				"query": {
					Type:        "string",
					Description: "Search query string",
				},
				"limit": {
					Type:        "integer",
					Description: "Maximum results (default 20)",
					Default:     20,
				},
			},
			Required: []string{"query"},
		},
	},
	{
		Name:        "get_statistics",
		Description: "Get dashboard statistics (ticket counts by state, queue, etc.).",
		InputSchema: InputSchema{
			Type:       "object",
			Properties: map[string]Property{},
		},
	},
	{
		Name:        "execute_sql",
		Description: "Execute a read-only SQL query (SELECT only). Requires admin group membership. For debugging and development.",
		InputSchema: InputSchema{
			Type: "object",
			Properties: map[string]Property{
				"query": {
					Type:        "string",
					Description: "SQL SELECT query to execute",
				},
				"args": {
					Type:        "array",
					Description: "Query arguments for ? placeholders",
				},
			},
			Required: []string{"query"},
		},
	},
}

ToolRegistry contains all available MCP tools for GoatFlow.

Functions

This section is empty.

Types

type ContentBlock

type ContentBlock struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
}

ContentBlock represents content in a tool result.

func TextContent

func TextContent(text string) ContentBlock

Helper to create a text content block

type Error

type Error struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

Error represents a JSON-RPC 2.0 error.

type InitializeParams

type InitializeParams struct {
	ProtocolVersion string `json:"protocolVersion"`
	ClientInfo      struct {
		Name    string `json:"name"`
		Version string `json:"version"`
	} `json:"clientInfo"`
}

InitializeParams are sent by the client during initialization.

type InitializeResult

type InitializeResult struct {
	ProtocolVersion string             `json:"protocolVersion"`
	ServerInfo      ServerInfo         `json:"serverInfo"`
	Capabilities    ServerCapabilities `json:"capabilities"`
}

InitializeResult is returned after successful initialization.

type InputSchema

type InputSchema struct {
	Type       string              `json:"type"`
	Properties map[string]Property `json:"properties,omitempty"`
	Required   []string            `json:"required,omitempty"`
}

InputSchema defines the JSON Schema for tool inputs.

type Property

type Property struct {
	Type        string   `json:"type"`
	Description string   `json:"description,omitempty"`
	Enum        []string `json:"enum,omitempty"`
	Default     any      `json:"default,omitempty"`
}

Property defines a single property in the input schema.

type Request

type Request struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      any             `json:"id,omitempty"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

Request represents a JSON-RPC 2.0 request.

type Response

type Response struct {
	JSONRPC string `json:"jsonrpc"`
	ID      any    `json:"id,omitempty"`
	Result  any    `json:"result,omitempty"`
	Error   *Error `json:"error,omitempty"`
}

Response represents a JSON-RPC 2.0 response.

func ErrorResponse

func ErrorResponse(id any, code int, message string) Response

Helper to create an error response

func SuccessResponse

func SuccessResponse(id any, result any) Response

Helper to create a success response

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server handles MCP protocol messages. The MCP server acts as a multi-user proxy - each request is authenticated by an API token, and the token owner's permissions apply to all operations. Most tools delegate to existing APIs which enforce RBAC. Tools that bypass the API layer (like execute_sql) require admin group membership.

func NewServer

func NewServer(db *sql.DB, userID int, userLogin string) *Server

NewServer creates a new MCP server instance. The server inherits the permissions of the authenticated user (identified by userID).

func (*Server) HandleMessage

func (s *Server) HandleMessage(ctx context.Context, msg []byte) ([]byte, error)

HandleMessage processes a JSON-RPC message and returns a response.

type ServerCapabilities

type ServerCapabilities struct {
	Tools *ToolsCapability `json:"tools,omitempty"`
}

ServerCapabilities describes what this server supports.

type ServerInfo

type ServerInfo struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

ServerInfo describes this MCP server.

type Tool

type Tool struct {
	Name        string      `json:"name"`
	Description string      `json:"description,omitempty"`
	InputSchema InputSchema `json:"inputSchema"`
}

Tool represents an MCP tool definition.

type ToolCallParams

type ToolCallParams struct {
	Name      string         `json:"name"`
	Arguments map[string]any `json:"arguments,omitempty"`
}

ToolCallParams are the parameters for calling a tool.

type ToolCallResult

type ToolCallResult struct {
	Content []ContentBlock `json:"content"`
	IsError bool           `json:"isError,omitempty"`
}

ToolCallResult is the result of a tool call.

type ToolsCapability

type ToolsCapability struct {
	ListChanged bool `json:"listChanged,omitempty"`
}

ToolsCapability indicates tool support.

type ToolsListResult

type ToolsListResult struct {
	Tools []Tool `json:"tools"`
}

ToolsListResult contains the list of available tools.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL