@agentrica/mcp 0.5.0 → 0.6.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.
@@ -0,0 +1,161 @@
1
+ // `agentrica-mcp add` e `agentrica-mcp install` (F23): registrano il server in Claude Code con un solo comando, uguale su
2
+ // Mac, Windows e Linux. Chiamano `claude mcp add` (e per install `npm install -g`) senza shell, con gli argomenti in un
3
+ // array: niente quoting di PowerShell, cmd, zsh o bash. La versione è sempre quella di questo pacchetto, fissata.
4
+ // - add: il server parte con npx (su Windows `cmd /c npx`, perché npx è npx.cmd); ambito user, --project o --local.
5
+ // - install: installa questa versione con npm -g e registra `node <cartella globale>/…/server.js` con ambito user.
6
+ // Una registrazione con lo stesso nome nello stesso ambito si sostituisce: rilanciare con una versione nuova aggiorna.
7
+ // Se mancano Node ≥ 22, npm o claude, lo dice e stampa i comandi da lanciare a mano.
8
+ import { spawnSync } from "node:child_process";
9
+ import { existsSync } from "node:fs";
10
+ import { join } from "node:path";
11
+ import { parseArgs } from "node:util";
12
+ import { VERSION } from "./prompt.js";
13
+ const NAME = "agentrica";
14
+ const PACKAGE = `@agentrica/mcp@${VERSION}`;
15
+ const SERVER_IN_PACKAGE = ["@agentrica", "mcp", "dist", "mcp", "src", "server.js"];
16
+ /**
17
+ * Su Windows npm e (se installato con npm) claude sono file .cmd, che Node non avvia senza shell: si passa da
18
+ * cmd.exe con ogni argomento fra virgolette. Gli argomenti sono nostri; con " o % (che cmd espande anche fra
19
+ * virgolette) il comando non parte e si stampa quello da lanciare a mano.
20
+ */
21
+ export function cmdLine(command, args) {
22
+ const all = [command, ...args];
23
+ if (all.some((arg) => /["%\r\n]/.test(arg)))
24
+ return undefined;
25
+ return `"${all.map((arg) => `"${arg}"`).join(" ")}"`;
26
+ }
27
+ function realRun(platform) {
28
+ return (command, args) => {
29
+ const direct = spawnSync(command, args, { encoding: "utf8" });
30
+ const missing = direct.error?.code === "ENOENT";
31
+ if (!(missing && platform === "win32"))
32
+ return { status: direct.status, stdout: direct.stdout ?? "", stderr: direct.stderr ?? "", missing };
33
+ const line = cmdLine(command, args);
34
+ if (!line)
35
+ return { status: null, stdout: "", stderr: "", missing: true };
36
+ const viaCmd = spawnSync("cmd.exe", ["/d", "/s", "/c", line], { encoding: "utf8", windowsVerbatimArguments: true });
37
+ // cmd risponde 9009 quando il comando non esiste.
38
+ return { status: viaCmd.status, stdout: viaCmd.stdout ?? "", stderr: viaCmd.stderr ?? "", missing: viaCmd.status === 9009 };
39
+ };
40
+ }
41
+ const REAL = {
42
+ platform: process.platform,
43
+ nodeVersion: process.versions.node,
44
+ run: realRun(process.platform),
45
+ exists: existsSync,
46
+ out: (text) => process.stdout.write(text),
47
+ };
48
+ /** Il comando con cui il client avvia il server. */
49
+ export function serverCommand(mode, platform, flags, globalRoot = "") {
50
+ if (mode === "install")
51
+ return ["node", join(globalRoot, ...SERVER_IN_PACKAGE), ...flags];
52
+ const npx = ["npx", "-y", PACKAGE, ...flags];
53
+ return platform === "win32" ? ["cmd", "/c", ...npx] : npx;
54
+ }
55
+ /** Il comando da scrivere nel terminale, per i messaggi: gli argomenti con spazi fra virgolette. */
56
+ const shown = (args) => args.map((arg) => (/[\s"]/.test(arg) ? `"${arg}"` : arg)).join(" ");
57
+ const SCOPE_TEXT = {
58
+ user: "ambito user: tutti i tuoi progetti",
59
+ project: "ambito project: .mcp.json in questa cartella, per il team",
60
+ local: "ambito local: solo questo progetto, solo per te",
61
+ };
62
+ /** Esegue il comando; restituisce il codice di uscita. */
63
+ export function runSetup(mode, args, deps = REAL) {
64
+ const say = (line = "") => deps.out(`${line}\n`);
65
+ let scope = "user";
66
+ const flags = [];
67
+ let from;
68
+ try {
69
+ const { values } = parseArgs({
70
+ args,
71
+ options: {
72
+ project: { type: "boolean" },
73
+ local: { type: "boolean" },
74
+ agents: { type: "string" },
75
+ panel: { type: "boolean" },
76
+ "no-ratings": { type: "boolean" },
77
+ "no-update-check": { type: "boolean" },
78
+ // ponytail: --from installa da un .tgz di npm pack, per provare install prima del rilascio (F23-10).
79
+ from: { type: "string" },
80
+ },
81
+ });
82
+ if (values.project && values.local)
83
+ throw new Error("scegli --project o --local, non entrambi");
84
+ if (mode === "install" && (values.project || values.local))
85
+ throw new Error("install registra sempre con ambito user; per un progetto usa add --project o add --local");
86
+ if (mode === "add" && values.from)
87
+ throw new Error("--from vale solo per install");
88
+ scope = values.project ? "project" : values.local ? "local" : "user";
89
+ if (values.agents !== undefined) {
90
+ if (!/^[A-Za-z0-9,-]{1,300}$/.test(values.agents))
91
+ throw new Error("--agents: id di agenti e sigle di reparti separati da virgole, es. --agents aisa,aiwda-08");
92
+ flags.push("--agents", values.agents);
93
+ }
94
+ if (values.panel)
95
+ flags.push("--panel");
96
+ if (values["no-ratings"])
97
+ flags.push("--no-ratings");
98
+ if (values["no-update-check"])
99
+ flags.push("--no-update-check");
100
+ from = values.from;
101
+ }
102
+ catch (error) {
103
+ say(`agentrica ${mode}: ${(error instanceof Error ? error.message : String(error)).replace(/\p{Cc}/gu, " ")}`);
104
+ return 1;
105
+ }
106
+ const win = deps.platform === "win32";
107
+ const manual = (steps) => {
108
+ say("Comandi da lanciare a mano:");
109
+ for (const step of steps)
110
+ say(` ${step}`);
111
+ };
112
+ if (Number(deps.nodeVersion.split(".")[0]) < 22) {
113
+ say(`agentrica ${mode}: serve Node.js 22 o più recente (in uso ${deps.nodeVersion}). Installalo da https://nodejs.org e rilancia:`);
114
+ say(` npx -y ${PACKAGE} ${mode}`);
115
+ return 1;
116
+ }
117
+ let command;
118
+ if (mode === "install") {
119
+ const install = deps.run("npm", ["install", "-g", from ?? PACKAGE]);
120
+ if (install.missing) {
121
+ say("agentrica install: npm non trovato. Installa Node.js 22 o più recente (con npm) da https://nodejs.org e rilancia.");
122
+ return 1;
123
+ }
124
+ if (install.status !== 0) {
125
+ say(`agentrica install: npm install -g non riuscito.${win ? "" : " Se è un problema di permessi, configura una cartella globale di npm tua (npm config set prefix) invece di usare sudo."}`);
126
+ if (install.stderr.trim())
127
+ say(install.stderr.trim());
128
+ return 1;
129
+ }
130
+ const root = deps.run("npm", ["root", "-g"]).stdout.trim();
131
+ command = serverCommand("install", deps.platform, flags, root);
132
+ if (!root || !deps.exists(command[1])) {
133
+ say(`agentrica install: pacchetto installato ma server non trovato in ${root || "(cartella globale di npm sconosciuta)"}.`);
134
+ return 1;
135
+ }
136
+ say(`Installato ${from ? from : PACKAGE} in ${root}.`);
137
+ }
138
+ else {
139
+ command = serverCommand("add", deps.platform, flags);
140
+ }
141
+ const addArgs = ["mcp", "add", "--scope", scope, NAME, "--", ...command];
142
+ const removed = deps.run("claude", ["mcp", "remove", NAME, "--scope", scope]);
143
+ if (removed.missing) {
144
+ say("agentrica: Claude Code (comando claude) non trovato. Installalo e rilancia questo comando, oppure registra il server a mano:");
145
+ manual([shown(["claude", ...addArgs])]);
146
+ say("Per altri client MCP usa lo stesso comando del server nella loro configurazione (README di @agentrica/mcp).");
147
+ return 1;
148
+ }
149
+ const added = deps.run("claude", addArgs);
150
+ if (added.status !== 0) {
151
+ say("agentrica: claude mcp add non riuscito.");
152
+ if ((added.stderr || added.stdout).trim())
153
+ say((added.stderr || added.stdout).trim());
154
+ manual([shown(["claude", ...addArgs])]);
155
+ return 1;
156
+ }
157
+ say(`Agentrica ${VERSION} registrato in Claude Code (${SCOPE_TEXT[scope]})${removed.status === 0 ? ", al posto della registrazione precedente" : ""}.`);
158
+ say(`Comando del server: ${shown(command)}`);
159
+ say("Riavvia Claude Code (o usa /mcp) e controlla con: claude mcp list");
160
+ return 0;
161
+ }
@@ -0,0 +1,10 @@
1
+ export declare const REGISTRY_URL = "https://registry.npmjs.org/-/package/@agentrica/mcp/dist-tags";
2
+ /** Come è installato il server: dalla cartella globale di npm (`install`), dalla cache di npx (`add`, `init`) o da un clone. */
3
+ export type InstallKind = "global" | "npx" | "source";
4
+ export declare function installKind(serverPath: string): InstallKind;
5
+ /** true se `latest` è una versione x.y.z più nuova di `current`. */
6
+ export declare function isNewer(latest: string, current: string): boolean;
7
+ /** La versione `latest` del registro, o undefined per qualunque problema. */
8
+ export declare function fetchLatest(url?: string, doFetch?: typeof fetch): Promise<string | undefined>;
9
+ /** L'avviso per l'utente (anche nel banner del pannello), con il comando giusto per come è installato il server. */
10
+ export declare function updateMessage(current: string, latest: string, kind: InstallKind): string;
@@ -0,0 +1,65 @@
1
+ // Controllo della versione nuova (F23): all'avvio una GET ai dist-tag di @agentrica/mcp sul registro npm, senza
2
+ // parametri né dati. La risposta è un dato esterno: se ne legge al più MAX_BYTES, si accetta solo una versione semver
3
+ // x.y.z e nel testo per il modello entra solo quella. Rete assente o negata, timeout, risposta strana: niente avviso.
4
+ // La versione resta fissata: l'avviso dice solo come aggiornare. --no-update-check lo spegne.
5
+ export const REGISTRY_URL = "https://registry.npmjs.org/-/package/@agentrica/mcp/dist-tags";
6
+ const TIMEOUT_MS = 3_000;
7
+ const MAX_BYTES = 4_096;
8
+ const SEMVER = /^(\d{1,6})\.(\d{1,6})\.(\d{1,6})$/;
9
+ export function installKind(serverPath) {
10
+ if (/[\\/]_npx[\\/]/.test(serverPath))
11
+ return "npx";
12
+ if (/[\\/]node_modules[\\/]@agentrica[\\/]mcp[\\/]/.test(serverPath))
13
+ return "global";
14
+ return "source";
15
+ }
16
+ /** true se `latest` è una versione x.y.z più nuova di `current`. */
17
+ export function isNewer(latest, current) {
18
+ const a = SEMVER.exec(latest);
19
+ const b = SEMVER.exec(current);
20
+ if (!a || !b)
21
+ return false;
22
+ for (let i = 1; i <= 3; i++) {
23
+ const diff = Number(a[i]) - Number(b[i]);
24
+ if (diff !== 0)
25
+ return diff > 0;
26
+ }
27
+ return false;
28
+ }
29
+ /** La versione `latest` del registro, o undefined per qualunque problema. */
30
+ export async function fetchLatest(url = REGISTRY_URL, doFetch = fetch) {
31
+ try {
32
+ const response = await doFetch(url, { headers: { Accept: "application/json" }, signal: AbortSignal.timeout(TIMEOUT_MS) });
33
+ if (!response.ok || !response.body)
34
+ return undefined;
35
+ const reader = response.body.getReader();
36
+ const chunks = [];
37
+ let size = 0;
38
+ for (;;) {
39
+ const { done, value } = await reader.read();
40
+ if (done)
41
+ break;
42
+ size += value.byteLength;
43
+ if (size > MAX_BYTES) {
44
+ await reader.cancel();
45
+ return undefined;
46
+ }
47
+ chunks.push(value);
48
+ }
49
+ const data = JSON.parse(Buffer.concat(chunks).toString("utf8"));
50
+ const latest = typeof data === "object" && data !== null ? data.latest : undefined;
51
+ return typeof latest === "string" && SEMVER.test(latest) ? latest : undefined;
52
+ }
53
+ catch {
54
+ return undefined;
55
+ }
56
+ }
57
+ /** L'avviso per l'utente (anche nel banner del pannello), con il comando giusto per come è installato il server. */
58
+ export function updateMessage(current, latest, kind) {
59
+ const how = kind === "global"
60
+ ? `Per aggiornare: npx -y @agentrica/mcp@${latest} install, poi riavvia il client.`
61
+ : kind === "npx"
62
+ ? `Per aggiornare cambia la versione in @agentrica/mcp@${latest} nel comando del server (claude mcp add o .mcp.json), poi riavvia il client.`
63
+ : "Per aggiornare il clone: git pull, poi riavvia il client.";
64
+ return `È uscita la versione ${latest} di Agentrica (in uso la ${current}). ${how}`;
65
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agentrica/mcp",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "mcpName": "io.github.flgisimone/agentrica",
5
5
  "description": "I 56 agenti IA di Agentrica come server MCP locale (stdio): un prompt per agente, due tool in sola lettura e un tool per valutare gli agenti.",
6
6
  "license": "MIT",
@@ -17,7 +17,8 @@
17
17
  "types": "./dist/mcp/src/catalog.d.ts",
18
18
  "default": "./dist/mcp/src/catalog.js"
19
19
  },
20
- "./package.json": "./package.json"
20
+ "./package.json": "./package.json",
21
+ "./CHANGELOG.md": "./CHANGELOG.md"
21
22
  },
22
23
  "bin": {
23
24
  "agentrica-mcp": "dist/mcp/src/server.js"
@@ -27,7 +28,8 @@
27
28
  "agents",
28
29
  "starter",
29
30
  ".claude/agents",
30
- "README.en.md"
31
+ "README.en.md",
32
+ "CHANGELOG.md"
31
33
  ],
32
34
  "engines": {
33
35
  "node": ">=22"
@@ -148,7 +148,7 @@ Se un passo fallisce ci si ferma, si riferisce l'errore e non si salta ai passi
148
148
 
149
149
  ### 13.8 Rilascio in `main`
150
150
  Non fa parte della chiusura di una fase: si fa solo quando l'utente lo chiede, con la CI di `develop` verde.
151
- 1. Pull request da `develop` a `main` (`gh pr create --base main --head develop --title "Rilascio: FN descrizione breve"`), unita con merge commit quando la CI è verde (`gh pr merge --merge`). Conviene un ruleset su `main` che vieti push diretti e force push.
151
+ 1. Pull request da `develop` a `main` (`gh pr create --base main --head develop --title "Rilascio: FN descrizione breve"`), unita con merge commit quando la CI è verde (`gh pr merge --merge`). Conviene un ruleset su `main` che vieti push diretti e force push. **Subito dopo, `develop` torna allo stesso commit di `main`**: `git fetch`, su `develop` `git merge --ff-only origin/main`, push di `develop`, e `origin/develop` e `origin/main` devono avere lo stesso hash. Una nota scritta dopo il rilascio va in `main` con un'altra PR, poi si riallinea di nuovo. `develop` e `main` sono sempre allineati.
152
152
  2. <!-- Da compilare: hosting, cosa pubblica `main`, passi per le migrazioni, controllo dopo il deploy. -->
153
153
 
154
154
  Deploy e migrazioni in produzione partono sempre con un ok esplicito, a parte da quello della fase.