# بناء عميل MCP مخصص

إذا كنت تبني تطبيق LLM خاصًا بك، يمكنك الاتصال بخادم Synapse
MCP مباشرة باستخدام MCP SDK الرسمي. هذا يمنح تطبيقك الوصول إلى
جميع أدوات Synapse الـ 79.

## حزم SDK

| اللغة | الحزمة |
|----------|---------|
| TypeScript/JavaScript | `@modelcontextprotocol/sdk` |
| Python | `mcp` |

## مثال TypeScript

### تثبيت

```bash
npm install @modelcontextprotocol/sdk
```

### الاتصال عبر stdio

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "synapse-mcp-api@latest"],
  env: {
    SYNAPSE_MIND_KEY: process.env.SYNAPSE_MIND_KEY!,
    SYNAPSE_URL: "https://synapse.schaefer.zone",
  },
});

const client = new Client(
  { name: "my-app", version: "1.0.0" },
  { capabilities: {} }
);

await client.connect(transport);

// سرد جميع الأدوات المتاحة
const { tools } = await client.listTools();
console.log(`Available tools: ${tools.length}`);
for (const tool of tools) {
  console.log(`- ${tool.name}: ${tool.description}`);
}

// استدعِ أداة
const result = await client.callTool({
  name: "memory_recall",
  arguments: {},
});
console.log(result.content);

// خزّن ذاكرة
await client.callTool({
  name: "memory_store",
  arguments: {
    category: "fact",
    key: "custom_client_test",
    content: "Built a custom MCP client",
    tags: ["test", "mcp"],
    priority: "normal",
  },
});

await client.close();
```

### الاتصال عبر HTTP/SSE (بعيد)

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const transport = new SSEClientTransport(
  new URL("https://synapse-mcp.schaefer.zone/sse"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${process.env.SYNAPSE_MIND_KEY}`,
      },
    },
  }
);

const client = new Client(
  { name: "my-app", version: "1.0.0" },
  { capabilities: {} }
);

await client.connect(transport);
// ... استخدم كما هو مذكور أعلاه
```

## مثال Python

### تثبيت

```bash
pip install mcp
```

### الاتصال عبر stdio

```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="npx",
    args=["-y", "synapse-mcp-api@latest"],
    env={
        "SYNAPSE_MIND_KEY": "mk_YOUR_KEY",
        "SYNAPSE_URL": "https://synapse.schaefer.zone",
    },
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()

        # سرد الأدوات
        tools = await session.list_tools()
        print(f"Available tools: {len(tools.tools)}")

        # استدعِ أداة
        result = await session.call_tool("memory_recall", {})
        print(result.content)

        # خزّن ذاكرة
        await session.call_tool("memory_store", {
            "category": "fact",
            "key": "python_client_test",
            "content": "Built a Python MCP client",
            "tags": ["test", "mcp", "python"],
            "priority": "normal",
        })
```

## ملفات الأدوات

عند الاتصال، يمكنك طلب ملف أداة محدد عبر
ترويسة `Mcp-Tool-Profile` (HTTP/SSE) أو متغير البيئة `MCP_PROFILE` (stdio):

```typescript
// stdio: عيّن متغير البيئة
env: {
  SYNAPSE_MIND_KEY: "mk_...",
  MCP_PROFILE: "minimal",  // 8 أدوات بدلًا من 119
}

// HTTP/SSE: عيّن الترويسة
requestInit: {
  headers: {
    Authorization: "Bearer mk_...",
    "Mcp-Tool-Profile": "minimal",
  },
}
```

## معالجة الأخطاء

```typescript
try {
  const result = await client.callTool({ name: "memory_recall", arguments: {} });
  if (result.isError) {
    console.error("Tool error:", result.content);
  } else {
    console.log("Success:", result.content);
  }
} catch (err) {
  console.error("MCP error:", err);
}
```

## حالات الاستخدام

- **مساعدون ذكيون مخصصون** — ابنِ وكيلك الخاص بذاكرة دائمة
- **أتمتة سير العمل** — اربط أدوات Synapse في سير عمل مخصص
- **خطوط بيانات** — استخرج الذكريات، حوّل، حمّل في مكان آخر
- **لوحات المراقبة** — اعرض إحصائيات الذاكرة، سجل الدردشة، المهام

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

- [مواصفات MCP](https://spec.modelcontextprotocol.io)
- [مستودع Synapse MCP](https://gitlab.com/schaefer-services/synapse-mcp)
- [نظرة عامة على الـ API](/docs/api/overview)