@lushly-dev/afd-client weekly downloads statistics

@lushly-dev/afd-client

MCP client library for Agent-First Development.

Installation

npm install @lushly-dev/afd-client
# or
pnpm add @lushly-dev/afd-client

Overview

This package provides clients for AFD command servers. It supports:

• SSE Transport: Real-time streaming with Server-Sent Events
• HTTP Transport: Simple request/response communication
• Direct Transport: Zero-overhead in-process execution for co-located agents
• Auto-reconnection: Exponential backoff with jitter and a cap
• Type-safe API: Full TypeScript support with CommandResult integration

Supported servers

McpClient talks to AFD servers: createMcpServer() from @lushly-dev/afd-server (and the AFD Python server), through their HTTP transport:

Route	Used for
GET <base>/sse	Event stream of the sse transport
POST <base>/message	JSON-RPC requests (initialize, tools/list, tools/call)
GET <base>/health	Reachability check on connect (http transport)
POST <base>/stream/<command>	stream()

McpClient is not a general MCP client. It does not implement the MCP Streamable HTTP transport (the Accept: application/json, text/event-stream negotiation and its session handling), and it ignores the endpoint event of the legacy MCP SSE transport. Servers built on the official MCP SDK answer it with HTTP 406 or 400. To talk to those servers, use the official @modelcontextprotocol/sdk client.

Usage

Basic Connection

import { createClient } from '@lushly-dev/afd-client';

// Create client
const client = createClient({
  url: 'http://localhost:3100/sse',
  transport: 'sse', // or 'http'
});

// Connect
await client.connect();

// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools.map(t => t.name));

// Disconnect when done
await client.disconnect();

Calling Commands

import { createClient, type CommandResult } from '@lushly-dev/afd-client';
import { isSuccess, isFailure } from '@lushly-dev/afd-core';

const client = createClient({ url: 'http://localhost:3100/sse' });
await client.connect();

// Call a command - returns CommandResult
const result = await client.call<Document>('document-create', {
  title: 'My Document',
  content: 'Hello, world!'
});

if (isSuccess(result)) {
  console.log('Created document:', result.data);
  console.log('Confidence:', result.confidence);
  console.log('Reasoning:', result.reasoning);
} else {
  console.error('Error:', result.error.message);
  console.error('Suggestion:', result.error.suggestion);
}

Pass per-request deadlines and cancellation to call(), callTool(), or request():

const result = await client.call('item-get', { id: '123' }, {
  timeout: 5_000,
  signal: controller.signal,
});

With the direct transport, deadlines and cancellation settle the request even when a handler ignores its abort signal. Disconnecting also aborts active execution. A handler that has already started may still complete its side effects; check a mutation's effect before retrying. Direct discovery preserves the registry's input schema and planning metadata. HTTP and SSE session renewal requires a successful JSON-RPC initialize result and a replacement session ID before replaying a rejected request. Concurrent requests share renewal work.

Event Handling

const client = createClient({
  url: 'http://localhost:3100/sse',
  autoReconnect: true,
  maxReconnectAttempts: 5,
});

// Subscribe to events
client.on('connected', (info) => {
  console.log('Connected to:', info.serverInfo.name);
});

client.on('disconnected', (reason) => {
  console.log('Disconnected:', reason);
});

client.on('reconnecting', (attempt, max) => {
  console.log(`Reconnecting... (${attempt}/${max})`);
});

client.on('error', (error) => {
  console.error('Client error:', error);
});

client.on('toolsChanged', (tools) => {
  console.log('Tools updated:', tools.length);
});

await client.connect();

• connected fires once the server is initialized and the tools list is loaded, so client.getTools() is ready inside the handler. A failed tools refresh does not fail the connection; the list stays empty.
• While reconnecting, each attempt emits reconnecting; failed attempts emit nothing else. If every attempt fails, the client emits one error ("Max reconnection attempts reached", with the last failure as cause) and moves to the error state.
• The delay before attempt n is reconnectDelay * 2^(n-1) plus up to 100 ms of jitter, capped at maxReconnectDelay.
• The sse transport notices a closed event stream. The http transport has no persistent connection, so it reports the connection as lost after 3 consecutive requests get no HTTP response at all; autoReconnect then applies to it too.

Client Status

const status = client.getStatus();

console.log('State:', status.state);
console.log('Server:', status.serverInfo?.name);
console.log('Connected at:', status.connectedAt);
console.log('Pending requests:', status.pendingRequests);

Raw Tool Calls

For low-level access, use callTool which returns the raw MCP response:

// Raw MCP response
const rawResult = await client.callTool('document-create', {
  title: 'Test'
});

console.log('Content:', rawResult.content);
console.log('Is error:', rawResult.isError);

callTool() and request() take an optional { timeout } that overrides the client timeout for that request. They throw NotConnectedError, RequestTimeoutError, JsonRpcResponseError (with the JSON-RPC code and data) or HttpStatusError; call(), batch(), pipe() and stream() never throw and return these as failures instead.

Batches and Pipelines…