# ربط المساعد بخادم MCP

> أتح التفريغ الصوتي لمساعدك عبر MCP. اتبع إعداد Claude أو ChatGPT أو VS Code، أو خطوات ربط Cursor MCP وClaude Code MCP.

Canonical: https://transcript1.com/ar/docs/mcp
Language: ar
Last updated: 2026-10-15

يمكن لمساعد الذكاء الاصطناعي طلب التفريغ وقراءة النص المفرغ بعد ربطه بخادم transcript1 البعيد عبر [Model Context Protocol](https://modelcontextprotocol.io/). أرسل إليه رابط YouTube أو X أو TikTok أو Instagram أو Facebook أو Bluesky، أو استخدم ملف صوت أو فيديو مرفوعا. ندعم أيضا التسجيلات العامة الإضافية المذكورة في [المصادر والخيارات](https://transcript1.com/ar/docs/sources-and-options)، وفق القيود الموضحة هناك.

يجب أن يكون المنشور عاما؛ وإذا احتوى على عدة فيديوهات، نفرغ الأول فقط. ما زال دعم الترجمة النصية في YouTube وX كما كان. نستخدم أيضا الترجمة النصية المناسبة بلغة الفيديو الأصلية على TikTok وBluesky وDailymotion وLinkedIn. في وضع `auto`، نلجأ إلى التفريغ الصوتي بالذكاء الاصطناعي إذا لم تتوفر، وبسعر الدقيقة نفسه.

خارج YouTube، تعطي الترجمة النصية توقيت المقاطع فقط، مع `words: null` حتى للمسارات المنشأة تلقائيا. وضع `captions` (الترجمة النصية فقط) لا ينزل الصوت ولا يستخدم STT. وللبدء من الصوت مباشرة، اختر `source=stt` أو فعل تمييز المتحدثين. التفاصيل في [المصادر والخيارات](https://transcript1.com/ar/docs/sources-and-options).

- **عنوان الخادم** هو `https://api.transcript1.com/mcp` ويستخدم streamable HTTP.
- **المصادقة** عبر OAuth 2.1 في Claude وChatGPT؛ تسجل الدخول إلى transcript1 وتوافق على الوصول. أما Cursor وVS Code وClaude Code والوكلاء، فتستخدم مفتاح API في `Authorization: Bearer t1_...`. أنشئ مفتاحا من صفحة [«API keys»](https://transcript1.com/dashboard/account/tokens).

تستدعي الأدوات [REST API](https://transcript1.com/ar/docs/api-reference) على `/v1` باستخدام بيانات مصادقتك. لا تختلف قواعد التحقق أو التكلفة أو رموز الأخطاء. وطلبات MCP تستهلك من الدقائق وحدود الطلبات نفسها في حسابك.

## ما الذي يستطيع المساعد فعله؟

| الأداة | الاستخدام والمعاملات |
|---|---|
| `transcribe` | تبدأ تفريغ رابط فيديو مدعوم. أرسل `url`، ويمكنك إضافة `platform` و`source` و`language` و`diarize` و`format` و`wait_seconds`. تتعرف الأداة على المنصة من الرابط، وتنتظر لتعيد الصفحة الأولى من النص المفرغ، أو `id` إذا استمرت المعالجة. |
| `get_transcription` | تقرأ حالة التفريغ أو نصه عبر `id`. تقبل أيضا `wait_seconds` و`format` و`from_seconds` و`max_chars` اختياريا. |
| `list_transcriptions` | تعرض التفريغات من الأحدث إلى الأقدم، دون النصوص. يمكنك تحديد `status` و`platform` و`limit` و`cursor`. |
| `create_upload` | تحجز رفع ملف من الجهاز على أجزاء. تحتاج إلى `filename` و`size` و`request_id`، وهو UUID تنشئه أنت. يمكنك إضافة `mime_type` و`language` و`diarize`. |
| `get_upload_status` | تبين الأجزاء التي وصلت لتكمل رفع ما تبقى. |
| `complete_upload` | تفحص أجزاء الملف وتضيف التفريغ إلى قائمة الانتظار. |
| `delete_transcription` | تلغي التفريغ الجاري وتعيد دقائقه، أو تحذف التفريغ المنتهي مع النص المفرغ. |
| `get_account` | تقرأ رصيد الدقائق والباقة وموعد التجديد. |

### التنسيق والانتظار والصفحات

- افتراضيا، تكون `format` هي `text`. تحصل على سطر لكل مقطع مع طابع زمني، وتسمية المتحدث إذا فعلت تمييز المتحدثين، مثل `[00:01:02] Speaker 1: Good morning.` ويمكنك طلب `srt` أو `vtt` أو `json` بدلا منه.
- تنتظر الأداة 50 ثانية افتراضيا. لتغيير المدة، حدد `wait_seconds` بين 0 و55. إذا لم ينته التفريغ، يوضح الرد ذلك ويعيد `id`. أرسله إلى `get_transcription` للانتظار مرة أخرى.
- للنصوص الطويلة صفحات تنتهي عند نهاية مقطع. يحدد `max_chars` حجم الصفحة، وافتراضه 60,000 ونطاقه من 1,000 إلى 100,000. خذ `next_from_seconds` من الرد وأرسله في `from_seconds` لجلب الصفحة التالية.
- يبين `transcript_source` مصدر النص للمساعد، بقيمة `youtube_captions` أو `x_captions` أو `tiktok_captions` أو `bluesky_captions` أو `dailymotion_captions` أو `linkedin_captions` أو `speech_to_text`. أما `caption_kind: null`، فتعني أن مصدر مسار الترجمة النصية مجهول، لا أن صانع المحتوى رفعه.

### تابع التفريغ الموجود قبل إنشاء آخر

تطلب `transcribe` تفعيل `reuse_recent` دائما. إذا أرسلت رابط الفيديو الكامل نفسه بالخيارات نفسها خلال 24 ساعة، تحصل على التفريغ السابق دون دفع مرة أخرى. يوضح الرد أنه أعاد استخدام التفريغ. لا تعمل هذه المطابقة مع الروابط القصيرة. استخدم `get_transcription` أو `list_transcriptions` للتحقق من التفريغ الموجود بدلا من إرسال الفيديو من جديد.

### كيف ترفع ملفا مع MCP؟

لا ينقل MCP بايتات الملف نفسه. استدع `create_upload` أولا لتحصل على `id` التفريغ وقالب روابط الأجزاء و`X-Upload-Token` وقائمة الأجزاء. بعدها يرسل المساعد كل جزء بطلب HTTP `PUT` خارج MCP، ثم يستدعي `complete_upload`. يتضمن الرد أيضا رابط صفحة الرفع في لوحة التحكم كخيار بديل. راجع البروتوكول في [رفع الملفات](https://transcript1.com/ar/docs/uploads).

### إشعارات webhook ليست ضمن أدوات MCP

إذا احتجت إلى [إشعارات webhook](https://transcript1.com/ar/docs/webhooks)، استخدم REST API؛ لا تقبل أدوات MCP معامل webhook.

## Claude

أضف خادم MCP البعيد إلى Claude عبر موصل مخصص.

1. انتقل إلى إعدادات الموصلات في Claude واختر إضافة موصل مخصص.
2. سم الموصل `transcript1`، وضع `https://api.transcript1.com/mcp` في عنوان الخادم.
3. عند فتح transcript1، سجل الدخول ووافق على منح صلاحيتين هما `transcriptions:read` و`transcriptions:write`.

بعد الربط، اطلب مثلا «أريد النص المفرغ لهذا الفيديو https://www.youtube.com/watch?v=dQw4w9WgXcQ». توفر الموصلات المخصصة يعتمد على باقتك في Claude.

## ChatGPT

للربط مع ChatGPT، أضف موصلا مخصصا أيضا.

1. من إعدادات الموصلات في ChatGPT، أضف موصلا مخصصا لخادم MCP.
2. ضع `https://api.transcript1.com/mcp` في عنوان الخادم.
3. سجل الدخول إلى transcript1 وأكمل الموافقة على الوصول.

قد تحتاج إلى تفعيل developer mode. توفر الموصلات المخصصة يتوقف على باقتك في ChatGPT وإعدادات مساحة العمل.

## اربط Cursor عبر MCP

للإعداد بنقرة واحدة، استخدم [إضافة transcript1 إلى Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=transcript1&config=eyJ1cmwiOiJodHRwczovL2FwaS50cmFuc2NyaXB0MS5jb20vbWNwIn0=).

وللإعداد اليدوي، أضف التالي إلى `.cursor/mcp.json`، وضع مفتاح API في ترويسة `Authorization`:

```json
{
  "mcpServers": {
    "transcript1": {
      "url": "https://api.transcript1.com/mcp",
      "headers": {
        "Authorization": "Bearer t1_YOURKEY"
      }
    }
  }
}
```

## VS Code

استخدم [إضافة transcript1 إلى VS Code](vscode:mcp/install?%7B%22name%22%3A%22transcript1%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.transcript1.com%2Fmcp%22%7D) للإعداد بنقرة واحدة.

أو ضع الإعداد التالي في `.vscode/mcp.json` داخل مساحة العمل:

```json
{
  "servers": {
    "transcript1": {
      "type": "http",
      "url": "https://api.transcript1.com/mcp",
      "headers": {
        "Authorization": "Bearer t1_YOURKEY"
      }
    }
  }
}
```

## اربط Claude Code عبر MCP

ضع مفتاح API مكان `t1_YOURKEY` في الأمر التالي وشغله:

```bash
claude mcp add --transport http transcript1 https://api.transcript1.com/mcp --header "Authorization: Bearer t1_YOURKEY"
```

## استخدم عميلا آخر

إذا كان العميل يدعم خوادم MCP البعيدة، وجهه إلى `https://api.transcript1.com/mcp` وأضف الترويسة `Authorization: Bearer t1_...`.

## الربط بأمر محلي في Claude Desktop وغيره

بعض العملاء يشغلون خادم MCP بأمر محلي. في هذه الحالة، استخدم `npx -y @transcript1/mcp` وحدد مفتاح API في `TRANSCRIPT1_API_KEY`. تصل الحزمة عميلك بخادم transcript1 المستضاف، وتحتاج إلى Node.js 18 أو أحدث.

في Claude Desktop، أضف المثال التالي إلى `claude_desktop_config.json` وضع مفتاحا من صفحة [«API keys»](https://transcript1.com/dashboard/account/tokens) مكان `t1_YOURKEY`.

```json
{
  "mcpServers": {
    "transcript1": {
      "command": "npx",
      "args": ["-y", "@transcript1/mcp"],
      "env": { "TRANSCRIPT1_API_KEY": "t1_YOURKEY" }
    }
  }
}
```

## Agent Skill

إذا كان وكيلك يدعم المهارات، أضف إليه ملف [Agent Skill لاستخدام transcript1](https://transcript1.com/.well-known/agent-skills/transcript1/SKILL.md). إنه ملف `SKILL.md` قصير يشرح للوكيل كيفية استخدام transcript1.

أما الوكلاء الذين يكتشفون المهارات تلقائيا، فيمكنهم العثور عليه عبر `https://transcript1.com/.well-known/agent-skills/index.json`.

## كيف تظهر الأخطاء للمساعد؟

عند فشل أداة، يتلقى المساعد رمز `code` نفسه الذي يستخدمه REST API، مع رسالة وخطوة لمعالجة المشكلة. يأتي الرد بالصيغة `<code>: <message>. <next step>`. مثلا، عند نفاد الدقائق:

```text
insufficient_minutes: 20 minutes needed, 3 remaining. Top up at https://transcript1.com/dashboard/billing
```

إذا فشل التفريغ، يصلك الخطأ بالطريقة نفسها مع رمز مثل `media_private` أو `no_captions`. تجد شرح جميع الرموز في [التعامل مع الأخطاء](https://transcript1.com/ar/docs/errors).