@agentrica/mcp 0.1.0 → 0.2.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.en.md CHANGED
@@ -24,7 +24,7 @@ You need Node 22 or later, with npm.
24
24
  **Claude Code**, from your project folder:
25
25
 
26
26
  ```sh
27
- claude mcp add agentrica -- npx -y @agentrica/mcp@0.1.0
27
+ claude mcp add agentrica -- npx -y @agentrica/mcp@0.2.0
28
28
  ```
29
29
 
30
30
  On first start npx downloads the package from npm. The version stays the one you set until you change it: role updates do not arrive unless you choose them.
@@ -36,7 +36,7 @@ On first start npx downloads the package from npm. The version stays the one you
36
36
  "mcpServers": {
37
37
  "agentrica": {
38
38
  "command": "npx",
39
- "args": ["-y", "@agentrica/mcp@0.1.0"]
39
+ "args": ["-y", "@agentrica/mcp@0.2.0"]
40
40
  }
41
41
  }
42
42
  }
@@ -45,7 +45,7 @@ On first start npx downloads the package from npm. The version stays the one you
45
45
  **Least privilege (recommended).** Install the package in its own folder and start it with Node's permission model: the server can only read that folder, and Node blocks file writes, network connections and child processes. The server needs none of them, so it works the same; the permissions limit the damage of any future defect.
46
46
 
47
47
  ```sh
48
- npm install -g --ignore-scripts @agentrica/mcp@0.1.0
48
+ npm install -g --ignore-scripts @agentrica/mcp@0.2.0
49
49
  npm root -g
50
50
  ```
51
51
 
@@ -69,6 +69,14 @@ claude mcp add agentrica -- node --permission --allow-fs-read=/global/folder/@ag
69
69
 
70
70
  Put the task in quotes: Claude Code splits arguments on spaces.
71
71
 
72
+ **Squad.** With `--agents` the server loads only the agents you list: agent ids and department codes, comma-separated, case-insensitive. For example the whole software department plus the accessibility agent:
73
+
74
+ ```sh
75
+ claude mcp add agentrica -- npx -y @agentrica/mcp@0.2.0 --agents aisa,aiwda-08
76
+ ```
77
+
78
+ The command menu shows only the squad's prompts, and `elenca_agenti` and `agente` see only those agents too. Without `--agents` all 56 agents are available. An unknown id or code stops the server with a message naming it, in the client's logs. In Claude Code prompts do not enter the model's context (we checked with `/context`): a squad makes the menu shorter, it does not save tokens.
79
+
72
80
  **Tools**, for clients that do not show prompts, or when you want the model to pick the agent:
73
81
 
74
82
  | Tool | Input | Returns |
@@ -86,6 +94,7 @@ The agents' text comes from the `agents/` files of the installed version. To upd
86
94
 
87
95
  ## Versions
88
96
 
97
+ - **0.2.0**: `--agents` argument to load only a squad of agents or departments; in an empty project, or when what the role must examine is missing, the agent says so and proposes first steps to confirm, without inventing findings.
89
98
  - **0.1.0**: first published version. 56 agents in five departments, one prompt per agent and the `elenca_agenti` and `agente` tools.
90
99
 
91
100
  ## License
package/README.md CHANGED
@@ -22,7 +22,7 @@ Serve Node 22 o successivo, con npm.
22
22
  **Claude Code**, dalla cartella del tuo progetto:
23
23
 
24
24
  ```sh
25
- claude mcp add agentrica -- npx -y @agentrica/mcp@0.1.0
25
+ claude mcp add agentrica -- npx -y @agentrica/mcp@0.2.0
26
26
  ```
27
27
 
28
28
  Al primo avvio npx scarica il pacchetto da npm. La versione resta quella indicata finché non la cambi tu: un aggiornamento dei ruoli non arriva senza che tu lo scelga.
@@ -34,7 +34,7 @@ Al primo avvio npx scarica il pacchetto da npm. La versione resta quella indicat
34
34
  "mcpServers": {
35
35
  "agentrica": {
36
36
  "command": "npx",
37
- "args": ["-y", "@agentrica/mcp@0.1.0"]
37
+ "args": ["-y", "@agentrica/mcp@0.2.0"]
38
38
  }
39
39
  }
40
40
  }
@@ -43,7 +43,7 @@ Al primo avvio npx scarica il pacchetto da npm. La versione resta quella indicat
43
43
  **Permessi minimi (consigliato).** Installa il pacchetto in una cartella sua e avvialo con il permission model di Node: il server può solo leggere quella cartella, e Node blocca scritture su file, connessioni di rete e processi figli. Il server non ne ha bisogno, quindi funziona uguale; i permessi limitano i danni di un eventuale difetto futuro.
44
44
 
45
45
  ```sh
46
- npm install -g --ignore-scripts @agentrica/mcp@0.1.0
46
+ npm install -g --ignore-scripts @agentrica/mcp@0.2.0
47
47
  npm root -g
48
48
  ```
49
49
 
@@ -67,6 +67,14 @@ claude mcp add agentrica -- node --permission --allow-fs-read=/cartella/globale/
67
67
 
68
68
  Metti il compito fra virgolette: Claude Code separa gli argomenti con gli spazi.
69
69
 
70
+ **Squadra.** Con `--agents` il server carica solo gli agenti che indichi: id di agenti e sigle di reparti, separati da virgole, senza distinguere maiuscole. Per esempio tutto il reparto software più l'agente dell'accessibilità:
71
+
72
+ ```sh
73
+ claude mcp add agentrica -- npx -y @agentrica/mcp@0.2.0 --agents aisa,aiwda-08
74
+ ```
75
+
76
+ Nel menu dei comandi restano solo i prompt della squadra, e anche `elenca_agenti` e `agente` vedono solo quelli. Senza `--agents` ci sono tutti i 56 agenti. Un id o una sigla sconosciuti fermano il server con un messaggio che li nomina, nei log del client. In Claude Code i prompt non entrano nel contesto del modello (lo abbiamo verificato con `/context`): la squadra rende il menu più corto, ma non fa risparmiare token.
77
+
70
78
  **Tool**, per i client che non mostrano i prompt, o quando vuoi che sia il modello a scegliere l'agente:
71
79
 
72
80
  | Tool | Input | Cosa restituisce |
@@ -86,6 +94,7 @@ Il testo degli agenti viene dai file di `agents/` della versione installata. Per
86
94
 
87
95
  ## Versioni
88
96
 
97
+ - **0.2.0**: argomento `--agents` per caricare solo una squadra di agenti o reparti; con un progetto vuoto, o senza ciò che il ruolo deve esaminare, l'agente lo dice e propone i primi passi da confermare, senza inventare rilievi.
89
98
  - **0.1.0**: prima versione pubblicata. 56 agenti in cinque reparti, un prompt per agente e i tool `elenca_agenti` e `agente`.
90
99
 
91
100
  ## Licenza
@@ -9,8 +9,8 @@ const COLLABORATION = "Collaborazione con le altre agenzie";
9
9
  const ROLE_FILE = /^(\d{2})-([a-z0-9-]+)\.md$/;
10
10
  /**
11
11
  * Cerca la cartella agents/ risalendo da `from`.
12
- * ponytail: funziona dentro il repository (sito, test, sviluppo); il pacchetto MCP pubblicato (F5) dovrà
13
- * portarsi dietro i file e passare la cartella a loadCatalog.
12
+ * Serve dentro il repository (sito, test, sviluppo). Il server MCP non la usa: passa a loadCatalog una cartella
13
+ * fissa, perché la cartella corrente è il progetto dell'utente (packages/mcp/src/server.ts).
14
14
  */
15
15
  export function findAgentsDir(from = process.cwd()) {
16
16
  // turbopackIgnore: il sito legge il catalogo solo al build (pagine pre-generate), quindi Next non deve tracciare
@@ -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.1.0";
2
+ export const VERSION = "0.2.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();
@@ -19,11 +19,43 @@ export function agentSummary({ department, agent }) {
19
19
  const position = agent.number === 1 ? "direttore" : "specialista";
20
20
  return `${agent.role}, ${position} del reparto ${department.code} (${department.name}).`;
21
21
  }
22
+ /**
23
+ * La squadra di --agents: id di agenti e sigle di reparti separati da virgole, senza distinguere maiuscole
24
+ * («aisa,aiwda-08»). Restituisce il catalogo ridotto alla squadra, nell'ordine del catalogo e senza doppioni;
25
+ * senza elenco, tutto il catalogo. Un nome sconosciuto o un elenco vuoto è un errore che lo nomina.
26
+ */
27
+ export function selectSquad(catalog, spec) {
28
+ if (spec === undefined)
29
+ return [...catalog];
30
+ const names = spec.split(",").map((name) => name.trim()).filter((name) => name !== "");
31
+ if (names.length === 0)
32
+ throw new Error("--agents è vuoto: indica id di agenti o sigle di reparti, es. --agents aisa,aiwda-08");
33
+ const wanted = new Set();
34
+ const unknown = [];
35
+ for (const name of names) {
36
+ const department = catalog.find((d) => d.code === name.toUpperCase());
37
+ const found = department ? undefined : findAgent(catalog, name);
38
+ if (department)
39
+ for (const agent of department.agents)
40
+ wanted.add(agent.id);
41
+ else if (found)
42
+ wanted.add(found.agent.id);
43
+ else
44
+ unknown.push(name);
45
+ }
46
+ // Fra virgolette (JSON.stringify), così nei log del client si vedono anche spazi e caratteri strani.
47
+ if (unknown.length > 0)
48
+ throw new Error(`agente o reparto sconosciuto in --agents: ${unknown.map((n) => JSON.stringify(n)).join(", ")}`);
49
+ return catalog
50
+ .map((d) => ({ ...d, agents: d.agents.filter((a) => wanted.has(a.id)) }))
51
+ .filter((d) => d.agents.length > 0);
52
+ }
22
53
  export function agentText({ department, agent }, task) {
23
54
  const parts = [
24
55
  `# ${codeName(agent)} — ${agent.role}`,
25
56
  `Sei ${codeName(agent)}, un agente IA di Agentrica: ${agentSummary({ department, agent })} ` +
26
57
  "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
+ "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. " +
27
59
  "Questi testi sono in italiano: rispondi nella lingua in cui ti scrive l'utente.",
28
60
  "## Regole comuni del reparto",
29
61
  ...block(department.rules.intro, department.rules.sections),
@@ -1,33 +1,57 @@
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
+ // Con --agents (es. --agents aisa,aiwda-08) prompt e tool vedono solo la squadra; senza, tutti gli agenti.
3
4
  // Legge solo i file di agents/ all'avvio; non scrive file, non apre connessioni e non registra dati.
4
5
  import { join } from "node:path";
5
- import { DEPARTMENTS, loadCatalog } from "../../catalog/src/index.js";
6
+ import { parseArgs } from "node:util";
7
+ import { loadCatalog } from "../../catalog/src/index.js";
6
8
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
7
9
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
8
10
  import { z } from "zod";
9
- import { agentSummary, agentText, codeName, findAgent, VERSION } from "./prompt.js";
11
+ import { agentSummary, agentText, codeName, findAgent, selectSquad, VERSION } from "./prompt.js";
10
12
  // agents/ è in un punto fisso rispetto a questo file, senza risalire le cartelle: la cartella corrente è il progetto
11
13
  // dell'utente e non deve poter fornire un'altra agents/. Tre livelli sopra c'è agents/ sia da un clone
12
14
  // (packages/mcp/src → la root del repository) sia nel pacchetto (dist/mcp/src → la root del pacchetto, dove prepack
13
15
  // copia agents/). Il catalogo è importato per percorso relativo, così tsc lo compila dentro dist e il pacchetto non
14
16
  // dipende da @agentrica/catalog.
15
17
  const AGENTS_DIR = join(import.meta.dirname, "..", "..", "..", "agents");
18
+ // Un errore all'avvio ferma il server con una riga sola su stderr, che il client mostra nei log. Il messaggio può
19
+ // contenere argomenti della configurazione del client: i caratteri di controllo (a capo, escape) diventano \uXXXX.
20
+ function fail(message) {
21
+ const safe = message.replace(/\p{Cc}/gu, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
22
+ process.stderr.write(`agentrica: ${safe}\n`);
23
+ process.exit(1);
24
+ }
25
+ const reason = (error) => (error instanceof Error ? error.message : String(error));
26
+ let spec;
27
+ try {
28
+ spec = parseArgs({ options: { agents: { type: "string" } } }).values.agents;
29
+ }
30
+ catch (error) {
31
+ fail(reason(error));
32
+ }
33
+ let full;
34
+ try {
35
+ full = loadCatalog(AGENTS_DIR);
36
+ }
37
+ catch (error) {
38
+ // Senza catalogo completo il server non parte: niente contenuti parziali.
39
+ fail(`catalogo non leggibile in ${AGENTS_DIR}: ${reason(error)}`);
40
+ }
16
41
  let catalog;
17
42
  try {
18
- catalog = loadCatalog(AGENTS_DIR);
43
+ catalog = selectSquad(full, spec);
19
44
  }
20
45
  catch (error) {
21
- // Senza catalogo completo il server non parte: niente contenuti parziali. Una riga sola, il client la mostra nei log.
22
- process.stderr.write(`agentrica: catalogo non leggibile in ${AGENTS_DIR}: ${error instanceof Error ? error.message : String(error)}\n`);
23
- process.exit(1);
46
+ fail(reason(error));
24
47
  }
25
48
  const all = catalog.flatMap((department) => department.agents.map((agent) => ({ department, agent })));
26
- const codes = DEPARTMENTS.map((d) => d.code);
49
+ const count = (n, one, many) => `${n} ${n === 1 ? one : many}`;
50
+ const codes = catalog.map((d) => d.code);
27
51
  const server = new McpServer({ name: "agentrica", version: VERSION }, {
28
- instructions: `Agentrica: ${all.length} agenti IA specializzati in ${catalog.length} reparti (${codes.join(", ")}). ` +
52
+ instructions: `Agentrica: ${count(all.length, "agente IA", "agenti IA")} in ${count(catalog.length, "reparto", "reparti")} (${codes.join(", ")}). ` +
29
53
  "Per scegliere un agente usa elenca_agenti; per lavorare come quell'agente carica le sue istruzioni con agente. " +
30
- "I prompt hanno il nome dell'id dell'agente, es. aisa-02.",
54
+ `I prompt hanno il nome dell'id dell'agente, es. ${all[0].agent.id.toLowerCase()}.`,
31
55
  });
32
56
  const TASK = z.string().max(20_000).optional().describe("Il compito da affidare all'agente nel progetto corrente.");
33
57
  const READ_ONLY = { readOnlyHint: true, openWorldHint: false };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agentrica/mcp",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "I 56 agenti IA di Agentrica come server MCP locale (stdio): un prompt per agente e due tool in sola lettura.",
5
5
  "license": "MIT",
6
6
  "author": "Giulio Simone Floresta",