npm package: @sarasanalytics-com/mcp-client
Description: A lightweight, framework-agnostic client for the Model Context Protocol (MCP)
Latest version: 0.1.0

# MCP Client

A lightweight, framework-agnostic TypeScript client for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).

## Installation

```bash
npm install @anthropic/mcp-client
```

## Quick Start

```typescript
import { McpClient } from '@anthropic/mcp-client';

const client = new McpClient({
  baseUrl: 'http://localhost:3000/mcp',
  clientInfo: { name: 'my-app', version: '1.0.0' },
  debug: true,
});

// Connect to the server
await client.connect();

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

// Call a tool
const result = await client.callTool('my-tool', { query: 'hello' });
console.log('Result:', result);
```

## API Reference

### Constructor

```typescript
new McpClient(config: McpClientConfig)
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `baseUrl` | `string` | *required* | MCP server URL |
| `clientInfo` | `{ name, version }` | `{ name: 'mcp-client', version: '1.0.0' }` | Client identification |
| `protocolVersion` | `string` | `'2024-11-05'` | MCP protocol version |
| `capabilities` | `object` | `{}` | Capabilities to advertise |
| `debug` | `boolean` | `false` | Enable debug logging |

### Methods

#### Connection

- **`connect(): Promise<void>`** — Connect and initialize session
- **`disconnect(): void`** — Clear session
- **`isConnected(): boolean`** — Check connection status
- **`getActiveSessionId(): string | null`** — Get current session ID
- **`ping(): Promise<boolean>`** — Check server health

#### Tools

- **`listTools(): Promise<McpTool[]>`** — List available tools
- **`callTool(name: string, args: object): Promise<McpToolCallResult>`** — Execute a tool

#### Resources

- **`listResources(): Promise<McpResource[]>`** — List available resources
- **`readResource(uri: string): Promise<any>`** — Read a resource

#### Prompts

- **`listPrompts(): Promise<McpPrompt[]>`** — List available prompts
- **`getPrompt(name: string, args?: object): Promise<any>`** — Get a prompt

### Events

Subscribe to client events:

```typescript
const unsubscribe = client.on((event) => {
  switch (event.type) {
    case 'connected':
      console.log('Connected with session:', event.sessionId);
      break;
    case 'disconnected':
      console.log('Disconnected');
      break;
    case 'session-expired':
      console.log('Session expired, will auto-reconnect');
      break;
    case 'error':
      console.error('Error:', event.error);
      break;
  }
});

// Later: unsubscribe()
```

## Types

```typescript
interface McpTool {
  name: string;
  description?: string;
  inputSchema: {
    type: string;
    properties?: Record<string, any>;
    required?: string[];
  };
}

interface McpToolCallResult {
  content: Array<{
    type: string;
    text?: string;
  }>;
  isError?: boolean;
}

interface McpResource {
  uri: string;
  name: string;
  description?: string;
  mimeType?: string;
}

interface McpPrompt {
  name: string;
  description?: string;
  arguments?: Array<{
    name: string;
    description?: string;
    required?: boolean;
  }>;
}
```

## Features

- **Zero dependencies** — Only uses native `fetch`
- **TypeScript-first** — Full type definitions included
- **Auto-reconnect** — Handles session expiration automatically
- **Framework-agnostic** — Works with any LLM provider (OpenAI, Anthropic, Google, etc.)
- **Browser & Node.js** — Works in both environments

## License

MIT