بناء عميل MCP بـ TypeScript: الاتصال بأي خادم أدوات ذكاء اصطناعي

mkdir mcp-client && cd mcp-client
npm init -y

npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true
  },
  "include": ["src/**/*"]
}

mkdir src

{
  "type": "module",
  "scripts": {
    "start": "tsx src/index.ts",
    "build": "tsc",
    "dev": "tsx watch src/index.ts"
  }
}

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 
export async function createMCPClient(
  serverCommand: string,
  serverArgs: string[] = [],
  env?: Record<string, string>
) {
  const transport = new StdioClientTransport({
    command: serverCommand,
    args: serverArgs,
    env: env ? { ...process.env, ...env } as Record<string, string> : undefined,
  });
 
  const client = new Client(
    {
      name: "my-mcp-client",
      version: "1.0.0",
    },
    {
      capabilities: {
        roots: { listChanged: true },
        sampling: {},
      },
    }
  );
 
  await client.connect(transport);
  return client;
}

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 
export async function discoverCapabilities(client: Client) {
  const serverInfo = client.getServerVersion();
  console.log("متصل بالخادم:", serverInfo);
 
  const capabilities = client.getServerCapabilities();
  console.log("إمكانيات الخادم:", capabilities);
 
  if (capabilities?.tools) {
    const toolsResult = await client.listTools();
    console.log(`\nتم العثور على ${toolsResult.tools.length} أداة:`);
    for (const tool of toolsResult.tools) {
      console.log(`  - ${tool.name}: ${tool.description}`);
    }
  }
 
  if (capabilities?.resources) {
    const resourcesResult = await client.listResources();
    console.log(`\nتم العثور على ${resourcesResult.resources.length} مورد:`);
    for (const resource of resourcesResult.resources) {
      console.log(`  - ${resource.uri}: ${resource.name}`);
    }
  }
 
  if (capabilities?.prompts) {
    const promptsResult = await client.listPrompts();
    console.log(`\nتم العثور على ${promptsResult.prompts.length} قالب:`);
    for (const prompt of promptsResult.prompts) {
      console.log(`  - ${prompt.name}: ${prompt.description}`);
    }
  }
 
  return capabilities;
}

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 
export async function callTool(
  client: Client,
  toolName: string,
  args: Record<string, unknown> = {}
) {
  const result = await client.callTool({
    name: toolName,
    arguments: args,
  });
 
  if (result.isError) {
    throw new Error(
      `فشلت الأداة "${toolName}": ${JSON.stringify(result.content)}`
    );
  }
 
  return result;
}
 
export async function listAndDescribeTools(client: Client) {
  const { tools } = await client.listTools();
 
  return tools.map((tool) => ({
    name: tool.name,
    description: tool.description,
    parameters: tool.inputSchema,
  }));
}

const result = await callTool(client, "search_files", {
  query: "authentication",
  path: "./src",
});
 
for (const content of result.content) {
  if (content.type === "text") {
    console.log(content.text);
  }
}

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 
export function processToolResult(result: Awaited<ReturnType<Client["callTool"]>>) {
  const outputs: string[] = [];
 
  for (const content of result.content) {
    switch (content.type) {
      case "text":
        outputs.push(content.text);
        break;
      case "image":
        outputs.push(`[صورة: ${content.mimeType}, ${content.data.length} بايت]`);
        break;
      case "resource":
        outputs.push(`[مورد: ${content.resource.uri}]`);
        break;
      default:
        outputs.push(`[نوع محتوى غير معروف]`);
    }
  }
 
  return outputs.join("\n");
}

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 
export async function readResource(client: Client, uri: string) {
  const result = await client.readResource({ uri });
 
  for (const content of result.contents) {
    if (content.text) {
      return content.text;
    }
    if (content.blob) {
      return `[بيانات ثنائية: ${content.mimeType}]`;
    }
  }
 
  return null;
}
 
export async function listAllResources(client: Client) {
  const resources: Array<{ uri: string; name: string; description?: string }> = [];
 
  const result = await client.listResources();
  resources.push(...result.resources);
 
  let cursor = result.nextCursor;
  while (cursor) {
    const nextPage = await client.listResources({ cursor });
    resources.push(...nextPage.resources);
    cursor = nextPage.nextCursor;
  }
 
  return resources;
}

export async function listResourceTemplates(client: Client) {
  const result = await client.listResourceTemplates();
 
  for (const template of result.resourceTemplates) {
    console.log(`القالب: ${template.uriTemplate}`);
    console.log(`  الاسم: ${template.name}`);
    console.log(`  الوصف: ${template.description}`);
  }
 
  return result.resourceTemplates;
}

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 
export async function getPrompt(
  client: Client,
  promptName: string,
  args: Record<string, string> = {}
) {
  const result = await client.getPrompt({
    name: promptName,
    arguments: args,
  });
 
  console.log(`القالب: ${result.description}`);
 
  for (const message of result.messages) {
    console.log(`[${message.role}]:`);
    if (message.content.type === "text") {
      console.log(message.content.text);
    }
  }
 
  return result;
}

import * as readline from "node:readline";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { createMCPClient } from "./client.js";
import { discoverCapabilities } from "./discover.js";
import { callTool, listAndDescribeTools, processToolResult } from "./tools.js";
import { readResource, listAllResources } from "./resources.js";
import { getPrompt } from "./prompts.js";
 
class MCPExplorer {
  private client: Client | null = null;
  private rl: readline.Interface;
 
  constructor() {
    this.rl = readline.createInterface({
      input: process.stdin,
      output: process.stdout,
    });
  }
 
  private prompt(question: string): Promise<string> {
    return new Promise((resolve) => {
      this.rl.question(question, resolve);
    });
  }
 
  async connect(command: string, args: string[] = []) {
    console.log(`جاري الاتصال بالخادم: ${command} ${args.join(" ")}`);
    this.client = await createMCPClient(command, args);
    await discoverCapabilities(this.client);
    console.log("\nتم إنشاء الاتصال. اكتب 'help' للأوامر.\n");
  }
 
  async run() {
    if (!this.client) {
      const serverCmd = process.argv[2];
      const serverArgs = process.argv.slice(3);
 
      if (!serverCmd) {
        console.log("الاستخدام: tsx src/index.ts <server-command> [args...]");
        console.log("مثال: tsx src/index.ts npx -y @modelcontextprotocol/server-everything");
        process.exit(1);
      }
 
      await this.connect(serverCmd, serverArgs);
    }
 
    while (true) {
      const input = await this.prompt("mcp> ");
      const [command, ...params] = input.trim().split(" ");
 
      try {
        await this.handleCommand(command, params);
      } catch (error) {
        console.error("خطأ:", (error as Error).message);
      }
    }
  }
 
  private async handleCommand(command: string, params: string[]) {
    if (!this.client) return;
 
    switch (command) {
      case "help":
        this.showHelp();
        break;
 
      case "tools":
        const tools = await listAndDescribeTools(this.client);
        for (const tool of tools) {
          console.log(`\n${tool.name}`);
          console.log(`  ${tool.description}`);
          if (tool.parameters) {
            console.log(`  المعاملات: ${JSON.stringify(tool.parameters, null, 2)}`);
          }
        }
        break;
 
      case "call": {
        const toolName = params[0];
        if (!toolName) {
          console.log("الاستخدام: call <tool-name> [json-args]");
          break;
        }
        const argsStr = params.slice(1).join(" ");
        const args = argsStr ? JSON.parse(argsStr) : {};
        const result = await callTool(this.client, toolName, args);
        console.log(processToolResult(result));
        break;
      }
 
      case "resources": {
        const resources = await listAllResources(this.client);
        for (const r of resources) {
          console.log(`  ${r.uri} — ${r.name}`);
        }
        break;
      }
 
      case "read": {
        const uri = params[0];
        if (!uri) {
          console.log("الاستخدام: read <resource-uri>");
          break;
        }
        const content = await readResource(this.client, uri);
        console.log(content);
        break;
      }
 
      case "prompts": {
        const promptsResult = await this.client.listPrompts();
        for (const p of promptsResult.prompts) {
          console.log(`  ${p.name}: ${p.description}`);
        }
        break;
      }
 
      case "prompt": {
        const promptName = params[0];
        if (!promptName) {
          console.log("الاستخدام: prompt <prompt-name> [json-args]");
          break;
        }
        const promptArgs = params.slice(1).join(" ");
        const parsedArgs = promptArgs ? JSON.parse(promptArgs) : {};
        await getPrompt(this.client, promptName, parsedArgs);
        break;
      }
 
      case "quit":
      case "exit":
        await this.client.close();
        this.rl.close();
        process.exit(0);
 
      default:
        console.log(`أمر غير معروف: ${command}. اكتب 'help' للخيارات.`);
    }
  }
 
  private showHelp() {
    console.log(`
الأوامر المتاحة:
  tools              عرض جميع الأدوات المتاحة
  call <name> [args] استدعاء أداة مع معاملات JSON اختيارية
  resources          عرض جميع الموارد المتاحة
  read <uri>         قراءة مورد بالعنوان
  prompts            عرض جميع القوالب المتاحة
  prompt <name>      الحصول على قالب مع معاملات JSON اختيارية
  help               عرض رسالة المساعدة
  quit               قطع الاتصال والخروج
    `);
  }
}
 
const explorer = new MCPExplorer();
explorer.run().catch(console.error);

npx tsx src/index.ts npx -y @modelcontextprotocol/server-everything

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 
export async function createSSEClient(serverUrl: string) {
  const transport = new SSEClientTransport(new URL(serverUrl));
 
  const client = new Client(
    {
      name: "my-mcp-client",
      version: "1.0.0",
    },
    {
      capabilities: {
        roots: { listChanged: true },
        sampling: {},
      },
    }
  );
 
  await client.connect(transport);
  return client;
}

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { createMCPClient } from "./client.js";
import { createSSEClient } from "./sse-client.js";
 
interface ServerConfig {
  name: string;
  transport: "stdio" | "sse";
  command?: string;
  args?: string[];
  url?: string;
  env?: Record<string, string>;
}
 
export class MultiServerClient {
  private clients = new Map<string, Client>();
 
  async addServer(config: ServerConfig) {
    let client: Client;
 
    if (config.transport === "stdio" && config.command) {
      client = await createMCPClient(
        config.command,
        config.args ?? [],
        config.env
      );
    } else if (config.transport === "sse" && config.url) {
      client = await createSSEClient(config.url);
    } else {
      throw new Error(`إعداد خادم غير صالح لـ "${config.name}"`);
    }
 
    this.clients.set(config.name, client);
    console.log(`تم الاتصال بـ "${config.name}"`);
    return client;
  }
 
  async listAllTools() {
    const allTools: Array<{
      server: string;
      name: string;
      description?: string;
    }> = [];
 
    for (const [serverName, client] of this.clients) {
      const capabilities = client.getServerCapabilities();
      if (!capabilities?.tools) continue;
 
      const { tools } = await client.listTools();
      for (const tool of tools) {
        allTools.push({
          server: serverName,
          name: tool.name,
          description: tool.description,
        });
      }
    }
 
    return allTools;
  }
 
  async callTool(
    serverName: string,
    toolName: string,
    args: Record<string, unknown> = {}
  ) {
    const client = this.clients.get(serverName);
    if (!client) {
      throw new Error(`الخادم "${serverName}" غير موجود`);
    }
 
    return client.callTool({ name: toolName, arguments: args });
  }
 
  async disconnectAll() {
    for (const [name, client] of this.clients) {
      await client.close();
      console.log(`تم قطع الاتصال من "${name}"`);
    }
    this.clients.clear();
  }
}

import { MultiServerClient } from "./multi-client.js";
 
const manager = new MultiServerClient();
 
await manager.addServer({
  name: "filesystem",
  transport: "stdio",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
});
 
await manager.addServer({
  name: "github",
  transport: "stdio",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-github"],
  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN ?? "" },
});
 
const allTools = await manager.listAllTools();
console.log("جميع الأدوات المتاحة عبر الخوادم:");
for (const tool of allTools) {
  console.log(`  [${tool.server}] ${tool.name}: ${tool.description}`);
}
 
const files = await manager.callTool("filesystem", "list_directory", {
  path: "/tmp",
});
 
await manager.disconnectAll();

import Anthropic from "@anthropic-ai/sdk";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 
export async function runAgentLoop(
  anthropic: Anthropic,
  mcpClient: Client,
  userMessage: string
) {
  const { tools: mcpTools } = await mcpClient.listTools();
 
  const anthropicTools: Anthropic.Tool[] = mcpTools.map((tool) => ({
    name: tool.name,
    description: tool.description ?? "",
    input_schema: tool.inputSchema as Anthropic.Tool.InputSchema,
  }));
 
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: userMessage },
  ];
 
  let response = await anthropic.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 4096,
    tools: anthropicTools,
    messages,
  });
 
  while (response.stop_reason === "tool_use") {
    const toolUseBlocks = response.content.filter(
      (block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
    );
 
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
 
    for (const toolUse of toolUseBlocks) {
      console.log(`استدعاء الأداة: ${toolUse.name}`);
      const result = await mcpClient.callTool({
        name: toolUse.name,
        arguments: toolUse.input as Record<string, unknown>,
      });
 
      const textContent = result.content
        .filter((c): c is { type: "text"; text: string } => c.type === "text")
        .map((c) => c.text)
        .join("\n");
 
      toolResults.push({
        type: "tool_result",
        tool_use_id: toolUse.id,
        content: textContent,
      });
    }
 
    messages.push({ role: "assistant", content: response.content });
    messages.push({ role: "user", content: toolResults });
 
    response = await anthropic.messages.create({
      model: "claude-sonnet-4-20250514",
      max_tokens: 4096,
      tools: anthropicTools,
      messages,
    });
  }
 
  const finalText = response.content
    .filter((block): block is Anthropic.TextBlock => block.type === "text")
    .map((block) => block.text)
    .join("\n");
 
  return finalText;
}

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { createMCPClient } from "./client.js";
 
export class ResilientMCPClient {
  private client: Client | null = null;
  private command: string;
  private args: string[];
  private maxRetries: number;
 
  constructor(command: string, args: string[] = [], maxRetries = 3) {
    this.command = command;
    this.args = args;
    this.maxRetries = maxRetries;
  }
 
  async connect(): Promise<Client> {
    for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
      try {
        this.client = await createMCPClient(this.command, this.args);
        return this.client;
      } catch (error) {
        console.error(`محاولة الاتصال ${attempt} فشلت:`, error);
        if (attempt === this.maxRetries) throw error;
        const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
        await new Promise((r) => setTimeout(r, delay));
      }
    }
    throw new Error("فشل الاتصال بعد جميع المحاولات");
  }
 
  async callToolSafely(
    toolName: string,
    args: Record<string, unknown> = {}
  ) {
    if (!this.client) {
      await this.connect();
    }
 
    try {
      return await this.client!.callTool({ name: toolName, arguments: args });
    } catch (error) {
      console.error(`فشل استدعاء الأداة، جاري إعادة الاتصال...`);
      await this.connect();
      return this.client!.callTool({ name: toolName, arguments: args });
    }
  }
 
  async disconnect() {
    if (this.client) {
      await this.client.close();
      this.client = null;
    }
  }
}

import { readFile } from "node:fs/promises";
import { MultiServerClient } from "./multi-client.js";
 
interface MCPConfig {
  mcpServers: Record<
    string,
    {
      command: string;
      args?: string[];
      env?: Record<string, string>;
    }
  >;
}
 
export async function loadFromConfig(configPath: string) {
  const raw = await readFile(configPath, "utf-8");
  const config: MCPConfig = JSON.parse(raw);
 
  const manager = new MultiServerClient();
 
  for (const [name, server] of Object.entries(config.mcpServers)) {
    await manager.addServer({
      name,
      transport: "stdio",
      command: server.command,
      args: server.args,
      env: server.env,
    });
  }
 
  return manager;
}

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

npx @modelcontextprotocol/inspector

import { describe, it, expect } from "vitest";
import { createMCPClient } from "./client.js";
 
describe("MCP Client", () => {
  it("يجب أن يتصل بخادم everything", async () => {
    const client = await createMCPClient("npx", [
      "-y",
      "@modelcontextprotocol/server-everything",
    ]);
 
    const version = client.getServerVersion();
    expect(version).toBeDefined();
 
    const { tools } = await client.listTools();
    expect(tools.length).toBeGreaterThan(0);
 
    await client.close();
  });
 
  it("يجب أن يستدعي أداة echo", async () => {
    const client = await createMCPClient("npx", [
      "-y",
      "@modelcontextprotocol/server-everything",
    ]);
 
    const result = await client.callTool({
      name: "echo",
      arguments: { message: "اختبار" },
    });
 
    expect(result.content).toBeDefined();
    await client.close();
  });
});