@astratra/ai 1.13.0 → 1.14.0
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 +23 -0
- package/package.json +5 -3
- package/src/index.d.ts +32 -0
- package/src/index.js +2 -1
- package/src/mcpClient.js +118 -0
package/README.md
CHANGED
|
@@ -305,6 +305,29 @@ outils répond avec ce qui a été lu ; un tour sans texte ni outil lève
|
|
|
305
305
|
`summary(args)` donne les valeurs de la ligne d'étape (`stepParams`, coupées à
|
|
306
306
|
120 caractères) : l'interface écrit la phrase, le serveur n'en écrit aucune.
|
|
307
307
|
|
|
308
|
+
## Se brancher sur un serveur MCP
|
|
309
|
+
|
|
310
|
+
`connectMcpServer` relie une IA à un serveur MCP distant (transport « Streamable HTTP ») et rend ses outils au format des outils natifs, prêts pour `runToolLoop` ou `createToolCaller`. Premier usage : Palabre, la salle où les IA parlent entre elles ; un autre serveur MCP se branche de la même façon.
|
|
311
|
+
|
|
312
|
+
```js
|
|
313
|
+
const { connectMcpServer, runToolLoop } = require('@astratra/ai');
|
|
314
|
+
|
|
315
|
+
const palabre = await connectMcpServer({
|
|
316
|
+
url: 'https://palabre.boutiqueroro.com/mcp',
|
|
317
|
+
headers: { Authorization: `Bearer ${process.env.PALABRE_CLE}` },
|
|
318
|
+
prefix: 'palabre_',
|
|
319
|
+
allow: ['lire_reunion', 'ecrire_message', 'prochaine_reunion', 'retenir_reunion'],
|
|
320
|
+
kinds: { ecrire_message: { kind: 'write', risk: 'LOW' } }
|
|
321
|
+
});
|
|
322
|
+
// palabre.tools s'ajoute aux outils de l'IA ; palabre.instructions donne les règles du serveur.
|
|
323
|
+
await palabre.close();
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
- Ce que rend un serveur MCP est une donnée non fiable : chaque outil porte `external: true`, pour que les gardes le traitent comme tel.
|
|
327
|
+
- Un outil est « read » par défaut ; l'application déclare ceux qui écrivent (`kinds`), avec leur risque, et leur `undo` si elle le demande.
|
|
328
|
+
- `allow` limite les outils à une liste connue : un outil ajouté plus tard par le serveur n'arrive pas en douce.
|
|
329
|
+
- La clé passe par `headers` ; elle n'est ni journalisée ni rendue.
|
|
330
|
+
|
|
308
331
|
## Le flux vers l'app (server-sent events)
|
|
309
332
|
|
|
310
333
|
```js
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astratra/ai",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.14.0",
|
|
4
4
|
"description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra, plus agent guards (@astratra/ai/guards): outbound masking, prompt-injection handling for untrusted tool results, reply checks.",
|
|
5
5
|
"engines": {
|
|
6
6
|
"node": ">=20"
|
|
@@ -28,14 +28,16 @@
|
|
|
28
28
|
"llama.cpp",
|
|
29
29
|
"cpu-inference",
|
|
30
30
|
"guardrails",
|
|
31
|
-
"prompt-injection"
|
|
31
|
+
"prompt-injection",
|
|
32
|
+
"mcp"
|
|
32
33
|
],
|
|
33
34
|
"license": "MIT",
|
|
34
35
|
"publishConfig": {
|
|
35
36
|
"access": "public"
|
|
36
37
|
},
|
|
37
38
|
"dependencies": {
|
|
38
|
-
"@astratra/core": "^1.0.0"
|
|
39
|
+
"@astratra/core": "^1.0.0",
|
|
40
|
+
"@modelcontextprotocol/sdk": "^1.32.1"
|
|
39
41
|
},
|
|
40
42
|
"peerDependencies": {
|
|
41
43
|
"redis": ">=4",
|
package/src/index.d.ts
CHANGED
|
@@ -1162,3 +1162,35 @@ export function createInferenceQueue(options?: { maxConcurrent?: number; maxQueu
|
|
|
1162
1162
|
run<T>(task: () => Awaitable<T>, options?: { signal?: AbortSignal }): Promise<T>;
|
|
1163
1163
|
stats(): { active: number; waiting: number };
|
|
1164
1164
|
};
|
|
1165
|
+
|
|
1166
|
+
/* ─────────────────── Connecteur MCP ─────────────────── */
|
|
1167
|
+
|
|
1168
|
+
/** Un outil d'un serveur MCP, rendu au format des outils natifs ; son résultat est une donnée non fiable (`external`). */
|
|
1169
|
+
export interface McpNativeTool extends NativeTool {
|
|
1170
|
+
external: true;
|
|
1171
|
+
mcp: { name: string };
|
|
1172
|
+
}
|
|
1173
|
+
|
|
1174
|
+
export interface McpConnection {
|
|
1175
|
+
tools: McpNativeTool[];
|
|
1176
|
+
/** Les instructions annoncées par le serveur, ou null. */
|
|
1177
|
+
instructions: string | null;
|
|
1178
|
+
close(): Promise<void>;
|
|
1179
|
+
}
|
|
1180
|
+
|
|
1181
|
+
/** Se connecte à un serveur MCP (Streamable HTTP) et rend ses outils au format des outils natifs. */
|
|
1182
|
+
export function connectMcpServer(options: {
|
|
1183
|
+
url?: string;
|
|
1184
|
+
headers?: Record<string, string>;
|
|
1185
|
+
prefix?: string;
|
|
1186
|
+
allow?: string[];
|
|
1187
|
+
kinds?: Record<string, NativeToolKind | { kind?: NativeToolKind; risk?: DeclaredToolRisk }>;
|
|
1188
|
+
timeoutMs?: number;
|
|
1189
|
+
resultMax?: number;
|
|
1190
|
+
client?: { name: string; version: string };
|
|
1191
|
+
transport?: unknown;
|
|
1192
|
+
fetch?: typeof globalThis.fetch;
|
|
1193
|
+
}): Promise<McpConnection>;
|
|
1194
|
+
|
|
1195
|
+
/** Le nom d'outil Astratra d'un outil MCP (minuscules, chiffres, « _ », 64 caractères au plus). */
|
|
1196
|
+
export function mcpToolName(prefix: string, name: string): string;
|
package/src/index.js
CHANGED
package/src/mcpClient.js
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Connecteur MCP (26/10/2026) : une IA d'Astratra se branche sur un serveur MCP distant (transport « Streamable HTTP »)
|
|
5
|
+
* et en reçoit les outils comme ses outils natifs ({ name, description, parameters, kind, run }), prêts pour
|
|
6
|
+
* runToolLoop / createToolCaller. Premier usage : Palabre, la salle où les IA d'Emch parlent entre elles ; tout autre
|
|
7
|
+
* serveur MCP (GitHub, documentation…) se branche de la même façon.
|
|
8
|
+
*
|
|
9
|
+
* Règles :
|
|
10
|
+
* - ce que rend un serveur MCP est une DONNÉE NON FIABLE : chaque outil est marqué `external: true`, pour que les gardes
|
|
11
|
+
* de l'application (prompt-injection) le traitent comme tel ;
|
|
12
|
+
* - un outil est « read » par défaut ; l'application déclare elle-même ceux qui écrivent (`kinds`), avec leur risque ;
|
|
13
|
+
* - `allow` limite les outils exposés à une liste connue : un serveur qui ajoute un outil ne le donne pas à l'IA en douce ;
|
|
14
|
+
* - la clé (en-tête Authorization) n'est jamais journalisée ni rendue.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
const NAME = /^[a-z][a-z0-9_]{0,63}$/;
|
|
18
|
+
const DEFAULT_RESULT_MAX = 20_000;
|
|
19
|
+
const DEFAULT_TIMEOUT_MS = 20_000;
|
|
20
|
+
|
|
21
|
+
/** Un nom d'outil MCP ramené aux noms d'Astratra (minuscules, chiffres, « _ », 64 caractères au plus). */
|
|
22
|
+
function toolNameOf(prefix, name) {
|
|
23
|
+
const brut = `${prefix || ''}${String(name)}`.toLowerCase().replace(/[^a-z0-9_]+/g, '_').replace(/^_+/, '');
|
|
24
|
+
const nom = /^[a-z]/.test(brut) ? brut : `mcp_${brut}`;
|
|
25
|
+
return nom.slice(0, 64);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** Le texte d'un résultat MCP : les parties texte jointes ; un JSON valide est rendu comme objet. */
|
|
29
|
+
function resultValue(result, max) {
|
|
30
|
+
const texte = (Array.isArray(result?.content) ? result.content : [])
|
|
31
|
+
.filter((part) => part && part.type === 'text' && typeof part.text === 'string')
|
|
32
|
+
.map((part) => part.text)
|
|
33
|
+
.join('\n')
|
|
34
|
+
.slice(0, max);
|
|
35
|
+
if (result?.structuredContent && typeof result.structuredContent === 'object') return result.structuredContent;
|
|
36
|
+
try { return JSON.parse(texte); } catch { return texte; }
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
async function chargerSdk() {
|
|
40
|
+
const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
|
|
41
|
+
const { StreamableHTTPClientTransport } = require('@modelcontextprotocol/sdk/client/streamableHttp.js');
|
|
42
|
+
return { Client, StreamableHTTPClientTransport };
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Se connecte à un serveur MCP et rend ses outils au format des outils natifs.
|
|
47
|
+
*
|
|
48
|
+
* @param {object} options
|
|
49
|
+
* @param {string} options.url adresse du serveur MCP (https://…/mcp)
|
|
50
|
+
* @param {Record<string,string>} [options.headers] en-têtes envoyés à chaque requête (par exemple Authorization: Bearer …)
|
|
51
|
+
* @param {string} [options.prefix] préfixe des noms d'outils (par exemple « palabre_ »)
|
|
52
|
+
* @param {string[]} [options.allow] noms MCP des seuls outils à exposer
|
|
53
|
+
* @param {Record<string,{kind?:string,risk?:string}|string>} [options.kinds] genre et risque par nom MCP (défaut read)
|
|
54
|
+
* @param {number} [options.timeoutMs] délai d'un appel d'outil (défaut 20 s)
|
|
55
|
+
* @param {number} [options.resultMax] taille maximale du texte rendu (défaut 20 000)
|
|
56
|
+
* @param {{name:string,version:string}} [options.client] identité du client annoncée au serveur
|
|
57
|
+
* @param {object} [options.transport] transport MCP déjà construit (tests) ; sinon Streamable HTTP
|
|
58
|
+
* @param {Function} [options.fetch] fetch utilisé par le transport
|
|
59
|
+
* @returns {Promise<{ tools: object[], instructions: string|null, close(): Promise<void> }>}
|
|
60
|
+
*/
|
|
61
|
+
async function connectMcpServer(options = {}) {
|
|
62
|
+
const { url, headers = {}, prefix = '', allow = null, kinds = {}, timeoutMs = DEFAULT_TIMEOUT_MS, resultMax = DEFAULT_RESULT_MAX } = options;
|
|
63
|
+
if (!options.transport && !url) throw new Error('connectMcpServer: url is required');
|
|
64
|
+
const { Client, StreamableHTTPClientTransport } = await chargerSdk();
|
|
65
|
+
const transport = options.transport || new StreamableHTTPClientTransport(new URL(url), {
|
|
66
|
+
requestInit: { headers },
|
|
67
|
+
...(options.fetch ? { fetch: options.fetch } : {})
|
|
68
|
+
});
|
|
69
|
+
const client = new Client(options.client || { name: 'astratra-ai', version: '1.0.0' });
|
|
70
|
+
await client.connect(transport);
|
|
71
|
+
|
|
72
|
+
const decrits = [];
|
|
73
|
+
let curseur;
|
|
74
|
+
do {
|
|
75
|
+
const page = await client.listTools(curseur ? { cursor: curseur } : {});
|
|
76
|
+
decrits.push(...(page.tools || []));
|
|
77
|
+
curseur = page.nextCursor;
|
|
78
|
+
} while (curseur);
|
|
79
|
+
|
|
80
|
+
const permis = allow ? new Set(allow) : null;
|
|
81
|
+
const tools = decrits
|
|
82
|
+
.filter((t) => !permis || permis.has(t.name))
|
|
83
|
+
.map((t) => {
|
|
84
|
+
const name = toolNameOf(prefix, t.name);
|
|
85
|
+
if (!NAME.test(name)) return null;
|
|
86
|
+
const reglage = typeof kinds[t.name] === 'string' ? { kind: kinds[t.name] } : (kinds[t.name] || {});
|
|
87
|
+
const parameters = t.inputSchema && t.inputSchema.type === 'object' ? t.inputSchema : { type: 'object', properties: {} };
|
|
88
|
+
return {
|
|
89
|
+
name,
|
|
90
|
+
description: String(t.description || t.title || t.name).slice(0, 2000),
|
|
91
|
+
parameters,
|
|
92
|
+
kind: reglage.kind || 'read',
|
|
93
|
+
...(reglage.risk ? { risk: reglage.risk } : {}),
|
|
94
|
+
external: true,
|
|
95
|
+
mcp: { name: t.name },
|
|
96
|
+
summary: () => ({}),
|
|
97
|
+
async run(args, ctx = {}) {
|
|
98
|
+
const result = await client.callTool({ name: t.name, arguments: args || {} }, undefined, {
|
|
99
|
+
timeout: timeoutMs,
|
|
100
|
+
...(ctx.signal ? { signal: ctx.signal } : {})
|
|
101
|
+
});
|
|
102
|
+
const data = resultValue(result, resultMax);
|
|
103
|
+
if (result && result.isError) return { data: { erreur: true, detail: data } };
|
|
104
|
+
return { data };
|
|
105
|
+
}
|
|
106
|
+
};
|
|
107
|
+
})
|
|
108
|
+
.filter(Boolean);
|
|
109
|
+
|
|
110
|
+
const instructions = typeof client.getInstructions === 'function' ? (client.getInstructions() || null) : null;
|
|
111
|
+
return {
|
|
112
|
+
tools,
|
|
113
|
+
instructions,
|
|
114
|
+
async close() { await client.close().catch(() => {}); }
|
|
115
|
+
};
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
module.exports = { connectMcpServer, mcpToolName: toolNameOf };
|