@agentrica/mcp 0.3.3 → 0.5.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.
Files changed (84) hide show
  1. package/.claude/agents/business-product/biz-business-analyst-requirements-strategist.md +18 -0
  2. package/.claude/agents/business-product/biz-business-development-manager.md +18 -0
  3. package/.claude/agents/business-product/biz-business-financial-analyst.md +18 -0
  4. package/.claude/agents/business-product/biz-chief-officer.md +18 -0
  5. package/.claude/agents/business-product/biz-customer-success-retention-strategist.md +18 -0
  6. package/.claude/agents/business-product/biz-growth-monetization-manager.md +18 -0
  7. package/.claude/agents/business-product/biz-market-research-analyst.md +18 -0
  8. package/.claude/agents/business-product/biz-product-innovation-strategist.md +18 -0
  9. package/.claude/agents/business-product/biz-product-manager.md +18 -0
  10. package/.claude/agents/business-product/biz-product-marketing-manager.md +18 -0
  11. package/.claude/agents/business-product/biz-product-portfolio-roadmap-manager.md +18 -0
  12. package/.claude/agents/business-product/biz-sales-revenue-strategist.md +18 -0
  13. package/.claude/agents/cybersecurity/sec-appsec-engineer.md +18 -0
  14. package/.claude/agents/cybersecurity/sec-awareness-engineer.md +18 -0
  15. package/.claude/agents/cybersecurity/sec-ciso.md +18 -0
  16. package/.claude/agents/cybersecurity/sec-cloud-security-engineer.md +18 -0
  17. package/.claude/agents/cybersecurity/sec-iam-engineer.md +18 -0
  18. package/.claude/agents/cybersecurity/sec-incident-response.md +18 -0
  19. package/.claude/agents/cybersecurity/sec-network-security-engineer.md +18 -0
  20. package/.claude/agents/cybersecurity/sec-pentest-specialist.md +18 -0
  21. package/.claude/agents/cybersecurity/sec-risk-compliance-auditor.md +18 -0
  22. package/.claude/agents/cybersecurity/sec-security-architect.md +18 -0
  23. package/.claude/agents/cybersecurity/sec-soc-analyst.md +18 -0
  24. package/.claude/agents/cybersecurity/sec-vulnerability-management.md +18 -0
  25. package/.claude/agents/privacy-compliance/privacy-breach-response.md +18 -0
  26. package/.claude/agents/privacy-compliance/privacy-chief-officer.md +18 -0
  27. package/.claude/agents/privacy-compliance/privacy-compliance-auditor.md +18 -0
  28. package/.claude/agents/privacy-compliance/privacy-data-governance.md +18 -0
  29. package/.claude/agents/privacy-compliance/privacy-data-subject-rights.md +18 -0
  30. package/.claude/agents/privacy-compliance/privacy-dpia-specialist.md +18 -0
  31. package/.claude/agents/privacy-compliance/privacy-gdpr-specialist.md +18 -0
  32. package/.claude/agents/privacy-compliance/privacy-legal-specialist.md +18 -0
  33. package/.claude/agents/privacy-compliance/privacy-security-engineer.md +18 -0
  34. package/.claude/agents/privacy-compliance/privacy-vendor-compliance.md +18 -0
  35. package/.claude/agents/software/sw-architect.md +18 -0
  36. package/.claude/agents/software/sw-backend-developer.md +18 -0
  37. package/.claude/agents/software/sw-code-reviewer.md +18 -0
  38. package/.claude/agents/software/sw-cto.md +18 -0
  39. package/.claude/agents/software/sw-database-engineer.md +18 -0
  40. package/.claude/agents/software/sw-devops-engineer.md +18 -0
  41. package/.claude/agents/software/sw-frontend-developer.md +18 -0
  42. package/.claude/agents/software/sw-fullstack-developer.md +18 -0
  43. package/.claude/agents/software/sw-functional-analyst.md +18 -0
  44. package/.claude/agents/software/sw-performance-engineer.md +18 -0
  45. package/.claude/agents/software/sw-qa-engineer.md +18 -0
  46. package/.claude/agents/software/sw-security-engineer.md +18 -0
  47. package/.claude/agents/web-design/design-accessibility-specialist.md +18 -0
  48. package/.claude/agents/web-design/design-dataviz-designer.md +18 -0
  49. package/.claude/agents/web-design/design-director.md +18 -0
  50. package/.claude/agents/web-design/design-information-architect.md +18 -0
  51. package/.claude/agents/web-design/design-system-specialist.md +18 -0
  52. package/.claude/agents/web-design/design-ui-designer.md +18 -0
  53. package/.claude/agents/web-design/design-usability-auditor.md +18 -0
  54. package/.claude/agents/web-design/design-ux-designer.md +18 -0
  55. package/.claude/agents/web-design/design-ux-researcher.md +18 -0
  56. package/.claude/agents/web-design/design-ux-writer.md +18 -0
  57. package/README.en.md +44 -9
  58. package/README.md +43 -10
  59. package/dist/mcp/src/init.d.ts +6 -0
  60. package/dist/mcp/src/init.js +103 -0
  61. package/dist/mcp/src/page/app.js +70 -4
  62. package/dist/mcp/src/page/index.html +4 -0
  63. package/dist/mcp/src/page/style.css +9 -1
  64. package/dist/mcp/src/panel.d.ts +16 -1
  65. package/dist/mcp/src/panel.js +38 -2
  66. package/dist/mcp/src/project.js +2 -2
  67. package/dist/mcp/src/prompt.d.ts +6 -2
  68. package/dist/mcp/src/prompt.js +12 -2
  69. package/dist/mcp/src/ratings.d.ts +54 -0
  70. package/dist/mcp/src/ratings.js +115 -0
  71. package/dist/mcp/src/server.js +88 -11
  72. package/package.json +5 -3
  73. package/starter/.github/workflows/ci.yml +65 -0
  74. package/starter/.nvmrc +1 -0
  75. package/starter/AGENTS.md +89 -0
  76. package/starter/CLAUDE.md +1 -0
  77. package/starter/CONVENTIONS.md +192 -0
  78. package/starter/README.md +20 -0
  79. package/starter/audit/README.md +15 -0
  80. package/starter/docs/AI Multi-Agency System.md +516 -0
  81. package/starter/docs/README.md +7 -0
  82. package/starter/gitignore +36 -0
  83. package/starter/plan/00-base.md +47 -0
  84. package/starter/plan/README.md +37 -0
@@ -9,6 +9,7 @@ import { readFileSync } from "node:fs";
9
9
  import { createServer } from "node:http";
10
10
  import { join } from "node:path";
11
11
  import { readProject } from "./project.js";
12
+ import { MAX_COMMENT, NOTICE } from "./ratings.js";
12
13
  const MAX_BODY_BYTES = 16_000;
13
14
  const MAX_NOTE = 2000;
14
15
  const MAX_ACTIVITY = 20;
@@ -79,6 +80,19 @@ export function parseAnswer(question, body) {
79
80
  return null;
80
81
  return { choices: picked, note: note.trim() };
81
82
  }
83
+ /** Controlla una valutazione dalla pagina: agente fra quelli usati, voto intero 1–5, commento corto, casella booleana. */
84
+ export function parseRate(used, body) {
85
+ if (typeof body !== "object" || body === null)
86
+ return null;
87
+ const { agentId, rating, comment = "", publish = false } = body;
88
+ if (typeof agentId !== "string" || !used.has(agentId))
89
+ return null;
90
+ if (typeof rating !== "number" || !Number.isInteger(rating) || rating < 1 || rating > 5)
91
+ return null;
92
+ if (typeof comment !== "string" || comment.length > MAX_COMMENT || typeof publish !== "boolean")
93
+ return null;
94
+ return { agentId, rating, comment: comment.trim(), publish };
95
+ }
82
96
  /** Apre l'URL nel browser predefinito; se non riesce (es. sessione remota) l'URL resta nella risposta del tool. */
83
97
  export function openBrowser(url) {
84
98
  const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
@@ -91,7 +105,7 @@ export function openBrowser(url) {
91
105
  // Nessun browser: l'utente apre l'URL a mano.
92
106
  }
93
107
  }
94
- export async function startPanel(root, pageDir = join(import.meta.dirname, "page")) {
108
+ export async function startPanel(root, ratings, pageDir = join(import.meta.dirname, "page")) {
95
109
  const token = randomBytes(32).toString("hex");
96
110
  const pages = Object.fromEntries(Object.entries(PAGE_FILES).map(([route, [file, type]]) => [route, { body: readFileSync(join(pageDir, file)), type }]));
97
111
  const pending = new Map();
@@ -135,7 +149,9 @@ export async function startPanel(root, pageDir = join(import.meta.dirname, "page
135
149
  if (req.method === "GET" && url.pathname === "/api/state") {
136
150
  const project = await readProject(root);
137
151
  const questions = [...pending.values()].map((p) => p.question);
138
- return send(res, 200, JSON.stringify({ project, questions, activity }), "application/json; charset=utf-8");
152
+ const rated = ratings ? [...new Set(activity.map((a) => a.id))].filter((id) => ratings.isRated(id)) : [];
153
+ const rating = ratings ? { notice: NOTICE, maxComment: MAX_COMMENT, rated } : null;
154
+ return send(res, 200, JSON.stringify({ project, questions, activity, rating }), "application/json; charset=utf-8");
139
155
  }
140
156
  if (req.method === "GET" && url.pathname === "/api/events") {
141
157
  res.writeHead(200, { ...SECURITY_HEADERS, "Content-Type": "text/event-stream; charset=utf-8", Connection: "keep-alive" });
@@ -144,6 +160,26 @@ export async function startPanel(root, pageDir = join(import.meta.dirname, "page
144
160
  req.on("close", () => viewers.delete(res));
145
161
  return;
146
162
  }
163
+ if (req.method === "POST" && url.pathname === "/api/rate" && ratings) {
164
+ if (req.headers.origin !== origin)
165
+ return send(res, 403, "Origine non valida.");
166
+ if (!req.headers["content-type"]?.startsWith("application/json"))
167
+ return send(res, 415, "Serve JSON.");
168
+ let body;
169
+ try {
170
+ body = JSON.parse(await readBody(req));
171
+ }
172
+ catch {
173
+ return send(res, 400, "Richiesta non valida.");
174
+ }
175
+ const input = parseRate(new Set(activity.map((a) => a.id)), body);
176
+ if (!input)
177
+ return send(res, 400, "Valutazione non valida.");
178
+ // L'invio dalla pagina è la conferma dell'utente: la pagina mostra l'avviso accanto al pulsante.
179
+ const result = await ratings.rate(input);
180
+ changed();
181
+ return send(res, result.ok ? 200 : 502, JSON.stringify(result), "application/json; charset=utf-8");
182
+ }
147
183
  if (req.method === "POST" && url.pathname === "/api/answer") {
148
184
  if (req.headers.origin !== origin)
149
185
  return send(res, 403, "Origine non valida.");
@@ -1,5 +1,5 @@
1
1
  // Lettura del progetto dell'utente per il pannello: fasi e backlog da plan/, rilievi da plan/ e audit/, stato di git.
2
- // Il formato è quello di agentic-starter, descritto nel README del pacchetto. Si legge solo dentro plan/ e audit/
2
+ // Il formato è quello che crea `init` (init.ts), descritto nel README del pacchetto. Si legge solo dentro plan/ e audit/
3
3
  // della cartella del progetto: i link simbolici che escono sono rifiutati e ogni file ha un limite di dimensione.
4
4
  // Un file mancante o fuori formato diventa un problema in `problems`, mai un errore che ferma il pannello.
5
5
  import { execFile } from "node:child_process";
@@ -50,7 +50,7 @@ function readPhases(root, plan, problems) {
50
50
  readme = readInside(root, join(plan, "README.md"));
51
51
  }
52
52
  catch {
53
- problems.push("Non trovo plan/README.md: il pannello legge il formato di agentic-starter (vedi il README del pacchetto).");
53
+ problems.push("Non trovo plan/README.md: il pannello legge il formato creato da `agentrica-mcp init` (vedi il README del pacchetto).");
54
54
  return [];
55
55
  }
56
56
  const fasi = section(readme, "Fasi");
@@ -1,6 +1,6 @@
1
1
  import type { Agent, Department } from "../../catalog/src/index.ts";
2
2
  /** Versione del server, uguale a quella di package.json (lo controlla prompt.test.ts). */
3
- export declare const VERSION = "0.3.3";
3
+ export declare const VERSION = "0.5.0";
4
4
  /**
5
5
  * Un reparto della squadra di --agents. Non ha `director`: con un reparto filtrato il direttore può essere fuori
6
6
  * squadra, così il tipo impedisce di usarlo senza controllare (rilievo di F12).
@@ -22,4 +22,8 @@ export declare function agentSummary({ department, agent }: Found): string;
22
22
  * senza elenco, tutto il catalogo. Un nome sconosciuto o un elenco vuoto è un errore che lo nomina.
23
23
  */
24
24
  export declare function selectSquad(catalog: readonly Department[], spec?: string): SquadDepartment[];
25
- export declare function agentText({ department, agent }: Found, task?: string): string;
25
+ /** La riga con cui l'agente si presenta: «AISA-02 · ALTAIR — Senior Software Architect, reparto AISA (Software)». */
26
+ export declare function introLine({ department, agent }: Found): string;
27
+ export declare function agentText(found: Found, task?: string, { ratings }?: {
28
+ ratings?: boolean;
29
+ }): string;
@@ -1,5 +1,5 @@
1
1
  /** Versione del server, uguale a quella di package.json (lo controlla prompt.test.ts). */
2
- export const VERSION = "0.3.3";
2
+ export const VERSION = "0.5.0";
3
3
  /** Cerca un agente per id, senza distinguere maiuscole e minuscole («aisa-02» o «AISA-02»). */
4
4
  export function findAgent(catalog, id) {
5
5
  const wanted = id.toUpperCase();
@@ -50,13 +50,23 @@ export function selectSquad(catalog, spec) {
50
50
  .map(({ director: _, ...d }) => ({ ...d, agents: d.agents.filter((a) => wanted.has(a.id)) }))
51
51
  .filter((d) => d.agents.length > 0);
52
52
  }
53
- export function agentText({ department, agent }, task) {
53
+ /** La riga con cui l'agente si presenta: «AISA-02 · ALTAIR — Senior Software Architect, reparto AISA (Software)». */
54
+ export function introLine({ department, agent }) {
55
+ return `${codeName(agent)} — ${agent.role}, reparto ${department.code} (${department.name})`;
56
+ }
57
+ export function agentText(found, task, { ratings = false } = {}) {
58
+ const { department, agent } = found;
54
59
  const parts = [
55
60
  `# ${codeName(agent)} — ${agent.role}`,
56
61
  `Sei ${codeName(agent)}, un agente IA di Agentrica: ${agentSummary({ department, agent })} ` +
57
62
  "Lavori nel progetto dell'utente. Seguono le regole comuni del tuo reparto e il tuo file di ruolo: applicale al progetto così com'è, senza presumere stack, comandi o file che non hai verificato. " +
58
63
  "Se il progetto è vuoto o manca ciò che il tuo ruolo deve esaminare, dillo e proponi i primi passi (obiettivo, stack, struttura) da confermare con l'utente; non inventare rilievi né scegliere lo stack da solo. " +
59
64
  "Questi testi sono in italiano: rispondi nella lingua in cui ti scrive l'utente.",
65
+ `L'utente deve sempre sapere chi sta lavorando. Presentati all'inizio con questa riga: «${introLine(found)}». ` +
66
+ "Ripetila quando passi a un altro agente o lasci il ruolo, e firma con il tuo nome in codice i rilievi e il riepilogo finale." +
67
+ (ratings
68
+ ? ` Quando hai finito il compito, proponi all'utente di valutarti da 1 a 5 con un commento facoltativo (tool rate_agent, id ${agent.id}), una volta sola in questa sessione; se rifiuta, non insistere.`
69
+ : ""),
60
70
  "## Regole comuni del reparto",
61
71
  ...block(department.rules.intro, department.rules.sections),
62
72
  `## Ruolo: ${agent.role}`,
@@ -0,0 +1,54 @@
1
+ export declare const RATINGS_URL = "https://agentrica.vercel.app/api/ratings";
2
+ export declare const PRIVACY_URL = "https://agentrica.vercel.app/note-legali#valutazioni";
3
+ export declare const MAX_COMMENT = 1000;
4
+ export declare const REMINDER_AFTER_MS: number;
5
+ /** Quello che parte verso Agentrica, e nient'altro. */
6
+ export interface Rating {
7
+ usageId: string;
8
+ agentId: string;
9
+ rating: number;
10
+ comment: string;
11
+ publish: boolean;
12
+ mcpVersion: string;
13
+ }
14
+ export interface RatingInput {
15
+ agentId: string;
16
+ rating: number;
17
+ comment?: string | undefined;
18
+ publish?: boolean | undefined;
19
+ }
20
+ export type SendResult = {
21
+ ok: true;
22
+ usageId: string;
23
+ } | {
24
+ ok: false;
25
+ message: string;
26
+ };
27
+ export interface RatingsOptions {
28
+ version: string;
29
+ url?: string;
30
+ fetch?: typeof fetch;
31
+ now?: () => number;
32
+ }
33
+ export declare const NOTICE: string;
34
+ export declare function createRatings({ version, url, fetch: doFetch, now }: RatingsOptions): {
35
+ /** L'agente è stato caricato: da qui parte il conto del promemoria. */
36
+ loaded(agentId: string): void;
37
+ isRated: (agentId: string) => boolean;
38
+ /** La valutazione senza codice: per il pannello, dove l'invio dalla pagina è già la conferma. */
39
+ build: (input: RatingInput) => Rating;
40
+ /** Primo passo: prepara il contenuto e restituisce il codice da usare per inviarlo. */
41
+ draft(input: RatingInput): {
42
+ code: string;
43
+ rating: Rating;
44
+ };
45
+ /** Secondo passo: invia il contenuto del codice, una volta sola. */
46
+ confirm(code: string, agentId: string): Promise<SendResult>;
47
+ /** Invio di un contenuto già confermato dall'utente (dal secondo passo o dal pannello). */
48
+ send(rating: Rating): Promise<SendResult>;
49
+ /** Agenti caricati da almeno 30 minuti, non valutati e non ancora ricordati: si ricordano una volta sola. */
50
+ due(): string[];
51
+ };
52
+ export type Ratings = ReturnType<typeof createRatings>;
53
+ /** Testo dell'anteprima: cosa parte, l'avviso e il codice. */
54
+ export declare function previewText(name: string, code: string, rating: Rating): string;
@@ -0,0 +1,115 @@
1
+ // Valutazioni degli agenti (F20): anteprima con codice monouso, invio all'endpoint del sito, promemoria.
2
+ // È l'unico punto del server che apre una connessione, e solo dopo la conferma dell'utente: l'invio parte con il codice
3
+ // dell'anteprima e manda esattamente il contenuto mostrato. Niente compito, file o percorsi: solo i campi di Rating.
4
+ // Tutto resta in memoria (nessun file); i tempi e fetch si passano dall'esterno per i test.
5
+ import { randomBytes, randomUUID } from "node:crypto";
6
+ export const RATINGS_URL = "https://agentrica.vercel.app/api/ratings";
7
+ export const PRIVACY_URL = "https://agentrica.vercel.app/note-legali#valutazioni";
8
+ export const MAX_COMMENT = 1000;
9
+ const CODE_TTL_MS = 10 * 60_000;
10
+ const SEND_TIMEOUT_MS = 5_000;
11
+ export const REMINDER_AFTER_MS = 30 * 60_000;
12
+ export const NOTICE = "Parte solo ciò che vedi qui: niente compito, codice o file del progetto. " +
13
+ `Non scrivere nel commento nomi, dati personali o parti del progetto. Informativa: ${PRIVACY_URL}`;
14
+ export function createRatings({ version, url = RATINGS_URL, fetch: doFetch = fetch, now = Date.now }) {
15
+ // Un id casuale per agente e sessione: non collega sessioni né agenti diversi, ferma solo i doppi invii.
16
+ const usage = new Map();
17
+ const loadedAt = new Map();
18
+ const rated = new Set();
19
+ const reminded = new Set();
20
+ const drafts = new Map();
21
+ const build = (input) => ({
22
+ usageId: usageId(input.agentId),
23
+ agentId: input.agentId,
24
+ rating: input.rating,
25
+ comment: (input.comment ?? "").trim(),
26
+ publish: input.publish ?? false,
27
+ mcpVersion: version,
28
+ });
29
+ const usageId = (agentId) => {
30
+ let id = usage.get(agentId);
31
+ if (!id)
32
+ usage.set(agentId, (id = randomUUID()));
33
+ return id;
34
+ };
35
+ return {
36
+ /** L'agente è stato caricato: da qui parte il conto del promemoria. */
37
+ loaded(agentId) {
38
+ if (!loadedAt.has(agentId))
39
+ loadedAt.set(agentId, now());
40
+ usageId(agentId);
41
+ },
42
+ isRated: (agentId) => rated.has(agentId),
43
+ /** La valutazione senza codice: per il pannello, dove l'invio dalla pagina è già la conferma. */
44
+ build,
45
+ /** Primo passo: prepara il contenuto e restituisce il codice da usare per inviarlo. */
46
+ draft(input) {
47
+ for (const [code, entry] of drafts)
48
+ if (entry.expires <= now())
49
+ drafts.delete(code);
50
+ const rating = build(input);
51
+ const code = randomBytes(4).toString("hex");
52
+ drafts.set(code, { rating, expires: now() + CODE_TTL_MS });
53
+ return { code, rating };
54
+ },
55
+ /** Secondo passo: invia il contenuto del codice, una volta sola. */
56
+ async confirm(code, agentId) {
57
+ const entry = drafts.get(code);
58
+ if (entry && entry.rating.agentId !== agentId)
59
+ return { ok: false, message: "Codice non valido per questo agente: prepara di nuovo l'anteprima." };
60
+ drafts.delete(code);
61
+ if (!entry || entry.expires <= now())
62
+ return { ok: false, message: "Codice scaduto o già usato: prepara di nuovo l'anteprima." };
63
+ return this.send(entry.rating);
64
+ },
65
+ /** Invio di un contenuto già confermato dall'utente (dal secondo passo o dal pannello). */
66
+ async send(rating) {
67
+ if (rated.has(rating.agentId))
68
+ return { ok: false, message: `${rating.agentId} è già stato valutato in questa sessione.` };
69
+ let response;
70
+ try {
71
+ response = await doFetch(url, {
72
+ method: "POST",
73
+ headers: { "Content-Type": "application/json" },
74
+ body: JSON.stringify(rating),
75
+ signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
76
+ });
77
+ }
78
+ catch {
79
+ // Offline, endpoint giù, timeout o rete negata dal permission model di Node (--permission senza --allow-net).
80
+ return { ok: false, message: "Invio non riuscito: Agentrica non è raggiungibile (rete assente, timeout o rete non permessa). Riprova più tardi." };
81
+ }
82
+ if (response.ok || response.status === 409) {
83
+ // 409: lo stesso usageId è già registrato, quindi il voto c'è.
84
+ rated.add(rating.agentId);
85
+ return { ok: true, usageId: rating.usageId };
86
+ }
87
+ if (response.status === 429)
88
+ return { ok: false, message: "Hai già valutato questo agente oggi da questa rete." };
89
+ if (response.status === 400)
90
+ return { ok: false, message: "Valutazione respinta: dati non validi." };
91
+ return { ok: false, message: `Invio non riuscito (errore ${response.status} del servizio). Riprova più tardi.` };
92
+ },
93
+ /** Agenti caricati da almeno 30 minuti, non valutati e non ancora ricordati: si ricordano una volta sola. */
94
+ due() {
95
+ const ids = [...loadedAt].filter(([id, at]) => now() - at >= REMINDER_AFTER_MS && !rated.has(id) && !reminded.has(id)).map(([id]) => id);
96
+ for (const id of ids)
97
+ reminded.add(id);
98
+ return ids;
99
+ },
100
+ };
101
+ }
102
+ /** Testo dell'anteprima: cosa parte, l'avviso e il codice. */
103
+ export function previewText(name, code, rating) {
104
+ return [
105
+ `Anteprima della valutazione di ${name}:`,
106
+ `- voto: ${rating.rating}/5`,
107
+ `- commento: ${rating.comment || "(nessuno)"}`,
108
+ `- pubblicazione del commento sul sito: ${rating.publish ? "sì" : "no"}`,
109
+ `- versione: ${rating.mcpVersion}`,
110
+ "",
111
+ NOTICE,
112
+ "",
113
+ `Mostra questa anteprima all'utente e chiedigli se inviarla. Solo dopo il suo sì richiama rate_agent con code "${code}" (valido 10 minuti, una volta). Se dice no, non fare nulla.`,
114
+ ].join("\n");
115
+ }
@@ -1,7 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  // Server MCP di Agentrica su stdio: un prompt per agente e due tool (elenca_agenti, agente).
3
3
  // Con --agents (es. --agents aisa,aiwda-08) prompt e tool vedono solo la squadra; senza, tutti gli agenti.
4
- // Legge solo i file di agents/ all'avvio; non scrive file, non apre connessioni e non registra dati.
4
+ // Legge solo i file di agents/ all'avvio; non scrive file e non registra dati (scrive solo init). L'unica connessione
5
+ // è l'invio di una valutazione (F20, ratings.ts), solo dopo la conferma dell'utente; --no-ratings toglie tool e promemoria.
5
6
  // Con --panel (F14) apre anche il pannello locale su 127.0.0.1 (panel.ts), che legge plan/, audit/ e lo stato di git
6
7
  // della cartella corrente e aggiunge i tool open_panel e ask_user; le chiamate agli agenti restano solo in memoria.
7
8
  import { realpathSync } from "node:fs";
@@ -11,7 +12,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
11
12
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
12
13
  import { z } from "zod";
13
14
  import { openBrowser, startPanel } from "./panel.js";
14
- import { agentSummary, agentText, codeName, findAgent, selectSquad, VERSION } from "./prompt.js";
15
+ import { agentSummary, agentText, codeName, findAgent, introLine, selectSquad, VERSION } from "./prompt.js";
16
+ import { createRatings, MAX_COMMENT, previewText, RATINGS_URL } from "./ratings.js";
15
17
  // Un errore all'avvio ferma il server con una riga sola su stderr, che il client mostra nei log. Il messaggio può
16
18
  // contenere argomenti della configurazione del client: i caratteri di controllo (a capo, escape) diventano \uXXXX.
17
19
  function fail(message) {
@@ -22,10 +24,17 @@ function fail(message) {
22
24
  const reason = (error) => (error instanceof Error ? error.message : String(error));
23
25
  let spec;
24
26
  let withPanel = false;
27
+ let withRatings = true;
28
+ // `init` (F18) crea un progetto e termina, senza avviare il server: è l'unico comando che scrive file (init.ts).
29
+ if (process.argv[2] === "init") {
30
+ const { runInit } = await import("./init.js");
31
+ process.exit(runInit(process.argv.slice(3)));
32
+ }
25
33
  try {
26
- const { values } = parseArgs({ options: { agents: { type: "string" }, panel: { type: "boolean" } } });
34
+ const { values } = parseArgs({ options: { agents: { type: "string" }, panel: { type: "boolean" }, "no-ratings": { type: "boolean" } } });
27
35
  spec = values.agents;
28
36
  withPanel = values.panel ?? false;
37
+ withRatings = !values["no-ratings"];
29
38
  }
30
39
  catch (error) {
31
40
  fail(reason(error));
@@ -48,10 +57,20 @@ catch (error) {
48
57
  const all = catalog.flatMap((department) => department.agents.map((agent) => ({ department, agent })));
49
58
  const count = (n, one, many) => `${n} ${n === 1 ? one : many}`;
50
59
  const codes = catalog.map((d) => d.code);
60
+ // AGENTRICA_RATINGS_URL serve solo ai test (un endpoint finto) e vale solo su 127.0.0.1: un .mcp.json di un progetto
61
+ // non può dirottare le valutazioni verso un altro server. In uso resta l'URL fisso del sito.
62
+ const testUrl = process.env.AGENTRICA_RATINGS_URL;
63
+ const ratings = withRatings
64
+ ? createRatings({ version: VERSION, url: testUrl && /^http:\/\/127\.0\.0\.1:\d+\//.test(testUrl) ? testUrl : RATINGS_URL })
65
+ : undefined;
51
66
  let panel;
52
67
  if (withPanel) {
53
68
  try {
54
- panel = await startPanel(realpathSync(process.cwd()));
69
+ const panelRatings = ratings && {
70
+ isRated: ratings.isRated,
71
+ rate: (input) => ratings.send(ratings.build(input)),
72
+ };
73
+ panel = await startPanel(realpathSync(process.cwd()), panelRatings);
55
74
  }
56
75
  catch (error) {
57
76
  fail(`pannello non avviato: ${reason(error)}`);
@@ -59,6 +78,7 @@ if (withPanel) {
59
78
  }
60
79
  /** Registra nel pannello che un agente è stato usato: id, nome in codice, ruolo e l'inizio del compito. */
61
80
  function used({ department, agent }, task) {
81
+ ratings?.loaded(agent.id);
62
82
  const line = (task ?? "").replace(/\s+/g, " ").trim();
63
83
  panel?.record({
64
84
  id: agent.id,
@@ -74,19 +94,32 @@ const server = new McpServer({ name: "agentrica", version: VERSION }, {
74
94
  `I prompt hanno il nome dell'id dell'agente, es. ${all[0].agent.id.toLowerCase()}.` +
75
95
  (panel
76
96
  ? " Il pannello locale è attivo: per le scelte che spettano all'utente usa ask_user, che mostra la domanda nella pagina; open_panel dà l'URL della pagina."
97
+ : "") +
98
+ (ratings
99
+ ? " Quando un agente ha finito il compito, proponi all'utente di valutarlo con rate_agent (una volta per agente per sessione); niente parte senza il suo sì all'anteprima."
77
100
  : ""),
78
101
  });
79
102
  const TASK = z.string().max(20_000).optional().describe("Il compito da affidare all'agente nel progetto corrente.");
80
103
  const READ_ONLY = { readOnlyHint: true, openWorldHint: false };
81
104
  // Id ammesso: una sigla di tutto il catalogo (non solo della squadra, così fuori squadra è «non trovato») e due cifre.
82
105
  const ID = new RegExp(`^(?:${full.map((d) => d.code).join("|")})-\\d{2}$`, "i");
106
+ const AGENT_ID = z.string().regex(ID, "Formato dell'id: SIGLA-NN, es. AISA-02.").describe("Id dell'agente, es. AISA-02.");
107
+ /** Promemoria (F20): agenti in uso da 30 minuti e non valutati, in coda alla risposta di un tool, una volta per agente. */
108
+ function remind(result) {
109
+ const due = ratings?.due() ?? [];
110
+ if (due.length === 0)
111
+ return result;
112
+ const names = due.map((id) => findAgent(catalog, id)).filter((f) => f !== undefined).map((f) => codeName(f.agent));
113
+ const line = `Promemoria per il modello: ${names.join(", ")} ${names.length === 1 ? "è" : "sono"} in uso da più di 30 minuti. A un punto naturale del lavoro proponi all'utente di valutarl${names.length === 1 ? "o" : "i"} con rate_agent; se rifiuta, non chiedere più.`;
114
+ return { ...result, content: [...result.content, { type: "text", text: line }] };
115
+ }
83
116
  for (const found of all) {
84
117
  const title = `${codeName(found.agent)} — ${found.agent.role}`;
85
118
  server.registerPrompt(found.agent.id.toLowerCase(), { title, description: agentSummary(found), argsSchema: { compito: TASK } }, ({ compito }) => {
86
119
  used(found, compito);
87
120
  return {
88
121
  description: title,
89
- messages: [{ role: "user", content: { type: "text", text: agentText(found, compito) } }],
122
+ messages: [{ role: "user", content: { type: "text", text: agentText(found, compito, { ratings: Boolean(ratings) }) } }],
90
123
  };
91
124
  });
92
125
  }
@@ -104,13 +137,13 @@ server.registerTool("elenca_agenti", {
104
137
  ...d.agents.map((agent) => `- ${codeName(agent)}: ${agentSummary({ department: d, agent })}`),
105
138
  "",
106
139
  ]);
107
- return { content: [{ type: "text", text: lines.join("\n") }] };
140
+ return remind({ content: [{ type: "text", text: lines.join("\n") }] });
108
141
  });
109
142
  server.registerTool("agente", {
110
143
  title: "Istruzioni di un agente",
111
144
  description: "Restituisce le istruzioni complete di un agente (regole comuni del reparto e file di ruolo), da seguire per lavorare come quell'agente.",
112
145
  inputSchema: {
113
- id: z.string().regex(ID, "Formato dell'id: SIGLA-NN, es. AISA-02.").describe("Id dell'agente, es. AISA-02."),
146
+ id: AGENT_ID,
114
147
  compito: TASK,
115
148
  },
116
149
  annotations: READ_ONLY,
@@ -123,8 +156,52 @@ server.registerTool("agente", {
123
156
  };
124
157
  }
125
158
  used(found, compito);
126
- return { content: [{ type: "text", text: agentText(found, compito) }] };
159
+ return remind({ content: [{ type: "text", text: agentText(found, compito, { ratings: Boolean(ratings) }) }] });
127
160
  });
161
+ if (ratings)
162
+ registerRatingTool(ratings);
163
+ function registerRatingTool(ratings) {
164
+ server.registerTool("rate_agent", {
165
+ title: "Valuta un agente di Agentrica",
166
+ description: "Invia ad Agentrica la valutazione di un agente (voto 1–5, commento facoltativo), in forma anonima, in due passi. " +
167
+ "1) Senza code: restituisce l'anteprima di ciò che parte e un codice. 2) Mostra l'anteprima all'utente, chiedigli se inviarla " +
168
+ "e solo dopo il suo sì richiama il tool con quel code. Non inviare mai senza il sì dell'utente; non mettere nel commento codice, " +
169
+ "file o dati del progetto, solo le parole dell'utente.",
170
+ inputSchema: {
171
+ id: AGENT_ID,
172
+ rating: z.number().int().min(1).max(5).optional().describe("Voto da 1 a 5 (primo passo)."),
173
+ comment: z.string().max(MAX_COMMENT).optional().describe("Cosa è andato bene o cosa migliorare, con le parole dell'utente (primo passo)."),
174
+ publish: z.boolean().optional().describe("true se l'utente permette di pubblicare il commento sul sito; predefinito false (primo passo)."),
175
+ code: z.string().regex(/^[0-9a-f]{8}$/).optional().describe("Il codice dell'anteprima, solo dopo il sì dell'utente (secondo passo)."),
176
+ },
177
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
178
+ }, async ({ id, rating, comment, publish, code }) => {
179
+ const found = findAgent(catalog, id);
180
+ const fail = (text) => ({ isError: true, content: [{ type: "text", text }] });
181
+ if (!found)
182
+ return fail("Agente non trovato: usa elenca_agenti per vedere gli id.");
183
+ if (ratings.isRated(found.agent.id))
184
+ return fail(`${codeName(found.agent)} è già stato valutato in questa sessione.`);
185
+ if (code) {
186
+ const result = await ratings.confirm(code, found.agent.id);
187
+ if (!result.ok)
188
+ return fail(result.message);
189
+ return {
190
+ content: [
191
+ {
192
+ type: "text",
193
+ text: `Valutazione di ${codeName(found.agent)} inviata, grazie. Codice della valutazione: ${result.usageId}. ` +
194
+ "Dillo all'utente: con questo codice può chiedere di cancellarla o di non pubblicare il commento (note legali di Agentrica).",
195
+ },
196
+ ],
197
+ };
198
+ }
199
+ if (rating === undefined)
200
+ return fail("Serve il voto da 1 a 5 per preparare l'anteprima.");
201
+ const draft = ratings.draft({ agentId: found.agent.id, rating, comment, publish });
202
+ return { content: [{ type: "text", text: previewText(introLine(found), draft.code, draft.rating) }] };
203
+ });
204
+ }
128
205
  if (panel)
129
206
  registerPanelTools(panel);
130
207
  function registerPanelTools(panel) {
@@ -138,9 +215,9 @@ function registerPanelTools(panel) {
138
215
  annotations: { readOnlyHint: true, openWorldHint: false },
139
216
  }, () => {
140
217
  openBrowser(panel.url);
141
- return {
218
+ return remind({
142
219
  content: [{ type: "text", text: `Pannello aperto nel browser. Se non si è aperto, l'utente può aprire questo URL, valido solo su questo computer: ${panel.url}` }],
143
- };
220
+ });
144
221
  });
145
222
  const option = z.object({
146
223
  label: z.string().min(1).max(80).describe("Etichetta breve dell'opzione."),
@@ -180,7 +257,7 @@ function registerPanelTools(panel) {
180
257
  try {
181
258
  const answer = await panel.ask({ question, header: header ?? "", options, multiple: multiple ?? false }, AbortSignal.any([extra.signal, AbortSignal.timeout(wait)]));
182
259
  const chosen = answer.choices.length ? `L'utente ha scelto: ${answer.choices.join("; ")}.` : "L'utente non ha scelto un'opzione.";
183
- return { content: [{ type: "text", text: answer.note ? `${chosen}\nNota dell'utente: ${answer.note}` : chosen }] };
260
+ return remind({ content: [{ type: "text", text: answer.note ? `${chosen}\nNota dell'utente: ${answer.note}` : chosen }] });
184
261
  }
185
262
  catch {
186
263
  return {
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@agentrica/mcp",
3
- "version": "0.3.3",
3
+ "version": "0.5.0",
4
4
  "mcpName": "io.github.flgisimone/agentrica",
5
- "description": "I 56 agenti IA di Agentrica come server MCP locale (stdio): un prompt per agente e due tool in sola lettura.",
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",
7
7
  "author": "Giulio Simone Floresta",
8
8
  "repository": {
@@ -25,13 +25,15 @@
25
25
  "files": [
26
26
  "dist",
27
27
  "agents",
28
+ "starter",
29
+ ".claude/agents",
28
30
  "README.en.md"
29
31
  ],
30
32
  "engines": {
31
33
  "node": ">=22"
32
34
  },
33
35
  "scripts": {
34
- "prepack": "rm -rf dist agents LICENSE && tsc -p tsconfig.build.json && cp -R src/page dist/mcp/src/page && cp -R ../../agents agents && cp ../../LICENSE LICENSE"
36
+ "prepack": "rm -rf dist agents starter .claude LICENSE && tsc -p tsconfig.build.json && cp -R src/page dist/mcp/src/page && cp -R ../../agents agents && cp -R ../../starter starter && mkdir .claude && cp -R ../../.claude/agents .claude/agents && cp ../../LICENSE LICENSE"
35
37
  },
36
38
  "dependencies": {
37
39
  "@modelcontextprotocol/sdk": "1.32.2",
@@ -0,0 +1,65 @@
1
+ # Controlli di ogni push e pull request: npm run verify e npm run verify:e2e (CONVENTIONS §13.5).
2
+ # Nessun deploy da qui. I passi senza il loro file o script si saltano, così la CI regge anche prima di F0.
3
+ # ponytail: con un repository privato e GitHub gratuito il merge non si blocca da solo; va verde prima di unire in main.
4
+ name: CI
5
+
6
+ on:
7
+ push:
8
+ branches: [main, develop, "fase/**", "fix/**"]
9
+ pull_request:
10
+ workflow_dispatch:
11
+
12
+ concurrency:
13
+ group: ci-${{ github.ref }}
14
+ cancel-in-progress: true
15
+
16
+ permissions:
17
+ contents: read
18
+
19
+ env:
20
+ TZ: Europe/Rome
21
+
22
+ jobs:
23
+ verify:
24
+ runs-on: ubuntu-latest
25
+ timeout-minutes: 30
26
+ steps:
27
+ # Action fissate per SHA: un tag si può spostare, uno SHA no.
28
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
29
+
30
+ - name: Script disponibili
31
+ id: scripts
32
+ run: |
33
+ if [ -f package.json ]; then
34
+ echo "verify=$(node -p "Boolean(require('./package.json').scripts?.verify)")" >> "$GITHUB_OUTPUT"
35
+ echo "e2e=$(node -p "Boolean(require('./package.json').scripts?.['verify:e2e'])")" >> "$GITHUB_OUTPUT"
36
+ fi
37
+
38
+ - if: hashFiles('package-lock.json') != ''
39
+ uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
40
+ with:
41
+ node-version-file: .nvmrc
42
+ cache: npm
43
+
44
+ - if: hashFiles('package-lock.json') != ''
45
+ run: npm ci
46
+
47
+ - name: Dipendenze di produzione senza vulnerabilità alte
48
+ if: hashFiles('package-lock.json') != ''
49
+ run: npm audit --omit=dev --audit-level=high
50
+
51
+ - if: steps.scripts.outputs.verify == 'true'
52
+ run: npm run verify
53
+
54
+ - if: steps.scripts.outputs.e2e == 'true'
55
+ run: npx playwright install --with-deps chromium
56
+
57
+ - if: steps.scripts.outputs.e2e == 'true'
58
+ run: npm run verify:e2e
59
+
60
+ - if: failure() && steps.scripts.outputs.e2e == 'true'
61
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
62
+ with:
63
+ name: playwright-report
64
+ path: test-results/
65
+ retention-days: 3
package/starter/.nvmrc ADDED
@@ -0,0 +1 @@
1
+ 26