@agentrica/mcp 0.1.0 → 0.2.1
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 +25 -3
- package/README.md +25 -3
- package/dist/catalog/src/index.js +2 -2
- package/dist/mcp/src/prompt.js +33 -1
- package/dist/mcp/src/server.js +33 -9
- package/package.json +2 -1
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
|
|
27
|
+
claude mcp add agentrica -- npx -y @agentrica/mcp@0.2.1
|
|
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
|
|
39
|
+
"args": ["-y", "@agentrica/mcp@0.2.1"]
|
|
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
|
|
48
|
+
npm install -g --ignore-scripts @agentrica/mcp@0.2.1
|
|
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.1 --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 |
|
|
@@ -80,12 +88,26 @@ For example: "Use elenca_agenti, pick the right Agentrica agent and check the ac
|
|
|
80
88
|
|
|
81
89
|
Number 01 in each department is the director: it coordinates the specialists and consolidates their findings.
|
|
82
90
|
|
|
91
|
+
## Put to the test
|
|
92
|
+
|
|
93
|
+
Three agents tested on 2026-11-15 against three small projects with planted, documented defects, using `@agentrica/mcp@0.2.0 --agents <id>`, Claude Code for VS Code and Opus 5.5 (medium reasoning). One run per case, counted by hand.
|
|
94
|
+
|
|
95
|
+
| Agent | Project | Defects found | False findings | Other valid findings |
|
|
96
|
+
|---|---|---|---|---|
|
|
97
|
+
| AISA-09 · REGULUS, Application Security | Node REST API | 6 of 6 | 0 | 2 |
|
|
98
|
+
| AIWDA-08 · GACRUX, Accessibility | sign-up form | 8 of 8 | 0 | 2 |
|
|
99
|
+
| AIPCA-02 · ALIOTH, GDPR | gym booking service | 7 of 7 | 0 | 3 |
|
|
100
|
+
|
|
101
|
+
Limits: the defects are few, known and fairly obvious; one model and one run per case; a result like this says nothing about how an agent does on a large project. Projects, expected defects, counting rules and the agents' full reports (in Italian) are in [`examples/`](https://github.com/flgisimone/agentrica/tree/main/examples): you can repeat the tests.
|
|
102
|
+
|
|
83
103
|
## Updates
|
|
84
104
|
|
|
85
105
|
The agents' text comes from the `agents/` files of the installed version. To update, change the version in the command (or reinstall with `npm install -g`) and restart the client. Ids and code names do not change.
|
|
86
106
|
|
|
87
107
|
## Versions
|
|
88
108
|
|
|
109
|
+
- **0.2.1**: name `io.github.flgisimone/agentrica` for the official MCP registry; agents and behaviour unchanged.
|
|
110
|
+
- **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
111
|
- **0.1.0**: first published version. 56 agents in five departments, one prompt per agent and the `elenca_agenti` and `agente` tools.
|
|
90
112
|
|
|
91
113
|
## 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
|
|
25
|
+
claude mcp add agentrica -- npx -y @agentrica/mcp@0.2.1
|
|
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
|
|
37
|
+
"args": ["-y", "@agentrica/mcp@0.2.1"]
|
|
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
|
|
46
|
+
npm install -g --ignore-scripts @agentrica/mcp@0.2.1
|
|
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.1 --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 |
|
|
@@ -80,12 +88,26 @@ Il numero 01 di ogni reparto è il direttore: coordina gli specialisti e consoli
|
|
|
80
88
|
|
|
81
89
|
I file degli agenti sono in italiano; l'agente risponde nella lingua in cui gli scrivi.
|
|
82
90
|
|
|
91
|
+
## Messi alla prova
|
|
92
|
+
|
|
93
|
+
Tre agenti provati il 2026-11-15 su tre piccoli progetti con difetti piantati e documentati, con `@agentrica/mcp@0.2.0 --agents <id>`, Claude Code per VS Code e Opus 5.5 (ragionamento medio). Un'esecuzione per caso, contata a mano.
|
|
94
|
+
|
|
95
|
+
| Agente | Progetto | Difetti trovati | Rilievi falsi | Altri rilievi validi |
|
|
96
|
+
|---|---|---|---|---|
|
|
97
|
+
| AISA-09 · REGULUS, Application Security | API REST in Node | 6 su 6 | 0 | 2 |
|
|
98
|
+
| AIWDA-08 · GACRUX, Accessibility | form di iscrizione | 8 su 8 | 0 | 2 |
|
|
99
|
+
| AIPCA-02 · ALIOTH, GDPR | prenotazioni di una palestra | 7 su 7 | 0 | 3 |
|
|
100
|
+
|
|
101
|
+
Limiti: i difetti sono pochi, noti e abbastanza evidenti; un solo modello e una sola esecuzione per caso; un risultato del genere non dice come va un agente su un progetto grande. Progetti, difetti attesi, regole di conteggio e rapporti completi degli agenti sono in [`examples/`](https://github.com/flgisimone/agentrica/tree/main/examples): puoi ripetere le prove.
|
|
102
|
+
|
|
83
103
|
## Aggiornamenti
|
|
84
104
|
|
|
85
105
|
Il testo degli agenti viene dai file di `agents/` della versione installata. Per aggiornare cambia la versione nel comando (o reinstalla con `npm install -g`) e riavvia il client. Gli id e i nomi in codice non cambiano.
|
|
86
106
|
|
|
87
107
|
## Versioni
|
|
88
108
|
|
|
109
|
+
- **0.2.1**: nome `io.github.flgisimone/agentrica` per il registro MCP ufficiale; agenti e comportamento invariati.
|
|
110
|
+
- **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
111
|
- **0.1.0**: prima versione pubblicata. 56 agenti in cinque reparti, un prompt per agente e i tool `elenca_agenti` e `agente`.
|
|
90
112
|
|
|
91
113
|
## 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
|
-
*
|
|
13
|
-
*
|
|
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
|
package/dist/mcp/src/prompt.js
CHANGED
|
@@ -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
|
|
2
|
+
export const VERSION = "0.2.1";
|
|
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),
|
package/dist/mcp/src/server.js
CHANGED
|
@@ -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 {
|
|
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 =
|
|
43
|
+
catalog = selectSquad(full, spec);
|
|
19
44
|
}
|
|
20
45
|
catch (error) {
|
|
21
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@agentrica/mcp",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "0.2.1",
|
|
4
|
+
"mcpName": "io.github.flgisimone/agentrica",
|
|
4
5
|
"description": "I 56 agenti IA di Agentrica come server MCP locale (stdio): un prompt per agente e due tool in sola lettura.",
|
|
5
6
|
"license": "MIT",
|
|
6
7
|
"author": "Giulio Simone Floresta",
|