وكلاء البرمجة بالذكاء الاصطناعي و MCP
خلّ Claude Code أو Cursor أو Codex أو ChatGPT يجهّز datacub عنك. الصق أمر واحد؛ يقرأ تطبيقك، ويفهم وش يسوي منتجك، ويركّب datacub، ويتتبّع الإجراءات القليلة اللي تهم.
أمر الإعداد
انسخ الأمر حق منصتك والصقه في وكيل البرمجة. يركّب الـ SDK، ويعرّف المستخدمين المسجّلين، ويضيف من 3 إلى 5 أحداث للإجراءات اللي تبيّن إن منتجك يشتغل، ويتأكد إن حدث تلقائي وواحد من أحداثه يوصلون datacub فعلًا. وما يتتبّع كل زر، ولا يرسل بيانات شخصية. الأمر مكتوب بالإنجليزي لأن الوكلاء يمشون عليه أدق، وفيه سطر يطلب من الوكيل يكلمك بالعربي. ونفس الأمر، ومعه مفتاح مشروعك، موجود في الإعدادات، MCP والذكاء الاصطناعي.
You are connecting datacub to this website or web app. In short: 1. add datacub's script to the page, 2. track the 3 to 5 actions that matter, for example signup_completed right after someone signs up, 3. check that a real visit and one of those actions reach datacub. The numbered steps below say exactly how.
datacub is privacy-first product analytics: it shows how people find the product, start using it (activation), keep using it (engagement), pay (conversion) and come back (retention). Do the whole setup yourself, from the code. Do not ask me to describe the business or to pick event names: work them out from the repository. Keep the change small and touch nothing unrelated.
Talk to me in Arabic. Keep code, event names and property names in English.
Project
Public ingestion key: not filled in yet: ask me for it (it starts with pk_live_ or pk_test_; datacub shows it under Settings, Integrations)
These keys are public: they can only send events, so they are safe in client code. Never put any other datacub credential (read keys rk_, MCP tokens datacub_mcp_) in code, and never print secrets from .env files.
1. Inspect the repository
Read the README, the package manifests, the routes or screens, the data models and the main flows before changing anything.
2. Understand the business
Say in one or two sentences what the product does and for whom, from the code.
3. Find the core customer journey
Sign up, the first moment of value (activation), the action people repeat, and paying or subscribing, where each exists.
4. Discover the framework and architecture
Entry points, client versus server code, the router or navigation, how login works.
5. Install the official datacub SDK
Web (any site or framework). The SDK is not on npm: datacub serves it as a script. Never install an npm package named @datacub/web, @datacub/react-native or anything else under @datacub: datacub has published nothing on npm yet.
Paste this in the HTML <head>: index.html for Vite and plain sites. In JSX (the root layout in Next.js or TanStack Start) never paste raw script text between tags: put the snippet's code (what is between <script> and </script>) in <script dangerouslySetInnerHTML={{ __html: `...` }} /> inside <head>. It defines the global datacub at once and loads the SDK:
<script>
(function (w, d, src) {
var q = (w.datacub = w.datacub || [])
;['init', 'track', 'identify', 'reset'].forEach(function (n) {
q[n] = function () { q.push([n].concat([].slice.call(arguments))) }
})
var s = d.createElement('script'); s.async = true; s.src = src; d.head.appendChild(s)
})(window, document, 'https://ingest.datacub.example/v1/sdk/datacub-0.4.0.min.js')
datacub.init('pk_live_YOUR_PROJECT_KEY')
</script>
Then use the global datacub in client code only (event handlers, effects), never in code that runs on the server. For TypeScript, save https://ingest.datacub.example/v1/sdk/datacub-0.4.0.d.ts as datacub.d.ts in a folder the tsconfig include covers (src/ for Vite, the project root for Next.js): it types the global datacub.
Page views, route changes in single page apps, and clicks on buttons and links are captured automatically. Do not add page view or click tracking yourself. To give an important button a readable name in reports, add data-datacub-name="upgrade_plan" to it.
The site's domain must be in the project's allowed websites (datacub dashboard, Settings), or datacub refuses its events. On localhost only a test key (pk_test_) is accepted.
6. Automatic analytics
Page views, route changes in single page apps, and clicks on buttons and links are captured automatically once datacub.init runs. Do not add your own page view or click tracking.
7. Consent
Nothing to add: datacub tracks from the first page view or screen. Do not add a consent banner or datacub.consent calls for datacub.
8. Identify signed-in users
After login or signup succeeds, call datacub.identify(user.id) with the app's own stable internal user id. Never use an email address, phone number, national ID or name as the id. Optionally pass { email, name, phone } as the second argument when the user's account has them, at login or when they change, not on every page load: datacub.identify(user.id, { email: user.email, name: user.name }). On logout call datacub.reset(), or the next person on the device inherits the last user's activity.
9. Choose 3 to 5 business events
From the journey in step 3, pick the 3 to 5 actions that show the product is working for someone, for example signup_completed, project_created, checkout_completed, subscription_started, teammate_invited. Name them object_action in snake case. Decide yourself; do not wait for me.
10. Instrument them as custom events
Track successful outcomes where the code knows the action succeeded (after the API call resolves, in the success branch), not the button click: datacub.track('signup_completed', { method: 'email' }). Add a few flat, low-cardinality properties (plan, step, count, true or false). Put each call next to the code that does the action.
11. Stay clean
No passwords, OTPs, tokens, API keys, card data, IBANs, national or Iqama IDs, emails, phone numbers, names, addresses, free text a person typed, or IDs in event names or property values (the identify traits above are the only place for email, name and phone). No duplicate events: one call per outcome, check for existing analytics calls first, never inside code that re-runs on render. No unrelated refactors or formatting changes.
12. Verify for real
Run the app, open a page or screen (an automatic event), then do one of the business actions (a custom event). Each must reach datacub: the POST to https://ingest.datacub.example/v1/batch answers 200 with "accepted" of 1 or more. A 403 names the reason, for example origin_not_allowed (the site must be added to the project's allowed websites) or localhost_live_key (use the test key). Events are sent in small batches: wait 5 seconds before you leave or close the page. A headless or automated browser (Playwright, Puppeteer) counts as a bot: its events are stored but left out of reports, so check the POST answers, not the reports. The datacub setup page turns green by itself when the first automatic event and then the first custom event arrive in a normal browser. Only report what you actually saw.
Feature flags and A/B tests: skip this unless I ask for one. Then add <script src="https://ingest.datacub.example/v1/flags.js"></script> right after the datacub snippet, and use await datacub.flag('key') (true or false) or await datacub.experiment('key') ('A' the original, 'B' the new version). datacub.experiment records that the user saw the version, so call it where that version is actually shown. Use the key of a flag or experiment created in datacub (Feature flags or Experiments); never invent one. A flag is never a permission check: keep those on the server.
13. Report briefly
What you installed and where datacub.init lives, each event and where it fires, what you verified and what you could not, and anything I must do (allow a domain).لتطبيق React Native أو Expo:
You are connecting datacub to this mobile app. In short: 1. add datacub's SDK, 2. track the 3 to 5 actions that matter, for example signup_completed right after someone signs up, 3. check that a real session and one of those actions reach datacub. The numbered steps below say exactly how.
datacub is privacy-first product analytics: it shows how people find the product, start using it (activation), keep using it (engagement), pay (conversion) and come back (retention). Do the whole setup yourself, from the code. Do not ask me to describe the business or to pick event names: work them out from the repository. Keep the change small and touch nothing unrelated.
Talk to me in Arabic. Keep code, event names and property names in English.
Project
Public ingestion key: not filled in yet: ask me for it (it starts with pk_live_ or pk_test_; datacub shows it under Settings, Integrations)
These keys are public: they can only send events, so they are safe in client code. Never put any other datacub credential (read keys rk_, MCP tokens datacub_mcp_) in code, and never print secrets from .env files.
1. Inspect the repository
Read the README, the package manifests, the routes or screens, the data models and the main flows before changing anything.
2. Understand the business
Say in one or two sentences what the product does and for whom, from the code.
3. Find the core customer journey
Sign up, the first moment of value (activation), the action people repeat, and paying or subscribing, where each exists.
4. Discover the framework and architecture
Entry points, client versus server code, the router or navigation, how login works.
5. Install the official datacub SDK
React Native or Expo: datacub's React Native SDK is not published yet, so nothing can connect this app today. Do not install anything and do not fake a connection. Still do steps 1 to 4 and 9, so the event plan is ready, then stop and tell me that datacub's mobile SDK is in early access and that I should contact the datacub team. Swift, Kotlin, Flutter and other native stacks are not supported yet: say so plainly. Never install an npm package named @datacub/web, @datacub/react-native or anything else under @datacub: datacub has published nothing on npm yet.
6. Automatic analytics
Screen views come from the navigation helper of the SDK; do not add your own.
7. Consent
Nothing to add: datacub tracks from the first page view or screen. Do not add a consent banner or datacub.consent calls for datacub.
8. Identify signed-in users
After login or signup succeeds, call datacub.identify(user.id) with the app's own stable internal user id. Never use an email address, phone number, national ID or name as the id. On logout call datacub.reset(), or the next person on the device inherits the last user's activity.
9. Choose 3 to 5 business events
From the journey in step 3, pick the 3 to 5 actions that show the product is working for someone, for example signup_completed, project_created, checkout_completed, subscription_started, teammate_invited. Name them object_action in snake case. Decide yourself; do not wait for me.
10. Instrument them as custom events
Track successful outcomes where the code knows the action succeeded (after the API call resolves, in the success branch), not the button click: datacub.track('signup_completed', { method: 'email' }). Add a few flat, low-cardinality properties (plan, step, count, true or false). Put each call next to the code that does the action.
11. Stay clean
No passwords, OTPs, tokens, API keys, card data, IBANs, national or Iqama IDs, emails, phone numbers, names, addresses, free text a person typed, or IDs in event names or property values. No duplicate events: one call per outcome, check for existing analytics calls first, never inside code that re-runs on render. No unrelated refactors or formatting changes.
12. Verify for real
Run the app, open a page or screen (an automatic event), then do one of the business actions (a custom event). Each must reach datacub: the POST to https://ingest.datacub.example/v1/batch answers 200 with "accepted" of 1 or more. A 403 names the reason, for example origin_not_allowed (the site must be added to the project's allowed websites) or localhost_live_key (use the test key). Events are sent in small batches: wait 5 seconds before you leave or close the page. A headless or automated browser (Playwright, Puppeteer) counts as a bot: its events are stored but left out of reports, so check the POST answers, not the reports. The datacub setup page turns green by itself when the first automatic event and then the first custom event arrive in a normal browser. Only report what you actually saw.
13. Report briefly
What you installed and where datacub.init lives, each event and where it fires, what you verified and what you could not, and anything I must do (allow a domain).خادم MCP
datacub يشغّل خادم Model Context Protocol، عشان Claude Code و Cursor و Codex وأدوات MCP الثانية تقدر تقرأ تحليلاتك وتشيّك على الربط. ويشوف نفس اللي يشوفه دورك في الفريق داخل لوحة التحكم، وبالأرقام المجمّعة بس.
1. سوّ توكن
افتح الإعدادات، MCP والذكاء الاصطناعي في لوحة التحكم، وبعدها التوكنات:
- الصلاحية: قراءة فقط (الافتراضي)، أو قراءة وتسجيل الأحداث، واللي يخلي الأداة تعرّف أحداثك وخصائصها. التسجيل يحتاج دور محلل أو أعلى.
- المشاريع: هذا المشروع بس، أو كل مشاريع فريقك.
- ينتهي بعد: 7 أو 30 أو 90 يوم، أو سنة.
التوكن يبدأ بـ datacub_mcp_ وينعرض مرة وحدة بس. احفظه مثل كلمة المرور، وأبد لا تحطه في كود الواجهة. التوكن لك أنت: يشتغل بدورك الحالي في الفريق، ويوقف لما تنتهي مدته، أو تلغيه، أو تطلع من الفريق.
2. اربط أداتك
الخادم هو عنوان datacub حقك وبعده /mcp. وصفحة الإعدادات تعرض لك هذي الأوامر وفيها عنوانك والتوكن جاهزين.
claude mcp add --transport http x https://YOUR_DATACUB_HOST/mcp \
--header "Authorization: Bearer datacub_mcp_YOUR_TOKEN"{
"mcpServers": {
"x": {
"url": "https://YOUR_DATACUB_HOST/mcp",
"headers": { "Authorization": "Bearer datacub_mcp_YOUR_TOKEN" }
}
}
}# ~/.codex/config.toml, then: export DATACUB_MCP_TOKEN=datacub_mcp_YOUR_TOKEN
[mcp_servers.x]
url = "https://YOUR_DATACUB_HOST/mcp"
bearer_token_env_var = "DATACUB_MCP_TOKEN"روابط ChatGPT تحتاج تسجيل دخول OAuth، وهذا ما يدعمه datacub للحين. الصق أمر الإعداد اللي فوق في ChatGPT بداله.
بعد ما تسوي التوكن على طول، جرّب الاتصال يتأكد منه. وبعدين، آخر استخدام في قائمة التوكنات يوريك إذا أداتك توصل لـ datacub.
وش تقدر تسوي أداتك
| الأداة | وش تسوي |
|---|---|
list_projects، get_project | مشاريعك، ومنطقتها الزمنية، والمواقع والتطبيقات المسموح لها |
get_sdk_setup، get_docs | خطوات التركيب للويب أو React Native، ومرجع مختصر |
get_integration_status | أول حدث وأحدث حدث، والأحداث في آخر 24 ساعة، والـ SDK |
list_event_definitions، get_event_schema | الأحداث اللي وصلت مع أعدادها، والأحداث اللي عرّفها فريقك |
register_event_definition | تعريف حدث ومعناه وخصائصه (صلاحية الكتابة) |
list_flags، create_flag | مفاتيح الميزات والتجارب في المشروع، وإنشاء واحد لما تطلبه (صلاحية الكتابة) |
query_analytics | سؤال واحد بـ نموذج الاستعلام حق لوحة التحكم |
funnel، retention، feature_adoption | نفس أرقام صفحات لوحة التحكم |
investigate_event، investigate_users | حدث واحد، أو مجموعة مستخدمين، بأرقام مجمّعة |
القوائم ترجّع next_cursor للصفحة اللي بعدها. والأداة اللي ما تقدر تجاوب ترجّع {"error": "...", "message": "..."}؛ والمدخلات اللي ما تطابق مخطط الأداة يرفضها MCP نفسه بخطأ invalid params المعتاد. والتوكن يقدر يسوي 120 طلب في الدقيقة.
وش ما يسويه أبد
- ما يعرض أشخاص بعينهم، ولا صفوف أحداث، ولا جلسات. الملفات الشخصية تبقى في لوحة التحكم، وكل مشاهدة لها تنسجّل.
- ما يعطي أي عدد بالضبط. كل عدد يتقرّب لأقرب 10 (والجواب فيه
"approx": true)، ومن 1 إلى 9 يرجع{"lt": 10}يعني أقل من 10، والصفر يبقى صفر. وعدد الأحداث اللي سواها أقل من 10 أشخاص يرجعnull. والنسبة تحتاج 10 أو أكثر في الطرفين. الأرقام الدقيقة في لوحة التحكم حقتك. - يقرأ أيام كاملة بتوقيت المشروع، و
timezoneما يحرّك الفترة. - القيم اللي من أحداثك تنحجب قبل ما تطلع: الإيميل يصير
<email>، والرقم الطويل<number:10>. - ما يشغّل SQL أبد. كل سؤال يمر بنفس محرك الاستعلام حق لوحة التحكم، ومحصور في مشاريع فريقك.
توثيق لأدوات الذكاء الاصطناعي
هذا التوثيق منشور بعد للنماذج اللغوية، بالإنجليزي:
- /llms.txt: فهرس لكل الصفحات، مع رابط للـ markdown حق كل وحدة
- /llms-full.txt: كل الصفحات في ملف واحد
- أي صفحة كـ markdown: أضف
.mdلعنوانها، مثل /docs/quickstart.md - /openapi.json: واجهة HTTP، ومنها نقطة MCP