mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-05-01 07:13:00 +00:00
docs: add modern standard arabic translation of all documentation
This commit is contained in:
Greyson LaLonde
349
docs/ar/mcp/dsl-integration.mdx
Normal file
349
docs/ar/mcp/dsl-integration.mdx
Normal file
@@ -0,0 +1,349 @@
|
||||
---
|
||||
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.
|
||||
65
docs/ar/mcp/multiple-servers.mdx
Normal file
65
docs/ar/mcp/multiple-servers.mdx
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: الاتصال بخوادم MCP متعددة
|
||||
description: تعلم كيفية استخدام MCPServerAdapter في CrewAI للاتصال بخوادم MCP متعددة بشكل متزامن وتجميع أدواتها.
|
||||
icon: layer-group
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## نظرة عامة
|
||||
|
||||
يتيح لك `MCPServerAdapter` في `crewai-tools` الاتصال بخوادم MCP متعددة بشكل متزامن. هذا مفيد عندما يحتاج وكلاؤك للوصول إلى أدوات موزعة عبر خدمات أو بيئات مختلفة. يجمع المحول الأدوات من جميع الخوادم المحددة، مما يجعلها متاحة لوكلاء CrewAI.
|
||||
|
||||
## الإعداد
|
||||
|
||||
للاتصال بخوادم متعددة، توفر قائمة من قواميس معاملات الخادم لـ `MCPServerAdapter`. يجب أن يعرّف كل قاموس في القائمة معاملات خادم MCP واحد.
|
||||
|
||||
تتضمن أنواع النقل المدعومة لكل خادم في القائمة `stdio` و `sse` و `streamable-http`.
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai_tools import MCPServerAdapter
|
||||
from mcp import StdioServerParameters # Needed for Stdio example
|
||||
|
||||
# Define parameters for multiple MCP servers
|
||||
server_params_list = [
|
||||
# Streamable HTTP Server
|
||||
{
|
||||
"url": "http://localhost:8001/mcp",
|
||||
"transport": "streamable-http"
|
||||
},
|
||||
# SSE Server
|
||||
{
|
||||
"url": "http://localhost:8000/sse",
|
||||
"transport": "sse"
|
||||
},
|
||||
# StdIO Server
|
||||
StdioServerParameters(
|
||||
command="python3",
|
||||
args=["servers/your_stdio_server.py"],
|
||||
env={"UV_PYTHON": "3.12", **os.environ},
|
||||
)
|
||||
]
|
||||
|
||||
try:
|
||||
with MCPServerAdapter(server_params_list) as aggregated_tools:
|
||||
print(f"Available aggregated tools: {[tool.name for tool in aggregated_tools]}")
|
||||
|
||||
multi_server_agent = Agent(
|
||||
role="Versatile Assistant",
|
||||
goal="Utilize tools from local Stdio, remote SSE, and remote HTTP MCP servers.",
|
||||
backstory="An AI agent capable of leveraging a diverse set of tools from multiple sources.",
|
||||
tools=aggregated_tools, # All tools are available here
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
... # Your other agent, tasks, and crew code here
|
||||
|
||||
except Exception as e:
|
||||
print(f"Error connecting to or using multiple MCP servers (Managed): {e}")
|
||||
print("Ensure all MCP servers are running and accessible with correct configurations.")
|
||||
|
||||
```
|
||||
|
||||
## إدارة الاتصال
|
||||
|
||||
عند استخدام مدير السياق (تعليمة `with`)، يتعامل `MCPServerAdapter` مع دورة حياة جميع الاتصالات بخوادم MCP المُعدة (البدء والإيقاف). هذا يبسط إدارة الموارد ويضمن إغلاق جميع الاتصالات بشكل صحيح عند الخروج من السياق.
|
||||
690
docs/ar/mcp/overview.mdx
Normal file
690
docs/ar/mcp/overview.mdx
Normal file
@@ -0,0 +1,690 @@
|
||||
---
|
||||
title: "خوادم MCP كأدوات في CrewAI"
|
||||
description: "تعلم كيفية دمج خوادم MCP كأدوات في وكلاء CrewAI باستخدام مكتبة `crewai-tools`."
|
||||
icon: plug
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## نظرة عامة
|
||||
|
||||
يوفر [بروتوكول سياق النموذج](https://modelcontextprotocol.io/introduction) (MCP) طريقة موحدة لوكلاء الذكاء الاصطناعي لتوفير سياق لنماذج اللغة الكبيرة من خلال التواصل مع خدمات خارجية تُعرف بخوادم MCP.
|
||||
|
||||
يقدم CrewAI **نهجين** لتكامل MCP:
|
||||
|
||||
### تكامل DSL البسيط (الموصى به)
|
||||
|
||||
استخدم حقل `mcps` مباشرة على الوكلاء لتكامل سلس مع أدوات MCP. يدعم DSL كلاً من **المراجع النصية** (للإعداد السريع) و**الإعدادات المنظمة** (للتحكم الكامل).
|
||||
|
||||
#### المراجع النصية (إعداد سريع)
|
||||
|
||||
مثالية لخوادم HTTPS البعيدة وتكاملات MCP المتصلة من كتالوج CrewAI:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
|
||||
agent = Agent(
|
||||
role="Research Analyst",
|
||||
goal="Research and analyze information",
|
||||
backstory="Expert researcher with access to external tools",
|
||||
mcps=[
|
||||
"https://mcp.exa.ai/mcp?api_key=your_key", # External MCP server
|
||||
"https://api.weather.com/mcp#get_forecast", # Specific tool from server
|
||||
"snowflake", # Connected MCP from catalog
|
||||
"stripe#list_invoices" # Specific tool from connected MCP
|
||||
]
|
||||
)
|
||||
# MCP tools are now automatically available to your agent!
|
||||
```
|
||||
|
||||
#### الإعدادات المنظمة (تحكم كامل)
|
||||
|
||||
للتحكم الكامل في إعدادات الاتصال وتصفية الأدوات وجميع أنواع النقل:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai.mcp import MCPServerStdio, MCPServerHTTP, MCPServerSSE
|
||||
from crewai.mcp.filters import create_static_tool_filter
|
||||
|
||||
agent = Agent(
|
||||
role="Advanced Research Analyst",
|
||||
goal="Research with full control over MCP connections",
|
||||
backstory="Expert researcher with advanced tool access",
|
||||
mcps=[
|
||||
# Stdio transport for local servers
|
||||
MCPServerStdio(
|
||||
command="npx",
|
||||
args=["-y", "@modelcontextprotocol/server-filesystem"],
|
||||
env={"API_KEY": "your_key"},
|
||||
tool_filter=create_static_tool_filter(
|
||||
allowed_tool_names=["read_file", "list_directory"]
|
||||
),
|
||||
cache_tools_list=True,
|
||||
),
|
||||
# HTTP/Streamable HTTP transport for remote servers
|
||||
MCPServerHTTP(
|
||||
url="https://api.example.com/mcp",
|
||||
headers={"Authorization": "Bearer your_token"},
|
||||
streamable=True,
|
||||
cache_tools_list=True,
|
||||
),
|
||||
# SSE transport for real-time streaming
|
||||
MCPServerSSE(
|
||||
url="https://stream.example.com/mcp/sse",
|
||||
headers={"Authorization": "Bearer your_token"},
|
||||
),
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
### متقدم: MCPServerAdapter (للسيناريوهات المعقدة)
|
||||
|
||||
لحالات الاستخدام المتقدمة التي تتطلب إدارة اتصال يدوية، توفر مكتبة `crewai-tools` فئة `MCPServerAdapter`.
|
||||
|
||||
ندعم حالياً آليات النقل التالية:
|
||||
|
||||
- **Stdio**: للخوادم المحلية (التواصل عبر الإدخال/الإخراج القياسي بين العمليات على نفس الجهاز)
|
||||
- **Server-Sent Events (SSE)**: للخوادم البعيدة (بث بيانات أحادي الاتجاه في الوقت الفعلي من الخادم إلى العميل عبر HTTP)
|
||||
- **Streamable HTTPS**: للخوادم البعيدة (اتصال مرن، ربما ثنائي الاتجاه عبر HTTPS، يستخدم غالباً SSE للتدفقات من الخادم إلى العميل)
|
||||
|
||||
## فيديو تعليمي
|
||||
|
||||
شاهد هذا الفيديو التعليمي للحصول على دليل شامل حول تكامل MCP مع CrewAI:
|
||||
|
||||
<iframe
|
||||
className="w-full aspect-video rounded-xl"
|
||||
src="https://www.youtube.com/embed/TpQ45lAZh48"
|
||||
title="CrewAI MCP Integration Guide"
|
||||
frameBorder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowFullScreen
|
||||
></iframe>
|
||||
|
||||
## التثبيت
|
||||
|
||||
يتطلب تكامل CrewAI MCP مكتبة `mcp`:
|
||||
|
||||
```shell
|
||||
# For Simple DSL Integration (Recommended)
|
||||
uv add mcp
|
||||
|
||||
# For Advanced MCPServerAdapter usage
|
||||
uv pip install 'crewai-tools[mcp]'
|
||||
```
|
||||
|
||||
## البدء السريع: تكامل DSL البسيط
|
||||
|
||||
أسهل طريقة لدمج خوادم MCP هي استخدام حقل `mcps` على وكلائك. يمكنك استخدام مراجع نصية أو إعدادات منظمة.
|
||||
|
||||
### البدء السريع مع المراجع النصية
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
|
||||
# Create agent with MCP tools using string references
|
||||
research_agent = Agent(
|
||||
role="Research Analyst",
|
||||
goal="Find and analyze information using advanced search tools",
|
||||
backstory="Expert researcher with access to multiple data sources",
|
||||
mcps=[
|
||||
"https://mcp.exa.ai/mcp?api_key=your_key&profile=your_profile",
|
||||
"snowflake#run_query"
|
||||
]
|
||||
)
|
||||
|
||||
# Create task
|
||||
research_task = Task(
|
||||
description="Research the latest developments in AI agent frameworks",
|
||||
expected_output="Comprehensive research report with citations",
|
||||
agent=research_agent
|
||||
)
|
||||
|
||||
# Create and run crew
|
||||
crew = Crew(agents=[research_agent], tasks=[research_task])
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
### البدء السريع مع الإعدادات المنظمة
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew
|
||||
from crewai.mcp import MCPServerStdio, MCPServerHTTP, MCPServerSSE
|
||||
|
||||
# Create agent with structured MCP configurations
|
||||
research_agent = Agent(
|
||||
role="Research Analyst",
|
||||
goal="Find and analyze information using advanced search tools",
|
||||
backstory="Expert researcher with access to multiple data sources",
|
||||
mcps=[
|
||||
# Local stdio server
|
||||
MCPServerStdio(
|
||||
command="python",
|
||||
args=["local_server.py"],
|
||||
env={"API_KEY": "your_key"},
|
||||
),
|
||||
# Remote HTTP server
|
||||
MCPServerHTTP(
|
||||
url="https://api.research.com/mcp",
|
||||
headers={"Authorization": "Bearer your_token"},
|
||||
),
|
||||
]
|
||||
)
|
||||
|
||||
# Create task
|
||||
research_task = Task(
|
||||
description="Research the latest developments in AI agent frameworks",
|
||||
expected_output="Comprehensive research report with citations",
|
||||
agent=research_agent
|
||||
)
|
||||
|
||||
# Create and run crew
|
||||
crew = Crew(agents=[research_agent], tasks=[research_task])
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
هذا كل شيء! يتم اكتشاف أدوات MCP تلقائياً وإتاحتها لوكيلك.
|
||||
|
||||
## تنسيقات مراجع MCP
|
||||
|
||||
يدعم حقل `mcps` كلاً من **المراجع النصية** (للإعداد السريع) و**الإعدادات المنظمة** (للتحكم الكامل). يمكنك مزج كلا التنسيقين في نفس القائمة.
|
||||
|
||||
### المراجع النصية
|
||||
|
||||
#### خوادم MCP الخارجية
|
||||
|
||||
```python
|
||||
mcps=[
|
||||
# Full server - get all available tools
|
||||
"https://mcp.example.com/api",
|
||||
|
||||
# Specific tool from server using # syntax
|
||||
"https://api.weather.com/mcp#get_current_weather",
|
||||
|
||||
# Server with authentication parameters
|
||||
"https://mcp.exa.ai/mcp?api_key=your_key&profile=your_profile"
|
||||
]
|
||||
```
|
||||
|
||||
#### تكاملات MCP المتصلة
|
||||
|
||||
اربط خوادم MCP من كتالوج CrewAI أو أحضر خوادمك الخاصة. بمجرد الاتصال في حسابك، أشر إليها بالمعرف المختصر:
|
||||
|
||||
```python
|
||||
mcps=[
|
||||
# Connected MCP - get all available tools
|
||||
"snowflake",
|
||||
|
||||
# Specific tool from a connected MCP using # syntax
|
||||
"stripe#list_invoices",
|
||||
|
||||
# Multiple connected MCPs
|
||||
"snowflake",
|
||||
"stripe",
|
||||
"github"
|
||||
]
|
||||
```
|
||||
|
||||
### الإعدادات المنظمة
|
||||
|
||||
#### نقل Stdio (خوادم محلية)
|
||||
|
||||
مثالي لخوادم MCP المحلية التي تعمل كعمليات:
|
||||
|
||||
```python
|
||||
from crewai.mcp import MCPServerStdio
|
||||
from crewai.mcp.filters import create_static_tool_filter
|
||||
|
||||
mcps=[
|
||||
MCPServerStdio(
|
||||
command="npx",
|
||||
args=["-y", "@modelcontextprotocol/server-filesystem"],
|
||||
env={"API_KEY": "your_key"},
|
||||
tool_filter=create_static_tool_filter(
|
||||
allowed_tool_names=["read_file", "write_file"]
|
||||
),
|
||||
cache_tools_list=True,
|
||||
),
|
||||
# Python-based server
|
||||
MCPServerStdio(
|
||||
command="python",
|
||||
args=["path/to/server.py"],
|
||||
env={"UV_PYTHON": "3.12", "API_KEY": "your_key"},
|
||||
),
|
||||
]
|
||||
```
|
||||
|
||||
#### نقل HTTP/Streamable HTTP (خوادم بعيدة)
|
||||
|
||||
لخوادم MCP البعيدة عبر HTTP/HTTPS:
|
||||
|
||||
```python
|
||||
from crewai.mcp import MCPServerHTTP
|
||||
|
||||
mcps=[
|
||||
# Streamable HTTP (default)
|
||||
MCPServerHTTP(
|
||||
url="https://api.example.com/mcp",
|
||||
headers={"Authorization": "Bearer your_token"},
|
||||
streamable=True,
|
||||
cache_tools_list=True,
|
||||
),
|
||||
# Standard HTTP
|
||||
MCPServerHTTP(
|
||||
url="https://api.example.com/mcp",
|
||||
headers={"Authorization": "Bearer your_token"},
|
||||
streamable=False,
|
||||
),
|
||||
]
|
||||
```
|
||||
|
||||
#### نقل SSE (البث في الوقت الفعلي)
|
||||
|
||||
للخوادم البعيدة التي تستخدم Server-Sent Events:
|
||||
|
||||
```python
|
||||
from crewai.mcp import MCPServerSSE
|
||||
|
||||
mcps=[
|
||||
MCPServerSSE(
|
||||
url="https://stream.example.com/mcp/sse",
|
||||
headers={"Authorization": "Bearer your_token"},
|
||||
cache_tools_list=True,
|
||||
),
|
||||
]
|
||||
```
|
||||
|
||||
### مراجع مختلطة
|
||||
|
||||
يمكنك دمج المراجع النصية والإعدادات المنظمة:
|
||||
|
||||
```python
|
||||
from crewai.mcp import MCPServerStdio, MCPServerHTTP
|
||||
|
||||
mcps=[
|
||||
# String references
|
||||
"https://external-api.com/mcp", # External server
|
||||
"snowflake", # Connected MCP from catalog
|
||||
|
||||
# Structured configurations
|
||||
MCPServerStdio(
|
||||
command="npx",
|
||||
args=["-y", "@modelcontextprotocol/server-filesystem"],
|
||||
),
|
||||
MCPServerHTTP(
|
||||
url="https://api.example.com/mcp",
|
||||
headers={"Authorization": "Bearer token"},
|
||||
),
|
||||
]
|
||||
```
|
||||
|
||||
### تصفية الأدوات
|
||||
|
||||
تدعم الإعدادات المنظمة تصفية أدوات متقدمة:
|
||||
|
||||
```python
|
||||
from crewai.mcp import MCPServerStdio
|
||||
from crewai.mcp.filters import create_static_tool_filter, create_dynamic_tool_filter, ToolFilterContext
|
||||
|
||||
# Static filtering (allow/block lists)
|
||||
static_filter = create_static_tool_filter(
|
||||
allowed_tool_names=["read_file", "write_file"],
|
||||
blocked_tool_names=["delete_file"],
|
||||
)
|
||||
|
||||
# Dynamic filtering (context-aware)
|
||||
def dynamic_filter(context: ToolFilterContext, tool: dict) -> bool:
|
||||
# Block dangerous tools for certain agent roles
|
||||
if context.agent.role == "Code Reviewer":
|
||||
if "delete" in tool.get("name", "").lower():
|
||||
return False
|
||||
return True
|
||||
|
||||
mcps=[
|
||||
MCPServerStdio(
|
||||
command="npx",
|
||||
args=["-y", "@modelcontextprotocol/server-filesystem"],
|
||||
tool_filter=static_filter, # or dynamic_filter
|
||||
),
|
||||
]
|
||||
```
|
||||
|
||||
## معاملات الإعداد
|
||||
|
||||
يدعم كل نوع نقل خيارات إعداد محددة:
|
||||
|
||||
### معاملات MCPServerStdio
|
||||
|
||||
- **`command`** (مطلوب): الأمر المراد تنفيذه (مثل `"python"` أو `"node"` أو `"npx"` أو `"uvx"`)
|
||||
- **`args`** (اختياري): قائمة وسيطات الأمر (مثل `["server.py"]` أو `["-y", "@mcp/server"]`)
|
||||
- **`env`** (اختياري): قاموس متغيرات البيئة لتمريرها إلى العملية
|
||||
- **`tool_filter`** (اختياري): دالة تصفية الأدوات لتصفية الأدوات المتاحة
|
||||
- **`cache_tools_list`** (اختياري): ما إذا كان يجب تخزين قائمة الأدوات مؤقتاً لوصول أسرع لاحقاً (الافتراضي: `False`)
|
||||
|
||||
### معاملات MCPServerHTTP
|
||||
|
||||
- **`url`** (مطلوب): عنوان URL الخادم (مثل `"https://api.example.com/mcp"`)
|
||||
- **`headers`** (اختياري): قاموس رؤوس HTTP للمصادقة أو أغراض أخرى
|
||||
- **`streamable`** (اختياري): ما إذا كان يجب استخدام نقل HTTP القابل للبث (الافتراضي: `True`)
|
||||
- **`tool_filter`** (اختياري): دالة تصفية الأدوات لتصفية الأدوات المتاحة
|
||||
- **`cache_tools_list`** (اختياري): ما إذا كان يجب تخزين قائمة الأدوات مؤقتاً (الافتراضي: `False`)
|
||||
|
||||
### معاملات MCPServerSSE
|
||||
|
||||
- **`url`** (مطلوب): عنوان URL الخادم (مثل `"https://api.example.com/mcp/sse"`)
|
||||
- **`headers`** (اختياري): قاموس رؤوس HTTP للمصادقة أو أغراض أخرى
|
||||
- **`tool_filter`** (اختياري): دالة تصفية الأدوات لتصفية الأدوات المتاحة
|
||||
- **`cache_tools_list`** (اختياري): ما إذا كان يجب تخزين قائمة الأدوات مؤقتاً (الافتراضي: `False`)
|
||||
|
||||
### المعاملات المشتركة
|
||||
|
||||
تدعم جميع أنواع النقل:
|
||||
|
||||
- **`tool_filter`**: دالة تصفية للتحكم في الأدوات المتاحة. يمكن أن تكون:
|
||||
- `None` (الافتراضي): جميع الأدوات متاحة
|
||||
- تصفية ثابتة: تُنشأ باستخدام `create_static_tool_filter()` لقوائم السماح/الحظر
|
||||
- تصفية ديناميكية: تُنشأ باستخدام `create_dynamic_tool_filter()` للتصفية الواعية بالسياق
|
||||
- **`cache_tools_list`**: عند `True`، تخزن قائمة الأدوات مؤقتاً بعد أول اكتشاف لتحسين الأداء في الاتصالات اللاحقة
|
||||
|
||||
## الميزات الرئيسية
|
||||
|
||||
- **اكتشاف تلقائي للأدوات**: يتم اكتشاف الأدوات ودمجها تلقائياً
|
||||
- **منع تعارض الأسماء**: تُضاف بادئات أسماء الخوادم لأسماء الأدوات
|
||||
- **محسّن للأداء**: اتصالات حسب الطلب مع تخزين مؤقت للمخططات
|
||||
- **مرونة في الأخطاء**: تعامل أنيق مع الخوادم غير المتاحة
|
||||
- **حماية المهلة الزمنية**: مهلات زمنية مدمجة تمنع تعليق الاتصالات
|
||||
- **تكامل شفاف**: يعمل بسلاسة مع ميزات CrewAI الموجودة
|
||||
- **دعم نقل كامل**: أنواع نقل Stdio وHTTP/Streamable HTTP وSSE
|
||||
- **تصفية متقدمة**: قدرات تصفية أدوات ثابتة وديناميكية
|
||||
- **مصادقة مرنة**: دعم للرؤوس ومتغيرات البيئة ومعاملات الاستعلام
|
||||
|
||||
## معالجة الأخطاء
|
||||
|
||||
صُمم تكامل MCP DSL ليكون مرناً ويتعامل مع الفشل بأناقة:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai.mcp import MCPServerStdio, MCPServerHTTP
|
||||
|
||||
agent = Agent(
|
||||
role="Resilient Agent",
|
||||
goal="Continue working despite server issues",
|
||||
backstory="Agent that handles failures gracefully",
|
||||
mcps=[
|
||||
# String references
|
||||
"https://reliable-server.com/mcp", # Will work
|
||||
"https://unreachable-server.com/mcp", # Will be skipped gracefully
|
||||
"snowflake", # Connected MCP from catalog
|
||||
|
||||
# Structured configs
|
||||
MCPServerStdio(
|
||||
command="python",
|
||||
args=["reliable_server.py"], # Will work
|
||||
),
|
||||
MCPServerHTTP(
|
||||
url="https://slow-server.com/mcp", # Will timeout gracefully
|
||||
),
|
||||
]
|
||||
)
|
||||
# Agent will use tools from working servers and log warnings for failing ones
|
||||
```
|
||||
|
||||
جميع أخطاء الاتصال تُعالج بأناقة:
|
||||
|
||||
- **فشل الاتصال**: تُسجل كتحذيرات، ويستمر الوكيل مع الأدوات المتاحة
|
||||
- **أخطاء المهلة الزمنية**: تنتهي الاتصالات بعد 30 ثانية (قابلة للتعديل)
|
||||
- **أخطاء المصادقة**: تُسجل بوضوح للتصحيح
|
||||
- **إعدادات غير صالحة**: تُرفع أخطاء التحقق عند إنشاء الوكيل
|
||||
|
||||
## متقدم: MCPServerAdapter
|
||||
|
||||
للسيناريوهات المعقدة التي تتطلب إدارة اتصال يدوية، استخدم فئة `MCPServerAdapter` من `crewai-tools`. استخدام مدير سياق Python (تعليمة `with`) هو النهج الموصى به لأنه يتعامل تلقائياً مع بدء وإيقاف الاتصال بخادم MCP.
|
||||
|
||||
## إعداد الاتصال
|
||||
|
||||
يدعم `MCPServerAdapter` عدة خيارات إعداد لتخصيص سلوك الاتصال:
|
||||
|
||||
- **`connect_timeout`** (اختياري): الحد الأقصى للوقت بالثواني لانتظار إنشاء اتصال بخادم MCP. القيمة الافتراضية 30 ثانية إذا لم تُحدد. هذا مفيد بشكل خاص للخوادم البعيدة التي قد يكون لها أوقات استجابة متغيرة.
|
||||
|
||||
```python
|
||||
# Example with custom connection timeout
|
||||
with MCPServerAdapter(server_params, connect_timeout=60) as tools:
|
||||
# Connection will timeout after 60 seconds if not established
|
||||
pass
|
||||
```
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai_tools import MCPServerAdapter
|
||||
from mcp import StdioServerParameters # For Stdio Server
|
||||
|
||||
# Example server_params (choose one based on your server type):
|
||||
# 1. Stdio Server:
|
||||
server_params=StdioServerParameters(
|
||||
command="python3",
|
||||
args=["servers/your_server.py"],
|
||||
env={"UV_PYTHON": "3.12", **os.environ},
|
||||
)
|
||||
|
||||
# 2. SSE Server:
|
||||
server_params = {
|
||||
"url": "http://localhost:8000/sse",
|
||||
"transport": "sse"
|
||||
}
|
||||
|
||||
# 3. Streamable HTTP Server:
|
||||
server_params = {
|
||||
"url": "http://localhost:8001/mcp",
|
||||
"transport": "streamable-http"
|
||||
}
|
||||
|
||||
# Example usage (uncomment and adapt once server_params is set):
|
||||
with MCPServerAdapter(server_params, connect_timeout=60) as mcp_tools:
|
||||
print(f"Available tools: {[tool.name for tool in mcp_tools]}")
|
||||
|
||||
my_agent = Agent(
|
||||
role="MCP Tool User",
|
||||
goal="Utilize tools from an MCP server.",
|
||||
backstory="I can connect to MCP servers and use their tools.",
|
||||
tools=mcp_tools, # Pass the loaded tools to your agent
|
||||
reasoning=True,
|
||||
verbose=True
|
||||
)
|
||||
# ... rest of your crew setup ...
|
||||
```
|
||||
|
||||
يوضح هذا النمط العام كيفية دمج الأدوات. للحصول على أمثلة محددة مصممة لكل نوع نقل، راجع الأدلة التفصيلية أدناه.
|
||||
|
||||
## تصفية الأدوات
|
||||
|
||||
هناك طريقتان لتصفية الأدوات:
|
||||
|
||||
1. الوصول إلى أداة محددة باستخدام فهرسة نمط القاموس.
|
||||
2. تمرير قائمة أسماء الأدوات إلى منشئ `MCPServerAdapter`.
|
||||
|
||||
### الوصول إلى أداة محددة باستخدام فهرسة نمط القاموس.
|
||||
|
||||
```python
|
||||
with MCPServerAdapter(server_params, connect_timeout=60) as mcp_tools:
|
||||
print(f"Available tools: {[tool.name for tool in mcp_tools]}")
|
||||
|
||||
my_agent = Agent(
|
||||
role="MCP Tool User",
|
||||
goal="Utilize tools from an MCP server.",
|
||||
backstory="I can connect to MCP servers and use their tools.",
|
||||
tools=[mcp_tools["tool_name"]], # Pass the loaded tools to your agent
|
||||
reasoning=True,
|
||||
verbose=True
|
||||
)
|
||||
# ... rest of your crew setup ...
|
||||
```
|
||||
|
||||
### تمرير قائمة أسماء الأدوات إلى منشئ `MCPServerAdapter`.
|
||||
|
||||
```python
|
||||
with MCPServerAdapter(server_params, "tool_name", connect_timeout=60) as mcp_tools:
|
||||
print(f"Available tools: {[tool.name for tool in mcp_tools]}")
|
||||
|
||||
my_agent = Agent(
|
||||
role="MCP Tool User",
|
||||
goal="Utilize tools from an MCP server.",
|
||||
backstory="I can connect to MCP servers and use their tools.",
|
||||
tools=mcp_tools, # Pass the loaded tools to your agent
|
||||
reasoning=True,
|
||||
verbose=True
|
||||
)
|
||||
# ... rest of your crew setup ...
|
||||
```
|
||||
|
||||
## الاستخدام مع CrewBase
|
||||
|
||||
لاستخدام أدوات MCPServer ضمن فئة CrewBase، استخدم طريقة `get_mcp_tools`. يجب توفير إعدادات الخادم عبر خاصية `mcp_server_params`. يمكنك تمرير إعداد واحد أو قائمة من إعدادات خوادم متعددة.
|
||||
|
||||
```python
|
||||
@CrewBase
|
||||
class CrewWithMCP:
|
||||
# ... define your agents and tasks config file ...
|
||||
|
||||
mcp_server_params = [
|
||||
# Streamable HTTP Server
|
||||
{
|
||||
"url": "http://localhost:8001/mcp",
|
||||
"transport": "streamable-http"
|
||||
},
|
||||
# SSE Server
|
||||
{
|
||||
"url": "http://localhost:8000/sse",
|
||||
"transport": "sse"
|
||||
},
|
||||
# StdIO Server
|
||||
StdioServerParameters(
|
||||
command="python3",
|
||||
args=["servers/your_stdio_server.py"],
|
||||
env={"UV_PYTHON": "3.12", **os.environ},
|
||||
)
|
||||
]
|
||||
|
||||
@agent
|
||||
def your_agent(self):
|
||||
return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) # get all available tools
|
||||
|
||||
# ... rest of your crew setup ...
|
||||
```
|
||||
|
||||
<Tip>
|
||||
عندما تكون فئة الطاقم مزينة بـ `@CrewBase`، تُدار دورة حياة المحول نيابة عنك:
|
||||
|
||||
- أول استدعاء لـ `get_mcp_tools()` ينشئ بكسل `MCPServerAdapter` مشتركاً يُعاد استخدامه من قبل كل وكيل في الطاقم.
|
||||
- يُغلق المحول تلقائياً بعد اكتمال `.kickoff()` بفضل خطاف ما بعد التشغيل الضمني المحقون من `@CrewBase`، لذا لا حاجة للتنظيف اليدوي.
|
||||
- إذا لم يتم تعريف `mcp_server_params`، يُرجع `get_mcp_tools()` ببساطة قائمة فارغة، مما يسمح لنفس مسارات الكود بالعمل مع أو بدون إعداد MCP.
|
||||
|
||||
هذا يجعل من الآمن استدعاء `get_mcp_tools()` من طرق وكلاء متعددة أو تفعيل MCP بشكل انتقائي لكل بيئة.
|
||||
</Tip>
|
||||
|
||||
### إعداد مهلة الاتصال
|
||||
|
||||
يمكنك إعداد مهلة الاتصال لخوادم MCP عن طريق تعيين خاصية فئة `mcp_connect_timeout`. إذا لم تُحدد مهلة، تكون القيمة الافتراضية 30 ثانية.
|
||||
|
||||
```python
|
||||
@CrewBase
|
||||
class CrewWithMCP:
|
||||
mcp_server_params = [...]
|
||||
mcp_connect_timeout = 60 # 60 seconds timeout for all MCP connections
|
||||
|
||||
@agent
|
||||
def your_agent(self):
|
||||
return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools())
|
||||
```
|
||||
|
||||
### تصفية الأدوات
|
||||
|
||||
يمكنك تصفية الأدوات المتاحة لوكيلك عن طريق تمرير قائمة أسماء الأدوات إلى طريقة `get_mcp_tools`.
|
||||
|
||||
```python
|
||||
@agent
|
||||
def another_agent(self):
|
||||
return Agent(
|
||||
config=self.agents_config["your_agent"],
|
||||
tools=self.get_mcp_tools("tool_1", "tool_2") # get specific tools
|
||||
)
|
||||
```
|
||||
|
||||
## استكشاف تكاملات MCP
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="تكامل DSL البسيط"
|
||||
icon="code"
|
||||
href="/ar/mcp/dsl-integration"
|
||||
color="#3B82F6"
|
||||
>
|
||||
**الموصى به**: استخدم صياغة حقل `mcps=[]` البسيطة لتكامل MCP بلا جهد.
|
||||
</Card>
|
||||
<Card
|
||||
title="نقل Stdio"
|
||||
icon="server"
|
||||
href="/ar/mcp/stdio"
|
||||
color="#10B981"
|
||||
>
|
||||
الاتصال بخوادم MCP المحلية عبر الإدخال/الإخراج القياسي. مثالي للنصوص البرمجية والملفات التنفيذية المحلية.
|
||||
</Card>
|
||||
<Card title="نقل SSE" icon="wifi" href="/ar/mcp/sse" color="#F59E0B">
|
||||
التكامل مع خوادم MCP البعيدة باستخدام Server-Sent Events لبث البيانات في الوقت الفعلي.
|
||||
</Card>
|
||||
<Card
|
||||
title="نقل Streamable HTTP"
|
||||
icon="globe"
|
||||
href="/ar/mcp/streamable-http"
|
||||
color="#8B5CF6"
|
||||
>
|
||||
استخدام Streamable HTTP المرن للاتصال القوي مع خوادم MCP البعيدة.
|
||||
</Card>
|
||||
<Card
|
||||
title="الاتصال بخوادم متعددة"
|
||||
icon="layer-group"
|
||||
href="/ar/mcp/multiple-servers"
|
||||
color="#EF4444"
|
||||
>
|
||||
تجميع الأدوات من عدة خوادم MCP بشكل متزامن باستخدام محول واحد.
|
||||
</Card>
|
||||
<Card
|
||||
title="اعتبارات الأمان"
|
||||
icon="lock"
|
||||
href="/ar/mcp/security"
|
||||
color="#DC2626"
|
||||
>
|
||||
مراجعة أفضل ممارسات الأمان المهمة لتكامل MCP للحفاظ على سلامة وكلائك.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
تحقق من هذا المستودع للحصول على عروض وأمثلة كاملة لتكامل MCP مع CrewAI!
|
||||
|
||||
<Card
|
||||
title="GitHub Repository"
|
||||
icon="github"
|
||||
href="https://github.com/tonykipkemboi/crewai-mcp-demo"
|
||||
target="_blank"
|
||||
>
|
||||
CrewAI MCP Demo
|
||||
</Card>
|
||||
|
||||
## البقاء آمناً مع MCP
|
||||
|
||||
<Warning>تأكد دائماً من أنك تثق بخادم MCP قبل استخدامه.</Warning>
|
||||
|
||||
#### تحذير أمني: هجمات إعادة ربط DNS
|
||||
|
||||
يمكن أن تكون عمليات نقل SSE عرضة لهجمات إعادة ربط DNS إذا لم تكن مؤمنة بشكل صحيح.
|
||||
لمنع ذلك:
|
||||
|
||||
1. **تحقق دائماً من رؤوس Origin** على اتصالات SSE الواردة للتأكد من أنها تأتي من مصادر متوقعة
|
||||
2. **تجنب ربط الخوادم بجميع واجهات الشبكة** (0.0.0.0) عند التشغيل محلياً - اربط فقط بـ localhost (127.0.0.1) بدلاً من ذلك
|
||||
3. **نفّذ مصادقة مناسبة** لجميع اتصالات SSE
|
||||
|
||||
بدون هذه الحمايات، يمكن للمهاجمين استخدام إعادة ربط DNS للتفاعل مع خوادم MCP المحلية من مواقع ويب بعيدة.
|
||||
|
||||
لمزيد من التفاصيل، راجع [وثائق أمان نقل MCP من Anthropic](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations).
|
||||
|
||||
### القيود
|
||||
|
||||
- **الأوليات المدعومة**: حالياً، يدعم `MCPServerAdapter` بشكل أساسي تكييف `أدوات` MCP.
|
||||
لا يتم دمج أوليات MCP الأخرى مثل `prompts` أو `resources` مباشرة كمكونات CrewAI من خلال هذا المحول في هذا الوقت.
|
||||
- **معالجة المخرجات**: يعالج المحول عادةً المخرجات النصية الرئيسية من أداة MCP (مثل `.content[0].text`). قد تتطلب المخرجات المعقدة أو متعددة الوسائط معالجة مخصصة إذا لم تتناسب مع هذا النمط.
|
||||
149
docs/ar/mcp/security.mdx
Normal file
149
docs/ar/mcp/security.mdx
Normal file
@@ -0,0 +1,149 @@
|
||||
---
|
||||
title: اعتبارات أمان MCP
|
||||
description: تعرف على أفضل ممارسات الأمان المهمة عند دمج خوادم MCP مع وكلاء CrewAI.
|
||||
icon: lock
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## نظرة عامة
|
||||
|
||||
<Warning>
|
||||
الجانب الأكثر أهمية في أمان MCP هو **الثقة**. يجب أن تتصل فقط بخوادم MCP التي تثق بها **بالكامل**.
|
||||
</Warning>
|
||||
|
||||
عند دمج خدمات خارجية مثل خوادم MCP (بروتوكول سياق النموذج) في وكلاء CrewAI، يكون الأمان أمراً بالغ الأهمية.
|
||||
يمكن لخوادم MCP تنفيذ التعليمات البرمجية والوصول إلى البيانات أو التفاعل مع أنظمة أخرى بناءً على الأدوات التي تكشفها.
|
||||
من الضروري فهم الآثار واتباع أفضل الممارسات لحماية تطبيقاتك وبياناتك.
|
||||
|
||||
### المخاطر
|
||||
|
||||
- تنفيذ تعليمات برمجية عشوائية على الجهاز الذي يعمل عليه الوكيل (خاصة مع نقل `Stdio` إذا كان الخادم يمكنه التحكم في الأمر المُنفذ).
|
||||
- كشف بيانات حساسة من وكيلك أو بيئته.
|
||||
- التلاعب بسلوك وكيلك بطرق غير مقصودة، بما في ذلك إجراء استدعاءات API غير مصرح بها نيابة عنك.
|
||||
- اختطاف عملية استدلال وكيلك من خلال تقنيات حقن المطالبات المتطورة (انظر أدناه).
|
||||
|
||||
### 1. الثقة بخوادم MCP
|
||||
|
||||
<Warning>
|
||||
**اتصل فقط بخوادم MCP التي تثق بها.**
|
||||
</Warning>
|
||||
|
||||
قبل إعداد `MCPServerAdapter` للاتصال بخادم MCP، تأكد من معرفة:
|
||||
- **من يشغل الخادم؟** هل هو خدمة معروفة وذات سمعة جيدة، أم خادم داخلي تحت سيطرتك؟
|
||||
- **ما الأدوات التي يكشفها؟** افهم قدرات الأدوات. هل يمكن إساءة استخدامها إذا سيطر مهاجم أو إذا كان الخادم نفسه خبيثاً؟
|
||||
- **ما البيانات التي يصل إليها أو يعالجها؟** كن على دراية بأي معلومات حساسة قد تُرسل إلى خادم MCP أو يتعامل معها.
|
||||
|
||||
تجنب الاتصال بخوادم MCP غير معروفة أو غير موثقة، خاصة إذا كان وكلاؤك يتعاملون مع مهام أو بيانات حساسة.
|
||||
|
||||
### 2. حقن المطالبات الآمن عبر بيانات الأداة الوصفية: خطر "بروتوكول التحكم بالنموذج"
|
||||
|
||||
خطر كبير وخفي هو إمكانية حقن المطالبات عبر البيانات الوصفية للأداة. إليك كيف يعمل:
|
||||
|
||||
1. عندما يتصل وكيل CrewAI بخادم MCP، يطلب عادةً قائمة الأدوات المتاحة.
|
||||
2. يستجيب خادم MCP ببيانات وصفية لكل أداة، بما في ذلك اسمها ووصفها وأوصاف معاملاتها.
|
||||
3. يستخدم نموذج اللغة (LLM) الأساسي لوكيلك هذه البيانات الوصفية لفهم كيف ومتى يستخدم الأدوات.
|
||||
4. يمكن لخادم MCP خبيث صياغة بياناته الوصفية للأدوات لتتضمن تعليمات مخفية أو صريحة تعمل كحقن مطالبات.
|
||||
|
||||
**الأهم، يمكن أن يحدث هذا الهجوم بمجرد الاتصال بخادم خبيث وسرد أدواته، حتى لو لم يقرر وكيلك *استخدام* أي من تلك الأدوات.** مجرد التعرض للبيانات الوصفية الخبيثة يمكن أن يكون كافياً لاختراق سلوك الوكيل.
|
||||
|
||||
**التخفيف:**
|
||||
|
||||
* **الحذر الشديد مع الخوادم غير الموثوقة:** نكرر: *لا تتصل بخوادم MCP لا تثق بها بالكامل.* يجعل خطر حقن البيانات الوصفية هذا أمراً بالغ الأهمية.
|
||||
|
||||
### أمان نقل Stdio
|
||||
|
||||
عادةً ما يُستخدم نقل Stdio (الإدخال/الإخراج القياسي) لخوادم MCP المحلية التي تعمل على نفس الجهاز مثل تطبيق CrewAI.
|
||||
|
||||
- **عزل العملية**: على الرغم من أنه أكثر أماناً بشكل عام لأنه لا يتضمن تعرض شبكي افتراضياً، تأكد من أن النص البرمجي أو الأمر الذي يُشغله `StdioServerParameters` من مصدر موثوق ولديه أذونات نظام ملفات مناسبة.
|
||||
- **تنقية المدخلات**: إذا كان نص Stdio البرمجي يأخذ مدخلات معقدة مشتقة من تفاعلات الوكيل، تأكد من أن النص ينقي هذه المدخلات لمنع حقن الأوامر أو الثغرات الأخرى.
|
||||
- **حدود الموارد**: كن على دراية بأن عملية خادم Stdio المحلية تستهلك موارد محلية (CPU، الذاكرة). تأكد من أنها تعمل بشكل جيد ولن تستنفد موارد النظام.
|
||||
|
||||
### هجمات الوكيل المرتبك
|
||||
|
||||
[مشكلة الوكيل المرتبك](https://en.wikipedia.org/wiki/Confused_deputy_problem) هي ثغرة أمنية كلاسيكية يمكن أن تظهر في تكاملات MCP، خاصة عندما يعمل خادم MCP كوسيط لخدمات طرف ثالث (مثل Google Calendar وGitHub) التي تستخدم OAuth 2.0 للترخيص.
|
||||
|
||||
**السيناريو:**
|
||||
|
||||
1. خادم MCP (نسميه `MCP-Proxy`) يسمح لوكيلك بالتفاعل مع `ThirdPartyAPI`.
|
||||
2. يستخدم `MCP-Proxy` `client_id` ثابتاً واحداً خاصاً به عند التحدث مع خادم ترخيص `ThirdPartyAPI`.
|
||||
3. أنت، كمستخدم، تصرح بشكل شرعي لـ `MCP-Proxy` بالوصول إلى `ThirdPartyAPI` نيابة عنك.
|
||||
4. يصنع مهاجم رابطاً خبيثاً يبدأ تدفق OAuth مع `MCP-Proxy`، لكنه مصمم لخداع خادم ترخيص `ThirdPartyAPI`.
|
||||
5. إذا نقرت على هذا الرابط، وشاهد خادم ترخيص `ThirdPartyAPI` ملف تعريف ارتباط الموافقة الموجود لـ `client_id` الخاص بـ `MCP-Proxy`، فقد *يتخطى* طلب موافقتك مرة أخرى.
|
||||
6. قد يُخدع `MCP-Proxy` بعد ذلك لتمرير رمز ترخيص إلى المهاجم.
|
||||
|
||||
**التخفيف (بشكل أساسي لمطوري خوادم MCP):**
|
||||
|
||||
* يجب على خوادم MCP الوسيطة التي تستخدم معرفات عميل ثابتة للخدمات النهائية الحصول على **موافقة صريحة من المستخدم** لكل تطبيق عميل أو وكيل يتصل بها قبل بدء تدفق OAuth.
|
||||
|
||||
**تداعيات مستخدم CrewAI:**
|
||||
|
||||
* كن حذراً إذا أعاد خادم MCP توجيهك لمصادقات OAuth متعددة، خاصة إذا بدت غير متوقعة أو كانت الأذونات المطلوبة واسعة جداً.
|
||||
|
||||
### أمان النقل البعيد (SSE و Streamable HTTP)
|
||||
|
||||
عند الاتصال بخوادم MCP البعيدة عبر SSE أو Streamable HTTP، فإن ممارسات أمان الويب القياسية ضرورية.
|
||||
|
||||
### اعتبارات أمان SSE
|
||||
|
||||
### أ. هجمات إعادة ربط DNS (خاصة لـ SSE)
|
||||
|
||||
<Critical>
|
||||
**احمِ ضد هجمات إعادة ربط DNS.**
|
||||
</Critical>
|
||||
|
||||
تسمح إعادة ربط DNS لموقع ويب يتحكم فيه مهاجم بتجاوز سياسة نفس الأصل وإجراء طلبات لخوادم على شبكة المستخدم المحلية.
|
||||
|
||||
**استراتيجيات التخفيف لمنفذي خوادم MCP:**
|
||||
- **تحقق من رؤوس `Origin` و `Host`**: يجب على خوادم MCP (خاصة SSE) التحقق من رؤوس HTTP لضمان أن الطلبات تأتي من نطاقات/عملاء متوقعين.
|
||||
- **اربط بـ `localhost` (127.0.0.1)**: عند تشغيل خوادم MCP محلياً للتطوير، اربطها بـ `127.0.0.1` بدلاً من `0.0.0.0`.
|
||||
- **المصادقة**: اطلب مصادقة لجميع الاتصالات بخادم MCP.
|
||||
|
||||
### ب. استخدم HTTPS
|
||||
|
||||
- **تشفير البيانات أثناء النقل**: استخدم دائماً HTTPS لعناوين URL خوادم MCP البعيدة لتشفير الاتصال.
|
||||
|
||||
### ج. تمرير الرمز (نمط مضاد)
|
||||
|
||||
هذا يتعلق بشكل أساسي بمطوري خوادم MCP لكن فهمه يساعد في اختيار خوادم آمنة.
|
||||
|
||||
"تمرير الرمز" هو عندما يقبل خادم MCP رمز وصول من وكيل CrewAI ويمرره ببساطة إلى API آخر بدون تحقق مناسب.
|
||||
|
||||
**المخاطر:**
|
||||
* يتجاوز ضوابط الأمان على خادم MCP أو API النهائي.
|
||||
* يكسر مسارات التدقيق والمساءلة.
|
||||
* يسمح بإساءة استخدام الرموز المسروقة.
|
||||
|
||||
### د. التحقق من المدخلات وتنقيتها
|
||||
|
||||
- **التحقق من المدخلات أمر بالغ الأهمية**: يجب على خوادم MCP التحقق بصرامة من جميع المدخلات المستلمة من الوكلاء *قبل* معالجتها أو تمريرها إلى الأدوات. هذا دفاع أساسي ضد العديد من الثغرات الشائعة:
|
||||
- **حقن الأوامر:** إذا كانت أداة تبني أوامر shell أو استعلامات SQL بناءً على المدخلات، يجب على الخادم تنقية هذه المدخلات بدقة.
|
||||
- **اجتياز المسار:** إذا وصلت أداة إلى ملفات بناءً على معاملات المدخلات، يجب على الخادم التحقق من هذه المسارات وتنقيتها.
|
||||
- **فحوصات نوع البيانات والنطاق:** يجب أن تضمن الخوادم توافق البيانات مع الأنواع والنطاقات المتوقعة.
|
||||
|
||||
### هـ. تحديد المعدل وإدارة الموارد
|
||||
|
||||
- **منع الإساءة**: يجب أن تنفذ خوادم MCP تحديد المعدل لمنع الإساءة.
|
||||
- **إعادة المحاولة من جانب العميل**: نفّذ منطق إعادة محاولة معقول في مهام CrewAI.
|
||||
|
||||
## 4. نصائح لتنفيذ خادم MCP آمن (للمطورين)
|
||||
|
||||
إذا كنت تطور خادم MCP قد تتصل به وكلاء CrewAI، ضع في الاعتبار أفضل الممارسات التالية:
|
||||
|
||||
- **اتبع ممارسات البرمجة الآمنة**: التزم بمبادئ البرمجة الآمنة القياسية (مثل OWASP Top 10).
|
||||
- **مبدأ الحد الأدنى من الصلاحيات**: تأكد من أن العملية التي تشغل خادم MCP لديها فقط الأذونات اللازمة.
|
||||
- **إدارة الاعتماديات**: حافظ على تحديث جميع الاعتماديات لتصحيح الثغرات المعروفة.
|
||||
- **الإعدادات الافتراضية الآمنة**: صمم خادمك وأدواته لتكون آمنة افتراضياً.
|
||||
- **التحكم في الوصول للأدوات**: نفّذ آليات قوية للتحكم في الوكلاء أو المستخدمين المصرح لهم بالوصول إلى أدوات محددة.
|
||||
- **معالجة أخطاء آمنة**: يجب ألا تكشف الخوادم رسائل خطأ داخلية مفصلة أو تتبعات المكدس للعميل.
|
||||
- **التسجيل والمراقبة الشاملة**: نفّذ تسجيلاً مفصلاً للأحداث المتعلقة بالأمان.
|
||||
- **الالتزام بمواصفات ترخيص MCP**: إذا كنت تنفذ المصادقة والترخيص، اتبع بدقة [مواصفات ترخيص MCP](https://modelcontextprotocol.io/specification/draft/basic/authorization).
|
||||
- **تدقيقات أمنية منتظمة**: إذا كان خادم MCP يتعامل مع بيانات حساسة، فكر في إجراء تدقيقات أمنية دورية.
|
||||
|
||||
## 5. قراءة إضافية
|
||||
|
||||
لمزيد من المعلومات التفصيلية حول أمان MCP، راجع التوثيق الرسمي:
|
||||
- **[أمان نقل MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations)**
|
||||
|
||||
من خلال فهم اعتبارات الأمان هذه وتنفيذ أفضل الممارسات، يمكنك الاستفادة بأمان من قوة خوادم MCP في مشاريع CrewAI.
|
||||
هذه ليست شاملة بأي حال، لكنها تغطي المخاوف الأمنية الأكثر شيوعاً وأهمية.
|
||||
ستستمر التهديدات في التطور، لذا من المهم البقاء على اطلاع وتكييف إجراءات الأمان وفقاً لذلك.
|
||||
151
docs/ar/mcp/sse.mdx
Normal file
151
docs/ar/mcp/sse.mdx
Normal file
@@ -0,0 +1,151 @@
|
||||
---
|
||||
title: نقل SSE
|
||||
description: تعلم كيفية ربط CrewAI بخوادم MCP البعيدة باستخدام Server-Sent Events (SSE) للاتصال في الوقت الفعلي.
|
||||
icon: wifi
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## نظرة عامة
|
||||
|
||||
توفر Server-Sent Events (SSE) طريقة قياسية لخادم الويب لإرسال تحديثات إلى العميل عبر اتصال HTTP واحد طويل الأمد. في سياق MCP، تُستخدم SSE للخوادم البعيدة لبث البيانات (مثل استجابات الأدوات) إلى تطبيق CrewAI في الوقت الفعلي.
|
||||
|
||||
## المفاهيم الرئيسية
|
||||
|
||||
- **خوادم بعيدة**: SSE مناسب لخوادم MCP المستضافة عن بُعد.
|
||||
- **بث أحادي الاتجاه**: عادةً ما يكون SSE قناة اتصال أحادية الاتجاه من الخادم إلى العميل.
|
||||
- **إعداد `MCPServerAdapter`**: لـ SSE، ستوفر عنوان URL الخادم وتحدد نوع النقل.
|
||||
|
||||
## الاتصال عبر SSE
|
||||
|
||||
يمكنك الاتصال بخادم MCP المبني على SSE باستخدام نهجين رئيسيين لإدارة دورة حياة الاتصال:
|
||||
|
||||
### 1. اتصال مُدار بالكامل (الموصى به)
|
||||
|
||||
استخدام مدير سياق Python (تعليمة `with`) هو النهج الموصى به. يتعامل تلقائياً مع إنشاء وإغلاق الاتصال بخادم MCP SSE.
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai_tools import MCPServerAdapter
|
||||
|
||||
server_params = {
|
||||
"url": "http://localhost:8000/sse", # Replace with your actual SSE server URL
|
||||
"transport": "sse"
|
||||
}
|
||||
|
||||
# Using MCPServerAdapter with a context manager
|
||||
try:
|
||||
with MCPServerAdapter(server_params) as tools:
|
||||
print(f"Available tools from SSE MCP server: {[tool.name for tool in tools]}")
|
||||
|
||||
# Example: Using a tool from the SSE MCP server
|
||||
sse_agent = Agent(
|
||||
role="Remote Service User",
|
||||
goal="Utilize a tool provided by a remote SSE MCP server.",
|
||||
backstory="An AI agent that connects to external services via SSE.",
|
||||
tools=tools,
|
||||
reasoning=True,
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
sse_task = Task(
|
||||
description="Fetch real-time stock updates for 'AAPL' using an SSE tool.",
|
||||
expected_output="The latest stock price for AAPL.",
|
||||
agent=sse_agent,
|
||||
markdown=True
|
||||
)
|
||||
|
||||
sse_crew = Crew(
|
||||
agents=[sse_agent],
|
||||
tasks=[sse_task],
|
||||
verbose=True,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
if tools: # Only kickoff if tools were loaded
|
||||
result = sse_crew.kickoff() # Add inputs={'stock_symbol': 'AAPL'} if tool requires it
|
||||
print("\nCrew Task Result (SSE - Managed):\n", result)
|
||||
else:
|
||||
print("Skipping crew kickoff as tools were not loaded (check server connection).")
|
||||
|
||||
except Exception as e:
|
||||
print(f"Error connecting to or using SSE MCP server (Managed): {e}")
|
||||
print("Ensure the SSE MCP server is running and accessible at the specified URL.")
|
||||
|
||||
```
|
||||
|
||||
<Note>
|
||||
استبدل `"http://localhost:8000/sse"` بعنوان URL الفعلي لخادم MCP SSE الخاص بك.
|
||||
</Note>
|
||||
|
||||
### 2. دورة حياة اتصال يدوية
|
||||
|
||||
إذا كنت بحاجة إلى تحكم أدق، يمكنك إدارة دورة حياة اتصال `MCPServerAdapter` يدوياً.
|
||||
|
||||
<Info>
|
||||
**يجب** عليك استدعاء `mcp_server_adapter.stop()` لضمان إغلاق الاتصال وتحرير الموارد. يُوصى بشدة باستخدام كتلة `try...finally`.
|
||||
</Info>
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai_tools import MCPServerAdapter
|
||||
|
||||
server_params = {
|
||||
"url": "http://localhost:8000/sse", # Replace with your actual SSE server URL
|
||||
"transport": "sse"
|
||||
}
|
||||
|
||||
mcp_server_adapter = None
|
||||
try:
|
||||
mcp_server_adapter = MCPServerAdapter(server_params)
|
||||
mcp_server_adapter.start()
|
||||
tools = mcp_server_adapter.tools
|
||||
print(f"Available tools (manual SSE): {[tool.name for tool in tools]}")
|
||||
|
||||
manual_sse_agent = Agent(
|
||||
role="Remote Data Analyst",
|
||||
goal="Analyze data fetched from a remote SSE MCP server using manual connection management.",
|
||||
backstory="An AI skilled in handling SSE connections explicitly.",
|
||||
tools=tools,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
analysis_task = Task(
|
||||
description="Fetch and analyze the latest user activity trends from the SSE server.",
|
||||
expected_output="A summary report of user activity trends.",
|
||||
agent=manual_sse_agent
|
||||
)
|
||||
|
||||
analysis_crew = Crew(
|
||||
agents=[manual_sse_agent],
|
||||
tasks=[analysis_task],
|
||||
verbose=True,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
result = analysis_crew.kickoff()
|
||||
print("\nCrew Task Result (SSE - Manual):\n", result)
|
||||
|
||||
except Exception as e:
|
||||
print(f"An error occurred during manual SSE MCP integration: {e}")
|
||||
print("Ensure the SSE MCP server is running and accessible.")
|
||||
finally:
|
||||
if mcp_server_adapter and mcp_server_adapter.is_connected:
|
||||
print("Stopping SSE MCP server connection (manual)...")
|
||||
mcp_server_adapter.stop() # **Crucial: Ensure stop is called**
|
||||
elif mcp_server_adapter:
|
||||
print("SSE MCP server adapter was not connected. No stop needed or start failed.")
|
||||
|
||||
```
|
||||
|
||||
## اعتبارات أمان SSE
|
||||
|
||||
<Warning>
|
||||
**هجمات إعادة ربط DNS**: يمكن أن تكون عمليات نقل SSE عرضة لهجمات إعادة ربط DNS إذا لم يكن خادم MCP مؤمناً بشكل صحيح. قد يسمح هذا لمواقع ويب خبيثة بالتفاعل مع خوادم MCP المحلية أو على الشبكة الداخلية.
|
||||
</Warning>
|
||||
|
||||
للتخفيف من هذا الخطر:
|
||||
- يجب أن تتحقق تطبيقات خادم MCP من **رؤوس `Origin`** على اتصالات SSE الواردة.
|
||||
- عند تشغيل خوادم MCP SSE محلية للتطوير، **اربط فقط بـ `localhost` (`127.0.0.1`)** بدلاً من جميع واجهات الشبكة (`0.0.0.0`).
|
||||
- نفّذ **مصادقة مناسبة** لجميع اتصالات SSE إذا كشفت أدوات أو بيانات حساسة.
|
||||
|
||||
للحصول على نظرة شاملة على أفضل ممارسات الأمان، يرجى الرجوع إلى صفحة [اعتبارات الأمان](./security.mdx) ووثائق [أمان نقل MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations) الرسمية.
|
||||
134
docs/ar/mcp/stdio.mdx
Normal file
134
docs/ar/mcp/stdio.mdx
Normal file
@@ -0,0 +1,134 @@
|
||||
---
|
||||
title: نقل Stdio
|
||||
description: تعلم كيفية ربط CrewAI بخوادم MCP المحلية باستخدام آلية نقل Stdio (الإدخال/الإخراج القياسي).
|
||||
icon: server
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## نظرة عامة
|
||||
|
||||
صُمم نقل Stdio (الإدخال/الإخراج القياسي) لربط `MCPServerAdapter` بخوادم MCP المحلية التي تتواصل عبر تدفقات الإدخال والإخراج القياسية. يُستخدم هذا عادةً عندما يكون خادم MCP نصاً برمجياً أو ملفاً تنفيذياً يعمل على نفس الجهاز مثل تطبيق CrewAI.
|
||||
|
||||
## المفاهيم الرئيسية
|
||||
|
||||
- **التنفيذ المحلي**: يدير نقل Stdio عملية تعمل محلياً لخادم MCP.
|
||||
- **`StdioServerParameters`**: تُستخدم هذه الفئة من مكتبة `mcp` لإعداد الأمر والوسيطات ومتغيرات البيئة لتشغيل خادم Stdio.
|
||||
|
||||
## الاتصال عبر Stdio
|
||||
|
||||
يمكنك الاتصال بخادم MCP المبني على Stdio باستخدام نهجين رئيسيين لإدارة دورة حياة الاتصال:
|
||||
|
||||
### 1. اتصال مُدار بالكامل (الموصى به)
|
||||
|
||||
استخدام مدير سياق Python (تعليمة `with`) هو النهج الموصى به. يتعامل تلقائياً مع بدء عملية خادم MCP وإيقافها عند الخروج من السياق.
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai_tools import MCPServerAdapter
|
||||
from mcp import StdioServerParameters
|
||||
import os
|
||||
|
||||
# Create a StdioServerParameters object
|
||||
server_params=StdioServerParameters(
|
||||
command="python3",
|
||||
args=["servers/your_stdio_server.py"],
|
||||
env={"UV_PYTHON": "3.12", **os.environ},
|
||||
)
|
||||
|
||||
with MCPServerAdapter(server_params) as tools:
|
||||
print(f"Available tools from Stdio MCP server: {[tool.name for tool in tools]}")
|
||||
|
||||
# Example: Using the tools from the Stdio MCP server in a CrewAI Agent
|
||||
research_agent = Agent(
|
||||
role="Local Data Processor",
|
||||
goal="Process data using a local Stdio-based tool.",
|
||||
backstory="An AI that leverages local scripts via MCP for specialized tasks.",
|
||||
tools=tools,
|
||||
reasoning=True,
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
processing_task = Task(
|
||||
description="Process the input data file 'data.txt' and summarize its contents.",
|
||||
expected_output="A summary of the processed data.",
|
||||
agent=research_agent,
|
||||
markdown=True
|
||||
)
|
||||
|
||||
data_crew = Crew(
|
||||
agents=[research_agent],
|
||||
tasks=[processing_task],
|
||||
verbose=True,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
result = data_crew.kickoff()
|
||||
print("\nCrew Task Result (Stdio - Managed):\n", result)
|
||||
|
||||
```
|
||||
|
||||
### 2. دورة حياة اتصال يدوية
|
||||
|
||||
إذا كنت بحاجة إلى تحكم أدق في وقت بدء وإيقاف عملية خادم MCP Stdio، يمكنك إدارة دورة حياة `MCPServerAdapter` يدوياً.
|
||||
|
||||
<Info>
|
||||
**يجب** عليك استدعاء `mcp_server_adapter.stop()` لضمان إنهاء عملية الخادم وتحرير الموارد. يُوصى بشدة باستخدام كتلة `try...finally`.
|
||||
</Info>
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai_tools import MCPServerAdapter
|
||||
from mcp import StdioServerParameters
|
||||
import os
|
||||
|
||||
# Create a StdioServerParameters object
|
||||
stdio_params=StdioServerParameters(
|
||||
command="python3",
|
||||
args=["servers/your_stdio_server.py"],
|
||||
env={"UV_PYTHON": "3.12", **os.environ},
|
||||
)
|
||||
|
||||
mcp_server_adapter = MCPServerAdapter(server_params=stdio_params)
|
||||
try:
|
||||
mcp_server_adapter.start() # Manually start the connection and server process
|
||||
tools = mcp_server_adapter.tools
|
||||
print(f"Available tools (manual Stdio): {[tool.name for tool in tools]}")
|
||||
|
||||
# Example: Using the tools with your Agent, Task, Crew setup
|
||||
manual_agent = Agent(
|
||||
role="Local Task Executor",
|
||||
goal="Execute a specific local task using a manually managed Stdio tool.",
|
||||
backstory="An AI proficient in controlling local processes via MCP.",
|
||||
tools=tools,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
manual_task = Task(
|
||||
description="Execute the 'perform_analysis' command via the Stdio tool.",
|
||||
expected_output="Results of the analysis.",
|
||||
agent=manual_agent
|
||||
)
|
||||
|
||||
manual_crew = Crew(
|
||||
agents=[manual_agent],
|
||||
tasks=[manual_task],
|
||||
verbose=True,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
|
||||
result = manual_crew.kickoff() # Actual inputs depend on your tool
|
||||
print("\nCrew Task Result (Stdio - Manual):\n", result)
|
||||
|
||||
except Exception as e:
|
||||
print(f"An error occurred during manual Stdio MCP integration: {e}")
|
||||
finally:
|
||||
if mcp_server_adapter and mcp_server_adapter.is_connected: # Check if connected before stopping
|
||||
print("Stopping Stdio MCP server connection (manual)...")
|
||||
mcp_server_adapter.stop() # **Crucial: Ensure stop is called**
|
||||
elif mcp_server_adapter: # If adapter exists but not connected (e.g. start failed)
|
||||
print("Stdio MCP server adapter was not connected. No stop needed or start failed.")
|
||||
|
||||
```
|
||||
|
||||
تذكر استبدال المسارات والأوامر النائبة بتفاصيل خادم Stdio الفعلية. يمكن استخدام معامل `env` في `StdioServerParameters` لتعيين متغيرات البيئة لعملية الخادم، وهو مفيد لإعداد سلوكها أو توفير المسارات اللازمة (مثل `PYTHONPATH`).
|
||||
136
docs/ar/mcp/streamable-http.mdx
Normal file
136
docs/ar/mcp/streamable-http.mdx
Normal file
@@ -0,0 +1,136 @@
|
||||
---
|
||||
title: نقل Streamable HTTP
|
||||
description: تعلم كيفية ربط CrewAI بخوادم MCP البعيدة باستخدام نقل Streamable HTTP المرن.
|
||||
icon: globe
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## نظرة عامة
|
||||
|
||||
يوفر نقل Streamable HTTP طريقة مرنة للاتصال بخوادم MCP البعيدة. يُبنى عادةً على HTTP ويمكنه دعم أنماط اتصال متنوعة، بما في ذلك الطلب والاستجابة والبث، وأحياناً يستخدم Server-Sent Events (SSE) لتدفقات من الخادم إلى العميل ضمن تفاعل HTTP أوسع.
|
||||
|
||||
## المفاهيم الرئيسية
|
||||
|
||||
- **خوادم بعيدة**: مصمم لخوادم MCP المستضافة عن بُعد.
|
||||
- **المرونة**: يمكنه دعم أنماط تفاعل أكثر تعقيداً من SSE العادي، بما في ذلك الاتصال ثنائي الاتجاه المحتمل إذا نفذه الخادم.
|
||||
- **إعداد `MCPServerAdapter`**: ستحتاج إلى توفير عنوان URL الأساسي للخادم للاتصال MCP وتحديد `"streamable-http"` كنوع النقل.
|
||||
|
||||
## الاتصال عبر Streamable HTTP
|
||||
|
||||
لديك طريقتان رئيسيتان لإدارة دورة حياة الاتصال مع خادم MCP Streamable HTTP:
|
||||
|
||||
### 1. اتصال مُدار بالكامل (الموصى به)
|
||||
|
||||
النهج الموصى به هو استخدام مدير سياق Python (تعليمة `with`)، الذي يتعامل مع إعداد الاتصال وإنهائه تلقائياً.
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai_tools import MCPServerAdapter
|
||||
|
||||
server_params = {
|
||||
"url": "http://localhost:8001/mcp", # Replace with your actual Streamable HTTP server URL
|
||||
"transport": "streamable-http"
|
||||
}
|
||||
|
||||
try:
|
||||
with MCPServerAdapter(server_params) as tools:
|
||||
print(f"Available tools from Streamable HTTP MCP server: {[tool.name for tool in tools]}")
|
||||
|
||||
http_agent = Agent(
|
||||
role="HTTP Service Integrator",
|
||||
goal="Utilize tools from a remote MCP server via Streamable HTTP.",
|
||||
backstory="An AI agent adept at interacting with complex web services.",
|
||||
tools=tools,
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
http_task = Task(
|
||||
description="Perform a complex data query using a tool from the Streamable HTTP server.",
|
||||
expected_output="The result of the complex data query.",
|
||||
agent=http_agent,
|
||||
)
|
||||
|
||||
http_crew = Crew(
|
||||
agents=[http_agent],
|
||||
tasks=[http_task],
|
||||
verbose=True,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
result = http_crew.kickoff()
|
||||
print("\nCrew Task Result (Streamable HTTP - Managed):\n", result)
|
||||
|
||||
except Exception as e:
|
||||
print(f"Error connecting to or using Streamable HTTP MCP server (Managed): {e}")
|
||||
print("Ensure the Streamable HTTP MCP server is running and accessible at the specified URL.")
|
||||
|
||||
```
|
||||
**ملاحظة:** استبدل `"http://localhost:8001/mcp"` بعنوان URL الفعلي لخادم MCP Streamable HTTP الخاص بك.
|
||||
|
||||
### 2. دورة حياة اتصال يدوية
|
||||
|
||||
للسيناريوهات التي تتطلب تحكماً أكثر صراحة، يمكنك إدارة اتصال `MCPServerAdapter` يدوياً.
|
||||
|
||||
<Info>
|
||||
من **الضروري** استدعاء `mcp_server_adapter.stop()` عند الانتهاء لإغلاق الاتصال وتحرير الموارد. كتلة `try...finally` هي الطريقة الأكثر أماناً لضمان ذلك.
|
||||
</Info>
|
||||
|
||||
```python
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai_tools import MCPServerAdapter
|
||||
|
||||
server_params = {
|
||||
"url": "http://localhost:8001/mcp", # Replace with your actual Streamable HTTP server URL
|
||||
"transport": "streamable-http"
|
||||
}
|
||||
|
||||
mcp_server_adapter = None
|
||||
try:
|
||||
mcp_server_adapter = MCPServerAdapter(server_params)
|
||||
mcp_server_adapter.start()
|
||||
tools = mcp_server_adapter.tools
|
||||
print(f"Available tools (manual Streamable HTTP): {[tool.name for tool in tools]}")
|
||||
|
||||
manual_http_agent = Agent(
|
||||
role="Advanced Web Service User",
|
||||
goal="Interact with an MCP server using manually managed Streamable HTTP connections.",
|
||||
backstory="An AI specialist in fine-tuning HTTP-based service integrations.",
|
||||
tools=tools,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
data_processing_task = Task(
|
||||
description="Submit data for processing and retrieve results via Streamable HTTP.",
|
||||
expected_output="Processed data or confirmation.",
|
||||
agent=manual_http_agent
|
||||
)
|
||||
|
||||
data_crew = Crew(
|
||||
agents=[manual_http_agent],
|
||||
tasks=[data_processing_task],
|
||||
verbose=True,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
result = data_crew.kickoff()
|
||||
print("\nCrew Task Result (Streamable HTTP - Manual):\n", result)
|
||||
|
||||
except Exception as e:
|
||||
print(f"An error occurred during manual Streamable HTTP MCP integration: {e}")
|
||||
print("Ensure the Streamable HTTP MCP server is running and accessible.")
|
||||
finally:
|
||||
if mcp_server_adapter and mcp_server_adapter.is_connected:
|
||||
print("Stopping Streamable HTTP MCP server connection (manual)...")
|
||||
mcp_server_adapter.stop() # **Crucial: Ensure stop is called**
|
||||
elif mcp_server_adapter:
|
||||
print("Streamable HTTP MCP server adapter was not connected. No stop needed or start failed.")
|
||||
```
|
||||
|
||||
## اعتبارات الأمان
|
||||
|
||||
عند استخدام نقل Streamable HTTP، فإن أفضل ممارسات أمان الويب العامة ضرورية:
|
||||
- **استخدم HTTPS**: فضّل دائماً HTTPS لعناوين URL خوادم MCP لتشفير البيانات أثناء النقل.
|
||||
- **المصادقة**: نفّذ آليات مصادقة قوية إذا كان خادم MCP يكشف أدوات أو بيانات حساسة.
|
||||
- **التحقق من المدخلات**: تأكد من أن خادم MCP يتحقق من جميع الطلبات والمعاملات الواردة.
|
||||
|
||||
للحصول على دليل شامل حول تأمين تكاملات MCP، يرجى الرجوع إلى صفحة [اعتبارات الأمان](./security.mdx) ووثائق [أمان نقل MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations) الرسمية.
|
||||
Reference in New Issue
Block a user