@mcp-z/client 2.2.1 → 2.2.3

package/README.md

@@ -11,25 +11,42 @@ Programmatic MCP client library for Node.js - connect, discover, and call tools
 ## Install
 
 ```bash
-npm install --save-dev @mcp-z/client
+npm install @mcp-z/client
 ```
 
-Requires Node.js >= 22.
+Requires Node.js >= 20.
 
 ## Quick start
 
-```ts
-import { createServerRegistry } from '@mcp-z/client';
+Create a local stdio server that exposes an `echo` tool:
 
-const registry = createServerRegistry({
-  todoist: { type: 'http', url: 'https://ai.todoist.net/mcp' }
-});
+```bash
+npm install @modelcontextprotocol/sdk zod
+```
 
-const client = await registry.connect('todoist');
-await client.callTool('add-tasks', {
-  tasks: [{ content: 'Learn MCP', priority: 4 }]
-});
+Save this as `echo-server.mjs`:
+
+```js
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const server = new McpServer({ name: 'echo', version: '1.0.0' });
+server.registerTool('echo', { inputSchema: { message: z.string() } }, async ({ message }) => ({
+  content: [{ type: 'text', text: message }]
+}));
+await server.connect(new StdioServerTransport());
+```
+
+Connect to it and print the returned text:
+
+```ts
+import { createServerRegistry } from '@mcp-z/client';
 
+const registry = createServerRegistry({ echo: { command: 'node', args: ['echo-server.mjs'] } });
+const client = await registry.connect('echo');
+const response = await client.callTool('echo', { message: 'hello MCP' });
+console.log(response.text()); // hello MCP
 await registry.close();
 ```
 
@@ -176,12 +193,20 @@ const pinned = await registry.connect('strict-server', {
 
 After connecting, `client.getProtocolEra()` returns `'modern'` or `'legacy'` and `client.getNegotiatedProtocolVersion()` the revision the server settled on.
 
-Note: with `mode: 'auto'` against a stdio server, a legacy server that never answers the `server/discover` probe costs the full request timeout (60s) before the client falls back to the 2025 sequence. The probe ends fast when the server answers it at all — with any reply, even a "method not found" error.
+With `mode: 'auto'` against a stdio server, a legacy server that never answers the `server/discover` probe costs the full 60-second request timeout before the client falls back to the 2025 sequence. Any reply, including a "method not found" error, ends the probe.
 
 ## Requirements
 
-- Node.js >= 22
+- Node.js >= 20
+
+## Agent skill
+
+If a coding agent will use this package, install its agent guidance globally:
+
+```bash
+npx skills add https://github.com/mcp-z/client.git -g -s mcp-z-client
+```
 
-### Documentation
+## Documentation
 
 [API Docs](https://mcp-z.github.io/client)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-z/client",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "Programmatic MCP client library for Node.js - connect, discover, and call tools on Model Context Protocol servers.",
   "keywords": [
     "mcp",
@@ -45,8 +45,7 @@
   "types": "./dist/esm/index.d.ts",
   "files": [
     "dist",
-    "schemas",
-    "AGENTS.md"
+    "schemas"
   ],
   "scripts": {
     "build": "tsds validate",
@@ -70,6 +69,7 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/server": "^2.0.0",
     "@types/express": "^5.0.6",
     "@types/mocha": "^10.0.10",
     "@types/node": "^26.2.0",

package/AGENTS.md

@@ -1,159 +0,0 @@
-# MCP Examples for AI Agents
-
-Quick-start examples for building scripts with MCP servers using `@mcp-z/client`.
-
-## Install
-
-```bash
-npm install @mcp-z/client
-```
-
-## Quick Peek
-
-```javascript
-import { createServerRegistry } from '@mcp-z/client';
-
-const registry = createServerRegistry({ todoist: { url: 'https://ai.todoist.net/mcp' } });
-const client = await registry.connect('todoist');
-await client.callTool('add-tasks', { tasks: [{ content: 'My task', priority: 4 }] });
-await registry.close();
-```
-
-## Full Example: Todoist Task Management
-
-```javascript
-/**
- * This example shows how to use @mcp-z/client to manage tasks via Todoist.
- * Copy this and modify it for your needs!
- *
- * PREREQUISITES:
- *   npm install @mcp-z/client                     # the client library for typescript / javascript
- *   npm install @mcp-z/cli                        # the cli command is "mcpz". Run "mcpz --help" for a full list of commands
- *
- * DISCOVERY (find tools before writing code):
- *   npx @mcp-z/cli search "add task"              # Find the tool you need
- *   npx @mcp-z/cli inspect --servers todoist      # See all available tools
- *   npx @mcp-z/cli call-tool todoist add-tasks '{}' # Test it works
- *
- * TIP: Or load your own .mcp.json file instead of inline config:
- *   const config = JSON.parse(fs.readFileSync('.mcp.json', 'utf-8'));
- *   const registry = createServerRegistry(config.mcpServers);
- */
-
-import { createServerRegistry } from '@mcp-z/client';
-
-// Configure your MCP servers (inline, or load from .mcp.json file)
-const servers = {
-  todoist: {
-    url: 'https://ai.todoist.net/mcp'
-  }
-};
-
-async function main() {
-  const registry = createServerRegistry(servers);
-
-  try {
-    console.log('🚀 Connecting to Todoist...');
-    const client = await registry.connect('todoist');
-
-    console.log('✅ Connected! Adding task...');
-
-    // Add a task to Todoist
-    // See available tools: npx @mcp-z/cli inspect --servers todoist
-    await client.callTool('add-tasks', {
-      tasks: [
-        {
-          content: 'Learn MCP with @mcp-z/client',
-          projectId: undefined, // Optional: add to specific project
-          priority: 4           // 1-4, where 4 is highest
-        }
-      ]
-    });
-
-    console.log('✅ Task added successfully!');
-
-    // List tasks (discovery first: npx @mcp-z/cli inspect --servers todoist)
-    console.log('\n📋 Fetching tasks...');
-    const findResponse = await client.callTool('find-tasks', {
-      searchText: 'Learn MCP'
-    });
-
-    console.log('✅ Tasks found:', findResponse.json());
-
-  } catch (error) {
-    console.error('❌ Error:', error.message);
-    process.exit(1);
-  } finally {
-    console.log('🔒 Closing connection...');
-    await registry.close();
-    console.log('✅ Done!');
-  }
-}
-
-main();
-```
-
-## The Pattern
-
-Once you understand this example, you understand them all:
-
-```javascript
-import { createServerRegistry } from '@mcp-z/client';
-
-const registry = createServerRegistry(servers);  // Configure servers
-try {
-  const client = await registry.connect('server-name');  // Connect
-  await client.callTool('tool-name', { /* args */ });    // Use tools
-} finally {
-  await registry.close();  // Always cleanup
-}
-```
-
-**Configure servers inline or from `.mcp.json`:**
-```javascript
-// Inline config
-const servers = { todoist: { url: '...' } };
-
-// Or load from file
-const config = JSON.parse(fs.readFileSync('.mcp.json', 'utf-8'));
-const servers = config.mcpServers;
-```
-
-## Discovery Workflow
-
-**Before writing code, discover what's available:**
-
-1. **Search for tools:**
-   ```bash
-   npx @mcp-z/cli search "add task"
-   ```
-
-2. **Inspect a server:**
-   ```bash
-   npx @mcp-z/cli inspect --servers todoist
-   ```
-
-3. **Test a tool:**
-   ```bash
-   npx @mcp-z/cli call-tool todoist add-tasks '{"tasks":[{"content":"Test"}]}'
-   ```
-
-4. **Write your script** using `@mcp-z/client`
-
-## Available Public Servers
-
-These servers don't need special setup - just use their URLs:
-
-- **Todoist**: `https://ai.todoist.net/mcp`
-- **Notion**: `https://mcp.notion.com/mcp`
-
-Private servers (require authentication):
-- Google Sheets, Drive, Gmail, Outlook, PDF (contact us for access)
-
-## Need Help?
-
-1. **Discover tools**: `npx @mcp-z/cli search <query>`
-2. **See all tools**: `npx @mcp-z/cli inspect --servers <server>`
-3. **Test first**: `npx @mcp-z/cli call-tool <server> <tool> '{}'`
-
-Once you know a tool works via CLI, use it in your script with `@mcp-z/client`!