تخطَّ إلى المحتوى

دليل التثبيت

ابدأ العمل الفعلي خلال أقل من 5 دقائق. يتضمن هذا الدليل إعدادًا لـ 24 من عملاء MCP، بما في ذلك Claude Code, Claude Desktop, Cursor, VS Code / GitHub Copilot، وWindsurf، وغيرها.

المتطلبات الأساسية: ستحتاج إلى مفتاح API من app.maguyva.ai ومستودع GitHub متصل.

إعداد البيئة#

أولًا، عيِّن مفتاح API في متغيّر بيئة. احذف repository عندما يوفّر عميل MCP قيمة افتراضية على مستوى الطلب أو عندما يمكن للمفتاح الوصول إلى مستودع واحد فقط؛ وإلا فمرِّره صراحةً.

macOS/Linux (Bash/Zsh)#

# Add to your shell profile for persistence:
echo 'export MAGUYVA_API_KEY="mgv_xxxx"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # reload

Windows (PowerShell)#

# Make it persist in your profile:
'$Env:MAGUYVA_API_KEY="mgv_xxxx"' | Out-File -Append $PROFILE
. $PROFILE

استبدل mgv_xxxx بمفتاح API الفعلي الخاص بك من app.maguyva.ai.

إعداد العميل#

اختر عميل MCP الخاص بك أدناه للحصول على تعليمات إعداد محددة.

ملاحظة حول التوافق: يستخدم Maguyva بروتوكول MCP القياسي. يمكن لأي عميل يدعم MCP الاتصال بنفس الخادم، حتى لو لم نكتب بعد دليل إعداد رسمي خاصًا به.

Claude Code

ثبّت إضافة Maguyva من سوق Claude Code:

أضِف سوق Maguyva، ثم ثبّت الإضافة (نفّذ كل أمر داخل Claude Code):

/plugin marketplace add maguyva/claude-code-plugin
/plugin install maguyva@maguyva

يُثبَّت لحساب المستخدم الخاص بك. للفرق، أضف --scope project إلى كلا الأمرين لتثبيت الإضافة في ملف .claude/settings.json الخاص بالمستودع بحيث يحصل عليها زملاؤك تلقائيًا.

تُصادِق الإضافة عبر متغير البيئة MAGUYVA_API_KEY. اضبطه في الصدفة (shell) الخاصة بك:

export MAGUYVA_API_KEY=mgv_xxxx

يُنصح باستخدام direnv (.envrc) لكل مشروع — المفاتيح مخصصة لكل مستودع، لذا تتوافق القيمة الخاصة بكل مشروع مع صلاحيات وصوله. يعمل التصدير العام للصدفة إن كان مفتاح واحد يغطي كل عملك.

يدوي (.mcp.json) — متقدم
.mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

وثائق MCP لـ Claude Code →

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %AppData%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

أضِف إلى ملف إعداد Claude Desktop الخاص بك:

claude_desktop_config.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

يدعم Claude Desktop الخوادم البعيدة فقط كـ"موصلات" (connectors) عبر OAuth من خلال Settings، وليس كإدخال يُصادَق بترويسة في claude_desktop_config.json، لذا يُستخدم هنا جسر mcp-remote (يتطلب Node.js / npx).

وثائق MCP لـ Claude Desktop →

Cursor

macOS: ~/.cursor/mcp.json
Windows: %UserProfile%\.cursor\mcp.json
Linux: ~/.cursor/mcp.json

أضِف إلى .cursor/mcp.json في جذر مشروعك:

.cursor/mcp.json
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

وثائق MCP لـ Cursor →

VS Code / GitHub Copilot

أضِف إلى .vscode/mcp.json في مشروعك (أو إعدادات المستخدم):

.vscode/mcp.json
{
  "servers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

وثائق MCP لـ VS Code / GitHub Copilot →

Windsurf

macOS: ~/.codeium/windsurf/mcp_config.json
Windows: %UserProfile%\.codeium\windsurf\mcp_config.json
Linux: ~/.codeium/windsurf/mcp_config.json

أضِف إلى إعداد MCP الخاص بـWindsurf:

mcp_config.json
{
  "mcpServers": {
    "maguyva": {
      "serverUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

وثائق MCP لـ Windsurf →

Codex

macOS: ~/.codex/config.toml
Windows: %UserProfile%\.codex\config.toml
Linux: ~/.codex/config.toml

أضِف إلى إعداد Codex CLI الخاص بك (~/.codex/config.toml):

.codex/config.toml
[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"

[mcp_servers.maguyva.http_headers]
Authorization = "Bearer ${MAGUYVA_API_KEY}"

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

وثائق MCP لـ Codex →

GitHub Copilot CLI

أضِف إلى .copilot/mcp-config.json:

.copilot/mcp-config.json
{
  "servers": {
    "maguyva": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

وثائق MCP لـ GitHub Copilot CLI →

Gemini CLI

macOS: ~/.gemini/settings.json
Windows: %UserProfile%\.gemini\settings.json
Linux: ~/.gemini/settings.json

أضِف إلى إعدادات Gemini CLI الخاصة بك (~/.gemini/settings.json):

settings.json
{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

وثائق MCP لـ Gemini CLI →

Cline

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

أضِف إلى إعدادات MCP الخاصة بـCline:

cline_mcp_settings.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

لا يدعم هذا العميل بعد خادم MCP بعيد بترويسة مصادقة مخصصة، لذا يتصل عبر جسر mcp-remote (يتطلب Node.js / npx). يعمل Maguyva بالكامل عن بعد — الجسر فقط هو ما يعمل محليًا.

وثائق MCP لـ Cline →

Roo Code

macOS: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json

أضِف إلى إعدادات MCP الخاصة بـRoo Code:

mcp_settings.json
{
  "mcpServers": {
    "maguyva": {
      "type": "streamable-http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

وثائق MCP لـ Roo Code →

Goose

macOS: ~/.config/goose/config.yaml
Windows: %AppData%\goose\config.yaml
Linux: ~/.config/goose/config.yaml

أضِف إلى إعداد Goose الخاص بك:

config.yaml
extensions:
  maguyva:
    name: maguyva
    cmd: npx
    args:
      - -y
      - mcp-remote
      - https://maguyva.tools/mcp
      - --header
      - "Authorization: Bearer ${MAGUYVA_API_KEY}"
    enabled: true
    envs:
      MAGUYVA_API_KEY: mgv_xxxx
    type: stdio

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

لا يدعم هذا العميل بعد خادم MCP بعيد بترويسة مصادقة مخصصة، لذا يتصل عبر جسر mcp-remote (يتطلب Node.js / npx). يعمل Maguyva بالكامل عن بعد — الجسر فقط هو ما يعمل محليًا.

وثائق MCP لـ Goose →

LM Studio

يدعم LM Studio خوادم MCP عبر إعداد الوكيل (Agent) الخاص به. أضِف خادم MCP جديدًا من Settings → Agent → MCP Servers باستخدام صيغة JSON القياسية mcpServers. يتصل LM Studio بخوادم MCP عبر stdio. اطّلع على الوثائق →

Continue

macOS: ~/.continue/config.json
Windows: %UserProfile%\.continue\config.json
Linux: ~/.continue/config.json

أضِف إلى إعداد Continue الخاص بك (~/.continue/config.json):

config.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

لا يدعم هذا العميل بعد خادم MCP بعيد بترويسة مصادقة مخصصة، لذا يتصل عبر جسر mcp-remote (يتطلب Node.js / npx). يعمل Maguyva بالكامل عن بعد — الجسر فقط هو ما يعمل محليًا.

وثائق MCP لـ Continue →

Amazon Q Developer

macOS: ~/.aws/amazonq/mcp.json
Windows: %UserProfile%\.aws\amazonq\mcp.json
Linux: ~/.aws/amazonq/mcp.json

أضِف إلى إعداد MCP الخاص بـAmazon Q:

mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

لا يدعم هذا العميل بعد خادم MCP بعيد بترويسة مصادقة مخصصة، لذا يتصل عبر جسر mcp-remote (يتطلب Node.js / npx). يعمل Maguyva بالكامل عن بعد — الجسر فقط هو ما يعمل محليًا.

وثائق MCP لـ Amazon Q Developer →

PyCharm

أضِف إلى .ai/mcp/mcp.json في جذر مشروعك، أو الصق في Settings > Tools > AI Assistant > MCP:

.ai/mcp/mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

لا يدعم هذا العميل بعد خادم MCP بعيد بترويسة مصادقة مخصصة، لذا يتصل عبر جسر mcp-remote (يتطلب Node.js / npx). يعمل Maguyva بالكامل عن بعد — الجسر فقط هو ما يعمل محليًا.

وثائق MCP لـ PyCharm →

Zed

macOS: ~/.config/zed/settings.json
Windows: %AppData%\Zed\settings.json
Linux: ~/.config/zed/settings.json

أضِف إلى إعدادات Zed الخاصة بك (~/.config/zed/settings.json):

settings.json
{
  "context_servers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

وثائق MCP لـ Zed →

Trae

أضِف إلى .trae/mcp.json في جذر مشروعك:

.trae/mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

لا يدعم هذا العميل بعد خادم MCP بعيد بترويسة مصادقة مخصصة، لذا يتصل عبر جسر mcp-remote (يتطلب Node.js / npx). يعمل Maguyva بالكامل عن بعد — الجسر فقط هو ما يعمل محليًا.

وثائق MCP لـ Trae →

OpenCode

أضِف إلى opencode.json في جذر مشروعك:

opencode.json
{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

وثائق MCP لـ OpenCode →

BoltAI

macOS: ~/Library/Application Support/BoltAI/mcp_config.json

أضِف إلى إعداد MCP الخاص بـBoltAI:

mcp_config.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

لا يدعم هذا العميل بعد خادم MCP بعيد بترويسة مصادقة مخصصة، لذا يتصل عبر جسر mcp-remote (يتطلب Node.js / npx). يعمل Maguyva بالكامل عن بعد — الجسر فقط هو ما يعمل محليًا.

وثائق MCP لـ BoltAI →

LibreChat

أضِف إلى إعداد LibreChat الخاص بك:

librechat.yaml
mcpServers:
  maguyva:
    command: npx
    args:
      - -y
      - mcp-remote
      - https://maguyva.tools/mcp
      - --header
      - "Authorization: Bearer ${MAGUYVA_API_KEY}"
    env:
      MAGUYVA_API_KEY: mgv_xxxx

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

لا يدعم هذا العميل بعد خادم MCP بعيد بترويسة مصادقة مخصصة، لذا يتصل عبر جسر mcp-remote (يتطلب Node.js / npx). يعمل Maguyva بالكامل عن بعد — الجسر فقط هو ما يعمل محليًا.

وثائق MCP لـ LibreChat →

Antigravity

macOS: ~/.gemini/antigravity/mcp_config.json
Windows: %UserProfile%\.gemini\antigravity\mcp_config.json
Linux: ~/.gemini/antigravity/mcp_config.json

أضِف إلى إعداد MCP الخاص بـAntigravity:

mcp_config.json
{
  "mcpServers": {
    "maguyva": {
      "serverUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

وثائق MCP لـ Antigravity →

Claude Cowork

يستخدم Claude Cowork نفس صيغة MCP التي تستخدمها عملاء Anthropic الأخرى:

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

استبدل mgv_xxxx بمفتاح API الخاص بك من app.maguyva.ai.

وثائق MCP لـ Claude Cowork →

ChatGPT

يدعم ChatGPT خوادم MCP البعيدة في خطط Business وEnterprise وEdu عبر Settings → Apps → Create. يلزم توفر نقطة نهاية HTTPS بعيدة — لا يدعم ChatGPT الخوادم المحلية عبر stdio. راجع دليل MCP الخاص بـOpenAI للإعداد. اطّلع على الوثائق →

Warp

يدعم Warp خوادم MCP في وضع الوكيل (Agent Mode). تُدار الإعدادات عبر واجهة Warp (Settings → Agent Mode → MCP Servers) وتُزامَن عبر Warp Drive. الصق صيغة JSON القياسية mcpServers عند إضافة خادم. اطّلع على الوثائق →

تستخدم Maguyva بروتوكول MCP القياسي. يمكن لأي عميل يدعم البروتوكول الاتصال — حتى إن لم يكن هناك دليل رسمي أعلاه. 24 عميل موثّق، ويُضاف المزيد بانتظام.

تحقّق من إعدادك#

بعد الاتصال، جرّب طرح بضعة أسئلة على وكيلك:

  • "ما المستودعات المتصلة لديّ؟" — يتحقّق من أن الاتصال يعمل
  • "كيف تُعالَج المصادقة في قاعدة الكود هذه؟" — يختبر البحث الدلالي
  • "ابحث عن جميع الدوال التي تستدعي قاعدة البيانات" — يختبر بحث الاعتماديات
  • "على ماذا تعتمد فئة UserService؟" — يختبر البحث عن الرموز

يجب أن ترى نتائج تتضمن مسارات الملفات وأرقام الأسطر من مستودعك المتصل. إن لم يحدث ذلك، راجع troubleshooting section أدناه.

صيغة المستودع#

عند تحديد المستودعات:

  • مع تحديد الفرع: "owner/repo:branch" (e.g., "owner/repository:develop")
  • الفرع الافتراضي: "owner/repo"

تلميح: استخدم repository_context(action="info", repository="...") للتحقّق من كيفية حل المستودع. خادم v3 لا يحتفظ بالحالة، لذا فإن تجاوز المستودع يُنطبق على استدعاء واحد فقط.

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

مشكلات مفتاح API#

  • تحقّق من أن مفتاحك يبدأ بالبادئة mgv_
  • تحقّق من أن المفتاح مضبوط بشكل صحيح في بيئتك
  • تأكّد من أن المفتاح لم تنتهِ صلاحيته

المستودع غير موجود#

  • تحقّق من أن المستودع متصل في app.maguyva.ai
  • تحقّق من صحة صيغة owner/repo
  • تأكّد من أن لديك صلاحية الوصول إلى المستودع

مشكلات اتصال MCP#

  • تحقّق من توفر npx ضمن PATH لديك
  • تحقّق من أن رمز API الخاص بك صالح ولم تنتهِ صلاحيته
  • اختبر الاتصال بـ https://maguyva.tools/mcp
  • تحقّق من صيغة إعداد MCP الخاصة بعميلك

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