14 - Tech-MCP: Panoramica Completa del Progetto Open Source

Introduzione: Il Viaggio Completo

Questo e l'ultimo articolo della serie dedicata al Model Context Protocol (MCP). In 14 articoli abbiamo percorso un cammino completo: dai fondamenti teorici del protocollo fino all'implementazione di un ecosistema production-ready con 31 server MCP, 85+ tool, 6 pacchetti condivisi e un sistema di testing professionale.

In questo articolo presentiamo una panoramica completa del progetto open source Tech-MCP: il catalogo di tutti i server organizzati per categoria, lo stack tecnologico, l'architettura complessiva, le lezioni apprese durante lo sviluppo e come contribuire al progetto.

Tech-MCP in Numeri

Il progetto Tech-MCP e il risultato di un processo di progettazione e sviluppo che ha prodotto un ecosistema MCP completo, coprendo l'intero ciclo di vita dello sviluppo software. Ecco i numeri chiave:

Architettura Complessiva

Tech-MCP e organizzato come un monorepo gestito con pnpm workspaces e Turborepo. I pacchetti condivisi forniscono funzionalità trasversali, mentre i 31 server implementano la logica di dominio specifica:

Tech-MCP/
├── packages/                    # 6 Pacchetti Condivisi
│   ├── core/                    # Factory, tipi condivisi, startHttpServer()
│   ├── event-bus/               # EventBus interface + LocalEventBus + 29 eventi
│   ├── client-manager/          # McpClientManager per cross-server
│   ├── database/                # BaseStore SQLite, migrazioni
│   ├── testing/                 # TestHarness, MockEventBus, InMemoryTransport
│   └── cli/                     # Utility CLI per gestione server
│
├── servers/                     # 31 Server MCP
│   ├── scrum-board/             # Project Management
│   ├── agile-metrics/           # Project Management
│   ├── time-tracking/           # Project Management
│   ├── project-economics/       # Project Management
│   ├── retrospective-manager/   # Project Management
│   ├── code-review/             # Produttività
│   ├── dependency-manager/      # Produttività
│   ├── project-scaffolding/     # Produttività
│   ├── docker-compose/          # DevOps
│   ├── log-analyzer/            # DevOps
│   ├── cicd-monitor/            # DevOps
│   ├── db-schema-explorer/      # Database
│   ├── data-mock-generator/     # Database
│   ├── test-generator/          # Testing
│   ├── performance-profiler/    # Testing
│   ├── api-documentation/       # Documentazione
│   ├── codebase-knowledge/      # Documentazione
│   ├── regex-builder/           # Utility
│   ├── http-client/             # Utility
│   ├── snippet-manager/         # Utility
│   ├── standup-notes/           # Comunicazione
│   ├── environment-manager/     # Comunicazione
│   ├── incident-manager/        # Avanzati
│   ├── decision-log/            # Avanzati
│   ├── access-policy/           # Avanzati
│   ├── quality-gate/            # Avanzati
│   ├── workflow-orchestrator/   # Avanzati
│   ├── insight-engine/          # Avanzati
│   ├── mcp-registry/            # Avanzati
│   ├── dashboard-api/           # Avanzati
│   └── tech-radar/              # Avanzati
│
├── docs/                        # Documentazione completa
├── turbo.json                   # Configurazione Turborepo
├── pnpm-workspace.yaml          # Workspace definition
└── package.json                 # Root package
    

Catalogo Completo dei Server

I 31 server MCP sono organizzati in 9 categorie funzionali che coprono ogni aspetto del ciclo di vita dello sviluppo software. Ogni server e indipendente ma può collaborare con gli altri tramite EventBus e ClientManager.

Project Management (5 server)

Produttività (3 server)

DevOps (3 server)

Database (2 server)

Testing (2 server)

Documentazione (2 server)

Utility (3 server)

Comunicazione (2 server)

Avanzati (9 server)

Stack Tecnologico

Lo stack tecnologico di Tech-MCP e stato scelto per massimizzare la type-safety, la velocità di sviluppo e la manutenibilità a lungo termine:

I 6 Pacchetti Condivisi

I pacchetti condivisi forniscono le fondamenta su cui tutti i 31 server sono costruiti. Ogni pacchetto e pubblicato internamente nel monorepo e consumato dai server tramite workspace:*:

Pattern Architetturali Chiave

Durante lo sviluppo di 31 server MCP sono emersi pattern architetturali ricorrenti che garantiscono coerenza, testabilità e manutenibilità:

1. Server Factory Pattern

Ogni server espone una factory function con parametri opzionali per massima flessibilità:

export function createMyServer(options?: {
  eventBus?: EventBus;
  clientManager?: McpClientManager;
  storeOptions?: { inMemory?: boolean; dbPath?: string };
}) {
  const server = new McpServer({
    name: "my-server",
    version: "1.0.0",
  });

  const store = new MyStore(options?.storeOptions);

  // Registra i tool con dipendenze opzionali
  registerAddItem(server, store, options?.eventBus);
  registerGetStats(server, store, options?.clientManager);

  // Collaboration: attivata solo se c'è un event bus
  if (options?.eventBus) {
    setupCollaborationHandlers(options.eventBus, store);
  }

  return { server, store };
}
    

2. Un File per Tool

Ogni tool e isolato nel proprio file, registrato come funzione pura che riceve le dipendenze:

// tools/add-item.ts
export function registerAddItem(
  server: McpServer,
  store: MyStore,
  eventBus?: EventBus,
): void {
  server.tool(
    "add-item",
    "Add a new item to the store",
    { title: z.string(), content: z.string() },
    async ({ title, content }) => {
      try {
        const item = store.addItem({ title, content });
        eventBus?.publish("items:created", { id: item.id, title });
        return {
          content: [{ type: "text", text: JSON.stringify(item, null, 2) }],
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: `Error: ${error instanceof Error ? error.message : String(error)}`,
          }],
          isError: true,
        };
      }
    },
  );
}
    

3. Collaboration Fire-and-Forget

Gli eventi sono pubblicati con il pattern fire-and-forget: il server pubblica l'evento e prosegue senza attendere risposta. Questo disaccoppia completamente i server:

// Il server pubblica senza attendere
eventBus?.publish("scrum:sprint-started", {
  sprintId: sprint.id,
  name: sprint.name,
});

// Un altro server reagisce nel proprio collaboration.ts
eventBus.subscribe("scrum:sprint-started", (payload) => {
  store.autoCreateBudget(payload.sprintId, payload.name);
});
    

Come Contribuire

Tech-MCP e un progetto open source e i contributi sono benvenuti. Il processo di contribuzione segue un workflow standard:

Prerequisiti

• Node.js >= 20.0.0
• pnpm >= 9.0.0
• Conoscenza base di TypeScript e del Model Context Protocol

Setup dell'Ambiente di Sviluppo

# 1. Fork e clone del repository
git clone https://github.com/<tuo-utente>/Tech-MCP.git
cd Tech-MCP

# 2. Installa le dipendenze
pnpm install

# 3. Build completo di tutti i pacchetti e server
pnpm build

# 4. Verifica che tutto compili correttamente
pnpm typecheck
    

Tipi di Contributo

1. Aggiungere un nuovo server MCP: crea un nuovo server nella directory servers/ seguendo la struttura standardizzata (package.json, tsconfig.json, src/index.ts, src/server.ts, src/tools/, src/services/)
2. Aggiungere un tool a un server esistente: crea il file in servers/<nome>/src/tools/ seguendo il pattern di registrazione con dipendenze opzionali
3. Aggiungere un evento: definisci l'evento in packages/event-bus/src/events.ts, pubblica nel tool appropriato e sottoscrivi nel collaboration handler
4. Implementare collaboration handler: molti collaboration.ts contengono handler placeholder con void payload. Implementare la logica reale e un contributo prezioso
5. Scrivere test: unit test dello store, integration test dei tool, wiring test cross-server

Convenzioni del Codice

Processo di Review

1. Fork il repository su GitHub
2. Crea un branch dalla main
3. Implementa seguendo le convenzioni del progetto
4. Build e typecheck: pnpm build && pnpm typecheck
5. Committa con messaggi chiari e descrittivi
6. Apri una Pull Request verso main
7. Rispondi al feedback della review

Aree dove Serve Aiuto

Il progetto ha diverse aree dove i contributi sono particolarmente benvenuti:

Roadmap e Sviluppi Futuri

Tech-MCP e un progetto in evoluzione. Le aree di sviluppo pianificate sono organizzate per priorità:

Priorità 1: Redis EventBus

Attualmente l'EventBus funziona solo con LocalEventBus (in-process). Per deployment reali dove ogni server e un processo separato, serve un broker di messaggi esterno. L'implementazione con Redis permettera la comunicazione inter-processo tra server MCP distribuiti su macchine diverse.

Priorità 2: Resources e Prompts MCP

Attualmente Tech-MCP utilizza esclusivamente la primitiva Tools. Le specifiche MCP definiscono anche Resources (dati read-only con URI) e Prompts (template per workflow strutturati). Aggiungere queste primitive arricchirebbe significativamente le capacità dei server.

Priorità 3: Dashboard Web

Una web dashboard per visualizzare in tempo reale lo stato di tutti i server, gli eventi pubblicati, le metriche di utilizzo dei tool e gli health check.

Priorità 4: Plugin System

Un'architettura per plugin third-party con registry, hot-reload di tool e un marketplace condiviso.

Lezioni Apprese

Costruire 31 server MCP in un monorepo ha insegnato lezioni preziose che si applicano a qualsiasi progetto software di media-grande scala:

1. La Standardizzazione Paga

Avere una struttura standardizzata per ogni server (factory function, un file per tool, store isolato, collaboration handler separato) ha ridotto drasticamente il tempo di sviluppo di nuovi server. Dopo i primi 5 server, creare un nuovo server richiedeva pochissimo tempo perchè il pattern era consolidato.

2. I Pacchetti Condivisi Sono Fondamentali

Estrarre la logica comune in pacchetti condivisi (core, event-bus, database, testing) ha eliminato la duplicazione del codice e garantito coerenza tra tutti i server. Ogni modifica a un pacchetto condiviso si propaga automaticamente a tutti i server che lo utilizzano.

3. Le Descrizioni dei Tool Sono Critiche

L'AI sceglie quale tool chiamare basandosi esclusivamente sulla descrizione. Descrizioni vaghe producono tool sottoutilizzati, descrizioni precise producono un'esperienza fluida. Investire tempo nella stesura delle descrizioni e un investimento ad alto rendimento.

4. Fire-and-Forget Semplifica Tutto

Il pattern fire-and-forget per gli eventi ha semplificato enormemente l'architettura. I server pubblicano eventi senza sapere chi li riceve, e i collaboration handler reagiscono senza accoppiamento diretto. Questo ha reso possibile aggiungere nuove collaborazioni senza modificare i server esistenti.

5. Test In-Memory Sono la Chiave

La possibilità di istanziare ogni server con un database in-memory ha reso i test veloci, isolati e riproducibili. L'investimento in createTestHarness() e MockEventBus ha ripagato enormemente nella velocità di sviluppo.

Riepilogo della Serie

Questa serie di 14 articoli ha coperto l'intero percorso dal protocollo MCP alla produzione. Ecco un riepilogo degli argomenti trattati:

Conclusioni

Il Model Context Protocol rappresenta un cambio di paradigma nell'interazione tra sviluppatori e intelligenza artificiale. Non si tratta semplicemente di un wrapper attorno a chiamate API, ma di un protocollo strutturato che abilita discovery automatico, tipizzazione forte, comunicazione bidirezionale, composabilità nativa e collaborazione inter-server.

Con Tech-MCP abbiamo dimostrato che e possibile costruire un ecosistema completo di 31 server MCP, coprendo l'intero ciclo di vita dello sviluppo software: dalla gestione del codice al project management, dal testing al deploy, dal monitoraggio all'analisi cross-project.

Il progetto e open source e in continua evoluzione. Ogni contributo, che sia un nuovo server, un test, un fix o una nuova feature, e benvenuto. Il futuro dell'interazione uomo-AI passa attraverso protocolli aperti e composabili come MCP, e Tech-MCP vuole essere un punto di riferimento per chiunque voglia esplorare questo territorio.

Grazie per aver seguito questa serie. Il codice completo, la documentazione e le istruzioni per contribuire sono disponibili su GitHub.