MCP

Integrazione del Model Context Protocol per collegare gli agent a strumenti e servizi esterni

Integrazione del Model Context Protocol per collegare gli agent a strumenti e servizi esterni

Panoramica

MCP (Model Context Protocol) permette agli agent di Astreus di connettersi in modo fluido a strumenti e servizi esterni. Definisci i server MCP come semplici oggetti con caricamento automatico delle variabili d'ambiente e usali a diversi livelli: agent, task o conversazione.

Definizioni di tipo

MCPServerDefinition

interface MCPServerDefinition {
  name: string;           // Server name for identification (required)
  command?: string;       // Command to execute (for stdio servers)
  args?: string[];        // Command arguments
  env?: Record<string, string>;  // Environment variable overrides
  url?: string;           // URL for SSE servers
  cwd?: string;           // Working directory
}

MCPTool

interface MCPTool {
  name: string;
  description: string;
  inputSchema: MCPJsonSchema;
}

MCPToolResult

interface MCPToolResult {
  content: Array<{
    type: string;
    text?: string;
  }>;
  isError?: boolean;
}

MCPValue

type MCPPrimitive = string | number | boolean | null;
type MCPValue = MCPPrimitive | MCPPrimitive[] | { [key: string]: MCPValue };

Creare server MCP

Definisci i server MCP come oggetti array con caricamento automatico dell'ambiente:

import { Agent } from '@astreus-ai/astreus';

// Define MCP servers array
const mcpServers = [
  {
    name: 'github',
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-github"]
    // GITHUB_PERSONAL_ACCESS_TOKEN loaded from .env automatically
  },
  {
    name: 'filesystem', 
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
  }
];

const agent = await Agent.create({
  name: 'DevAgent',
  model: 'gpt-4'
});

// Add MCP servers to agent
await agent.addMCPServers(mcpServers);

// Use automatically in conversations
const response = await agent.ask("List my repositories and save to repos.txt");

Esempio

Ecco un esempio completo che mostra l'integrazione MCP:

import { Agent } from '@astreus-ai/astreus';

// Create agent
const agent = await Agent.create({
  name: 'DevAssistant',
  model: 'gpt-4',
  systemPrompt: 'You are a helpful development assistant with access to various tools.'
});

// Add MCP servers
await agent.addMCPServers([
  {
    name: 'github',
    command: "npx", 
    args: ["-y", "@modelcontextprotocol/server-github"]
  },
  {
    name: 'filesystem',
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
  },
  {
    name: 'search',
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-brave-search"]
  }
]);

// Agent now has access to GitHub, filesystem, and search tools
const response = await agent.ask(`
  Check my latest repositories, 
  create a summary file in my project directory,
  and search for TypeScript best practices
`);

console.log(response);

Variabili d'ambiente

I server MCP caricano automaticamente le variabili d'ambiente dal tuo file .env:

# .env
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx
BRAVE_API_KEY=your_brave_api_key
GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json

Non è necessario specificare le variabili d'ambiente nel codice: vengono caricate automaticamente e in modo sicuro.

Tipi di server

Server locali (stdio)

Per server che vengono eseguiti come processi locali:

const localServers = [
  {
    name: 'sqlite',
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "/path/to/db.sqlite"],
    cwd: "/working/directory"
  }
];

Server remoti (SSE)

Per server che si connettono via HTTP/SSE:

const remoteServers = [
  {
    name: 'api-server',
    url: "https://api.example.com/mcp/events"
  }
];

Utilizzo su più livelli

Livello Agent

Disponibile per tutti i task e le conversazioni:

// Agent-level: Available everywhere 
await agent.addMCPServers([
  {
    name: 'filesystem',
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
  }
]);

Livello Task

Disponibile per task specifici:

// Task-level: Available for this task only
const task = await agent.createTask({
  prompt: "Analyze my GitHub repositories",
  mcpServers: [
    {
      name: 'github',
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-github"]
    }
  ]
});

Livello Conversazione

Disponibile per singole conversazioni:

// Conversation-level: Available for this conversation only
const response = await agent.ask("Search for TypeScript news", {
  mcpServers: [
    {
      name: 'search',
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-brave-search"]
    }
  ]
});

Accesso manuale agli strumenti

Accedi agli strumenti MCP programmaticamente:

// List available MCP tools
const tools: MCPTool[] = agent.getMCPTools();
console.log('Available MCP tools:', tools.map(t => t.name));

// Call specific MCP tool
// Tool name format: "server:tool_name" or just "tool_name" (auto-resolves server)
const result: MCPToolResult = await agent.callMCPTool('github:list_repos', {
  owner: 'username'
});

// Remove an MCP server by name (synchronous)
agent.removeMCPServer('github');

Tipi di risposta

Risposta di callMCPTool

const result: MCPToolResult = await agent.callMCPTool('github:list_repos', { owner: 'username' });

// Response structure (MCPToolResult):
{
  content: [
    { type: 'text', text: 'Repository list...' }
  ],
  isError?: boolean  // Optional error flag
}

Risposta di getMCPTools

const tools: MCPTool[] = agent.getMCPTools();

// Response structure (MCPTool[]):
[
  {
    name: 'list_repos',           // Tool name without server prefix
    description: 'List repositories for a user',
    inputSchema: {                // MCPJsonSchema
      type: 'object',
      properties: {
        owner: { type: 'string', description: 'Repository owner' }
      },
      required: ['owner']
    }
  }
]

Riferimento API

Metodi MCP dell'Agent

// Add a single MCP server (async)
async addMCPServer(serverDef: MCPServerDefinition): Promise<void>

// Add multiple MCP servers (async)
async addMCPServers(servers: MCPServerDefinition[]): Promise<void>

// Remove an MCP server by name (sync)
removeMCPServer(name: string): void

// Call an MCP tool (async)
async callMCPTool(
  toolName: string,                    // "server:tool" or just "tool"
  args: Record<string, MCPValue>       // Tool arguments
): Promise<MCPToolResult>

// Get all available MCP tools (sync)
getMCPTools(): MCPTool[]

L'integrazione MCP offre un accesso potente a strumenti esterni mantenendo sicurezza e semplicità.

Ultimo aggiornamento: 6 luglio 2026

In questa sezione

Introduzione

Framework AI agent open-source per costruire sistemi autonomi che risolvono in modo efficace problemi del mondo reale.

Installazione

Installa Astreus con npm, yarn o pnpm, verifica la versione richiesta di Node.js e prepara un progetto locale per costruire agenti AI con il framework.

Avvio rapido

Costruisci il tuo primo agente AI con Astreus in meno di 2 minuti Scopri i pattern di configurazione, le API e gli esempi pratici necessari per creare...

Agente

Entità AI centrale con funzionalità modulari e composizione basata su decoratori Scopri i pattern di configurazione, le API e gli esempi pratici necessari...

Plugin

Visione