@mcp-z/client 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -23,7 +23,7 @@ Requires Node.js >= 22.
|
|
|
23
23
|
import { createServerRegistry } from '@mcp-z/client';
|
|
24
24
|
|
|
25
25
|
const registry = createServerRegistry({
|
|
26
|
-
todoist: { url: 'https://ai.todoist.net/mcp'
|
|
26
|
+
todoist: { type: 'http', url: 'https://ai.todoist.net/mcp' }
|
|
27
27
|
});
|
|
28
28
|
|
|
29
29
|
const client = await registry.connect('todoist');
|
|
@@ -60,17 +60,89 @@ MCP supports stdio and HTTP.
|
|
|
60
60
|
}
|
|
61
61
|
```
|
|
62
62
|
|
|
63
|
-
|
|
63
|
+
**HTTP with start block (extension)**
|
|
64
|
+
|
|
65
|
+
Use `dialects: ['start']` to spawn HTTP servers with `start` blocks.
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
const registry = createServerRegistry(
|
|
69
|
+
{
|
|
70
|
+
api: {
|
|
71
|
+
type: 'http',
|
|
72
|
+
url: 'http://localhost:3000/mcp',
|
|
73
|
+
start: { command: 'node', args: ['server.js'] }
|
|
74
|
+
}
|
|
75
|
+
},
|
|
76
|
+
{ dialects: ['start'] }
|
|
77
|
+
);
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## API overview
|
|
81
|
+
|
|
82
|
+
### Registry
|
|
64
83
|
|
|
65
84
|
- `createServerRegistry(config, options?)`
|
|
66
|
-
- `registry.connect(name)`
|
|
85
|
+
- `registry.connect(name, options?)`
|
|
86
|
+
- `registry.searchCapabilities(query, options?)`
|
|
87
|
+
- `registry.close()`
|
|
88
|
+
|
|
89
|
+
### Managed client
|
|
90
|
+
|
|
67
91
|
- `client.callTool(name, args)`
|
|
92
|
+
- `client.getPrompt(name, args)`
|
|
93
|
+
- `client.readResource(uri)`
|
|
68
94
|
- `client.listTools()` / `client.listResources()` / `client.listPrompts()`
|
|
69
|
-
- `
|
|
95
|
+
- `client.callToolRaw()` / `client.getPromptRaw()` / `client.readResourceRaw()` (raw SDK responses)
|
|
96
|
+
|
|
97
|
+
### Response helpers
|
|
98
|
+
|
|
99
|
+
Tool, prompt, and resource calls return wrappers with:
|
|
100
|
+
|
|
101
|
+
- `json()` - Parse structured content
|
|
102
|
+
- `text()` - First text result
|
|
103
|
+
- `raw()` - Raw MCP response
|
|
104
|
+
|
|
105
|
+
## Examples
|
|
106
|
+
|
|
107
|
+
### Call a tool
|
|
108
|
+
|
|
109
|
+
```ts
|
|
110
|
+
const response = await client.callTool('drive-search', { query: 'Q4 Reports' });
|
|
111
|
+
const data = response.json();
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### Get a prompt
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
const prompt = await client.getPrompt('query-syntax', { service: 'gmail' });
|
|
118
|
+
console.log(prompt.text());
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Read a resource
|
|
122
|
+
|
|
123
|
+
```ts
|
|
124
|
+
const resource = await client.readResource('mcp-pdf://abc123');
|
|
125
|
+
console.log(resource.text());
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### Search capabilities
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
const results = await registry.searchCapabilities('message send', {
|
|
132
|
+
types: ['tool'],
|
|
133
|
+
servers: ['gmail', 'outlook']
|
|
134
|
+
});
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## createServerRegistry options
|
|
138
|
+
|
|
139
|
+
- `cwd` - Working directory for spawned processes (default: `process.cwd()`)
|
|
140
|
+
- `env` - Base env for all servers (if set, `process.env` is not merged)
|
|
141
|
+
- `dialects` - Which servers to spawn: `['servers']` (stdio), `['start']` (HTTP start blocks), or both
|
|
70
142
|
|
|
71
143
|
## OAuth (DCR)
|
|
72
144
|
|
|
73
|
-
If an HTTP server supports DCR, pass a token store
|
|
145
|
+
If an HTTP server supports DCR, pass a token store via `dcrAuthenticator`:
|
|
74
146
|
|
|
75
147
|
```ts
|
|
76
148
|
import Keyv from 'keyv';
|
|
@@ -9,10 +9,11 @@ Object.defineProperty(exports, "validateServers", {
|
|
|
9
9
|
}
|
|
10
10
|
});
|
|
11
11
|
var _ajv = require("ajv");
|
|
12
|
+
var _ajvformats = /*#__PURE__*/ _interop_require_default(require("ajv-formats"));
|
|
12
13
|
var _fs = /*#__PURE__*/ _interop_require_wildcard(require("fs"));
|
|
13
|
-
var _module = require("module");
|
|
14
14
|
var _modulerootsync = /*#__PURE__*/ _interop_require_default(require("module-root-sync"));
|
|
15
15
|
var _path = /*#__PURE__*/ _interop_require_wildcard(require("path"));
|
|
16
|
+
var _url = /*#__PURE__*/ _interop_require_wildcard(require("url"));
|
|
16
17
|
function _interop_require_default(obj) {
|
|
17
18
|
return obj && obj.__esModule ? obj : {
|
|
18
19
|
default: obj
|
|
@@ -60,9 +61,8 @@ function _interop_require_wildcard(obj, nodeInterop) {
|
|
|
60
61
|
return newObj;
|
|
61
62
|
}
|
|
62
63
|
// Import ajv-formats (CommonJS module - use createRequire for ESM compatibility)
|
|
63
|
-
var
|
|
64
|
-
var
|
|
65
|
-
var packageRoot = (0, _modulerootsync.default)(__filename);
|
|
64
|
+
var __dirname = _path.dirname(typeof __filename !== 'undefined' ? __filename : _url.fileURLToPath(require("url").pathToFileURL(__filename).toString()));
|
|
65
|
+
var packageRoot = (0, _modulerootsync.default)(__dirname);
|
|
66
66
|
// Module-level cache for schema and validator
|
|
67
67
|
var schemaCache = null;
|
|
68
68
|
var validatorCache = null;
|
|
@@ -92,7 +92,7 @@ var validatorCache = null;
|
|
|
92
92
|
strictSchema: false
|
|
93
93
|
});
|
|
94
94
|
// Add format validators (uri, email, etc.)
|
|
95
|
-
|
|
95
|
+
(0, _ajvformats.default)(ajv);
|
|
96
96
|
validatorCache = ajv.compile(schema);
|
|
97
97
|
return validatorCache;
|
|
98
98
|
}
|
|
@@ -103,8 +103,8 @@ function validateServers(servers) {
|
|
|
103
103
|
if (!valid) {
|
|
104
104
|
var _validate_errors;
|
|
105
105
|
var errors = ((_validate_errors = validate.errors) === null || _validate_errors === void 0 ? void 0 : _validate_errors.map(function(e) {
|
|
106
|
-
var path = e.instancePath || '(root)';
|
|
107
|
-
return "".concat(path, ": ").concat(e.message);
|
|
106
|
+
var _$path = e.instancePath || '(root)';
|
|
107
|
+
return "".concat(_$path, ": ").concat(e.message);
|
|
108
108
|
})) || [];
|
|
109
109
|
return {
|
|
110
110
|
valid: false,
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/config/validate-config.ts"],"sourcesContent":["import { Ajv, type ErrorObject } from 'ajv';\nimport
|
|
1
|
+
{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/config/validate-config.ts"],"sourcesContent":["import { Ajv, type ErrorObject } from 'ajv';\nimport addFormats from 'ajv-formats';\nimport * as fs from 'fs';\nimport moduleRoot from 'module-root-sync';\nimport * as path from 'path';\nimport * as url from 'url';\n\n// Import ajv-formats (CommonJS module - use createRequire for ESM compatibility)\nconst __dirname = path.dirname(typeof __filename !== 'undefined' ? __filename : url.fileURLToPath(import.meta.url));\nconst packageRoot = moduleRoot(__dirname);\n\n/**\n * Validation result for servers configuration\n */\nexport interface ValidationResult {\n valid: boolean;\n errors?: string[];\n warnings?: string[];\n}\n\n// Module-level cache for schema and validator\nlet schemaCache: object | null = null;\nlet validatorCache: ReturnType<Ajv['compile']> | null = null;\n\n/**\n * Get servers schema (loads once from bundled file, then caches)\n */\nfunction getSchema(): object {\n if (schemaCache) {\n return schemaCache;\n }\n\n const schemaPath = path.join(packageRoot, 'schemas/servers.schema.json');\n if (!fs.existsSync(schemaPath)) {\n throw new Error(`Servers schema not found at: ${schemaPath}`);\n }\n\n schemaCache = JSON.parse(fs.readFileSync(schemaPath, 'utf8')) as object;\n return schemaCache;\n}\n\n/**\n * Get compiled AJV validator (creates once, then caches)\n */\nfunction getValidator(): ReturnType<Ajv['compile']> {\n if (validatorCache) {\n return validatorCache;\n }\n\n const schema = getSchema();\n const ajv = new Ajv({\n allErrors: true,\n verbose: true,\n strictSchema: false, // Allow non-standard keywords like \"example\"\n });\n\n // Add format validators (uri, email, etc.)\n addFormats(ajv);\n\n validatorCache = ajv.compile(schema);\n return validatorCache;\n}\n\n/**\n * Validate servers configuration against JSON Schema\n *\n * @param servers - Servers configuration object to validate (map of server names to configs)\n * @returns ValidationResult with valid flag, errors, and warnings\n */\nexport function validateServers(servers: unknown): ValidationResult {\n try {\n const validate = getValidator();\n const valid = validate(servers);\n\n if (!valid) {\n const errors =\n validate.errors?.map((e: ErrorObject) => {\n const path = e.instancePath || '(root)';\n return `${path}: ${e.message}`;\n }) || [];\n\n return { valid: false, errors };\n }\n\n const warnings: string[] = [];\n return { valid: true, warnings };\n } catch (err) {\n return {\n valid: false,\n errors: [`Configuration validation failed: ${(err as Error).message}`],\n };\n }\n}\n"],"names":["validateServers","__dirname","path","dirname","__filename","url","fileURLToPath","packageRoot","moduleRoot","schemaCache","validatorCache","getSchema","schemaPath","join","fs","existsSync","Error","JSON","parse","readFileSync","getValidator","schema","ajv","Ajv","allErrors","verbose","strictSchema","addFormats","compile","servers","validate","valid","errors","map","e","instancePath","message","warnings","err"],"mappings":";;;;+BAqEgBA;;;eAAAA;;;mBArEsB;iEACf;0DACH;qEACG;4DACD;2DACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAErB,iFAAiF;AACjF,IAAMC,YAAYC,MAAKC,OAAO,CAAC,OAAOC,eAAe,cAAcA,aAAaC,KAAIC,aAAa,CAAC;AAClG,IAAMC,cAAcC,IAAAA,uBAAU,EAACP;AAW/B,8CAA8C;AAC9C,IAAIQ,cAA6B;AACjC,IAAIC,iBAAoD;AAExD;;CAEC,GACD,SAASC;IACP,IAAIF,aAAa;QACf,OAAOA;IACT;IAEA,IAAMG,aAAaV,MAAKW,IAAI,CAACN,aAAa;IAC1C,IAAI,CAACO,IAAGC,UAAU,CAACH,aAAa;QAC9B,MAAM,IAAII,MAAM,AAAC,gCAA0C,OAAXJ;IAClD;IAEAH,cAAcQ,KAAKC,KAAK,CAACJ,IAAGK,YAAY,CAACP,YAAY;IACrD,OAAOH;AACT;AAEA;;CAEC,GACD,SAASW;IACP,IAAIV,gBAAgB;QAClB,OAAOA;IACT;IAEA,IAAMW,SAASV;IACf,IAAMW,MAAM,IAAIC,QAAG,CAAC;QAClBC,WAAW;QACXC,SAAS;QACTC,cAAc;IAChB;IAEA,2CAA2C;IAC3CC,IAAAA,mBAAU,EAACL;IAEXZ,iBAAiBY,IAAIM,OAAO,CAACP;IAC7B,OAAOX;AACT;AAQO,SAASV,gBAAgB6B,OAAgB;IAC9C,IAAI;QACF,IAAMC,WAAWV;QACjB,IAAMW,QAAQD,SAASD;QAEvB,IAAI,CAACE,OAAO;gBAERD;YADF,IAAME,SACJF,EAAAA,mBAAAA,SAASE,MAAM,cAAfF,uCAAAA,iBAAiBG,GAAG,CAAC,SAACC;gBACpB,IAAMhC,SAAOgC,EAAEC,YAAY,IAAI;gBAC/B,OAAO,AAAC,GAAWD,OAAThC,QAAK,MAAc,OAAVgC,EAAEE,OAAO;YAC9B,OAAM,EAAE;YAEV,OAAO;gBAAEL,OAAO;gBAAOC,QAAAA;YAAO;QAChC;QAEA,IAAMK,WAAqB,EAAE;QAC7B,OAAO;YAAEN,OAAO;YAAMM,UAAAA;QAAS;IACjC,EAAE,OAAOC,KAAK;QACZ,OAAO;YACLP,OAAO;YACPC,QAAQ;gBAAE,oCAA0D,OAAvB,AAACM,IAAcF,OAAO;aAAG;QACxE;IACF;AACF"}
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
import { Ajv } from 'ajv';
|
|
2
|
+
import addFormats from 'ajv-formats';
|
|
2
3
|
import * as fs from 'fs';
|
|
3
|
-
import { createRequire } from 'module';
|
|
4
4
|
import moduleRoot from 'module-root-sync';
|
|
5
5
|
import * as path from 'path';
|
|
6
|
+
import * as url from 'url';
|
|
6
7
|
// Import ajv-formats (CommonJS module - use createRequire for ESM compatibility)
|
|
7
|
-
const
|
|
8
|
-
const
|
|
9
|
-
const packageRoot = moduleRoot(import.meta.filename);
|
|
8
|
+
const __dirname = path.dirname(typeof __filename !== 'undefined' ? __filename : url.fileURLToPath(import.meta.url));
|
|
9
|
+
const packageRoot = moduleRoot(__dirname);
|
|
10
10
|
// Module-level cache for schema and validator
|
|
11
11
|
let schemaCache = null;
|
|
12
12
|
let validatorCache = null;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/config/validate-config.ts"],"sourcesContent":["import { Ajv, type ErrorObject } from 'ajv';\nimport
|
|
1
|
+
{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/config/validate-config.ts"],"sourcesContent":["import { Ajv, type ErrorObject } from 'ajv';\nimport addFormats from 'ajv-formats';\nimport * as fs from 'fs';\nimport moduleRoot from 'module-root-sync';\nimport * as path from 'path';\nimport * as url from 'url';\n\n// Import ajv-formats (CommonJS module - use createRequire for ESM compatibility)\nconst __dirname = path.dirname(typeof __filename !== 'undefined' ? __filename : url.fileURLToPath(import.meta.url));\nconst packageRoot = moduleRoot(__dirname);\n\n/**\n * Validation result for servers configuration\n */\nexport interface ValidationResult {\n valid: boolean;\n errors?: string[];\n warnings?: string[];\n}\n\n// Module-level cache for schema and validator\nlet schemaCache: object | null = null;\nlet validatorCache: ReturnType<Ajv['compile']> | null = null;\n\n/**\n * Get servers schema (loads once from bundled file, then caches)\n */\nfunction getSchema(): object {\n if (schemaCache) {\n return schemaCache;\n }\n\n const schemaPath = path.join(packageRoot, 'schemas/servers.schema.json');\n if (!fs.existsSync(schemaPath)) {\n throw new Error(`Servers schema not found at: ${schemaPath}`);\n }\n\n schemaCache = JSON.parse(fs.readFileSync(schemaPath, 'utf8')) as object;\n return schemaCache;\n}\n\n/**\n * Get compiled AJV validator (creates once, then caches)\n */\nfunction getValidator(): ReturnType<Ajv['compile']> {\n if (validatorCache) {\n return validatorCache;\n }\n\n const schema = getSchema();\n const ajv = new Ajv({\n allErrors: true,\n verbose: true,\n strictSchema: false, // Allow non-standard keywords like \"example\"\n });\n\n // Add format validators (uri, email, etc.)\n addFormats(ajv);\n\n validatorCache = ajv.compile(schema);\n return validatorCache;\n}\n\n/**\n * Validate servers configuration against JSON Schema\n *\n * @param servers - Servers configuration object to validate (map of server names to configs)\n * @returns ValidationResult with valid flag, errors, and warnings\n */\nexport function validateServers(servers: unknown): ValidationResult {\n try {\n const validate = getValidator();\n const valid = validate(servers);\n\n if (!valid) {\n const errors =\n validate.errors?.map((e: ErrorObject) => {\n const path = e.instancePath || '(root)';\n return `${path}: ${e.message}`;\n }) || [];\n\n return { valid: false, errors };\n }\n\n const warnings: string[] = [];\n return { valid: true, warnings };\n } catch (err) {\n return {\n valid: false,\n errors: [`Configuration validation failed: ${(err as Error).message}`],\n };\n }\n}\n"],"names":["Ajv","addFormats","fs","moduleRoot","path","url","__dirname","dirname","__filename","fileURLToPath","packageRoot","schemaCache","validatorCache","getSchema","schemaPath","join","existsSync","Error","JSON","parse","readFileSync","getValidator","schema","ajv","allErrors","verbose","strictSchema","compile","validateServers","servers","validate","valid","errors","map","e","instancePath","message","warnings","err"],"mappings":"AAAA,SAASA,GAAG,QAA0B,MAAM;AAC5C,OAAOC,gBAAgB,cAAc;AACrC,YAAYC,QAAQ,KAAK;AACzB,OAAOC,gBAAgB,mBAAmB;AAC1C,YAAYC,UAAU,OAAO;AAC7B,YAAYC,SAAS,MAAM;AAE3B,iFAAiF;AACjF,MAAMC,YAAYF,KAAKG,OAAO,CAAC,OAAOC,eAAe,cAAcA,aAAaH,IAAII,aAAa,CAAC,YAAYJ,GAAG;AACjH,MAAMK,cAAcP,WAAWG;AAW/B,8CAA8C;AAC9C,IAAIK,cAA6B;AACjC,IAAIC,iBAAoD;AAExD;;CAEC,GACD,SAASC;IACP,IAAIF,aAAa;QACf,OAAOA;IACT;IAEA,MAAMG,aAAaV,KAAKW,IAAI,CAACL,aAAa;IAC1C,IAAI,CAACR,GAAGc,UAAU,CAACF,aAAa;QAC9B,MAAM,IAAIG,MAAM,CAAC,6BAA6B,EAAEH,YAAY;IAC9D;IAEAH,cAAcO,KAAKC,KAAK,CAACjB,GAAGkB,YAAY,CAACN,YAAY;IACrD,OAAOH;AACT;AAEA;;CAEC,GACD,SAASU;IACP,IAAIT,gBAAgB;QAClB,OAAOA;IACT;IAEA,MAAMU,SAAST;IACf,MAAMU,MAAM,IAAIvB,IAAI;QAClBwB,WAAW;QACXC,SAAS;QACTC,cAAc;IAChB;IAEA,2CAA2C;IAC3CzB,WAAWsB;IAEXX,iBAAiBW,IAAII,OAAO,CAACL;IAC7B,OAAOV;AACT;AAEA;;;;;CAKC,GACD,OAAO,SAASgB,gBAAgBC,OAAgB;IAC9C,IAAI;QACF,MAAMC,WAAWT;QACjB,MAAMU,QAAQD,SAASD;QAEvB,IAAI,CAACE,OAAO;gBAERD;YADF,MAAME,SACJF,EAAAA,mBAAAA,SAASE,MAAM,cAAfF,uCAAAA,iBAAiBG,GAAG,CAAC,CAACC;gBACpB,MAAM9B,OAAO8B,EAAEC,YAAY,IAAI;gBAC/B,OAAO,GAAG/B,KAAK,EAAE,EAAE8B,EAAEE,OAAO,EAAE;YAChC,OAAM,EAAE;YAEV,OAAO;gBAAEL,OAAO;gBAAOC;YAAO;QAChC;QAEA,MAAMK,WAAqB,EAAE;QAC7B,OAAO;YAAEN,OAAO;YAAMM;QAAS;IACjC,EAAE,OAAOC,KAAK;QACZ,OAAO;YACLP,OAAO;YACPC,QAAQ;gBAAC,CAAC,iCAAiC,EAAE,AAACM,IAAcF,OAAO,EAAE;aAAC;QACxE;IACF;AACF"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mcp-z/client",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "Programmatic MCP client library for Node.js - connect, discover, and call tools on Model Context Protocol servers.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"mcp",
|
|
@@ -63,15 +63,14 @@
|
|
|
63
63
|
},
|
|
64
64
|
"dependencies": {
|
|
65
65
|
"@modelcontextprotocol/sdk": "^1.0.0",
|
|
66
|
-
"ajv": "^8.
|
|
67
|
-
"ajv-formats": "^3.0.
|
|
66
|
+
"ajv": "^8.0.0",
|
|
67
|
+
"ajv-formats": "^3.0.0",
|
|
68
68
|
"get-port": "^7.1.0",
|
|
69
69
|
"keyv": "^5.5.5",
|
|
70
70
|
"keyv-file": "^5.3.3",
|
|
71
|
-
"module-root-sync": "^2.0.
|
|
71
|
+
"module-root-sync": "^2.0.0"
|
|
72
72
|
},
|
|
73
73
|
"devDependencies": {
|
|
74
|
-
"@types/express": "^5.0.6",
|
|
75
74
|
"@types/mocha": "^10.0.10",
|
|
76
75
|
"@types/node": "^25.0.2",
|
|
77
76
|
"dotenv": "^17.2.3",
|
|
@@ -84,7 +83,7 @@
|
|
|
84
83
|
"zod": "^4.0.0"
|
|
85
84
|
},
|
|
86
85
|
"engines": {
|
|
87
|
-
"node": ">=
|
|
86
|
+
"node": ">=18"
|
|
88
87
|
},
|
|
89
88
|
"tsds": {
|
|
90
89
|
"source": "src/index.ts"
|