MCP
Ajanları harici araçlara ve servislere bağlamak için Model Context Protocol entegrasyonu
Genel Bakış#
MCP (Model Context Protocol), Astreus ajanlarının harici araçlara ve servislere sorunsuz biçimde bağlanmasını sağlar. MCP sunucularını, otomatik ortam değişkeni yüklemeli basit nesneler olarak tanımlayın ve farklı seviyelerde kullanın - ajan, görev veya konuşma seviyesinde.
Tip Tanımları#
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 };MCP Sunucuları Oluşturma#
MCP sunucularını, otomatik ortam yüklemeli dizi nesneleri olarak tanımlayın:
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-6-astra'
});
// 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");Örnek#
MCP entegrasyonunu gösteren eksiksiz bir örnek:
import { Agent } from '@astreus-ai/astreus';
// Create agent
const agent = await Agent.create({
name: 'DevAssistant',
model: 'gpt-6-astra',
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);Ortam Değişkenleri#
MCP sunucuları, ortam değişkenlerini .env dosyanızdan otomatik olarak yükler:
# .env
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx
BRAVE_API_KEY=your_brave_api_key
GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.jsonKod içinde ortam değişkenlerini belirtmenize gerek yoktur - otomatik ve güvenli biçimde yüklenirler.
Sunucu Tipleri#
Yerel Sunucular (stdio)#
Yerel işlemler olarak çalışan sunucular için:
const localServers = [
{
name: 'sqlite',
command: "npx",
args: ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "/path/to/db.sqlite"],
cwd: "/working/directory"
}
];Uzak Sunucular (SSE)#
HTTP/SSE üzerinden bağlanan sunucular için:
const remoteServers = [
{
name: 'api-server',
url: "https://api.example.com/mcp/events"
}
];Çok Seviyeli Kullanım#
Ajan Seviyesi#
Tüm görevler ve konuşmalar için kullanılabilir:
// Agent-level: Available everywhere
await agent.addMCPServers([
{
name: 'filesystem',
command: "npx",
args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
}
]);Görev Seviyesi#
Belirli görevler için kullanılabilir:
// 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"]
}
]
});Konuşma Seviyesi#
Tek bir konuşma için kullanılabilir:
// 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"]
}
]
});Manuel Araç Erişimi#
MCP araçlarına programatik olarak erişin:
// 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');Yanıt Tipleri#
callMCPTool Yanıtı#
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
}getMCPTools Yanıtı#
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']
}
}
]API Referansı#
Ajan MCP Metodları#
// 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[]MCP entegrasyonu, güvenliği ve basitliği korurken güçlü harici araç erişimi sağlar.