mcp

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Jan 24, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package mcp provides an MCP (Model Context Protocol) server for voice interactions.

The MCP server exposes voice interaction tools that can be used by Claude Code or other MCP-compatible clients. It abstracts the underlying STT, TTS, and transport providers, allowing any combination of providers to be used.

Tools

The server exposes four tools:

  • initiate_call: Start a voice call with an initial message
  • continue_call: Continue an active call with a follow-up message
  • speak_to_user: Speak a message without waiting for a response
  • end_call: End an active call with a closing message

Usage

Create a server with your providers and run it:

server := mcp.NewServer(mcp.Config{
    STT:       sttProvider,       // stt.StreamingProvider
    TTS:       ttsProvider,       // tts.StreamingProvider
    Transport: transportProvider, // transport.Transport
    PhoneNumber:     "+15551234567",
    UserPhoneNumber: "+15559876543",
})
server.Run(ctx) // Blocks, communicates via stdio

Index

Constants

View Source
const (
	ParseError     = -32700
	InvalidRequest = -32600
	MethodNotFound = -32601
	InvalidParams  = -32602
	InternalError  = -32603
)

Standard JSON-RPC 2.0 error codes

Variables

View Source
var (
	ErrSessionNotFound = errors.New("session not found")
	ErrSessionHungUp   = errors.New("session was hung up")
	ErrNoConnection    = errors.New("no active connection")
)

Session errors

Functions

This section is empty.

Types

type CallToolParams

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

CallToolParams contains parameters for tools/call.

type CallToolResult

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

CallToolResult is returned from tools/call.

type ClientCapabilities

type ClientCapabilities struct {
	Roots    *RootsCapability    `json:"roots,omitempty"`
	Sampling *SamplingCapability `json:"sampling,omitempty"`
}

ClientCapabilities describes what the client supports.

type ClientInfo

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

ClientInfo describes the MCP client.

type Config

type Config struct {
	// STT is the speech-to-text provider.
	STT stt.StreamingProvider

	// TTS is the text-to-speech provider.
	TTS tts.StreamingProvider

	// Transport is the audio transport provider.
	Transport transport.Transport

	// PhoneNumber is the phone number to call from (E.164 format).
	PhoneNumber string

	// UserPhoneNumber is the phone number to call (E.164 format).
	UserPhoneNumber string

	// TranscriptTimeoutMs is the timeout for waiting for user speech.
	// Default is 180000 (3 minutes).
	TranscriptTimeoutMs int

	// VoiceID is the TTS voice to use.
	VoiceID string

	// TTSModel is the TTS model to use.
	TTSModel string

	// STTModel is the STT model to use.
	STTModel string

	// STTLanguage is the STT language code (e.g., "en-US").
	STTLanguage string
}

Config configures the MCP server.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults.

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

TextContent creates a text content block.

type ErrorObject

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

ErrorObject represents a JSON-RPC 2.0 error.

type InitializeParams

type InitializeParams struct {
	ProtocolVersion string             `json:"protocolVersion"`
	Capabilities    ClientCapabilities `json:"capabilities"`
	ClientInfo      ClientInfo         `json:"clientInfo"`
}

InitializeParams contains parameters for the initialize request.

type InitializeResult

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

InitializeResult is returned from initialize.

type JSONSchema

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

JSONSchema is a simplified JSON Schema for tool parameters.

type ListToolsResult

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

ListToolsResult is returned from tools/list.

type Notification

type Notification struct {
	JSONRPC string          `json:"jsonrpc"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

Notification represents a JSON-RPC 2.0 notification (no ID).

type Property

type Property struct {
	Type        string `json:"type"`
	Description string `json:"description,omitempty"`
}

Property describes a schema property.

type Request

type Request struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      json.RawMessage `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      json.RawMessage `json:"id,omitempty"`
	Result  any             `json:"result,omitempty"`
	Error   *ErrorObject    `json:"error,omitempty"`
}

Response represents a JSON-RPC 2.0 response.

type RootsCapability

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

RootsCapability indicates roots support.

type SamplingCapability

type SamplingCapability struct{}

SamplingCapability indicates sampling support.

type Server

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

Server is an MCP server that communicates via stdio.

func NewServer

func NewServer(config Config) *Server

NewServer creates a new MCP server.

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

Run starts the MCP server and blocks until the context is cancelled.

type ServerCapabilities

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

ServerCapabilities describes what the server supports.

type ServerInfo

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

ServerInfo describes the MCP server.

type Session

type Session struct {
	ID        string
	StartTime time.Time
	// contains filtered or unexported fields
}

Session represents an active voice call session.

func (*Session) AddHistory

func (s *Session) AddHistory(speaker, message string)

AddHistory adds a turn to the conversation history.

func (*Session) Close

func (s *Session) Close() error

Close ends the session.

func (*Session) Duration

func (s *Session) Duration() time.Duration

Duration returns the session duration.

func (*Session) IsHungUp

func (s *Session) IsHungUp() bool

IsHungUp returns whether the session was hung up.

func (*Session) Listen

func (s *Session) Listen(ctx context.Context, timeoutMs int) (string, error)

Listen waits for user speech and returns the transcript.

func (*Session) Speak

func (s *Session) Speak(ctx context.Context, text string) error

Speak synthesizes and sends audio to the connection.

func (*Session) SpeakAndListen

func (s *Session) SpeakAndListen(ctx context.Context, text string, timeoutMs int) (string, error)

SpeakAndListen speaks a message and waits for a response.

type SessionManager

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

SessionManager manages active voice sessions.

func NewSessionManager

func NewSessionManager(config Config) *SessionManager

NewSessionManager creates a new session manager.

func (*SessionManager) CreateSession

func (m *SessionManager) CreateSession(ctx context.Context) (*Session, error)

CreateSession creates a new voice session.

func (*SessionManager) GetSession

func (m *SessionManager) GetSession(id string) (*Session, error)

GetSession retrieves a session by ID.

func (*SessionManager) RemoveSession

func (m *SessionManager) RemoveSession(id string)

RemoveSession removes a session.

type Tool

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

Tool describes an MCP tool.

type ToolHandler

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

ToolHandler handles tool calls.

func NewToolHandler

func NewToolHandler(config Config) *ToolHandler

NewToolHandler creates a new tool handler.

func (*ToolHandler) CallTool

func (h *ToolHandler) CallTool(ctx context.Context, name string, args map[string]any) CallToolResult

CallTool executes a tool and returns the result.

func (*ToolHandler) GetTools

func (h *ToolHandler) GetTools() []Tool

GetTools returns the list of available tools.

type ToolsCapability

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

ToolsCapability indicates tools are supported.

type Turn

type Turn struct {
	Speaker string // "claude" or "user"
	Message string
}

Turn represents a conversation turn.

Jump to

Keyboard shortcuts

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