كيفية بناء خادم MCP يمنح وكلاء الذكاء الاصطناعي قدرات اختبار API

الخلاصة

ابنِ خادم MCP باستخدام TypeScript يعرض ثلاث أدوات: run_test، و validate_schema، و list_environments. قم بتكوينه في ~/.claude/settings.json لـ Claude Code أو .cursor/mcp.json لـ Cursor. يمكن لوكلاء الذكاء الاصطناعي لديك بعد ذلك تشغيل اختبارات Apidog، والتحقق من صحة مخططات OpenAPI، وجلب البيئات دون مغادرة واجهة الدردشة. يبلغ حجم الكود المصدري الكامل حوالي 150 سطرًا ويستخدم حزمة @modelcontextprotocol/sdk.

ابنِ خادم MCP يتيح لـ Claude Code، و Cursor، ووكلاء الذكاء الاصطناعي الآخرين تشغيل اختبارات Apidog API، والتحقق من صحة المخططات، ومقارنة الاستجابات، كل ذلك دون مغادرة واجهة الدردشة الخاصة بهم.

💡

أنت في منتصف جلسة برمجة. انتهى وكيل الذكاء الاصطناعي الخاص بك للتو من بناء نقطة نهاية API. بدلاً من نسخ الكود، وفتح Apidog، وإنشاء مجموعة اختبار، وتشغيل التحقق يدويًا، تريد كتابة أمر واحد والحصول على النتائج.

زر

هذا ما يتيحه بروتوكول سياق النموذج (MCP). يتيح MCP لوكلاء الذكاء الاصطناعي الوصول إلى الأدوات الخارجية من خلال واجهة موحدة. ابنِ خادم MCP لـ Apidog، ويمكن لوكيل الذكاء الاصطناعي الخاص بك تشغيل الاختبارات، والتحقق من صحة المخططات، وجلب البيئات دون تبديل السياق.

ما هو بروتوكول سياق النموذج (MCP)؟

MCP (Model Context Protocol) هو بروتوكول لوكلاء الذكاء الاصطناعي للوصول إلى الأدوات ومصادر البيانات الخارجية. فكر فيه كنظام إضافي يعمل عبر Claude Code، و Cursor، وعملاء آخرين متوافقين مع MCP.

يعرض خادم MCP أدوات (وظائف يمكن للوكيل استدعاؤها) وموارد (بيانات يمكن للوكيل قراءتها). سيعرض خادم Apidog MCP الخاص بك أدوات لاختبار واجهة برمجة التطبيقات.

┌─────────────────┐         ┌──────────────────┐         ┌─────────────┐
│  وكيل الذكاء      │         │  خادم MCP        │         │  Apidog     │
│  الاصطناعي      │◄───────►│  (كودك الخاص بك) │◄───────►│  API        │
│  (Claude Code)  │   JSON  └──────────────────┘  HTTP   └─────────────┘
└─────────────────┘

الخطوة 1: إعداد المشروع

أنشئ مشروع TypeScript جديدًا:

mkdir apidog-mcp-server
cd apidog-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

أنشئ ملف tsconfig.json:

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

أضف سكريبت البناء إلى package.json:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

الخطوة 2: إنشاء هيكل خادم MCP

أنشئ ملف src/index.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "apidog",
  version: "1.0.0",
  description: "Apidog API testing tools for AI agents"
});

// Tools will be defined here

const transport = new StdioServerTransport();
await server.connect(transport);

يقوم هذا الهيكل بإنشاء خادم MCP وربطه بوسيط نقل stdio. يتعامل وسيط النقل مع الاتصال بين وكيل الذكاء الاصطناعي وخادمك عبر الإدخال/الإخراج القياسي.

الخطوة 3: تعريف أداة `run_test`

أضف الأداة الأولى إلى src/index.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "apidog",
  version: "1.0.0",
  description: "Apidog API testing tools for AI agents"
});

// Tool: run_test
server.tool(
  "run_test",
  {
    projectId: z.string().describe("معرّف مشروع Apidog (موجود في عنوان URL للمشروع)"),
    environmentId: z.string().optional().describe("معرّف البيئة الاختياري لتنفيذ الاختبار"),
    testSuiteId: z.string().optional().describe("معرّف مجموعة الاختبار الاختياري لتشغيل مجموعة معينة")
  },
  async ({ projectId, environmentId, testSuiteId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "خطأ: لم يتم تعيين متغير البيئة APIDOG_API_KEY"
        }]
      };
    }

    // Build API URL
    let url = `https://api.apidog.com/v1/projects/${projectId}/tests/run`;
    const params = new URLSearchParams();
    if (environmentId) params.append("environmentId", environmentId);
    if (testSuiteId) params.append("testSuiteId", testSuiteId);
    if (params.toString()) url += `?${params.toString()}`;

    try {
      const response = await fetch(url, {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${apiKey}`,
          "Content-Type": "application/json"
        }
      });

      if (!response.ok) {
        const error = await response.text();
        return {
          content: [{
            type: "text",
            text: `خطأ API: ${response.status} ${error}`
          }]
        };
      }

      const results = await response.json();
      return {
        content: [{
          type: "text",
          text: JSON.stringify(results, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `فشل الطلب: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

يتكون تعريف الأداة من ثلاثة أجزاء:

الاسم — run_test (يختار الوكلاء الأدوات بالاسم، لذا اجعله وصفيًا)
المخطط — التحقق من صحة Zod للمعاملات مع الأوصاف
المعالج — دالة غير متزامنة تستدعي واجهة برمجة تطبيقات Apidog

الخطوة 4: إضافة أداة `validate_schema`

أضف التحقق من صحة المخطط لالتقاط أخطاء OpenAPI قبل النشر:

// Tool: validate_schema
server.tool(
  "validate_schema",
  {
    schema: z.object({}).describe("كائن مخطط OpenAPI 3.x للتحقق من صحته"),
    strict: z.boolean().optional().default(false).describe("تمكين الوضع الصارم لإجراء فحوصات إضافية")
  },
  async ({ schema, strict }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "خطأ: لم يتم تعيين متغير البيئة APIDOG_API_KEY"
        }]
      };
    }

    try {
      const response = await fetch("https://api.apidog.com/v1/schemas/validate", {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${apiKey}`,
          "Content-Type": "application/json"
        },
        body: JSON.stringify({ schema, strict })
      });

      const result = await response.json();

      if (!response.ok) {
        return {
          content: [{
            type: "text",
            text: `فشل التحقق من الصحة: ${JSON.stringify(result.errors, null, 2)}`
          }]
        };
      }

      return {
        content: [{
          type: "text",
          text: result.valid
            ? "المخطط صالح لـ OpenAPI 3.x"
            : `تحذيرات: ${JSON.stringify(result.warnings, null, 2)}`
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `فشل التحقق من الصحة: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);

الخطوة 5: إضافة أداة `list_environments`

أضف أداة لجلب بيئات الاختبار المتاحة:

// Tool: list_environments
server.tool(
  "list_environments",
  {
    projectId: z.string().describe("معرّف مشروع Apidog")
  },
  async ({ projectId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "خطأ: لم يتم تعيين متغير البيئة APIDOG_API_KEY"
        }]
      };
    }

    try {
      const response = await fetch(
        `https://api.apidog.com/v1/projects/${projectId}/environments`,
        {
          headers: {
            "Authorization": `Bearer ${apiKey}`
          }
        }
      );

      if (!response.ok) {
        const error = await response.text();
        return {
          content: [{
            type: "text",
            text: `خطأ API: ${response.status} ${error}`
          }]
        };
      }

      const environments = await response.json();
      return {
        content: [{
          type: "text",
          text: environments.length === 0
            ? "لم يتم العثور على بيئات لهذا المشروع"
            : environments.map((e: any) =>
                `- ${e.name} (المعرف: ${e.id})${e.isDefault ? " [افتراضي]" : ""}`
              ).join("\n")
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `فشل الطلب: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);

الخطوة 6: البناء والاختبار

ابنِ الخادم:

npm run build

اختبر باستخدام عميل MCP بسيط. أنشئ ملف test-client.js:

import { spawn } from "child_process";

const server = spawn("node", ["dist/index.js"], {
  env: { ...process.env, APIDOG_API_KEY: "your-api-key" }
});

server.stdout.on("data", (data) => {
  console.log(`Server output: ${data}`);
});

server.stderr.on("data", (data) => {
  console.error(`Server error: ${data}`);
});

// Send a test message
const message = {
  jsonrpc: "2.0",
  id: 1,
  method: "initialize",
  params: {
    protocolVersion: "2024-11-05",
    capabilities: {},
    clientInfo: { name: "test-client", version: "1.0.0" }
  }
};

server.stdin.write(JSON.stringify(message) + "\n");

الخطوة 7: التكوين لـ Claude Code

أضف خادم MCP إلى تكوين Claude Code الخاص بك:

أنشئ أو عدّل ملف ~/.claude/settings.json:

{
  "mcpServers": {
    "apidog": {
      "command": "node",
      "args": ["/absolute/path/to/apidog-mcp-server/dist/index.js"],
      "env": {
        "APIDOG_API_KEY": "your-api-key-here"
      }
    }
  }
}

أعد تشغيل Claude Code. يجب أن تظهر أدوات Apidog الآن عندما تطلب المساعدة في اختبار واجهة برمجة التطبيقات.

الاستخدام في Claude Code:

Use the run_test tool to run tests on my Apidog project.
Project ID: proj_12345
Environment: staging

Validate this OpenAPI schema against Apidog rules:
[paste schema]

List all environments for project proj_12345

الخطوة 8: التكوين لـ Cursor

يستخدم Cursor تكوين MCP مشابهًا. أنشئ ملف .cursor/mcp.json في مشروعك:

{
  "mcpServers": {
    "apidog": {
      "command": "node",
      "args": ["/absolute/path/to/apidog-mcp-server/dist/index.js"],
      "env": {
        "APIDOG_API_KEY": "your-api-key-here"
      }
    }
  }
}

الاستخدام في Cursor:

@apidog run_test projectId="proj_12345" environmentId="staging"

الكود المصدري الكامل

إليك المحتوى الكامل لملف src/index.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "apidog",
  version: "1.0.0",
  description: "Apidog API testing tools for AI agents"
});

// Tool: run_test
server.tool(
  "run_test",
  {
    projectId: z.string().describe("معرّف مشروع Apidog"),
    environmentId: z.string().optional().describe("معرّف البيئة"),
    testSuiteId: z.string().optional().describe("معرّف مجموعة الاختبار")
  },
  async ({ projectId, environmentId, testSuiteId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "خطأ: لم يتم تعيين APIDOG_API_KEY"
        }]
      };
    }

    let url = `https://api.apidog.com/v1/projects/${projectId}/tests/run`;
    const params = new URLSearchParams();
    if (environmentId) params.append("environmentId", environmentId);
    if (testSuiteId) params.append("testSuiteId", testSuiteId);
    if (params.toString()) url += `?${params.toString()}`;

    try {
      const response = await fetch(url, {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${apiKey}`,
          "Content-Type": "application/json"
        }
      });

      const results = await response.json();
      return {
        content: [{
          type: "text",
          text: JSON.stringify(results, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `فشل الطلب: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);

// Tool: validate_schema
server.tool(
  "validate_schema",
  {
    schema: z.object({}).describe("مخطط OpenAPI"),
    strict: z.boolean().optional().default(false)
  },
  async ({ schema, strict }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "خطأ: لم يتم تعيين APIDOG_API_KEY"
        }]
      };
    }

    const response = await fetch("https://api.apidog.com/v1/schemas/validate", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ schema, strict })
    });

    const result = await response.json();
    return {
      content: [{
        type: "text",
        text: result.valid
          ? "المخطط صالح"
          : `مشاكل: ${JSON.stringify(result.errors || result.warnings, null, 2)}`
      }]
    };
  }
);

// Tool: list_environments
server.tool(
  "list_environments",
  {
    projectId: z.string().describe("معرّف مشروع Apidog")
  },
  async ({ projectId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "خطأ: لم يتم تعيين APIDOG_API_KEY"
        }]
      };
    }

    const response = await fetch(
      `https://api.apidog.com/v1/projects/${projectId}/environments`,
      {
        headers: { "Authorization": `Bearer ${apiKey}` }
      }
    );

    const environments = await response.json();
    return {
      content: [{
        type: "text",
        text: environments.map((e: any) =>
          `- ${e.name} (${e.id})${e.isDefault ? " [افتراضي]" : ""}`
        ).join("\n")
      }]
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

ما قمت ببنائه

المكون	الغرض
خادم MCP	يربط وكلاء الذكاء الاصطناعي بواجهة برمجة تطبيقات Apidog
`run_test`	تنفيذ مجموعات الاختبار برمجيًا
`validate_schema`	اكتشاف أخطاء OpenAPI قبل النشر
`list_environments`	اكتشاف بيئات الاختبار المتاحة
التحقق من صحة Zod	معالجة آمنة للنوع للمعاملات
وسيط نقل Stdio	يعمل مع Claude Code و Cursor وأي عميل MCP

الخطوات التالية

توسيع الخادم:

أضف أداة compare_responses لمقارنة نتائج الاختبار عبر البيئات
أضف get_test_history لجلب سجل تشغيلات الاختبار
أضف trigger_mock_server لبدء/إيقاف نقاط النهاية الوهمية

اعتبارات الإنتاج:

أضف منطق إعادة المحاولة لطلبات الشبكة غير المستقرة
طبق تحديد المعدل لتجنب تقييد واجهة برمجة التطبيقات
أضف التسجيل لتصحيح أخطاء استدعاءات الأدوات الفاشلة
قم بتخزين مفاتيح API في خزنة آمنة بدلاً من متغيرات البيئة

شارك مع فريقك:

انشر إلى npm باسم @your-org/apidog-mcp-server
وثّق متغيرات البيئة المطلوبة
ضمّن أمثلة تكوينات MCP للعملاء الشائعين

استكشاف الأخطاء الشائعة وإصلاحها

خادم MCP لا يتم تحميله في Claude Code:

تحقق من أن المسار في ~/.claude/settings.json مطلق (وليس نسبيًا)
تحقق من وجود node في متغير PATH الخاص بك: which node
تأكد من وجود ملف dist/index.js المبني: ls -la dist/
ابحث عن الأخطاء في سجلات MCP الخاصة بـ Claude Code

الأدوات لا تظهر بعد التكوين:

أعد تشغيل Claude Code بالكامل (أغلقه وأعد فتحه)
قم بتشغيل npm run build للتأكد من تجميع TypeScript
تحقق من تعريف جميع الأدوات الثلاث قبل server.connect()
تحقق من أن الخادم يبدأ بدون أخطاء: node dist/index.js

فشل طلبات واجهة برمجة التطبيقات برمز 401:

تأكد من تعيين APIDOG_API_KEY في التكوين
تحقق من عدم وجود مسافات إضافية أو علامات اقتباس حول قيمة المفتاح
تحقق من تمكين وصول API لحساب Apidog الخاص بك
اختبر المفتاح يدويًا: curl -H "Authorization: Bearer $APIDOG_API_KEY" https://api.apidog.com/v1/user

أخطاء التحقق من صحة Zod:

تأكد من مطابقة أسماء المعلمات للمخطط تمامًا
تحقق من توفير الحقول المطلوبة (لا توجد أخطاء إملائية في projectId)
تحقق من أن الحقول الاختيارية تستخدم .optional() في المخطط
اقرأ رسالة الخطأ الكاملة — يخبرك Zod بالحقل الذي فشل

أخطاء تجميع TypeScript:

قم بتشغيل npm install للتأكد من تثبيت جميع التبعيات
تحقق من إصدار TypeScript: npx tsc --version (يجب أن يكون 5.x)
مسح وإعادة البناء: rm -rf dist && npm run build
ابحث عن عدم تطابق الأنواع في استجابات الجلب (أضف تأكيدات النوع as)

اختبار خادم MCP الخاص بك محليًا

قبل النشر إلى بيئة الإنتاج، اختبر خادمك محليًا:

الاختبار اليدوي باستخدام stdio:

# Start the server
node dist/index.js

# In another terminal, send a test message
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

الناتج المتوقع:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      { "name": "run_test", "description": "...", "inputSchema": {...} },
      { "name": "validate_schema", "description": "...", "inputSchema": {...} },
      { "name": "list_environments", "description": "...", "inputSchema": {...} }
    ]
  }
}

اختبار استدعاء أداة:

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_environments","arguments":{"projectId":"your-project-id"}}}' | node dist/index.js

وكلاء الذكاء الاصطناعي لديك لديهم الآن وصول مباشر إلى إمكانيات اختبار Apidog. لا مزيد من النسخ واللصق بين الدردشة والمتصفح. لا مزيد من تشغيل الاختبارات اليدوية. اكتب أمرًا، واحصل على النتائج.

هذه هي قوة MCP: قم بتوسيع وكلاء الذكاء الاصطناعي لديك بأدوات خاصة بالمجال، ودعهم يقومون بما هو مفترض منهم - مساعدتك على التسليم بشكل أسرع.

النقاط الرئيسية

تربط خوادم MCP وكلاء الذكاء الاصطناعي بواجهات برمجة التطبيقات الخارجية — ابنِ مرة واحدة، واستخدمها عبر Claude Code، و Cursor، وأي عميل متوافق مع MCP
تغطي ثلاث أدوات معظم احتياجات اختبار واجهة برمجة التطبيقات — run_test للتنفيذ، validate_schema للتحقق من صحة OpenAPI، list_environments للاكتشاف
يمنع التحقق من صحة Zod المعلمات الخاطئة — تلتقط تعريفات الأدوات الآمنة للنوع الأخطاء قبل استدعاءات واجهة برمجة التطبيقات
التكوين خاص بالأداة — يستخدم Claude Code ملف ~/.claude/settings.json، ويستخدم Cursor ملف .cursor/mcp.json
يتطلب الإنتاج معالجة الأخطاء — أضف منطق إعادة المحاولة، وتحديد المعدل، وتخزين المفاتيح بشكل آمن قبل النشر

زر

الأسئلة الشائعة

ما هو MCP في الذكاء الاصطناعي؟MCP (بروتوكول سياق النموذج) هو بروتوكول موحد يسمح لوكلاء الذكاء الاصطناعي بالوصول إلى الأدوات ومصادر البيانات الخارجية. فكر فيه كنظام إضافي (plugin system) لوكلاء الذكاء الاصطناعي.

كيف أقوم بإنشاء خادم MCP لـ Apidog؟قم بتثبيت @modelcontextprotocol/sdk، وعرّف الأدوات باستخدام التحقق من صحة Zod، ونفذ المعالجات التي تستدعي واجهة برمجة تطبيقات Apidog، واتصل عبر StdioServerTransport.

هل يمكنني استخدام هذا مع Cursor؟نعم. أضف تكوين خادم MCP إلى ملف .cursor/mcp.json في جذر مشروعك. يعمل نفس الخادم مع Claude Code، و Cursor، وعملاء MCP الآخرين.

ما هي الأدوات التي يجب أن أعرضها؟ابدأ بـ run_test لتنفيذ مجموعات الاختبار، و validate_schema للتحقق من صحة OpenAPI، و list_environments لجلب البيئات المتاحة.

هل خادم Apidog MCP جاهز للإنتاج؟الكود التعليمي هو نقطة بداية. أضف منطق إعادة المحاولة، وتحديد المعدل، ومعالجة الأخطاء المناسبة، وتخزين مفاتيح API بشكل آمن قبل الاستخدام في الإنتاج.

هل أحتاج إلى مفتاح Apidog API؟نعم. عيّن APIDOG_API_KEY كمتغير بيئة. يقرأ الخادم هذا أثناء وقت التشغيل لمصادقة طلبات واجهة برمجة التطبيقات.

هل يمكنني مشاركة خادم MCP هذا مع فريقي؟نعم. انشره إلى npm كحزمة خاصة، وثّق متغيرات البيئة المطلوبة، وضمّن أمثلة تكوينات MCP.