npm package: @phoenix-erp/mcp-client
Description: Typed MCP client SDK for Phoenix ERP server
Latest version: 0.3.0

# @phoenix-erp/mcp-client

Typed client SDK for connecting to the Phoenix ERP MCP server over HTTP or custom transports.

## Install

```bash
npm install @phoenix-erp/mcp-client
```

## Quick Start

```typescript
import { PhoenixMcpClient } from '@phoenix-erp/mcp-client';

const client = await PhoenixMcpClient.connect({
  baseUrl: 'http://localhost:3100',
  token: 'your-phx-mcp-token',
});

const results = await client.searchDocs('user authentication', { mode: 'hybrid' });
console.log(results);

await client.disconnect();
```

### Production (behind Traefik)

```typescript
const client = await PhoenixMcpClient.connect({
  baseUrl: 'https://mcp.phx-erp.cloud/mcp-server',
  token: 'your-phx-mcp-token',
});
```

### Custom Transport (stdio)

```typescript
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = await PhoenixMcpClient.connectWithTransport(
  new StdioClientTransport({ command: 'npx', args: ['-y', '@phoenix-erp/mcp'] })
);
```

## Methods

### Tool Wrappers

| Method | Description |
|--------|-------------|
| `searchDocs(query, options?)` | Hybrid search across ERP documentation. Options: `category`, `limit`, `fuzzy`, `mode` |
| `getSection(document, sectionPath)` | Retrieve a specific section by document slug and path |
| `listDocuments(category?)` | List all loaded documents, optionally filtered by category |
| `listSections(document, maxDepth?)` | Table of contents for a document |
| `getCodeExamples(query, options?)` | Find code examples by topic. Options: `language`, `category` |
| `getArchitecture(topic)` | Architecture info and mermaid diagrams |
| `getFileMap(document, section?)` | File structure for a module |

### Resources

| Method | Description |
|--------|-------------|
| `listResources()` | List all available MCP resources |
| `readResource(uri)` | Read a resource by URI (e.g. `erp://docs`, `erp://dev-guide/{slug}`) |

### Utilities

| Method | Description |
|--------|-------------|
| `callTool(name, args)` | Generic tool call for any registered MCP tool |
| `listTools()` | List all tools with names and descriptions |
| `serverInstructions` | Server-provided instructions (getter) |
| `disconnect()` | Close the connection and terminate the session |

## Full Example

```typescript
import { PhoenixMcpClient } from '@phoenix-erp/mcp-client';

const client = await PhoenixMcpClient.connect({
  baseUrl: 'http://localhost:3100',
  token: 'your-phx-mcp-token',
});

const results = await client.searchDocs('backup restore', { mode: 'hybrid', limit: 5 });
const section = await client.getSection('getting-started', 'Setup > Environment Variables');
const docs = await client.listDocuments('dev-guide');
const toc = await client.listSections('getting-started');
const code = await client.getCodeExamples('graphql resolver', { language: 'typescript' });
const arch = await client.getArchitecture('module architecture');
const files = await client.getFileMap('getting-started');

const allDocs = await client.readResource('erp://docs');
const raw = await client.callTool('search_docs', { query: 'backup', limit: 3 });

await client.disconnect();
```

## Requirements

- Node.js >= 18
- A running `@phoenix-erp/mcp-server` instance with a valid `PHX_MCP_TOKEN`

## License

MIT