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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.