mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-04-10 21:12:37 +00:00
350 lines
10 KiB
Plaintext
350 lines
10 KiB
Plaintext
---
|
|
title: تكامل MCP DSL
|
|
description: تعلم كيفية استخدام صياغة DSL البسيطة في CrewAI لدمج خوادم MCP مباشرة مع وكلائك باستخدام حقل mcps.
|
|
icon: code
|
|
mode: "wide"
|
|
---
|
|
|
|
## نظرة عامة
|
|
|
|
يوفر تكامل MCP DSL (لغة المجال المحددة) في CrewAI **الطريقة الأبسط** لربط وكلائك بخوادم MCP (بروتوكول سياق النموذج). ما عليك سوى إضافة حقل `mcps` إلى وكيلك وسيتعامل CrewAI مع كل التعقيدات تلقائياً.
|
|
|
|
<Info>
|
|
هذا هو **النهج الموصى به** لمعظم حالات استخدام MCP. للسيناريوهات المتقدمة
|
|
التي تتطلب إدارة اتصال يدوية، راجع
|
|
[MCPServerAdapter](/ar/mcp/overview#advanced-mcpserveradapter).
|
|
</Info>
|
|
|
|
## الاستخدام الأساسي
|
|
|
|
أضف خوادم MCP إلى وكيلك باستخدام حقل `mcps`:
|
|
|
|
```python
|
|
from crewai import Agent
|
|
|
|
agent = Agent(
|
|
role="Research Assistant",
|
|
goal="Help with research and analysis tasks",
|
|
backstory="Expert assistant with access to advanced research tools",
|
|
mcps=[
|
|
"https://mcp.exa.ai/mcp?api_key=your_key&profile=research"
|
|
]
|
|
)
|
|
|
|
# MCP tools are now automatically available!
|
|
# No need for manual connection management or tool configuration
|
|
```
|
|
|
|
## تنسيقات المراجع المدعومة
|
|
|
|
### خوادم MCP البعيدة الخارجية
|
|
|
|
```python
|
|
# Basic HTTPS server
|
|
"https://api.example.com/mcp"
|
|
|
|
# Server with authentication
|
|
"https://mcp.exa.ai/mcp?api_key=your_key&profile=your_profile"
|
|
|
|
# Server with custom path
|
|
"https://services.company.com/api/v1/mcp"
|
|
```
|
|
|
|
### اختيار أدوات محددة
|
|
|
|
استخدم صياغة `#` لاختيار أدوات محددة من خادم:
|
|
|
|
```python
|
|
# Get only the forecast tool from weather server
|
|
"https://weather.api.com/mcp#get_forecast"
|
|
|
|
# Get only the search tool from Exa
|
|
"https://mcp.exa.ai/mcp?api_key=your_key#web_search_exa"
|
|
```
|
|
|
|
### تكاملات MCP المتصلة
|
|
|
|
اربط خوادم MCP من كتالوج CrewAI أو أحضر خوادمك الخاصة. بمجرد الاتصال في حسابك، أشر إليها بالمعرف المختصر:
|
|
|
|
```python
|
|
# Connected MCP with all tools
|
|
"snowflake"
|
|
|
|
# Specific tool from a connected MCP
|
|
"stripe#list_invoices"
|
|
|
|
# Multiple connected MCPs
|
|
mcps=[
|
|
"snowflake",
|
|
"stripe",
|
|
"github"
|
|
]
|
|
```
|
|
|
|
## مثال كامل
|
|
|
|
إليك مثالاً كاملاً يستخدم خوادم MCP متعددة:
|
|
|
|
```python
|
|
from crewai import Agent, Task, Crew, Process
|
|
|
|
# Create agent with multiple MCP sources
|
|
multi_source_agent = Agent(
|
|
role="Multi-Source Research Analyst",
|
|
goal="Conduct comprehensive research using multiple data sources",
|
|
backstory="""Expert researcher with access to web search, weather data,
|
|
financial information, and academic research tools""",
|
|
mcps=[
|
|
# External MCP servers
|
|
"https://mcp.exa.ai/mcp?api_key=your_exa_key&profile=research",
|
|
"https://weather.api.com/mcp#get_current_conditions",
|
|
|
|
# Connected MCPs from catalog
|
|
"snowflake",
|
|
"stripe#list_invoices",
|
|
"github#search_repositories"
|
|
]
|
|
)
|
|
|
|
# Create comprehensive research task
|
|
research_task = Task(
|
|
description="""Research the impact of AI agents on business productivity.
|
|
Include current weather impacts on remote work, financial market trends,
|
|
and recent academic publications on AI agent frameworks.""",
|
|
expected_output="""Comprehensive report covering:
|
|
1. AI agent business impact analysis
|
|
2. Weather considerations for remote work
|
|
3. Financial market trends related to AI
|
|
4. Academic research citations and insights
|
|
5. Competitive landscape analysis""",
|
|
agent=multi_source_agent
|
|
)
|
|
|
|
# Create and execute crew
|
|
research_crew = Crew(
|
|
agents=[multi_source_agent],
|
|
tasks=[research_task],
|
|
process=Process.sequential,
|
|
verbose=True
|
|
)
|
|
|
|
result = research_crew.kickoff()
|
|
print(f"Research completed with {len(multi_source_agent.mcps)} MCP data sources")
|
|
```
|
|
|
|
## تسمية الأدوات والتنظيم
|
|
|
|
يتعامل CrewAI تلقائياً مع تسمية الأدوات لمنع التعارضات:
|
|
|
|
```python
|
|
# Original MCP server has tools: "search", "analyze"
|
|
# CrewAI creates tools: "mcp_exa_ai_search", "mcp_exa_ai_analyze"
|
|
|
|
agent = Agent(
|
|
role="Tool Organization Demo",
|
|
goal="Show how tool naming works",
|
|
backstory="Demonstrates automatic tool organization",
|
|
mcps=[
|
|
"https://mcp.exa.ai/mcp?api_key=key", # Tools: mcp_exa_ai_*
|
|
"https://weather.service.com/mcp", # Tools: weather_service_com_*
|
|
"snowflake" # Tools: snowflake_*
|
|
]
|
|
)
|
|
|
|
# Each server's tools get unique prefixes based on the server name
|
|
# This prevents naming conflicts between different MCP servers
|
|
```
|
|
|
|
## معالجة الأخطاء والمرونة
|
|
|
|
صُمم MCP DSL ليكون متيناً وسهل الاستخدام:
|
|
|
|
### التعامل الأنيق مع فشل الخادم
|
|
|
|
```python
|
|
agent = Agent(
|
|
role="Resilient Researcher",
|
|
goal="Research despite server issues",
|
|
backstory="Experienced researcher who adapts to available tools",
|
|
mcps=[
|
|
"https://primary-server.com/mcp", # Primary data source
|
|
"https://backup-server.com/mcp", # Backup if primary fails
|
|
"https://unreachable-server.com/mcp", # Will be skipped with warning
|
|
"snowflake" # Connected MCP from catalog
|
|
]
|
|
)
|
|
|
|
# Agent will:
|
|
# 1. Successfully connect to working servers
|
|
# 2. Log warnings for failing servers
|
|
# 3. Continue with available tools
|
|
# 4. Not crash or hang on server failures
|
|
```
|
|
|
|
### حماية المهلة الزمنية
|
|
|
|
جميع عمليات MCP لها مهلات زمنية مدمجة:
|
|
|
|
- **مهلة الاتصال**: 10 ثوانٍ
|
|
- **مهلة تنفيذ الأداة**: 30 ثانية
|
|
- **مهلة الاكتشاف**: 15 ثانية
|
|
|
|
```python
|
|
# These servers will timeout gracefully if unresponsive
|
|
mcps=[
|
|
"https://slow-server.com/mcp", # Will timeout after 10s if unresponsive
|
|
"https://overloaded-api.com/mcp" # Will timeout if discovery takes > 15s
|
|
]
|
|
```
|
|
|
|
## ميزات الأداء
|
|
|
|
### التخزين المؤقت التلقائي
|
|
|
|
تُخزن مخططات الأدوات مؤقتاً لمدة 5 دقائق لتحسين الأداء:
|
|
|
|
```python
|
|
# First agent creation - discovers tools from server
|
|
agent1 = Agent(role="First", goal="Test", backstory="Test",
|
|
mcps=["https://api.example.com/mcp"])
|
|
|
|
# Second agent creation (within 5 minutes) - uses cached tool schemas
|
|
agent2 = Agent(role="Second", goal="Test", backstory="Test",
|
|
mcps=["https://api.example.com/mcp"]) # Much faster!
|
|
```
|
|
|
|
### الاتصالات حسب الطلب
|
|
|
|
تُنشأ اتصالات الأدوات فقط عند استخدام الأدوات فعلياً:
|
|
|
|
```python
|
|
# Agent creation is fast - no MCP connections made yet
|
|
agent = Agent(
|
|
role="On-Demand Agent",
|
|
goal="Use tools efficiently",
|
|
backstory="Efficient agent that connects only when needed",
|
|
mcps=["https://api.example.com/mcp"]
|
|
)
|
|
|
|
# MCP connection is made only when a tool is actually executed
|
|
# This minimizes connection overhead and improves startup performance
|
|
```
|
|
|
|
## التكامل مع الميزات الموجودة
|
|
|
|
تعمل أدوات MCP بسلاسة مع ميزات CrewAI الأخرى:
|
|
|
|
```python
|
|
from crewai.tools import BaseTool
|
|
|
|
class CustomTool(BaseTool):
|
|
name: str = "custom_analysis"
|
|
description: str = "Custom analysis tool"
|
|
|
|
def _run(self, **kwargs):
|
|
return "Custom analysis result"
|
|
|
|
agent = Agent(
|
|
role="Full-Featured Agent",
|
|
goal="Use all available tool types",
|
|
backstory="Agent with comprehensive tool access",
|
|
|
|
# All tool types work together
|
|
tools=[CustomTool()], # Custom tools
|
|
apps=["gmail", "slack"], # Platform integrations
|
|
mcps=[ # MCP servers
|
|
"https://mcp.exa.ai/mcp?api_key=key",
|
|
"snowflake"
|
|
],
|
|
|
|
verbose=True,
|
|
max_iter=15
|
|
)
|
|
```
|
|
|
|
## أفضل الممارسات
|
|
|
|
### 1. استخدم أدوات محددة عند الإمكان
|
|
|
|
```python
|
|
# Good - only get the tools you need
|
|
mcps=["https://weather.api.com/mcp#get_forecast"]
|
|
|
|
# Less efficient - gets all tools from server
|
|
mcps=["https://weather.api.com/mcp"]
|
|
```
|
|
|
|
### 2. تعامل مع المصادقة بأمان
|
|
|
|
```python
|
|
import os
|
|
|
|
# Store API keys in environment variables
|
|
exa_key = os.getenv("EXA_API_KEY")
|
|
exa_profile = os.getenv("EXA_PROFILE")
|
|
|
|
agent = Agent(
|
|
role="Secure Agent",
|
|
goal="Use MCP tools securely",
|
|
backstory="Security-conscious agent",
|
|
mcps=[f"https://mcp.exa.ai/mcp?api_key={exa_key}&profile={exa_profile}"]
|
|
)
|
|
```
|
|
|
|
### 3. خطط لفشل الخادم
|
|
|
|
```python
|
|
# Always include backup options
|
|
mcps=[
|
|
"https://primary-api.com/mcp", # Primary choice
|
|
"https://backup-api.com/mcp", # Backup option
|
|
"snowflake" # Connected MCP fallback
|
|
]
|
|
```
|
|
|
|
### 4. استخدم أدواراً وصفية للوكلاء
|
|
|
|
```python
|
|
agent = Agent(
|
|
role="Weather-Enhanced Market Analyst",
|
|
goal="Analyze markets considering weather impacts",
|
|
backstory="Financial analyst with access to weather data for agricultural market insights",
|
|
mcps=[
|
|
"https://weather.service.com/mcp#get_forecast",
|
|
"stripe#list_invoices"
|
|
]
|
|
)
|
|
```
|
|
|
|
## استكشاف الأخطاء وإصلاحها
|
|
|
|
### المشاكل الشائعة
|
|
|
|
**لم يتم اكتشاف أدوات:**
|
|
|
|
```python
|
|
# Check your MCP server URL and authentication
|
|
# Verify the server is running and accessible
|
|
mcps=["https://mcp.example.com/mcp?api_key=valid_key"]
|
|
```
|
|
|
|
**انتهاء مهلة الاتصال:**
|
|
|
|
```python
|
|
# Server may be slow or overloaded
|
|
# CrewAI will log warnings and continue with other servers
|
|
# Check server status or try backup servers
|
|
```
|
|
|
|
**فشل المصادقة:**
|
|
|
|
```python
|
|
# Verify API keys and credentials
|
|
# Check server documentation for required parameters
|
|
# Ensure query parameters are properly URL encoded
|
|
```
|
|
|
|
## متقدم: MCPServerAdapter
|
|
|
|
للسيناريوهات المعقدة التي تتطلب إدارة اتصال يدوية، استخدم فئة `MCPServerAdapter` من `crewai-tools`. استخدام مدير سياق Python (تعليمة `with`) هو النهج الموصى به لأنه يتعامل تلقائياً مع بدء وإيقاف الاتصال بخادم MCP.
|