@reaatech/voice-agent-mcp-client

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

JSON-RPC 2.0 client for connecting to any MCP (Model Context Protocol) server endpoint. Tool discovery, conversation history management, retry with backoff, and response sanitization for TTS output.

Installation

npm install @reaatech/voice-agent-mcp-client
pnpm add @reaatech/voice-agent-mcp-client

Feature Overview

• JSON-RPC 2.0 transport — Standards-compliant protocol over HTTP POST with fetch
• Tool discovery — discoverTools() fetches available tools from MCP server at connect time
• Bearer and API-key auth — Pluggable authentication via config
• Conversation history — Automatic history truncation to max turns to control context size
• Retry with backoff — Configurable retry for 5xx errors, network failures, and timeouts
• Response sanitization — Strips HTML, markdown links, and HTML entities from MCP responses for clean TTS
• Abort signal support — Timeout-based abort via AbortController

Quick Start

import { MCPClient } from '@reaatech/voice-agent-mcp-client';

const client = new MCPClient({
  endpoint: 'https://my-agent.example.com/mcp',
  auth: {
    type: 'bearer',
    credentials: { token: process.env.MCP_API_KEY! },
  },
  timeout: 400,
  retryAttempts: 2,
  maxHistoryTurns: 20,
});

await client.connect();

const response = await client.sendRequest({
  sessionId: 'session-123',
  turnId: 'turn-456',
  utterance: 'What is the weather in Tokyo?',
  history: [
    { role: 'user', content: 'Hello' },
    { role: 'assistant', content: 'Hi there! How can I help?' },
  ],
});

console.log(response.text);       // Clean TTS-ready text
console.log(response.toolCalls);  // Any tool calls made
console.log(response.latencyMs);  // Response time in ms

await client.close();

API Reference

MCPClient

class MCPClient {
  constructor(config: MCPClientConfig);

  connect(): Promise<void>;
  close(): Promise<void>;

  sendRequest(params: MCPRequestParams): Promise<MCPResponse>;
  discoverTools(): Promise<MCPTool[]>;
  isConnected(): boolean;
  getDiscoveredTools(): MCPTool[];
}

MCPClientConfig

| Property | Type | Default | Description | |----------|------|---------|-------------| | endpoint | string | — | Required. MCP server URL | | auth | { type, credentials } | — | Authentication configuration | | timeout | number | 400 | Request timeout in ms | | retryAttempts | number | 1 | Number of retry attempts for retryable errors | | retryDelay | number | 100 | Delay between retries in ms | | maxHistoryTurns | number | 20 | Max conversation turns sent in request history |

MCPRequestParams

| Property | Type | Description | |----------|------|-------------| | sessionId | string | Session identifier | | turnId | string | Turn identifier | | utterance | string | User utterance text | | history | Array<{ role, content }> | Previous conversation turns | | tools | MCPTool[] | Optional tool list override (uses discovered tools by default) |

MCPResponse

| Property | Type | Description | |----------|------|-------------| | text | string | Sanitized response text ready for TTS | | toolCalls | MCPToolCall[] | Tool calls made by the agent | | latencyMs | number | Request round-trip latency | | confidence | number | Response confidence (default 0.95) |

MCPTool

interface MCPTool {
  name: string;
  description?: string;
  inputSchema: Record<string, unknown>;
}

Usage Patterns

Authentication

Bearer token:

const client = new MCPClient({
  endpoint: 'https://...',
  auth: { type: 'bearer', credentials: { token: 'sk-...' } },
});

API key:

const client = new MCPClient({
  endpoint: 'https://...',
  auth: { type: 'api-key', credentials: { key: 'pk-...' } },
});

Retry Behavior

Retryable errors: HTTP 5xx responses, fetch failed network errors, AbortError timeouts, TypeError DNS failures. Non-retryable: HTTP 4xx responses.

const client = new MCPClient({
  endpoint: 'https://...',
  retryAttempts: 3,
  retryDelay: 200,   // 200ms between retries
  timeout: 500,
});

Response Sanitization

MCP responses are automatically cleaned for TTS consumption:

• HTML tags removed: <div>Hello</div> → Hello
• Markdown links stripped: [click here](url) → click here
• HTML entities decoded: & → &, < → <

Tool Discovery

await client.connect();               // Automatically discovers tools
const tools = client.getDiscoveredTools(); // Cached tool list

console.log('Available tools:', tools.map(t => t.name));

Related Packages

• @reaatech/voice-agent-core — Core types, pipeline, config
• @reaatech/voice-agent-stt — Speech-to-text providers
• @reaatech/voice-agent-tts — Text-to-speech providers

License

MIT