@astratra/ai 1.13.0 → 1.15.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 CHANGED
@@ -51,7 +51,7 @@ ne fait que lire. Le mode d'une exécution est `newRun({ mode: 'action' | 'read'
51
51
 
52
52
  **Textes courts (1.13.0)** : un texte de moins de `injection.minWords` mots (3 par
53
53
  défaut ; `0` envoie tout) n'est pas soumis au modèle d'injection, qui note un ou
54
- deux mots au hasard (mesuré sur Examen d'État le 20/10/2026 : « oui » 0,96,
54
+ deux mots au hasard (mesuré en production le 20/10/2026 : « oui » 0,96,
55
55
  « Salut » 0,72, alors que toutes les vraies attaques dépassaient 0,993 dès trois
56
56
  mots). Le résultat porte `score: null` et la raison `too_short_to_scan`.
57
57
 
@@ -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`. Tout serveur MCP se branche de la même façon.
311
+
312
+ ```js
313
+ const { connectMcpServer, runToolLoop } = require('@astratra/ai');
314
+
315
+ const salon = await connectMcpServer({
316
+ url: 'https://salon.example.com/mcp',
317
+ headers: { Authorization: `Bearer ${process.env.SALON_CLE}` },
318
+ prefix: 'salon_',
319
+ allow: ['lire_reunion', 'ecrire_message', 'prochaine_reunion', 'retenir_reunion'],
320
+ kinds: { ecrire_message: { kind: 'write', risk: 'LOW' } }
321
+ });
322
+ // salon.tools s'ajoute aux outils de l'IA ; salon.instructions donne les règles du serveur.
323
+ await salon.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
@@ -320,14 +343,20 @@ un proxy (`X-Accel-Buffering: no`) ; écrire après la fin ne fait rien.
320
343
  ## Recherche web (Serper)
321
344
 
322
345
  ```js
323
- const resultats = await searchSerper({ query, sites: ['jw.org'], hl: 'fr' }, {
346
+ const resultats = await searchSerper({ query, sites: ['example.com'], hl: 'fr', gl: 'fr', period: 'week' }, {
324
347
  key: process.env.SERPER_API_KEY, fetch,
325
348
  accept: (resultat, url) => !estHostile(resultat) // écarté avant que le modèle ne lise
326
349
  });
327
350
  ```
328
351
 
329
- Des résultats https avec un titre, 8 au plus. Sans clé, rien n'est demandé
330
- (`code: 'WEB_SEARCH_NO_KEY'`) ; une panne porte `'WEB_SEARCH_FAILED'`, jamais la clé.
352
+ Des résultats https avec un titre, 8 au plus. `gl` choisit le pays, `period`
353
+ (`hour`, `day`, `week`, `month`, `year`) ne garde que les résultats récents.
354
+ Sans clé, rien n'est demandé (`code: 'WEB_SEARCH_NO_KEY'`) ; une panne porte
355
+ `'WEB_SEARCH_FAILED'` et, si Serper a répondu, son `status` — jamais la clé.
356
+
357
+ Pour plusieurs moteurs (Serper, Brave, Tavily, Exa) fusionnés sans mélanger les
358
+ pages, la lecture sûre d'une page et un outil prêt pour les modèles, voir
359
+ [`@astratra/web-search`](../web-search/README.md), qui réutilise `searchSerper`.
331
360
 
332
361
  ## Registre d'outils
333
362
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astratra/ai",
3
- "version": "1.13.0",
3
+ "version": "1.15.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/gemini.js CHANGED
@@ -303,4 +303,4 @@ function createGeminiProvider(options = {}) {
303
303
  };
304
304
  }
305
305
 
306
- module.exports = { askGeminiModel, createGeminiProvider, readGeminiGrounding };
306
+ module.exports = { askGeminiModel, createGeminiProvider, readGeminiGrounding, geminiSchema };
@@ -240,7 +240,7 @@ function createGuards(options = {}) {
240
240
 
241
241
  async function scanForInjection(content, threshold) {
242
242
  /* One or two words carry no instruction, and the injection model scores them at random (« oui » 0.96,
243
- « Salut » 0.72 on Examen d'État, 20/10/2026, where every real attack scored ≥ 0.993 from three words up). */
243
+ « Salut » 0.72 in production, 20/10/2026, where every real attack scored ≥ 0.993 from three words up). */
244
244
  if (wordCount(content) < minWords) return { score: null, suspected: false, chunks: 0, short: true };
245
245
  const pieces = windowsOf(content, chunkChars, overlapChars);
246
246
  let max = 0;
package/src/index.d.ts CHANGED
@@ -709,6 +709,8 @@ export function askGeminiModel(
709
709
 
710
710
  /** Les sources d'une réponse generateContent (ou d'un de ses candidats), nettoyées et bornées. Ne lève jamais. */
711
711
  export function readGeminiGrounding(answer: unknown): GeminiGrounding;
712
+ /** Un schéma JSON accepté par l'API Gemini native : additionalProperties, $schema et $id retirés à toute profondeur. */
713
+ export function geminiSchema<T>(schema: T): T;
712
714
 
713
715
  export function createGeminiProvider(options: ChatProviderOptions & {
714
716
  id?: string;
@@ -820,9 +822,15 @@ export function openEventStream(
820
822
 
821
823
  export interface WebResult { title: string; url: string; snippet: string; date: string | null }
822
824
 
823
- /** Lève une erreur de code 'WEB_SEARCH_NO_KEY' (rien n'est demandé) ou 'WEB_SEARCH_FAILED'. */
825
+ export type SerperPeriod = 'hour' | 'day' | 'week' | 'month' | 'year';
826
+ export const SERPER_PERIODS: Readonly<Record<SerperPeriod, string>>;
827
+
828
+ /**
829
+ * Lève une erreur de code 'WEB_SEARCH_NO_KEY' (rien n'est demandé) ou 'WEB_SEARCH_FAILED', avec `status` quand Serper a
830
+ * répondu. Pour plusieurs moteurs fusionnés et la lecture des pages, voir @astratra/web-search, qui réutilise celui-ci.
831
+ */
824
832
  export function searchSerper(
825
- search: { query: string; sites?: string[]; hl?: string; num?: number },
833
+ search: { query: string; sites?: string[]; hl?: string; gl?: string; period?: SerperPeriod; num?: number },
826
834
  io: { key: string | null | undefined; fetch: FetchLike; accept?: (result: WebResult, url: URL) => boolean; timeoutMs?: number; endpoint?: string }
827
835
  ): Promise<WebResult[]>;
828
836
 
@@ -1162,3 +1170,35 @@ export function createInferenceQueue(options?: { maxConcurrent?: number; maxQueu
1162
1170
  run<T>(task: () => Awaitable<T>, options?: { signal?: AbortSignal }): Promise<T>;
1163
1171
  stats(): { active: number; waiting: number };
1164
1172
  };
1173
+
1174
+ /* ─────────────────── Connecteur MCP ─────────────────── */
1175
+
1176
+ /** Un outil d'un serveur MCP, rendu au format des outils natifs ; son résultat est une donnée non fiable (`external`). */
1177
+ export interface McpNativeTool extends NativeTool {
1178
+ external: true;
1179
+ mcp: { name: string };
1180
+ }
1181
+
1182
+ export interface McpConnection {
1183
+ tools: McpNativeTool[];
1184
+ /** Les instructions annoncées par le serveur, ou null. */
1185
+ instructions: string | null;
1186
+ close(): Promise<void>;
1187
+ }
1188
+
1189
+ /** Se connecte à un serveur MCP (Streamable HTTP) et rend ses outils au format des outils natifs. */
1190
+ export function connectMcpServer(options: {
1191
+ url?: string;
1192
+ headers?: Record<string, string>;
1193
+ prefix?: string;
1194
+ allow?: string[];
1195
+ kinds?: Record<string, NativeToolKind | { kind?: NativeToolKind; risk?: DeclaredToolRisk }>;
1196
+ timeoutMs?: number;
1197
+ resultMax?: number;
1198
+ client?: { name: string; version: string };
1199
+ transport?: unknown;
1200
+ fetch?: typeof globalThis.fetch;
1201
+ }): Promise<McpConnection>;
1202
+
1203
+ /** Le nom d'outil Astratra d'un outil MCP (minuscules, chiffres, « _ », 64 caractères au plus). */
1204
+ export function mcpToolName(prefix: string, name: string): string;
package/src/index.js CHANGED
@@ -27,5 +27,6 @@ module.exports = {
27
27
  ...require('./serviceHttp'),
28
28
  ...require('./serviceLanguage'),
29
29
  ...require('./voice'),
30
- ...require('./providerLimits')
30
+ ...require('./providerLimits'),
31
+ ...require('./mcpClient')
31
32
  };
@@ -0,0 +1,117 @@
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. Tout serveur MCP (GitHub, documentation…) se branche de la même façon.
7
+ *
8
+ * Règles :
9
+ * - ce que rend un serveur MCP est une DONNÉE NON FIABLE : chaque outil est marqué `external: true`, pour que les gardes
10
+ * de l'application (prompt-injection) le traitent comme tel ;
11
+ * - un outil est « read » par défaut ; l'application déclare elle-même ceux qui écrivent (`kinds`), avec leur risque ;
12
+ * - `allow` limite les outils exposés à une liste connue : un serveur qui ajoute un outil ne le donne pas à l'IA en douce ;
13
+ * - la clé (en-tête Authorization) n'est jamais journalisée ni rendue.
14
+ */
15
+
16
+ const NAME = /^[a-z][a-z0-9_]{0,63}$/;
17
+ const DEFAULT_RESULT_MAX = 20_000;
18
+ const DEFAULT_TIMEOUT_MS = 20_000;
19
+
20
+ /** Un nom d'outil MCP ramené aux noms d'Astratra (minuscules, chiffres, « _ », 64 caractères au plus). */
21
+ function toolNameOf(prefix, name) {
22
+ const brut = `${prefix || ''}${String(name)}`.toLowerCase().replace(/[^a-z0-9_]+/g, '_').replace(/^_+/, '');
23
+ const nom = /^[a-z]/.test(brut) ? brut : `mcp_${brut}`;
24
+ return nom.slice(0, 64);
25
+ }
26
+
27
+ /** Le texte d'un résultat MCP : les parties texte jointes ; un JSON valide est rendu comme objet. */
28
+ function resultValue(result, max) {
29
+ const texte = (Array.isArray(result?.content) ? result.content : [])
30
+ .filter((part) => part && part.type === 'text' && typeof part.text === 'string')
31
+ .map((part) => part.text)
32
+ .join('\n')
33
+ .slice(0, max);
34
+ if (result?.structuredContent && typeof result.structuredContent === 'object') return result.structuredContent;
35
+ try { return JSON.parse(texte); } catch { return texte; }
36
+ }
37
+
38
+ async function chargerSdk() {
39
+ const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
40
+ const { StreamableHTTPClientTransport } = require('@modelcontextprotocol/sdk/client/streamableHttp.js');
41
+ return { Client, StreamableHTTPClientTransport };
42
+ }
43
+
44
+ /**
45
+ * Se connecte à un serveur MCP et rend ses outils au format des outils natifs.
46
+ *
47
+ * @param {object} options
48
+ * @param {string} options.url adresse du serveur MCP (https://…/mcp)
49
+ * @param {Record<string,string>} [options.headers] en-têtes envoyés à chaque requête (par exemple Authorization: Bearer …)
50
+ * @param {string} [options.prefix] préfixe des noms d'outils (par exemple « salon_ »)
51
+ * @param {string[]} [options.allow] noms MCP des seuls outils à exposer
52
+ * @param {Record<string,{kind?:string,risk?:string}|string>} [options.kinds] genre et risque par nom MCP (défaut read)
53
+ * @param {number} [options.timeoutMs] délai d'un appel d'outil (défaut 20 s)
54
+ * @param {number} [options.resultMax] taille maximale du texte rendu (défaut 20 000)
55
+ * @param {{name:string,version:string}} [options.client] identité du client annoncée au serveur
56
+ * @param {object} [options.transport] transport MCP déjà construit (tests) ; sinon Streamable HTTP
57
+ * @param {Function} [options.fetch] fetch utilisé par le transport
58
+ * @returns {Promise<{ tools: object[], instructions: string|null, close(): Promise<void> }>}
59
+ */
60
+ async function connectMcpServer(options = {}) {
61
+ const { url, headers = {}, prefix = '', allow = null, kinds = {}, timeoutMs = DEFAULT_TIMEOUT_MS, resultMax = DEFAULT_RESULT_MAX } = options;
62
+ if (!options.transport && !url) throw new Error('connectMcpServer: url is required');
63
+ const { Client, StreamableHTTPClientTransport } = await chargerSdk();
64
+ const transport = options.transport || new StreamableHTTPClientTransport(new URL(url), {
65
+ requestInit: { headers },
66
+ ...(options.fetch ? { fetch: options.fetch } : {})
67
+ });
68
+ const client = new Client(options.client || { name: 'astratra-ai', version: '1.0.0' });
69
+ await client.connect(transport);
70
+
71
+ const decrits = [];
72
+ let curseur;
73
+ do {
74
+ const page = await client.listTools(curseur ? { cursor: curseur } : {});
75
+ decrits.push(...(page.tools || []));
76
+ curseur = page.nextCursor;
77
+ } while (curseur);
78
+
79
+ const permis = allow ? new Set(allow) : null;
80
+ const tools = decrits
81
+ .filter((t) => !permis || permis.has(t.name))
82
+ .map((t) => {
83
+ const name = toolNameOf(prefix, t.name);
84
+ if (!NAME.test(name)) return null;
85
+ const reglage = typeof kinds[t.name] === 'string' ? { kind: kinds[t.name] } : (kinds[t.name] || {});
86
+ const parameters = t.inputSchema && t.inputSchema.type === 'object' ? t.inputSchema : { type: 'object', properties: {} };
87
+ return {
88
+ name,
89
+ description: String(t.description || t.title || t.name).slice(0, 2000),
90
+ parameters,
91
+ kind: reglage.kind || 'read',
92
+ ...(reglage.risk ? { risk: reglage.risk } : {}),
93
+ external: true,
94
+ mcp: { name: t.name },
95
+ summary: () => ({}),
96
+ async run(args, ctx = {}) {
97
+ const result = await client.callTool({ name: t.name, arguments: args || {} }, undefined, {
98
+ timeout: timeoutMs,
99
+ ...(ctx.signal ? { signal: ctx.signal } : {})
100
+ });
101
+ const data = resultValue(result, resultMax);
102
+ if (result && result.isError) return { data: { erreur: true, detail: data } };
103
+ return { data };
104
+ }
105
+ };
106
+ })
107
+ .filter(Boolean);
108
+
109
+ const instructions = typeof client.getInstructions === 'function' ? (client.getInstructions() || null) : null;
110
+ return {
111
+ tools,
112
+ instructions,
113
+ async close() { await client.close().catch(() => {}); }
114
+ };
115
+ }
116
+
117
+ module.exports = { connectMcpServer, mcpToolName: toolNameOf };
package/src/webSearch.js CHANGED
@@ -5,15 +5,21 @@
5
5
  * seulement, un titre obligatoire, au plus `num`, et un filtre de l'appelant
6
6
  * (un site hostile, une source refusée) appliqué AVANT que le modèle ne lise.
7
7
  * La clé part dans l'en-tête et n'apparaît dans aucune erreur.
8
+ *
9
+ * C'est aussi l'adaptateur Serper de @astratra/web-search, qui le réutilise
10
+ * (fusion de plusieurs moteurs, lecture des pages) au lieu d'en écrire un autre.
8
11
  */
9
12
 
10
13
  const DEFAULT_ENDPOINT = 'https://google.serper.dev/search';
11
14
  const DEFAULT_NUM = 8;
12
15
  const DEFAULT_TIMEOUT_MS = 10_000;
16
+ /** La période de Google (`tbs=qdr:…`) : dernière heure, jour, semaine, mois, an. */
17
+ const PERIODS = Object.freeze({ hour: 'qdr:h', day: 'qdr:d', week: 'qdr:w', month: 'qdr:m', year: 'qdr:y' });
13
18
 
14
- function failure(code, message) {
19
+ function failure(code, message, status) {
15
20
  const error = new Error(message);
16
21
  error.code = code;
22
+ if (status !== undefined) error.status = status;
17
23
  return error;
18
24
  }
19
25
 
@@ -22,6 +28,8 @@ function failure(code, message) {
22
28
  * @param {string} search.query
23
29
  * @param {string[]} [search.sites] la recherche restreinte à ces sites (site:a OR site:b).
24
30
  * @param {string} [search.hl] la langue de l'interface de recherche.
31
+ * @param {string} [search.gl] le pays des résultats (code à deux lettres).
32
+ * @param {string} [search.period] 'hour' | 'day' | 'week' | 'month' | 'year' : seulement les résultats récents.
25
33
  * @param {number} [search.num] Défaut 8.
26
34
  * @param {object} io
27
35
  * @param {string} io.key
@@ -30,25 +38,36 @@ function failure(code, message) {
30
38
  * @param {number} [io.timeoutMs] Défaut 10 s.
31
39
  * @param {string} [io.endpoint]
32
40
  * @returns {Promise<{ title: string, url: string, snippet: string, date: string|null }[]>}
33
- * @throws {Error} code 'WEB_SEARCH_NO_KEY' sans clé (rien n'est demandé), 'WEB_SEARCH_FAILED' sinon.
41
+ * @throws {Error} code 'WEB_SEARCH_NO_KEY' sans clé (rien n'est demandé), 'WEB_SEARCH_FAILED' sinon,
42
+ * avec `status` quand Serper a répondu (429, 5xx…) : de quoi décider d'un repli.
34
43
  */
35
44
  async function searchSerper(search = {}, io = {}) {
36
45
  if (!io.key) throw failure('WEB_SEARCH_NO_KEY', 'no key');
37
46
  if (typeof io.fetch !== 'function') throw new Error('searchSerper requires io.fetch.');
38
47
  const num = search.num || DEFAULT_NUM;
39
48
  const scope = (search.sites || []).map((site) => `site:${site}`).join(' OR ');
49
+ if (search.period !== undefined && !PERIODS[search.period]) throw new Error(`searchSerper: unknown period ${search.period}.`);
50
+ const extra = {
51
+ ...(search.hl ? { hl: search.hl } : {}),
52
+ ...(search.gl ? { gl: String(search.gl).toLowerCase() } : {}),
53
+ ...(search.period ? { tbs: PERIODS[search.period] } : {})
54
+ };
40
55
  let answer;
56
+ let status;
41
57
  try {
42
58
  const response = await io.fetch(io.endpoint || DEFAULT_ENDPOINT, {
43
59
  method: 'POST',
44
60
  headers: { 'X-API-KEY': io.key, 'content-type': 'application/json' },
45
- body: JSON.stringify({ q: scope ? `${search.query} ${scope}` : search.query, num, ...(search.hl ? { hl: search.hl } : {}) }),
61
+ body: JSON.stringify({ q: scope ? `${search.query} ${scope}` : search.query, num, ...extra }),
46
62
  signal: globalThis.AbortSignal.timeout(io.timeoutMs || DEFAULT_TIMEOUT_MS)
47
63
  });
48
- if (!response.ok) throw new Error(`Serper answered ${response.status}`);
64
+ if (!response.ok) {
65
+ status = response.status;
66
+ throw new Error(`Serper answered ${response.status}`);
67
+ }
49
68
  answer = await response.json();
50
69
  } catch (error) {
51
- throw failure('WEB_SEARCH_FAILED', error.message);
70
+ throw failure('WEB_SEARCH_FAILED', error.message, status);
52
71
  }
53
72
  const accept = typeof io.accept === 'function' ? io.accept : () => true;
54
73
  return (Array.isArray(answer?.organic) ? answer.organic : [])
@@ -68,4 +87,4 @@ async function searchSerper(search = {}, io = {}) {
68
87
  .slice(0, num);
69
88
  }
70
89
 
71
- module.exports = { searchSerper };
90
+ module.exports = { searchSerper, SERPER_PERIODS: PERIODS };