Compare commits
1 Commits
v4.10.0
...
copilot/fi
| Author | SHA1 | Date | |
|---|---|---|---|
|
f27085af3d |
14
.github/MAINTENANCE.md
vendored
14
.github/MAINTENANCE.md
vendored
@@ -177,19 +177,11 @@ When cutting a new version (e.g., V4):
|
||||
- Update `package.json` → `"version": "X.Y.Z"` (source of truth for npm).
|
||||
- Update version header in `README.md` if it displays the number.
|
||||
- One-liner: `npm version patch` (or `minor`/`major`) — bumps `package.json` and creates a git tag; then amend if you need to tag after release.
|
||||
4. **Create GitHub Release** (REQUIRED):
|
||||
|
||||
> ⚠️ **CRITICAL**: Pushing a tag (`git push --tags`) is NOT enough. You must create a **GitHub Release Object** for it to appear in the sidebar and trigger the NPM publish workflow.
|
||||
|
||||
Use the GitHub CLI:
|
||||
|
||||
4. **Tag Release**:
|
||||
```bash
|
||||
# This creates the tag AND the release page automatically
|
||||
gh release create v4.0.0 --title "v4.0.0 - [Theme Name]" --notes-file release_notes.md
|
||||
git tag -a v4.0.0 -m "V4 Enterprise Edition"
|
||||
git push origin v4.0.0
|
||||
```
|
||||
|
||||
_Or manually via the GitHub UI > Releases > Draft a new release._
|
||||
|
||||
5. **Publish to npm** (so `npx antigravity-awesome-skills` works):
|
||||
- **Option A (manual):** From repo root, with npm logged in and 2FA/token set up:
|
||||
```bash
|
||||
|
||||
3
.github/workflows/ci.yml
vendored
3
.github/workflows/ci.yml
vendored
@@ -68,9 +68,6 @@ jobs:
|
||||
# If no changes, exit successfully
|
||||
git diff --quiet && exit 0
|
||||
|
||||
# Pull with rebase to integrate remote changes
|
||||
git pull origin main --rebase || true
|
||||
|
||||
git add README.md skills_index.json data/catalog.json data/bundles.json data/aliases.json CATALOG.md || true
|
||||
|
||||
# If nothing to commit, exit successfully
|
||||
|
||||
117
CATALOG.md
117
CATALOG.md
@@ -1,15 +1,13 @@
|
||||
# Skill Catalog
|
||||
|
||||
Generated at: 2026-02-06T07:49:30.257Z
|
||||
Generated at: 2026-02-03T09:20:12.539Z
|
||||
|
||||
Total skills: 713
|
||||
Total skills: 626
|
||||
|
||||
## architecture (63)
|
||||
## architecture (60)
|
||||
|
||||
| Skill | Description | Tags | Triggers |
|
||||
| --- | --- | --- | --- |
|
||||
| `angular` | Modern Angular (v20+) expert with deep knowledge of Signals, Standalone Components, Zoneless applications, SSR/Hydration, and reactive patterns. Use PROACTIV... | angular | angular, v20, deep, knowledge, signals, standalone, components, zoneless, applications, ssr, hydration, reactive |
|
||||
| `angular-state-management` | Master modern Angular state management with Signals, NgRx, and RxJS. Use when setting up global state, managing component stores, choosing between state solu... | angular, state | angular, state, signals, ngrx, rxjs, setting, up, global, managing, component, stores, choosing |
|
||||
| `architect-review` | Master software architect specializing in modern architecture patterns, clean architecture, microservices, event-driven systems, and DDD. Reviews system desi... | | architect, review, software, specializing, architecture, clean, microservices, event, driven, ddd, reviews, designs |
|
||||
| `architecture` | Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing ... | architecture | architecture, architectural, decision, making, framework, requirements, analysis, trade, off, evaluation, adr, documentation |
|
||||
| `architecture-decision-records` | Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant techn... | architecture, decision, records | architecture, decision, records, write, maintain, adrs, following, technical, documentation, documenting, significant, decisions |
|
||||
@@ -23,7 +21,6 @@ Total skills: 713
|
||||
| `c4-code` | Expert C4 Code-level documentation specialist. Analyzes code directories to create comprehensive C4 code-level documentation including function signatures, a... | c4, code | c4, code, level, documentation, analyzes, directories, including, function, signatures, arguments, dependencies, structure |
|
||||
| `c4-component` | Expert C4 Component-level documentation specialist. Synthesizes C4 Code-level documentation into Component-level architecture, defining component boundaries,... | c4, component | c4, component, level, documentation, synthesizes, code, architecture, defining, boundaries, interfaces, relationships, creates |
|
||||
| `c4-context` | Expert C4 Context-level documentation specialist. Creates high-level system context diagrams, documents personas, user journeys, system features, and externa... | c4 | c4, context, level, documentation, creates, high, diagrams, documents, personas, user, journeys, features |
|
||||
| `calendly-automation` | Automate Calendly scheduling, event management, invitee tracking, availability checks, and organization administration via Rube MCP (Composio). Always search... | calendly | calendly, automation, automate, scheduling, event, invitee, tracking, availability, checks, organization, administration, via |
|
||||
| `code-refactoring-refactor-clean` | You are a code refactoring expert specializing in clean code principles, SOLID design patterns, and modern software engineering best practices. Analyze and r... | code, refactoring, refactor, clean | code, refactoring, refactor, clean, specializing, principles, solid, software, engineering, analyze, provided, improve |
|
||||
| `codebase-cleanup-refactor-clean` | You are a code refactoring expert specializing in clean code principles, SOLID design patterns, and modern software engineering best practices. Analyze and r... | codebase, cleanup, refactor, clean | codebase, cleanup, refactor, clean, code, refactoring, specializing, principles, solid, software, engineering, analyze |
|
||||
| `competitor-alternatives` | When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'v... | competitor, alternatives | competitor, alternatives, user, wants, comparison, alternative, pages, seo, sales, enablement, mentions, page |
|
||||
@@ -72,7 +69,7 @@ Total skills: 713
|
||||
| `workflow-patterns` | Use this skill when implementing tasks according to Conductor's TDD workflow, handling phase checkpoints, managing git commits for tasks, or understanding th... | | skill, implementing, tasks, according, conductor, tdd, handling, phase, checkpoints, managing, git, commits |
|
||||
| `zapier-make-patterns` | No-code automation democratizes workflow building. Zapier and Make (formerly Integromat) let non-developers automate business processes without writing code.... | zapier, make | zapier, make, no, code, automation, democratizes, building, formerly, integromat, let, non, developers |
|
||||
|
||||
## business (38)
|
||||
## business (37)
|
||||
|
||||
| Skill | Description | Tags | Triggers |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -113,9 +110,8 @@ Total skills: 713
|
||||
| `startup-business-analyst-market-opportunity` | Generate comprehensive market opportunity analysis with TAM/SAM/SOM calculations | startup, business, analyst, market, opportunity | startup, business, analyst, market, opportunity, generate, analysis, tam, sam, som, calculations |
|
||||
| `startup-financial-modeling` | This skill should be used when the user asks to "create financial projections", "build a financial model", "forecast revenue", "calculate burn rate", "estima... | startup, financial, modeling | startup, financial, modeling, skill, should, used, user, asks, projections, model, forecast, revenue |
|
||||
| `team-composition-analysis` | This skill should be used when the user asks to "plan team structure", "determine hiring needs", "design org chart", "calculate compensation", "plan equity a... | team, composition | team, composition, analysis, skill, should, used, user, asks, plan, structure, determine, hiring |
|
||||
| `whatsapp-automation` | Automate WhatsApp Business tasks via Rube MCP (Composio): send messages, manage templates, upload media, and handle contacts. Always search tools first for c... | whatsapp | whatsapp, automation, automate, business, tasks, via, rube, mcp, composio, send, messages, upload |
|
||||
|
||||
## data-ai (99)
|
||||
## data-ai (92)
|
||||
|
||||
| Skill | Description | Tags | Triggers |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -125,9 +121,7 @@ Total skills: 713
|
||||
| `ai-engineer` | Build production-ready LLM applications, advanced RAG systems, and intelligent agents. Implements vector search, multimodal AI, agent orchestration, and ente... | ai | ai, engineer, llm, applications, rag, intelligent, agents, implements, vector, search, multimodal, agent |
|
||||
| `ai-wrapper-product` | Expert in building products that wrap AI APIs (OpenAI, Anthropic, etc.) into focused tools people will pay for. Not just 'ChatGPT but different' - products t... | ai, wrapper, product | ai, wrapper, product, building, products, wrap, apis, openai, anthropic, etc, people, pay |
|
||||
| `analytics-tracking` | Design, audit, and improve analytics tracking systems that produce reliable, decision-ready data. Use when the user wants to set up, fix, or evaluate analyti... | analytics, tracking | analytics, tracking, audit, improve, produce, reliable, decision, data, user, wants, set, up |
|
||||
| `angular-ui-patterns` | Modern Angular UI patterns for loading states, error handling, and data display. Use when building UI components, handling async data, or managing component ... | angular, ui | angular, ui, loading, states, error, handling, data, display, building, components, async, managing |
|
||||
| `api-documenter` | Master API documentation with OpenAPI 3.1, AI-powered tools, and modern developer experience practices. Create interactive docs, generate SDKs, and build com... | api, documenter | api, documenter, documentation, openapi, ai, powered, developer, experience, interactive, docs, generate, sdks |
|
||||
| `audio-transcriber` | Transform audio recordings into professional Markdown documentation with intelligent summaries using LLM integration | audio, transcription, whisper, meeting-minutes, speech-to-text | audio, transcription, whisper, meeting-minutes, speech-to-text, transcriber, transform, recordings, professional, markdown, documentation, intelligent |
|
||||
| `autonomous-agent-patterns` | Design patterns for building autonomous coding agents. Covers tool integration, permission systems, browser automation, and human-in-the-loop workflows. Use ... | autonomous, agent | autonomous, agent, building, coding, agents, covers, integration, permission, browser, automation, human, loop |
|
||||
| `autonomous-agents` | Autonomous agents are AI systems that can independently decompose goals, plan actions, execute tools, and self-correct without constant human guidance. The c... | autonomous, agents | autonomous, agents, ai, independently, decompose, goals, plan, actions, execute, self, correct, without |
|
||||
| `beautiful-prose` | Hard-edged writing style contract for timeless, forceful English prose without AI tics | beautiful, prose | beautiful, prose, hard, edged, writing, style, contract, timeless, forceful, english, without, ai |
|
||||
@@ -164,8 +158,6 @@ Total skills: 713
|
||||
| `fp-ts-react` | Practical patterns for using fp-ts with React - hooks, state, forms, data fetching. Use when building React apps with functional programming patterns. Works ... | fp, ts, react | fp, ts, react, practical, hooks, state, forms, data, fetching, building, apps, functional |
|
||||
| `frontend-dev-guidelines` | Opinionated frontend development standards for modern React + TypeScript applications. Covers Suspense-first data fetching, lazy loading, feature-based archi... | frontend, dev, guidelines | frontend, dev, guidelines, opinionated, development, standards, react, typescript, applications, covers, suspense, first |
|
||||
| `geo-fundamentals` | Generative Engine Optimization for AI search engines (ChatGPT, Claude, Perplexity). | geo, fundamentals | geo, fundamentals, generative, engine, optimization, ai, search, engines, chatgpt, claude, perplexity |
|
||||
| `google-analytics-automation` | Automate Google Analytics tasks via Rube MCP (Composio): run reports, list accounts/properties, funnels, pivots, key events. Always search tools first for cu... | google, analytics | google, analytics, automation, automate, tasks, via, rube, mcp, composio, run, reports, list |
|
||||
| `googlesheets-automation` | Automate Google Sheets operations (read, write, format, filter, manage spreadsheets) via Rube MCP (Composio). Read/write data, manage tabs, apply formatting,... | googlesheets | googlesheets, automation, automate, google, sheets, operations, read, write, format, filter, spreadsheets, via |
|
||||
| `graphql` | GraphQL gives clients exactly the data they need - no more, no less. One endpoint, typed schema, introspection. But the flexibility that makes it powerful al... | graphql | graphql, gives, clients, exactly, data, no, less, one, endpoint, typed, schema, introspection |
|
||||
| `hybrid-search-implementation` | Combine vector and keyword search for improved retrieval. Use when implementing RAG systems, building search engines, or when neither approach alone provides... | hybrid, search | hybrid, search, combine, vector, keyword, improved, retrieval, implementing, rag, building, engines, neither |
|
||||
| `ios-developer` | Develop native iOS applications with Swift/SwiftUI. Masters iOS 18, SwiftUI, UIKit integration, Core Data, networking, and App Store optimization. Use PROACT... | ios | ios, developer, develop, native, applications, swift, swiftui, masters, 18, uikit, integration, core |
|
||||
@@ -175,7 +167,6 @@ Total skills: 713
|
||||
| `llm-application-dev-langchain-agent` | You are an expert LangChain agent developer specializing in production-grade AI systems using LangChain 0.1+ and LangGraph. | llm, application, dev, langchain, agent | llm, application, dev, langchain, agent, developer, specializing, grade, ai, langgraph |
|
||||
| `llm-application-dev-prompt-optimize` | You are an expert prompt engineer specializing in crafting effective prompts for LLMs through advanced techniques including constitutional AI, chain-of-thoug... | llm, application, dev, prompt, optimize | llm, application, dev, prompt, optimize, engineer, specializing, crafting, effective, prompts, llms, through |
|
||||
| `llm-evaluation` | Implement comprehensive evaluation strategies for LLM applications using automated metrics, human feedback, and benchmarking. Use when testing LLM performanc... | llm, evaluation | llm, evaluation, applications, automated, metrics, human, feedback, benchmarking, testing, performance, measuring, ai |
|
||||
| `mailchimp-automation` | Automate Mailchimp email marketing including campaigns, audiences, subscribers, segments, and analytics via Rube MCP (Composio). Always search tools first fo... | mailchimp | mailchimp, automation, automate, email, marketing, including, campaigns, audiences, subscribers, segments, analytics, via |
|
||||
| `nanobanana-ppt-skills` | AI-powered PPT generation with document analysis and styled images | nanobanana, ppt, skills | nanobanana, ppt, skills, ai, powered, generation, document, analysis, styled, images |
|
||||
| `neon-postgres` | Expert patterns for Neon serverless Postgres, branching, connection pooling, and Prisma/Drizzle integration Use when: neon database, serverless postgres, dat... | neon, postgres | neon, postgres, serverless, branching, connection, pooling, prisma, drizzle, integration, database |
|
||||
| `nextjs-app-router-patterns` | Master Next.js 14+ App Router with Server Components, streaming, parallel routes, and advanced data fetching. Use when building Next.js applications, impleme... | nextjs, app, router | nextjs, app, router, next, js, 14, server, components, streaming, parallel, routes, data |
|
||||
@@ -187,6 +178,7 @@ Total skills: 713
|
||||
| `prisma-expert` | Prisma ORM expert for schema design, migrations, query optimization, relations modeling, and database operations. Use PROACTIVELY for Prisma schema issues, m... | prisma | prisma, orm, schema, migrations, query, optimization, relations, modeling, database, operations, proactively, issues |
|
||||
| `programmatic-seo` | Design and evaluate programmatic SEO strategies for creating SEO-driven pages at scale using templates and structured data. Use when the user mentions progra... | programmatic, seo | programmatic, seo, evaluate, creating, driven, pages, scale, structured, data, user, mentions, directory |
|
||||
| `prompt-caching` | Caching strategies for LLM prompts including Anthropic prompt caching, response caching, and CAG (Cache Augmented Generation) Use when: prompt caching, cache... | prompt, caching | prompt, caching, llm, prompts, including, anthropic, response, cag, cache, augmented, generation |
|
||||
| `prompt-engineer` | Expert prompt engineer specializing in advanced prompting techniques, LLM optimization, and AI system design. Masters chain-of-thought, constitutional AI, an... | prompt | prompt, engineer, specializing, prompting, techniques, llm, optimization, ai, masters, chain, thought, constitutional |
|
||||
| `prompt-engineering-patterns` | Master advanced prompt engineering techniques to maximize LLM performance, reliability, and controllability in production. Use when optimizing prompts, impro... | prompt, engineering | prompt, engineering, techniques, maximize, llm, performance, reliability, controllability, optimizing, prompts, improving, outputs |
|
||||
| `rag-engineer` | Expert in building Retrieval-Augmented Generation systems. Masters embedding models, vector databases, chunking strategies, and retrieval optimization for LL... | rag | rag, engineer, building, retrieval, augmented, generation, masters, embedding, models, vector, databases, chunking |
|
||||
| `rag-implementation` | Build Retrieval-Augmented Generation (RAG) systems for LLM applications with vector databases and semantic search. Use when implementing knowledge-grounded A... | rag | rag, retrieval, augmented, generation, llm, applications, vector, databases, semantic, search, implementing, knowledge |
|
||||
@@ -195,7 +187,6 @@ Total skills: 713
|
||||
| `scala-pro` | Master enterprise-grade Scala development with functional programming, distributed systems, and big data processing. Expert in Apache Pekko, Akka, Spark, ZIO... | scala | scala, pro, enterprise, grade, development, functional, programming, distributed, big, data, processing, apache |
|
||||
| `schema-markup` | Design, validate, and optimize schema.org structured data for eligibility, correctness, and measurable SEO impact. Use when the user wants to add, fix, audit... | schema, markup | schema, markup, validate, optimize, org, structured, data, eligibility, correctness, measurable, seo, impact |
|
||||
| `segment-cdp` | Expert patterns for Segment Customer Data Platform including Analytics.js, server-side tracking, tracking plans with Protocols, identity resolution, destinat... | segment, cdp | segment, cdp, customer, data, platform, including, analytics, js, server, side, tracking, plans |
|
||||
| `sendgrid-automation` | Automate SendGrid email operations including sending emails, managing contacts/lists, sender identities, templates, and analytics via Rube MCP (Composio). Al... | sendgrid | sendgrid, automation, automate, email, operations, including, sending, emails, managing, contacts, lists, sender |
|
||||
| `senior-architect` | Comprehensive software architecture skill for designing scalable, maintainable systems using ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin, F... | senior | senior, architect, software, architecture, skill, designing, scalable, maintainable, reactjs, nextjs, nodejs, express |
|
||||
| `seo-audit` | Diagnose and audit SEO issues affecting crawlability, indexation, rankings, and organic performance. Use when the user asks for an SEO audit, technical SEO r... | seo, audit | seo, audit, diagnose, issues, affecting, crawlability, indexation, rankings, organic, performance, user, asks |
|
||||
| `similarity-search-patterns` | Implement efficient similarity search with vector databases. Use when building semantic search, implementing nearest neighbor queries, or optimizing retrieva... | similarity, search | similarity, search, efficient, vector, databases, building, semantic, implementing, nearest, neighbor, queries, optimizing |
|
||||
@@ -204,7 +195,6 @@ Total skills: 713
|
||||
| `sql-optimization-patterns` | Master SQL query optimization, indexing strategies, and EXPLAIN analysis to dramatically improve database performance and eliminate slow queries. Use when de... | sql, optimization | sql, optimization, query, indexing, explain, analysis, dramatically, improve, database, performance, eliminate, slow |
|
||||
| `sqlmap-database-pentesting` | This skill should be used when the user asks to "automate SQL injection testing," "enumerate database structure," "extract database credentials using sqlmap,... | sqlmap, database, pentesting | sqlmap, database, pentesting, penetration, testing, skill, should, used, user, asks, automate, sql |
|
||||
| `stitch-ui-design` | Expert guide for creating effective prompts for Google Stitch AI UI design tool. Use when user wants to design UI/UX in Stitch, create app interfaces, genera... | stitch, ui | stitch, ui, creating, effective, prompts, google, ai, user, wants, ux, app, interfaces |
|
||||
| `supabase-automation` | Automate Supabase database queries, table management, project administration, storage, edge functions, and SQL execution via Rube MCP (Composio). Always sear... | supabase | supabase, automation, automate, database, queries, table, administration, storage, edge, functions, sql, execution |
|
||||
| `tdd-orchestrator` | Master TDD orchestrator specializing in red-green-refactor discipline, multi-agent workflow coordination, and comprehensive test-driven development practices... | tdd, orchestrator | tdd, orchestrator, specializing, red, green, refactor, discipline, multi, agent, coordination, test, driven |
|
||||
| `team-collaboration-standup-notes` | You are an expert team communication specialist focused on async-first standup practices, AI-assisted note generation from commit history, and effective remo... | team, collaboration, standup, notes | team, collaboration, standup, notes, communication, async, first, ai, assisted, note, generation, commit |
|
||||
| `telegram-bot-builder` | Expert in building Telegram bots that solve real problems - from simple automation to complex AI-powered bots. Covers bot architecture, the Telegram Bot API,... | telegram, bot, builder | telegram, bot, builder, building, bots, solve, real, problems, simple, automation, complex, ai |
|
||||
@@ -217,9 +207,8 @@ Total skills: 713
|
||||
| `voice-ai-engine-development` | Build real-time conversational AI voice engines using async worker pipelines, streaming transcription, LLM agents, and TTS synthesis with interrupt handling ... | voice, ai, engine | voice, ai, engine, development, real, time, conversational, engines, async, worker, pipelines, streaming |
|
||||
| `web-artifacts-builder` | Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use ... | web, artifacts, builder | web, artifacts, builder, suite, creating, elaborate, multi, component, claude, ai, html, frontend |
|
||||
| `xlsx-official` | Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work ... | xlsx, official | xlsx, official, spreadsheet, creation, editing, analysis, formulas, formatting, data, visualization, claude, work |
|
||||
| `youtube-automation` | Automate YouTube tasks via Rube MCP (Composio): upload videos, manage playlists, search content, get analytics, and handle comments. Always search tools firs... | youtube | youtube, automation, automate, tasks, via, rube, mcp, composio, upload, videos, playlists, search |
|
||||
|
||||
## development (82)
|
||||
## development (81)
|
||||
|
||||
| Skill | Description | Tags | Triggers |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -292,7 +281,6 @@ Total skills: 713
|
||||
| `shopify-apps` | Expert patterns for Shopify app development including Remix/React Router apps, embedded apps with App Bridge, webhook handling, GraphQL Admin API, Polaris co... | shopify, apps | shopify, apps, app, development, including, remix, react, router, embedded, bridge, webhook, handling |
|
||||
| `shopify-development` | Build Shopify apps, extensions, themes using GraphQL Admin API, Shopify CLI, Polaris UI, and Liquid.
|
||||
TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify, development, apps, extensions, themes, graphql, admin, api, cli, polaris, ui, liquid |
|
||||
| `slack-automation` | Automate Slack messaging, channel management, search, reactions, and threads via Rube MCP (Composio). Send messages, search conversations, manage channels/us... | slack | slack, automation, automate, messaging, channel, search, reactions, threads, via, rube, mcp, composio |
|
||||
| `slack-bot-builder` | Build Slack apps using the Bolt framework across Python, JavaScript, and Java. Covers Block Kit for rich UIs, interactive components, slash commands, event h... | slack, bot, builder | slack, bot, builder, apps, bolt, framework, python, javascript, java, covers, block, kit |
|
||||
| `swiftui-expert-skill` | Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, modern APIs, Swift concurrency, and iOS ... | swiftui, skill | swiftui, skill, write, review, improve, code, following, state, view, composition, performance, apis |
|
||||
| `systems-programming-rust-project` | You are a Rust project architecture expert specializing in scaffolding production-ready Rust applications. Generate complete project structures with cargo to... | programming, rust | programming, rust, architecture, specializing, scaffolding, applications, generate, complete, structures, cargo, tooling, proper |
|
||||
@@ -307,14 +295,13 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
|
||||
| `viral-generator-builder` | Expert in building shareable generator tools that go viral - name generators, quiz makers, avatar creators, personality tests, and calculator tools. Covers t... | viral, generator, builder | viral, generator, builder, building, shareable, go, name, generators, quiz, makers, avatar, creators |
|
||||
| `webapp-testing` | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing... | webapp | webapp, testing, toolkit, interacting, local, web, applications, playwright, supports, verifying, frontend, functionality |
|
||||
|
||||
## general (131)
|
||||
## general (128)
|
||||
|
||||
| Skill | Description | Tags | Triggers |
|
||||
| --- | --- | --- | --- |
|
||||
| `address-github-comments` | Use when you need to address review or issue comments on an open GitHub Pull Request using the gh CLI. | address, github, comments | address, github, comments, review, issue, open, pull, request, gh, cli |
|
||||
| `agent-manager-skill` | Manage multiple local CLI agents via tmux sessions (start/stop/monitor/assign) with cron-friendly scheduling. | agent, manager, skill | agent, manager, skill, multiple, local, cli, agents, via, tmux, sessions, start, stop |
|
||||
| `algorithmic-art` | Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, gener... | algorithmic, art | algorithmic, art, creating, p5, js, seeded, randomness, interactive, parameter, exploration, users, request |
|
||||
| `angular-best-practices` | Angular performance optimization and best practices guide. Use when writing, reviewing, or refactoring Angular code for optimal performance, bundle size, and... | angular, best, practices | angular, best, practices, performance, optimization, writing, reviewing, refactoring, code, optimal, bundle, size |
|
||||
| `angular-migration` | Migrate from AngularJS to Angular using hybrid mode, incremental component rewriting, and dependency injection updates. Use when upgrading AngularJS applicat... | angular, migration | angular, migration, migrate, angularjs, hybrid, mode, incremental, component, rewriting, dependency, injection, updates |
|
||||
| `anti-reversing-techniques` | Understand anti-reversing, obfuscation, and protection techniques encountered during software analysis. Use when analyzing protected binaries, bypassing anti... | anti, reversing, techniques | anti, reversing, techniques, understand, obfuscation, protection, encountered, during, software, analysis, analyzing, protected |
|
||||
| `app-builder` | Main application building orchestrator. Creates full-stack applications from natural language requests. Determines project type, selects tech stack, coordina... | app, builder | app, builder, main, application, building, orchestrator, creates, full, stack, applications, natural, language |
|
||||
@@ -347,7 +334,6 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
|
||||
| `commit` | Create commit messages following Sentry conventions. Use when committing code changes, writing commit messages, or formatting git history. Follows convention... | commit | commit, messages, following, sentry, conventions, committing, code, changes, writing, formatting, git, history |
|
||||
| `comprehensive-review-full-review` | Use when working with comprehensive review full review | comprehensive, full | comprehensive, full, review, working |
|
||||
| `comprehensive-review-pr-enhance` | You are a PR optimization expert specializing in creating high-quality pull requests that facilitate efficient code reviews. Generate comprehensive PR descri... | comprehensive, pr, enhance | comprehensive, pr, enhance, review, optimization, specializing, creating, high, quality, pull, requests, facilitate |
|
||||
| `computer-vision-expert` | SOTA Computer Vision Expert (2026). Specialized in YOLO26, Segment Anything 3 (SAM 3), Vision Language Models, and real-time spatial analysis. | computer, vision | computer, vision, sota, 2026, specialized, yolo26, segment, anything, sam, language, models, real |
|
||||
| `concise-planning` | Use when a user asks for a plan for a coding task, to generate a clear, actionable, and atomic checklist. | concise, planning | concise, planning, user, asks, plan, coding, task, generate, clear, actionable, atomic, checklist |
|
||||
| `context-compression` | Design and evaluate compression strategies for long-running sessions | compression | compression, context, evaluate, long, running, sessions |
|
||||
| `context-fundamentals` | Understand what context is, why it matters, and the anatomy of context in agent systems | fundamentals | fundamentals, context, understand, what, why, matters, anatomy, agent |
|
||||
@@ -401,7 +387,6 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
|
||||
| `nosql-expert` | Expert guidance for distributed NoSQL databases (Cassandra, DynamoDB). Focuses on mental models, query-first modeling, single-table design, and avoiding hot ... | nosql | nosql, guidance, distributed, databases, cassandra, dynamodb, mental, models, query, first, modeling, single |
|
||||
| `obsidian-clipper-template-creator` | Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format cli... | obsidian, clipper, creator | obsidian, clipper, creator, creating, web, want, new, clipping, understand, available, variables, format |
|
||||
| `onboarding-cro` | When the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Also use when the user mentions "onboarding ... | onboarding, cro | onboarding, cro, user, wants, optimize, post, signup, activation, first, run, experience, time |
|
||||
| `oss-hunter` | Automatically hunt for high-impact OSS contribution opportunities in trending repositories. | oss, hunter | oss, hunter, automatically, hunt, high, impact, contribution, opportunities, trending, repositories |
|
||||
| `paid-ads` | When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when ... | paid, ads | paid, ads, user, wants, advertising, campaigns, google, meta, facebook, instagram, linkedin, twitter |
|
||||
| `paypal-integration` | Integrate PayPal payment processing with support for express checkout, subscriptions, and refund management. Use when implementing PayPal payments, processin... | paypal, integration | paypal, integration, integrate, payment, processing, express, checkout, subscriptions, refund, implementing, payments, online |
|
||||
| `performance-profiling` | Performance profiling principles. Measurement, analysis, and optimization techniques. | performance, profiling | performance, profiling, principles, measurement, analysis, optimization, techniques |
|
||||
@@ -411,8 +396,8 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
|
||||
| `posix-shell-pro` | Expert in strict POSIX sh scripting for maximum portability across Unix-like systems. Specializes in shell scripts that run on any POSIX-compliant shell (das... | posix, shell | posix, shell, pro, strict, sh, scripting, maximum, portability, unix, like, specializes, scripts |
|
||||
| `pptx-official` | Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying o... | pptx, official | pptx, official, presentation, creation, editing, analysis, claude, work, presentations, files, creating, new |
|
||||
| `privilege-escalation-methods` | This skill should be used when the user asks to "escalate privileges", "get root access", "become administrator", "privesc techniques", "abuse sudo", "exploi... | privilege, escalation, methods | privilege, escalation, methods, skill, should, used, user, asks, escalate, privileges, get, root |
|
||||
| `prompt-engineer` | Transforms user prompts into optimized prompts using frameworks (RTF, RISEN, Chain of Thought, RODES, Chain of Density, RACE, RISE, STAR, SOAP, CLEAR, GROW) | prompt-engineering, optimization, frameworks, ai-enhancement | prompt-engineering, optimization, frameworks, ai-enhancement, prompt, engineer, transforms, user, prompts, optimized, rtf, risen |
|
||||
| `prompt-library` | Curated collection of high-quality prompts for various use cases. Includes role-based prompts, task-specific templates, and prompt refinement techniques. Use... | prompt, library | prompt, library, curated, collection, high, quality, prompts, various, cases, includes, role, task |
|
||||
| `readme` | When the user wants to create or update a README.md file for a project. Also use when the user says | readme | readme, user, wants, update, md, file, says |
|
||||
| `receiving-code-review` | Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technic... | receiving, code | receiving, code, review, feedback, before, implementing, suggestions, especially, seems, unclear, technically, questionable |
|
||||
| `referral-program` | When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy. Also use when the user mentions 'referr... | referral, program | referral, program, user, wants, optimize, analyze, affiliate, word, mouth, mentions, ambassador, viral |
|
||||
| `requesting-code-review` | Use when completing tasks, implementing major features, or before merging to verify work meets requirements | requesting, code | requesting, code, review, completing, tasks, implementing, major, features, before, merging, verify, work |
|
||||
@@ -420,6 +405,7 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
|
||||
| `sharp-edges` | Identify error-prone APIs and dangerous configurations | sharp, edges | sharp, edges, identify, error, prone, apis, dangerous, configurations |
|
||||
| `shellcheck-configuration` | Master ShellCheck static analysis configuration and usage for shell script quality. Use when setting up linting infrastructure, fixing code issues, or ensuri... | shellcheck, configuration | shellcheck, configuration, static, analysis, usage, shell, script, quality, setting, up, linting, infrastructure |
|
||||
| `signup-flow-cro` | When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the user mentions "signup conversions," "reg... | signup, flow, cro | signup, flow, cro, user, wants, optimize, registration, account, creation, trial, activation, flows |
|
||||
| `skill-creator` | Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capa... | skill, creator | skill, creator, creating, effective, skills, should, used, users, want, new, update, existing |
|
||||
| `skill-rails-upgrade` | Analyze Rails apps and provide upgrade assessments | skill, rails, upgrade | skill, rails, upgrade, analyze, apps, provide, assessments |
|
||||
| `slack-gif-creator` | Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users reques... | slack, gif, creator | slack, gif, creator, knowledge, utilities, creating, animated, gifs, optimized, provides, constraints, validation |
|
||||
| `social-content` | When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms. A... | social, content | social, content, user, wants, creating, scheduling, optimizing, media, linkedin, twitter, instagram, tiktok |
|
||||
@@ -441,9 +427,8 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
|
||||
| `writing-plans` | Use when you have a spec or requirements for a multi-step task, before touching code | writing, plans | writing, plans, spec, requirements, multi, step, task, before, touching, code |
|
||||
| `writing-skills` | Use when creating, updating, or improving agent skills. | writing, skills | writing, skills, creating, updating, improving, agent |
|
||||
| `x-article-publisher-skill` | Publish articles to X/Twitter | x, article, publisher, skill | x, article, publisher, skill, publish, articles, twitter |
|
||||
| `youtube-summarizer` | Extract transcripts from YouTube videos and generate comprehensive, detailed summaries using intelligent analysis frameworks | video, summarization, transcription, youtube, content-analysis | video, summarization, transcription, youtube, content-analysis, summarizer, extract, transcripts, videos, generate, detailed, summaries |
|
||||
|
||||
## infrastructure (83)
|
||||
## infrastructure (78)
|
||||
|
||||
| Skill | Description | Tags | Triggers |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -458,7 +443,6 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
|
||||
| `bash-defensive-patterns` | Master defensive Bash programming techniques for production-grade scripts. Use when writing robust shell scripts, CI/CD pipelines, or system utilities requir... | bash, defensive | bash, defensive, programming, techniques, grade, scripts, writing, robust, shell, ci, cd, pipelines |
|
||||
| `bash-pro` | Master of defensive Bash scripting for production automation, CI/CD pipelines, and system utilities. Expert in safe, portable, and testable shell scripts. | bash | bash, pro, defensive, scripting, automation, ci, cd, pipelines, utilities, safe, portable, testable |
|
||||
| `bats-testing-patterns` | Master Bash Automated Testing System (Bats) for comprehensive shell script testing. Use when writing tests for shell scripts, CI/CD pipelines, or requiring t... | bats | bats, testing, bash, automated, shell, script, writing, tests, scripts, ci, cd, pipelines |
|
||||
| `box-automation` | Automate Box cloud storage operations including file upload/download, search, folder management, sharing, collaborations, and metadata queries via Rube MCP (... | box | box, automation, automate, cloud, storage, operations, including, file, upload, download, search, folder |
|
||||
| `c4-container` | Expert C4 Container-level documentation specialist. Synthesizes Component-level documentation into Container-level architecture, mapping components to deploy... | c4, container | c4, container, level, documentation, synthesizes, component, architecture, mapping, components, deployment, units, documenting |
|
||||
| `claude-d3js-skill` | Creating interactive data visualisations using d3.js. This skill should be used when creating custom charts, graphs, network diagrams, geographic visualisati... | claude, d3js, skill | claude, d3js, skill, d3, viz, creating, interactive, data, visualisations, js, should, used |
|
||||
| `code-review-ai-ai-review` | You are an expert AI-powered code review specialist combining automated static analysis, intelligent pattern recognition, and modern DevOps practices. Levera... | code, ai | code, ai, review, powered, combining, automated, static, analysis, intelligent, recognition, devops, leverage |
|
||||
@@ -481,12 +465,10 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
|
||||
| `expo-deployment` | Deploy Expo apps to production | expo, deployment | expo, deployment, deploy, apps |
|
||||
| `file-uploads` | Expert at handling file uploads and cloud storage. Covers S3, Cloudflare R2, presigned URLs, multipart uploads, and image optimization. Knows how to handle l... | file, uploads | file, uploads, handling, cloud, storage, covers, s3, cloudflare, r2, presigned, urls, multipart |
|
||||
| `flutter-expert` | Master Flutter development with Dart 3, advanced widgets, and multi-platform deployment. Handles state management, animations, testing, and performance optim... | flutter | flutter, development, dart, widgets, multi, platform, deployment, state, animations, testing, performance, optimization |
|
||||
| `freshservice-automation` | Automate Freshservice ITSM tasks via Rube MCP (Composio): create/update tickets, bulk operations, service requests, and outbound emails. Always search tools ... | freshservice | freshservice, automation, automate, itsm, tasks, via, rube, mcp, composio, update, tickets, bulk |
|
||||
| `game-development/game-art` | Game art principles. Visual style selection, asset pipeline, animation workflow. | game, development/game, art | game, development/game, art, principles, visual, style, selection, asset, pipeline, animation |
|
||||
| `gcp-cloud-run` | Specialized skill for building production-ready serverless applications on GCP. Covers Cloud Run services (containerized), Cloud Run Functions (event-driven)... | gcp, cloud, run | gcp, cloud, run, specialized, skill, building, serverless, applications, covers, containerized, functions, event |
|
||||
| `git-pr-workflows-git-workflow` | Orchestrate a comprehensive git workflow from code review through PR creation, leveraging specialized agents for quality assurance, testing, and deployment r... | git, pr | git, pr, orchestrate, code, review, through, creation, leveraging, specialized, agents, quality, assurance |
|
||||
| `github-actions-templates` | Create production-ready GitHub Actions workflows for automated testing, building, and deploying applications. Use when setting up CI/CD with GitHub Actions, ... | github, actions | github, actions, automated, testing, building, deploying, applications, setting, up, ci, cd, automating |
|
||||
| `github-automation` | Automate GitHub repositories, issues, pull requests, branches, CI/CD, and permissions via Rube MCP (Composio). Manage code workflows, review PRs, search code... | github | github, automation, automate, repositories, issues, pull, requests, branches, ci, cd, permissions, via |
|
||||
| `github-workflow-automation` | Automate GitHub workflows with AI assistance. Includes PR reviews, issue triage, CI/CD integration, and Git operations. Use when automating GitHub workflows,... | github | github, automation, automate, ai, assistance, includes, pr, reviews, issue, triage, ci, cd |
|
||||
| `gitlab-ci-patterns` | Build GitLab CI/CD pipelines with multi-stage workflows, caching, and distributed runners for scalable automation. Use when implementing GitLab CI/CD, optimi... | gitlab, ci | gitlab, ci, cd, pipelines, multi, stage, caching, distributed, runners, scalable, automation, implementing |
|
||||
| `gitops-workflow` | Implement GitOps workflows with ArgoCD and Flux for automated, declarative Kubernetes deployments with continuous reconciliation. Use when implementing GitOp... | gitops | gitops, argocd, flux, automated, declarative, kubernetes, deployments, continuous, reconciliation, implementing, automating, setting |
|
||||
@@ -512,10 +494,8 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
|
||||
| `observability-monitoring-slo-implement` | You are an SLO (Service Level Objective) expert specializing in implementing reliability standards and error budget-based practices. Design SLO frameworks, d... | observability, monitoring, slo, implement | observability, monitoring, slo, implement, level, objective, specializing, implementing, reliability, standards, error, budget |
|
||||
| `performance-engineer` | Expert performance engineer specializing in modern observability, application optimization, and scalable system performance. Masters OpenTelemetry, distribut... | performance | performance, engineer, specializing, observability, application, optimization, scalable, masters, opentelemetry, distributed, tracing, load |
|
||||
| `performance-testing-review-ai-review` | You are an expert AI-powered code review specialist combining automated static analysis, intelligent pattern recognition, and modern DevOps practices. Levera... | performance, ai | performance, ai, testing, review, powered, code, combining, automated, static, analysis, intelligent, recognition |
|
||||
| `pipedrive-automation` | Automate Pipedrive CRM operations including deals, contacts, organizations, activities, notes, and pipeline management via Rube MCP (Composio). Always search... | pipedrive | pipedrive, automation, automate, crm, operations, including, deals, contacts, organizations, activities, notes, pipeline |
|
||||
| `prometheus-configuration` | Set up Prometheus for comprehensive metric collection, storage, and monitoring of infrastructure and applications. Use when implementing metrics collection, ... | prometheus, configuration | prometheus, configuration, set, up, metric, collection, storage, monitoring, infrastructure, applications, implementing, metrics |
|
||||
| `protocol-reverse-engineering` | Master network protocol reverse engineering including packet analysis, protocol dissection, and custom protocol documentation. Use when analyzing network tra... | protocol, reverse, engineering | protocol, reverse, engineering, network, including, packet, analysis, dissection, custom, documentation, analyzing, traffic |
|
||||
| `readme` | When the user wants to create or update a README.md file for a project. Also use when the user says 'write readme,' 'create readme,' 'document this project,'... | readme | readme, user, wants, update, md, file, says, write, document, documentation, asks, skill |
|
||||
| `server-management` | Server management principles and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands. | server | server, principles, decision, making, process, monitoring, scaling, decisions, teaches, thinking, commands |
|
||||
| `service-mesh-observability` | Implement comprehensive observability for service meshes including distributed tracing, metrics, and visualization. Use when setting up mesh monitoring, debu... | service, mesh, observability | service, mesh, observability, meshes, including, distributed, tracing, metrics, visualization, setting, up, monitoring |
|
||||
| `slo-implementation` | Define and implement Service Level Indicators (SLIs) and Service Level Objectives (SLOs) with error budgets and alerting. Use when establishing reliability t... | slo | slo, define, level, indicators, slis, objectives, slos, error, budgets, alerting, establishing, reliability |
|
||||
@@ -525,13 +505,13 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
|
||||
| `terraform-skill` | Terraform infrastructure as code best practices | terraform, skill | terraform, skill, infrastructure, code |
|
||||
| `test-automator` | Master AI-powered test automation with modern frameworks, self-healing tests, and comprehensive quality engineering. Build scalable testing strategies with a... | automator | automator, test, ai, powered, automation, frameworks, self, healing, tests, quality, engineering, scalable |
|
||||
| `unity-developer` | Build Unity games with optimized C# scripts, efficient rendering, and proper asset management. Masters Unity 6 LTS, URP/HDRP pipelines, and cross-platform de... | unity | unity, developer, games, optimized, scripts, efficient, rendering, proper, asset, masters, lts, urp |
|
||||
| `vercel-deploy-claimable` | Deploy applications and websites to Vercel. Use this skill when the user requests deployment actions such as 'Deploy my app', 'Deploy this to production', 'C... | vercel, deploy, claimable | vercel, deploy, claimable, applications, websites, skill, user, requests, deployment, actions, such, my |
|
||||
| `vercel-deploy-claimable` | Deploy applications and websites to Vercel. Use this skill when the user requests deployment actions such as | vercel, deploy, claimable | vercel, deploy, claimable, applications, websites, skill, user, requests, deployment, actions, such |
|
||||
| `vercel-deployment` | Expert knowledge for deploying to Vercel with Next.js Use when: vercel, deploy, deployment, hosting, production. | vercel, deployment | vercel, deployment, knowledge, deploying, next, js, deploy, hosting |
|
||||
| `voice-agents` | Voice agents represent the frontier of AI interaction - humans speaking naturally with AI systems. The challenge isn't just speech recognition and synthesis,... | voice, agents | voice, agents, represent, frontier, ai, interaction, humans, speaking, naturally, challenge, isn, just |
|
||||
| `wireshark-analysis` | This skill should be used when the user asks to "analyze network traffic with Wireshark", "capture packets for troubleshooting", "filter PCAP files", "follow... | wireshark | wireshark, network, traffic, analysis, skill, should, used, user, asks, analyze, capture, packets |
|
||||
| `workflow-automation` | Workflow automation is the infrastructure that makes AI agents reliable. Without durable execution, a network hiccup during a 10-step payment flow means lost... | | automation, infrastructure, makes, ai, agents, reliable, without, durable, execution, network, hiccup, during |
|
||||
|
||||
## security (113)
|
||||
## security (112)
|
||||
|
||||
| Skill | Description | Tags | Triggers |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -565,7 +545,6 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
|
||||
| `design-orchestration` | Orchestrates design workflows by routing work through brainstorming, multi-agent review, and execution readiness in the correct order. Prevents premature imp... | | orchestration, orchestrates, routing, work, through, brainstorming, multi, agent, review, execution, readiness, correct |
|
||||
| `devops-troubleshooter` | Expert DevOps troubleshooter specializing in rapid incident response, advanced debugging, and modern observability. Masters log analysis, distributed tracing... | devops, troubleshooter | devops, troubleshooter, specializing, rapid, incident, response, debugging, observability, masters, log, analysis, distributed |
|
||||
| `docker-expert` | Docker containerization expert with deep knowledge of multi-stage builds, image optimization, container security, Docker Compose orchestration, and productio... | docker | docker, containerization, deep, knowledge, multi, stage, image, optimization, container, security, compose, orchestration |
|
||||
| `dotnet-backend` | Build ASP.NET Core 8+ backend services with EF Core, auth, background jobs, and production API patterns. | dotnet, backend | dotnet, backend, asp, net, core, ef, auth, background, jobs, api |
|
||||
| `ethical-hacking-methodology` | This skill should be used when the user asks to "learn ethical hacking", "understand penetration testing lifecycle", "perform reconnaissance", "conduct secur... | ethical, hacking, methodology | ethical, hacking, methodology, skill, should, used, user, asks, learn, understand, penetration, testing |
|
||||
| `file-path-traversal` | This skill should be used when the user asks to "test for directory traversal", "exploit path traversal vulnerabilities", "read arbitrary files through web a... | file, path, traversal | file, path, traversal, testing, skill, should, used, user, asks, test, directory, exploit |
|
||||
| `find-bugs` | Find bugs, security vulnerabilities, and code quality issues in local branch changes. Use when asked to review changes, find bugs, security review, or audit ... | find, bugs | find, bugs, security, vulnerabilities, code, quality, issues, local, branch, changes, asked, review |
|
||||
@@ -649,12 +628,11 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
|
||||
| `wordpress-penetration-testing` | This skill should be used when the user asks to "pentest WordPress sites", "scan WordPress for vulnerabilities", "enumerate WordPress users, themes, or plugi... | wordpress, penetration | wordpress, penetration, testing, skill, should, used, user, asks, pentest, sites, scan, vulnerabilities |
|
||||
| `xss-html-injection` | This skill should be used when the user asks to "test for XSS vulnerabilities", "perform cross-site scripting attacks", "identify HTML injection flaws", "exp... | xss, html, injection | xss, html, injection, cross, site, scripting, testing, skill, should, used, user, asks |
|
||||
|
||||
## testing (23)
|
||||
## testing (22)
|
||||
|
||||
| Skill | Description | Tags | Triggers |
|
||||
| --- | --- | --- | --- |
|
||||
| `ab-test-setup` | Structured guide for setting up A/B tests with mandatory gates for hypothesis, metrics, and execution readiness. | ab, setup | ab, setup, test, structured, setting, up, tests, mandatory, gates, hypothesis, metrics, execution |
|
||||
| `circleci-automation` | Automate CircleCI tasks via Rube MCP (Composio): trigger pipelines, monitor workflows/jobs, retrieve artifacts and test metadata. Always search tools first f... | circleci | circleci, automation, automate, tasks, via, rube, mcp, composio, trigger, pipelines, monitor, jobs |
|
||||
| `conductor-implement` | Execute tasks from a track's implementation plan following TDD workflow | conductor, implement | conductor, implement, execute, tasks, track, plan, following, tdd |
|
||||
| `conductor-revert` | Git-aware undo by logical work unit (track, phase, or task) | conductor, revert | conductor, revert, git, aware, undo, logical, work, unit, track, phase, task |
|
||||
| `debugger` | Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues. | debugger | debugger, debugging, errors, test, failures, unexpected, behavior, proactively, encountering, any, issues |
|
||||
@@ -677,88 +655,23 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
|
||||
| `unit-testing-test-generate` | Generate comprehensive, maintainable unit tests across languages with strong coverage and edge case focus. | unit, generate | unit, generate, testing, test, maintainable, tests, languages, strong, coverage, edge, case |
|
||||
| `web3-testing` | Test smart contracts comprehensively using Hardhat and Foundry with unit tests, integration tests, and mainnet forking. Use when testing Solidity contracts, ... | web3 | web3, testing, test, smart, contracts, comprehensively, hardhat, foundry, unit, tests, integration, mainnet |
|
||||
|
||||
## workflow (81)
|
||||
## workflow (16)
|
||||
|
||||
| Skill | Description | Tags | Triggers |
|
||||
| --- | --- | --- | --- |
|
||||
| `activecampaign-automation` | Automate ActiveCampaign tasks via Rube MCP (Composio): manage contacts, tags, list subscriptions, automation enrollment, and tasks. Always search tools first... | activecampaign | activecampaign, automation, automate, tasks, via, rube, mcp, composio, contacts, tags, list, subscriptions |
|
||||
| `agent-orchestration-improve-agent` | Systematic improvement of existing agents through performance analysis, prompt engineering, and continuous iteration. | agent, improve | agent, improve, orchestration, systematic, improvement, existing, agents, through, performance, analysis, prompt, engineering |
|
||||
| `agent-orchestration-multi-agent-optimize` | Optimize multi-agent systems with coordinated profiling, workload distribution, and cost-aware orchestration. Use when improving agent performance, throughpu... | agent, multi, optimize | agent, multi, optimize, orchestration, coordinated, profiling, workload, distribution, cost, aware, improving, performance |
|
||||
| `airtable-automation` | Automate Airtable tasks via Rube MCP (Composio): records, bases, tables, fields, views. Always search tools first for current schemas. | airtable | airtable, automation, automate, tasks, via, rube, mcp, composio, records, bases, tables, fields |
|
||||
| `amplitude-automation` | Automate Amplitude tasks via Rube MCP (Composio): events, user activity, cohorts, user identification. Always search tools first for current schemas. | amplitude | amplitude, automation, automate, tasks, via, rube, mcp, composio, events, user, activity, cohorts |
|
||||
| `asana-automation` | Automate Asana tasks via Rube MCP (Composio): tasks, projects, sections, teams, workspaces. Always search tools first for current schemas. | asana | asana, automation, automate, tasks, via, rube, mcp, composio, sections, teams, workspaces, always |
|
||||
| `bamboohr-automation` | Automate BambooHR tasks via Rube MCP (Composio): employees, time-off, benefits, dependents, employee updates. Always search tools first for current schemas. | bamboohr | bamboohr, automation, automate, tasks, via, rube, mcp, composio, employees, time, off, benefits |
|
||||
| `basecamp-automation` | Automate Basecamp project management, to-dos, messages, people, and to-do list organization via Rube MCP (Composio). Always search tools first for current sc... | basecamp | basecamp, automation, automate, dos, messages, people, do, list, organization, via, rube, mcp |
|
||||
| `billing-automation` | Build automated billing systems for recurring payments, invoicing, subscription lifecycle, and dunning management. Use when implementing subscription billing... | billing | billing, automation, automated, recurring, payments, invoicing, subscription, lifecycle, dunning, implementing, automating, managing |
|
||||
| `bitbucket-automation` | Automate Bitbucket repositories, pull requests, branches, issues, and workspace management via Rube MCP (Composio). Always search tools first for current sch... | bitbucket | bitbucket, automation, automate, repositories, pull, requests, branches, issues, workspace, via, rube, mcp |
|
||||
| `brevo-automation` | Automate Brevo (Sendinblue) tasks via Rube MCP (Composio): manage email campaigns, create/edit templates, track senders, and monitor campaign performance. Al... | brevo | brevo, automation, automate, sendinblue, tasks, via, rube, mcp, composio, email, campaigns, edit |
|
||||
| `cal-com-automation` | Automate Cal.com tasks via Rube MCP (Composio): manage bookings, check availability, configure webhooks, and handle teams. Always search tools first for curr... | cal, com | cal, com, automation, automate, tasks, via, rube, mcp, composio, bookings, check, availability |
|
||||
| `canva-automation` | Automate Canva tasks via Rube MCP (Composio): designs, exports, folders, brand templates, autofill. Always search tools first for current schemas. | canva | canva, automation, automate, tasks, via, rube, mcp, composio, designs, exports, folders, brand |
|
||||
| `changelog-automation` | Automate changelog generation from commits, PRs, and releases following Keep a Changelog format. Use when setting up release workflows, generating release no... | changelog | changelog, automation, automate, generation, commits, prs, releases, following, keep, format, setting, up |
|
||||
| `clickup-automation` | Automate ClickUp project management including tasks, spaces, folders, lists, comments, and team operations via Rube MCP (Composio). Always search tools first... | clickup | clickup, automation, automate, including, tasks, spaces, folders, lists, comments, team, operations, via |
|
||||
| `close-automation` | Automate Close CRM tasks via Rube MCP (Composio): create leads, manage calls/SMS, handle tasks, and track notes. Always search tools first for current schemas. | close | close, automation, automate, crm, tasks, via, rube, mcp, composio, leads, calls, sms |
|
||||
| `coda-automation` | Automate Coda tasks via Rube MCP (Composio): manage docs, pages, tables, rows, formulas, permissions, and publishing. Always search tools first for current s... | coda | coda, automation, automate, tasks, via, rube, mcp, composio, docs, pages, tables, rows |
|
||||
| `conductor-manage` | Manage track lifecycle: archive, restore, delete, rename, and cleanup | conductor, manage | conductor, manage, track, lifecycle, archive, restore, delete, rename, cleanup |
|
||||
| `conductor-new-track` | Create a new track with specification and phased implementation plan | conductor, new, track | conductor, new, track, specification, phased, plan |
|
||||
| `conductor-status` | Display project status, active tracks, and next actions | conductor, status | conductor, status, display, active, tracks, next, actions |
|
||||
| `conductor-validator` | Validates Conductor project artifacts for completeness, consistency, and correctness. Use after setup, when diagnosing issues, or before implementation to ve... | conductor, validator | conductor, validator, validates, artifacts, completeness, consistency, correctness, after, setup, diagnosing, issues, before |
|
||||
| `confluence-automation` | Automate Confluence page creation, content search, space management, labels, and hierarchy navigation via Rube MCP (Composio). Always search tools first for ... | confluence | confluence, automation, automate, page, creation, content, search, space, labels, hierarchy, navigation, via |
|
||||
| `convertkit-automation` | Automate ConvertKit (Kit) tasks via Rube MCP (Composio): manage subscribers, tags, broadcasts, and broadcast stats. Always search tools first for current sch... | convertkit | convertkit, automation, automate, kit, tasks, via, rube, mcp, composio, subscribers, tags, broadcasts |
|
||||
| `datadog-automation` | Automate Datadog tasks via Rube MCP (Composio): query metrics, search logs, manage monitors/dashboards, create events and downtimes. Always search tools firs... | datadog | datadog, automation, automate, tasks, via, rube, mcp, composio, query, metrics, search, logs |
|
||||
| `discord-automation` | Automate Discord tasks via Rube MCP (Composio): messages, channels, roles, webhooks, reactions. Always search tools first for current schemas. | discord | discord, automation, automate, tasks, via, rube, mcp, composio, messages, channels, roles, webhooks |
|
||||
| `docusign-automation` | Automate DocuSign tasks via Rube MCP (Composio): templates, envelopes, signatures, document management. Always search tools first for current schemas. | docusign | docusign, automation, automate, tasks, via, rube, mcp, composio, envelopes, signatures, document, always |
|
||||
| `dropbox-automation` | Automate Dropbox file management, sharing, search, uploads, downloads, and folder operations via Rube MCP (Composio). Always search tools first for current s... | dropbox | dropbox, automation, automate, file, sharing, search, uploads, downloads, folder, operations, via, rube |
|
||||
| `email-sequence` | When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions... | email, sequence | email, sequence, user, wants, optimize, drip, campaign, automated, flow, lifecycle, program, mentions |
|
||||
| `figma-automation` | Automate Figma tasks via Rube MCP (Composio): files, components, design tokens, comments, exports. Always search tools first for current schemas. | figma | figma, automation, automate, tasks, via, rube, mcp, composio, files, components, tokens, comments |
|
||||
| `freshdesk-automation` | Automate Freshdesk helpdesk operations including tickets, contacts, companies, notes, and replies via Rube MCP (Composio). Always search tools first for curr... | freshdesk | freshdesk, automation, automate, helpdesk, operations, including, tickets, contacts, companies, notes, replies, via |
|
||||
| `full-stack-orchestration-full-stack-feature` | Use when working with full stack orchestration full stack feature | full, stack | full, stack, orchestration, feature, working |
|
||||
| `git-pushing` | Stage, commit, and push git changes with conventional commit messages. Use when user wants to commit and push changes, mentions pushing to remote, or asks to... | git, pushing | git, pushing, stage, commit, push, changes, conventional, messages, user, wants, mentions, remote |
|
||||
| `gitlab-automation` | Automate GitLab project management, issues, merge requests, pipelines, branches, and user operations via Rube MCP (Composio). Always search tools first for c... | gitlab | gitlab, automation, automate, issues, merge, requests, pipelines, branches, user, operations, via, rube |
|
||||
| `gmail-automation` | Automate Gmail tasks via Rube MCP (Composio): send/reply, search, labels, drafts, attachments. Always search tools first for current schemas. | gmail | gmail, automation, automate, tasks, via, rube, mcp, composio, send, reply, search, labels |
|
||||
| `google-calendar-automation` | Automate Google Calendar events, scheduling, availability checks, and attendee management via Rube MCP (Composio). Create events, find free slots, manage att... | google, calendar | google, calendar, automation, automate, events, scheduling, availability, checks, attendee, via, rube, mcp |
|
||||
| `google-drive-automation` | Automate Google Drive file operations (upload, download, search, share, organize) via Rube MCP (Composio). Upload/download files, manage folders, share with ... | google, drive | google, drive, automation, automate, file, operations, upload, download, search, share, organize, via |
|
||||
| `helpdesk-automation` | Automate HelpDesk tasks via Rube MCP (Composio): list tickets, manage views, use canned responses, and configure custom fields. Always search tools first for... | helpdesk | helpdesk, automation, automate, tasks, via, rube, mcp, composio, list, tickets, views, canned |
|
||||
| `hubspot-automation` | Automate HubSpot CRM operations (contacts, companies, deals, tickets, properties) via Rube MCP using Composio integration. | hubspot | hubspot, automation, automate, crm, operations, contacts, companies, deals, tickets, properties, via, rube |
|
||||
| `instagram-automation` | Automate Instagram tasks via Rube MCP (Composio): create posts, carousels, manage media, get insights, and publishing limits. Always search tools first for c... | instagram | instagram, automation, automate, tasks, via, rube, mcp, composio, posts, carousels, media, get |
|
||||
| `intercom-automation` | Automate Intercom tasks via Rube MCP (Composio): conversations, contacts, companies, segments, admins. Always search tools first for current schemas. | intercom | intercom, automation, automate, tasks, via, rube, mcp, composio, conversations, contacts, companies, segments |
|
||||
| `jira-automation` | Automate Jira tasks via Rube MCP (Composio): issues, projects, sprints, boards, comments, users. Always search tools first for current schemas. | jira | jira, automation, automate, tasks, via, rube, mcp, composio, issues, sprints, boards, comments |
|
||||
| `kaizen` | Guide for continuous improvement, error proofing, and standardization. Use this skill when the user wants to improve code quality, refactor, or discuss proce... | kaizen | kaizen, continuous, improvement, error, proofing, standardization, skill, user, wants, improve, code, quality |
|
||||
| `klaviyo-automation` | Automate Klaviyo tasks via Rube MCP (Composio): manage email/SMS campaigns, inspect campaign messages, track tags, and monitor send jobs. Always search tools... | klaviyo | klaviyo, automation, automate, tasks, via, rube, mcp, composio, email, sms, campaigns, inspect |
|
||||
| `linear-automation` | Automate Linear tasks via Rube MCP (Composio): issues, projects, cycles, teams, labels. Always search tools first for current schemas. | linear | linear, automation, automate, tasks, via, rube, mcp, composio, issues, cycles, teams, labels |
|
||||
| `linkedin-automation` | Automate LinkedIn tasks via Rube MCP (Composio): create posts, manage profile, company info, comments, and image uploads. Always search tools first for curre... | linkedin | linkedin, automation, automate, tasks, via, rube, mcp, composio, posts, profile, company, info |
|
||||
| `make-automation` | Automate Make (Integromat) tasks via Rube MCP (Composio): operations, enums, language and timezone lookups. Always search tools first for current schemas. | make | make, automation, automate, integromat, tasks, via, rube, mcp, composio, operations, enums, language |
|
||||
| `mermaid-expert` | Create Mermaid diagrams for flowcharts, sequences, ERDs, and architectures. Masters syntax for all diagram types and styling. Use PROACTIVELY for visual docu... | mermaid | mermaid, diagrams, flowcharts, sequences, erds, architectures, masters, syntax, all, diagram, types, styling |
|
||||
| `microsoft-teams-automation` | Automate Microsoft Teams tasks via Rube MCP (Composio): send messages, manage channels, create meetings, handle chats, and search messages. Always search too... | microsoft, teams | microsoft, teams, automation, automate, tasks, via, rube, mcp, composio, send, messages, channels |
|
||||
| `miro-automation` | Automate Miro tasks via Rube MCP (Composio): boards, items, sticky notes, frames, sharing, connectors. Always search tools first for current schemas. | miro | miro, automation, automate, tasks, via, rube, mcp, composio, boards, items, sticky, notes |
|
||||
| `mixpanel-automation` | Automate Mixpanel tasks via Rube MCP (Composio): events, segmentation, funnels, cohorts, user profiles, JQL queries. Always search tools first for current sc... | mixpanel | mixpanel, automation, automate, tasks, via, rube, mcp, composio, events, segmentation, funnels, cohorts |
|
||||
| `monday-automation` | Automate Monday.com work management including boards, items, columns, groups, subitems, and updates via Rube MCP (Composio). Always search tools first for cu... | monday | monday, automation, automate, com, work, including, boards, items, columns, groups, subitems, updates |
|
||||
| `notion-automation` | Automate Notion tasks via Rube MCP (Composio): pages, databases, blocks, comments, users. Always search tools first for current schemas. | notion | notion, automation, automate, tasks, via, rube, mcp, composio, pages, databases, blocks, comments |
|
||||
| `one-drive-automation` | Automate OneDrive file management, search, uploads, downloads, sharing, permissions, and folder operations via Rube MCP (Composio). Always search tools first... | one, drive | one, drive, automation, automate, onedrive, file, search, uploads, downloads, sharing, permissions, folder |
|
||||
| `outlook-automation` | Automate Outlook tasks via Rube MCP (Composio): emails, calendar, contacts, folders, attachments. Always search tools first for current schemas. | outlook | outlook, automation, automate, tasks, via, rube, mcp, composio, emails, calendar, contacts, folders |
|
||||
| `outlook-calendar-automation` | Automate Outlook Calendar tasks via Rube MCP (Composio): create events, manage attendees, find meeting times, and handle invitations. Always search tools fir... | outlook, calendar | outlook, calendar, automation, automate, tasks, via, rube, mcp, composio, events, attendees, find |
|
||||
| `pagerduty-automation` | Automate PagerDuty tasks via Rube MCP (Composio): manage incidents, services, schedules, escalation policies, and on-call rotations. Always search tools firs... | pagerduty | pagerduty, automation, automate, tasks, via, rube, mcp, composio, incidents, schedules, escalation, policies |
|
||||
| `pdf-official` | Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs ... | pdf, official | pdf, official, manipulation, toolkit, extracting, text, tables, creating, new, pdfs, merging, splitting |
|
||||
| `posthog-automation` | Automate PostHog tasks via Rube MCP (Composio): events, feature flags, projects, user profiles, annotations. Always search tools first for current schemas. | posthog | posthog, automation, automate, tasks, via, rube, mcp, composio, events, feature, flags, user |
|
||||
| `postmark-automation` | Automate Postmark email delivery tasks via Rube MCP (Composio): send templated emails, manage templates, monitor delivery stats and bounces. Always search to... | postmark | postmark, automation, automate, email, delivery, tasks, via, rube, mcp, composio, send, templated |
|
||||
| `reddit-automation` | Automate Reddit tasks via Rube MCP (Composio): search subreddits, create posts, manage comments, and browse top content. Always search tools first for curren... | reddit | reddit, automation, automate, tasks, via, rube, mcp, composio, search, subreddits, posts, comments |
|
||||
| `render-automation` | Automate Render tasks via Rube MCP (Composio): services, deployments, projects. Always search tools first for current schemas. | render | render, automation, automate, tasks, via, rube, mcp, composio, deployments, always, search, first |
|
||||
| `salesforce-automation` | Automate Salesforce tasks via Rube MCP (Composio): leads, contacts, accounts, opportunities, SOQL queries. Always search tools first for current schemas. | salesforce | salesforce, automation, automate, tasks, via, rube, mcp, composio, leads, contacts, accounts, opportunities |
|
||||
| `segment-automation` | Automate Segment tasks via Rube MCP (Composio): track events, identify users, manage groups, page views, aliases, batch operations. Always search tools first... | segment | segment, automation, automate, tasks, via, rube, mcp, composio, track, events, identify, users |
|
||||
| `sentry-automation` | Automate Sentry tasks via Rube MCP (Composio): manage issues/events, configure alerts, track releases, monitor projects and teams. Always search tools first ... | sentry | sentry, automation, automate, tasks, via, rube, mcp, composio, issues, events, configure, alerts |
|
||||
| `shopify-automation` | Automate Shopify tasks via Rube MCP (Composio): products, orders, customers, inventory, collections. Always search tools first for current schemas. | shopify | shopify, automation, automate, tasks, via, rube, mcp, composio, products, orders, customers, inventory |
|
||||
| `skill-creator` | This skill should be used when the user asks to create a new skill, build a skill, make a custom skill, develop a CLI skill, or wants to extend the CLI with ... | automation, scaffolding, skill-creation, meta-skill | automation, scaffolding, skill-creation, meta-skill, skill, creator, should, used, user, asks, new, custom |
|
||||
| `square-automation` | Automate Square tasks via Rube MCP (Composio): payments, orders, invoices, locations. Always search tools first for current schemas. | square | square, automation, automate, tasks, via, rube, mcp, composio, payments, orders, invoices, locations |
|
||||
| `stripe-automation` | Automate Stripe tasks via Rube MCP (Composio): customers, charges, subscriptions, invoices, products, refunds. Always search tools first for current schemas. | stripe | stripe, automation, automate, tasks, via, rube, mcp, composio, customers, charges, subscriptions, invoices |
|
||||
| `team-collaboration-issue` | You are a GitHub issue resolution expert specializing in systematic bug investigation, feature implementation, and collaborative development workflows. Your ... | team, collaboration, issue | team, collaboration, issue, github, resolution, specializing, systematic, bug, investigation, feature, collaborative, development |
|
||||
| `telegram-automation` | Automate Telegram tasks via Rube MCP (Composio): send messages, manage chats, share photos/documents, and handle bot commands. Always search tools first for ... | telegram | telegram, automation, automate, tasks, via, rube, mcp, composio, send, messages, chats, share |
|
||||
| `tiktok-automation` | Automate TikTok tasks via Rube MCP (Composio): upload/publish videos, post photos, manage content, and view user profiles/stats. Always search tools first fo... | tiktok | tiktok, automation, automate, tasks, via, rube, mcp, composio, upload, publish, videos, post |
|
||||
| `todoist-automation` | Automate Todoist task management, projects, sections, filtering, and bulk operations via Rube MCP (Composio). Always search tools first for current schemas. | todoist | todoist, automation, automate, task, sections, filtering, bulk, operations, via, rube, mcp, composio |
|
||||
| `track-management` | Use this skill when creating, managing, or working with Conductor tracks - the logical work units for features, bugs, and refactors. Applies to spec.md, plan... | track | track, skill, creating, managing, working, conductor, tracks, logical, work, units, features, bugs |
|
||||
| `trello-automation` | Automate Trello boards, cards, and workflows via Rube MCP (Composio). Create cards, manage lists, assign members, and search across boards programmatically. | trello | trello, automation, automate, boards, cards, via, rube, mcp, composio, lists, assign, members |
|
||||
| `twitter-automation` | Automate Twitter/X tasks via Rube MCP (Composio): posts, search, users, bookmarks, lists, media. Always search tools first for current schemas. | twitter | twitter, automation, automate, tasks, via, rube, mcp, composio, posts, search, users, bookmarks |
|
||||
| `vercel-automation` | Automate Vercel tasks via Rube MCP (Composio): manage deployments, domains, DNS, env vars, projects, and teams. Always search tools first for current schemas. | vercel | vercel, automation, automate, tasks, via, rube, mcp, composio, deployments, domains, dns, env |
|
||||
| `webflow-automation` | Automate Webflow CMS collections, site publishing, page management, asset uploads, and ecommerce orders via Rube MCP (Composio). Always search tools first fo... | webflow | webflow, automation, automate, cms, collections, site, publishing, page, asset, uploads, ecommerce, orders |
|
||||
| `wrike-automation` | Automate Wrike project management via Rube MCP (Composio): create tasks/folders, manage projects, assign work, and track progress. Always search tools first ... | wrike | wrike, automation, automate, via, rube, mcp, composio, tasks, folders, assign, work, track |
|
||||
| `zendesk-automation` | Automate Zendesk tasks via Rube MCP (Composio): tickets, users, organizations, replies. Always search tools first for current schemas. | zendesk | zendesk, automation, automate, tasks, via, rube, mcp, composio, tickets, users, organizations, replies |
|
||||
| `zoho-crm-automation` | Automate Zoho CRM tasks via Rube MCP (Composio): create/update records, search contacts, manage leads, and convert leads. Always search tools first for curre... | zoho, crm | zoho, crm, automation, automate, tasks, via, rube, mcp, composio, update, records, search |
|
||||
| `zoom-automation` | Automate Zoom meeting creation, management, recordings, webinars, and participant tracking via Rube MCP (Composio). Always search tools first for current sch... | zoom | zoom, automation, automate, meeting, creation, recordings, webinars, participant, tracking, via, rube, mcp |
|
||||
|
||||
47
CHANGELOG.md
47
CHANGELOG.md
@@ -7,53 +7,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
|
||||
---
|
||||
|
||||
## [4.10.0] - 2026-02-06 - "Composio Automation + .NET Backend"
|
||||
|
||||
> Merged two community PRs adding broad automation coverage and a dedicated .NET backend skill.
|
||||
|
||||
### Added
|
||||
|
||||
- **79 new skills total**:
|
||||
- **78 Composio/Rube automation skills** across CRM, productivity, comms, analytics, support, and DevOps tools (PR #64).
|
||||
- **1 new `.NET backend` skill** for ASP.NET Core enterprise APIs (PR #65).
|
||||
- **Registry** now tracks **713 skills** (from 634).
|
||||
|
||||
### Changed
|
||||
|
||||
- Synced generated registry artifacts after merges:
|
||||
- `README.md`
|
||||
- `skills_index.json`
|
||||
- `CATALOG.md`
|
||||
- `data/catalog.json`
|
||||
- `data/bundles.json`
|
||||
- `data/aliases.json`
|
||||
|
||||
### Contributors
|
||||
|
||||
- [@sohamganatra](https://github.com/sohamganatra) - 78 Composio automation skills (PR #64)
|
||||
- [@Nguyen-Van-Chan](https://github.com/Nguyen-Van-Chan) - .NET backend skill (PR #65)
|
||||
|
||||
## [4.9.0] - 2026-02-05 - "OSS Hunter & Universal Skills"
|
||||
|
||||
> Automated contribution hunting and universal CLI AI skills (Audio, YouTube, Prompt Engineering).
|
||||
|
||||
### Added
|
||||
|
||||
- **New Skill**: `oss-hunter` – Automated tool for finding high-impact Open Source contributions (Good First Issues, Help Wanted) in trending repositories.
|
||||
- **New Skill**: `audio-transcriber` – Transform audio recordings into professional Markdown with Whisper integration.
|
||||
- **New Skill**: `youtube-summarizer` – Generate comprehensive summaries/notes from YouTube videos.
|
||||
- **New Skill**: `prompt-engineer` (Enhanced) – Now includes 11 optimization frameworks (RTF, RISEN, etc.).
|
||||
- **Registry**: 634 skills (from 626). Catalog regenerated.
|
||||
|
||||
### Changed
|
||||
|
||||
- **CLI AI Skills**: Merged core skills from `ericgandrade/cli-ai-skills`.
|
||||
|
||||
### Contributors
|
||||
|
||||
- [@jackjin1997](https://github.com/jackjin1997) - OSS Hunter (PR #61)
|
||||
- [@ericgandrade](https://github.com/ericgandrade) - CLI AI Skills (PR #62)
|
||||
|
||||
## [4.7.0] - 2026-02-03 - "Installer Fix & OpenCode Docs"
|
||||
|
||||
> Critical installer fix for Windows and OpenCode documentation completion.
|
||||
|
||||
108
README.md
108
README.md
@@ -1,6 +1,6 @@
|
||||
# 🌌 Antigravity Awesome Skills: 713+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More
|
||||
# 🌌 Antigravity Awesome Skills: 626+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More
|
||||
|
||||
> **The Ultimate Collection of 713+ Universal Agentic Skills for AI Coding Assistants — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode, AdaL**
|
||||
> **The Ultimate Collection of 626+ Universal Agentic Skills for AI Coding Assistants — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode, AdaL**
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://claude.ai)
|
||||
@@ -10,10 +10,9 @@
|
||||
[](https://github.com/features/copilot)
|
||||
[](https://github.com/opencode-ai/opencode)
|
||||
[](https://github.com/sickn33/antigravity-awesome-skills)
|
||||
[](https://sylph.ai/)
|
||||
[](https://github.com/yeasy/ask)
|
||||
[](https://github.com/HumanSignal/Adala)
|
||||
|
||||
**Antigravity Awesome Skills** is a curated, battle-tested library of **713 high-performance agentic skills** designed to work seamlessly across all major AI coding assistants:
|
||||
**Antigravity Awesome Skills** is a curated, battle-tested library of **626 high-performance agentic skills** designed to work seamlessly across all major AI coding assistants:
|
||||
|
||||
- 🟣 **Claude Code** (Anthropic CLI)
|
||||
- 🔵 **Gemini CLI** (Google DeepMind)
|
||||
@@ -22,7 +21,7 @@
|
||||
- 🩵 **GitHub Copilot** (VSCode Extension)
|
||||
- 🟠 **Cursor** (AI-native IDE)
|
||||
- ⚪ **OpenCode** (Open-source CLI)
|
||||
- 🌸 **AdaL CLI** (Self-evolving Coding Agent)
|
||||
- 🌸 **AdaL** (Self-evolving AI Agent)
|
||||
|
||||
This repository provides essential skills to transform your AI assistant into a **full-stack digital agency**, including official capabilities from **Anthropic**, **OpenAI**, **Google**, **Supabase**, and **Vercel Labs**.
|
||||
|
||||
@@ -32,7 +31,7 @@ This repository provides essential skills to transform your AI assistant into a
|
||||
- [🔌 Compatibility & Invocation](#compatibility--invocation)
|
||||
- [📦 Features & Categories](#features--categories)
|
||||
- [🎁 Curated Collections (Bundles)](#curated-collections)
|
||||
- [📚 Browse 713+ Skills](#browse-713-skills)
|
||||
- [📚 Browse 626+ Skills](#browse-626-skills)
|
||||
- [🛠️ Installation](#installation)
|
||||
- [🤝 How to Contribute](#how-to-contribute)
|
||||
- [👥 Contributors & Credits](#credits--sources)
|
||||
@@ -87,16 +86,16 @@ Once installed, just ask your agent naturally:
|
||||
|
||||
These skills follow the universal **SKILL.md** format and work with any AI coding assistant that supports agentic skills.
|
||||
|
||||
| Tool | Type | Invocation Example | Path |
|
||||
| :-------------- | :--- | :-------------------------------- | :---------------- |
|
||||
| **Claude Code** | CLI | `>> /skill-name help me...` | `.claude/skills/` |
|
||||
| **Gemini CLI** | CLI | `(User Prompt) Use skill-name...` | `.gemini/skills/` |
|
||||
| **Codex CLI** | CLI | `(User Prompt) Use skill-name...` | `.codex/skills/` |
|
||||
| **Antigravity** | IDE | `(Agent Mode) Use skill...` | `.agent/skills/` |
|
||||
| **Cursor** | IDE | `@skill-name (in Chat)` | `.cursor/skills/` |
|
||||
| **Copilot** | Ext | `(Paste content manually)` | N/A |
|
||||
| **OpenCode** | CLI | `opencode run @skill-name` | `.agent/skills/` |
|
||||
| **AdaL CLI** | CLI | `(Auto) Skills load on-demand` | `.adal/skills/` |
|
||||
| Tool | Type | Invocation Example | Path |
|
||||
| :-------------- | :---- | :-------------------------------- | :---------------- |
|
||||
| **Claude Code** | CLI | `>> /skill-name help me...` | `.claude/skills/` |
|
||||
| **Gemini CLI** | CLI | `(User Prompt) Use skill-name...` | `.gemini/skills/` |
|
||||
| **Codex CLI** | CLI | `(User Prompt) Use skill-name...` | `.codex/skills/` |
|
||||
| **Antigravity** | IDE | `(Agent Mode) Use skill...` | `.agent/skills/` |
|
||||
| **Cursor** | IDE | `@skill-name (in Chat)` | `.cursor/skills/` |
|
||||
| **Copilot** | Ext | `(Paste content manually)` | N/A |
|
||||
| **OpenCode** | CLI | `opencode run @skill-name` | `.agent/skills/` |
|
||||
| **AdaL** | Agent | `(Agent Mode) Use skill...` | `.agent/skills/` |
|
||||
|
||||
> [!TIP]
|
||||
> **Universal Path**: We recommend cloning to `.agent/skills/`. Most modern tools (Antigravity, recent CLIs) look here by default.
|
||||
@@ -132,7 +131,7 @@ The repository is organized into specialized domains to transform your AI into a
|
||||
|
||||
[Check out our Starter Packs in docs/BUNDLES.md](docs/BUNDLES.md) to find the perfect toolkit for your role.
|
||||
|
||||
## Browse 713+ Skills
|
||||
## Browse 626+ Skills
|
||||
|
||||
We have moved the full skill registry to a dedicated catalog to keep this README clean.
|
||||
|
||||
@@ -297,46 +296,39 @@ Made with [contrib.rocks](https://contrib.rocks).
|
||||
|
||||
We officially thank the following contributors for their help in making this repository awesome!
|
||||
|
||||
- [@sck000](https://github.com/sck000)
|
||||
- [@munir-abbasi](https://github.com/munir-abbasi)
|
||||
- [@sickn33](https://github.com/sickn33)
|
||||
- [@Mohammad-Faiz-Cloud-Engineer](https://github.com/Mohammad-Faiz-Cloud-Engineer)
|
||||
- [@Dokhacgiakhoa](https://github.com/Dokhacgiakhoa)
|
||||
- [@IanJ332](https://github.com/IanJ332)
|
||||
- [@chauey](https://github.com/chauey)
|
||||
- [@PabloSMD](https://github.com/PabloSMD)
|
||||
- [@GuppyTheCat](https://github.com/GuppyTheCat)
|
||||
- [@Tiger-Foxx](https://github.com/Tiger-Foxx)
|
||||
- [@arathiesh](https://github.com/arathiesh)
|
||||
- [@liyin2015](https://github.com/liyin2015)
|
||||
- [@1bcMax](https://github.com/1bcMax)
|
||||
- [@ALEKGG1](https://github.com/ALEKGG1)
|
||||
- [@ar27111994](https://github.com/ar27111994)
|
||||
- [@BenedictKing](https://github.com/BenedictKing)
|
||||
- [@whatiskadudoing](https://github.com/whatiskadudoing)
|
||||
- [@LocNguyenSGU](https://github.com/LocNguyenSGU)
|
||||
- [@yubing744](https://github.com/yubing744)
|
||||
- [@SuperJMN](https://github.com/SuperJMN)
|
||||
- [@truongnmt](https://github.com/truongnmt)
|
||||
- [@viktor-ferenczi](https://github.com/viktor-ferenczi)
|
||||
- [@c1c3ru](https://github.com/c1c3ru)
|
||||
- [@ckdwns9121](https://github.com/ckdwns9121)
|
||||
- [@fbientrigo](https://github.com/fbientrigo)
|
||||
- [@junited31](https://github.com/junited31)
|
||||
- [@KrisnaSantosa15](https://github.com/KrisnaSantosa15)
|
||||
- [@sstklen](https://github.com/sstklen)
|
||||
- [@taksrules](https://github.com/taksrules)
|
||||
- [@zebbern](https://github.com/zebbern)
|
||||
- [@vuth-dogo](https://github.com/vuth-dogo)
|
||||
- [@mvanhorn](https://github.com/mvanhorn)
|
||||
- [@rookie-ricardo](https://github.com/rookie-ricardo)
|
||||
- [@evandro-miguel](https://github.com/evandro-miguel)
|
||||
- [@raeef1001](https://github.com/raeef1001)
|
||||
- [@devchangjun](https://github.com/devchangjun)
|
||||
- [@jackjin1997](https://github.com/jackjin1997)
|
||||
- [@ericgandrade](https://github.com/ericgandrade)
|
||||
- [@sohamganatra](https://github.com/sohamganatra)
|
||||
- [@Nguyen-Van-Chan](https://github.com/Nguyen-Van-Chan)
|
||||
- [sck_0](https://github.com/sck000)
|
||||
- [Munir Abbasi](https://github.com/munir-abbasi)
|
||||
- [sickn33](https://github.com/sickn33)
|
||||
- [Mohammad Faiz](https://github.com/Mohammad-Faiz-Cloud-Engineer)
|
||||
- [Đỗ Khắc Gia Khoa](https://github.com/Dokhacgiakhoa)
|
||||
- [Ianj332](https://github.com/IanJ332)
|
||||
- [GuppyTheCat](https://github.com/GuppyTheCat)
|
||||
- [Tiger-Foxx](https://github.com/Tiger-Foxx)
|
||||
- [arathiesh](https://github.com/arathiesh)
|
||||
- [1bcMax](https://github.com/1bcMax)
|
||||
- [ALEKGG1](https://github.com/ALEKGG1)
|
||||
- [Ahmed Rehan](https://github.com/ar27111994)
|
||||
- [BenedictKing](https://github.com/BenedictKing)
|
||||
- [whatiskadudoing](https://github.com/whatiskadudoing)
|
||||
- [Nguyen Huu Loc](https://github.com/LocNguyenSGU)
|
||||
- [Owen Wu](https://github.com/yubing744)
|
||||
- [SuperJMN](https://github.com/SuperJMN)
|
||||
- [Truong Nguyen](https://github.com/truongnmt)
|
||||
- [Viktor Ferenczi](https://github.com/viktor-ferenczi)
|
||||
- [c1c3ru](https://github.com/c1c3ru)
|
||||
- [ckdwns9121](https://github.com/ckdwns9121)
|
||||
- [junited31](https://github.com/junited31)
|
||||
- [liyin2015](https://github.com/liyin2015)
|
||||
- [krisnasantosa15](https://github.com/KrisnaSantosa15)
|
||||
- [sstklen](https://github.com/sstklen)
|
||||
- [taksrules](https://github.com/taksrules)
|
||||
- [zebbern](https://github.com/zebbern)
|
||||
- [vuth-dogo](https://github.com/vuth-dogo)
|
||||
- [mvanhorn](https://github.com/mvanhorn)
|
||||
- [rookie-ricardo](https://github.com/rookie-ricardo)
|
||||
- [evandro-miguel](https://github.com/evandro-miguel)
|
||||
- [raeef1001](https://github.com/raeef1001)
|
||||
- [devchangjun](https://github.com/devchangjun)
|
||||
|
||||
## Star History
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 49 KiB After Width: | Height: | Size: 50 KiB |
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"generatedAt": "2026-02-06T07:49:30.257Z",
|
||||
"generatedAt": "2026-02-03T09:20:12.539Z",
|
||||
"aliases": {
|
||||
"accessibility-compliance-audit": "accessibility-compliance-accessibility-audit",
|
||||
"active directory attacks": "active-directory-attacks",
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"generatedAt": "2026-02-06T07:49:30.257Z",
|
||||
"generatedAt": "2026-02-03T09:20:12.539Z",
|
||||
"bundles": {
|
||||
"core-dev": {
|
||||
"description": "Core development skills across languages, frameworks, and backend/frontend fundamentals.",
|
||||
@@ -38,7 +38,6 @@
|
||||
"documentation-generation-doc-generate",
|
||||
"documentation-templates",
|
||||
"dotnet-architect",
|
||||
"dotnet-backend",
|
||||
"dotnet-backend-patterns",
|
||||
"exa-search",
|
||||
"fastapi-pro",
|
||||
@@ -113,7 +112,6 @@
|
||||
"shodan-reconnaissance",
|
||||
"shopify-apps",
|
||||
"shopify-development",
|
||||
"slack-automation",
|
||||
"slack-bot-builder",
|
||||
"stitch-ui-design",
|
||||
"swiftui-expert-skill",
|
||||
@@ -166,7 +164,6 @@
|
||||
"deployment-pipeline-design",
|
||||
"design-orchestration",
|
||||
"docker-expert",
|
||||
"dotnet-backend",
|
||||
"ethical-hacking-methodology",
|
||||
"find-bugs",
|
||||
"firebase",
|
||||
@@ -239,7 +236,6 @@
|
||||
"skills": [
|
||||
"backend-architect",
|
||||
"devops-troubleshooter",
|
||||
"freshservice-automation",
|
||||
"gitops-workflow",
|
||||
"helm-chart-scaffolding",
|
||||
"istio-traffic-management",
|
||||
@@ -263,7 +259,6 @@
|
||||
"skills": [
|
||||
"airflow-dag-patterns",
|
||||
"analytics-tracking",
|
||||
"angular-ui-patterns",
|
||||
"blockrun",
|
||||
"business-analyst",
|
||||
"cc-skill-backend-patterns",
|
||||
@@ -289,8 +284,6 @@
|
||||
"fp-ts-react",
|
||||
"frontend-dev-guidelines",
|
||||
"gdpr-data-handling",
|
||||
"google-analytics-automation",
|
||||
"googlesheets-automation",
|
||||
"graphql",
|
||||
"hugging-face-jobs",
|
||||
"hybrid-cloud-networking",
|
||||
@@ -299,7 +292,6 @@
|
||||
"kpi-dashboard-design",
|
||||
"legal-advisor",
|
||||
"loki-mode",
|
||||
"mailchimp-automation",
|
||||
"ml-pipeline-workflow",
|
||||
"moodle-external-api-development",
|
||||
"neon-postgres",
|
||||
@@ -318,7 +310,6 @@
|
||||
"scala-pro",
|
||||
"schema-markup",
|
||||
"segment-cdp",
|
||||
"sendgrid-automation",
|
||||
"senior-architect",
|
||||
"seo-audit",
|
||||
"spark-optimization",
|
||||
@@ -326,12 +317,10 @@
|
||||
"sql-optimization-patterns",
|
||||
"sql-pro",
|
||||
"sqlmap-database-pentesting",
|
||||
"supabase-automation",
|
||||
"unity-ecs-patterns",
|
||||
"using-neon",
|
||||
"vector-database-engineer",
|
||||
"xlsx-official",
|
||||
"youtube-automation"
|
||||
"xlsx-official"
|
||||
]
|
||||
},
|
||||
"ops-core": {
|
||||
@@ -394,10 +383,8 @@
|
||||
"observability-monitoring-slo-implement",
|
||||
"performance-engineer",
|
||||
"performance-testing-review-ai-review",
|
||||
"pipedrive-automation",
|
||||
"postmortem-writing",
|
||||
"prometheus-configuration",
|
||||
"readme",
|
||||
"risk-metrics-calculation",
|
||||
"security-auditor",
|
||||
"server-management",
|
||||
|
||||
2180
data/catalog.json
2180
data/catalog.json
File diff suppressed because it is too large
Load Diff
11
package-lock.json
generated
11
package-lock.json
generated
@@ -1,25 +1,24 @@
|
||||
{
|
||||
"name": "antigravity-awesome-skills",
|
||||
"version": "4.10.0",
|
||||
"version": "4.2.0",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "antigravity-awesome-skills",
|
||||
"version": "4.10.0",
|
||||
"version": "4.2.0",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"yaml": "^2.8.2"
|
||||
},
|
||||
"bin": {
|
||||
"antigravity-awesome-skills": "bin/install.js"
|
||||
},
|
||||
"devDependencies": {
|
||||
"yaml": "^2.8.2"
|
||||
}
|
||||
},
|
||||
"node_modules/yaml": {
|
||||
"version": "2.8.2",
|
||||
"resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz",
|
||||
"integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==",
|
||||
"dev": true,
|
||||
"license": "ISC",
|
||||
"bin": {
|
||||
"yaml": "bin.mjs"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "antigravity-awesome-skills",
|
||||
"version": "4.10.0",
|
||||
"version": "4.7.0",
|
||||
"description": "626+ agentic skills for Claude Code, Gemini CLI, Cursor, Antigravity & more. Installer CLI.",
|
||||
"license": "MIT",
|
||||
"scripts": {
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
## [4.10.0] - 2026-02-06 - "Composio Automation + .NET Backend"
|
||||
|
||||
> Merged two community PRs adding broad automation coverage and a dedicated .NET backend skill.
|
||||
|
||||
### Added
|
||||
|
||||
- 79 new skills total:
|
||||
- 78 Composio/Rube automation skills (PR #64)
|
||||
- 1 .NET backend skill (PR #65)
|
||||
- Registry increased from 634 to 713 skills.
|
||||
|
||||
### Changed
|
||||
|
||||
- Synced generated registry artifacts:
|
||||
- README.md
|
||||
- skills_index.json
|
||||
- CATALOG.md
|
||||
- data/catalog.json
|
||||
- data/bundles.json
|
||||
- data/aliases.json
|
||||
|
||||
### Contributors
|
||||
|
||||
- [@sohamganatra](https://github.com/sohamganatra)
|
||||
- [@Nguyen-Van-Chan](https://github.com/Nguyen-Van-Chan)
|
||||
@@ -1,209 +0,0 @@
|
||||
---
|
||||
name: activecampaign-automation
|
||||
description: "Automate ActiveCampaign tasks via Rube MCP (Composio): manage contacts, tags, list subscriptions, automation enrollment, and tasks. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# ActiveCampaign Automation via Rube MCP
|
||||
|
||||
Automate ActiveCampaign CRM and marketing automation operations through Composio's ActiveCampaign toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active ActiveCampaign connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `active_campaign`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `active_campaign`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete ActiveCampaign authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create and Find Contacts
|
||||
|
||||
**When to use**: User wants to create new contacts or look up existing ones
|
||||
|
||||
**Tool sequence**:
|
||||
1. `ACTIVE_CAMPAIGN_FIND_CONTACT` - Search for an existing contact [Optional]
|
||||
2. `ACTIVE_CAMPAIGN_CREATE_CONTACT` - Create a new contact [Required]
|
||||
|
||||
**Key parameters for find**:
|
||||
- `email`: Search by email address
|
||||
- `id`: Search by ActiveCampaign contact ID
|
||||
- `phone`: Search by phone number
|
||||
|
||||
**Key parameters for create**:
|
||||
- `email`: Contact email address (required)
|
||||
- `first_name`: Contact first name
|
||||
- `last_name`: Contact last name
|
||||
- `phone`: Contact phone number
|
||||
- `organization_name`: Contact's organization
|
||||
- `job_title`: Contact's job title
|
||||
- `tags`: Comma-separated list of tags to apply
|
||||
|
||||
**Pitfalls**:
|
||||
- `email` is the only required field for contact creation
|
||||
- Phone search uses a general search parameter internally; it may return partial matches
|
||||
- When combining `email` and `phone` in FIND_CONTACT, results are filtered client-side
|
||||
- Tags provided during creation are applied immediately
|
||||
- Creating a contact with an existing email may update the existing contact
|
||||
|
||||
### 2. Manage Contact Tags
|
||||
|
||||
**When to use**: User wants to add or remove tags from contacts
|
||||
|
||||
**Tool sequence**:
|
||||
1. `ACTIVE_CAMPAIGN_FIND_CONTACT` - Find contact by email or ID [Prerequisite]
|
||||
2. `ACTIVE_CAMPAIGN_MANAGE_CONTACT_TAG` - Add or remove tags [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `action`: 'Add' or 'Remove' (required)
|
||||
- `tags`: Tag names as comma-separated string or array of strings (required)
|
||||
- `contact_id`: Contact ID (provide this or contact_email)
|
||||
- `contact_email`: Contact email address (alternative to contact_id)
|
||||
|
||||
**Pitfalls**:
|
||||
- `action` values are capitalized: 'Add' or 'Remove' (not lowercase)
|
||||
- Tags can be a comma-separated string ('tag1, tag2') or an array (['tag1', 'tag2'])
|
||||
- Either `contact_id` or `contact_email` must be provided; `contact_id` takes precedence
|
||||
- Adding a tag that does not exist creates it automatically
|
||||
- Removing a non-existent tag is a no-op (does not error)
|
||||
|
||||
### 3. Manage List Subscriptions
|
||||
|
||||
**When to use**: User wants to subscribe or unsubscribe contacts from lists
|
||||
|
||||
**Tool sequence**:
|
||||
1. `ACTIVE_CAMPAIGN_FIND_CONTACT` - Find the contact [Prerequisite]
|
||||
2. `ACTIVE_CAMPAIGN_MANAGE_LIST_SUBSCRIPTION` - Subscribe or unsubscribe [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `action`: 'subscribe' or 'unsubscribe' (required)
|
||||
- `list_id`: Numeric list ID string (required)
|
||||
- `email`: Contact email address (provide this or contact_id)
|
||||
- `contact_id`: Numeric contact ID string (alternative to email)
|
||||
|
||||
**Pitfalls**:
|
||||
- `action` values are lowercase: 'subscribe' or 'unsubscribe'
|
||||
- `list_id` is a numeric string (e.g., '2'), not the list name
|
||||
- List IDs can be retrieved via the GET /api/3/lists endpoint (not available as a Composio tool; use the ActiveCampaign UI)
|
||||
- If both `email` and `contact_id` are provided, `contact_id` takes precedence
|
||||
- Unsubscribing changes status to '2' (unsubscribed) but the relationship record persists
|
||||
|
||||
### 4. Add Contacts to Automations
|
||||
|
||||
**When to use**: User wants to enroll a contact in an automation workflow
|
||||
|
||||
**Tool sequence**:
|
||||
1. `ACTIVE_CAMPAIGN_FIND_CONTACT` - Verify contact exists [Prerequisite]
|
||||
2. `ACTIVE_CAMPAIGN_ADD_CONTACT_TO_AUTOMATION` - Enroll contact in automation [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `contact_email`: Email of the contact to enroll (required)
|
||||
- `automation_id`: ID of the target automation (required)
|
||||
|
||||
**Pitfalls**:
|
||||
- The contact must already exist in ActiveCampaign
|
||||
- Automations can only be created through the ActiveCampaign UI, not via API
|
||||
- `automation_id` must reference an existing, active automation
|
||||
- The tool performs a two-step process: lookup contact by email, then enroll
|
||||
- Automation IDs can be found in the ActiveCampaign UI or via GET /api/3/automations
|
||||
|
||||
### 5. Create Contact Tasks
|
||||
|
||||
**When to use**: User wants to create follow-up tasks associated with contacts
|
||||
|
||||
**Tool sequence**:
|
||||
1. `ACTIVE_CAMPAIGN_FIND_CONTACT` - Find the contact to associate the task with [Prerequisite]
|
||||
2. `ACTIVE_CAMPAIGN_CREATE_CONTACT_TASK` - Create the task [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `relid`: Contact ID to associate the task with (required)
|
||||
- `duedate`: Due date in ISO 8601 format with timezone (required, e.g., '2025-01-15T14:30:00-05:00')
|
||||
- `dealTasktype`: Task type ID based on available types (required)
|
||||
- `title`: Task title
|
||||
- `note`: Task description/content
|
||||
- `assignee`: User ID to assign the task to
|
||||
- `edate`: End date in ISO 8601 format (must be later than duedate)
|
||||
- `status`: 0 for incomplete, 1 for complete
|
||||
|
||||
**Pitfalls**:
|
||||
- `duedate` must be a valid ISO 8601 datetime with timezone offset; do NOT use placeholder values
|
||||
- `edate` must be later than `duedate`
|
||||
- `dealTasktype` is a string ID referencing task types configured in ActiveCampaign
|
||||
- `relid` is the numeric contact ID, not the email address
|
||||
- `assignee` is a user ID; resolve user names to IDs via the ActiveCampaign UI
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Contact Lookup Flow
|
||||
|
||||
```
|
||||
1. Call ACTIVE_CAMPAIGN_FIND_CONTACT with email
|
||||
2. If found, extract contact ID for subsequent operations
|
||||
3. If not found, create contact with ACTIVE_CAMPAIGN_CREATE_CONTACT
|
||||
4. Use contact ID for tags, subscriptions, or automations
|
||||
```
|
||||
|
||||
### Bulk Contact Tagging
|
||||
|
||||
```
|
||||
1. For each contact, call ACTIVE_CAMPAIGN_MANAGE_CONTACT_TAG
|
||||
2. Use contact_email to avoid separate lookup calls
|
||||
3. Batch with reasonable delays to respect rate limits
|
||||
```
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Contact email -> Contact ID**:
|
||||
```
|
||||
1. Call ACTIVE_CAMPAIGN_FIND_CONTACT with email
|
||||
2. Extract id from the response
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Action Capitalization**:
|
||||
- Tag actions: 'Add', 'Remove' (capitalized)
|
||||
- Subscription actions: 'subscribe', 'unsubscribe' (lowercase)
|
||||
- Mixing up capitalization causes errors
|
||||
|
||||
**ID Types**:
|
||||
- Contact IDs: numeric strings (e.g., '123')
|
||||
- List IDs: numeric strings
|
||||
- Automation IDs: numeric strings
|
||||
- All IDs should be passed as strings, not integers
|
||||
|
||||
**Automations**:
|
||||
- Automations cannot be created via API; only enrollment is possible
|
||||
- Automation must be active to accept new contacts
|
||||
- Enrolling a contact already in the automation may have no effect
|
||||
|
||||
**Rate Limits**:
|
||||
- ActiveCampaign API has rate limits per account
|
||||
- Implement backoff on 429 responses
|
||||
- Batch operations should be spaced appropriately
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` or `data.data`
|
||||
- Parse defensively with fallback patterns
|
||||
- Contact search may return multiple results; match by email for accuracy
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Find contact | ACTIVE_CAMPAIGN_FIND_CONTACT | email, id, phone |
|
||||
| Create contact | ACTIVE_CAMPAIGN_CREATE_CONTACT | email, first_name, last_name, tags |
|
||||
| Add/remove tags | ACTIVE_CAMPAIGN_MANAGE_CONTACT_TAG | action, tags, contact_email |
|
||||
| Subscribe/unsubscribe | ACTIVE_CAMPAIGN_MANAGE_LIST_SUBSCRIPTION | action, list_id, email |
|
||||
| Add to automation | ACTIVE_CAMPAIGN_ADD_CONTACT_TO_AUTOMATION | contact_email, automation_id |
|
||||
| Create task | ACTIVE_CAMPAIGN_CREATE_CONTACT_TASK | relid, duedate, dealTasktype, title |
|
||||
@@ -1,170 +0,0 @@
|
||||
---
|
||||
name: airtable-automation
|
||||
description: "Automate Airtable tasks via Rube MCP (Composio): records, bases, tables, fields, views. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Airtable Automation via Rube MCP
|
||||
|
||||
Automate Airtable operations through Composio's Airtable toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Airtable connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `airtable`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `airtable`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Airtable auth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create and Manage Records
|
||||
|
||||
**When to use**: User wants to create, read, update, or delete records
|
||||
|
||||
**Tool sequence**:
|
||||
1. `AIRTABLE_LIST_BASES` - Discover available bases [Prerequisite]
|
||||
2. `AIRTABLE_GET_BASE_SCHEMA` - Inspect table structure [Prerequisite]
|
||||
3. `AIRTABLE_LIST_RECORDS` - List/filter records [Optional]
|
||||
4. `AIRTABLE_CREATE_RECORD` / `AIRTABLE_CREATE_RECORDS` - Create records [Optional]
|
||||
5. `AIRTABLE_UPDATE_RECORD` / `AIRTABLE_UPDATE_MULTIPLE_RECORDS` - Update records [Optional]
|
||||
6. `AIRTABLE_DELETE_RECORD` / `AIRTABLE_DELETE_MULTIPLE_RECORDS` - Delete records [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `baseId`: Base ID (starts with 'app', e.g., 'appXXXXXXXXXXXXXX')
|
||||
- `tableIdOrName`: Table ID (starts with 'tbl') or table name
|
||||
- `fields`: Object mapping field names to values
|
||||
- `recordId`: Record ID (starts with 'rec') for updates/deletes
|
||||
- `filterByFormula`: Airtable formula for filtering
|
||||
- `typecast`: Set true for automatic type conversion
|
||||
|
||||
**Pitfalls**:
|
||||
- pageSize capped at 100; uses offset pagination; changing filters between pages can skip/duplicate rows
|
||||
- CREATE_RECORDS hard limit of 10 records per request; chunk larger imports
|
||||
- Field names are CASE-SENSITIVE and must match schema exactly
|
||||
- 422 UNKNOWN_FIELD_NAME when field names are wrong; 403 for permission issues
|
||||
- INVALID_MULTIPLE_CHOICE_OPTIONS may require typecast=true
|
||||
|
||||
### 2. Search and Filter Records
|
||||
|
||||
**When to use**: User wants to find specific records using formulas
|
||||
|
||||
**Tool sequence**:
|
||||
1. `AIRTABLE_GET_BASE_SCHEMA` - Verify field names and types [Prerequisite]
|
||||
2. `AIRTABLE_LIST_RECORDS` - Query with filterByFormula [Required]
|
||||
3. `AIRTABLE_GET_RECORD` - Get full record details [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `filterByFormula`: Airtable formula (e.g., `{Status}='Done'`)
|
||||
- `sort`: Array of sort objects
|
||||
- `fields`: Array of field names to return
|
||||
- `maxRecords`: Max total records across all pages
|
||||
- `offset`: Pagination cursor from previous response
|
||||
|
||||
**Pitfalls**:
|
||||
- Field names in formulas must be wrapped in `{}` and match schema exactly
|
||||
- String values must be quoted: `{Status}='Active'` not `{Status}=Active`
|
||||
- 422 INVALID_FILTER_BY_FORMULA for bad syntax or non-existent fields
|
||||
- Airtable rate limit: ~5 requests/second per base; handle 429 with Retry-After
|
||||
|
||||
### 3. Manage Fields and Schema
|
||||
|
||||
**When to use**: User wants to create or modify table fields
|
||||
|
||||
**Tool sequence**:
|
||||
1. `AIRTABLE_GET_BASE_SCHEMA` - Inspect current schema [Prerequisite]
|
||||
2. `AIRTABLE_CREATE_FIELD` - Create a new field [Optional]
|
||||
3. `AIRTABLE_UPDATE_FIELD` - Rename/describe a field [Optional]
|
||||
4. `AIRTABLE_UPDATE_TABLE` - Update table metadata [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Field name
|
||||
- `type`: Field type (singleLineText, number, singleSelect, etc.)
|
||||
- `options`: Type-specific options (choices for select, precision for number)
|
||||
- `description`: Field description
|
||||
|
||||
**Pitfalls**:
|
||||
- UPDATE_FIELD only changes name/description, NOT type/options; create a replacement field and migrate
|
||||
- Computed fields (formula, rollup, lookup) cannot be created via API
|
||||
- 422 when type options are missing or malformed
|
||||
|
||||
### 4. Manage Comments
|
||||
|
||||
**When to use**: User wants to view or add comments on records
|
||||
|
||||
**Tool sequence**:
|
||||
1. `AIRTABLE_LIST_COMMENTS` - List comments on a record [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `baseId`: Base ID
|
||||
- `tableIdOrName`: Table identifier
|
||||
- `recordId`: Record ID (17 chars, starts with 'rec')
|
||||
- `pageSize`: Comments per page (max 100)
|
||||
|
||||
**Pitfalls**:
|
||||
- Record IDs must be exactly 17 characters starting with 'rec'
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Airtable Formula Syntax
|
||||
|
||||
**Comparison**:
|
||||
- `{Status}='Done'` - Equals
|
||||
- `{Priority}>1` - Greater than
|
||||
- `{Name}!=''` - Not empty
|
||||
|
||||
**Functions**:
|
||||
- `AND({A}='x', {B}='y')` - Both conditions
|
||||
- `OR({A}='x', {A}='y')` - Either condition
|
||||
- `FIND('test', {Name})>0` - Contains text
|
||||
- `IS_BEFORE({Due Date}, TODAY())` - Date comparison
|
||||
|
||||
**Escape rules**:
|
||||
- Single quotes in values: double them (`{Name}='John''s Company'`)
|
||||
|
||||
### Pagination
|
||||
|
||||
- Set `pageSize` (max 100)
|
||||
- Check response for `offset` string
|
||||
- Pass `offset` to next request unchanged
|
||||
- Keep filters/sorts/view stable between pages
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**ID Formats**:
|
||||
- Base IDs: `appXXXXXXXXXXXXXX` (17 chars)
|
||||
- Table IDs: `tblXXXXXXXXXXXXXX` (17 chars)
|
||||
- Record IDs: `recXXXXXXXXXXXXXX` (17 chars)
|
||||
- Field IDs: `fldXXXXXXXXXXXXXX` (17 chars)
|
||||
|
||||
**Batch Limits**:
|
||||
- CREATE_RECORDS: max 10 per request
|
||||
- UPDATE_MULTIPLE_RECORDS: max 10 per request
|
||||
- DELETE_MULTIPLE_RECORDS: max 10 per request
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List bases | AIRTABLE_LIST_BASES | (none) |
|
||||
| Get schema | AIRTABLE_GET_BASE_SCHEMA | baseId |
|
||||
| List records | AIRTABLE_LIST_RECORDS | baseId, tableIdOrName |
|
||||
| Get record | AIRTABLE_GET_RECORD | baseId, tableIdOrName, recordId |
|
||||
| Create record | AIRTABLE_CREATE_RECORD | baseId, tableIdOrName, fields |
|
||||
| Create records | AIRTABLE_CREATE_RECORDS | baseId, tableIdOrName, records |
|
||||
| Update record | AIRTABLE_UPDATE_RECORD | baseId, tableIdOrName, recordId, fields |
|
||||
| Update records | AIRTABLE_UPDATE_MULTIPLE_RECORDS | baseId, tableIdOrName, records |
|
||||
| Delete record | AIRTABLE_DELETE_RECORD | baseId, tableIdOrName, recordId |
|
||||
| Create field | AIRTABLE_CREATE_FIELD | baseId, tableIdOrName, name, type |
|
||||
| Update field | AIRTABLE_UPDATE_FIELD | baseId, tableIdOrName, fieldId |
|
||||
| Update table | AIRTABLE_UPDATE_TABLE | baseId, tableIdOrName, name |
|
||||
| List comments | AIRTABLE_LIST_COMMENTS | baseId, tableIdOrName, recordId |
|
||||
@@ -1,216 +0,0 @@
|
||||
---
|
||||
name: amplitude-automation
|
||||
description: "Automate Amplitude tasks via Rube MCP (Composio): events, user activity, cohorts, user identification. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Amplitude Automation via Rube MCP
|
||||
|
||||
Automate Amplitude product analytics through Composio's Amplitude toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Amplitude connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `amplitude`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `amplitude`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Amplitude authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Send Events
|
||||
|
||||
**When to use**: User wants to track events or send event data to Amplitude
|
||||
|
||||
**Tool sequence**:
|
||||
1. `AMPLITUDE_SEND_EVENTS` - Send one or more events to Amplitude [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `events`: Array of event objects, each containing:
|
||||
- `event_type`: Name of the event (e.g., 'page_view', 'purchase')
|
||||
- `user_id`: Unique user identifier (required if no `device_id`)
|
||||
- `device_id`: Device identifier (required if no `user_id`)
|
||||
- `event_properties`: Object with custom event properties
|
||||
- `user_properties`: Object with user properties to set
|
||||
- `time`: Event timestamp in milliseconds since epoch
|
||||
|
||||
**Pitfalls**:
|
||||
- At least one of `user_id` or `device_id` is required per event
|
||||
- `event_type` is required for every event; cannot be empty
|
||||
- `time` must be in milliseconds (13-digit epoch), not seconds
|
||||
- Batch limit applies; check schema for maximum events per request
|
||||
- Events are processed asynchronously; successful API response does not mean data is immediately queryable
|
||||
|
||||
### 2. Get User Activity
|
||||
|
||||
**When to use**: User wants to view event history for a specific user
|
||||
|
||||
**Tool sequence**:
|
||||
1. `AMPLITUDE_FIND_USER` - Find user by ID or property [Prerequisite]
|
||||
2. `AMPLITUDE_GET_USER_ACTIVITY` - Retrieve user's event stream [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `user`: Amplitude internal user ID (from FIND_USER)
|
||||
- `offset`: Pagination offset for event list
|
||||
- `limit`: Maximum number of events to return
|
||||
|
||||
**Pitfalls**:
|
||||
- `user` parameter requires Amplitude's internal user ID, NOT your application's user_id
|
||||
- Must call FIND_USER first to resolve your user_id to Amplitude's internal ID
|
||||
- Activity is returned in reverse chronological order by default
|
||||
- Large activity histories require pagination via `offset`
|
||||
|
||||
### 3. Find and Identify Users
|
||||
|
||||
**When to use**: User wants to look up users or set user properties
|
||||
|
||||
**Tool sequence**:
|
||||
1. `AMPLITUDE_FIND_USER` - Search for a user by various identifiers [Required]
|
||||
2. `AMPLITUDE_IDENTIFY` - Set or update user properties [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- For FIND_USER:
|
||||
- `user`: Search term (user_id, email, or Amplitude ID)
|
||||
- For IDENTIFY:
|
||||
- `user_id`: Your application's user identifier
|
||||
- `device_id`: Device identifier (alternative to user_id)
|
||||
- `user_properties`: Object with `$set`, `$unset`, `$add`, `$append` operations
|
||||
|
||||
**Pitfalls**:
|
||||
- FIND_USER searches across user_id, device_id, and Amplitude ID
|
||||
- IDENTIFY uses special property operations (`$set`, `$unset`, `$add`, `$append`)
|
||||
- `$set` overwrites existing values; `$setOnce` only sets if not already set
|
||||
- At least one of `user_id` or `device_id` is required for IDENTIFY
|
||||
- User property changes are eventually consistent; not immediate
|
||||
|
||||
### 4. Manage Cohorts
|
||||
|
||||
**When to use**: User wants to list cohorts, view cohort details, or update cohort membership
|
||||
|
||||
**Tool sequence**:
|
||||
1. `AMPLITUDE_LIST_COHORTS` - List all saved cohorts [Required]
|
||||
2. `AMPLITUDE_GET_COHORT` - Get detailed cohort information [Optional]
|
||||
3. `AMPLITUDE_UPDATE_COHORT_MEMBERSHIP` - Add/remove users from a cohort [Optional]
|
||||
4. `AMPLITUDE_CHECK_COHORT_STATUS` - Check async cohort operation status [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- For LIST_COHORTS: No required parameters
|
||||
- For GET_COHORT: `cohort_id` (from list results)
|
||||
- For UPDATE_COHORT_MEMBERSHIP:
|
||||
- `cohort_id`: Target cohort ID
|
||||
- `memberships`: Object with `add` and/or `remove` arrays of user IDs
|
||||
- For CHECK_COHORT_STATUS: `request_id` from update response
|
||||
|
||||
**Pitfalls**:
|
||||
- Cohort IDs are required for all cohort-specific operations
|
||||
- UPDATE_COHORT_MEMBERSHIP is asynchronous; use CHECK_COHORT_STATUS to verify
|
||||
- `request_id` from the update response is needed for status checking
|
||||
- Maximum membership changes per request may be limited; chunk large updates
|
||||
- Only behavioral cohorts support API membership updates
|
||||
|
||||
### 5. Browse Event Categories
|
||||
|
||||
**When to use**: User wants to discover available event types and categories in Amplitude
|
||||
|
||||
**Tool sequence**:
|
||||
1. `AMPLITUDE_GET_EVENT_CATEGORIES` - List all event categories [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- No required parameters; returns all configured event categories
|
||||
|
||||
**Pitfalls**:
|
||||
- Categories are configured in Amplitude UI; API provides read access
|
||||
- Event names within categories are case-sensitive
|
||||
- Use these categories to validate event_type values before sending events
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Application user_id -> Amplitude internal ID**:
|
||||
```
|
||||
1. Call AMPLITUDE_FIND_USER with user=your_user_id
|
||||
2. Extract Amplitude's internal user ID from response
|
||||
3. Use internal ID for GET_USER_ACTIVITY
|
||||
```
|
||||
|
||||
**Cohort name -> Cohort ID**:
|
||||
```
|
||||
1. Call AMPLITUDE_LIST_COHORTS
|
||||
2. Find cohort by name in results
|
||||
3. Extract id for cohort operations
|
||||
```
|
||||
|
||||
### User Property Operations
|
||||
|
||||
Amplitude IDENTIFY supports these property operations:
|
||||
- `$set`: Set property value (overwrites existing)
|
||||
- `$setOnce`: Set only if property not already set
|
||||
- `$add`: Increment numeric property
|
||||
- `$append`: Append to list property
|
||||
- `$unset`: Remove property entirely
|
||||
|
||||
Example structure:
|
||||
```json
|
||||
{
|
||||
"user_properties": {
|
||||
"$set": {"plan": "premium", "company": "Acme"},
|
||||
"$add": {"login_count": 1}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Async Operation Pattern
|
||||
|
||||
For cohort membership updates:
|
||||
```
|
||||
1. Call AMPLITUDE_UPDATE_COHORT_MEMBERSHIP -> get request_id
|
||||
2. Call AMPLITUDE_CHECK_COHORT_STATUS with request_id
|
||||
3. Repeat step 2 until status is 'complete' or 'error'
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**User IDs**:
|
||||
- Amplitude has its own internal user IDs separate from your application's
|
||||
- FIND_USER resolves your IDs to Amplitude's internal IDs
|
||||
- GET_USER_ACTIVITY requires Amplitude's internal ID, not your user_id
|
||||
|
||||
**Event Timestamps**:
|
||||
- Must be in milliseconds since epoch (13 digits)
|
||||
- Seconds (10 digits) will be interpreted as very old dates
|
||||
- Omitting timestamp uses server receive time
|
||||
|
||||
**Rate Limits**:
|
||||
- Event ingestion has throughput limits per project
|
||||
- Batch events where possible to reduce API calls
|
||||
- Cohort membership updates have async processing limits
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` key
|
||||
- User activity returns events in reverse chronological order
|
||||
- Cohort lists may include archived cohorts; check status field
|
||||
- Parse defensively with fallbacks for optional fields
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Send events | AMPLITUDE_SEND_EVENTS | events (array) |
|
||||
| Find user | AMPLITUDE_FIND_USER | user |
|
||||
| Get user activity | AMPLITUDE_GET_USER_ACTIVITY | user, offset, limit |
|
||||
| Identify user | AMPLITUDE_IDENTIFY | user_id, user_properties |
|
||||
| List cohorts | AMPLITUDE_LIST_COHORTS | (none) |
|
||||
| Get cohort | AMPLITUDE_GET_COHORT | cohort_id |
|
||||
| Update cohort members | AMPLITUDE_UPDATE_COHORT_MEMBERSHIP | cohort_id, memberships |
|
||||
| Check cohort status | AMPLITUDE_CHECK_COHORT_STATUS | request_id |
|
||||
| List event categories | AMPLITUDE_GET_EVENT_CATEGORIES | (none) |
|
||||
@@ -1,58 +0,0 @@
|
||||
# Angular Best Practices
|
||||
|
||||
Performance optimization and best practices for Angular applications optimized for AI agents and LLMs.
|
||||
|
||||
## Overview
|
||||
|
||||
This skill provides prioritized performance guidelines across:
|
||||
|
||||
- **Change Detection** - OnPush strategy, Signals, Zoneless apps
|
||||
- **Async Operations** - Avoiding waterfalls, SSR preloading
|
||||
- **Bundle Optimization** - Lazy loading, `@defer`, tree-shaking
|
||||
- **Rendering Performance** - TrackBy, virtual scrolling, CDK
|
||||
- **SSR & Hydration** - Server-side rendering patterns
|
||||
- **Template Optimization** - Structural directives, pipe memoization
|
||||
- **State Management** - Efficient reactivity patterns
|
||||
- **Memory Management** - Subscription cleanup, detached refs
|
||||
|
||||
## Structure
|
||||
|
||||
The `SKILL.md` file is organized by priority:
|
||||
|
||||
1. **Critical Priority** - Largest performance gains (change detection, async)
|
||||
2. **High Priority** - Significant impact (bundles, rendering)
|
||||
3. **Medium Priority** - Noticeable improvements (SSR, templates)
|
||||
4. **Low Priority** - Incremental gains (memory, cleanup)
|
||||
|
||||
Each rule includes:
|
||||
|
||||
- ❌ **WRONG** - What not to do
|
||||
- ✅ **CORRECT** - Recommended pattern
|
||||
- 📝 **Why** - Explanation of the impact
|
||||
|
||||
## Quick Reference Checklist
|
||||
|
||||
**For New Components:**
|
||||
|
||||
- [ ] Using `ChangeDetectionStrategy.OnPush`
|
||||
- [ ] Using Signals for reactive state
|
||||
- [ ] Using `@defer` for non-critical content
|
||||
- [ ] Using `trackBy` for `*ngFor` loops
|
||||
- [ ] No subscriptions without cleanup
|
||||
|
||||
**For Performance Reviews:**
|
||||
|
||||
- [ ] No async waterfalls (parallel data fetching)
|
||||
- [ ] Routes lazy-loaded
|
||||
- [ ] Large libraries code-split
|
||||
- [ ] Images use `NgOptimizedImage`
|
||||
|
||||
## Version
|
||||
|
||||
Current version: 1.0.0 (February 2026)
|
||||
|
||||
## References
|
||||
|
||||
- [Angular Performance](https://angular.dev/guide/performance)
|
||||
- [Zoneless Angular](https://angular.dev/guide/zoneless)
|
||||
- [Angular SSR](https://angular.dev/guide/ssr)
|
||||
@@ -1,559 +0,0 @@
|
||||
---
|
||||
name: angular-best-practices
|
||||
description: Angular performance optimization and best practices guide. Use when writing, reviewing, or refactoring Angular code for optimal performance, bundle size, and rendering efficiency.
|
||||
risk: safe
|
||||
source: self
|
||||
---
|
||||
|
||||
# Angular Best Practices
|
||||
|
||||
Comprehensive performance optimization guide for Angular applications. Contains prioritized rules for eliminating performance bottlenecks, optimizing bundles, and improving rendering.
|
||||
|
||||
## When to Apply
|
||||
|
||||
Reference these guidelines when:
|
||||
|
||||
- Writing new Angular components or pages
|
||||
- Implementing data fetching patterns
|
||||
- Reviewing code for performance issues
|
||||
- Refactoring existing Angular code
|
||||
- Optimizing bundle size or load times
|
||||
- Configuring SSR/hydration
|
||||
|
||||
---
|
||||
|
||||
## Rule Categories by Priority
|
||||
|
||||
| Priority | Category | Impact | Focus |
|
||||
| -------- | --------------------- | ---------- | ------------------------------- |
|
||||
| 1 | Change Detection | CRITICAL | Signals, OnPush, Zoneless |
|
||||
| 2 | Async Waterfalls | CRITICAL | RxJS patterns, SSR preloading |
|
||||
| 3 | Bundle Optimization | CRITICAL | Lazy loading, tree shaking |
|
||||
| 4 | Rendering Performance | HIGH | @defer, trackBy, virtualization |
|
||||
| 5 | Server-Side Rendering | HIGH | Hydration, prerendering |
|
||||
| 6 | Template Optimization | MEDIUM | Control flow, pipes |
|
||||
| 7 | State Management | MEDIUM | Signal patterns, selectors |
|
||||
| 8 | Memory Management | LOW-MEDIUM | Cleanup, subscriptions |
|
||||
|
||||
---
|
||||
|
||||
## 1. Change Detection (CRITICAL)
|
||||
|
||||
### Use OnPush Change Detection
|
||||
|
||||
```typescript
|
||||
// CORRECT - OnPush with Signals
|
||||
@Component({
|
||||
changeDetection: ChangeDetectionStrategy.OnPush,
|
||||
template: `<div>{{ count() }}</div>`,
|
||||
})
|
||||
export class CounterComponent {
|
||||
count = signal(0);
|
||||
}
|
||||
|
||||
// WRONG - Default change detection
|
||||
@Component({
|
||||
template: `<div>{{ count }}</div>`, // Checked every cycle
|
||||
})
|
||||
export class CounterComponent {
|
||||
count = 0;
|
||||
}
|
||||
```
|
||||
|
||||
### Prefer Signals Over Mutable Properties
|
||||
|
||||
```typescript
|
||||
// CORRECT - Signals trigger precise updates
|
||||
@Component({
|
||||
template: `
|
||||
<h1>{{ title() }}</h1>
|
||||
<p>Count: {{ count() }}</p>
|
||||
`,
|
||||
})
|
||||
export class DashboardComponent {
|
||||
title = signal("Dashboard");
|
||||
count = signal(0);
|
||||
}
|
||||
|
||||
// WRONG - Mutable properties require zone.js checks
|
||||
@Component({
|
||||
template: `
|
||||
<h1>{{ title }}</h1>
|
||||
<p>Count: {{ count }}</p>
|
||||
`,
|
||||
})
|
||||
export class DashboardComponent {
|
||||
title = "Dashboard";
|
||||
count = 0;
|
||||
}
|
||||
```
|
||||
|
||||
### Enable Zoneless for New Projects
|
||||
|
||||
```typescript
|
||||
// main.ts - Zoneless Angular (v20+)
|
||||
bootstrapApplication(AppComponent, {
|
||||
providers: [provideZonelessChangeDetection()],
|
||||
});
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- No zone.js patches on async APIs
|
||||
- Smaller bundle (~15KB savings)
|
||||
- Clean stack traces for debugging
|
||||
- Better micro-frontend compatibility
|
||||
|
||||
---
|
||||
|
||||
## 2. Async Operations & Waterfalls (CRITICAL)
|
||||
|
||||
### Eliminate Sequential Data Fetching
|
||||
|
||||
```typescript
|
||||
// WRONG - Nested subscriptions create waterfalls
|
||||
this.route.params.subscribe((params) => {
|
||||
// 1. Wait for params
|
||||
this.userService.getUser(params.id).subscribe((user) => {
|
||||
// 2. Wait for user
|
||||
this.postsService.getPosts(user.id).subscribe((posts) => {
|
||||
// 3. Wait for posts
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
// CORRECT - Parallel execution with forkJoin
|
||||
forkJoin({
|
||||
user: this.userService.getUser(id),
|
||||
posts: this.postsService.getPosts(id),
|
||||
}).subscribe((data) => {
|
||||
// Fetched in parallel
|
||||
});
|
||||
|
||||
// CORRECT - Flatten dependent calls with switchMap
|
||||
this.route.params
|
||||
.pipe(
|
||||
map((p) => p.id),
|
||||
switchMap((id) => this.userService.getUser(id)),
|
||||
)
|
||||
.subscribe();
|
||||
```
|
||||
|
||||
### Avoid Client-Side Waterfalls in SSR
|
||||
|
||||
```typescript
|
||||
// CORRECT - Use resolvers or blocking hydration for critical data
|
||||
export const route: Route = {
|
||||
path: "profile/:id",
|
||||
resolve: { data: profileResolver }, // Fetched on server before navigation
|
||||
component: ProfileComponent,
|
||||
};
|
||||
|
||||
// WRONG - Component fetches data on init
|
||||
class ProfileComponent implements OnInit {
|
||||
ngOnInit() {
|
||||
// Starts ONLY after JS loads and component renders
|
||||
this.http.get("/api/profile").subscribe();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Bundle Optimization (CRITICAL)
|
||||
|
||||
### Lazy Load Routes
|
||||
|
||||
```typescript
|
||||
// CORRECT - Lazy load feature routes
|
||||
export const routes: Routes = [
|
||||
{
|
||||
path: "admin",
|
||||
loadChildren: () =>
|
||||
import("./admin/admin.routes").then((m) => m.ADMIN_ROUTES),
|
||||
},
|
||||
{
|
||||
path: "dashboard",
|
||||
loadComponent: () =>
|
||||
import("./dashboard/dashboard.component").then(
|
||||
(m) => m.DashboardComponent,
|
||||
),
|
||||
},
|
||||
];
|
||||
|
||||
// WRONG - Eager loading everything
|
||||
import { AdminModule } from "./admin/admin.module";
|
||||
export const routes: Routes = [
|
||||
{ path: "admin", component: AdminComponent }, // In main bundle
|
||||
];
|
||||
```
|
||||
|
||||
### Use @defer for Heavy Components
|
||||
|
||||
```html
|
||||
<!-- CORRECT - Heavy component loads on demand -->
|
||||
@defer (on viewport) {
|
||||
<app-analytics-chart [data]="data()" />
|
||||
} @placeholder {
|
||||
<div class="chart-skeleton"></div>
|
||||
}
|
||||
|
||||
<!-- WRONG - Heavy component in initial bundle -->
|
||||
<app-analytics-chart [data]="data()" />
|
||||
```
|
||||
|
||||
### Avoid Barrel File Re-exports
|
||||
|
||||
```typescript
|
||||
// WRONG - Imports entire barrel, breaks tree-shaking
|
||||
import { Button, Modal, Table } from "@shared/components";
|
||||
|
||||
// CORRECT - Direct imports
|
||||
import { Button } from "@shared/components/button/button.component";
|
||||
import { Modal } from "@shared/components/modal/modal.component";
|
||||
```
|
||||
|
||||
### Dynamic Import Third-Party Libraries
|
||||
|
||||
```typescript
|
||||
// CORRECT - Load heavy library on demand
|
||||
async loadChart() {
|
||||
const { Chart } = await import('chart.js');
|
||||
this.chart = new Chart(this.canvas, config);
|
||||
}
|
||||
|
||||
// WRONG - Bundle Chart.js in main chunk
|
||||
import { Chart } from 'chart.js';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Rendering Performance (HIGH)
|
||||
|
||||
### Always Use trackBy with @for
|
||||
|
||||
```html
|
||||
<!-- CORRECT - Efficient DOM updates -->
|
||||
@for (item of items(); track item.id) {
|
||||
<app-item-card [item]="item" />
|
||||
}
|
||||
|
||||
<!-- WRONG - Entire list re-renders on any change -->
|
||||
@for (item of items(); track $index) {
|
||||
<app-item-card [item]="item" />
|
||||
}
|
||||
```
|
||||
|
||||
### Use Virtual Scrolling for Large Lists
|
||||
|
||||
```typescript
|
||||
import { CdkVirtualScrollViewport, CdkFixedSizeVirtualScroll } from '@angular/cdk/scrolling';
|
||||
|
||||
@Component({
|
||||
imports: [CdkVirtualScrollViewport, CdkFixedSizeVirtualScroll],
|
||||
template: `
|
||||
<cdk-virtual-scroll-viewport itemSize="50" class="viewport">
|
||||
<div *cdkVirtualFor="let item of items" class="item">
|
||||
{{ item.name }}
|
||||
</div>
|
||||
</cdk-virtual-scroll-viewport>
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
### Prefer Pure Pipes Over Methods
|
||||
|
||||
```typescript
|
||||
// CORRECT - Pure pipe, memoized
|
||||
@Pipe({ name: 'filterActive', standalone: true, pure: true })
|
||||
export class FilterActivePipe implements PipeTransform {
|
||||
transform(items: Item[]): Item[] {
|
||||
return items.filter(i => i.active);
|
||||
}
|
||||
}
|
||||
|
||||
// Template
|
||||
@for (item of items() | filterActive; track item.id) { ... }
|
||||
|
||||
// WRONG - Method called every change detection
|
||||
@for (item of getActiveItems(); track item.id) { ... }
|
||||
```
|
||||
|
||||
### Use computed() for Derived Data
|
||||
|
||||
```typescript
|
||||
// CORRECT - Computed, cached until dependencies change
|
||||
export class ProductStore {
|
||||
products = signal<Product[]>([]);
|
||||
filter = signal('');
|
||||
|
||||
filteredProducts = computed(() => {
|
||||
const f = this.filter().toLowerCase();
|
||||
return this.products().filter(p =>
|
||||
p.name.toLowerCase().includes(f)
|
||||
);
|
||||
});
|
||||
}
|
||||
|
||||
// WRONG - Recalculates every access
|
||||
get filteredProducts() {
|
||||
return this.products.filter(p =>
|
||||
p.name.toLowerCase().includes(this.filter)
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Server-Side Rendering (HIGH)
|
||||
|
||||
### Configure Incremental Hydration
|
||||
|
||||
```typescript
|
||||
// app.config.ts
|
||||
import {
|
||||
provideClientHydration,
|
||||
withIncrementalHydration,
|
||||
} from "@angular/platform-browser";
|
||||
|
||||
export const appConfig: ApplicationConfig = {
|
||||
providers: [
|
||||
provideClientHydration(withIncrementalHydration(), withEventReplay()),
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### Defer Non-Critical Content
|
||||
|
||||
```html
|
||||
<!-- Critical above-the-fold content -->
|
||||
<app-header />
|
||||
<app-hero />
|
||||
|
||||
<!-- Below-fold deferred with hydration triggers -->
|
||||
@defer (hydrate on viewport) {
|
||||
<app-product-grid />
|
||||
} @defer (hydrate on interaction) {
|
||||
<app-chat-widget />
|
||||
}
|
||||
```
|
||||
|
||||
### Use TransferState for SSR Data
|
||||
|
||||
```typescript
|
||||
@Injectable({ providedIn: "root" })
|
||||
export class DataService {
|
||||
private http = inject(HttpClient);
|
||||
private transferState = inject(TransferState);
|
||||
private platformId = inject(PLATFORM_ID);
|
||||
|
||||
getData(key: string): Observable<Data> {
|
||||
const stateKey = makeStateKey<Data>(key);
|
||||
|
||||
if (isPlatformBrowser(this.platformId)) {
|
||||
const cached = this.transferState.get(stateKey, null);
|
||||
if (cached) {
|
||||
this.transferState.remove(stateKey);
|
||||
return of(cached);
|
||||
}
|
||||
}
|
||||
|
||||
return this.http.get<Data>(`/api/${key}`).pipe(
|
||||
tap((data) => {
|
||||
if (isPlatformServer(this.platformId)) {
|
||||
this.transferState.set(stateKey, data);
|
||||
}
|
||||
}),
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Template Optimization (MEDIUM)
|
||||
|
||||
### Use New Control Flow Syntax
|
||||
|
||||
```html
|
||||
<!-- CORRECT - New control flow (faster, smaller bundle) -->
|
||||
@if (user()) {
|
||||
<span>{{ user()!.name }}</span>
|
||||
} @else {
|
||||
<span>Guest</span>
|
||||
} @for (item of items(); track item.id) {
|
||||
<app-item [item]="item" />
|
||||
} @empty {
|
||||
<p>No items</p>
|
||||
}
|
||||
|
||||
<!-- WRONG - Legacy structural directives -->
|
||||
<span *ngIf="user; else guest">{{ user.name }}</span>
|
||||
<ng-template #guest><span>Guest</span></ng-template>
|
||||
```
|
||||
|
||||
### Avoid Complex Template Expressions
|
||||
|
||||
```typescript
|
||||
// CORRECT - Precompute in component
|
||||
class Component {
|
||||
items = signal<Item[]>([]);
|
||||
sortedItems = computed(() =>
|
||||
[...this.items()].sort((a, b) => a.name.localeCompare(b.name))
|
||||
);
|
||||
}
|
||||
|
||||
// Template
|
||||
@for (item of sortedItems(); track item.id) { ... }
|
||||
|
||||
// WRONG - Sorting in template every render
|
||||
@for (item of items() | sort:'name'; track item.id) { ... }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. State Management (MEDIUM)
|
||||
|
||||
### Use Selectors to Prevent Re-renders
|
||||
|
||||
```typescript
|
||||
// CORRECT - Selective subscription
|
||||
@Component({
|
||||
template: `<span>{{ userName() }}</span>`,
|
||||
})
|
||||
class HeaderComponent {
|
||||
private store = inject(Store);
|
||||
// Only re-renders when userName changes
|
||||
userName = this.store.selectSignal(selectUserName);
|
||||
}
|
||||
|
||||
// WRONG - Subscribing to entire state
|
||||
@Component({
|
||||
template: `<span>{{ state().user.name }}</span>`,
|
||||
})
|
||||
class HeaderComponent {
|
||||
private store = inject(Store);
|
||||
// Re-renders on ANY state change
|
||||
state = toSignal(this.store);
|
||||
}
|
||||
```
|
||||
|
||||
### Colocate State with Features
|
||||
|
||||
```typescript
|
||||
// CORRECT - Feature-scoped store
|
||||
@Injectable() // NOT providedIn: 'root'
|
||||
export class ProductStore { ... }
|
||||
|
||||
@Component({
|
||||
providers: [ProductStore], // Scoped to component tree
|
||||
})
|
||||
export class ProductPageComponent {
|
||||
store = inject(ProductStore);
|
||||
}
|
||||
|
||||
// WRONG - Everything in global store
|
||||
@Injectable({ providedIn: 'root' })
|
||||
export class GlobalStore {
|
||||
// Contains ALL app state - hard to tree-shake
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Memory Management (LOW-MEDIUM)
|
||||
|
||||
### Use takeUntilDestroyed for Subscriptions
|
||||
|
||||
```typescript
|
||||
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
|
||||
|
||||
@Component({...})
|
||||
export class DataComponent {
|
||||
private destroyRef = inject(DestroyRef);
|
||||
|
||||
constructor() {
|
||||
this.data$.pipe(
|
||||
takeUntilDestroyed(this.destroyRef)
|
||||
).subscribe(data => this.process(data));
|
||||
}
|
||||
}
|
||||
|
||||
// WRONG - Manual subscription management
|
||||
export class DataComponent implements OnDestroy {
|
||||
private subscription!: Subscription;
|
||||
|
||||
ngOnInit() {
|
||||
this.subscription = this.data$.subscribe(...);
|
||||
}
|
||||
|
||||
ngOnDestroy() {
|
||||
this.subscription.unsubscribe(); // Easy to forget
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Prefer Signals Over Subscriptions
|
||||
|
||||
```typescript
|
||||
// CORRECT - No subscription needed
|
||||
@Component({
|
||||
template: `<div>{{ data().name }}</div>`,
|
||||
})
|
||||
export class Component {
|
||||
data = toSignal(this.service.data$, { initialValue: null });
|
||||
}
|
||||
|
||||
// WRONG - Manual subscription
|
||||
@Component({
|
||||
template: `<div>{{ data?.name }}</div>`,
|
||||
})
|
||||
export class Component implements OnInit, OnDestroy {
|
||||
data: Data | null = null;
|
||||
private sub!: Subscription;
|
||||
|
||||
ngOnInit() {
|
||||
this.sub = this.service.data$.subscribe((d) => (this.data = d));
|
||||
}
|
||||
|
||||
ngOnDestroy() {
|
||||
this.sub.unsubscribe();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Checklist
|
||||
|
||||
### New Component
|
||||
|
||||
- [ ] `changeDetection: ChangeDetectionStrategy.OnPush`
|
||||
- [ ] `standalone: true`
|
||||
- [ ] Signals for state (`signal()`, `input()`, `output()`)
|
||||
- [ ] `inject()` for dependencies
|
||||
- [ ] `@for` with `track` expression
|
||||
|
||||
### Performance Review
|
||||
|
||||
- [ ] No methods in templates (use pipes or computed)
|
||||
- [ ] Large lists virtualized
|
||||
- [ ] Heavy components deferred
|
||||
- [ ] Routes lazy-loaded
|
||||
- [ ] Third-party libs dynamically imported
|
||||
|
||||
### SSR Check
|
||||
|
||||
- [ ] Hydration configured
|
||||
- [ ] Critical content renders first
|
||||
- [ ] Non-critical content uses `@defer (hydrate on ...)`
|
||||
- [ ] TransferState for server-fetched data
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- [Angular Performance Guide](https://angular.dev/best-practices/performance)
|
||||
- [Zoneless Angular](https://angular.dev/guide/experimental/zoneless)
|
||||
- [Angular SSR Guide](https://angular.dev/guide/ssr)
|
||||
- [Change Detection Deep Dive](https://angular.dev/guide/change-detection)
|
||||
@@ -1,13 +0,0 @@
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"organization": "Antigravity Awesome Skills",
|
||||
"date": "February 2026",
|
||||
"abstract": "Performance optimization and best practices guide for Angular applications designed for AI agents and LLMs. Covers change detection strategies (OnPush, Signals, Zoneless), avoiding async waterfalls, bundle optimization with lazy loading and @defer, rendering performance, SSR/hydration patterns, and memory management. Prioritized by impact from critical to incremental improvements.",
|
||||
"references": [
|
||||
"https://angular.dev/best-practices",
|
||||
"https://angular.dev/guide/performance",
|
||||
"https://angular.dev/guide/zoneless",
|
||||
"https://angular.dev/guide/ssr",
|
||||
"https://web.dev/performance"
|
||||
]
|
||||
}
|
||||
@@ -1,41 +0,0 @@
|
||||
# Angular State Management
|
||||
|
||||
Complete state management patterns for Angular applications optimized for AI agents and LLMs.
|
||||
|
||||
## Overview
|
||||
|
||||
This skill provides decision frameworks and implementation patterns for:
|
||||
|
||||
- **Signal-based Services** - Lightweight state for shared data
|
||||
- **NgRx SignalStore** - Feature-scoped state with computed values
|
||||
- **NgRx Store** - Enterprise-scale global state management
|
||||
- **RxJS ComponentStore** - Reactive component-level state
|
||||
- **Forms State** - Reactive and template-driven form patterns
|
||||
|
||||
## Structure
|
||||
|
||||
The `SKILL.md` file is organized into:
|
||||
|
||||
1. **State Categories** - Local, shared, global, server, URL, and form state
|
||||
2. **Selection Criteria** - Decision trees for choosing the right solution
|
||||
3. **Implementation Patterns** - Complete examples for each approach
|
||||
4. **Migration Guides** - Moving from BehaviorSubject to Signals
|
||||
5. **Bridging Patterns** - Integrating Signals with RxJS
|
||||
|
||||
## When to Use Each Pattern
|
||||
|
||||
- **Signal Service**: Shared UI state (theme, user preferences)
|
||||
- **NgRx SignalStore**: Feature state with computed values
|
||||
- **NgRx Store**: Complex cross-feature dependencies
|
||||
- **ComponentStore**: Component-scoped async operations
|
||||
- **Reactive Forms**: Form state with validation
|
||||
|
||||
## Version
|
||||
|
||||
Current version: 1.0.0 (February 2026)
|
||||
|
||||
## References
|
||||
|
||||
- [Angular Signals](https://angular.dev/guide/signals)
|
||||
- [NgRx](https://ngrx.io)
|
||||
- [NgRx SignalStore](https://ngrx.io/guide/signals)
|
||||
@@ -1,634 +0,0 @@
|
||||
---
|
||||
name: angular-state-management
|
||||
description: Master modern Angular state management with Signals, NgRx, and RxJS. Use when setting up global state, managing component stores, choosing between state solutions, or migrating from legacy patterns.
|
||||
risk: safe
|
||||
source: self
|
||||
---
|
||||
|
||||
# Angular State Management
|
||||
|
||||
Comprehensive guide to modern Angular state management patterns, from Signal-based local state to global stores and server state synchronization.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Setting up global state management in Angular
|
||||
- Choosing between Signals, NgRx, or Akita
|
||||
- Managing component-level stores
|
||||
- Implementing optimistic updates
|
||||
- Debugging state-related issues
|
||||
- Migrating from legacy state patterns
|
||||
|
||||
## Do Not Use This Skill When
|
||||
|
||||
- The task is unrelated to Angular state management
|
||||
- You need React state management → use `react-state-management`
|
||||
|
||||
---
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### State Categories
|
||||
|
||||
| Type | Description | Solutions |
|
||||
| ---------------- | ---------------------------- | --------------------- |
|
||||
| **Local State** | Component-specific, UI state | Signals, `signal()` |
|
||||
| **Shared State** | Between related components | Signal services |
|
||||
| **Global State** | App-wide, complex | NgRx, Akita, Elf |
|
||||
| **Server State** | Remote data, caching | NgRx Query, RxAngular |
|
||||
| **URL State** | Route parameters | ActivatedRoute |
|
||||
| **Form State** | Input values, validation | Reactive Forms |
|
||||
|
||||
### Selection Criteria
|
||||
|
||||
```
|
||||
Small app, simple state → Signal Services
|
||||
Medium app, moderate state → Component Stores
|
||||
Large app, complex state → NgRx Store
|
||||
Heavy server interaction → NgRx Query + Signal Services
|
||||
Real-time updates → RxAngular + Signals
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start: Signal-Based State
|
||||
|
||||
### Pattern 1: Simple Signal Service
|
||||
|
||||
```typescript
|
||||
// services/counter.service.ts
|
||||
import { Injectable, signal, computed } from "@angular/core";
|
||||
|
||||
@Injectable({ providedIn: "root" })
|
||||
export class CounterService {
|
||||
// Private writable signals
|
||||
private _count = signal(0);
|
||||
|
||||
// Public read-only
|
||||
readonly count = this._count.asReadonly();
|
||||
readonly doubled = computed(() => this._count() * 2);
|
||||
readonly isPositive = computed(() => this._count() > 0);
|
||||
|
||||
increment() {
|
||||
this._count.update((v) => v + 1);
|
||||
}
|
||||
|
||||
decrement() {
|
||||
this._count.update((v) => v - 1);
|
||||
}
|
||||
|
||||
reset() {
|
||||
this._count.set(0);
|
||||
}
|
||||
}
|
||||
|
||||
// Usage in component
|
||||
@Component({
|
||||
template: `
|
||||
<p>Count: {{ counter.count() }}</p>
|
||||
<p>Doubled: {{ counter.doubled() }}</p>
|
||||
<button (click)="counter.increment()">+</button>
|
||||
`,
|
||||
})
|
||||
export class CounterComponent {
|
||||
counter = inject(CounterService);
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 2: Feature Signal Store
|
||||
|
||||
```typescript
|
||||
// stores/user.store.ts
|
||||
import { Injectable, signal, computed, inject } from "@angular/core";
|
||||
import { HttpClient } from "@angular/common/http";
|
||||
import { toSignal } from "@angular/core/rxjs-interop";
|
||||
|
||||
interface User {
|
||||
id: string;
|
||||
name: string;
|
||||
email: string;
|
||||
}
|
||||
|
||||
interface UserState {
|
||||
user: User | null;
|
||||
loading: boolean;
|
||||
error: string | null;
|
||||
}
|
||||
|
||||
@Injectable({ providedIn: "root" })
|
||||
export class UserStore {
|
||||
private http = inject(HttpClient);
|
||||
|
||||
// State signals
|
||||
private _user = signal<User | null>(null);
|
||||
private _loading = signal(false);
|
||||
private _error = signal<string | null>(null);
|
||||
|
||||
// Selectors (read-only computed)
|
||||
readonly user = computed(() => this._user());
|
||||
readonly loading = computed(() => this._loading());
|
||||
readonly error = computed(() => this._error());
|
||||
readonly isAuthenticated = computed(() => this._user() !== null);
|
||||
readonly displayName = computed(() => this._user()?.name ?? "Guest");
|
||||
|
||||
// Actions
|
||||
async loadUser(id: string) {
|
||||
this._loading.set(true);
|
||||
this._error.set(null);
|
||||
|
||||
try {
|
||||
const user = await fetch(`/api/users/${id}`).then((r) => r.json());
|
||||
this._user.set(user);
|
||||
} catch (e) {
|
||||
this._error.set("Failed to load user");
|
||||
} finally {
|
||||
this._loading.set(false);
|
||||
}
|
||||
}
|
||||
|
||||
updateUser(updates: Partial<User>) {
|
||||
this._user.update((user) => (user ? { ...user, ...updates } : null));
|
||||
}
|
||||
|
||||
logout() {
|
||||
this._user.set(null);
|
||||
this._error.set(null);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 3: SignalStore (NgRx Signals)
|
||||
|
||||
```typescript
|
||||
// stores/products.store.ts
|
||||
import {
|
||||
signalStore,
|
||||
withState,
|
||||
withMethods,
|
||||
withComputed,
|
||||
patchState,
|
||||
} from "@ngrx/signals";
|
||||
import { inject } from "@angular/core";
|
||||
import { ProductService } from "./product.service";
|
||||
|
||||
interface ProductState {
|
||||
products: Product[];
|
||||
loading: boolean;
|
||||
filter: string;
|
||||
}
|
||||
|
||||
const initialState: ProductState = {
|
||||
products: [],
|
||||
loading: false,
|
||||
filter: "",
|
||||
};
|
||||
|
||||
export const ProductStore = signalStore(
|
||||
{ providedIn: "root" },
|
||||
|
||||
withState(initialState),
|
||||
|
||||
withComputed((store) => ({
|
||||
filteredProducts: computed(() => {
|
||||
const filter = store.filter().toLowerCase();
|
||||
return store
|
||||
.products()
|
||||
.filter((p) => p.name.toLowerCase().includes(filter));
|
||||
}),
|
||||
totalCount: computed(() => store.products().length),
|
||||
})),
|
||||
|
||||
withMethods((store, productService = inject(ProductService)) => ({
|
||||
async loadProducts() {
|
||||
patchState(store, { loading: true });
|
||||
|
||||
try {
|
||||
const products = await productService.getAll();
|
||||
patchState(store, { products, loading: false });
|
||||
} catch {
|
||||
patchState(store, { loading: false });
|
||||
}
|
||||
},
|
||||
|
||||
setFilter(filter: string) {
|
||||
patchState(store, { filter });
|
||||
},
|
||||
|
||||
addProduct(product: Product) {
|
||||
patchState(store, ({ products }) => ({
|
||||
products: [...products, product],
|
||||
}));
|
||||
},
|
||||
})),
|
||||
);
|
||||
|
||||
// Usage
|
||||
@Component({
|
||||
template: `
|
||||
<input (input)="store.setFilter($event.target.value)" />
|
||||
@if (store.loading()) {
|
||||
<app-spinner />
|
||||
} @else {
|
||||
@for (product of store.filteredProducts(); track product.id) {
|
||||
<app-product-card [product]="product" />
|
||||
}
|
||||
}
|
||||
`,
|
||||
})
|
||||
export class ProductListComponent {
|
||||
store = inject(ProductStore);
|
||||
|
||||
ngOnInit() {
|
||||
this.store.loadProducts();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## NgRx Store (Global State)
|
||||
|
||||
### Setup
|
||||
|
||||
```typescript
|
||||
// store/app.state.ts
|
||||
import { ActionReducerMap } from "@ngrx/store";
|
||||
|
||||
export interface AppState {
|
||||
user: UserState;
|
||||
cart: CartState;
|
||||
}
|
||||
|
||||
export const reducers: ActionReducerMap<AppState> = {
|
||||
user: userReducer,
|
||||
cart: cartReducer,
|
||||
};
|
||||
|
||||
// main.ts
|
||||
bootstrapApplication(AppComponent, {
|
||||
providers: [
|
||||
provideStore(reducers),
|
||||
provideEffects([UserEffects, CartEffects]),
|
||||
provideStoreDevtools({ maxAge: 25 }),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
### Feature Slice Pattern
|
||||
|
||||
```typescript
|
||||
// store/user/user.actions.ts
|
||||
import { createActionGroup, props, emptyProps } from "@ngrx/store";
|
||||
|
||||
export const UserActions = createActionGroup({
|
||||
source: "User",
|
||||
events: {
|
||||
"Load User": props<{ userId: string }>(),
|
||||
"Load User Success": props<{ user: User }>(),
|
||||
"Load User Failure": props<{ error: string }>(),
|
||||
"Update User": props<{ updates: Partial<User> }>(),
|
||||
Logout: emptyProps(),
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
```typescript
|
||||
// store/user/user.reducer.ts
|
||||
import { createReducer, on } from "@ngrx/store";
|
||||
import { UserActions } from "./user.actions";
|
||||
|
||||
export interface UserState {
|
||||
user: User | null;
|
||||
loading: boolean;
|
||||
error: string | null;
|
||||
}
|
||||
|
||||
const initialState: UserState = {
|
||||
user: null,
|
||||
loading: false,
|
||||
error: null,
|
||||
};
|
||||
|
||||
export const userReducer = createReducer(
|
||||
initialState,
|
||||
|
||||
on(UserActions.loadUser, (state) => ({
|
||||
...state,
|
||||
loading: true,
|
||||
error: null,
|
||||
})),
|
||||
|
||||
on(UserActions.loadUserSuccess, (state, { user }) => ({
|
||||
...state,
|
||||
user,
|
||||
loading: false,
|
||||
})),
|
||||
|
||||
on(UserActions.loadUserFailure, (state, { error }) => ({
|
||||
...state,
|
||||
loading: false,
|
||||
error,
|
||||
})),
|
||||
|
||||
on(UserActions.logout, () => initialState),
|
||||
);
|
||||
```
|
||||
|
||||
```typescript
|
||||
// store/user/user.selectors.ts
|
||||
import { createFeatureSelector, createSelector } from "@ngrx/store";
|
||||
import { UserState } from "./user.reducer";
|
||||
|
||||
export const selectUserState = createFeatureSelector<UserState>("user");
|
||||
|
||||
export const selectUser = createSelector(
|
||||
selectUserState,
|
||||
(state) => state.user,
|
||||
);
|
||||
|
||||
export const selectUserLoading = createSelector(
|
||||
selectUserState,
|
||||
(state) => state.loading,
|
||||
);
|
||||
|
||||
export const selectIsAuthenticated = createSelector(
|
||||
selectUser,
|
||||
(user) => user !== null,
|
||||
);
|
||||
```
|
||||
|
||||
```typescript
|
||||
// store/user/user.effects.ts
|
||||
import { Injectable, inject } from "@angular/core";
|
||||
import { Actions, createEffect, ofType } from "@ngrx/effects";
|
||||
import { switchMap, map, catchError, of } from "rxjs";
|
||||
|
||||
@Injectable()
|
||||
export class UserEffects {
|
||||
private actions$ = inject(Actions);
|
||||
private userService = inject(UserService);
|
||||
|
||||
loadUser$ = createEffect(() =>
|
||||
this.actions$.pipe(
|
||||
ofType(UserActions.loadUser),
|
||||
switchMap(({ userId }) =>
|
||||
this.userService.getUser(userId).pipe(
|
||||
map((user) => UserActions.loadUserSuccess({ user })),
|
||||
catchError((error) =>
|
||||
of(UserActions.loadUserFailure({ error: error.message })),
|
||||
),
|
||||
),
|
||||
),
|
||||
),
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Component Usage
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
template: `
|
||||
@if (loading()) {
|
||||
<app-spinner />
|
||||
} @else if (user(); as user) {
|
||||
<h1>Welcome, {{ user.name }}</h1>
|
||||
<button (click)="logout()">Logout</button>
|
||||
}
|
||||
`,
|
||||
})
|
||||
export class HeaderComponent {
|
||||
private store = inject(Store);
|
||||
|
||||
user = this.store.selectSignal(selectUser);
|
||||
loading = this.store.selectSignal(selectUserLoading);
|
||||
|
||||
logout() {
|
||||
this.store.dispatch(UserActions.logout());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## RxJS-Based Patterns
|
||||
|
||||
### Component Store (Local Feature State)
|
||||
|
||||
```typescript
|
||||
// stores/todo.store.ts
|
||||
import { Injectable } from "@angular/core";
|
||||
import { ComponentStore } from "@ngrx/component-store";
|
||||
import { switchMap, tap, catchError, EMPTY } from "rxjs";
|
||||
|
||||
interface TodoState {
|
||||
todos: Todo[];
|
||||
loading: boolean;
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
export class TodoStore extends ComponentStore<TodoState> {
|
||||
constructor(private todoService: TodoService) {
|
||||
super({ todos: [], loading: false });
|
||||
}
|
||||
|
||||
// Selectors
|
||||
readonly todos$ = this.select((state) => state.todos);
|
||||
readonly loading$ = this.select((state) => state.loading);
|
||||
readonly completedCount$ = this.select(
|
||||
this.todos$,
|
||||
(todos) => todos.filter((t) => t.completed).length,
|
||||
);
|
||||
|
||||
// Updaters
|
||||
readonly addTodo = this.updater((state, todo: Todo) => ({
|
||||
...state,
|
||||
todos: [...state.todos, todo],
|
||||
}));
|
||||
|
||||
readonly toggleTodo = this.updater((state, id: string) => ({
|
||||
...state,
|
||||
todos: state.todos.map((t) =>
|
||||
t.id === id ? { ...t, completed: !t.completed } : t,
|
||||
),
|
||||
}));
|
||||
|
||||
// Effects
|
||||
readonly loadTodos = this.effect<void>((trigger$) =>
|
||||
trigger$.pipe(
|
||||
tap(() => this.patchState({ loading: true })),
|
||||
switchMap(() =>
|
||||
this.todoService.getAll().pipe(
|
||||
tap({
|
||||
next: (todos) => this.patchState({ todos, loading: false }),
|
||||
error: () => this.patchState({ loading: false }),
|
||||
}),
|
||||
catchError(() => EMPTY),
|
||||
),
|
||||
),
|
||||
),
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Server State with Signals
|
||||
|
||||
### HTTP + Signals Pattern
|
||||
|
||||
```typescript
|
||||
// services/api.service.ts
|
||||
import { Injectable, signal, inject } from "@angular/core";
|
||||
import { HttpClient } from "@angular/common/http";
|
||||
import { toSignal } from "@angular/core/rxjs-interop";
|
||||
|
||||
interface ApiState<T> {
|
||||
data: T | null;
|
||||
loading: boolean;
|
||||
error: string | null;
|
||||
}
|
||||
|
||||
@Injectable({ providedIn: "root" })
|
||||
export class ProductApiService {
|
||||
private http = inject(HttpClient);
|
||||
|
||||
private _state = signal<ApiState<Product[]>>({
|
||||
data: null,
|
||||
loading: false,
|
||||
error: null,
|
||||
});
|
||||
|
||||
readonly products = computed(() => this._state().data ?? []);
|
||||
readonly loading = computed(() => this._state().loading);
|
||||
readonly error = computed(() => this._state().error);
|
||||
|
||||
async fetchProducts(): Promise<void> {
|
||||
this._state.update((s) => ({ ...s, loading: true, error: null }));
|
||||
|
||||
try {
|
||||
const data = await firstValueFrom(
|
||||
this.http.get<Product[]>("/api/products"),
|
||||
);
|
||||
this._state.update((s) => ({ ...s, data, loading: false }));
|
||||
} catch (e) {
|
||||
this._state.update((s) => ({
|
||||
...s,
|
||||
loading: false,
|
||||
error: "Failed to fetch products",
|
||||
}));
|
||||
}
|
||||
}
|
||||
|
||||
// Optimistic update
|
||||
async deleteProduct(id: string): Promise<void> {
|
||||
const previousData = this._state().data;
|
||||
|
||||
// Optimistically remove
|
||||
this._state.update((s) => ({
|
||||
...s,
|
||||
data: s.data?.filter((p) => p.id !== id) ?? null,
|
||||
}));
|
||||
|
||||
try {
|
||||
await firstValueFrom(this.http.delete(`/api/products/${id}`));
|
||||
} catch {
|
||||
// Rollback on error
|
||||
this._state.update((s) => ({ ...s, data: previousData }));
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Do's
|
||||
|
||||
| Practice | Why |
|
||||
| ---------------------------------- | ---------------------------------- |
|
||||
| Use Signals for local state | Simple, reactive, no subscriptions |
|
||||
| Use `computed()` for derived data | Auto-updates, memoized |
|
||||
| Colocate state with feature | Easier to maintain |
|
||||
| Use NgRx for complex flows | Actions, effects, devtools |
|
||||
| Prefer `inject()` over constructor | Cleaner, works in factories |
|
||||
|
||||
### Don'ts
|
||||
|
||||
| Anti-Pattern | Instead |
|
||||
| --------------------------------- | ----------------------------------------------------- |
|
||||
| Store derived data | Use `computed()` |
|
||||
| Mutate signals directly | Use `set()` or `update()` |
|
||||
| Over-globalize state | Keep local when possible |
|
||||
| Mix RxJS and Signals chaotically | Choose primary, bridge with `toSignal`/`toObservable` |
|
||||
| Subscribe in components for state | Use template with signals |
|
||||
|
||||
---
|
||||
|
||||
## Migration Path
|
||||
|
||||
### From BehaviorSubject to Signals
|
||||
|
||||
```typescript
|
||||
// Before: RxJS-based
|
||||
@Injectable({ providedIn: "root" })
|
||||
export class OldUserService {
|
||||
private userSubject = new BehaviorSubject<User | null>(null);
|
||||
user$ = this.userSubject.asObservable();
|
||||
|
||||
setUser(user: User) {
|
||||
this.userSubject.next(user);
|
||||
}
|
||||
}
|
||||
|
||||
// After: Signal-based
|
||||
@Injectable({ providedIn: "root" })
|
||||
export class UserService {
|
||||
private _user = signal<User | null>(null);
|
||||
readonly user = this._user.asReadonly();
|
||||
|
||||
setUser(user: User) {
|
||||
this._user.set(user);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Bridging Signals and RxJS
|
||||
|
||||
```typescript
|
||||
import { toSignal, toObservable } from '@angular/core/rxjs-interop';
|
||||
|
||||
// Observable → Signal
|
||||
@Component({...})
|
||||
export class ExampleComponent {
|
||||
private route = inject(ActivatedRoute);
|
||||
|
||||
// Convert Observable to Signal
|
||||
userId = toSignal(
|
||||
this.route.params.pipe(map(p => p['id'])),
|
||||
{ initialValue: '' }
|
||||
);
|
||||
}
|
||||
|
||||
// Signal → Observable
|
||||
export class DataService {
|
||||
private filter = signal('');
|
||||
|
||||
// Convert Signal to Observable
|
||||
filter$ = toObservable(this.filter);
|
||||
|
||||
filteredData$ = this.filter$.pipe(
|
||||
debounceTime(300),
|
||||
switchMap(filter => this.http.get(`/api/data?q=${filter}`))
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- [Angular Signals Guide](https://angular.dev/guide/signals)
|
||||
- [NgRx Documentation](https://ngrx.io/)
|
||||
- [NgRx SignalStore](https://ngrx.io/guide/signals)
|
||||
- [RxAngular](https://www.rx-angular.io/)
|
||||
@@ -1,13 +0,0 @@
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"organization": "Antigravity Awesome Skills",
|
||||
"date": "February 2026",
|
||||
"abstract": "Complete state management guide for Angular applications designed for AI agents and LLMs. Covers Signal-based services, NgRx for global state, RxJS patterns, and component stores. Includes decision trees for choosing the right solution, migration patterns from BehaviorSubject to Signals, and strategies for bridging Signals with RxJS observables.",
|
||||
"references": [
|
||||
"https://angular.dev/guide/signals",
|
||||
"https://ngrx.io",
|
||||
"https://ngrx.io/guide/signals",
|
||||
"https://www.rx-angular.io",
|
||||
"https://github.com/ngrx/platform"
|
||||
]
|
||||
}
|
||||
@@ -1,55 +0,0 @@
|
||||
# Angular UI Patterns
|
||||
|
||||
Modern UI patterns for building robust Angular applications optimized for AI agents and LLMs.
|
||||
|
||||
## Overview
|
||||
|
||||
This skill covers essential UI patterns for:
|
||||
|
||||
- **Loading States** - Skeleton vs spinner decision trees
|
||||
- **Error Handling** - Error boundary hierarchy and recovery
|
||||
- **Progressive Disclosure** - Using `@defer` for lazy rendering
|
||||
- **Data Display** - Handling empty, loading, and error states
|
||||
- **Form Patterns** - Submission states and validation feedback
|
||||
- **Dialog/Modal Patterns** - Proper dialog lifecycle management
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Never show stale UI** - Only show loading when no data exists
|
||||
2. **Surface all errors** - Never silently fail
|
||||
3. **Optimistic updates** - Update UI before server confirms
|
||||
4. **Progressive disclosure** - Use `@defer` to load non-critical content
|
||||
5. **Graceful degradation** - Fallback for failed features
|
||||
|
||||
## Structure
|
||||
|
||||
The `SKILL.md` file includes:
|
||||
|
||||
1. **Golden Rules** - Non-negotiable patterns to follow
|
||||
2. **Decision Trees** - When to use skeleton vs spinner
|
||||
3. **Code Examples** - Correct vs incorrect implementations
|
||||
4. **Anti-patterns** - Common mistakes to avoid
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```html
|
||||
<!-- Angular template pattern for data states -->
|
||||
@if (error()) {
|
||||
<app-error-state [error]="error()" (retry)="load()" />
|
||||
} @else if (loading() && !data()) {
|
||||
<app-skeleton-state />
|
||||
} @else if (!data()?.length) {
|
||||
<app-empty-state message="No items found" />
|
||||
} @else {
|
||||
<app-data-display [data]="data()" />
|
||||
}
|
||||
```
|
||||
|
||||
## Version
|
||||
|
||||
Current version: 1.0.0 (February 2026)
|
||||
|
||||
## References
|
||||
|
||||
- [Angular @defer](https://angular.dev/guide/defer)
|
||||
- [Angular Templates](https://angular.dev/guide/templates)
|
||||
@@ -1,508 +0,0 @@
|
||||
---
|
||||
name: angular-ui-patterns
|
||||
description: Modern Angular UI patterns for loading states, error handling, and data display. Use when building UI components, handling async data, or managing component states.
|
||||
risk: safe
|
||||
source: self
|
||||
---
|
||||
|
||||
# Angular UI Patterns
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Never show stale UI** - Loading states only when actually loading
|
||||
2. **Always surface errors** - Users must know when something fails
|
||||
3. **Optimistic updates** - Make the UI feel instant
|
||||
4. **Progressive disclosure** - Use `@defer` to show content as available
|
||||
5. **Graceful degradation** - Partial data is better than no data
|
||||
|
||||
---
|
||||
|
||||
## Loading State Patterns
|
||||
|
||||
### The Golden Rule
|
||||
|
||||
**Show loading indicator ONLY when there's no data to display.**
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
template: `
|
||||
@if (error()) {
|
||||
<app-error-state [error]="error()" (retry)="load()" />
|
||||
} @else if (loading() && !items().length) {
|
||||
<app-skeleton-list />
|
||||
} @else if (!items().length) {
|
||||
<app-empty-state message="No items found" />
|
||||
} @else {
|
||||
<app-item-list [items]="items()" />
|
||||
}
|
||||
`,
|
||||
})
|
||||
export class ItemListComponent {
|
||||
private store = inject(ItemStore);
|
||||
|
||||
items = this.store.items;
|
||||
loading = this.store.loading;
|
||||
error = this.store.error;
|
||||
}
|
||||
```
|
||||
|
||||
### Loading State Decision Tree
|
||||
|
||||
```
|
||||
Is there an error?
|
||||
→ Yes: Show error state with retry option
|
||||
→ No: Continue
|
||||
|
||||
Is it loading AND we have no data?
|
||||
→ Yes: Show loading indicator (spinner/skeleton)
|
||||
→ No: Continue
|
||||
|
||||
Do we have data?
|
||||
→ Yes, with items: Show the data
|
||||
→ Yes, but empty: Show empty state
|
||||
→ No: Show loading (fallback)
|
||||
```
|
||||
|
||||
### Skeleton vs Spinner
|
||||
|
||||
| Use Skeleton When | Use Spinner When |
|
||||
| -------------------- | --------------------- |
|
||||
| Known content shape | Unknown content shape |
|
||||
| List/card layouts | Modal actions |
|
||||
| Initial page load | Button submissions |
|
||||
| Content placeholders | Inline operations |
|
||||
|
||||
---
|
||||
|
||||
## Control Flow Patterns
|
||||
|
||||
### @if/@else for Conditional Rendering
|
||||
|
||||
```html
|
||||
@if (user(); as user) {
|
||||
<span>Welcome, {{ user.name }}</span>
|
||||
} @else if (loading()) {
|
||||
<app-spinner size="small" />
|
||||
} @else {
|
||||
<a routerLink="/login">Sign In</a>
|
||||
}
|
||||
```
|
||||
|
||||
### @for with Track
|
||||
|
||||
```html
|
||||
@for (item of items(); track item.id) {
|
||||
<app-item-card [item]="item" (delete)="remove(item.id)" />
|
||||
} @empty {
|
||||
<app-empty-state
|
||||
icon="inbox"
|
||||
message="No items yet"
|
||||
actionLabel="Create Item"
|
||||
(action)="create()"
|
||||
/>
|
||||
}
|
||||
```
|
||||
|
||||
### @defer for Progressive Loading
|
||||
|
||||
```html
|
||||
<!-- Critical content loads immediately -->
|
||||
<app-header />
|
||||
<app-hero-section />
|
||||
|
||||
<!-- Non-critical content deferred -->
|
||||
@defer (on viewport) {
|
||||
<app-comments [postId]="postId()" />
|
||||
} @placeholder {
|
||||
<div class="h-32 bg-gray-100 animate-pulse"></div>
|
||||
} @loading (minimum 200ms) {
|
||||
<app-spinner />
|
||||
} @error {
|
||||
<app-error-state message="Failed to load comments" />
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling Patterns
|
||||
|
||||
### Error Handling Hierarchy
|
||||
|
||||
```
|
||||
1. Inline error (field-level) → Form validation errors
|
||||
2. Toast notification → Recoverable errors, user can retry
|
||||
3. Error banner → Page-level errors, data still partially usable
|
||||
4. Full error screen → Unrecoverable, needs user action
|
||||
```
|
||||
|
||||
### Always Show Errors
|
||||
|
||||
**CRITICAL: Never swallow errors silently.**
|
||||
|
||||
```typescript
|
||||
// CORRECT - Error always surfaced to user
|
||||
@Component({...})
|
||||
export class CreateItemComponent {
|
||||
private store = inject(ItemStore);
|
||||
private toast = inject(ToastService);
|
||||
|
||||
async create(data: CreateItemDto) {
|
||||
try {
|
||||
await this.store.create(data);
|
||||
this.toast.success('Item created successfully');
|
||||
this.router.navigate(['/items']);
|
||||
} catch (error) {
|
||||
console.error('createItem failed:', error);
|
||||
this.toast.error('Failed to create item. Please try again.');
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// WRONG - Error silently caught
|
||||
async create(data: CreateItemDto) {
|
||||
try {
|
||||
await this.store.create(data);
|
||||
} catch (error) {
|
||||
console.error(error); // User sees nothing!
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error State Component Pattern
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: "app-error-state",
|
||||
standalone: true,
|
||||
imports: [NgOptimizedImage],
|
||||
template: `
|
||||
<div class="error-state">
|
||||
<img ngSrc="/assets/error-icon.svg" width="64" height="64" alt="" />
|
||||
<h3>{{ title() }}</h3>
|
||||
<p>{{ message() }}</p>
|
||||
@if (retry.observed) {
|
||||
<button (click)="retry.emit()" class="btn-primary">Try Again</button>
|
||||
}
|
||||
</div>
|
||||
`,
|
||||
})
|
||||
export class ErrorStateComponent {
|
||||
title = input("Something went wrong");
|
||||
message = input("An unexpected error occurred");
|
||||
retry = output<void>();
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Button State Patterns
|
||||
|
||||
### Button Loading State
|
||||
|
||||
```html
|
||||
<button
|
||||
(click)="handleSubmit()"
|
||||
[disabled]="isSubmitting() || !form.valid"
|
||||
class="btn-primary"
|
||||
>
|
||||
@if (isSubmitting()) {
|
||||
<app-spinner size="small" class="mr-2" />
|
||||
Saving... } @else { Save Changes }
|
||||
</button>
|
||||
```
|
||||
|
||||
### Disable During Operations
|
||||
|
||||
**CRITICAL: Always disable triggers during async operations.**
|
||||
|
||||
```typescript
|
||||
// CORRECT - Button disabled while loading
|
||||
@Component({
|
||||
template: `
|
||||
<button
|
||||
[disabled]="saving()"
|
||||
(click)="save()"
|
||||
>
|
||||
@if (saving()) {
|
||||
<app-spinner size="sm" /> Saving...
|
||||
} @else {
|
||||
Save
|
||||
}
|
||||
</button>
|
||||
`
|
||||
})
|
||||
export class SaveButtonComponent {
|
||||
saving = signal(false);
|
||||
|
||||
async save() {
|
||||
this.saving.set(true);
|
||||
try {
|
||||
await this.service.save();
|
||||
} finally {
|
||||
this.saving.set(false);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// WRONG - User can click multiple times
|
||||
<button (click)="save()">
|
||||
{{ saving() ? 'Saving...' : 'Save' }}
|
||||
</button>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Empty States
|
||||
|
||||
### Empty State Requirements
|
||||
|
||||
Every list/collection MUST have an empty state:
|
||||
|
||||
```html
|
||||
@for (item of items(); track item.id) {
|
||||
<app-item-card [item]="item" />
|
||||
} @empty {
|
||||
<app-empty-state
|
||||
icon="folder-open"
|
||||
title="No items yet"
|
||||
description="Create your first item to get started"
|
||||
actionLabel="Create Item"
|
||||
(action)="openCreateDialog()"
|
||||
/>
|
||||
}
|
||||
```
|
||||
|
||||
### Contextual Empty States
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: "app-empty-state",
|
||||
template: `
|
||||
<div class="empty-state">
|
||||
<span class="icon" [class]="icon()"></span>
|
||||
<h3>{{ title() }}</h3>
|
||||
<p>{{ description() }}</p>
|
||||
@if (actionLabel()) {
|
||||
<button (click)="action.emit()" class="btn-primary">
|
||||
{{ actionLabel() }}
|
||||
</button>
|
||||
}
|
||||
</div>
|
||||
`,
|
||||
})
|
||||
export class EmptyStateComponent {
|
||||
icon = input("inbox");
|
||||
title = input.required<string>();
|
||||
description = input("");
|
||||
actionLabel = input<string | null>(null);
|
||||
action = output<void>();
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Form Patterns
|
||||
|
||||
### Form with Loading and Validation
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
template: `
|
||||
<form [formGroup]="form" (ngSubmit)="onSubmit()">
|
||||
<div class="form-field">
|
||||
<label for="name">Name</label>
|
||||
<input
|
||||
id="name"
|
||||
formControlName="name"
|
||||
[class.error]="isFieldInvalid('name')"
|
||||
/>
|
||||
@if (isFieldInvalid("name")) {
|
||||
<span class="error-text">
|
||||
{{ getFieldError("name") }}
|
||||
</span>
|
||||
}
|
||||
</div>
|
||||
|
||||
<div class="form-field">
|
||||
<label for="email">Email</label>
|
||||
<input id="email" type="email" formControlName="email" />
|
||||
@if (isFieldInvalid("email")) {
|
||||
<span class="error-text">
|
||||
{{ getFieldError("email") }}
|
||||
</span>
|
||||
}
|
||||
</div>
|
||||
|
||||
<button type="submit" [disabled]="form.invalid || submitting()">
|
||||
@if (submitting()) {
|
||||
<app-spinner size="sm" /> Submitting...
|
||||
} @else {
|
||||
Submit
|
||||
}
|
||||
</button>
|
||||
</form>
|
||||
`,
|
||||
})
|
||||
export class UserFormComponent {
|
||||
private fb = inject(FormBuilder);
|
||||
|
||||
submitting = signal(false);
|
||||
|
||||
form = this.fb.group({
|
||||
name: ["", [Validators.required, Validators.minLength(2)]],
|
||||
email: ["", [Validators.required, Validators.email]],
|
||||
});
|
||||
|
||||
isFieldInvalid(field: string): boolean {
|
||||
const control = this.form.get(field);
|
||||
return control ? control.invalid && control.touched : false;
|
||||
}
|
||||
|
||||
getFieldError(field: string): string {
|
||||
const control = this.form.get(field);
|
||||
if (control?.hasError("required")) return "This field is required";
|
||||
if (control?.hasError("email")) return "Invalid email format";
|
||||
if (control?.hasError("minlength")) return "Too short";
|
||||
return "";
|
||||
}
|
||||
|
||||
async onSubmit() {
|
||||
if (this.form.invalid) return;
|
||||
|
||||
this.submitting.set(true);
|
||||
try {
|
||||
await this.service.submit(this.form.value);
|
||||
this.toast.success("Submitted successfully");
|
||||
} catch {
|
||||
this.toast.error("Submission failed");
|
||||
} finally {
|
||||
this.submitting.set(false);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dialog/Modal Patterns
|
||||
|
||||
### Confirmation Dialog
|
||||
|
||||
```typescript
|
||||
// dialog.service.ts
|
||||
@Injectable({ providedIn: 'root' })
|
||||
export class DialogService {
|
||||
private dialog = inject(Dialog); // CDK Dialog or custom
|
||||
|
||||
async confirm(options: {
|
||||
title: string;
|
||||
message: string;
|
||||
confirmText?: string;
|
||||
cancelText?: string;
|
||||
}): Promise<boolean> {
|
||||
const dialogRef = this.dialog.open(ConfirmDialogComponent, {
|
||||
data: options,
|
||||
});
|
||||
|
||||
return await firstValueFrom(dialogRef.closed) ?? false;
|
||||
}
|
||||
}
|
||||
|
||||
// Usage
|
||||
async deleteItem(item: Item) {
|
||||
const confirmed = await this.dialog.confirm({
|
||||
title: 'Delete Item',
|
||||
message: `Are you sure you want to delete "${item.name}"?`,
|
||||
confirmText: 'Delete',
|
||||
});
|
||||
|
||||
if (confirmed) {
|
||||
await this.store.delete(item.id);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### Loading States
|
||||
|
||||
```typescript
|
||||
// WRONG - Spinner when data exists (causes flash on refetch)
|
||||
@if (loading()) {
|
||||
<app-spinner />
|
||||
}
|
||||
|
||||
// CORRECT - Only show loading without data
|
||||
@if (loading() && !items().length) {
|
||||
<app-spinner />
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```typescript
|
||||
// WRONG - Error swallowed
|
||||
try {
|
||||
await this.service.save();
|
||||
} catch (e) {
|
||||
console.log(e); // User has no idea!
|
||||
}
|
||||
|
||||
// CORRECT - Error surfaced
|
||||
try {
|
||||
await this.service.save();
|
||||
} catch (e) {
|
||||
console.error("Save failed:", e);
|
||||
this.toast.error("Failed to save. Please try again.");
|
||||
}
|
||||
```
|
||||
|
||||
### Button States
|
||||
|
||||
```html
|
||||
<!-- WRONG - Button not disabled during submission -->
|
||||
<button (click)="submit()">Submit</button>
|
||||
|
||||
<!-- CORRECT - Disabled and shows loading -->
|
||||
<button (click)="submit()" [disabled]="loading()">
|
||||
@if (loading()) {
|
||||
<app-spinner size="sm" />
|
||||
} Submit
|
||||
</button>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## UI State Checklist
|
||||
|
||||
Before completing any UI component:
|
||||
|
||||
### UI States
|
||||
|
||||
- [ ] Error state handled and shown to user
|
||||
- [ ] Loading state shown only when no data exists
|
||||
- [ ] Empty state provided for collections (`@empty` block)
|
||||
- [ ] Buttons disabled during async operations
|
||||
- [ ] Buttons show loading indicator when appropriate
|
||||
|
||||
### Data & Mutations
|
||||
|
||||
- [ ] All async operations have error handling
|
||||
- [ ] All user actions have feedback (toast/visual)
|
||||
- [ ] Optimistic updates rollback on failure
|
||||
|
||||
### Accessibility
|
||||
|
||||
- [ ] Loading states announced to screen readers
|
||||
- [ ] Error messages linked to form fields
|
||||
- [ ] Focus management after state changes
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **angular-state-management**: Use Signal stores for state
|
||||
- **angular**: Apply modern patterns (Signals, @defer)
|
||||
- **testing-patterns**: Test all UI states
|
||||
@@ -1,12 +0,0 @@
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"organization": "Antigravity Awesome Skills",
|
||||
"date": "February 2026",
|
||||
"abstract": "Modern UI patterns for Angular applications designed for AI agents and LLMs. Covers loading states, error handling, progressive disclosure, and data display patterns. Emphasizes showing loading only without data, surfacing all errors, optimistic updates, and graceful degradation using @defer. Includes decision trees and anti-patterns to avoid.",
|
||||
"references": [
|
||||
"https://angular.dev/guide/defer",
|
||||
"https://angular.dev/guide/templates",
|
||||
"https://material.angular.io",
|
||||
"https://ng-spartan.com"
|
||||
]
|
||||
}
|
||||
@@ -1,40 +0,0 @@
|
||||
# Angular
|
||||
|
||||
A comprehensive guide to modern Angular development (v20+) optimized for AI agents and LLMs.
|
||||
|
||||
## Overview
|
||||
|
||||
This skill covers modern Angular patterns including:
|
||||
|
||||
- **Signals** - Angular's reactive primitive for state management
|
||||
- **Standalone Components** - Modern component architecture without NgModules
|
||||
- **Zoneless Applications** - High-performance apps without Zone.js
|
||||
- **SSR & Hydration** - Server-side rendering and client hydration patterns
|
||||
- **Modern Routing** - Functional guards, resolvers, and lazy loading
|
||||
- **Dependency Injection** - Modern DI with `inject()` function
|
||||
- **Reactive Forms** - Type-safe form handling
|
||||
|
||||
## Structure
|
||||
|
||||
This skill is a single, comprehensive `SKILL.md` file containing:
|
||||
|
||||
1. Modern component patterns with Signal inputs/outputs
|
||||
2. State management with Signals and computed values
|
||||
3. Performance optimization techniques
|
||||
4. SSR and hydration best practices
|
||||
5. Migration strategies from legacy Angular patterns
|
||||
|
||||
## Usage
|
||||
|
||||
This skill is designed to be read in full to understand the complete modern Angular development approach, or referenced for specific patterns when needed.
|
||||
|
||||
## Version
|
||||
|
||||
Current version: 1.0.0 (February 2026)
|
||||
|
||||
## References
|
||||
|
||||
- [Angular Documentation](https://angular.dev)
|
||||
- [Angular Signals](https://angular.dev/guide/signals)
|
||||
- [Zoneless Angular](https://angular.dev/guide/zoneless)
|
||||
- [Angular SSR](https://angular.dev/guide/ssr)
|
||||
@@ -1,821 +0,0 @@
|
||||
---
|
||||
name: angular
|
||||
description: >-
|
||||
Modern Angular (v20+) expert with deep knowledge of Signals, Standalone
|
||||
Components, Zoneless applications, SSR/Hydration, and reactive patterns.
|
||||
Use PROACTIVELY for Angular development, component architecture, state
|
||||
management, performance optimization, and migration to modern patterns.
|
||||
risk: safe
|
||||
source: self
|
||||
---
|
||||
|
||||
# Angular Expert
|
||||
|
||||
Master modern Angular development with Signals, Standalone Components, Zoneless applications, SSR/Hydration, and the latest reactive patterns.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Building new Angular applications (v20+)
|
||||
- Implementing Signals-based reactive patterns
|
||||
- Creating Standalone Components and migrating from NgModules
|
||||
- Configuring Zoneless Angular applications
|
||||
- Implementing SSR, prerendering, and hydration
|
||||
- Optimizing Angular performance
|
||||
- Adopting modern Angular patterns and best practices
|
||||
|
||||
## Do Not Use This Skill When
|
||||
|
||||
- Migrating from AngularJS (1.x) → use `angular-migration` skill
|
||||
- Working with legacy Angular apps that cannot upgrade
|
||||
- General TypeScript issues → use `typescript-expert` skill
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Assess the Angular version and project structure
|
||||
2. Apply modern patterns (Signals, Standalone, Zoneless)
|
||||
3. Implement with proper typing and reactivity
|
||||
4. Validate with build and tests
|
||||
|
||||
## Safety
|
||||
|
||||
- Always test changes in development before production
|
||||
- Gradual migration for existing apps (don't big-bang refactor)
|
||||
- Keep backward compatibility during transitions
|
||||
|
||||
---
|
||||
|
||||
## Angular Version Timeline
|
||||
|
||||
| Version | Release | Key Features |
|
||||
| -------------- | ------- | ------------------------------------------------------ |
|
||||
| **Angular 20** | Q2 2025 | Signals stable, Zoneless stable, Incremental hydration |
|
||||
| **Angular 21** | Q4 2025 | Signals-first default, Enhanced SSR |
|
||||
| **Angular 22** | Q2 2026 | Signal Forms, Selectorless components |
|
||||
|
||||
---
|
||||
|
||||
## 1. Signals: The New Reactive Primitive
|
||||
|
||||
Signals are Angular's fine-grained reactivity system, replacing zone.js-based change detection.
|
||||
|
||||
### Core Concepts
|
||||
|
||||
```typescript
|
||||
import { signal, computed, effect } from "@angular/core";
|
||||
|
||||
// Writable signal
|
||||
const count = signal(0);
|
||||
|
||||
// Read value
|
||||
console.log(count()); // 0
|
||||
|
||||
// Update value
|
||||
count.set(5); // Direct set
|
||||
count.update((v) => v + 1); // Functional update
|
||||
|
||||
// Computed (derived) signal
|
||||
const doubled = computed(() => count() * 2);
|
||||
|
||||
// Effect (side effects)
|
||||
effect(() => {
|
||||
console.log(`Count changed to: ${count()}`);
|
||||
});
|
||||
```
|
||||
|
||||
### Signal-Based Inputs and Outputs
|
||||
|
||||
```typescript
|
||||
import { Component, input, output, model } from "@angular/core";
|
||||
|
||||
@Component({
|
||||
selector: "app-user-card",
|
||||
standalone: true,
|
||||
template: `
|
||||
<div class="card">
|
||||
<h3>{{ name() }}</h3>
|
||||
<span>{{ role() }}</span>
|
||||
<button (click)="select.emit(id())">Select</button>
|
||||
</div>
|
||||
`,
|
||||
})
|
||||
export class UserCardComponent {
|
||||
// Signal inputs (read-only)
|
||||
id = input.required<string>();
|
||||
name = input.required<string>();
|
||||
role = input<string>("User"); // With default
|
||||
|
||||
// Output
|
||||
select = output<string>();
|
||||
|
||||
// Two-way binding (model)
|
||||
isSelected = model(false);
|
||||
}
|
||||
|
||||
// Usage:
|
||||
// <app-user-card [id]="'123'" [name]="'John'" [(isSelected)]="selected" />
|
||||
```
|
||||
|
||||
### Signal Queries (ViewChild/ContentChild)
|
||||
|
||||
```typescript
|
||||
import {
|
||||
Component,
|
||||
viewChild,
|
||||
viewChildren,
|
||||
contentChild,
|
||||
} from "@angular/core";
|
||||
|
||||
@Component({
|
||||
selector: "app-container",
|
||||
standalone: true,
|
||||
template: `
|
||||
<input #searchInput />
|
||||
<app-item *ngFor="let item of items()" />
|
||||
`,
|
||||
})
|
||||
export class ContainerComponent {
|
||||
// Signal-based queries
|
||||
searchInput = viewChild<ElementRef>("searchInput");
|
||||
items = viewChildren(ItemComponent);
|
||||
projectedContent = contentChild(HeaderDirective);
|
||||
|
||||
focusSearch() {
|
||||
this.searchInput()?.nativeElement.focus();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### When to Use Signals vs RxJS
|
||||
|
||||
| Use Case | Signals | RxJS |
|
||||
| ----------------------- | --------------- | -------------------------------- |
|
||||
| Local component state | ✅ Preferred | Overkill |
|
||||
| Derived/computed values | ✅ `computed()` | `combineLatest` works |
|
||||
| Side effects | ✅ `effect()` | `tap` operator |
|
||||
| HTTP requests | ❌ | ✅ HttpClient returns Observable |
|
||||
| Event streams | ❌ | ✅ `fromEvent`, operators |
|
||||
| Complex async flows | ❌ | ✅ `switchMap`, `mergeMap` |
|
||||
|
||||
---
|
||||
|
||||
## 2. Standalone Components
|
||||
|
||||
Standalone components are self-contained and don't require NgModule declarations.
|
||||
|
||||
### Creating Standalone Components
|
||||
|
||||
```typescript
|
||||
import { Component } from "@angular/core";
|
||||
import { CommonModule } from "@angular/common";
|
||||
import { RouterLink } from "@angular/router";
|
||||
|
||||
@Component({
|
||||
selector: "app-header",
|
||||
standalone: true,
|
||||
imports: [CommonModule, RouterLink], // Direct imports
|
||||
template: `
|
||||
<header>
|
||||
<a routerLink="/">Home</a>
|
||||
<a routerLink="/about">About</a>
|
||||
</header>
|
||||
`,
|
||||
})
|
||||
export class HeaderComponent {}
|
||||
```
|
||||
|
||||
### Bootstrapping Without NgModule
|
||||
|
||||
```typescript
|
||||
// main.ts
|
||||
import { bootstrapApplication } from "@angular/platform-browser";
|
||||
import { provideRouter } from "@angular/router";
|
||||
import { provideHttpClient } from "@angular/common/http";
|
||||
import { AppComponent } from "./app/app.component";
|
||||
import { routes } from "./app/app.routes";
|
||||
|
||||
bootstrapApplication(AppComponent, {
|
||||
providers: [provideRouter(routes), provideHttpClient()],
|
||||
});
|
||||
```
|
||||
|
||||
### Lazy Loading Standalone Components
|
||||
|
||||
```typescript
|
||||
// app.routes.ts
|
||||
import { Routes } from "@angular/router";
|
||||
|
||||
export const routes: Routes = [
|
||||
{
|
||||
path: "dashboard",
|
||||
loadComponent: () =>
|
||||
import("./dashboard/dashboard.component").then(
|
||||
(m) => m.DashboardComponent,
|
||||
),
|
||||
},
|
||||
{
|
||||
path: "admin",
|
||||
loadChildren: () =>
|
||||
import("./admin/admin.routes").then((m) => m.ADMIN_ROUTES),
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Zoneless Angular
|
||||
|
||||
Zoneless applications don't use zone.js, improving performance and debugging.
|
||||
|
||||
### Enabling Zoneless Mode
|
||||
|
||||
```typescript
|
||||
// main.ts
|
||||
import { bootstrapApplication } from "@angular/platform-browser";
|
||||
import { provideZonelessChangeDetection } from "@angular/core";
|
||||
import { AppComponent } from "./app/app.component";
|
||||
|
||||
bootstrapApplication(AppComponent, {
|
||||
providers: [provideZonelessChangeDetection()],
|
||||
});
|
||||
```
|
||||
|
||||
### Zoneless Component Patterns
|
||||
|
||||
```typescript
|
||||
import { Component, signal, ChangeDetectionStrategy } from "@angular/core";
|
||||
|
||||
@Component({
|
||||
selector: "app-counter",
|
||||
standalone: true,
|
||||
changeDetection: ChangeDetectionStrategy.OnPush,
|
||||
template: `
|
||||
<div>Count: {{ count() }}</div>
|
||||
<button (click)="increment()">+</button>
|
||||
`,
|
||||
})
|
||||
export class CounterComponent {
|
||||
count = signal(0);
|
||||
|
||||
increment() {
|
||||
this.count.update((v) => v + 1);
|
||||
// No zone.js needed - Signal triggers change detection
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Key Zoneless Benefits
|
||||
|
||||
- **Performance**: No zone.js patches on async APIs
|
||||
- **Debugging**: Clean stack traces without zone wrappers
|
||||
- **Bundle size**: Smaller without zone.js (~15KB savings)
|
||||
- **Interoperability**: Better with Web Components and micro-frontends
|
||||
|
||||
---
|
||||
|
||||
## 4. Server-Side Rendering & Hydration
|
||||
|
||||
### SSR Setup with Angular CLI
|
||||
|
||||
```bash
|
||||
ng add @angular/ssr
|
||||
```
|
||||
|
||||
### Hydration Configuration
|
||||
|
||||
```typescript
|
||||
// app.config.ts
|
||||
import { ApplicationConfig } from "@angular/core";
|
||||
import {
|
||||
provideClientHydration,
|
||||
withEventReplay,
|
||||
} from "@angular/platform-browser";
|
||||
|
||||
export const appConfig: ApplicationConfig = {
|
||||
providers: [provideClientHydration(withEventReplay())],
|
||||
};
|
||||
```
|
||||
|
||||
### Incremental Hydration (v20+)
|
||||
|
||||
```typescript
|
||||
import { Component } from "@angular/core";
|
||||
|
||||
@Component({
|
||||
selector: "app-page",
|
||||
standalone: true,
|
||||
template: `
|
||||
<app-hero />
|
||||
|
||||
@defer (hydrate on viewport) {
|
||||
<app-comments />
|
||||
}
|
||||
|
||||
@defer (hydrate on interaction) {
|
||||
<app-chat-widget />
|
||||
}
|
||||
`,
|
||||
})
|
||||
export class PageComponent {}
|
||||
```
|
||||
|
||||
### Hydration Triggers
|
||||
|
||||
| Trigger | When to Use |
|
||||
| ---------------- | --------------------------------------- |
|
||||
| `on idle` | Low-priority, hydrate when browser idle |
|
||||
| `on viewport` | Hydrate when element enters viewport |
|
||||
| `on interaction` | Hydrate on first user interaction |
|
||||
| `on hover` | Hydrate when user hovers |
|
||||
| `on timer(ms)` | Hydrate after specified delay |
|
||||
|
||||
---
|
||||
|
||||
## 5. Modern Routing Patterns
|
||||
|
||||
### Functional Route Guards
|
||||
|
||||
```typescript
|
||||
// auth.guard.ts
|
||||
import { inject } from "@angular/core";
|
||||
import { Router, CanActivateFn } from "@angular/router";
|
||||
import { AuthService } from "./auth.service";
|
||||
|
||||
export const authGuard: CanActivateFn = (route, state) => {
|
||||
const auth = inject(AuthService);
|
||||
const router = inject(Router);
|
||||
|
||||
if (auth.isAuthenticated()) {
|
||||
return true;
|
||||
}
|
||||
|
||||
return router.createUrlTree(["/login"], {
|
||||
queryParams: { returnUrl: state.url },
|
||||
});
|
||||
};
|
||||
|
||||
// Usage in routes
|
||||
export const routes: Routes = [
|
||||
{
|
||||
path: "dashboard",
|
||||
loadComponent: () => import("./dashboard.component"),
|
||||
canActivate: [authGuard],
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
### Route-Level Data Resolvers
|
||||
|
||||
```typescript
|
||||
import { inject } from '@angular/core';
|
||||
import { ResolveFn } from '@angular/router';
|
||||
import { UserService } from './user.service';
|
||||
import { User } from './user.model';
|
||||
|
||||
export const userResolver: ResolveFn<User> = (route) => {
|
||||
const userService = inject(UserService);
|
||||
return userService.getUser(route.paramMap.get('id')!);
|
||||
};
|
||||
|
||||
// In routes
|
||||
{
|
||||
path: 'user/:id',
|
||||
loadComponent: () => import('./user.component'),
|
||||
resolve: { user: userResolver }
|
||||
}
|
||||
|
||||
// In component
|
||||
export class UserComponent {
|
||||
private route = inject(ActivatedRoute);
|
||||
user = toSignal(this.route.data.pipe(map(d => d['user'])));
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Dependency Injection Patterns
|
||||
|
||||
### Modern inject() Function
|
||||
|
||||
```typescript
|
||||
import { Component, inject } from '@angular/core';
|
||||
import { HttpClient } from '@angular/common/http';
|
||||
import { UserService } from './user.service';
|
||||
|
||||
@Component({...})
|
||||
export class UserComponent {
|
||||
// Modern inject() - no constructor needed
|
||||
private http = inject(HttpClient);
|
||||
private userService = inject(UserService);
|
||||
|
||||
// Works in any injection context
|
||||
users = toSignal(this.userService.getUsers());
|
||||
}
|
||||
```
|
||||
|
||||
### Injection Tokens for Configuration
|
||||
|
||||
```typescript
|
||||
import { InjectionToken, inject } from "@angular/core";
|
||||
|
||||
// Define token
|
||||
export const API_BASE_URL = new InjectionToken<string>("API_BASE_URL");
|
||||
|
||||
// Provide in config
|
||||
bootstrapApplication(AppComponent, {
|
||||
providers: [{ provide: API_BASE_URL, useValue: "https://api.example.com" }],
|
||||
});
|
||||
|
||||
// Inject in service
|
||||
@Injectable({ providedIn: "root" })
|
||||
export class ApiService {
|
||||
private baseUrl = inject(API_BASE_URL);
|
||||
|
||||
get(endpoint: string) {
|
||||
return this.http.get(`${this.baseUrl}/${endpoint}`);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Component Composition & Reusability
|
||||
|
||||
### Content Projection (Slots)
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: 'app-card',
|
||||
template: `
|
||||
<div class="card">
|
||||
<div class="header">
|
||||
<!-- Select by attribute -->
|
||||
<ng-content select="[card-header]"></ng-content>
|
||||
</div>
|
||||
<div class="body">
|
||||
<!-- Default slot -->
|
||||
<ng-content></ng-content>
|
||||
</div>
|
||||
</div>
|
||||
`
|
||||
})
|
||||
export class CardComponent {}
|
||||
|
||||
// Usage
|
||||
<app-card>
|
||||
<h3 card-header>Title</h3>
|
||||
<p>Body content</p>
|
||||
</app-card>
|
||||
```
|
||||
|
||||
### Host Directives (Composition)
|
||||
|
||||
```typescript
|
||||
// Reusable behaviors without inheritance
|
||||
@Directive({
|
||||
standalone: true,
|
||||
selector: '[appTooltip]',
|
||||
inputs: ['tooltip'] // Signal input alias
|
||||
})
|
||||
export class TooltipDirective { ... }
|
||||
|
||||
@Component({
|
||||
selector: 'app-button',
|
||||
standalone: true,
|
||||
hostDirectives: [
|
||||
{
|
||||
directive: TooltipDirective,
|
||||
inputs: ['tooltip: title'] // Map input
|
||||
}
|
||||
],
|
||||
template: `<ng-content />`
|
||||
})
|
||||
export class ButtonComponent {}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. State Management Patterns
|
||||
|
||||
### Signal-Based State Service
|
||||
|
||||
```typescript
|
||||
import { Injectable, signal, computed } from "@angular/core";
|
||||
|
||||
interface AppState {
|
||||
user: User | null;
|
||||
theme: "light" | "dark";
|
||||
notifications: Notification[];
|
||||
}
|
||||
|
||||
@Injectable({ providedIn: "root" })
|
||||
export class StateService {
|
||||
// Private writable signals
|
||||
private _user = signal<User | null>(null);
|
||||
private _theme = signal<"light" | "dark">("light");
|
||||
private _notifications = signal<Notification[]>([]);
|
||||
|
||||
// Public read-only computed
|
||||
readonly user = computed(() => this._user());
|
||||
readonly theme = computed(() => this._theme());
|
||||
readonly notifications = computed(() => this._notifications());
|
||||
readonly unreadCount = computed(
|
||||
() => this._notifications().filter((n) => !n.read).length,
|
||||
);
|
||||
|
||||
// Actions
|
||||
setUser(user: User | null) {
|
||||
this._user.set(user);
|
||||
}
|
||||
|
||||
toggleTheme() {
|
||||
this._theme.update((t) => (t === "light" ? "dark" : "light"));
|
||||
}
|
||||
|
||||
addNotification(notification: Notification) {
|
||||
this._notifications.update((n) => [...n, notification]);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Component Store Pattern with Signals
|
||||
|
||||
```typescript
|
||||
import { Injectable, signal, computed, inject } from "@angular/core";
|
||||
import { HttpClient } from "@angular/common/http";
|
||||
import { toSignal } from "@angular/core/rxjs-interop";
|
||||
|
||||
@Injectable()
|
||||
export class ProductStore {
|
||||
private http = inject(HttpClient);
|
||||
|
||||
// State
|
||||
private _products = signal<Product[]>([]);
|
||||
private _loading = signal(false);
|
||||
private _filter = signal("");
|
||||
|
||||
// Selectors
|
||||
readonly products = computed(() => this._products());
|
||||
readonly loading = computed(() => this._loading());
|
||||
readonly filteredProducts = computed(() => {
|
||||
const filter = this._filter().toLowerCase();
|
||||
return this._products().filter((p) =>
|
||||
p.name.toLowerCase().includes(filter),
|
||||
);
|
||||
});
|
||||
|
||||
// Actions
|
||||
loadProducts() {
|
||||
this._loading.set(true);
|
||||
this.http.get<Product[]>("/api/products").subscribe({
|
||||
next: (products) => {
|
||||
this._products.set(products);
|
||||
this._loading.set(false);
|
||||
},
|
||||
error: () => this._loading.set(false),
|
||||
});
|
||||
}
|
||||
|
||||
setFilter(filter: string) {
|
||||
this._filter.set(filter);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Forms with Signals (Coming in v22+)
|
||||
|
||||
### Current Reactive Forms
|
||||
|
||||
```typescript
|
||||
import { Component, inject } from "@angular/core";
|
||||
import { FormBuilder, Validators, ReactiveFormsModule } from "@angular/forms";
|
||||
|
||||
@Component({
|
||||
selector: "app-user-form",
|
||||
standalone: true,
|
||||
imports: [ReactiveFormsModule],
|
||||
template: `
|
||||
<form [formGroup]="form" (ngSubmit)="onSubmit()">
|
||||
<input formControlName="name" placeholder="Name" />
|
||||
<input formControlName="email" type="email" placeholder="Email" />
|
||||
<button [disabled]="form.invalid">Submit</button>
|
||||
</form>
|
||||
`,
|
||||
})
|
||||
export class UserFormComponent {
|
||||
private fb = inject(FormBuilder);
|
||||
|
||||
form = this.fb.group({
|
||||
name: ["", Validators.required],
|
||||
email: ["", [Validators.required, Validators.email]],
|
||||
});
|
||||
|
||||
onSubmit() {
|
||||
if (this.form.valid) {
|
||||
console.log(this.form.value);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Signal-Aware Form Patterns (Preview)
|
||||
|
||||
```typescript
|
||||
// Future Signal Forms API (experimental)
|
||||
import { Component, signal } from '@angular/core';
|
||||
|
||||
@Component({...})
|
||||
export class SignalFormComponent {
|
||||
name = signal('');
|
||||
email = signal('');
|
||||
|
||||
// Computed validation
|
||||
isValid = computed(() =>
|
||||
this.name().length > 0 &&
|
||||
this.email().includes('@')
|
||||
);
|
||||
|
||||
submit() {
|
||||
if (this.isValid()) {
|
||||
console.log({ name: this.name(), email: this.email() });
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Performance Optimization
|
||||
|
||||
### Change Detection Strategies
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
changeDetection: ChangeDetectionStrategy.OnPush,
|
||||
// Only checks when:
|
||||
// 1. Input signal/reference changes
|
||||
// 2. Event handler runs
|
||||
// 3. Async pipe emits
|
||||
// 4. Signal value changes
|
||||
})
|
||||
```
|
||||
|
||||
### Defer Blocks for Lazy Loading
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
template: `
|
||||
<!-- Immediate loading -->
|
||||
<app-header />
|
||||
|
||||
<!-- Lazy load when visible -->
|
||||
@defer (on viewport) {
|
||||
<app-heavy-chart />
|
||||
} @placeholder {
|
||||
<div class="skeleton" />
|
||||
} @loading (minimum 200ms) {
|
||||
<app-spinner />
|
||||
} @error {
|
||||
<p>Failed to load chart</p>
|
||||
}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
### NgOptimizedImage
|
||||
|
||||
```typescript
|
||||
import { NgOptimizedImage } from '@angular/common';
|
||||
|
||||
@Component({
|
||||
imports: [NgOptimizedImage],
|
||||
template: `
|
||||
<img
|
||||
ngSrc="hero.jpg"
|
||||
width="800"
|
||||
height="600"
|
||||
priority
|
||||
/>
|
||||
|
||||
<img
|
||||
ngSrc="thumbnail.jpg"
|
||||
width="200"
|
||||
height="150"
|
||||
loading="lazy"
|
||||
placeholder="blur"
|
||||
/>
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Testing Modern Angular
|
||||
|
||||
### Testing Signal Components
|
||||
|
||||
```typescript
|
||||
import { ComponentFixture, TestBed } from "@angular/core/testing";
|
||||
import { CounterComponent } from "./counter.component";
|
||||
|
||||
describe("CounterComponent", () => {
|
||||
let component: CounterComponent;
|
||||
let fixture: ComponentFixture<CounterComponent>;
|
||||
|
||||
beforeEach(async () => {
|
||||
await TestBed.configureTestingModule({
|
||||
imports: [CounterComponent], // Standalone import
|
||||
}).compileComponents();
|
||||
|
||||
fixture = TestBed.createComponent(CounterComponent);
|
||||
component = fixture.componentInstance;
|
||||
fixture.detectChanges();
|
||||
});
|
||||
|
||||
it("should increment count", () => {
|
||||
expect(component.count()).toBe(0);
|
||||
|
||||
component.increment();
|
||||
|
||||
expect(component.count()).toBe(1);
|
||||
});
|
||||
|
||||
it("should update DOM on signal change", () => {
|
||||
component.count.set(5);
|
||||
fixture.detectChanges();
|
||||
|
||||
const el = fixture.nativeElement.querySelector(".count");
|
||||
expect(el.textContent).toContain("5");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Testing with Signal Inputs
|
||||
|
||||
```typescript
|
||||
import { ComponentFixture, TestBed } from "@angular/core/testing";
|
||||
import { ComponentRef } from "@angular/core";
|
||||
import { UserCardComponent } from "./user-card.component";
|
||||
|
||||
describe("UserCardComponent", () => {
|
||||
let fixture: ComponentFixture<UserCardComponent>;
|
||||
let componentRef: ComponentRef<UserCardComponent>;
|
||||
|
||||
beforeEach(async () => {
|
||||
await TestBed.configureTestingModule({
|
||||
imports: [UserCardComponent],
|
||||
}).compileComponents();
|
||||
|
||||
fixture = TestBed.createComponent(UserCardComponent);
|
||||
componentRef = fixture.componentRef;
|
||||
|
||||
// Set signal inputs via setInput
|
||||
componentRef.setInput("id", "123");
|
||||
componentRef.setInput("name", "John Doe");
|
||||
|
||||
fixture.detectChanges();
|
||||
});
|
||||
|
||||
it("should display user name", () => {
|
||||
const el = fixture.nativeElement.querySelector("h3");
|
||||
expect(el.textContent).toContain("John Doe");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
| Pattern | ✅ Do | ❌ Don't |
|
||||
| -------------------- | ------------------------------ | ------------------------------- |
|
||||
| **State** | Use Signals for local state | Overuse RxJS for simple state |
|
||||
| **Components** | Standalone with direct imports | Bloated SharedModules |
|
||||
| **Change Detection** | OnPush + Signals | Default CD everywhere |
|
||||
| **Lazy Loading** | `@defer` and `loadComponent` | Eager load everything |
|
||||
| **DI** | `inject()` function | Constructor injection (verbose) |
|
||||
| **Inputs** | `input()` signal function | `@Input()` decorator (legacy) |
|
||||
| **Zoneless** | Enable for new projects | Force on legacy without testing |
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- [Angular.dev Documentation](https://angular.dev)
|
||||
- [Angular Signals Guide](https://angular.dev/guide/signals)
|
||||
- [Angular SSR Guide](https://angular.dev/guide/ssr)
|
||||
- [Angular Update Guide](https://angular.dev/update-guide)
|
||||
- [Angular Blog](https://blog.angular.dev)
|
||||
|
||||
---
|
||||
|
||||
## Common Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
| ------------------------------ | --------------------------------------------------- |
|
||||
| Signal not updating UI | Ensure `OnPush` + call signal as function `count()` |
|
||||
| Hydration mismatch | Check server/client content consistency |
|
||||
| Circular dependency | Use `inject()` with `forwardRef` |
|
||||
| Zoneless not detecting changes | Trigger via signal updates, not mutations |
|
||||
| SSR fetch fails | Use `TransferState` or `withFetch()` |
|
||||
@@ -1,14 +0,0 @@
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"organization": "Antigravity Awesome Skills",
|
||||
"date": "February 2026",
|
||||
"abstract": "Comprehensive guide to modern Angular development (v20+) designed for AI agents and LLMs. Covers Signals, Standalone Components, Zoneless applications, SSR/Hydration, reactive patterns, routing, dependency injection, and modern forms. Emphasizes component-driven architecture with practical examples and migration strategies for modernizing existing codebases.",
|
||||
"references": [
|
||||
"https://angular.dev",
|
||||
"https://angular.dev/guide/signals",
|
||||
"https://angular.dev/guide/zoneless",
|
||||
"https://angular.dev/guide/ssr",
|
||||
"https://angular.dev/guide/standalone-components",
|
||||
"https://angular.dev/guide/defer"
|
||||
]
|
||||
}
|
||||
@@ -186,7 +186,7 @@ class CompetitorAnalyzer:
|
||||
|
||||
def _analyze_title(self, title: str) -> Dict[str, Any]:
|
||||
"""Analyze title structure and keyword usage."""
|
||||
parts = re.split(r'[-' + r':|]', title)
|
||||
parts = re.split(r'[-:|]', title)
|
||||
|
||||
return {
|
||||
'title': title,
|
||||
|
||||
@@ -1,171 +0,0 @@
|
||||
---
|
||||
name: asana-automation
|
||||
description: "Automate Asana tasks via Rube MCP (Composio): tasks, projects, sections, teams, workspaces. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Asana Automation via Rube MCP
|
||||
|
||||
Automate Asana operations through Composio's Asana toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Asana connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `asana`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `asana`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Asana OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Manage Tasks
|
||||
|
||||
**When to use**: User wants to create, search, list, or organize tasks
|
||||
|
||||
**Tool sequence**:
|
||||
1. `ASANA_GET_MULTIPLE_WORKSPACES` - Get workspace ID [Prerequisite]
|
||||
2. `ASANA_SEARCH_TASKS_IN_WORKSPACE` - Search tasks [Optional]
|
||||
3. `ASANA_GET_TASKS_FROM_A_PROJECT` - List project tasks [Optional]
|
||||
4. `ASANA_CREATE_A_TASK` - Create a new task [Optional]
|
||||
5. `ASANA_GET_A_TASK` - Get task details [Optional]
|
||||
6. `ASANA_CREATE_SUBTASK` - Create a subtask [Optional]
|
||||
7. `ASANA_GET_TASK_SUBTASKS` - List subtasks [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `workspace`: Workspace GID (required for search/creation)
|
||||
- `projects`: Array of project GIDs to add task to
|
||||
- `name`: Task name
|
||||
- `notes`: Task description
|
||||
- `assignee`: Assignee (user GID or email)
|
||||
- `due_on`: Due date (YYYY-MM-DD)
|
||||
|
||||
**Pitfalls**:
|
||||
- Workspace GID is required for most operations; get it first
|
||||
- Task GIDs are returned as strings, not integers
|
||||
- Search is workspace-scoped, not project-scoped
|
||||
|
||||
### 2. Manage Projects and Sections
|
||||
|
||||
**When to use**: User wants to create projects, manage sections, or organize tasks
|
||||
|
||||
**Tool sequence**:
|
||||
1. `ASANA_GET_WORKSPACE_PROJECTS` - List workspace projects [Optional]
|
||||
2. `ASANA_GET_A_PROJECT` - Get project details [Optional]
|
||||
3. `ASANA_CREATE_A_PROJECT` - Create a new project [Optional]
|
||||
4. `ASANA_GET_SECTIONS_IN_PROJECT` - List sections [Optional]
|
||||
5. `ASANA_CREATE_SECTION_IN_PROJECT` - Create a new section [Optional]
|
||||
6. `ASANA_ADD_TASK_TO_SECTION` - Move task to section [Optional]
|
||||
7. `ASANA_GET_TASKS_FROM_A_SECTION` - List tasks in section [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `project_gid`: Project GID
|
||||
- `name`: Project or section name
|
||||
- `workspace`: Workspace GID for creation
|
||||
- `task`: Task GID for section assignment
|
||||
- `section`: Section GID
|
||||
|
||||
**Pitfalls**:
|
||||
- Projects belong to workspaces; workspace GID is needed for creation
|
||||
- Sections are ordered within a project
|
||||
- DUPLICATE_PROJECT creates a copy with optional task inclusion
|
||||
|
||||
### 3. Manage Teams and Users
|
||||
|
||||
**When to use**: User wants to list teams, team members, or workspace users
|
||||
|
||||
**Tool sequence**:
|
||||
1. `ASANA_GET_TEAMS_IN_WORKSPACE` - List workspace teams [Optional]
|
||||
2. `ASANA_GET_USERS_FOR_TEAM` - List team members [Optional]
|
||||
3. `ASANA_GET_USERS_FOR_WORKSPACE` - List all workspace users [Optional]
|
||||
4. `ASANA_GET_CURRENT_USER` - Get authenticated user [Optional]
|
||||
5. `ASANA_GET_MULTIPLE_USERS` - Get multiple user details [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `workspace_gid`: Workspace GID
|
||||
- `team_gid`: Team GID
|
||||
|
||||
**Pitfalls**:
|
||||
- Users are workspace-scoped
|
||||
- Team membership requires the team GID
|
||||
|
||||
### 4. Parallel Operations
|
||||
|
||||
**When to use**: User needs to perform bulk operations efficiently
|
||||
|
||||
**Tool sequence**:
|
||||
1. `ASANA_SUBMIT_PARALLEL_REQUESTS` - Execute multiple API calls in parallel [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `actions`: Array of action objects with method, path, and data
|
||||
|
||||
**Pitfalls**:
|
||||
- Each action must be a valid Asana API call
|
||||
- Failed individual requests do not roll back successful ones
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Workspace name -> GID**:
|
||||
```
|
||||
1. Call ASANA_GET_MULTIPLE_WORKSPACES
|
||||
2. Find workspace by name
|
||||
3. Extract gid field
|
||||
```
|
||||
|
||||
**Project name -> GID**:
|
||||
```
|
||||
1. Call ASANA_GET_WORKSPACE_PROJECTS with workspace GID
|
||||
2. Find project by name
|
||||
3. Extract gid field
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Asana uses cursor-based pagination with `offset` parameter
|
||||
- Check for `next_page` in response
|
||||
- Pass `offset` from `next_page.offset` for next request
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**GID Format**:
|
||||
- All Asana IDs are strings (GIDs), not integers
|
||||
- GIDs are globally unique identifiers
|
||||
|
||||
**Workspace Scoping**:
|
||||
- Most operations require a workspace context
|
||||
- Tasks, projects, and users are workspace-scoped
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List workspaces | ASANA_GET_MULTIPLE_WORKSPACES | (none) |
|
||||
| Search tasks | ASANA_SEARCH_TASKS_IN_WORKSPACE | workspace, text |
|
||||
| Create task | ASANA_CREATE_A_TASK | workspace, name, projects |
|
||||
| Get task | ASANA_GET_A_TASK | task_gid |
|
||||
| Create subtask | ASANA_CREATE_SUBTASK | parent, name |
|
||||
| List subtasks | ASANA_GET_TASK_SUBTASKS | task_gid |
|
||||
| Project tasks | ASANA_GET_TASKS_FROM_A_PROJECT | project_gid |
|
||||
| List projects | ASANA_GET_WORKSPACE_PROJECTS | workspace |
|
||||
| Create project | ASANA_CREATE_A_PROJECT | workspace, name |
|
||||
| Get project | ASANA_GET_A_PROJECT | project_gid |
|
||||
| Duplicate project | ASANA_DUPLICATE_PROJECT | project_gid |
|
||||
| List sections | ASANA_GET_SECTIONS_IN_PROJECT | project_gid |
|
||||
| Create section | ASANA_CREATE_SECTION_IN_PROJECT | project_gid, name |
|
||||
| Add to section | ASANA_ADD_TASK_TO_SECTION | section, task |
|
||||
| Section tasks | ASANA_GET_TASKS_FROM_A_SECTION | section_gid |
|
||||
| List teams | ASANA_GET_TEAMS_IN_WORKSPACE | workspace_gid |
|
||||
| Team members | ASANA_GET_USERS_FOR_TEAM | team_gid |
|
||||
| Workspace users | ASANA_GET_USERS_FOR_WORKSPACE | workspace_gid |
|
||||
| Current user | ASANA_GET_CURRENT_USER | (none) |
|
||||
| Parallel requests | ASANA_SUBMIT_PARALLEL_REQUESTS | actions |
|
||||
@@ -1,137 +0,0 @@
|
||||
# Changelog - audio-transcriber
|
||||
|
||||
All notable changes to the audio-transcriber skill will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
---
|
||||
|
||||
## [1.1.0] - 2026-02-03
|
||||
|
||||
### ✨ Added
|
||||
|
||||
- **Intelligent Prompt Workflow** (Step 3b) - Complete integration with prompt-engineer skill
|
||||
- **Scenario A**: User-provided prompts are automatically improved with prompt-engineer
|
||||
- Displays both original and improved versions side-by-side
|
||||
- Single confirmation: "Usar versão melhorada? [s/n]"
|
||||
- **Scenario B**: Auto-generation when no prompt provided
|
||||
- Analyzes transcript and suggests document type (ata, resumo, notas)
|
||||
- Shows suggestion and asks confirmation
|
||||
- Generates complete structured prompt (RISEN/RODES/STAR)
|
||||
- Shows preview and asks final confirmation
|
||||
- Falls back to DEFAULT_MEETING_PROMPT if declined
|
||||
|
||||
- **LLM Integration** - Process transcripts with Claude CLI or GitHub Copilot CLI
|
||||
- Priority: Claude > GitHub Copilot > None (transcript-only mode)
|
||||
- Step 0b: CLI detection logic documented
|
||||
- Timeout handling (5 minutes default)
|
||||
- Graceful fallback if CLI unavailable
|
||||
|
||||
- **Progress Indicators** - Visual feedback during long operations
|
||||
- `tqdm` progress bar for Whisper transcription segments
|
||||
- `rich` spinner for LLM processing
|
||||
- Clear status messages at each step
|
||||
|
||||
- **Timestamp-based File Naming** - Avoid overwriting previous transcriptions
|
||||
- Format: `transcript-YYYYMMDD-HHMMSS.md`
|
||||
- Format: `ata-YYYYMMDD-HHMMSS.md`
|
||||
- Prevents data loss from repeated runs
|
||||
|
||||
- **Automatic Cleanup** - Remove temporary files after processing
|
||||
- Deletes `metadata.json` and `transcription.json` automatically
|
||||
- `--keep-temp` flag to preserve if needed
|
||||
- Clean output directory
|
||||
|
||||
- **Rich Terminal UI** - Beautiful output with `rich` library
|
||||
- Formatted panels for prompt previews
|
||||
- Color-coded status messages (green=success, yellow=warning, red=error)
|
||||
- Spinner animations for long-running tasks
|
||||
|
||||
- **Dual Output Support** - Generate both transcript and processed ata
|
||||
- `transcript-*.md` - Raw transcription with timestamps
|
||||
- `ata-*.md` - Intelligent summary/meeting minutes (if LLM available)
|
||||
- User can decline LLM processing to get transcript-only
|
||||
|
||||
### 🔧 Changed
|
||||
|
||||
- **SKILL.md** - Major documentation updates
|
||||
- Added Step 0b (CLI Detection)
|
||||
- Updated Step 2 (Progress Indicators)
|
||||
- Added Step 3b (Intelligent Prompt Workflow with 150+ lines)
|
||||
- Updated version to 1.1.0
|
||||
- Added detailed workflow diagrams for both scenarios
|
||||
|
||||
- **install-requirements.sh** - Added UI libraries
|
||||
- Now installs `tqdm` and `rich` packages
|
||||
- Graceful fallback if installation fails
|
||||
- Updated success messages
|
||||
|
||||
- **Python Implementation** - Complete refactor
|
||||
- Created `scripts/transcribe.py` (516 lines)
|
||||
- Functions: `detect_cli_tool()`, `invoke_prompt_engineer()`, `handle_prompt_workflow()`, `process_with_llm()`, `transcribe_audio()`, `save_outputs()`, `cleanup_temp_files()`
|
||||
- Command-line arguments: `--prompt`, `--model`, `--output-dir`, `--keep-temp`
|
||||
- Auto-installs `rich` and `tqdm` if missing
|
||||
|
||||
### 🐛 Fixed
|
||||
|
||||
- **User prompts no longer ignored** - v1.0.0 completely ignored custom prompts
|
||||
- Now processes all prompts (custom or auto-generated) with LLM
|
||||
- Improves simple prompts into structured frameworks
|
||||
|
||||
- **Temporary files cleanup** - v1.0.0 left `metadata.json` and `transcription.json` as trash
|
||||
- Now automatically removed after processing
|
||||
- Clean output directory
|
||||
|
||||
- **File overwriting** - v1.0.0 used same filename (e.g., `meeting.md`) every time
|
||||
- Now uses timestamp to prevent data loss
|
||||
- Each run creates unique files
|
||||
|
||||
- **Missing ata/summary** - v1.0.0 only generated raw transcript
|
||||
- Now generates intelligent ata/resumo using LLM
|
||||
- Respects user's prompt instructions
|
||||
|
||||
- **No progress feedback** - v1.0.0 had silent processing (users didn't know if it froze)
|
||||
- Now shows progress bar for transcription
|
||||
- Shows spinner for LLM processing
|
||||
- Clear status messages throughout
|
||||
|
||||
### 📝 Notes
|
||||
|
||||
- **Backward Compatibility:** Fully compatible with v1.0.0 workflows
|
||||
- **Requires:** Python 3.8+, faster-whisper OR whisper, tqdm, rich
|
||||
- **Optional:** Claude CLI or GitHub Copilot CLI for intelligent processing
|
||||
- **Optional:** prompt-engineer skill for automatic prompt generation
|
||||
|
||||
### 🔗 Related Issues
|
||||
|
||||
- Fixes #1: Prompt do usuário RISEN ignorado
|
||||
- Fixes #2: Arquivos temporários (metadata.json, transcription.json) deixados como lixo
|
||||
- Fixes #3: Output incompleto (apenas transcript RAW, sem ata)
|
||||
- Fixes #4: Falta de indicador de progresso visual
|
||||
- Fixes #5: Formato de saída sem timestamp
|
||||
|
||||
---
|
||||
|
||||
## [1.0.0] - 2026-02-02
|
||||
|
||||
### ✨ Initial Release
|
||||
|
||||
- Audio transcription using Faster-Whisper or OpenAI Whisper
|
||||
- Automatic language detection
|
||||
- Speaker diarization (basic)
|
||||
- Voice Activity Detection (VAD)
|
||||
- Markdown output with metadata table
|
||||
- Installation script for dependencies
|
||||
- Example scripts for basic transcription
|
||||
- Support for multiple audio formats (MP3, WAV, M4A, OGG, FLAC, WEBM)
|
||||
- FFmpeg integration for format conversion
|
||||
- Zero-configuration philosophy
|
||||
|
||||
### 📝 Known Limitations (Fixed in v1.1.0)
|
||||
|
||||
- User prompts ignored (no LLM integration)
|
||||
- Only raw transcript generated (no ata/summary)
|
||||
- Temporary files not cleaned up
|
||||
- No progress indicators
|
||||
- Files overwritten on repeated runs
|
||||
@@ -1,340 +0,0 @@
|
||||
# Audio Transcriber Skill v1.1.0
|
||||
|
||||
Transform audio recordings into professional Markdown documentation with **intelligent atas/summaries using LLM integration** (Claude/Copilot CLI) and automatic prompt engineering.
|
||||
|
||||
## 🆕 What's New in v1.1.0
|
||||
|
||||
- **🧠 LLM Integration** - Claude CLI (primary) or GitHub Copilot CLI (fallback) for intelligent processing
|
||||
- **✨ Smart Prompts** - Automatic integration with prompt-engineer skill
|
||||
- User-provided prompts → automatically improved → user chooses version
|
||||
- No prompt → analyzes transcript → suggests format → generates structured prompt
|
||||
- **📊 Progress Indicators** - Visual progress bars (tqdm) and spinners (rich)
|
||||
- **📁 Timestamp Filenames** - `transcript-YYYYMMDD-HHMMSS.md` + `ata-YYYYMMDD-HHMMSS.md`
|
||||
- **🧹 Auto-Cleanup** - Removes temporary `metadata.json` and `transcription.json`
|
||||
- **🎨 Rich Terminal UI** - Beautiful formatted output with panels and colors
|
||||
|
||||
See **[CHANGELOG.md](./CHANGELOG.md)** for complete v1.1.0 details.
|
||||
|
||||
## 🎯 Core Features
|
||||
|
||||
- **📝 Rich Markdown Output** - Structured reports with metadata tables, timestamps, and formatting
|
||||
- **🎙️ Speaker Diarization** - Automatically identifies and labels different speakers
|
||||
- **📊 Technical Metadata** - Extracts file size, duration, language, processing time
|
||||
- **📋 Intelligent Atas/Summaries** - Generated via LLM (Claude/Copilot) with customizable prompts
|
||||
- **💡 Executive Summaries** - AI-generated structured summaries with topics, decisions, action items
|
||||
- **🌍 Multi-language** - Supports 99 languages with auto-detection
|
||||
- **⚡ Zero Configuration** - Auto-discovers Faster-Whisper/Whisper installation
|
||||
- **🔒 Privacy-First** - 100% local Whisper processing, no cloud uploads
|
||||
- **🚀 Flexible Modes** - Transcript-only or intelligent processing with LLM
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
### Quick Install (NPX)
|
||||
|
||||
```bash
|
||||
npx cli-ai-skills@latest install audio-transcriber
|
||||
```
|
||||
|
||||
This automatically:
|
||||
- Downloads the skill
|
||||
- Installs Python dependencies (faster-whisper, tqdm, rich)
|
||||
- Installs ffmpeg (macOS via Homebrew)
|
||||
- Sets up the skill globally
|
||||
|
||||
### Manual Installation
|
||||
|
||||
#### 1. Install Transcription Engine
|
||||
|
||||
**Recommended (fastest):**
|
||||
```bash
|
||||
pip install faster-whisper tqdm rich
|
||||
```
|
||||
|
||||
**Alternative (original Whisper):**
|
||||
```bash
|
||||
pip install openai-whisper tqdm rich
|
||||
```
|
||||
|
||||
#### 2. Install Audio Tools (Optional)
|
||||
|
||||
For format conversion support:
|
||||
```bash
|
||||
# macOS
|
||||
brew install ffmpeg
|
||||
|
||||
# Linux
|
||||
apt install ffmpeg
|
||||
```
|
||||
|
||||
#### 3. Install LLM CLI (Optional - for intelligent summaries)
|
||||
|
||||
**Claude CLI (recommended):**
|
||||
```bash
|
||||
# Follow: https://docs.anthropic.com/en/docs/claude-cli
|
||||
```
|
||||
|
||||
**GitHub Copilot CLI (alternative):**
|
||||
```bash
|
||||
gh extension install github/gh-copilot
|
||||
```
|
||||
|
||||
#### 4. Install Skill
|
||||
|
||||
**Global installation (auto-updates with git pull):**
|
||||
```bash
|
||||
cd /path/to/cli-ai-skills
|
||||
./scripts/install-skills.sh $(pwd)
|
||||
```
|
||||
|
||||
**Repository only:**
|
||||
```bash
|
||||
# Skill is already available if you cloned the repo
|
||||
```
|
||||
|
||||
## 🚀 Usage
|
||||
|
||||
### Basic Transcription
|
||||
|
||||
```bash
|
||||
copilot> transcribe audio to markdown: meeting.mp3
|
||||
```
|
||||
|
||||
**Output:**
|
||||
- `meeting.md` - Full Markdown report with metadata, transcription, minutes, summary
|
||||
|
||||
### With Subtitles
|
||||
|
||||
```bash
|
||||
copilot> convert audio file to text with subtitles: interview.wav
|
||||
```
|
||||
|
||||
**Generates:**
|
||||
- `interview.md` - Markdown report
|
||||
- `interview.srt` - Subtitle file
|
||||
|
||||
### Batch Processing
|
||||
|
||||
```bash
|
||||
copilot> transcreva estes áudios: recordings/*.mp3
|
||||
```
|
||||
|
||||
**Processes all MP3 files in the directory.**
|
||||
|
||||
### Trigger Phrases
|
||||
|
||||
Activate the skill with any of these phrases:
|
||||
|
||||
- "transcribe audio to markdown"
|
||||
- "transcreva este áudio"
|
||||
- "convert audio file to text"
|
||||
- "extract speech from audio"
|
||||
- "áudio para texto com metadados"
|
||||
|
||||
## 📋 Use Cases
|
||||
|
||||
### 1. Team Meetings
|
||||
Record standups, planning sessions, or retrospectives and automatically generate:
|
||||
- Participant list
|
||||
- Discussion topics with timestamps
|
||||
- Decisions made
|
||||
- Action items assigned
|
||||
|
||||
### 2. Client Calls
|
||||
Transcribe client conversations with:
|
||||
- Speaker identification
|
||||
- Key agreements documented
|
||||
- Follow-up tasks extracted
|
||||
|
||||
### 3. Interviews
|
||||
Convert interviews to text with:
|
||||
- Question/answer attribution
|
||||
- Subtitle generation for video
|
||||
- Searchable transcript
|
||||
|
||||
### 4. Lectures & Training
|
||||
Document educational content with:
|
||||
- Timestamped notes
|
||||
- Topic breakdown
|
||||
- Key concepts summary
|
||||
|
||||
### 5. Content Creation
|
||||
Analyze podcasts, videos, YouTube content:
|
||||
- Full transcription
|
||||
- Chapter markers (timestamps)
|
||||
- Summary for show notes
|
||||
|
||||
## 📊 Output Example
|
||||
|
||||
```markdown
|
||||
# Audio Transcription Report
|
||||
|
||||
## 📊 Metadata
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **File Name** | team-standup.mp3 |
|
||||
| **File Size** | 3.2 MB |
|
||||
| **Duration** | 00:12:47 |
|
||||
| **Language** | English (en) |
|
||||
| **Processed Date** | 2026-02-02 14:35:21 |
|
||||
| **Speakers Identified** | 5 |
|
||||
| **Transcription Engine** | Faster-Whisper (model: base) |
|
||||
|
||||
---
|
||||
|
||||
## 🎙️ Full Transcription
|
||||
|
||||
**[00:00:12 → 00:00:45]** *Speaker 1*
|
||||
Good morning everyone. Let's start with updates from the frontend team.
|
||||
|
||||
**[00:00:46 → 00:01:23]** *Speaker 2*
|
||||
We completed the dashboard redesign and deployed to staging yesterday.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Meeting Minutes
|
||||
|
||||
### Participants
|
||||
- Speaker 1 (Meeting Lead)
|
||||
- Speaker 2 (Frontend Developer)
|
||||
- Speaker 3 (Backend Developer)
|
||||
- Speaker 4 (Designer)
|
||||
- Speaker 5 (Product Manager)
|
||||
|
||||
### Topics Discussed
|
||||
1. **Dashboard Redesign** (00:00:46)
|
||||
- Completed and deployed to staging
|
||||
- Positive feedback from QA team
|
||||
|
||||
2. **API Performance Issues** (00:03:12)
|
||||
- Database query optimization needed
|
||||
- Target response time < 200ms
|
||||
|
||||
### Decisions Made
|
||||
- ✅ Approved dashboard for production deployment
|
||||
- ✅ Allocated 2 sprint points for API optimization
|
||||
|
||||
### Action Items
|
||||
- [ ] **Deploy dashboard to production** - Assigned to: Speaker 2 - Due: 2026-02-05
|
||||
- [ ] **Optimize database queries** - Assigned to: Speaker 3
|
||||
- [ ] **Schedule user testing session** - Assigned to: Speaker 5
|
||||
|
||||
---
|
||||
|
||||
## 📝 Executive Summary
|
||||
|
||||
The team standup covered progress on the dashboard redesign, which has been successfully completed and is ready for production deployment. The frontend team received positive feedback from QA and the design aligns with user requirements.
|
||||
|
||||
Backend performance concerns were raised regarding API response times. The team decided to prioritize query optimization in the current sprint, with a target of sub-200ms response times.
|
||||
|
||||
Next steps include production deployment of the dashboard by end of week and scheduling user testing sessions to validate the new design with real users.
|
||||
|
||||
### Key Points
|
||||
- 🔹 Dashboard redesign complete and staging-approved
|
||||
- 🔹 API performance optimization prioritized
|
||||
- 🔹 User testing scheduled for next week
|
||||
|
||||
### Next Steps
|
||||
1. Production deployment (Speaker 2)
|
||||
2. Database optimization (Speaker 3)
|
||||
3. User testing coordination (Speaker 5)
|
||||
```
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
No configuration needed! The skill automatically:
|
||||
- Detects Faster-Whisper or Whisper installation
|
||||
- Chooses the fastest available engine
|
||||
- Selects appropriate model based on file size
|
||||
- Auto-detects language
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### "No transcription tool found"
|
||||
**Solution:** Install Whisper:
|
||||
```bash
|
||||
pip install faster-whisper
|
||||
```
|
||||
|
||||
### "Unsupported format"
|
||||
**Solution:** Install ffmpeg:
|
||||
```bash
|
||||
brew install ffmpeg # macOS
|
||||
apt install ffmpeg # Linux
|
||||
```
|
||||
|
||||
### Slow processing
|
||||
**Solution:** Use a smaller Whisper model:
|
||||
```bash
|
||||
# Edit the skill to use "tiny" or "base" model instead of "medium"
|
||||
```
|
||||
|
||||
### Poor speaker identification
|
||||
**Solution:**
|
||||
- Ensure clear audio with minimal background noise
|
||||
- Use a better microphone for recordings
|
||||
- Try the "medium" or "large" Whisper model
|
||||
|
||||
## 🛠️ Advanced Usage
|
||||
|
||||
### Custom Model Selection
|
||||
|
||||
Edit `SKILL.md` Step 2 to change model:
|
||||
```python
|
||||
model = WhisperModel("small", device="cpu") # Change "base" to "small", "medium", etc.
|
||||
```
|
||||
|
||||
### Output Language Control
|
||||
|
||||
Force output in specific language:
|
||||
```bash
|
||||
# Edit Step 3 to set language explicitly
|
||||
```
|
||||
|
||||
### Batch Settings
|
||||
|
||||
Process specific file types only:
|
||||
```bash
|
||||
copilot> transcribe audio: recordings/*.wav # Only WAV files
|
||||
```
|
||||
|
||||
## 📚 FAQ
|
||||
|
||||
**Q: Does this work offline?**
|
||||
A: Yes! 100% local processing, no internet required after initial model download.
|
||||
|
||||
**Q: What's the difference between Whisper and Faster-Whisper?**
|
||||
A: Faster-Whisper is 4-5x faster with same quality. Always prefer it if available.
|
||||
|
||||
**Q: Can I transcribe YouTube videos?**
|
||||
A: Not directly. Use a YouTube downloader first, then transcribe the audio file. Or use the `youtube-summarizer` skill instead.
|
||||
|
||||
**Q: How accurate is speaker identification?**
|
||||
A: Accuracy depends on audio quality. Clear recordings with distinct voices work best. Currently uses simple estimation; future versions will use advanced diarization.
|
||||
|
||||
**Q: What languages are supported?**
|
||||
A: 99 languages including English, Portuguese, Spanish, French, German, Chinese, Japanese, Arabic, and more.
|
||||
|
||||
**Q: Can I edit the meeting minutes format?**
|
||||
A: Yes! Edit the Markdown template in SKILL.md Step 3.
|
||||
|
||||
## 🔗 Related Skills
|
||||
|
||||
- **youtube-summarizer** - Extract and summarize YouTube video transcripts
|
||||
- **prompt-engineer** - Optimize prompts for better AI summaries
|
||||
|
||||
## 📄 License
|
||||
|
||||
This skill is part of the cli-ai-skills repository.
|
||||
MIT License - See repository LICENSE file.
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Found a bug or have a feature request?
|
||||
Open an issue in the [cli-ai-skills repository](https://github.com/yourusername/cli-ai-skills).
|
||||
|
||||
---
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Author:** Eric Andrade
|
||||
**Created:** 2026-02-02
|
||||
@@ -1,558 +0,0 @@
|
||||
---
|
||||
name: audio-transcriber
|
||||
description: "Transform audio recordings into professional Markdown documentation with intelligent summaries using LLM integration"
|
||||
version: 1.2.0
|
||||
author: Eric Andrade
|
||||
created: 2025-02-01
|
||||
updated: 2026-02-04
|
||||
platforms: [github-copilot-cli, claude-code, codex]
|
||||
category: content
|
||||
tags: [audio, transcription, whisper, meeting-minutes, speech-to-text]
|
||||
risk: safe
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
This skill automates audio-to-text transcription with professional Markdown output, extracting rich technical metadata (speakers, timestamps, language, file size, duration) and generating structured meeting minutes and executive summaries. It uses Faster-Whisper or Whisper with zero configuration, working universally across projects without hardcoded paths or API keys.
|
||||
|
||||
Inspired by tools like Plaud, this skill transforms raw audio recordings into actionable documentation, making it ideal for meetings, interviews, lectures, and content analysis.
|
||||
|
||||
## When to Use
|
||||
|
||||
Invoke this skill when:
|
||||
|
||||
- User needs to transcribe audio/video files to text
|
||||
- User wants meeting minutes automatically generated from recordings
|
||||
- User requires speaker identification (diarization) in conversations
|
||||
- User needs subtitles/captions (SRT, VTT formats)
|
||||
- User wants executive summaries of long audio content
|
||||
- User asks variations of "transcribe this audio", "convert audio to text", "generate meeting notes from recording"
|
||||
- User has audio files in common formats (MP3, WAV, M4A, OGG, FLAC, WEBM)
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 0: Discovery (Auto-detect Transcription Tools)
|
||||
|
||||
**Objective:** Identify available transcription engines without user configuration.
|
||||
|
||||
**Actions:**
|
||||
|
||||
Run detection commands to find installed tools:
|
||||
|
||||
```bash
|
||||
# Check for Faster-Whisper (preferred - 4-5x faster)
|
||||
if python3 -c "import faster_whisper" 2>/dev/null; then
|
||||
TRANSCRIBER="faster-whisper"
|
||||
echo "✅ Faster-Whisper detected (optimized)"
|
||||
# Fallback to original Whisper
|
||||
elif python3 -c "import whisper" 2>/dev/null; then
|
||||
TRANSCRIBER="whisper"
|
||||
echo "✅ OpenAI Whisper detected"
|
||||
else
|
||||
TRANSCRIBER="none"
|
||||
echo "⚠️ No transcription tool found"
|
||||
fi
|
||||
|
||||
# Check for ffmpeg (audio format conversion)
|
||||
if command -v ffmpeg &>/dev/null; then
|
||||
echo "✅ ffmpeg available (format conversion enabled)"
|
||||
else
|
||||
echo "ℹ️ ffmpeg not found (limited format support)"
|
||||
fi
|
||||
```
|
||||
|
||||
**If no transcriber found:**
|
||||
|
||||
Offer automatic installation using the provided script:
|
||||
|
||||
```bash
|
||||
echo "⚠️ No transcription tool found"
|
||||
echo ""
|
||||
echo "🔧 Auto-install dependencies? (Recommended)"
|
||||
read -p "Run installation script? [Y/n]: " AUTO_INSTALL
|
||||
|
||||
if [[ ! "$AUTO_INSTALL" =~ ^[Nn] ]]; then
|
||||
# Get skill directory (works for both repo and symlinked installations)
|
||||
SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
# Run installation script
|
||||
if [[ -f "$SKILL_DIR/scripts/install-requirements.sh" ]]; then
|
||||
bash "$SKILL_DIR/scripts/install-requirements.sh"
|
||||
else
|
||||
echo "❌ Installation script not found"
|
||||
echo ""
|
||||
echo "📦 Manual installation:"
|
||||
echo " pip install faster-whisper # Recommended"
|
||||
echo " pip install openai-whisper # Alternative"
|
||||
echo " brew install ffmpeg # Optional (macOS)"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Verify installation succeeded
|
||||
if python3 -c "import faster_whisper" 2>/dev/null || python3 -c "import whisper" 2>/dev/null; then
|
||||
echo "✅ Installation successful! Proceeding with transcription..."
|
||||
else
|
||||
echo "❌ Installation failed. Please install manually."
|
||||
exit 1
|
||||
fi
|
||||
else
|
||||
echo ""
|
||||
echo "📦 Manual installation required:"
|
||||
echo ""
|
||||
echo "Recommended (fastest):"
|
||||
echo " pip install faster-whisper"
|
||||
echo ""
|
||||
echo "Alternative (original):"
|
||||
echo " pip install openai-whisper"
|
||||
echo ""
|
||||
echo "Optional (format conversion):"
|
||||
echo " brew install ffmpeg # macOS"
|
||||
echo " apt install ffmpeg # Linux"
|
||||
echo ""
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
This ensures users can install dependencies with one confirmation, or opt for manual installation if preferred.
|
||||
|
||||
**If transcriber found:**
|
||||
|
||||
Proceed to Step 0b (CLI Detection).
|
||||
|
||||
|
||||
### Step 1: Validate Audio File
|
||||
|
||||
**Objective:** Verify file exists, check format, and extract metadata.
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. **Accept file path or URL** from user:
|
||||
- Local file: `meeting.mp3`
|
||||
- URL: `https://example.com/audio.mp3` (download to temp directory)
|
||||
|
||||
2. **Verify file exists:**
|
||||
|
||||
```bash
|
||||
if [[ ! -f "$AUDIO_FILE" ]]; then
|
||||
echo "❌ File not found: $AUDIO_FILE"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
3. **Extract metadata** using ffprobe or file utilities:
|
||||
|
||||
```bash
|
||||
# Get file size
|
||||
FILE_SIZE=$(du -h "$AUDIO_FILE" | cut -f1)
|
||||
|
||||
# Get duration and format using ffprobe
|
||||
DURATION=$(ffprobe -v error -show_entries format=duration \
|
||||
-of default=noprint_wrappers=1:nokey=1 "$AUDIO_FILE" 2>/dev/null)
|
||||
FORMAT=$(ffprobe -v error -select_streams a:0 -show_entries \
|
||||
stream=codec_name -of default=noprint_wrappers=1:nokey=1 "$AUDIO_FILE" 2>/dev/null)
|
||||
|
||||
# Convert duration to HH:MM:SS
|
||||
DURATION_HMS=$(date -u -r "$DURATION" +%H:%M:%S 2>/dev/null || echo "Unknown")
|
||||
```
|
||||
|
||||
4. **Check file size** (warn if large for cloud APIs):
|
||||
|
||||
```bash
|
||||
SIZE_MB=$(du -m "$AUDIO_FILE" | cut -f1)
|
||||
if [[ $SIZE_MB -gt 25 ]]; then
|
||||
echo "⚠️ Large file ($FILE_SIZE) - processing may take several minutes"
|
||||
fi
|
||||
```
|
||||
|
||||
5. **Validate format** (supported: MP3, WAV, M4A, OGG, FLAC, WEBM):
|
||||
|
||||
```bash
|
||||
EXTENSION="${AUDIO_FILE##*.}"
|
||||
SUPPORTED_FORMATS=("mp3" "wav" "m4a" "ogg" "flac" "webm" "mp4")
|
||||
|
||||
if [[ ! " ${SUPPORTED_FORMATS[@]} " =~ " ${EXTENSION,,} " ]]; then
|
||||
echo "⚠️ Unsupported format: $EXTENSION"
|
||||
if command -v ffmpeg &>/dev/null; then
|
||||
echo "🔄 Converting to WAV..."
|
||||
ffmpeg -i "$AUDIO_FILE" -ar 16000 "${AUDIO_FILE%.*}.wav" -y
|
||||
AUDIO_FILE="${AUDIO_FILE%.*}.wav"
|
||||
else
|
||||
echo "❌ Install ffmpeg to convert formats: brew install ffmpeg"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
|
||||
### Step 3: Generate Markdown Output
|
||||
|
||||
**Objective:** Create structured Markdown with metadata, transcription, meeting minutes, and summary.
|
||||
|
||||
**Output Template:**
|
||||
|
||||
```markdown
|
||||
# Audio Transcription Report
|
||||
|
||||
## 📊 Metadata
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **File Name** | {filename} |
|
||||
| **File Size** | {file_size} |
|
||||
| **Duration** | {duration_hms} |
|
||||
| **Language** | {language} ({language_code}) |
|
||||
| **Processed Date** | {process_date} |
|
||||
| **Speakers Identified** | {num_speakers} |
|
||||
| **Transcription Engine** | {engine} (model: {model}) |
|
||||
|
||||
|
||||
## 📋 Meeting Minutes
|
||||
|
||||
### Participants
|
||||
- {speaker_1}
|
||||
- {speaker_2}
|
||||
- ...
|
||||
|
||||
### Topics Discussed
|
||||
1. **{topic_1}** ({timestamp})
|
||||
- {key_point_1}
|
||||
- {key_point_2}
|
||||
|
||||
2. **{topic_2}** ({timestamp})
|
||||
- {key_point_1}
|
||||
|
||||
### Decisions Made
|
||||
- ✅ {decision_1}
|
||||
- ✅ {decision_2}
|
||||
|
||||
### Action Items
|
||||
- [ ] **{action_1}** - Assigned to: {speaker} - Due: {date_if_mentioned}
|
||||
- [ ] **{action_2}** - Assigned to: {speaker}
|
||||
|
||||
|
||||
*Generated by audio-transcriber skill v1.0.0*
|
||||
*Transcription engine: {engine} | Processing time: {elapsed_time}s*
|
||||
```
|
||||
|
||||
**Implementation:**
|
||||
|
||||
Use Python or bash with AI model (Claude/GPT) for intelligent summarization:
|
||||
|
||||
```python
|
||||
def generate_meeting_minutes(segments):
|
||||
"""Extract topics, decisions, action items from transcription."""
|
||||
|
||||
# Group segments by topic (simple clustering by timestamps)
|
||||
topics = cluster_by_topic(segments)
|
||||
|
||||
# Identify action items (keywords: "should", "will", "need to", "action")
|
||||
action_items = extract_action_items(segments)
|
||||
|
||||
# Identify decisions (keywords: "decided", "agreed", "approved")
|
||||
decisions = extract_decisions(segments)
|
||||
|
||||
return {
|
||||
"topics": topics,
|
||||
"decisions": decisions,
|
||||
"action_items": action_items
|
||||
}
|
||||
|
||||
def generate_summary(segments, max_paragraphs=5):
|
||||
"""Create executive summary using AI (Claude/GPT via API or local model)."""
|
||||
|
||||
full_text = " ".join([s["text"] for s in segments])
|
||||
|
||||
# Use Chain of Density approach (from prompt-engineer frameworks)
|
||||
summary_prompt = f"""
|
||||
Summarize the following transcription in {max_paragraphs} concise paragraphs.
|
||||
Focus on key topics, decisions, and action items.
|
||||
|
||||
Transcription:
|
||||
{full_text}
|
||||
"""
|
||||
|
||||
# Call AI model (placeholder - user can integrate Claude API or use local model)
|
||||
summary = call_ai_model(summary_prompt)
|
||||
|
||||
return summary
|
||||
```
|
||||
|
||||
**Output file naming:**
|
||||
|
||||
```bash
|
||||
# v1.1.0: Use timestamp para evitar sobrescrever
|
||||
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
|
||||
TRANSCRIPT_FILE="transcript-${TIMESTAMP}.md"
|
||||
ATA_FILE="ata-${TIMESTAMP}.md"
|
||||
|
||||
echo "$TRANSCRIPT_CONTENT" > "$TRANSCRIPT_FILE"
|
||||
echo "✅ Transcript salvo: $TRANSCRIPT_FILE"
|
||||
|
||||
if [[ -n "$ATA_CONTENT" ]]; then
|
||||
echo "$ATA_CONTENT" > "$ATA_FILE"
|
||||
echo "✅ Ata salva: $ATA_FILE"
|
||||
fi
|
||||
```
|
||||
|
||||
|
||||
#### **SCENARIO A: User Provided Custom Prompt**
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. **Display user's prompt:**
|
||||
```
|
||||
📝 Prompt fornecido pelo usuário:
|
||||
┌──────────────────────────────────┐
|
||||
│ [User's prompt preview] │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
|
||||
2. **Automatically improve with prompt-engineer (if available):**
|
||||
```bash
|
||||
🔧 Melhorando prompt com prompt-engineer...
|
||||
[Invokes: gh copilot -p "melhore este prompt: {user_prompt}"]
|
||||
```
|
||||
|
||||
3. **Show both versions:**
|
||||
```
|
||||
✨ Versão melhorada:
|
||||
┌──────────────────────────────────┐
|
||||
│ Role: Você é um documentador... │
|
||||
│ Instructions: Transforme... │
|
||||
│ Steps: 1) ... 2) ... │
|
||||
│ End Goal: ... │
|
||||
└──────────────────────────────────┘
|
||||
|
||||
📝 Versão original:
|
||||
┌──────────────────────────────────┐
|
||||
│ [User's original prompt] │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
|
||||
4. **Ask which to use:**
|
||||
```bash
|
||||
💡 Usar versão melhorada? [s/n] (default: s):
|
||||
```
|
||||
|
||||
5. **Process with selected prompt:**
|
||||
- If "s": use improved
|
||||
- If "n": use original
|
||||
|
||||
|
||||
#### **LLM Processing (Both Scenarios)**
|
||||
|
||||
Once prompt is finalized:
|
||||
|
||||
```python
|
||||
from rich.progress import Progress, SpinnerColumn, TextColumn
|
||||
|
||||
def process_with_llm(transcript, prompt, cli_tool='claude'):
|
||||
full_prompt = f"{prompt}\n\n---\n\nTranscrição:\n\n{transcript}"
|
||||
|
||||
with Progress(
|
||||
SpinnerColumn(),
|
||||
TextColumn("[progress.description]{task.description}"),
|
||||
transient=True
|
||||
) as progress:
|
||||
progress.add_task(
|
||||
description=f"🤖 Processando com {cli_tool}...",
|
||||
total=None
|
||||
)
|
||||
|
||||
if cli_tool == 'claude':
|
||||
result = subprocess.run(
|
||||
['claude', '-'],
|
||||
input=full_prompt,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=300 # 5 minutes
|
||||
)
|
||||
elif cli_tool == 'gh-copilot':
|
||||
result = subprocess.run(
|
||||
['gh', 'copilot', 'suggest', '-t', 'shell', full_prompt],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=300
|
||||
)
|
||||
|
||||
if result.returncode == 0:
|
||||
return result.stdout.strip()
|
||||
else:
|
||||
return None
|
||||
```
|
||||
|
||||
**Progress output:**
|
||||
```
|
||||
🤖 Processando com claude... ⠋
|
||||
[After completion:]
|
||||
✅ Ata gerada com sucesso!
|
||||
```
|
||||
|
||||
|
||||
#### **Final Output**
|
||||
|
||||
**Success (both files):**
|
||||
```bash
|
||||
💾 Salvando arquivos...
|
||||
|
||||
✅ Arquivos criados:
|
||||
- transcript-20260203-023045.md (transcript puro)
|
||||
- ata-20260203-023045.md (processado com LLM)
|
||||
|
||||
🧹 Removidos arquivos temporários: metadata.json, transcription.json
|
||||
|
||||
✅ Concluído! Tempo total: 3m 45s
|
||||
```
|
||||
|
||||
**Transcript only (user declined LLM):**
|
||||
```bash
|
||||
💾 Salvando arquivos...
|
||||
|
||||
✅ Arquivo criado:
|
||||
- transcript-20260203-023045.md
|
||||
|
||||
ℹ️ Ata não gerada (processamento LLM recusado pelo usuário)
|
||||
|
||||
🧹 Removidos arquivos temporários: metadata.json, transcription.json
|
||||
|
||||
✅ Concluído!
|
||||
```
|
||||
|
||||
|
||||
### Step 5: Display Results Summary
|
||||
|
||||
**Objective:** Show completion status and next steps.
|
||||
|
||||
**Output:**
|
||||
|
||||
```bash
|
||||
echo ""
|
||||
echo "✅ Transcription Complete!"
|
||||
echo ""
|
||||
echo "📊 Results:"
|
||||
echo " File: $OUTPUT_FILE"
|
||||
echo " Language: $LANGUAGE"
|
||||
echo " Duration: $DURATION_HMS"
|
||||
echo " Speakers: $NUM_SPEAKERS"
|
||||
echo " Words: $WORD_COUNT"
|
||||
echo " Processing time: ${ELAPSED_TIME}s"
|
||||
echo ""
|
||||
echo "📝 Generated:"
|
||||
echo " - $OUTPUT_FILE (Markdown report)"
|
||||
[if alternative formats:]
|
||||
echo " - ${OUTPUT_FILE%.*}.srt (Subtitles)"
|
||||
echo " - ${OUTPUT_FILE%.*}.json (Structured data)"
|
||||
echo ""
|
||||
echo "🎯 Next steps:"
|
||||
echo " 1. Review meeting minutes and action items"
|
||||
echo " 2. Share report with participants"
|
||||
echo " 3. Track action items to completion"
|
||||
```
|
||||
|
||||
|
||||
## Example Usage
|
||||
|
||||
### **Example 1: Basic Transcription**
|
||||
|
||||
**User Input:**
|
||||
```bash
|
||||
copilot> transcribe audio to markdown: meeting-2026-02-02.mp3
|
||||
```
|
||||
|
||||
**Skill Output:**
|
||||
|
||||
```bash
|
||||
✅ Faster-Whisper detected (optimized)
|
||||
✅ ffmpeg available (format conversion enabled)
|
||||
|
||||
📂 File: meeting-2026-02-02.mp3
|
||||
📊 Size: 12.3 MB
|
||||
⏱️ Duration: 00:45:32
|
||||
|
||||
🎙️ Processing...
|
||||
[████████████████████] 100%
|
||||
|
||||
✅ Language detected: Portuguese (pt-BR)
|
||||
👥 Speakers identified: 4
|
||||
📝 Generating Markdown output...
|
||||
|
||||
✅ Transcription Complete!
|
||||
|
||||
📊 Results:
|
||||
File: meeting-2026-02-02.md
|
||||
Language: pt-BR
|
||||
Duration: 00:45:32
|
||||
Speakers: 4
|
||||
Words: 6,842
|
||||
Processing time: 127s
|
||||
|
||||
📝 Generated:
|
||||
- meeting-2026-02-02.md (Markdown report)
|
||||
|
||||
🎯 Next steps:
|
||||
1. Review meeting minutes and action items
|
||||
2. Share report with participants
|
||||
3. Track action items to completion
|
||||
```
|
||||
|
||||
|
||||
### **Example 3: Batch Processing**
|
||||
|
||||
**User Input:**
|
||||
```bash
|
||||
copilot> transcreva estes áudios: recordings/*.mp3
|
||||
```
|
||||
|
||||
**Skill Output:**
|
||||
|
||||
```bash
|
||||
📦 Batch mode: 5 files found
|
||||
1. team-standup.mp3
|
||||
2. client-call.mp3
|
||||
3. brainstorm-session.mp3
|
||||
4. product-demo.mp3
|
||||
5. retrospective.mp3
|
||||
|
||||
🎙️ Processing batch...
|
||||
|
||||
[1/5] team-standup.mp3 ✅ (2m 34s)
|
||||
[2/5] client-call.mp3 ✅ (15m 12s)
|
||||
[3/5] brainstorm-session.mp3 ✅ (8m 47s)
|
||||
[4/5] product-demo.mp3 ✅ (22m 03s)
|
||||
[5/5] retrospective.mp3 ✅ (11m 28s)
|
||||
|
||||
✅ Batch Complete!
|
||||
📝 Generated 5 Markdown reports
|
||||
⏱️ Total processing time: 6m 15s
|
||||
```
|
||||
|
||||
|
||||
### **Example 5: Large File Warning**
|
||||
|
||||
**User Input:**
|
||||
```bash
|
||||
copilot> transcribe audio to markdown: conference-keynote.mp3
|
||||
```
|
||||
|
||||
**Skill Output:**
|
||||
|
||||
```bash
|
||||
✅ Faster-Whisper detected (optimized)
|
||||
|
||||
📂 File: conference-keynote.mp3
|
||||
📊 Size: 87.2 MB
|
||||
⏱️ Duration: 02:15:47
|
||||
⚠️ Large file (87.2 MB) - processing may take several minutes
|
||||
|
||||
Continue? [Y/n]:
|
||||
```
|
||||
|
||||
**User:** `Y`
|
||||
|
||||
```bash
|
||||
🎙️ Processing... (this may take 10-15 minutes)
|
||||
[████░░░░░░░░░░░░░░░░] 20% - Estimated time remaining: 12m
|
||||
```
|
||||
|
||||
|
||||
This skill is **platform-agnostic** and works in any terminal context where GitHub Copilot CLI is available. It does not depend on specific project configurations or external APIs, following the zero-configuration philosophy.
|
||||
@@ -1,250 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
# Basic Audio Transcription Example
|
||||
# Demonstrates how to use the audio-transcriber skill manually
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# Configuration
|
||||
AUDIO_FILE="${1:-}"
|
||||
MODEL="${MODEL:-base}" # Options: tiny, base, small, medium, large
|
||||
OUTPUT_FORMAT="${OUTPUT_FORMAT:-markdown}" # Options: markdown, txt, srt, vtt, json
|
||||
|
||||
# Colors for output
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
# Helper functions
|
||||
error() {
|
||||
echo -e "${RED}❌ Error: $1${NC}" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
success() {
|
||||
echo -e "${GREEN}✅ $1${NC}"
|
||||
}
|
||||
|
||||
info() {
|
||||
echo -e "${BLUE}ℹ️ $1${NC}"
|
||||
}
|
||||
|
||||
warn() {
|
||||
echo -e "${YELLOW}⚠️ $1${NC}"
|
||||
}
|
||||
|
||||
# Check if audio file is provided
|
||||
if [[ -z "$AUDIO_FILE" ]]; then
|
||||
error "Usage: $0 <audio_file>"
|
||||
fi
|
||||
|
||||
# Verify file exists
|
||||
if [[ ! -f "$AUDIO_FILE" ]]; then
|
||||
error "File not found: $AUDIO_FILE"
|
||||
fi
|
||||
|
||||
# Step 0: Discovery - Check for transcription tools
|
||||
info "Step 0: Discovering transcription tools..."
|
||||
|
||||
TRANSCRIBER=""
|
||||
if python3 -c "import faster_whisper" 2>/dev/null; then
|
||||
TRANSCRIBER="faster-whisper"
|
||||
success "Faster-Whisper detected (optimized)"
|
||||
elif python3 -c "import whisper" 2>/dev/null; then
|
||||
TRANSCRIBER="whisper"
|
||||
success "OpenAI Whisper detected"
|
||||
else
|
||||
error "No transcription tool found. Install with: pip install faster-whisper"
|
||||
fi
|
||||
|
||||
# Check for ffmpeg
|
||||
if command -v ffmpeg &>/dev/null; then
|
||||
success "ffmpeg available (format conversion enabled)"
|
||||
else
|
||||
warn "ffmpeg not found (limited format support)"
|
||||
fi
|
||||
|
||||
# Step 1: Extract metadata
|
||||
info "Step 1: Extracting audio metadata..."
|
||||
|
||||
FILE_SIZE=$(du -h "$AUDIO_FILE" | cut -f1)
|
||||
info "File size: $FILE_SIZE"
|
||||
|
||||
# Get duration if ffprobe is available
|
||||
if command -v ffprobe &>/dev/null; then
|
||||
DURATION=$(ffprobe -v error -show_entries format=duration \
|
||||
-of default=noprint_wrappers=1:nokey=1 "$AUDIO_FILE" 2>/dev/null || echo "0")
|
||||
|
||||
# Convert to HH:MM:SS
|
||||
if command -v date &>/dev/null; then
|
||||
if [[ "$OSTYPE" == "darwin"* ]]; then
|
||||
# macOS
|
||||
DURATION_HMS=$(date -u -r "${DURATION%.*}" +%H:%M:%S 2>/dev/null || echo "Unknown")
|
||||
else
|
||||
# Linux
|
||||
DURATION_HMS=$(date -u -d @"${DURATION%.*}" +%H:%M:%S 2>/dev/null || echo "Unknown")
|
||||
fi
|
||||
else
|
||||
DURATION_HMS="Unknown"
|
||||
fi
|
||||
|
||||
info "Duration: $DURATION_HMS"
|
||||
else
|
||||
warn "ffprobe not found - cannot extract duration"
|
||||
DURATION="0"
|
||||
DURATION_HMS="Unknown"
|
||||
fi
|
||||
|
||||
# Check file size warning
|
||||
SIZE_MB=$(du -m "$AUDIO_FILE" | cut -f1)
|
||||
if [[ $SIZE_MB -gt 25 ]]; then
|
||||
warn "Large file ($FILE_SIZE) - processing may take several minutes"
|
||||
read -p "Continue? [Y/n]: " CONTINUE
|
||||
if [[ "$CONTINUE" =~ ^[Nn] ]]; then
|
||||
info "Transcription cancelled"
|
||||
exit 0
|
||||
fi
|
||||
fi
|
||||
|
||||
# Step 2: Transcribe using Python
|
||||
info "Step 2: Transcribing audio..."
|
||||
|
||||
OUTPUT_FILE="${AUDIO_FILE%.*}.md"
|
||||
TEMP_JSON="/tmp/transcription_$$.json"
|
||||
|
||||
python3 << EOF
|
||||
import sys
|
||||
import json
|
||||
from datetime import datetime
|
||||
|
||||
try:
|
||||
if "$TRANSCRIBER" == "faster-whisper":
|
||||
from faster_whisper import WhisperModel
|
||||
model = WhisperModel("$MODEL", device="cpu", compute_type="int8")
|
||||
segments, info = model.transcribe("$AUDIO_FILE", language=None, vad_filter=True)
|
||||
|
||||
data = {
|
||||
"language": info.language,
|
||||
"language_probability": round(info.language_probability, 2),
|
||||
"duration": info.duration,
|
||||
"segments": []
|
||||
}
|
||||
|
||||
for segment in segments:
|
||||
data["segments"].append({
|
||||
"start": round(segment.start, 2),
|
||||
"end": round(segment.end, 2),
|
||||
"text": segment.text.strip()
|
||||
})
|
||||
else:
|
||||
import whisper
|
||||
model = whisper.load_model("$MODEL")
|
||||
result = model.transcribe("$AUDIO_FILE")
|
||||
|
||||
data = {
|
||||
"language": result["language"],
|
||||
"duration": result["segments"][-1]["end"] if result["segments"] else 0,
|
||||
"segments": result["segments"]
|
||||
}
|
||||
|
||||
with open("$TEMP_JSON", "w") as f:
|
||||
json.dump(data, f)
|
||||
|
||||
print(f"✅ Language detected: {data['language']}")
|
||||
print(f"📝 Transcribed {len(data['segments'])} segments")
|
||||
|
||||
except Exception as e:
|
||||
print(f"❌ Error: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
EOF
|
||||
|
||||
# Check if transcription succeeded
|
||||
if [[ ! -f "$TEMP_JSON" ]]; then
|
||||
error "Transcription failed"
|
||||
fi
|
||||
|
||||
# Step 3: Generate Markdown output
|
||||
info "Step 3: Generating Markdown report..."
|
||||
|
||||
python3 << 'EOF'
|
||||
import json
|
||||
import sys
|
||||
from datetime import datetime
|
||||
|
||||
# Load transcription data
|
||||
with open("${TEMP_JSON}") as f:
|
||||
data = json.load(f)
|
||||
|
||||
# Prepare metadata
|
||||
filename = "${AUDIO_FILE}".split("/")[-1]
|
||||
file_size = "${FILE_SIZE}"
|
||||
duration_hms = "${DURATION_HMS}"
|
||||
language = data["language"]
|
||||
process_date = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
|
||||
num_segments = len(data["segments"])
|
||||
|
||||
# Generate Markdown
|
||||
markdown = f"""# Audio Transcription Report
|
||||
|
||||
## 📊 Metadata
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **File Name** | {filename} |
|
||||
| **File Size** | {file_size} |
|
||||
| **Duration** | {duration_hms} |
|
||||
| **Language** | {language.upper()} |
|
||||
| **Processed Date** | {process_date} |
|
||||
| **Segments** | {num_segments} |
|
||||
| **Transcription Engine** | ${TRANSCRIBER} (model: ${MODEL}) |
|
||||
|
||||
---
|
||||
|
||||
## 🎙️ Full Transcription
|
||||
|
||||
"""
|
||||
|
||||
# Add transcription with timestamps
|
||||
for seg in data["segments"]:
|
||||
start_time = f"{int(seg['start'] // 60):02d}:{int(seg['start'] % 60):02d}"
|
||||
end_time = f"{int(seg['end'] // 60):02d}:{int(seg['end'] % 60):02d}"
|
||||
markdown += f"**[{start_time} → {end_time}]** \n{seg['text']}\n\n"
|
||||
|
||||
markdown += """---
|
||||
|
||||
## 📝 Summary
|
||||
|
||||
*Automatic summary generation requires AI integration (Claude/GPT).*
|
||||
*For now, review the full transcription above.*
|
||||
|
||||
---
|
||||
|
||||
*Generated by audio-transcriber skill example script*
|
||||
*Transcription engine: ${TRANSCRIBER} | Model: ${MODEL}*
|
||||
"""
|
||||
|
||||
# Write to file
|
||||
with open("${OUTPUT_FILE}", "w") as f:
|
||||
f.write(markdown)
|
||||
|
||||
print(f"✅ Markdown report saved: ${OUTPUT_FILE}")
|
||||
EOF
|
||||
|
||||
# Clean up
|
||||
rm -f "$TEMP_JSON"
|
||||
|
||||
# Step 4: Display summary
|
||||
success "Transcription complete!"
|
||||
echo ""
|
||||
echo "📊 Results:"
|
||||
echo " Output file: $OUTPUT_FILE"
|
||||
echo " Transcription engine: $TRANSCRIBER"
|
||||
echo " Model: $MODEL"
|
||||
echo ""
|
||||
info "Next steps:"
|
||||
echo " 1. Review the transcription: cat $OUTPUT_FILE"
|
||||
echo " 2. Edit if needed: vim $OUTPUT_FILE"
|
||||
echo " 3. Share with team or archive"
|
||||
EOF
|
||||
@@ -1,352 +0,0 @@
|
||||
# Transcription Tools Comparison
|
||||
|
||||
Comprehensive comparison of audio transcription engines supported by the audio-transcriber skill.
|
||||
|
||||
## Overview
|
||||
|
||||
| Tool | Type | Speed | Quality | Cost | Privacy | Offline | Languages |
|
||||
|------|------|-------|---------|------|---------|---------|-----------|
|
||||
| **Faster-Whisper** | Open-source | ⚡⚡⚡⚡⚡ | ⭐⭐⭐⭐⭐ | Free | 100% | ✅ | 99 |
|
||||
| **Whisper** | Open-source | ⚡⚡⚡ | ⭐⭐⭐⭐⭐ | Free | 100% | ✅ | 99 |
|
||||
| Google Speech-to-Text | Commercial API | ⚡⚡⚡⚡ | ⭐⭐⭐⭐⭐ | $0.006/15s | Partial | ❌ | 125+ |
|
||||
| Azure Speech | Commercial API | ⚡⚡⚡⚡ | ⭐⭐⭐⭐ | $1/hour | Partial | ❌ | 100+ |
|
||||
| AssemblyAI | Commercial API | ⚡⚡⚡⚡ | ⭐⭐⭐⭐⭐ | $0.00025/s | Partial | ❌ | 99 |
|
||||
|
||||
---
|
||||
|
||||
## Faster-Whisper (Recommended)
|
||||
|
||||
### Pros
|
||||
✅ **4-5x faster** than original Whisper
|
||||
✅ **Same quality** as original Whisper
|
||||
✅ **Lower memory usage** (50-60% less RAM)
|
||||
✅ **Free and open-source**
|
||||
✅ **100% offline** (privacy guaranteed)
|
||||
✅ **Easy installation** (`pip install faster-whisper`)
|
||||
✅ **Drop-in replacement** for Whisper
|
||||
|
||||
### Cons
|
||||
❌ Requires Python 3.8+
|
||||
❌ Initial model download (~100MB-1.5GB)
|
||||
❌ GPU optional but speeds up significantly
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
pip install faster-whisper
|
||||
```
|
||||
|
||||
### Usage Example
|
||||
|
||||
```python
|
||||
from faster_whisper import WhisperModel
|
||||
|
||||
# Load model (auto-downloads on first run)
|
||||
model = WhisperModel("base", device="cpu", compute_type="int8")
|
||||
|
||||
# Transcribe
|
||||
segments, info = model.transcribe("audio.mp3", language="pt")
|
||||
|
||||
# Print results
|
||||
for segment in segments:
|
||||
print(f"[{segment.start:.2f}s -> {segment.end:.2f}s] {segment.text}")
|
||||
```
|
||||
|
||||
### Model Sizes
|
||||
|
||||
| Model | Size | RAM | Speed (CPU) | Quality |
|
||||
|-------|------|-----|-------------|---------|
|
||||
| `tiny` | 39 MB | ~1 GB | Very fast (~10x realtime) | Basic |
|
||||
| `base` | 74 MB | ~1 GB | Fast (~7x realtime) | Good |
|
||||
| `small` | 244 MB | ~2 GB | Moderate (~4x realtime) | Very good |
|
||||
| `medium` | 769 MB | ~5 GB | Slow (~2x realtime) | Excellent |
|
||||
| `large` | 1550 MB | ~10 GB | Very slow (~1x realtime) | Best |
|
||||
|
||||
**Recommendation:** `small` or `medium` for production use.
|
||||
|
||||
---
|
||||
|
||||
## Whisper (Original)
|
||||
|
||||
### Pros
|
||||
✅ **Official OpenAI model**
|
||||
✅ **Excellent quality**
|
||||
✅ **Free and open-source**
|
||||
✅ **100% offline**
|
||||
✅ **Well-documented**
|
||||
✅ **Large community**
|
||||
|
||||
### Cons
|
||||
❌ **Slower** than Faster-Whisper (4-5x)
|
||||
❌ **Higher memory usage**
|
||||
❌ Requires PyTorch (large dependency)
|
||||
❌ GPU highly recommended for larger models
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
pip install openai-whisper
|
||||
```
|
||||
|
||||
### Usage Example
|
||||
|
||||
```python
|
||||
import whisper
|
||||
|
||||
# Load model
|
||||
model = whisper.load_model("base")
|
||||
|
||||
# Transcribe
|
||||
result = model.transcribe("audio.mp3", language="pt")
|
||||
|
||||
# Print results
|
||||
print(result["text"])
|
||||
```
|
||||
|
||||
### When to Use Whisper vs. Faster-Whisper
|
||||
|
||||
**Use Faster-Whisper if:**
|
||||
- Speed is important
|
||||
- Limited RAM available
|
||||
- Processing many files
|
||||
|
||||
**Use Original Whisper if:**
|
||||
- Faster-Whisper installation issues
|
||||
- Need exact OpenAI implementation
|
||||
- Already have Whisper in project dependencies
|
||||
|
||||
---
|
||||
|
||||
## Google Cloud Speech-to-Text
|
||||
|
||||
### Pros
|
||||
✅ **Very accurate** (industry-leading)
|
||||
✅ **Fast processing** (cloud infrastructure)
|
||||
✅ **125+ languages**
|
||||
✅ **Word-level timestamps**
|
||||
✅ **Punctuation & capitalization**
|
||||
✅ **Speaker diarization** (premium)
|
||||
|
||||
### Cons
|
||||
❌ **Requires internet** (cloud-only)
|
||||
❌ **Costs money** (after free tier)
|
||||
❌ **Privacy concerns** (audio uploaded to Google)
|
||||
❌ Requires GCP account setup
|
||||
❌ Complex authentication
|
||||
|
||||
### Pricing
|
||||
|
||||
- **Free tier:** 60 minutes/month
|
||||
- **Standard:** $0.006 per 15 seconds ($1.44/hour)
|
||||
- **Premium:** $0.009 per 15 seconds (with diarization)
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
pip install google-cloud-speech
|
||||
```
|
||||
|
||||
### Setup
|
||||
|
||||
1. Create GCP project
|
||||
2. Enable Speech-to-Text API
|
||||
3. Create service account & download JSON key
|
||||
4. Set environment variable:
|
||||
```bash
|
||||
export GOOGLE_APPLICATION_CREDENTIALS="path/to/key.json"
|
||||
```
|
||||
|
||||
### Usage Example
|
||||
|
||||
```python
|
||||
from google.cloud import speech
|
||||
|
||||
client = speech.SpeechClient()
|
||||
|
||||
with open("audio.wav", "rb") as audio_file:
|
||||
content = audio_file.read()
|
||||
|
||||
audio = speech.RecognitionAudio(content=content)
|
||||
config = speech.RecognitionConfig(
|
||||
encoding=speech.RecognitionConfig.AudioEncoding.LINEAR16,
|
||||
sample_rate_hertz=16000,
|
||||
language_code="pt-BR",
|
||||
)
|
||||
|
||||
response = client.recognize(config=config, audio=audio)
|
||||
|
||||
for result in response.results:
|
||||
print(result.alternatives[0].transcript)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Azure Speech Services
|
||||
|
||||
### Pros
|
||||
✅ **High accuracy**
|
||||
✅ **100+ languages**
|
||||
✅ **Real-time transcription**
|
||||
✅ **Custom models** (train on your data)
|
||||
✅ **Good Microsoft ecosystem integration**
|
||||
|
||||
### Cons
|
||||
❌ **Requires internet**
|
||||
❌ **Costs money** (after free tier)
|
||||
❌ **Privacy concerns** (cloud processing)
|
||||
❌ Requires Azure account
|
||||
❌ Complex setup
|
||||
|
||||
### Pricing
|
||||
|
||||
- **Free tier:** 5 hours/month
|
||||
- **Standard:** $1.00 per audio hour
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
pip install azure-cognitiveservices-speech
|
||||
```
|
||||
|
||||
### Setup
|
||||
|
||||
1. Create Azure account
|
||||
2. Create Speech resource
|
||||
3. Get API key and region
|
||||
4. Set environment variables:
|
||||
```bash
|
||||
export AZURE_SPEECH_KEY="your-key"
|
||||
export AZURE_SPEECH_REGION="your-region"
|
||||
```
|
||||
|
||||
### Usage Example
|
||||
|
||||
```python
|
||||
import azure.cognitiveservices.speech as speechsdk
|
||||
|
||||
speech_config = speechsdk.SpeechConfig(
|
||||
subscription=os.environ.get('AZURE_SPEECH_KEY'),
|
||||
region=os.environ.get('AZURE_SPEECH_REGION')
|
||||
)
|
||||
|
||||
audio_config = speechsdk.audio.AudioConfig(filename="audio.wav")
|
||||
speech_recognizer = speechsdk.SpeechRecognizer(
|
||||
speech_config=speech_config,
|
||||
audio_config=audio_config
|
||||
)
|
||||
|
||||
result = speech_recognizer.recognize_once()
|
||||
print(result.text)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AssemblyAI
|
||||
|
||||
### Pros
|
||||
✅ **Modern, developer-friendly API**
|
||||
✅ **Excellent accuracy**
|
||||
✅ **Advanced features** (sentiment, topic detection, PII redaction)
|
||||
✅ **Speaker diarization** (included)
|
||||
✅ **Fast processing**
|
||||
✅ **Good documentation**
|
||||
|
||||
### Cons
|
||||
❌ **Requires internet**
|
||||
❌ **Costs money** (no free tier, only trial credits)
|
||||
❌ **Privacy concerns** (cloud processing)
|
||||
❌ Requires API key
|
||||
|
||||
### Pricing
|
||||
|
||||
- **Free trial:** $50 credits
|
||||
- **Standard:** $0.00025 per second (~$0.90/hour)
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
pip install assemblyai
|
||||
```
|
||||
|
||||
### Setup
|
||||
|
||||
1. Sign up at assemblyai.com
|
||||
2. Get API key
|
||||
3. Set environment variable:
|
||||
```bash
|
||||
export ASSEMBLYAI_API_KEY="your-key"
|
||||
```
|
||||
|
||||
### Usage Example
|
||||
|
||||
```python
|
||||
import assemblyai as aai
|
||||
|
||||
aai.settings.api_key = os.environ["ASSEMBLYAI_API_KEY"]
|
||||
|
||||
transcriber = aai.Transcriber()
|
||||
transcript = transcriber.transcribe("audio.mp3")
|
||||
|
||||
print(transcript.text)
|
||||
|
||||
# Speaker diarization
|
||||
for utterance in transcript.utterances:
|
||||
print(f"Speaker {utterance.speaker}: {utterance.text}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recommendation Matrix
|
||||
|
||||
### Use Faster-Whisper if:
|
||||
- ✅ Privacy is critical (local processing)
|
||||
- ✅ Want zero cost (free forever)
|
||||
- ✅ Need offline capability
|
||||
- ✅ Processing many files (speed matters)
|
||||
- ✅ Limited budget
|
||||
|
||||
### Use Google Speech-to-Text if:
|
||||
- ✅ Need absolute best accuracy
|
||||
- ✅ Have budget for cloud services
|
||||
- ✅ Want advanced features (punctuation, diarization)
|
||||
- ✅ Already using GCP ecosystem
|
||||
|
||||
### Use Azure Speech if:
|
||||
- ✅ In Microsoft ecosystem
|
||||
- ✅ Need custom model training
|
||||
- ✅ Want real-time transcription
|
||||
- ✅ Have Azure credits
|
||||
|
||||
### Use AssemblyAI if:
|
||||
- ✅ Need advanced features (sentiment, topics)
|
||||
- ✅ Want easiest API experience
|
||||
- ✅ Need automatic PII redaction
|
||||
- ✅ Value developer experience
|
||||
|
||||
---
|
||||
|
||||
## Performance Benchmarks
|
||||
|
||||
**Test:** 1-hour podcast (MP3, 44.1kHz, stereo)
|
||||
|
||||
| Tool | Processing Time | Accuracy | Cost |
|
||||
|------|----------------|----------|------|
|
||||
| Faster-Whisper (small) | 8 min | 94% | $0 |
|
||||
| Whisper (small) | 32 min | 94% | $0 |
|
||||
| Google Speech | 2 min | 96% | $1.44 |
|
||||
| Azure Speech | 3 min | 95% | $1.00 |
|
||||
| AssemblyAI | 4 min | 96% | $0.90 |
|
||||
|
||||
*Benchmarks run on MacBook Pro M1, 16GB RAM*
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
**For the audio-transcriber skill:**
|
||||
|
||||
1. **Primary:** Faster-Whisper (best balance of speed, quality, privacy, cost)
|
||||
2. **Fallback:** Whisper (if Faster-Whisper unavailable)
|
||||
3. **Optional:** Cloud APIs (user choice for premium features)
|
||||
|
||||
This ensures the skill works out-of-the-box for most users while allowing advanced users to integrate commercial services if needed.
|
||||
@@ -1,190 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
# Audio Transcriber - Requirements Installation Script
|
||||
# Automatically installs and validates dependencies
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# Colors
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
RED='\033[0;31m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m'
|
||||
|
||||
echo -e "${BLUE}🔧 Audio Transcriber - Dependency Installation${NC}"
|
||||
echo ""
|
||||
|
||||
# Check Python
|
||||
if ! command -v python3 &>/dev/null; then
|
||||
echo -e "${RED}❌ Python 3 not found. Please install Python 3.8+${NC}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
PYTHON_VERSION=$(python3 --version | cut -d' ' -f2 | cut -d'.' -f1,2)
|
||||
echo -e "${GREEN}✅ Python ${PYTHON_VERSION} detected${NC}"
|
||||
|
||||
# Check pip
|
||||
if ! python3 -m pip --version &>/dev/null; then
|
||||
echo -e "${RED}❌ pip not found. Please install pip${NC}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo -e "${GREEN}✅ pip available${NC}"
|
||||
echo ""
|
||||
|
||||
# Install system dependencies (macOS only)
|
||||
if [[ "$OSTYPE" == "darwin"* ]]; then
|
||||
echo -e "${BLUE}📦 Checking system dependencies (macOS)...${NC}"
|
||||
|
||||
# Check for Homebrew
|
||||
if command -v brew &>/dev/null; then
|
||||
# Install pkg-config and ffmpeg if not present
|
||||
NEED_INSTALL=""
|
||||
|
||||
if ! brew list pkg-config &>/dev/null 2>&1; then
|
||||
NEED_INSTALL="$NEED_INSTALL pkg-config"
|
||||
fi
|
||||
|
||||
if ! brew list ffmpeg &>/dev/null 2>&1; then
|
||||
NEED_INSTALL="$NEED_INSTALL ffmpeg"
|
||||
fi
|
||||
|
||||
if [[ -n "$NEED_INSTALL" ]]; then
|
||||
echo -e "${BLUE}Installing:$NEED_INSTALL${NC}"
|
||||
brew install $NEED_INSTALL --quiet
|
||||
echo -e "${GREEN}✅ System dependencies installed${NC}"
|
||||
else
|
||||
echo -e "${GREEN}✅ System dependencies already installed${NC}"
|
||||
fi
|
||||
else
|
||||
echo -e "${YELLOW}⚠️ Homebrew not found. Install manually if needed:${NC}"
|
||||
echo " /bin/bash -c \"\$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\""
|
||||
fi
|
||||
fi
|
||||
|
||||
echo ""
|
||||
|
||||
# Install faster-whisper (recommended)
|
||||
echo -e "${BLUE}📦 Installing Faster-Whisper...${NC}"
|
||||
|
||||
# Try different installation methods based on Python environment
|
||||
if python3 -m pip install faster-whisper --quiet 2>/dev/null; then
|
||||
echo -e "${GREEN}✅ Faster-Whisper installed successfully${NC}"
|
||||
elif python3 -m pip install --user --break-system-packages faster-whisper --quiet 2>/dev/null; then
|
||||
echo -e "${GREEN}✅ Faster-Whisper installed successfully (user mode)${NC}"
|
||||
else
|
||||
echo -e "${YELLOW}⚠️ Faster-Whisper installation failed, trying Whisper...${NC}"
|
||||
|
||||
if python3 -m pip install openai-whisper --quiet 2>/dev/null; then
|
||||
echo -e "${GREEN}✅ Whisper installed successfully${NC}"
|
||||
elif python3 -m pip install --user --break-system-packages openai-whisper --quiet 2>/dev/null; then
|
||||
echo -e "${GREEN}✅ Whisper installed successfully (user mode)${NC}"
|
||||
else
|
||||
echo -e "${RED}❌ Failed to install transcription engine${NC}"
|
||||
echo ""
|
||||
echo -e "${YELLOW}Manual installation options:${NC}"
|
||||
echo " 1. Use --break-system-packages (macOS/Homebrew Python):"
|
||||
echo " python3 -m pip install --user --break-system-packages openai-whisper"
|
||||
echo ""
|
||||
echo " 2. Use virtual environment (recommended):"
|
||||
echo " python3 -m venv ~/whisper-env"
|
||||
echo " source ~/whisper-env/bin/activate"
|
||||
echo " pip install faster-whisper"
|
||||
echo ""
|
||||
echo " 3. Use pipx (isolated):"
|
||||
echo " brew install pipx"
|
||||
echo " pipx install openai-whisper"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
# Install UI/progress libraries (tqdm, rich)
|
||||
echo ""
|
||||
echo -e "${BLUE}📦 Installing UI libraries (tqdm, rich)...${NC}"
|
||||
|
||||
if python3 -m pip install tqdm rich --quiet 2>/dev/null; then
|
||||
echo -e "${GREEN}✅ tqdm and rich installed successfully${NC}"
|
||||
elif python3 -m pip install --user --break-system-packages tqdm rich --quiet 2>/dev/null; then
|
||||
echo -e "${GREEN}✅ tqdm and rich installed successfully (user mode)${NC}"
|
||||
else
|
||||
echo -e "${YELLOW}⚠️ Optional UI libraries not installed (skill will still work)${NC}"
|
||||
fi
|
||||
|
||||
# Check ffmpeg (optional but recommended)
|
||||
echo ""
|
||||
if command -v ffmpeg &>/dev/null; then
|
||||
echo -e "${GREEN}✅ ffmpeg already installed${NC}"
|
||||
else
|
||||
echo -e "${YELLOW}⚠️ ffmpeg not found (should have been installed earlier)${NC}"
|
||||
if [[ "$OSTYPE" == "darwin"* ]] && command -v brew &>/dev/null; then
|
||||
echo -e "${BLUE}Installing ffmpeg via Homebrew...${NC}"
|
||||
brew install ffmpeg --quiet && echo -e "${GREEN}✅ ffmpeg installed${NC}"
|
||||
else
|
||||
echo -e "${BLUE}ℹ️ ffmpeg is optional but recommended for format conversion${NC}"
|
||||
echo ""
|
||||
echo "Install ffmpeg:"
|
||||
if [[ "$OSTYPE" == "darwin"* ]]; then
|
||||
echo " brew install ffmpeg"
|
||||
elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
|
||||
echo " sudo apt install ffmpeg # Debian/Ubuntu"
|
||||
echo " sudo yum install ffmpeg # CentOS/RHEL"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# Verify installation
|
||||
echo ""
|
||||
echo -e "${BLUE}🔍 Verifying installation...${NC}"
|
||||
|
||||
if python3 -c "import faster_whisper" 2>/dev/null; then
|
||||
echo -e "${GREEN}✅ Faster-Whisper verified${NC}"
|
||||
TRANSCRIBER="Faster-Whisper"
|
||||
elif python3 -c "import whisper" 2>/dev/null; then
|
||||
echo -e "${GREEN}✅ Whisper verified${NC}"
|
||||
TRANSCRIBER="Whisper"
|
||||
else
|
||||
echo -e "${RED}❌ No transcription engine found after installation${NC}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Download initial model (optional)
|
||||
read -p "Download Whisper 'base' model now? (recommended, ~74MB) [Y/n]: " DOWNLOAD_MODEL
|
||||
|
||||
if [[ ! "$DOWNLOAD_MODEL" =~ ^[Nn] ]]; then
|
||||
echo ""
|
||||
echo -e "${BLUE}📥 Downloading 'base' model...${NC}"
|
||||
|
||||
python3 << 'EOF'
|
||||
try:
|
||||
import faster_whisper
|
||||
model = faster_whisper.WhisperModel("base", device="cpu", compute_type="int8")
|
||||
print("✅ Model downloaded successfully")
|
||||
except:
|
||||
try:
|
||||
import whisper
|
||||
model = whisper.load_model("base")
|
||||
print("✅ Model downloaded successfully")
|
||||
except Exception as e:
|
||||
print(f"❌ Model download failed: {e}")
|
||||
EOF
|
||||
fi
|
||||
|
||||
# Success summary
|
||||
echo ""
|
||||
echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
|
||||
echo -e "${GREEN}✅ Installation Complete!${NC}"
|
||||
echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
|
||||
echo ""
|
||||
echo "📊 Installed components:"
|
||||
echo " • Transcription engine: $TRANSCRIBER"
|
||||
if command -v ffmpeg &>/dev/null; then
|
||||
echo " • Format conversion: ffmpeg (available)"
|
||||
else
|
||||
echo " • Format conversion: ffmpeg (not installed)"
|
||||
fi
|
||||
echo ""
|
||||
echo "🚀 Ready to use! Try:"
|
||||
echo " copilot> transcribe audio to markdown: myfile.mp3"
|
||||
echo " claude> transcreva este áudio: myfile.mp3"
|
||||
echo ""
|
||||
@@ -1,486 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Audio Transcriber v1.1.0
|
||||
Transcreve áudio para texto e gera atas/resumos usando LLM.
|
||||
"""
|
||||
|
||||
import os
|
||||
import sys
|
||||
import json
|
||||
import subprocess
|
||||
import shutil
|
||||
from datetime import datetime
|
||||
from pathlib import Path
|
||||
|
||||
# Rich for beautiful terminal output
|
||||
try:
|
||||
from rich.console import Console
|
||||
from rich.prompt import Prompt
|
||||
from rich.panel import Panel
|
||||
from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn
|
||||
from rich import print as rprint
|
||||
RICH_AVAILABLE = True
|
||||
except ImportError:
|
||||
RICH_AVAILABLE = False
|
||||
print("⚠️ Installing rich for better UI...")
|
||||
subprocess.run([sys.executable, "-m", "pip", "install", "--user", "rich"], check=False)
|
||||
from rich.console import Console
|
||||
from rich.prompt import Prompt
|
||||
from rich.panel import Panel
|
||||
from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn
|
||||
from rich import print as rprint
|
||||
|
||||
# tqdm for progress bars
|
||||
try:
|
||||
from tqdm import tqdm
|
||||
except ImportError:
|
||||
print("⚠️ Installing tqdm for progress bars...")
|
||||
subprocess.run([sys.executable, "-m", "pip", "install", "--user", "tqdm"], check=False)
|
||||
from tqdm import tqdm
|
||||
|
||||
# Whisper engines
|
||||
try:
|
||||
from faster_whisper import WhisperModel
|
||||
TRANSCRIBER = "faster-whisper"
|
||||
except ImportError:
|
||||
try:
|
||||
import whisper
|
||||
TRANSCRIBER = "whisper"
|
||||
except ImportError:
|
||||
print("❌ Nenhum engine de transcrição encontrado!")
|
||||
print(" Instale: pip install faster-whisper")
|
||||
sys.exit(1)
|
||||
|
||||
console = Console()
|
||||
|
||||
# Template padrão RISEN para fallback
|
||||
DEFAULT_MEETING_PROMPT = """
|
||||
Role: Você é um transcritor profissional especializado em documentação.
|
||||
|
||||
Instructions: Transforme a transcrição fornecida em um documento estruturado e profissional.
|
||||
|
||||
Steps:
|
||||
1. Identifique o tipo de conteúdo (reunião, palestra, entrevista, etc.)
|
||||
2. Extraia os principais tópicos e pontos-chave
|
||||
3. Identifique participantes/speakers (se aplicável)
|
||||
4. Extraia decisões tomadas e ações definidas (se reunião)
|
||||
5. Organize em formato apropriado com seções claras
|
||||
6. Use Markdown para formatação profissional
|
||||
|
||||
End Goal: Documento final bem estruturado, legível e pronto para distribuição.
|
||||
|
||||
Narrowing:
|
||||
- Mantenha objetividade e clareza
|
||||
- Preserve contexto importante
|
||||
- Use formatação Markdown adequada
|
||||
- Inclua timestamps relevantes quando aplicável
|
||||
"""
|
||||
|
||||
|
||||
def detect_cli_tool():
|
||||
"""Detecta qual CLI de LLM está disponível (claude > gh copilot)."""
|
||||
if shutil.which('claude'):
|
||||
return 'claude'
|
||||
elif shutil.which('gh'):
|
||||
result = subprocess.run(['gh', 'copilot', '--version'],
|
||||
capture_output=True, text=True)
|
||||
if result.returncode == 0:
|
||||
return 'gh-copilot'
|
||||
return None
|
||||
|
||||
|
||||
def invoke_prompt_engineer(raw_prompt, timeout=90):
|
||||
"""
|
||||
Invoca prompt-engineer skill via CLI para melhorar/gerar prompts.
|
||||
|
||||
Args:
|
||||
raw_prompt: Prompt a ser melhorado ou meta-prompt
|
||||
timeout: Timeout em segundos
|
||||
|
||||
Returns:
|
||||
str: Prompt melhorado ou DEFAULT_MEETING_PROMPT se falhar
|
||||
"""
|
||||
try:
|
||||
# Tentar via gh copilot
|
||||
console.print("[dim] Invocando prompt-engineer...[/dim]")
|
||||
|
||||
result = subprocess.run(
|
||||
['gh', 'copilot', 'suggest', '-t', 'shell', raw_prompt],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=timeout
|
||||
)
|
||||
|
||||
if result.returncode == 0 and result.stdout.strip():
|
||||
return result.stdout.strip()
|
||||
else:
|
||||
console.print("[yellow]⚠️ prompt-engineer não respondeu, usando template padrão[/yellow]")
|
||||
return DEFAULT_MEETING_PROMPT
|
||||
|
||||
except subprocess.TimeoutExpired:
|
||||
console.print(f"[red]⚠️ Timeout após {timeout}s, usando template padrão[/red]")
|
||||
return DEFAULT_MEETING_PROMPT
|
||||
except Exception as e:
|
||||
console.print(f"[red]⚠️ Erro ao invocar prompt-engineer: {e}[/red]")
|
||||
return DEFAULT_MEETING_PROMPT
|
||||
|
||||
|
||||
def handle_prompt_workflow(user_prompt, transcript):
|
||||
"""
|
||||
Gerencia fluxo completo de prompts com prompt-engineer.
|
||||
|
||||
Cenário A: Usuário forneceu prompt → Melhorar AUTOMATICAMENTE → Confirmar
|
||||
Cenário B: Sem prompt → Sugerir tipo → Confirmar → Gerar → Confirmar
|
||||
|
||||
Returns:
|
||||
str: Prompt final a usar, ou None se usuário recusou processamento
|
||||
"""
|
||||
prompt_engineer_available = os.path.exists(
|
||||
os.path.expanduser('~/.copilot/skills/prompt-engineer/SKILL.md')
|
||||
)
|
||||
|
||||
# ========== CENÁRIO A: USUÁRIO FORNECEU PROMPT ==========
|
||||
if user_prompt:
|
||||
console.print("\n[cyan]📝 Prompt fornecido pelo usuário[/cyan]")
|
||||
console.print(Panel(user_prompt[:300] + ("..." if len(user_prompt) > 300 else ""),
|
||||
title="Prompt original", border_style="dim"))
|
||||
|
||||
if prompt_engineer_available:
|
||||
# Melhora AUTOMATICAMENTE (sem perguntar)
|
||||
console.print("\n[cyan]🔧 Melhorando prompt com prompt-engineer...[/cyan]")
|
||||
|
||||
improved_prompt = invoke_prompt_engineer(
|
||||
f"melhore este prompt:\n\n{user_prompt}"
|
||||
)
|
||||
|
||||
# Mostrar AMBAS versões
|
||||
console.print("\n[green]✨ Versão melhorada:[/green]")
|
||||
console.print(Panel(improved_prompt[:500] + ("..." if len(improved_prompt) > 500 else ""),
|
||||
title="Prompt otimizado", border_style="green"))
|
||||
|
||||
console.print("\n[dim]📝 Versão original:[/dim]")
|
||||
console.print(Panel(user_prompt[:300] + ("..." if len(user_prompt) > 300 else ""),
|
||||
title="Seu prompt", border_style="dim"))
|
||||
|
||||
# Pergunta qual usar
|
||||
confirm = Prompt.ask(
|
||||
"\n💡 Usar versão melhorada?",
|
||||
choices=["s", "n"],
|
||||
default="s"
|
||||
)
|
||||
|
||||
return improved_prompt if confirm == "s" else user_prompt
|
||||
else:
|
||||
# prompt-engineer não disponível
|
||||
console.print("[yellow]⚠️ prompt-engineer skill não disponível[/yellow]")
|
||||
console.print("[dim]✅ Usando seu prompt original[/dim]")
|
||||
return user_prompt
|
||||
|
||||
# ========== CENÁRIO B: SEM PROMPT - AUTO-GERAÇÃO ==========
|
||||
else:
|
||||
console.print("\n[yellow]⚠️ Nenhum prompt fornecido.[/yellow]")
|
||||
|
||||
if not prompt_engineer_available:
|
||||
console.print("[yellow]⚠️ prompt-engineer skill não encontrado[/yellow]")
|
||||
console.print("[dim]Usando template padrão...[/dim]")
|
||||
return DEFAULT_MEETING_PROMPT
|
||||
|
||||
# PASSO 1: Perguntar se quer auto-gerar
|
||||
console.print("Posso analisar o transcript e sugerir um formato de resumo/ata?")
|
||||
|
||||
generate = Prompt.ask(
|
||||
"\n💡 Gerar prompt automaticamente?",
|
||||
choices=["s", "n"],
|
||||
default="s"
|
||||
)
|
||||
|
||||
if generate == "n":
|
||||
console.print("[dim]✅ Ok, gerando apenas transcript.md (sem ata)[/dim]")
|
||||
return None # Sinaliza: não processar com LLM
|
||||
|
||||
# PASSO 2: Analisar transcript e SUGERIR tipo
|
||||
console.print("\n[cyan]🔍 Analisando transcript...[/cyan]")
|
||||
|
||||
suggestion_meta_prompt = f"""
|
||||
Analise este transcript ({len(transcript)} caracteres) e sugira:
|
||||
|
||||
1. Tipo de conteúdo (reunião, palestra, entrevista, etc.)
|
||||
2. Formato de saída recomendado (ata formal, resumo executivo, notas estruturadas)
|
||||
3. Framework ideal (RISEN, RODES, STAR, etc.)
|
||||
|
||||
Primeiras 1000 palavras do transcript:
|
||||
{transcript[:4000]}
|
||||
|
||||
Responda em 2-3 linhas concisas.
|
||||
"""
|
||||
|
||||
suggested_type = invoke_prompt_engineer(suggestion_meta_prompt)
|
||||
|
||||
# PASSO 3: Mostrar sugestão e CONFIRMAR
|
||||
console.print("\n[green]💡 Sugestão de formato:[/green]")
|
||||
console.print(Panel(suggested_type, title="Análise do transcript", border_style="green"))
|
||||
|
||||
confirm_type = Prompt.ask(
|
||||
"\n💡 Usar este formato?",
|
||||
choices=["s", "n"],
|
||||
default="s"
|
||||
)
|
||||
|
||||
if confirm_type == "n":
|
||||
console.print("[dim]Usando template padrão...[/dim]")
|
||||
return DEFAULT_MEETING_PROMPT
|
||||
|
||||
# PASSO 4: Gerar prompt completo baseado na sugestão
|
||||
console.print("\n[cyan]✨ Gerando prompt estruturado...[/cyan]")
|
||||
|
||||
final_meta_prompt = f"""
|
||||
Crie um prompt completo e estruturado (usando framework apropriado) para:
|
||||
|
||||
{suggested_type}
|
||||
|
||||
O prompt deve instruir uma IA a transformar o transcript em um documento
|
||||
profissional e bem formatado em Markdown.
|
||||
"""
|
||||
|
||||
generated_prompt = invoke_prompt_engineer(final_meta_prompt)
|
||||
|
||||
# PASSO 5: Mostrar prompt gerado e CONFIRMAR
|
||||
console.print("\n[green]✅ Prompt gerado:[/green]")
|
||||
console.print(Panel(generated_prompt[:600] + ("..." if len(generated_prompt) > 600 else ""),
|
||||
title="Preview", border_style="green"))
|
||||
|
||||
confirm_final = Prompt.ask(
|
||||
"\n💡 Usar este prompt?",
|
||||
choices=["s", "n"],
|
||||
default="s"
|
||||
)
|
||||
|
||||
if confirm_final == "s":
|
||||
return generated_prompt
|
||||
else:
|
||||
console.print("[dim]Usando template padrão...[/dim]")
|
||||
return DEFAULT_MEETING_PROMPT
|
||||
|
||||
|
||||
def process_with_llm(transcript, prompt, cli_tool='claude', timeout=300):
|
||||
"""
|
||||
Processa transcript com LLM usando prompt fornecido.
|
||||
|
||||
Args:
|
||||
transcript: Texto transcrito
|
||||
prompt: Prompt instruindo como processar
|
||||
cli_tool: 'claude' ou 'gh-copilot'
|
||||
timeout: Timeout em segundos
|
||||
|
||||
Returns:
|
||||
str: Ata/resumo processado
|
||||
"""
|
||||
full_prompt = f"{prompt}\n\n---\n\nTranscrição:\n\n{transcript}"
|
||||
|
||||
try:
|
||||
with Progress(
|
||||
SpinnerColumn(),
|
||||
TextColumn("[progress.description]{task.description}"),
|
||||
transient=True
|
||||
) as progress:
|
||||
progress.add_task(description=f"🤖 Processando com {cli_tool}...", total=None)
|
||||
|
||||
if cli_tool == 'claude':
|
||||
result = subprocess.run(
|
||||
['claude', '-'],
|
||||
input=full_prompt,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=timeout
|
||||
)
|
||||
elif cli_tool == 'gh-copilot':
|
||||
result = subprocess.run(
|
||||
['gh', 'copilot', 'suggest', '-t', 'shell', full_prompt],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=timeout
|
||||
)
|
||||
else:
|
||||
raise ValueError(f"CLI tool desconhecido: {cli_tool}")
|
||||
|
||||
if result.returncode == 0:
|
||||
return result.stdout.strip()
|
||||
else:
|
||||
console.print(f"[red]❌ Erro ao processar com {cli_tool}[/red]")
|
||||
console.print(f"[dim]{result.stderr[:200]}[/dim]")
|
||||
return None
|
||||
|
||||
except subprocess.TimeoutExpired:
|
||||
console.print(f"[red]❌ Timeout após {timeout}s[/red]")
|
||||
return None
|
||||
except Exception as e:
|
||||
console.print(f"[red]❌ Erro: {e}[/red]")
|
||||
return None
|
||||
|
||||
|
||||
def transcribe_audio(audio_file, model="base"):
|
||||
"""
|
||||
Transcreve áudio usando Whisper com barra de progresso.
|
||||
|
||||
Returns:
|
||||
dict: {language, duration, segments: [{start, end, text}]}
|
||||
"""
|
||||
console.print(f"\n[cyan]🎙️ Transcrevendo áudio com {TRANSCRIBER}...[/cyan]")
|
||||
|
||||
try:
|
||||
if TRANSCRIBER == "faster-whisper":
|
||||
model_obj = WhisperModel(model, device="cpu", compute_type="int8")
|
||||
segments, info = model_obj.transcribe(
|
||||
audio_file,
|
||||
language=None,
|
||||
vad_filter=True,
|
||||
word_timestamps=True
|
||||
)
|
||||
|
||||
data = {
|
||||
"language": info.language,
|
||||
"language_probability": round(info.language_probability, 2),
|
||||
"duration": info.duration,
|
||||
"segments": []
|
||||
}
|
||||
|
||||
# Converter generator em lista com progresso
|
||||
console.print("[dim]Processando segmentos...[/dim]")
|
||||
for segment in tqdm(segments, desc="Segmentos", unit="seg"):
|
||||
data["segments"].append({
|
||||
"start": round(segment.start, 2),
|
||||
"end": round(segment.end, 2),
|
||||
"text": segment.text.strip()
|
||||
})
|
||||
|
||||
else: # whisper original
|
||||
import whisper
|
||||
model_obj = whisper.load_model(model)
|
||||
result = model_obj.transcribe(audio_file, word_timestamps=True)
|
||||
|
||||
data = {
|
||||
"language": result["language"],
|
||||
"duration": result["segments"][-1]["end"] if result["segments"] else 0,
|
||||
"segments": result["segments"]
|
||||
}
|
||||
|
||||
console.print(f"[green]✅ Transcrição completa! Idioma: {data['language'].upper()}[/green]")
|
||||
console.print(f"[dim] {len(data['segments'])} segmentos processados[/dim]")
|
||||
|
||||
return data
|
||||
|
||||
except Exception as e:
|
||||
console.print(f"[red]❌ Erro na transcrição: {e}[/red]")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
def save_outputs(transcript_text, ata_text, audio_file, output_dir="."):
|
||||
"""
|
||||
Salva transcript e ata em arquivos .md com timestamp.
|
||||
|
||||
Returns:
|
||||
tuple: (transcript_path, ata_path or None)
|
||||
"""
|
||||
timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
|
||||
base_name = Path(audio_file).stem
|
||||
|
||||
# Sempre salva transcript
|
||||
transcript_filename = f"transcript-{timestamp}.md"
|
||||
transcript_path = Path(output_dir) / transcript_filename
|
||||
|
||||
with open(transcript_path, 'w', encoding='utf-8') as f:
|
||||
f.write(transcript_text)
|
||||
|
||||
console.print(f"[green]✅ Transcript salvo:[/green] {transcript_filename}")
|
||||
|
||||
# Salva ata se existir
|
||||
ata_path = None
|
||||
if ata_text:
|
||||
ata_filename = f"ata-{timestamp}.md"
|
||||
ata_path = Path(output_dir) / ata_filename
|
||||
|
||||
with open(ata_path, 'w', encoding='utf-8') as f:
|
||||
f.write(ata_text)
|
||||
|
||||
console.print(f"[green]✅ Ata salva:[/green] {ata_filename}")
|
||||
|
||||
return str(transcript_path), str(ata_path) if ata_path else None
|
||||
|
||||
|
||||
def main():
|
||||
"""Função principal."""
|
||||
import argparse
|
||||
|
||||
parser = argparse.ArgumentParser(description="Audio Transcriber v1.1.0")
|
||||
parser.add_argument("audio_file", help="Arquivo de áudio para transcrever")
|
||||
parser.add_argument("--prompt", help="Prompt customizado para processar transcript")
|
||||
parser.add_argument("--model", default="base", help="Modelo Whisper (tiny/base/small/medium/large)")
|
||||
parser.add_argument("--output-dir", default=".", help="Diretório de saída")
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
# Verificar arquivo existe
|
||||
if not os.path.exists(args.audio_file):
|
||||
console.print(f"[red]❌ Arquivo não encontrado: {args.audio_file}[/red]")
|
||||
sys.exit(1)
|
||||
|
||||
console.print("[bold cyan]🎵 Audio Transcriber v1.1.0[/bold cyan]\n")
|
||||
|
||||
# Step 1: Transcrever
|
||||
transcription_data = transcribe_audio(args.audio_file, model=args.model)
|
||||
|
||||
# Gerar texto do transcript
|
||||
transcript_text = f"# Transcrição de Áudio\n\n"
|
||||
transcript_text += f"**Arquivo:** {Path(args.audio_file).name}\n"
|
||||
transcript_text += f"**Idioma:** {transcription_data['language'].upper()}\n"
|
||||
transcript_text += f"**Data:** {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n"
|
||||
transcript_text += "---\n\n## Transcrição Completa\n\n"
|
||||
|
||||
for seg in transcription_data["segments"]:
|
||||
start_min = int(seg["start"] // 60)
|
||||
start_sec = int(seg["start"] % 60)
|
||||
end_min = int(seg["end"] // 60)
|
||||
end_sec = int(seg["end"] % 60)
|
||||
transcript_text += f"**[{start_min:02d}:{start_sec:02d} → {end_min:02d}:{end_sec:02d}]** \n{seg['text']}\n\n"
|
||||
|
||||
# Step 2: Detectar CLI
|
||||
cli_tool = detect_cli_tool()
|
||||
|
||||
if not cli_tool:
|
||||
console.print("\n[yellow]⚠️ Nenhuma CLI de IA detectada (Claude ou GitHub Copilot)[/yellow]")
|
||||
console.print("[dim]ℹ️ Salvando apenas transcript.md...[/dim]")
|
||||
|
||||
save_outputs(transcript_text, None, args.audio_file, args.output_dir)
|
||||
|
||||
console.print("\n[cyan]💡 Para gerar ata/resumo:[/cyan]")
|
||||
console.print(" - Instale Claude CLI: pip install claude-cli")
|
||||
console.print(" - Ou GitHub Copilot CLI já está instalado (gh copilot)")
|
||||
return
|
||||
|
||||
console.print(f"\n[green]✅ CLI detectada: {cli_tool}[/green]")
|
||||
|
||||
# Step 3: Workflow de prompt
|
||||
final_prompt = handle_prompt_workflow(args.prompt, transcript_text)
|
||||
|
||||
if final_prompt is None:
|
||||
# Usuário recusou processamento
|
||||
save_outputs(transcript_text, None, args.audio_file, args.output_dir)
|
||||
return
|
||||
|
||||
# Step 4: Processar com LLM
|
||||
ata_text = process_with_llm(transcript_text, final_prompt, cli_tool)
|
||||
|
||||
if ata_text:
|
||||
console.print("[green]✅ Ata gerada com sucesso![/green]")
|
||||
else:
|
||||
console.print("[yellow]⚠️ Falha ao gerar ata, salvando apenas transcript[/yellow]")
|
||||
|
||||
# Step 5: Salvar arquivos
|
||||
console.print("\n[cyan]💾 Salvando arquivos...[/cyan]")
|
||||
save_outputs(transcript_text, ata_text, args.audio_file, args.output_dir)
|
||||
|
||||
console.print("\n[bold green]✅ Concluído![/bold green]")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,220 +0,0 @@
|
||||
---
|
||||
name: bamboohr-automation
|
||||
description: "Automate BambooHR tasks via Rube MCP (Composio): employees, time-off, benefits, dependents, employee updates. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# BambooHR Automation via Rube MCP
|
||||
|
||||
Automate BambooHR human resources operations through Composio's BambooHR toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active BambooHR connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `bamboohr`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `bamboohr`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete BambooHR authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. List and Search Employees
|
||||
|
||||
**When to use**: User wants to find employees or get the full employee directory
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BAMBOOHR_GET_ALL_EMPLOYEES` - Get the employee directory [Required]
|
||||
2. `BAMBOOHR_GET_EMPLOYEE` - Get detailed info for a specific employee [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- For GET_ALL_EMPLOYEES: No required parameters; returns directory
|
||||
- For GET_EMPLOYEE:
|
||||
- `id`: Employee ID (numeric)
|
||||
- `fields`: Comma-separated list of fields to return (e.g., 'firstName,lastName,department,jobTitle')
|
||||
|
||||
**Pitfalls**:
|
||||
- Employee IDs are numeric integers
|
||||
- GET_ALL_EMPLOYEES returns basic directory info; use GET_EMPLOYEE for full details
|
||||
- The `fields` parameter controls which fields are returned; omitting it may return minimal data
|
||||
- Common fields: firstName, lastName, department, division, jobTitle, workEmail, status
|
||||
- Inactive/terminated employees may be included; check `status` field
|
||||
|
||||
### 2. Track Employee Changes
|
||||
|
||||
**When to use**: User wants to detect recent employee data changes for sync or auditing
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BAMBOOHR_EMPLOYEE_GET_CHANGED` - Get employees with recent changes [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `since`: ISO 8601 datetime string for change detection threshold
|
||||
- `type`: Type of changes to check (e.g., 'inserted', 'updated', 'deleted')
|
||||
|
||||
**Pitfalls**:
|
||||
- `since` parameter is required; use ISO 8601 format (e.g., '2024-01-15T00:00:00Z')
|
||||
- Returns IDs of changed employees, not full employee data
|
||||
- Must call GET_EMPLOYEE separately for each changed employee's details
|
||||
- Useful for incremental sync workflows; cache the last sync timestamp
|
||||
|
||||
### 3. Manage Time-Off
|
||||
|
||||
**When to use**: User wants to view time-off balances, request time off, or manage requests
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BAMBOOHR_GET_META_TIME_OFF_TYPES` - List available time-off types [Prerequisite]
|
||||
2. `BAMBOOHR_GET_TIME_OFF_BALANCES` - Check current balances [Optional]
|
||||
3. `BAMBOOHR_GET_TIME_OFF_REQUESTS` - List existing requests [Optional]
|
||||
4. `BAMBOOHR_CREATE_TIME_OFF_REQUEST` - Submit a new request [Optional]
|
||||
5. `BAMBOOHR_UPDATE_TIME_OFF_REQUEST` - Modify or approve/deny a request [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- For balances: `employeeId`, time-off type ID
|
||||
- For requests: `start`, `end` (date range), `employeeId`
|
||||
- For creation:
|
||||
- `employeeId`: Employee to request for
|
||||
- `timeOffTypeId`: Type ID from GET_META_TIME_OFF_TYPES
|
||||
- `start`: Start date (YYYY-MM-DD)
|
||||
- `end`: End date (YYYY-MM-DD)
|
||||
- `amount`: Number of days/hours
|
||||
- `notes`: Optional notes for the request
|
||||
- For update: `requestId`, `status` ('approved', 'denied', 'cancelled')
|
||||
|
||||
**Pitfalls**:
|
||||
- Time-off type IDs are numeric; resolve via GET_META_TIME_OFF_TYPES first
|
||||
- Date format is 'YYYY-MM-DD' for start and end dates
|
||||
- Balances may be in hours or days depending on company configuration
|
||||
- Request status updates require appropriate permissions (manager/admin)
|
||||
- Creating a request does NOT auto-approve it; separate approval step needed
|
||||
|
||||
### 4. Update Employee Information
|
||||
|
||||
**When to use**: User wants to modify employee profile data
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BAMBOOHR_GET_EMPLOYEE` - Get current employee data [Prerequisite]
|
||||
2. `BAMBOOHR_UPDATE_EMPLOYEE` - Update employee fields [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `id`: Employee ID (numeric, required)
|
||||
- Field-value pairs for the fields to update (e.g., `department`, `jobTitle`, `workPhone`)
|
||||
|
||||
**Pitfalls**:
|
||||
- Only fields included in the request are updated; others remain unchanged
|
||||
- Some fields are read-only and cannot be updated via API
|
||||
- Field names must match BambooHR's expected field names exactly
|
||||
- Updates are audited; changes appear in the employee's change history
|
||||
- Verify current values with GET_EMPLOYEE before updating to avoid overwriting
|
||||
|
||||
### 5. Manage Dependents and Benefits
|
||||
|
||||
**When to use**: User wants to view employee dependents or benefit coverage
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BAMBOOHR_DEPENDENTS_GET_ALL` - List all dependents [Required]
|
||||
2. `BAMBOOHR_BENEFIT_GET_COVERAGES` - Get benefit coverage details [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- For dependents: Optional `employeeId` filter
|
||||
- For benefits: Depends on schema; check RUBE_SEARCH_TOOLS for current parameters
|
||||
|
||||
**Pitfalls**:
|
||||
- Dependent data includes sensitive PII; handle with appropriate care
|
||||
- Benefit coverages may include multiple plan types per employee
|
||||
- Not all BambooHR plans include benefits administration; check account features
|
||||
- Data access depends on API key permissions
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Employee name -> Employee ID**:
|
||||
```
|
||||
1. Call BAMBOOHR_GET_ALL_EMPLOYEES
|
||||
2. Find employee by name in directory results
|
||||
3. Extract id (numeric) for detailed operations
|
||||
```
|
||||
|
||||
**Time-off type name -> Type ID**:
|
||||
```
|
||||
1. Call BAMBOOHR_GET_META_TIME_OFF_TYPES
|
||||
2. Find type by name (e.g., 'Vacation', 'Sick Leave')
|
||||
3. Extract id for time-off requests
|
||||
```
|
||||
|
||||
### Incremental Sync Pattern
|
||||
|
||||
For keeping external systems in sync with BambooHR:
|
||||
```
|
||||
1. Store last_sync_timestamp
|
||||
2. Call BAMBOOHR_EMPLOYEE_GET_CHANGED with since=last_sync_timestamp
|
||||
3. For each changed employee ID, call BAMBOOHR_GET_EMPLOYEE
|
||||
4. Process updates in external system
|
||||
5. Update last_sync_timestamp
|
||||
```
|
||||
|
||||
### Time-Off Workflow
|
||||
|
||||
```
|
||||
1. GET_META_TIME_OFF_TYPES -> find type ID
|
||||
2. GET_TIME_OFF_BALANCES -> verify available balance
|
||||
3. CREATE_TIME_OFF_REQUEST -> submit request
|
||||
4. UPDATE_TIME_OFF_REQUEST -> approve/deny (manager action)
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Employee IDs**:
|
||||
- Always numeric integers
|
||||
- Resolve names to IDs via GET_ALL_EMPLOYEES
|
||||
- Terminated employees retain their IDs
|
||||
|
||||
**Date Formats**:
|
||||
- Time-off dates: 'YYYY-MM-DD'
|
||||
- Change detection: ISO 8601 with timezone
|
||||
- Inconsistent formats between endpoints; check each endpoint's schema
|
||||
|
||||
**Permissions**:
|
||||
- API key permissions determine accessible fields and operations
|
||||
- Some operations require admin or manager-level access
|
||||
- Time-off approvals require appropriate role permissions
|
||||
|
||||
**Sensitive Data**:
|
||||
- Employee data includes PII (names, addresses, SSN, etc.)
|
||||
- Handle all responses with appropriate security measures
|
||||
- Dependent data is especially sensitive
|
||||
|
||||
**Rate Limits**:
|
||||
- BambooHR API has rate limits per API key
|
||||
- Bulk operations should be throttled
|
||||
- GET_ALL_EMPLOYEES is more efficient than individual GET_EMPLOYEE calls
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` key
|
||||
- Employee fields vary based on `fields` parameter
|
||||
- Empty fields may be omitted or returned as null
|
||||
- Parse defensively with fallbacks
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List all employees | BAMBOOHR_GET_ALL_EMPLOYEES | (none) |
|
||||
| Get employee details | BAMBOOHR_GET_EMPLOYEE | id, fields |
|
||||
| Track changes | BAMBOOHR_EMPLOYEE_GET_CHANGED | since, type |
|
||||
| Time-off types | BAMBOOHR_GET_META_TIME_OFF_TYPES | (none) |
|
||||
| Time-off balances | BAMBOOHR_GET_TIME_OFF_BALANCES | employeeId |
|
||||
| List time-off requests | BAMBOOHR_GET_TIME_OFF_REQUESTS | start, end, employeeId |
|
||||
| Create time-off request | BAMBOOHR_CREATE_TIME_OFF_REQUEST | employeeId, timeOffTypeId, start, end |
|
||||
| Update time-off request | BAMBOOHR_UPDATE_TIME_OFF_REQUEST | requestId, status |
|
||||
| Update employee | BAMBOOHR_UPDATE_EMPLOYEE | id, (field updates) |
|
||||
| List dependents | BAMBOOHR_DEPENDENTS_GET_ALL | employeeId |
|
||||
| Benefit coverages | BAMBOOHR_BENEFIT_GET_COVERAGES | (check schema) |
|
||||
@@ -1,234 +0,0 @@
|
||||
---
|
||||
name: basecamp-automation
|
||||
description: "Automate Basecamp project management, to-dos, messages, people, and to-do list organization via Rube MCP (Composio). Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Basecamp Automation via Rube MCP
|
||||
|
||||
Automate Basecamp operations including project management, to-do list creation, task management, message board posting, people management, and to-do group organization through Composio's Basecamp toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Basecamp connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `basecamp`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `basecamp`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Basecamp OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Manage To-Do Lists and Tasks
|
||||
|
||||
**When to use**: User wants to create to-do lists, add tasks, or organize work within a Basecamp project
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BASECAMP_GET_PROJECTS` - List projects to find the target bucket_id [Prerequisite]
|
||||
2. `BASECAMP_GET_BUCKETS_TODOSETS` - Get the to-do set within a project [Prerequisite]
|
||||
3. `BASECAMP_GET_BUCKETS_TODOSETS_TODOLISTS` - List existing to-do lists to avoid duplicates [Optional]
|
||||
4. `BASECAMP_POST_BUCKETS_TODOSETS_TODOLISTS` - Create a new to-do list in a to-do set [Required for list creation]
|
||||
5. `BASECAMP_GET_BUCKETS_TODOLISTS` - Get details of a specific to-do list [Optional]
|
||||
6. `BASECAMP_POST_BUCKETS_TODOLISTS_TODOS` - Create a to-do item in a to-do list [Required for task creation]
|
||||
7. `BASECAMP_CREATE_TODO` - Alternative tool for creating individual to-dos [Alternative]
|
||||
8. `BASECAMP_GET_BUCKETS_TODOLISTS_TODOS` - List to-dos within a to-do list [Optional]
|
||||
|
||||
**Key parameters for creating to-do lists**:
|
||||
- `bucket_id`: Integer project/bucket ID (from GET_PROJECTS)
|
||||
- `todoset_id`: Integer to-do set ID (from GET_BUCKETS_TODOSETS)
|
||||
- `name`: Title of the to-do list (required)
|
||||
- `description`: HTML-formatted description (supports Rich text)
|
||||
|
||||
**Key parameters for creating to-dos**:
|
||||
- `bucket_id`: Integer project/bucket ID
|
||||
- `todolist_id`: Integer to-do list ID
|
||||
- `content`: What the to-do is for (required)
|
||||
- `description`: HTML details about the to-do
|
||||
- `assignee_ids`: Array of integer person IDs
|
||||
- `due_on`: Due date in `YYYY-MM-DD` format
|
||||
- `starts_on`: Start date in `YYYY-MM-DD` format
|
||||
- `notify`: Boolean to notify assignees (defaults to false)
|
||||
- `completion_subscriber_ids`: Person IDs notified upon completion
|
||||
|
||||
**Pitfalls**:
|
||||
- A project (bucket) can contain multiple to-do sets; selecting the wrong `todoset_id` creates lists in the wrong section
|
||||
- Always check existing to-do lists before creating to avoid near-duplicate names
|
||||
- Success payloads include user-facing URLs (`app_url`, `app_todos_url`); prefer returning these over raw IDs
|
||||
- All IDs (`bucket_id`, `todoset_id`, `todolist_id`) are integers, not strings
|
||||
- Descriptions support HTML formatting only, not Markdown
|
||||
|
||||
### 2. Post and Manage Messages
|
||||
|
||||
**When to use**: User wants to post messages to a project message board or update existing messages
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BASECAMP_GET_PROJECTS` - Find the target project and bucket_id [Prerequisite]
|
||||
2. `BASECAMP_GET_MESSAGE_BOARD` - Get the message board ID for the project [Prerequisite]
|
||||
3. `BASECAMP_CREATE_MESSAGE` - Create a new message on the board [Required]
|
||||
4. `BASECAMP_POST_BUCKETS_MESSAGE_BOARDS_MESSAGES` - Alternative message creation tool [Fallback]
|
||||
5. `BASECAMP_GET_MESSAGE` - Read a specific message by ID [Optional]
|
||||
6. `BASECAMP_PUT_BUCKETS_MESSAGES` - Update an existing message [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `bucket_id`: Integer project/bucket ID
|
||||
- `message_board_id`: Integer message board ID (from GET_MESSAGE_BOARD)
|
||||
- `subject`: Message title (required)
|
||||
- `content`: HTML body of the message
|
||||
- `status`: Set to `"active"` to publish immediately
|
||||
- `category_id`: Message type classification (optional)
|
||||
- `subscriptions`: Array of person IDs to notify; omit to notify all project members
|
||||
|
||||
**Pitfalls**:
|
||||
- `status="draft"` can produce HTTP 400; use `status="active"` as the reliable option
|
||||
- `bucket_id` and `message_board_id` must belong to the same project; mismatches fail or misroute
|
||||
- Message content supports HTML tags only; not Markdown
|
||||
- Updates via `PUT_BUCKETS_MESSAGES` replace the entire body -- include the full corrected content, not just a diff
|
||||
- Prefer `app_url` from the response for user-facing confirmation links
|
||||
- Both `CREATE_MESSAGE` and `POST_BUCKETS_MESSAGE_BOARDS_MESSAGES` do the same thing; use CREATE_MESSAGE first and fall back to POST if it fails
|
||||
|
||||
### 3. Manage People and Access
|
||||
|
||||
**When to use**: User wants to list people, manage project access, or add new users
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BASECAMP_GET_PEOPLE` - List all people visible to the current user [Required]
|
||||
2. `BASECAMP_GET_PROJECTS` - Find the target project [Prerequisite]
|
||||
3. `BASECAMP_LIST_PROJECT_PEOPLE` - List people on a specific project [Required]
|
||||
4. `BASECAMP_GET_PROJECTS_PEOPLE` - Alternative to list project members [Alternative]
|
||||
5. `BASECAMP_PUT_PROJECTS_PEOPLE_USERS` - Grant or revoke project access [Required for access changes]
|
||||
|
||||
**Key parameters for PUT_PROJECTS_PEOPLE_USERS**:
|
||||
- `project_id`: Integer project ID
|
||||
- `grant`: Array of integer person IDs to add to the project
|
||||
- `revoke`: Array of integer person IDs to remove from the project
|
||||
- `create`: Array of objects with `name`, `email_address`, and optional `company_name`, `title` for new users
|
||||
- At least one of `grant`, `revoke`, or `create` must be provided
|
||||
|
||||
**Pitfalls**:
|
||||
- Person IDs are integers; always resolve names to IDs via GET_PEOPLE first
|
||||
- `project_id` for people management is the same as `bucket_id` for other operations
|
||||
- `LIST_PROJECT_PEOPLE` and `GET_PROJECTS_PEOPLE` are near-identical; use either
|
||||
- Creating users via `create` also grants them project access in one step
|
||||
|
||||
### 4. Organize To-Dos with Groups
|
||||
|
||||
**When to use**: User wants to organize to-dos within a list into color-coded groups
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BASECAMP_GET_PROJECTS` - Find the target project [Prerequisite]
|
||||
2. `BASECAMP_GET_BUCKETS_TODOLISTS` - Get the to-do list details [Prerequisite]
|
||||
3. `BASECAMP_GET_TODOLIST_GROUPS` - List existing groups in a to-do list [Optional]
|
||||
4. `BASECAMP_GET_BUCKETS_TODOLISTS_GROUPS` - Alternative group listing [Alternative]
|
||||
5. `BASECAMP_POST_BUCKETS_TODOLISTS_GROUPS` - Create a new group in a to-do list [Required]
|
||||
6. `BASECAMP_CREATE_TODOLIST_GROUP` - Alternative group creation tool [Alternative]
|
||||
|
||||
**Key parameters**:
|
||||
- `bucket_id`: Integer project/bucket ID
|
||||
- `todolist_id`: Integer to-do list ID
|
||||
- `name`: Group title (required)
|
||||
- `color`: Visual color identifier -- one of: `white`, `red`, `orange`, `yellow`, `green`, `blue`, `aqua`, `purple`, `gray`, `pink`, `brown`
|
||||
- `status`: Filter for listing -- `"archived"` or `"trashed"` (omit for active groups)
|
||||
|
||||
**Pitfalls**:
|
||||
- `POST_BUCKETS_TODOLISTS_GROUPS` and `CREATE_TODOLIST_GROUP` are near-identical; use either
|
||||
- Color values must be from the fixed palette; arbitrary hex/rgb values are not supported
|
||||
- Groups are sub-sections within a to-do list, not standalone entities
|
||||
|
||||
### 5. Browse and Inspect Projects
|
||||
|
||||
**When to use**: User wants to list projects, get project details, or explore project structure
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BASECAMP_GET_PROJECTS` - List all active projects [Required]
|
||||
2. `BASECAMP_GET_PROJECT` - Get comprehensive details for a specific project [Optional]
|
||||
3. `BASECAMP_GET_PROJECTS_BY_PROJECT_ID` - Alternative project detail retrieval [Alternative]
|
||||
|
||||
**Key parameters**:
|
||||
- `status`: Filter by `"archived"` or `"trashed"`; omit for active projects
|
||||
- `project_id`: Integer project ID for detailed retrieval
|
||||
|
||||
**Pitfalls**:
|
||||
- Projects are sorted by most recently created first
|
||||
- The response includes a `dock` array with tools (todoset, message_board, etc.) and their IDs
|
||||
- Use the dock tool IDs to find `todoset_id`, `message_board_id`, etc. for downstream operations
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
Basecamp uses a hierarchical ID structure. Always resolve top-down:
|
||||
- **Project (bucket_id)**: `BASECAMP_GET_PROJECTS` -- find by name, capture the `id`
|
||||
- **To-do set (todoset_id)**: Found in project dock or via `BASECAMP_GET_BUCKETS_TODOSETS`
|
||||
- **Message board (message_board_id)**: Found in project dock or via `BASECAMP_GET_MESSAGE_BOARD`
|
||||
- **To-do list (todolist_id)**: `BASECAMP_GET_BUCKETS_TODOSETS_TODOLISTS`
|
||||
- **People (person_id)**: `BASECAMP_GET_PEOPLE` or `BASECAMP_LIST_PROJECT_PEOPLE`
|
||||
- Note: `bucket_id` and `project_id` refer to the same entity in different contexts
|
||||
|
||||
### Pagination
|
||||
Basecamp uses page-based pagination on list endpoints:
|
||||
- Response headers or body may indicate more pages available
|
||||
- `GET_PROJECTS`, `GET_BUCKETS_TODOSETS_TODOLISTS`, and list endpoints return paginated results
|
||||
- Continue fetching until no more results are returned
|
||||
|
||||
### Content Formatting
|
||||
- All rich text fields use HTML, not Markdown
|
||||
- Wrap content in `<div>` tags; use `<strong>`, `<em>`, `<ul>`, `<ol>`, `<li>`, `<a>` etc.
|
||||
- Example: `<div><strong>Important:</strong> Complete by Friday</div>`
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
### ID Formats
|
||||
- All Basecamp IDs are integers, not strings or UUIDs
|
||||
- `bucket_id` = `project_id` (same entity, different parameter names across tools)
|
||||
- To-do set IDs, to-do list IDs, and message board IDs are found in the project's `dock` array
|
||||
- Person IDs are integers; resolve names via `GET_PEOPLE` before operations
|
||||
|
||||
### Status Field
|
||||
- `status="draft"` for messages can cause HTTP 400; always use `status="active"`
|
||||
- Project/to-do list status filters: `"archived"`, `"trashed"`, or omit for active
|
||||
|
||||
### Content Format
|
||||
- HTML only, never Markdown
|
||||
- Updates replace the entire body, not a partial diff
|
||||
- Invalid HTML tags may be silently stripped
|
||||
|
||||
### Rate Limits
|
||||
- Basecamp API has rate limits; space out rapid sequential requests
|
||||
- Large projects with many to-dos should be paginated carefully
|
||||
|
||||
### URL Handling
|
||||
- Prefer `app_url` from API responses for user-facing links
|
||||
- Do not reconstruct Basecamp URLs manually from IDs
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List projects | `BASECAMP_GET_PROJECTS` | `status` |
|
||||
| Get project | `BASECAMP_GET_PROJECT` | `project_id` |
|
||||
| Get project detail | `BASECAMP_GET_PROJECTS_BY_PROJECT_ID` | `project_id` |
|
||||
| Get to-do set | `BASECAMP_GET_BUCKETS_TODOSETS` | `bucket_id`, `todoset_id` |
|
||||
| List to-do lists | `BASECAMP_GET_BUCKETS_TODOSETS_TODOLISTS` | `bucket_id`, `todoset_id` |
|
||||
| Get to-do list | `BASECAMP_GET_BUCKETS_TODOLISTS` | `bucket_id`, `todolist_id` |
|
||||
| Create to-do list | `BASECAMP_POST_BUCKETS_TODOSETS_TODOLISTS` | `bucket_id`, `todoset_id`, `name` |
|
||||
| Create to-do | `BASECAMP_POST_BUCKETS_TODOLISTS_TODOS` | `bucket_id`, `todolist_id`, `content` |
|
||||
| Create to-do (alt) | `BASECAMP_CREATE_TODO` | `bucket_id`, `todolist_id`, `content` |
|
||||
| List to-dos | `BASECAMP_GET_BUCKETS_TODOLISTS_TODOS` | `bucket_id`, `todolist_id` |
|
||||
| List to-do groups | `BASECAMP_GET_TODOLIST_GROUPS` | `bucket_id`, `todolist_id` |
|
||||
| Create to-do group | `BASECAMP_POST_BUCKETS_TODOLISTS_GROUPS` | `bucket_id`, `todolist_id`, `name`, `color` |
|
||||
| Create to-do group (alt) | `BASECAMP_CREATE_TODOLIST_GROUP` | `bucket_id`, `todolist_id`, `name` |
|
||||
| Get message board | `BASECAMP_GET_MESSAGE_BOARD` | `bucket_id`, `message_board_id` |
|
||||
| Create message | `BASECAMP_CREATE_MESSAGE` | `bucket_id`, `message_board_id`, `subject`, `status` |
|
||||
| Create message (alt) | `BASECAMP_POST_BUCKETS_MESSAGE_BOARDS_MESSAGES` | `bucket_id`, `message_board_id`, `subject` |
|
||||
| Get message | `BASECAMP_GET_MESSAGE` | `bucket_id`, `message_id` |
|
||||
| Update message | `BASECAMP_PUT_BUCKETS_MESSAGES` | `bucket_id`, `message_id` |
|
||||
| List all people | `BASECAMP_GET_PEOPLE` | (none) |
|
||||
| List project people | `BASECAMP_LIST_PROJECT_PEOPLE` | `project_id` |
|
||||
| Manage access | `BASECAMP_PUT_PROJECTS_PEOPLE_USERS` | `project_id`, `grant`, `revoke`, `create` |
|
||||
@@ -1,224 +0,0 @@
|
||||
---
|
||||
name: bitbucket-automation
|
||||
description: "Automate Bitbucket repositories, pull requests, branches, issues, and workspace management via Rube MCP (Composio). Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Bitbucket Automation via Rube MCP
|
||||
|
||||
Automate Bitbucket operations including repository management, pull request workflows, branch operations, issue tracking, and workspace administration through Composio's Bitbucket toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Bitbucket connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `bitbucket`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `bitbucket`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Bitbucket OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Manage Pull Requests
|
||||
|
||||
**When to use**: User wants to create, review, or inspect pull requests
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BITBUCKET_LIST_WORKSPACES` - Discover accessible workspaces [Prerequisite]
|
||||
2. `BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE` - Find the target repository [Prerequisite]
|
||||
3. `BITBUCKET_LIST_BRANCHES` - Verify source and destination branches exist [Prerequisite]
|
||||
4. `BITBUCKET_CREATE_PULL_REQUEST` - Create a new PR with title, source branch, and optional reviewers [Required]
|
||||
5. `BITBUCKET_LIST_PULL_REQUESTS` - List PRs filtered by state (OPEN, MERGED, DECLINED) [Optional]
|
||||
6. `BITBUCKET_GET_PULL_REQUEST` - Get full details of a specific PR by ID [Optional]
|
||||
7. `BITBUCKET_GET_PULL_REQUEST_DIFF` - Fetch unified diff for code review [Optional]
|
||||
8. `BITBUCKET_GET_PULL_REQUEST_DIFFSTAT` - Get changed files with lines added/removed [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `workspace`: Workspace slug or UUID (required for all operations)
|
||||
- `repo_slug`: URL-friendly repository name
|
||||
- `source_branch`: Branch with changes to merge
|
||||
- `destination_branch`: Target branch (defaults to repo main branch if omitted)
|
||||
- `reviewers`: List of objects with `uuid` field for reviewer assignment
|
||||
- `state`: Filter for LIST_PULL_REQUESTS - `OPEN`, `MERGED`, or `DECLINED`
|
||||
- `max_chars`: Truncation limit for GET_PULL_REQUEST_DIFF to handle large diffs
|
||||
|
||||
**Pitfalls**:
|
||||
- `reviewers` expects an array of objects with `uuid` key, NOT usernames: `[{"uuid": "{...}"}]`
|
||||
- UUID format must include curly braces: `{123e4567-e89b-12d3-a456-426614174000}`
|
||||
- `destination_branch` defaults to the repo's main branch if omitted, which may not be `main`
|
||||
- `pull_request_id` is an integer for GET/DIFF operations but comes back as part of PR listing
|
||||
- Large diffs can overwhelm context; always set `max_chars` (e.g., 50000) on GET_PULL_REQUEST_DIFF
|
||||
|
||||
### 2. Manage Repositories and Workspaces
|
||||
|
||||
**When to use**: User wants to list, create, or delete repositories or explore workspaces
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BITBUCKET_LIST_WORKSPACES` - List all accessible workspaces [Required]
|
||||
2. `BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE` - List repos with optional BBQL filtering [Required]
|
||||
3. `BITBUCKET_CREATE_REPOSITORY` - Create a new repo with language, privacy, and project settings [Optional]
|
||||
4. `BITBUCKET_DELETE_REPOSITORY` - Permanently delete a repository (irreversible) [Optional]
|
||||
5. `BITBUCKET_LIST_WORKSPACE_MEMBERS` - List members for reviewer assignment or access checks [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `workspace`: Workspace slug (find via LIST_WORKSPACES)
|
||||
- `repo_slug`: URL-friendly name for create/delete
|
||||
- `q`: BBQL query filter (e.g., `name~"api"`, `project.key="PROJ"`, `is_private=true`)
|
||||
- `role`: Filter repos by user role: `member`, `contributor`, `admin`, `owner`
|
||||
- `sort`: Sort field with optional `-` prefix for descending (e.g., `-updated_on`)
|
||||
- `is_private`: Boolean for repository visibility (defaults to `true`)
|
||||
- `project_key`: Bitbucket project key; omit to use workspace's oldest project
|
||||
|
||||
**Pitfalls**:
|
||||
- `BITBUCKET_DELETE_REPOSITORY` is **irreversible** and does not affect forks
|
||||
- BBQL string values MUST be enclosed in double quotes: `name~"my-repo"` not `name~my-repo`
|
||||
- `repository` is NOT a valid BBQL field; use `name` instead
|
||||
- Default pagination is 10 results; set `pagelen` explicitly for complete listings
|
||||
- `CREATE_REPOSITORY` defaults to private; set `is_private: false` for public repos
|
||||
|
||||
### 3. Manage Issues
|
||||
|
||||
**When to use**: User wants to create, update, list, or comment on repository issues
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BITBUCKET_LIST_ISSUES` - List issues with optional filters for state, priority, kind, assignee [Required]
|
||||
2. `BITBUCKET_CREATE_ISSUE` - Create a new issue with title, content, priority, and kind [Required]
|
||||
3. `BITBUCKET_UPDATE_ISSUE` - Modify issue attributes (state, priority, assignee, etc.) [Optional]
|
||||
4. `BITBUCKET_CREATE_ISSUE_COMMENT` - Add a markdown comment to an existing issue [Optional]
|
||||
5. `BITBUCKET_DELETE_ISSUE` - Permanently delete an issue [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `issue_id`: String identifier for the issue
|
||||
- `title`, `content`: Required for creation
|
||||
- `kind`: `bug`, `enhancement`, `proposal`, or `task`
|
||||
- `priority`: `trivial`, `minor`, `major`, `critical`, or `blocker`
|
||||
- `state`: `new`, `open`, `resolved`, `on hold`, `invalid`, `duplicate`, `wontfix`, `closed`
|
||||
- `assignee`: Bitbucket username for CREATE; `assignee_account_id` (UUID) for UPDATE
|
||||
- `due_on`: ISO 8601 format date string
|
||||
|
||||
**Pitfalls**:
|
||||
- Issue tracker must be enabled on the repository (`has_issues: true`) or API calls will fail
|
||||
- `CREATE_ISSUE` uses `assignee` (username string), but `UPDATE_ISSUE` uses `assignee_account_id` (UUID) -- they are different fields
|
||||
- `DELETE_ISSUE` is permanent with no undo
|
||||
- `state` values include spaces: `"on hold"` not `"on_hold"`
|
||||
- Filtering by `assignee` in LIST_ISSUES uses account ID, not username; use `"null"` string for unassigned
|
||||
|
||||
### 4. Manage Branches
|
||||
|
||||
**When to use**: User wants to create branches or explore branch structure
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BITBUCKET_LIST_BRANCHES` - List branches with optional BBQL filter and sorting [Required]
|
||||
2. `BITBUCKET_CREATE_BRANCH` - Create a new branch from a specific commit hash [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Branch name without `refs/heads/` prefix (e.g., `feature/new-login`)
|
||||
- `target_hash`: Full SHA1 commit hash to branch from (must exist in repo)
|
||||
- `q`: BBQL filter (e.g., `name~"feature/"`, `name="main"`)
|
||||
- `sort`: Sort by `name` or `-target.date` (descending commit date)
|
||||
- `pagelen`: 1-100 results per page (default is 10)
|
||||
|
||||
**Pitfalls**:
|
||||
- `CREATE_BRANCH` requires a full commit hash, NOT a branch name as `target_hash`
|
||||
- Do NOT include `refs/heads/` prefix in branch names
|
||||
- Branch names must follow Bitbucket naming conventions (alphanumeric, `/`, `.`, `_`, `-`)
|
||||
- BBQL string values need double quotes: `name~"feature/"` not `name~feature/`
|
||||
|
||||
### 5. Review Pull Requests with Comments
|
||||
|
||||
**When to use**: User wants to add review comments to pull requests, including inline code comments
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BITBUCKET_GET_PULL_REQUEST` - Get PR details and verify it exists [Prerequisite]
|
||||
2. `BITBUCKET_GET_PULL_REQUEST_DIFF` - Review the actual code changes [Prerequisite]
|
||||
3. `BITBUCKET_GET_PULL_REQUEST_DIFFSTAT` - Get list of changed files [Optional]
|
||||
4. `BITBUCKET_CREATE_PULL_REQUEST_COMMENT` - Post review comments [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `pull_request_id`: String ID of the PR
|
||||
- `content_raw`: Markdown-formatted comment text
|
||||
- `content_markup`: Defaults to `markdown`; also supports `plaintext`
|
||||
- `inline`: Object with `path`, `from`, `to` for inline code comments
|
||||
- `parent_comment_id`: Integer ID for threaded replies to existing comments
|
||||
|
||||
**Pitfalls**:
|
||||
- `pull_request_id` is a string in CREATE_PULL_REQUEST_COMMENT but an integer in GET_PULL_REQUEST
|
||||
- Inline comments require `inline.path` at minimum; `from`/`to` are optional line numbers
|
||||
- `parent_comment_id` creates a threaded reply; omit for top-level comments
|
||||
- Line numbers in inline comments reference the diff, not the source file
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
Always resolve human-readable names to IDs before operations:
|
||||
- **Workspace**: `BITBUCKET_LIST_WORKSPACES` to get workspace slugs
|
||||
- **Repository**: `BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE` with `q` filter to find repo slugs
|
||||
- **Branch**: `BITBUCKET_LIST_BRANCHES` to verify branch existence before PR creation
|
||||
- **Members**: `BITBUCKET_LIST_WORKSPACE_MEMBERS` to get UUIDs for reviewer assignment
|
||||
|
||||
### Pagination
|
||||
Bitbucket uses page-based pagination (not cursor-based):
|
||||
- Use `page` (starts at 1) and `pagelen` (items per page) parameters
|
||||
- Default page size is typically 10; set `pagelen` explicitly (max 50 for PRs, 100 for others)
|
||||
- Check response for `next` URL or total count to determine if more pages exist
|
||||
- Always iterate through all pages for complete results
|
||||
|
||||
### BBQL Filtering
|
||||
Bitbucket Query Language is available on list endpoints:
|
||||
- String values MUST use double quotes: `name~"pattern"`
|
||||
- Operators: `=` (exact), `~` (contains), `!=` (not equal), `>`, `>=`, `<`, `<=`
|
||||
- Combine with `AND` / `OR`: `name~"api" AND is_private=true`
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
### ID Formats
|
||||
- Workspace: slug string (e.g., `my-workspace`) or UUID in braces (`{uuid}`)
|
||||
- Reviewer UUIDs must include curly braces: `{123e4567-e89b-12d3-a456-426614174000}`
|
||||
- Issue IDs are strings; PR IDs are integers in some tools, strings in others
|
||||
- Commit hashes must be full SHA1 (40 characters)
|
||||
|
||||
### Parameter Quirks
|
||||
- `assignee` vs `assignee_account_id`: CREATE_ISSUE uses username, UPDATE_ISSUE uses UUID
|
||||
- `state` values for issues include spaces: `"on hold"`, not `"on_hold"`
|
||||
- `destination_branch` omission defaults to repo main branch, not `main` literally
|
||||
- BBQL `repository` is not a valid field -- use `name`
|
||||
|
||||
### Rate Limits
|
||||
- Bitbucket Cloud API has rate limits; large batch operations should include delays
|
||||
- Paginated requests count against rate limits; minimize unnecessary page fetches
|
||||
|
||||
### Destructive Operations
|
||||
- `BITBUCKET_DELETE_REPOSITORY` is irreversible and does not remove forks
|
||||
- `BITBUCKET_DELETE_ISSUE` is permanent with no recovery option
|
||||
- Always confirm with the user before executing delete operations
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List workspaces | `BITBUCKET_LIST_WORKSPACES` | `q`, `sort` |
|
||||
| List repos | `BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE` | `workspace`, `q`, `role` |
|
||||
| Create repo | `BITBUCKET_CREATE_REPOSITORY` | `workspace`, `repo_slug`, `is_private` |
|
||||
| Delete repo | `BITBUCKET_DELETE_REPOSITORY` | `workspace`, `repo_slug` |
|
||||
| List branches | `BITBUCKET_LIST_BRANCHES` | `workspace`, `repo_slug`, `q` |
|
||||
| Create branch | `BITBUCKET_CREATE_BRANCH` | `workspace`, `repo_slug`, `name`, `target_hash` |
|
||||
| List PRs | `BITBUCKET_LIST_PULL_REQUESTS` | `workspace`, `repo_slug`, `state` |
|
||||
| Create PR | `BITBUCKET_CREATE_PULL_REQUEST` | `workspace`, `repo_slug`, `title`, `source_branch` |
|
||||
| Get PR details | `BITBUCKET_GET_PULL_REQUEST` | `workspace`, `repo_slug`, `pull_request_id` |
|
||||
| Get PR diff | `BITBUCKET_GET_PULL_REQUEST_DIFF` | `workspace`, `repo_slug`, `pull_request_id`, `max_chars` |
|
||||
| Get PR diffstat | `BITBUCKET_GET_PULL_REQUEST_DIFFSTAT` | `workspace`, `repo_slug`, `pull_request_id` |
|
||||
| Comment on PR | `BITBUCKET_CREATE_PULL_REQUEST_COMMENT` | `workspace`, `repo_slug`, `pull_request_id`, `content_raw` |
|
||||
| List issues | `BITBUCKET_LIST_ISSUES` | `workspace`, `repo_slug`, `state`, `priority` |
|
||||
| Create issue | `BITBUCKET_CREATE_ISSUE` | `workspace`, `repo_slug`, `title`, `content` |
|
||||
| Update issue | `BITBUCKET_UPDATE_ISSUE` | `workspace`, `repo_slug`, `issue_id` |
|
||||
| Comment on issue | `BITBUCKET_CREATE_ISSUE_COMMENT` | `workspace`, `repo_slug`, `issue_id`, `content` |
|
||||
| Delete issue | `BITBUCKET_DELETE_ISSUE` | `workspace`, `repo_slug`, `issue_id` |
|
||||
| List members | `BITBUCKET_LIST_WORKSPACE_MEMBERS` | `workspace` |
|
||||
@@ -1,233 +0,0 @@
|
||||
---
|
||||
name: box-automation
|
||||
description: "Automate Box cloud storage operations including file upload/download, search, folder management, sharing, collaborations, and metadata queries via Rube MCP (Composio). Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Box Automation via Rube MCP
|
||||
|
||||
Automate Box operations including file upload/download, content search, folder management, collaboration, metadata queries, and sign requests through Composio's Box toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Box connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `box`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `box`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Box OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Upload and Download Files
|
||||
|
||||
**When to use**: User wants to upload files to Box or download files from it
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BOX_SEARCH_FOR_CONTENT` - Find the target folder if path is unknown [Prerequisite]
|
||||
2. `BOX_GET_FOLDER_INFORMATION` - Verify folder exists and get folder_id [Prerequisite]
|
||||
3. `BOX_LIST_ITEMS_IN_FOLDER` - Browse folder contents and discover file IDs [Optional]
|
||||
4. `BOX_UPLOAD_FILE` - Upload a file to a specific folder [Required for upload]
|
||||
5. `BOX_DOWNLOAD_FILE` - Download a file by file_id [Required for download]
|
||||
6. `BOX_CREATE_ZIP_DOWNLOAD` - Bundle multiple files/folders into a zip [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `parent_id`: Folder ID for upload destination (use `"0"` for root folder)
|
||||
- `file`: FileUploadable object with `s3key`, `mimetype`, and `name` for uploads
|
||||
- `file_id`: Unique file identifier for downloads
|
||||
- `version`: Optional file version ID for downloading specific versions
|
||||
- `fields`: Comma-separated list of attributes to return
|
||||
|
||||
**Pitfalls**:
|
||||
- Uploading to a folder with existing filenames can trigger conflict behavior; decide overwrite vs rename semantics
|
||||
- Files over 50MB should use chunk upload APIs (not available via standard tools)
|
||||
- The `attributes` part of upload must come before the `file` part or you get HTTP 400 with `metadata_after_file_contents`
|
||||
- File IDs and folder IDs are numeric strings extractable from Box web app URLs (e.g., `https://*.app.box.com/files/123` gives file_id `"123"`)
|
||||
|
||||
### 2. Search and Browse Content
|
||||
|
||||
**When to use**: User wants to find files, folders, or web links by name, content, or metadata
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BOX_SEARCH_FOR_CONTENT` - Full-text search across files, folders, and web links [Required]
|
||||
2. `BOX_LIST_ITEMS_IN_FOLDER` - Browse contents of a specific folder [Optional]
|
||||
3. `BOX_GET_FILE_INFORMATION` - Get detailed metadata for a specific file [Optional]
|
||||
4. `BOX_GET_FOLDER_INFORMATION` - Get detailed metadata for a specific folder [Optional]
|
||||
5. `BOX_QUERY_FILES_FOLDERS_BY_METADATA` - Search by metadata template values [Optional]
|
||||
6. `BOX_LIST_RECENTLY_ACCESSED_ITEMS` - List recently accessed items [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: Search string supporting operators (`""` exact match, `AND`, `OR`, `NOT` - uppercase only)
|
||||
- `type`: Filter by `"file"`, `"folder"`, or `"web_link"`
|
||||
- `ancestor_folder_ids`: Limit search to specific folders (comma-separated IDs)
|
||||
- `file_extensions`: Filter by file type (comma-separated, no dots)
|
||||
- `content_types`: Search in `"name"`, `"description"`, `"file_content"`, `"comments"`, `"tags"`
|
||||
- `created_at_range` / `updated_at_range`: Date filters as comma-separated RFC3339 timestamps
|
||||
- `limit`: Results per page (default 30)
|
||||
- `offset`: Pagination offset (max 10000)
|
||||
- `folder_id`: For `LIST_ITEMS_IN_FOLDER` (use `"0"` for root)
|
||||
|
||||
**Pitfalls**:
|
||||
- Queries with offset > 10000 are rejected with HTTP 400
|
||||
- `BOX_SEARCH_FOR_CONTENT` requires either `query` or `mdfilters` parameter
|
||||
- Misconfigured filters can silently omit expected items; validate with small test queries first
|
||||
- Boolean operators (`AND`, `OR`, `NOT`) must be uppercase
|
||||
- `BOX_LIST_ITEMS_IN_FOLDER` requires pagination via `marker` or `offset`/`usemarker`; partial listings are common
|
||||
- Standard folders sort items by type first (folders before files before web links)
|
||||
|
||||
### 3. Manage Folders
|
||||
|
||||
**When to use**: User wants to create, update, move, copy, or delete folders
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BOX_GET_FOLDER_INFORMATION` - Verify folder exists and check permissions [Prerequisite]
|
||||
2. `BOX_CREATE_FOLDER` - Create a new folder [Required for create]
|
||||
3. `BOX_UPDATE_FOLDER` - Rename, move, or update folder settings [Required for update]
|
||||
4. `BOX_COPY_FOLDER` - Copy a folder to a new location [Optional]
|
||||
5. `BOX_DELETE_FOLDER` - Move folder to trash [Required for delete]
|
||||
6. `BOX_PERMANENTLY_REMOVE_FOLDER` - Permanently delete a trashed folder [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Folder name (no `/`, `\`, trailing spaces, or `.`/`..`)
|
||||
- `parent__id`: Parent folder ID (use `"0"` for root)
|
||||
- `folder_id`: Target folder ID for operations
|
||||
- `parent.id`: Destination folder ID for moves via `BOX_UPDATE_FOLDER`
|
||||
- `recursive`: Set `true` to delete non-empty folders
|
||||
- `shared_link`: Object with `access`, `password`, `permissions` for creating shared links on folders
|
||||
- `description`, `tags`: Optional metadata fields
|
||||
|
||||
**Pitfalls**:
|
||||
- `BOX_DELETE_FOLDER` moves to trash by default; use `BOX_PERMANENTLY_REMOVE_FOLDER` for permanent deletion
|
||||
- Non-empty folders require `recursive: true` for deletion
|
||||
- Root folder (ID `"0"`) cannot be copied or deleted
|
||||
- Folder names cannot contain `/`, `\`, non-printable ASCII, or trailing spaces
|
||||
- Moving folders requires setting `parent.id` via `BOX_UPDATE_FOLDER`
|
||||
|
||||
### 4. Share Files and Manage Collaborations
|
||||
|
||||
**When to use**: User wants to share files, manage access, or handle collaborations
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BOX_GET_FILE_INFORMATION` - Get file details and current sharing status [Prerequisite]
|
||||
2. `BOX_LIST_FILE_COLLABORATIONS` - List who has access to a file [Required]
|
||||
3. `BOX_UPDATE_COLLABORATION` - Change access level or accept/reject invitations [Required]
|
||||
4. `BOX_GET_COLLABORATION` - Get details of a specific collaboration [Optional]
|
||||
5. `BOX_UPDATE_FILE` - Create shared links, lock files, or update permissions [Optional]
|
||||
6. `BOX_UPDATE_FOLDER` - Create shared links on folders [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `collaboration_id`: Unique collaboration identifier
|
||||
- `role`: Access level (`"editor"`, `"viewer"`, `"co-owner"`, `"owner"`, `"previewer"`, `"uploader"`, `"viewer uploader"`, `"previewer uploader"`)
|
||||
- `status`: `"accepted"`, `"pending"`, or `"rejected"` for collaboration invites
|
||||
- `file_id`: File to share or manage
|
||||
- `lock__access`: Set to `"lock"` to lock a file
|
||||
- `permissions__can__download`: `"company"` or `"open"` for download permissions
|
||||
|
||||
**Pitfalls**:
|
||||
- Only certain roles can invite collaborators; insufficient permissions cause authorization errors
|
||||
- `can_view_path` increases load time for the invitee's "All Files" page; limit to 1000 per user
|
||||
- Collaboration expiration requires enterprise admin settings to be enabled
|
||||
- Nested parameter names use double underscores (e.g., `lock__access`, `parent__id`)
|
||||
|
||||
### 5. Box Sign Requests
|
||||
|
||||
**When to use**: User wants to manage document signature requests
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BOX_LIST_BOX_SIGN_REQUESTS` - List all signature requests [Required]
|
||||
2. `BOX_GET_BOX_SIGN_REQUEST_BY_ID` - Get details of a specific sign request [Optional]
|
||||
3. `BOX_CANCEL_BOX_SIGN_REQUEST` - Cancel a pending sign request [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `sign_request_id`: UUID of the sign request
|
||||
- `shared_requests`: Set `true` to include requests where user is a collaborator (not owner)
|
||||
- `senders`: Filter by sender emails (requires `shared_requests: true`)
|
||||
- `limit` / `marker`: Pagination parameters
|
||||
|
||||
**Pitfalls**:
|
||||
- Requires Box Sign to be enabled for the enterprise account
|
||||
- Deleted sign files or parent folders cause requests to not appear in listings
|
||||
- Only the creator can cancel a sign request
|
||||
- Sign request statuses include: `converting`, `created`, `sent`, `viewed`, `signed`, `declined`, `cancelled`, `expired`, `error_converting`, `error_sending`
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
Box uses numeric string IDs for all entities:
|
||||
- **Root folder**: Always ID `"0"`
|
||||
- **File ID from URL**: `https://*.app.box.com/files/123` gives file_id `"123"`
|
||||
- **Folder ID from URL**: `https://*.app.box.com/folder/123` gives folder_id `"123"`
|
||||
- **Search to ID**: Use `BOX_SEARCH_FOR_CONTENT` to find items, then extract IDs from results
|
||||
- **ETag**: Use `if_match` with file's ETag for safe concurrent delete operations
|
||||
|
||||
### Pagination
|
||||
Box supports two pagination methods:
|
||||
- **Offset-based**: Use `offset` + `limit` (max offset 10000)
|
||||
- **Marker-based**: Set `usemarker: true` and follow `marker` from responses (preferred for large datasets)
|
||||
- Always paginate to completion to avoid partial results
|
||||
|
||||
### Nested Parameters
|
||||
Box tools use double underscore notation for nested objects:
|
||||
- `parent__id` for parent folder reference
|
||||
- `lock__access`, `lock__expires__at`, `lock__is__download__prevented` for file locks
|
||||
- `permissions__can__download` for download permissions
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
### ID Formats
|
||||
- All IDs are numeric strings (e.g., `"123456"`, not integers)
|
||||
- Root folder is always `"0"`
|
||||
- File and folder IDs can be extracted from Box web app URLs
|
||||
|
||||
### Rate Limits
|
||||
- Box API has per-endpoint rate limits
|
||||
- Search and list operations should use pagination responsibly
|
||||
- Bulk operations should include delays between requests
|
||||
|
||||
### Parameter Quirks
|
||||
- `fields` parameter changes response shape: when specified, only mini representation + requested fields are returned
|
||||
- Search requires either `query` or `mdfilters`; both are optional individually but one must be present
|
||||
- `BOX_UPDATE_FILE` with `lock` set to `null` removes the lock (raw API only)
|
||||
- Metadata query `from` field format: `enterprise_{enterprise_id}.templateKey` or `global.templateKey`
|
||||
|
||||
### Permissions
|
||||
- Deletions fail without sufficient permissions; always handle error responses
|
||||
- Collaboration roles determine what operations are allowed
|
||||
- Enterprise settings may restrict certain sharing options
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Search content | `BOX_SEARCH_FOR_CONTENT` | `query`, `type`, `ancestor_folder_ids` |
|
||||
| List folder items | `BOX_LIST_ITEMS_IN_FOLDER` | `folder_id`, `limit`, `marker` |
|
||||
| Get file info | `BOX_GET_FILE_INFORMATION` | `file_id`, `fields` |
|
||||
| Get folder info | `BOX_GET_FOLDER_INFORMATION` | `folder_id`, `fields` |
|
||||
| Upload file | `BOX_UPLOAD_FILE` | `file`, `parent_id` |
|
||||
| Download file | `BOX_DOWNLOAD_FILE` | `file_id` |
|
||||
| Create folder | `BOX_CREATE_FOLDER` | `name`, `parent__id` |
|
||||
| Update folder | `BOX_UPDATE_FOLDER` | `folder_id`, `name`, `parent` |
|
||||
| Copy folder | `BOX_COPY_FOLDER` | `folder_id`, `parent__id` |
|
||||
| Delete folder | `BOX_DELETE_FOLDER` | `folder_id`, `recursive` |
|
||||
| Permanently delete folder | `BOX_PERMANENTLY_REMOVE_FOLDER` | folder_id |
|
||||
| Update file | `BOX_UPDATE_FILE` | `file_id`, `name`, `parent__id` |
|
||||
| Delete file | `BOX_DELETE_FILE` | `file_id`, `if_match` |
|
||||
| List collaborations | `BOX_LIST_FILE_COLLABORATIONS` | `file_id` |
|
||||
| Update collaboration | `BOX_UPDATE_COLLABORATION` | `collaboration_id`, `role` |
|
||||
| Get collaboration | `BOX_GET_COLLABORATION` | `collaboration_id` |
|
||||
| Query by metadata | `BOX_QUERY_FILES_FOLDERS_BY_METADATA` | `from`, `ancestor_folder_id`, `query` |
|
||||
| List collections | `BOX_LIST_ALL_COLLECTIONS` | (none) |
|
||||
| List collection items | `BOX_LIST_COLLECTION_ITEMS` | `collection_id` |
|
||||
| List sign requests | `BOX_LIST_BOX_SIGN_REQUESTS` | `limit`, `marker` |
|
||||
| Get sign request | `BOX_GET_BOX_SIGN_REQUEST_BY_ID` | `sign_request_id` |
|
||||
| Cancel sign request | `BOX_CANCEL_BOX_SIGN_REQUEST` | `sign_request_id` |
|
||||
| Recent items | `BOX_LIST_RECENTLY_ACCESSED_ITEMS` | (none) |
|
||||
| Create zip download | `BOX_CREATE_ZIP_DOWNLOAD` | item IDs |
|
||||
@@ -1,197 +0,0 @@
|
||||
---
|
||||
name: brevo-automation
|
||||
description: "Automate Brevo (Sendinblue) tasks via Rube MCP (Composio): manage email campaigns, create/edit templates, track senders, and monitor campaign performance. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Brevo Automation via Rube MCP
|
||||
|
||||
Automate Brevo (formerly Sendinblue) email marketing operations through Composio's Brevo toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Brevo connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `brevo`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `brevo`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Brevo authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Manage Email Campaigns
|
||||
|
||||
**When to use**: User wants to list, review, or update email campaigns
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BREVO_LIST_EMAIL_CAMPAIGNS` - List all campaigns with filters [Required]
|
||||
2. `BREVO_UPDATE_EMAIL_CAMPAIGN` - Update campaign content or settings [Optional]
|
||||
|
||||
**Key parameters for listing**:
|
||||
- `type`: Campaign type ('classic' or 'trigger')
|
||||
- `status`: Campaign status ('suspended', 'archive', 'sent', 'queued', 'draft', 'inProcess', 'inReview')
|
||||
- `startDate`/`endDate`: Date range filter (YYYY-MM-DDTHH:mm:ss.SSSZ format)
|
||||
- `statistics`: Stats type to include ('globalStats', 'linksStats', 'statsByDomain')
|
||||
- `limit`: Results per page (max 100, default 50)
|
||||
- `offset`: Pagination offset
|
||||
- `sort`: Sort order ('asc' or 'desc')
|
||||
- `excludeHtmlContent`: Set `true` to reduce response size
|
||||
|
||||
**Key parameters for update**:
|
||||
- `campaign_id`: Numeric campaign ID (required)
|
||||
- `name`: Campaign name
|
||||
- `subject`: Email subject line
|
||||
- `htmlContent`: HTML email body (mutually exclusive with `htmlUrl`)
|
||||
- `htmlUrl`: URL to HTML content
|
||||
- `sender`: Sender object with `name`, `email`, or `id`
|
||||
- `recipients`: Object with `listIds` and `exclusionListIds`
|
||||
- `scheduledAt`: Scheduled send time (YYYY-MM-DDTHH:mm:ss.SSSZ)
|
||||
|
||||
**Pitfalls**:
|
||||
- `startDate` and `endDate` are mutually required; provide both or neither
|
||||
- Date filters only work when `status` is not passed or set to 'sent'
|
||||
- `htmlContent` and `htmlUrl` are mutually exclusive
|
||||
- Campaign `sender` email must be a verified sender in Brevo
|
||||
- A/B testing fields (`subjectA`, `subjectB`, `splitRule`, `winnerCriteria`) require `abTesting: true`
|
||||
- `scheduledAt` uses full ISO 8601 format with timezone
|
||||
|
||||
### 2. Create and Manage Email Templates
|
||||
|
||||
**When to use**: User wants to create, edit, list, or delete email templates
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BREVO_GET_ALL_EMAIL_TEMPLATES` - List all templates [Required]
|
||||
2. `BREVO_CREATE_OR_UPDATE_EMAIL_TEMPLATE` - Create a new template or update existing [Required]
|
||||
3. `BREVO_DELETE_EMAIL_TEMPLATE` - Delete an inactive template [Optional]
|
||||
|
||||
**Key parameters for listing**:
|
||||
- `templateStatus`: Filter active (`true`) or inactive (`false`) templates
|
||||
- `limit`: Results per page (max 1000, default 50)
|
||||
- `offset`: Pagination offset
|
||||
- `sort`: Sort order ('asc' or 'desc')
|
||||
|
||||
**Key parameters for create/update**:
|
||||
- `templateId`: Include to update; omit to create new
|
||||
- `templateName`: Template display name (required for creation)
|
||||
- `subject`: Email subject line (required for creation)
|
||||
- `htmlContent`: HTML template body (min 10 characters; use this or `htmlUrl`)
|
||||
- `sender`: Sender object with `name` and `email`, or `id` (required for creation)
|
||||
- `replyTo`: Reply-to email address
|
||||
- `isActive`: Activate or deactivate the template
|
||||
- `tag`: Category tag for the template
|
||||
|
||||
**Pitfalls**:
|
||||
- When `templateId` is provided, the tool updates; when omitted, it creates
|
||||
- For creation, `templateName`, `subject`, and `sender` are required
|
||||
- `htmlContent` must be at least 10 characters
|
||||
- Template personalization uses `{{contact.ATTRIBUTE}}` syntax
|
||||
- Only inactive templates can be deleted
|
||||
- `htmlContent` and `htmlUrl` are mutually exclusive
|
||||
|
||||
### 3. Manage Senders
|
||||
|
||||
**When to use**: User wants to view authorized sender identities
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BREVO_GET_ALL_SENDERS` - List all verified senders [Required]
|
||||
|
||||
**Key parameters**: (none required)
|
||||
|
||||
**Pitfalls**:
|
||||
- Senders must be verified before they can be used in campaigns or templates
|
||||
- Sender verification is done through the Brevo web interface, not via API
|
||||
- Sender IDs can be used in `sender.id` fields for campaigns and templates
|
||||
|
||||
### 4. Configure A/B Testing Campaigns
|
||||
|
||||
**When to use**: User wants to set up or modify A/B test settings on a campaign
|
||||
|
||||
**Tool sequence**:
|
||||
1. `BREVO_LIST_EMAIL_CAMPAIGNS` - Find the target campaign [Prerequisite]
|
||||
2. `BREVO_UPDATE_EMAIL_CAMPAIGN` - Configure A/B test settings [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `campaign_id`: Campaign to configure
|
||||
- `abTesting`: Set to `true` to enable A/B testing
|
||||
- `subjectA`: Subject line for variant A
|
||||
- `subjectB`: Subject line for variant B
|
||||
- `splitRule`: Percentage split for the test (1-99)
|
||||
- `winnerCriteria`: 'open' or 'click' for determining the winner
|
||||
- `winnerDelay`: Hours to wait before selecting winner (1-168)
|
||||
|
||||
**Pitfalls**:
|
||||
- A/B testing must be enabled (`abTesting: true`) before setting variant fields
|
||||
- `splitRule` is the percentage of contacts that receive variant A
|
||||
- `winnerDelay` defines how long to test before sending the winner to remaining contacts
|
||||
- Only works with 'classic' campaign type
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Campaign Lifecycle
|
||||
|
||||
```
|
||||
1. Create campaign (status: draft)
|
||||
2. Set recipients (listIds)
|
||||
3. Configure content (htmlContent or htmlUrl)
|
||||
4. Optionally schedule (scheduledAt)
|
||||
5. Send or schedule via Brevo UI (API update can set scheduledAt)
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Use `limit` (page size) and `offset` (starting index)
|
||||
- Default limit is 50; max varies by endpoint (100 for campaigns, 1000 for templates)
|
||||
- Increment `offset` by `limit` each page
|
||||
- Check `count` in response to determine total available
|
||||
|
||||
### Template Personalization
|
||||
|
||||
```
|
||||
- First name: {{contact.FIRSTNAME}}
|
||||
- Last name: {{contact.LASTNAME}}
|
||||
- Custom attribute: {{contact.CUSTOM_ATTRIBUTE}}
|
||||
- Mirror link: {{mirror}}
|
||||
- Unsubscribe link: {{unsubscribe}}
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Date Formats**:
|
||||
- All dates use ISO 8601 with milliseconds: YYYY-MM-DDTHH:mm:ss.SSSZ
|
||||
- Pass timezone in the date-time format for accurate results
|
||||
- `startDate` and `endDate` must be used together
|
||||
|
||||
**Sender Verification**:
|
||||
- All sender emails must be verified in Brevo before use
|
||||
- Unverified senders cause campaign creation/update failures
|
||||
- Use GET_ALL_SENDERS to check available verified senders
|
||||
|
||||
**Rate Limits**:
|
||||
- Brevo API has rate limits per account plan
|
||||
- Implement backoff on 429 responses
|
||||
- Template operations have lower limits than read operations
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` or `data.data`
|
||||
- Parse defensively with fallback patterns
|
||||
- Campaign and template IDs are numeric integers
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List campaigns | BREVO_LIST_EMAIL_CAMPAIGNS | type, status, limit, offset |
|
||||
| Update campaign | BREVO_UPDATE_EMAIL_CAMPAIGN | campaign_id, subject, htmlContent |
|
||||
| List templates | BREVO_GET_ALL_EMAIL_TEMPLATES | templateStatus, limit, offset |
|
||||
| Create template | BREVO_CREATE_OR_UPDATE_EMAIL_TEMPLATE | templateName, subject, htmlContent, sender |
|
||||
| Update template | BREVO_CREATE_OR_UPDATE_EMAIL_TEMPLATE | templateId, htmlContent |
|
||||
| Delete template | BREVO_DELETE_EMAIL_TEMPLATE | templateId |
|
||||
| List senders | BREVO_GET_ALL_SENDERS | (none) |
|
||||
@@ -1,203 +0,0 @@
|
||||
---
|
||||
name: cal-com-automation
|
||||
description: "Automate Cal.com tasks via Rube MCP (Composio): manage bookings, check availability, configure webhooks, and handle teams. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Cal.com Automation via Rube MCP
|
||||
|
||||
Automate Cal.com scheduling operations through Composio's Cal toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Cal.com connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `cal`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `cal`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Cal.com authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Manage Bookings
|
||||
|
||||
**When to use**: User wants to list, create, or review bookings
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CAL_FETCH_ALL_BOOKINGS` - List all bookings with filters [Required]
|
||||
2. `CAL_POST_NEW_BOOKING_REQUEST` - Create a new booking [Optional]
|
||||
|
||||
**Key parameters for listing**:
|
||||
- `status`: Filter by booking status ('upcoming', 'recurring', 'past', 'cancelled', 'unconfirmed')
|
||||
- `afterStart`: Filter bookings after this date (ISO 8601)
|
||||
- `beforeEnd`: Filter bookings before this date (ISO 8601)
|
||||
|
||||
**Key parameters for creation**:
|
||||
- `eventTypeId`: Event type ID for the booking
|
||||
- `start`: Booking start time (ISO 8601)
|
||||
- `end`: Booking end time (ISO 8601)
|
||||
- `name`: Attendee name
|
||||
- `email`: Attendee email
|
||||
- `timeZone`: Attendee timezone (IANA format)
|
||||
- `language`: Attendee language code
|
||||
- `metadata`: Additional metadata object
|
||||
|
||||
**Pitfalls**:
|
||||
- Date filters use ISO 8601 format with timezone (e.g., '2024-01-15T09:00:00Z')
|
||||
- `eventTypeId` must reference a valid, active event type
|
||||
- Booking creation requires matching an available slot; check availability first
|
||||
- Time zone must be a valid IANA timezone string (e.g., 'America/New_York')
|
||||
- Status filter values are specific strings; invalid values return empty results
|
||||
|
||||
### 2. Check Availability
|
||||
|
||||
**When to use**: User wants to find free/busy times or available booking slots
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CAL_RETRIEVE_CALENDAR_BUSY_TIMES` - Get busy time blocks [Required]
|
||||
2. `CAL_GET_AVAILABLE_SLOTS_INFO` - Get specific available slots [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `dateFrom`: Start date for availability check (YYYY-MM-DD)
|
||||
- `dateTo`: End date for availability check (YYYY-MM-DD)
|
||||
- `eventTypeId`: Event type to check slots for
|
||||
- `timeZone`: Timezone for the availability response
|
||||
- `loggedInUsersTz`: Timezone of the requesting user
|
||||
|
||||
**Pitfalls**:
|
||||
- Busy times show when the user is NOT available
|
||||
- Available slots are specific to an event type's duration and configuration
|
||||
- Date range should be reasonable (not months in advance) to get accurate results
|
||||
- Timezone affects how slots are displayed; always specify explicitly
|
||||
- Availability reflects calendar integrations (Google Calendar, Outlook, etc.)
|
||||
|
||||
### 3. Configure Webhooks
|
||||
|
||||
**When to use**: User wants to set up or manage webhook notifications for booking events
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CAL_RETRIEVE_WEBHOOKS_LIST` - List existing webhooks [Required]
|
||||
2. `CAL_GET_WEBHOOK_BY_ID` - Get specific webhook details [Optional]
|
||||
3. `CAL_UPDATE_WEBHOOK_BY_ID` - Update webhook configuration [Optional]
|
||||
4. `CAL_DELETE_WEBHOOK_BY_ID` - Remove a webhook [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `id`: Webhook ID for GET/UPDATE/DELETE operations
|
||||
- `subscriberUrl`: Webhook endpoint URL
|
||||
- `eventTriggers`: Array of event types to trigger on
|
||||
- `active`: Whether the webhook is active
|
||||
- `secret`: Webhook signing secret
|
||||
|
||||
**Pitfalls**:
|
||||
- Webhook URLs must be publicly accessible HTTPS endpoints
|
||||
- Event triggers include: 'BOOKING_CREATED', 'BOOKING_RESCHEDULED', 'BOOKING_CANCELLED', etc.
|
||||
- Inactive webhooks do not fire; toggle `active` to enable/disable
|
||||
- Webhook secrets are used for payload signature verification
|
||||
|
||||
### 4. Manage Teams
|
||||
|
||||
**When to use**: User wants to create, view, or manage teams and team event types
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CAL_GET_TEAMS_LIST` - List all teams [Required]
|
||||
2. `CAL_GET_TEAM_INFORMATION_BY_TEAM_ID` - Get specific team details [Optional]
|
||||
3. `CAL_CREATE_TEAM_IN_ORGANIZATION` - Create a new team [Optional]
|
||||
4. `CAL_RETRIEVE_TEAM_EVENT_TYPES` - List event types for a team [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `teamId`: Team identifier
|
||||
- `name`: Team name (for creation)
|
||||
- `slug`: URL-friendly team identifier
|
||||
|
||||
**Pitfalls**:
|
||||
- Team creation may require organization-level permissions
|
||||
- Team event types are separate from personal event types
|
||||
- Team slugs must be URL-safe and unique within the organization
|
||||
|
||||
### 5. Organization Management
|
||||
|
||||
**When to use**: User wants to view organization details
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CAL_GET_ORGANIZATION_ID` - Get the organization ID [Required]
|
||||
|
||||
**Key parameters**: (none required)
|
||||
|
||||
**Pitfalls**:
|
||||
- Organization ID is needed for team creation and org-level operations
|
||||
- Not all Cal.com accounts have organizations; personal plans may return errors
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Booking Creation Flow
|
||||
|
||||
```
|
||||
1. Call CAL_GET_AVAILABLE_SLOTS_INFO to find open slots
|
||||
2. Present available times to the user
|
||||
3. Call CAL_POST_NEW_BOOKING_REQUEST with selected slot
|
||||
4. Confirm booking creation response
|
||||
```
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Team name -> Team ID**:
|
||||
```
|
||||
1. Call CAL_GET_TEAMS_LIST
|
||||
2. Find team by name in response
|
||||
3. Extract id field
|
||||
```
|
||||
|
||||
### Webhook Setup
|
||||
|
||||
```
|
||||
1. Call CAL_RETRIEVE_WEBHOOKS_LIST to check existing hooks
|
||||
2. Create or update webhook with desired triggers
|
||||
3. Verify webhook fires on test booking
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Date/Time Formats**:
|
||||
- Booking times: ISO 8601 with timezone (e.g., '2024-01-15T09:00:00Z')
|
||||
- Availability dates: YYYY-MM-DD format
|
||||
- Always specify timezone explicitly to avoid confusion
|
||||
|
||||
**Event Types**:
|
||||
- Event type IDs are numeric integers
|
||||
- Event types define duration, location, and booking rules
|
||||
- Disabled event types cannot accept new bookings
|
||||
|
||||
**Permissions**:
|
||||
- Team operations require team membership or admin access
|
||||
- Organization operations require org-level permissions
|
||||
- Webhook management requires appropriate access level
|
||||
|
||||
**Rate Limits**:
|
||||
- Cal.com API has rate limits per API key
|
||||
- Implement backoff on 429 responses
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List bookings | CAL_FETCH_ALL_BOOKINGS | status, afterStart, beforeEnd |
|
||||
| Create booking | CAL_POST_NEW_BOOKING_REQUEST | eventTypeId, start, end, name, email |
|
||||
| Get busy times | CAL_RETRIEVE_CALENDAR_BUSY_TIMES | dateFrom, dateTo |
|
||||
| Get available slots | CAL_GET_AVAILABLE_SLOTS_INFO | eventTypeId, dateFrom, dateTo |
|
||||
| List webhooks | CAL_RETRIEVE_WEBHOOKS_LIST | (none) |
|
||||
| Get webhook | CAL_GET_WEBHOOK_BY_ID | id |
|
||||
| Update webhook | CAL_UPDATE_WEBHOOK_BY_ID | id, subscriberUrl, eventTriggers |
|
||||
| Delete webhook | CAL_DELETE_WEBHOOK_BY_ID | id |
|
||||
| List teams | CAL_GET_TEAMS_LIST | (none) |
|
||||
| Get team | CAL_GET_TEAM_INFORMATION_BY_TEAM_ID | teamId |
|
||||
| Create team | CAL_CREATE_TEAM_IN_ORGANIZATION | name, slug |
|
||||
| Team event types | CAL_RETRIEVE_TEAM_EVENT_TYPES | teamId |
|
||||
| Get org ID | CAL_GET_ORGANIZATION_ID | (none) |
|
||||
@@ -1,211 +0,0 @@
|
||||
---
|
||||
name: calendly-automation
|
||||
description: "Automate Calendly scheduling, event management, invitee tracking, availability checks, and organization administration via Rube MCP (Composio). Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Calendly Automation via Rube MCP
|
||||
|
||||
Automate Calendly operations including event listing, invitee management, scheduling link creation, availability queries, and organization administration through Composio's Calendly toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Calendly connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `calendly`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
- Many operations require the user's Calendly URI, obtained via `CALENDLY_GET_CURRENT_USER`
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `calendly`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Calendly OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. List and View Scheduled Events
|
||||
|
||||
**When to use**: User wants to see their upcoming, past, or filtered Calendly events
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CALENDLY_GET_CURRENT_USER` - Get authenticated user URI and organization URI [Prerequisite]
|
||||
2. `CALENDLY_LIST_EVENTS` - List events scoped by user, organization, or group [Required]
|
||||
3. `CALENDLY_GET_EVENT` - Get detailed info for a specific event by UUID [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `user`: Full Calendly API URI (e.g., `https://api.calendly.com/users/{uuid}`) - NOT `"me"`
|
||||
- `organization`: Full organization URI for org-scoped queries
|
||||
- `status`: `"active"` or `"canceled"`
|
||||
- `min_start_time` / `max_start_time`: UTC timestamps (e.g., `2024-01-01T00:00:00.000000Z`)
|
||||
- `invitee_email`: Filter events by invitee email (filter only, not a scope)
|
||||
- `sort`: `"start_time:asc"` or `"start_time:desc"`
|
||||
- `count`: Results per page (default 20)
|
||||
- `page_token`: Pagination token from previous response
|
||||
|
||||
**Pitfalls**:
|
||||
- Exactly ONE of `user`, `organization`, or `group` must be provided - omitting or combining scopes fails
|
||||
- The `user` parameter requires the full API URI, not `"me"` - use `CALENDLY_GET_CURRENT_USER` first
|
||||
- `invitee_email` is a filter, not a scope; you still need one of user/organization/group
|
||||
- Pagination uses `count` + `page_token`; loop until `page_token` is absent for complete results
|
||||
- Admin rights may be needed for organization or group scope queries
|
||||
|
||||
### 2. Manage Event Invitees
|
||||
|
||||
**When to use**: User wants to see who is booked for events or get invitee details
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CALENDLY_LIST_EVENTS` - Find the target event(s) [Prerequisite]
|
||||
2. `CALENDLY_LIST_EVENT_INVITEES` - List all invitees for a specific event [Required]
|
||||
3. `CALENDLY_GET_EVENT_INVITEE` - Get detailed info for a single invitee [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `uuid`: Event UUID (for `LIST_EVENT_INVITEES`)
|
||||
- `event_uuid` + `invitee_uuid`: Both required for `GET_EVENT_INVITEE`
|
||||
- `email`: Filter invitees by email address
|
||||
- `status`: `"active"` or `"canceled"`
|
||||
- `sort`: `"created_at:asc"` or `"created_at:desc"`
|
||||
- `count`: Results per page (default 20)
|
||||
|
||||
**Pitfalls**:
|
||||
- The `uuid` parameter for `CALENDLY_LIST_EVENT_INVITEES` is the event UUID, not the invitee UUID
|
||||
- Paginate using `page_token` until absent for complete invitee lists
|
||||
- Canceled invitees are excluded by default; use `status: "canceled"` to see them
|
||||
|
||||
### 3. Create Scheduling Links and Check Availability
|
||||
|
||||
**When to use**: User wants to generate a booking link or check available time slots
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CALENDLY_GET_CURRENT_USER` - Get user URI [Prerequisite]
|
||||
2. `CALENDLY_LIST_USER_S_EVENT_TYPES` - List available event types [Required]
|
||||
3. `CALENDLY_LIST_EVENT_TYPE_AVAILABLE_TIMES` - Check available slots for an event type [Optional]
|
||||
4. `CALENDLY_CREATE_SCHEDULING_LINK` - Generate a single-use scheduling link [Required]
|
||||
5. `CALENDLY_LIST_USER_AVAILABILITY_SCHEDULES` - View user's availability schedules [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `owner`: Event type URI (e.g., `https://api.calendly.com/event_types/{uuid}`)
|
||||
- `owner_type`: `"EventType"` (default)
|
||||
- `max_event_count`: Must be exactly `1` for single-use links
|
||||
- `start_time` / `end_time`: UTC timestamps for availability queries (max 7-day range)
|
||||
- `active`: Boolean to filter active/inactive event types
|
||||
- `user`: User URI for event type listing
|
||||
|
||||
**Pitfalls**:
|
||||
- `CALENDLY_CREATE_SCHEDULING_LINK` can return 403 if token lacks rights or owner URI is invalid
|
||||
- `CALENDLY_LIST_EVENT_TYPE_AVAILABLE_TIMES` requires UTC timestamps and max 7-day range; split longer searches
|
||||
- Available times results are NOT paginated - all results returned in one response
|
||||
- Event type URIs must be full API URIs (e.g., `https://api.calendly.com/event_types/...`)
|
||||
|
||||
### 4. Cancel Events
|
||||
|
||||
**When to use**: User wants to cancel a scheduled Calendly event
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CALENDLY_LIST_EVENTS` - Find the event to cancel [Prerequisite]
|
||||
2. `CALENDLY_GET_EVENT` - Confirm event details before cancellation [Prerequisite]
|
||||
3. `CALENDLY_LIST_EVENT_INVITEES` - Check who will be affected [Optional]
|
||||
4. `CALENDLY_CANCEL_EVENT` - Cancel the event [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `uuid`: Event UUID to cancel
|
||||
- `reason`: Optional cancellation reason (may be included in notification to invitees)
|
||||
|
||||
**Pitfalls**:
|
||||
- Cancellation is IRREVERSIBLE - always confirm with the user before calling
|
||||
- Cancellation may trigger notifications to invitees
|
||||
- Only active events can be canceled; already-canceled events return errors
|
||||
- Get explicit user confirmation before executing `CALENDLY_CANCEL_EVENT`
|
||||
|
||||
### 5. Manage Organization and Invitations
|
||||
|
||||
**When to use**: User wants to invite members, manage organization, or handle org invitations
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CALENDLY_GET_CURRENT_USER` - Get user and organization context [Prerequisite]
|
||||
2. `CALENDLY_GET_ORGANIZATION` - Get organization details [Optional]
|
||||
3. `CALENDLY_LIST_ORGANIZATION_INVITATIONS` - Check existing invitations [Optional]
|
||||
4. `CALENDLY_CREATE_ORGANIZATION_INVITATION` - Send an org invitation [Required]
|
||||
5. `CALENDLY_REVOKE_USER_S_ORGANIZATION_INVITATION` - Revoke a pending invitation [Optional]
|
||||
6. `CALENDLY_REMOVE_USER_FROM_ORGANIZATION` - Remove a member [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `uuid`: Organization UUID
|
||||
- `email`: Email address of user to invite
|
||||
- `status`: Filter invitations by `"pending"`, `"accepted"`, or `"declined"`
|
||||
|
||||
**Pitfalls**:
|
||||
- Only org owners/admins can manage invitations and removals; others get authorization errors
|
||||
- Duplicate active invitations for the same email are rejected - check existing invitations first
|
||||
- Organization owners cannot be removed via `CALENDLY_REMOVE_USER_FROM_ORGANIZATION`
|
||||
- Invitation statuses include pending, accepted, declined, and revoked - handle each appropriately
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
Calendly uses full API URIs as identifiers, not simple IDs:
|
||||
- **Current user URI**: `CALENDLY_GET_CURRENT_USER` returns `resource.uri` (e.g., `https://api.calendly.com/users/{uuid}`)
|
||||
- **Organization URI**: Found in current user response at `resource.current_organization`
|
||||
- **Event UUID**: Extract from event URI or list responses
|
||||
- **Event type URI**: From `CALENDLY_LIST_USER_S_EVENT_TYPES` response
|
||||
|
||||
Important: Never use `"me"` as a user parameter in list/filter endpoints. Always resolve to the full URI first.
|
||||
|
||||
### Pagination
|
||||
Most Calendly list endpoints use token-based pagination:
|
||||
- Set `count` for page size (default 20)
|
||||
- Follow `page_token` from `pagination.next_page_token` until absent
|
||||
- Sort with `field:direction` format (e.g., `start_time:asc`, `created_at:desc`)
|
||||
|
||||
### Time Handling
|
||||
- All timestamps must be in UTC format: `yyyy-MM-ddTHH:mm:ss.ffffffZ`
|
||||
- Use `min_start_time` / `max_start_time` for date range filtering on events
|
||||
- Available times queries have a maximum 7-day range; split longer searches into multiple calls
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
### URI Formats
|
||||
- All entity references use full Calendly API URIs (e.g., `https://api.calendly.com/users/{uuid}`)
|
||||
- Never pass bare UUIDs where URIs are expected, and never pass `"me"` to list endpoints
|
||||
- Extract UUIDs from URIs when tools expect UUID parameters (e.g., `CALENDLY_GET_EVENT`)
|
||||
|
||||
### Scope Requirements
|
||||
- `CALENDLY_LIST_EVENTS` requires exactly one scope (user, organization, or group) - no more, no less
|
||||
- Organization/group scoped queries may require admin privileges
|
||||
- Token scope determines which operations are available; 403 errors indicate insufficient permissions
|
||||
|
||||
### Data Relationships
|
||||
- Events have invitees (attendees who booked)
|
||||
- Event types define scheduling pages (duration, availability rules)
|
||||
- Organizations contain users and groups
|
||||
- Scheduling links are tied to event types, not directly to events
|
||||
|
||||
### Rate Limits
|
||||
- Calendly API has rate limits; avoid tight loops over large datasets
|
||||
- Paginate responsibly and add delays for batch operations
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Get current user | `CALENDLY_GET_CURRENT_USER` | (none) |
|
||||
| Get user by UUID | `CALENDLY_GET_USER` | `uuid` |
|
||||
| List events | `CALENDLY_LIST_EVENTS` | `user`, `status`, `min_start_time` |
|
||||
| Get event details | `CALENDLY_GET_EVENT` | `uuid` |
|
||||
| Cancel event | `CALENDLY_CANCEL_EVENT` | `uuid`, `reason` |
|
||||
| List invitees | `CALENDLY_LIST_EVENT_INVITEES` | `uuid`, `status`, `email` |
|
||||
| Get invitee | `CALENDLY_GET_EVENT_INVITEE` | `event_uuid`, `invitee_uuid` |
|
||||
| List event types | `CALENDLY_LIST_USER_S_EVENT_TYPES` | `user`, `active` |
|
||||
| Get event type | `CALENDLY_GET_EVENT_TYPE` | `uuid` |
|
||||
| Check availability | `CALENDLY_LIST_EVENT_TYPE_AVAILABLE_TIMES` | event type URI, `start_time`, `end_time` |
|
||||
| Create scheduling link | `CALENDLY_CREATE_SCHEDULING_LINK` | `owner`, `max_event_count` |
|
||||
| List availability schedules | `CALENDLY_LIST_USER_AVAILABILITY_SCHEDULES` | user URI |
|
||||
| Get organization | `CALENDLY_GET_ORGANIZATION` | `uuid` |
|
||||
| Invite to org | `CALENDLY_CREATE_ORGANIZATION_INVITATION` | `uuid`, `email` |
|
||||
| List org invitations | `CALENDLY_LIST_ORGANIZATION_INVITATIONS` | `uuid`, `status` |
|
||||
| Revoke org invitation | `CALENDLY_REVOKE_USER_S_ORGANIZATION_INVITATION` | org UUID, invitation UUID |
|
||||
| Remove from org | `CALENDLY_REMOVE_USER_FROM_ORGANIZATION` | membership UUID |
|
||||
@@ -1,217 +0,0 @@
|
||||
---
|
||||
name: canva-automation
|
||||
description: "Automate Canva tasks via Rube MCP (Composio): designs, exports, folders, brand templates, autofill. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Canva Automation via Rube MCP
|
||||
|
||||
Automate Canva design operations through Composio's Canva toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Canva connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `canva`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `canva`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Canva OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. List and Browse Designs
|
||||
|
||||
**When to use**: User wants to find existing designs or browse their Canva library
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CANVA_LIST_USER_DESIGNS` - List all designs with optional filters [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: Search term to filter designs by name
|
||||
- `continuation`: Pagination token from previous response
|
||||
- `ownership`: Filter by 'owned', 'shared', or 'any'
|
||||
- `sort_by`: Sort field (e.g., 'modified_at', 'title')
|
||||
|
||||
**Pitfalls**:
|
||||
- Results are paginated; follow `continuation` token until absent
|
||||
- Deleted designs may still appear briefly; check design status
|
||||
- Search is substring-based, not fuzzy matching
|
||||
|
||||
### 2. Create and Design
|
||||
|
||||
**When to use**: User wants to create a new Canva design from scratch or from a template
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CANVA_ACCESS_USER_SPECIFIC_BRAND_TEMPLATES_LIST` - Browse available brand templates [Optional]
|
||||
2. `CANVA_CREATE_CANVA_DESIGN_WITH_OPTIONAL_ASSET` - Create a new design [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `design_type`: Type of design (e.g., 'Presentation', 'Poster', 'SocialMedia')
|
||||
- `title`: Name for the new design
|
||||
- `asset_id`: Optional asset to include in the design
|
||||
- `width` / `height`: Custom dimensions in pixels
|
||||
|
||||
**Pitfalls**:
|
||||
- Design type must match Canva's predefined types exactly
|
||||
- Custom dimensions have minimum and maximum limits
|
||||
- Asset must be uploaded first via CANVA_CREATE_ASSET_UPLOAD_JOB before referencing
|
||||
|
||||
### 3. Upload Assets
|
||||
|
||||
**When to use**: User wants to upload images or files to Canva for use in designs
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CANVA_CREATE_ASSET_UPLOAD_JOB` - Initiate the asset upload [Required]
|
||||
2. `CANVA_FETCH_ASSET_UPLOAD_JOB_STATUS` - Poll until upload completes [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Display name for the asset
|
||||
- `url`: Public URL of the file to upload (for URL-based uploads)
|
||||
- `job_id`: Upload job ID returned from step 1 (for status polling)
|
||||
|
||||
**Pitfalls**:
|
||||
- Upload is asynchronous; you MUST poll the job status until it completes
|
||||
- Supported formats include PNG, JPG, SVG, MP4, GIF
|
||||
- File size limits apply; large files may take longer to process
|
||||
- The `job_id` from CREATE returns the ID needed for status polling
|
||||
- Status values: 'in_progress', 'success', 'failed'
|
||||
|
||||
### 4. Export Designs
|
||||
|
||||
**When to use**: User wants to download or export a Canva design as PDF, PNG, or other format
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CANVA_LIST_USER_DESIGNS` - Find the design to export [Prerequisite]
|
||||
2. `CANVA_CREATE_CANVA_DESIGN_EXPORT_JOB` - Start the export process [Required]
|
||||
3. `CANVA_GET_DESIGN_EXPORT_JOB_RESULT` - Poll until export completes and get download URL [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `design_id`: ID of the design to export
|
||||
- `format`: Export format ('pdf', 'png', 'jpg', 'svg', 'mp4', 'gif', 'pptx')
|
||||
- `pages`: Specific page numbers to export (array)
|
||||
- `quality`: Export quality ('regular', 'high')
|
||||
- `job_id`: Export job ID for polling status
|
||||
|
||||
**Pitfalls**:
|
||||
- Export is asynchronous; you MUST poll the job result until it completes
|
||||
- Download URLs from completed exports expire after a limited time
|
||||
- Large designs with many pages take longer to export
|
||||
- Not all formats support all design types (e.g., MP4 only for animations)
|
||||
- Poll interval: wait 2-3 seconds between status checks
|
||||
|
||||
### 5. Organize with Folders
|
||||
|
||||
**When to use**: User wants to create folders or organize designs into folders
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CANVA_POST_FOLDERS` - Create a new folder [Required]
|
||||
2. `CANVA_MOVE_ITEM_TO_SPECIFIED_FOLDER` - Move designs into folders [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Folder name
|
||||
- `parent_folder_id`: Parent folder for nested organization
|
||||
- `item_id`: ID of the design or asset to move
|
||||
- `folder_id`: Target folder ID
|
||||
|
||||
**Pitfalls**:
|
||||
- Folder names must be unique within the same parent folder
|
||||
- Moving items between folders updates their location immediately
|
||||
- Root-level folders have no parent_folder_id
|
||||
|
||||
### 6. Autofill from Brand Templates
|
||||
|
||||
**When to use**: User wants to generate designs by filling brand template placeholders with data
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CANVA_ACCESS_USER_SPECIFIC_BRAND_TEMPLATES_LIST` - List available brand templates [Required]
|
||||
2. `CANVA_INITIATE_CANVA_DESIGN_AUTOFILL_JOB` - Start autofill with data [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `brand_template_id`: ID of the brand template to use
|
||||
- `title`: Title for the generated design
|
||||
- `data`: Key-value mapping of placeholder names to replacement values
|
||||
|
||||
**Pitfalls**:
|
||||
- Template placeholders must match exactly (case-sensitive)
|
||||
- Autofill is asynchronous; poll for completion
|
||||
- Only brand templates support autofill, not regular designs
|
||||
- Data values must match the expected type for each placeholder (text, image URL)
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Async Job Pattern
|
||||
|
||||
Many Canva operations are asynchronous:
|
||||
```
|
||||
1. Initiate job (upload, export, autofill) -> get job_id
|
||||
2. Poll status endpoint with job_id every 2-3 seconds
|
||||
3. Check for 'success' or 'failed' status
|
||||
4. On success, extract result (asset_id, download_url, design_id)
|
||||
```
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Design name -> Design ID**:
|
||||
```
|
||||
1. Call CANVA_LIST_USER_DESIGNS with query=design_name
|
||||
2. Find matching design in results
|
||||
3. Extract id field
|
||||
```
|
||||
|
||||
**Brand template name -> Template ID**:
|
||||
```
|
||||
1. Call CANVA_ACCESS_USER_SPECIFIC_BRAND_TEMPLATES_LIST
|
||||
2. Find template by name
|
||||
3. Extract brand_template_id
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Check response for `continuation` token
|
||||
- Pass token in next request's `continuation` parameter
|
||||
- Continue until `continuation` is absent or empty
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Async Operations**:
|
||||
- Uploads, exports, and autofills are all asynchronous
|
||||
- Always poll job status; do not assume immediate completion
|
||||
- Download URLs from exports expire; use them promptly
|
||||
|
||||
**Asset Management**:
|
||||
- Assets must be uploaded before they can be used in designs
|
||||
- Upload job must reach 'success' status before the asset_id is valid
|
||||
- Supported formats vary; check Canva documentation for current limits
|
||||
|
||||
**Rate Limits**:
|
||||
- Canva API has rate limits per endpoint
|
||||
- Implement exponential backoff for bulk operations
|
||||
- Batch operations where possible to reduce API calls
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` key
|
||||
- Job status responses include different fields based on completion state
|
||||
- Parse defensively with fallbacks for optional fields
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List designs | CANVA_LIST_USER_DESIGNS | query, continuation |
|
||||
| Create design | CANVA_CREATE_CANVA_DESIGN_WITH_OPTIONAL_ASSET | design_type, title |
|
||||
| Upload asset | CANVA_CREATE_ASSET_UPLOAD_JOB | name, url |
|
||||
| Check upload | CANVA_FETCH_ASSET_UPLOAD_JOB_STATUS | job_id |
|
||||
| Export design | CANVA_CREATE_CANVA_DESIGN_EXPORT_JOB | design_id, format |
|
||||
| Get export | CANVA_GET_DESIGN_EXPORT_JOB_RESULT | job_id |
|
||||
| Create folder | CANVA_POST_FOLDERS | name, parent_folder_id |
|
||||
| Move to folder | CANVA_MOVE_ITEM_TO_SPECIFIED_FOLDER | item_id, folder_id |
|
||||
| List templates | CANVA_ACCESS_USER_SPECIFIC_BRAND_TEMPLATES_LIST | (none) |
|
||||
| Autofill template | CANVA_INITIATE_CANVA_DESIGN_AUTOFILL_JOB | brand_template_id, data |
|
||||
@@ -1,177 +0,0 @@
|
||||
---
|
||||
name: circleci-automation
|
||||
description: "Automate CircleCI tasks via Rube MCP (Composio): trigger pipelines, monitor workflows/jobs, retrieve artifacts and test metadata. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# CircleCI Automation via Rube MCP
|
||||
|
||||
Automate CircleCI CI/CD operations through Composio's CircleCI toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active CircleCI connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `circleci`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `circleci`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete CircleCI authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Trigger a Pipeline
|
||||
|
||||
**When to use**: User wants to start a new CI/CD pipeline run
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CIRCLECI_TRIGGER_PIPELINE` - Trigger a new pipeline on a project [Required]
|
||||
2. `CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID` - Monitor resulting workflows [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `project_slug`: Project identifier in format `gh/org/repo` or `bb/org/repo`
|
||||
- `branch`: Git branch to run the pipeline on
|
||||
- `tag`: Git tag to run the pipeline on (mutually exclusive with branch)
|
||||
- `parameters`: Pipeline parameter key-value pairs
|
||||
|
||||
**Pitfalls**:
|
||||
- `project_slug` format is `{vcs}/{org}/{repo}` (e.g., `gh/myorg/myrepo`)
|
||||
- `branch` and `tag` are mutually exclusive; providing both causes an error
|
||||
- Pipeline parameters must match those defined in `.circleci/config.yml`
|
||||
- Triggering returns a pipeline ID; workflows start asynchronously
|
||||
|
||||
### 2. Monitor Pipelines and Workflows
|
||||
|
||||
**When to use**: User wants to check the status of pipelines or workflows
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CIRCLECI_LIST_PIPELINES_FOR_PROJECT` - List recent pipelines for a project [Required]
|
||||
2. `CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID` - List workflows within a pipeline [Required]
|
||||
3. `CIRCLECI_GET_PIPELINE_CONFIG` - View the pipeline configuration used [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `project_slug`: Project identifier in `{vcs}/{org}/{repo}` format
|
||||
- `pipeline_id`: UUID of a specific pipeline
|
||||
- `branch`: Filter pipelines by branch name
|
||||
- `page_token`: Pagination cursor for next page of results
|
||||
|
||||
**Pitfalls**:
|
||||
- Pipeline IDs are UUIDs, not numeric IDs
|
||||
- Workflows inherit the pipeline ID; a single pipeline can have multiple workflows
|
||||
- Workflow states include: success, running, not_run, failed, error, failing, on_hold, canceled, unauthorized
|
||||
- `page_token` is returned in responses for pagination; continue until absent
|
||||
|
||||
### 3. Inspect Job Details
|
||||
|
||||
**When to use**: User wants to drill into a specific job's execution details
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID` - Find workflow containing the job [Prerequisite]
|
||||
2. `CIRCLECI_GET_JOB_DETAILS` - Get detailed job information [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `project_slug`: Project identifier
|
||||
- `job_number`: Numeric job number (not UUID)
|
||||
|
||||
**Pitfalls**:
|
||||
- Job numbers are integers, not UUIDs (unlike pipeline and workflow IDs)
|
||||
- Job details include executor type, parallelism, start/stop times, and status
|
||||
- Job statuses: success, running, not_run, failed, retried, timedout, infrastructure_fail, canceled
|
||||
|
||||
### 4. Retrieve Build Artifacts
|
||||
|
||||
**When to use**: User wants to download or list artifacts produced by a job
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CIRCLECI_GET_JOB_DETAILS` - Confirm job completed successfully [Prerequisite]
|
||||
2. `CIRCLECI_GET_JOB_ARTIFACTS` - List all artifacts from the job [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `project_slug`: Project identifier
|
||||
- `job_number`: Numeric job number
|
||||
|
||||
**Pitfalls**:
|
||||
- Artifacts are only available after job completion
|
||||
- Each artifact has a `path` and `url` for download
|
||||
- Artifact URLs may require authentication headers to download
|
||||
- Large artifacts may have download size limits
|
||||
|
||||
### 5. Review Test Results
|
||||
|
||||
**When to use**: User wants to check test outcomes for a specific job
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CIRCLECI_GET_JOB_DETAILS` - Verify job ran tests [Prerequisite]
|
||||
2. `CIRCLECI_GET_TEST_METADATA` - Retrieve test results and metadata [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `project_slug`: Project identifier
|
||||
- `job_number`: Numeric job number
|
||||
|
||||
**Pitfalls**:
|
||||
- Test metadata requires the job to have uploaded test results (JUnit XML format)
|
||||
- If no test results were uploaded, the response will be empty
|
||||
- Test metadata includes classname, name, result, message, and run_time fields
|
||||
- Failed tests include failure messages in the `message` field
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Project Slug Format
|
||||
|
||||
```
|
||||
Format: {vcs_type}/{org_name}/{repo_name}
|
||||
- GitHub: gh/myorg/myrepo
|
||||
- Bitbucket: bb/myorg/myrepo
|
||||
```
|
||||
|
||||
### Pipeline -> Workflow -> Job Hierarchy
|
||||
|
||||
```
|
||||
1. Call CIRCLECI_LIST_PIPELINES_FOR_PROJECT to get pipeline IDs
|
||||
2. Call CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID with pipeline_id
|
||||
3. Extract job numbers from workflow details
|
||||
4. Call CIRCLECI_GET_JOB_DETAILS with job_number
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Check response for `next_page_token` field
|
||||
- Pass token as `page_token` in next request
|
||||
- Continue until `next_page_token` is absent or null
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**ID Formats**:
|
||||
- Pipeline IDs: UUIDs (e.g., `5034460f-c7c4-4c43-9457-de07e2029e7b`)
|
||||
- Workflow IDs: UUIDs
|
||||
- Job numbers: Integers (e.g., `123`)
|
||||
- Do NOT mix up UUIDs and integers between different endpoints
|
||||
|
||||
**Project Slugs**:
|
||||
- Must include VCS prefix: `gh/` for GitHub, `bb/` for Bitbucket
|
||||
- Organization and repo names are case-sensitive
|
||||
- Incorrect slug format causes 404 errors
|
||||
|
||||
**Rate Limits**:
|
||||
- CircleCI API has per-endpoint rate limits
|
||||
- Implement exponential backoff on 429 responses
|
||||
- Avoid rapid polling; use reasonable intervals (5-10 seconds)
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Trigger pipeline | CIRCLECI_TRIGGER_PIPELINE | project_slug, branch, parameters |
|
||||
| List pipelines | CIRCLECI_LIST_PIPELINES_FOR_PROJECT | project_slug, branch |
|
||||
| List workflows | CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID | pipeline_id |
|
||||
| Get pipeline config | CIRCLECI_GET_PIPELINE_CONFIG | pipeline_id |
|
||||
| Get job details | CIRCLECI_GET_JOB_DETAILS | project_slug, job_number |
|
||||
| Get job artifacts | CIRCLECI_GET_JOB_ARTIFACTS | project_slug, job_number |
|
||||
| Get test metadata | CIRCLECI_GET_TEST_METADATA | project_slug, job_number |
|
||||
@@ -1,234 +0,0 @@
|
||||
---
|
||||
name: clickup-automation
|
||||
description: "Automate ClickUp project management including tasks, spaces, folders, lists, comments, and team operations via Rube MCP (Composio). Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# ClickUp Automation via Rube MCP
|
||||
|
||||
Automate ClickUp project management workflows including task creation and updates, workspace hierarchy navigation, comments, and team member management through Composio's ClickUp toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active ClickUp connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `clickup`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `clickup`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete ClickUp OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create and Manage Tasks
|
||||
|
||||
**When to use**: User wants to create tasks, subtasks, update task properties, or list tasks in a ClickUp list.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CLICKUP_GET_AUTHORIZED_TEAMS_WORKSPACES` - Get workspace/team IDs [Prerequisite]
|
||||
2. `CLICKUP_GET_SPACES` - List spaces in the workspace [Prerequisite]
|
||||
3. `CLICKUP_GET_FOLDERS` - List folders in a space [Prerequisite]
|
||||
4. `CLICKUP_GET_FOLDERLESS_LISTS` - Get lists not inside folders [Optional]
|
||||
5. `CLICKUP_GET_LIST` - Validate list and check available statuses [Prerequisite]
|
||||
6. `CLICKUP_CREATE_TASK` - Create a task in the target list [Required]
|
||||
7. `CLICKUP_CREATE_TASK` (with `parent`) - Create subtask under a parent task [Optional]
|
||||
8. `CLICKUP_UPDATE_TASK` - Modify task status, assignees, dates, priority [Optional]
|
||||
9. `CLICKUP_GET_TASK` - Retrieve full task details [Optional]
|
||||
10. `CLICKUP_GET_TASKS` - List all tasks in a list with filters [Optional]
|
||||
11. `CLICKUP_DELETE_TASK` - Permanently remove a task [Optional]
|
||||
|
||||
**Key parameters for CLICKUP_CREATE_TASK**:
|
||||
- `list_id`: Target list ID (integer, required)
|
||||
- `name`: Task name (string, required)
|
||||
- `description`: Detailed task description
|
||||
- `status`: Must exactly match (case-sensitive) a status name configured in the target list
|
||||
- `priority`: 1 (Urgent), 2 (High), 3 (Normal), 4 (Low)
|
||||
- `assignees`: Array of user IDs (integers)
|
||||
- `due_date`: Unix timestamp in milliseconds
|
||||
- `parent`: Parent task ID string for creating subtasks
|
||||
- `tags`: Array of tag name strings
|
||||
- `time_estimate`: Estimated time in milliseconds
|
||||
|
||||
**Pitfalls**:
|
||||
- `status` is case-sensitive and must match an existing status in the list; use `CLICKUP_GET_LIST` to check available statuses
|
||||
- `due_date` and `start_date` are Unix timestamps in **milliseconds**, not seconds
|
||||
- Subtask `parent` must be a task (not another subtask) in the same list
|
||||
- `notify_all` triggers watcher notifications; set to false for bulk operations
|
||||
- Retries can create duplicates; track created task IDs to avoid re-creation
|
||||
- `custom_item_id` for milestones (ID 1) is subject to workspace plan quotas
|
||||
|
||||
### 2. Navigate Workspace Hierarchy
|
||||
|
||||
**When to use**: User wants to browse or manage the ClickUp workspace structure (Workspaces > Spaces > Folders > Lists).
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CLICKUP_GET_AUTHORIZED_TEAMS_WORKSPACES` - List all accessible workspaces [Required]
|
||||
2. `CLICKUP_GET_SPACES` - List spaces within a workspace [Required]
|
||||
3. `CLICKUP_GET_SPACE` - Get details for a specific space [Optional]
|
||||
4. `CLICKUP_GET_FOLDERS` - List folders in a space [Required]
|
||||
5. `CLICKUP_GET_FOLDER` - Get details for a specific folder [Optional]
|
||||
6. `CLICKUP_CREATE_FOLDER` - Create a new folder in a space [Optional]
|
||||
7. `CLICKUP_GET_FOLDERLESS_LISTS` - List lists not inside any folder [Required]
|
||||
8. `CLICKUP_GET_LIST` - Get list details including statuses and custom fields [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `team_id`: Workspace ID from GET_AUTHORIZED_TEAMS_WORKSPACES (required for spaces)
|
||||
- `space_id`: Space ID (required for folders and folderless lists)
|
||||
- `folder_id`: Folder ID (required for GET_FOLDER)
|
||||
- `list_id`: List ID (required for GET_LIST)
|
||||
- `archived`: Boolean filter for archived/active items
|
||||
|
||||
**Pitfalls**:
|
||||
- ClickUp hierarchy is: Workspace (Team) > Space > Folder > List > Task
|
||||
- Lists can exist directly under Spaces (folderless) or inside Folders
|
||||
- Must use `CLICKUP_GET_FOLDERLESS_LISTS` to find lists not inside folders; `CLICKUP_GET_FOLDERS` only returns folders
|
||||
- `team_id` in ClickUp API refers to the Workspace ID, not a user group
|
||||
|
||||
### 3. Add Comments to Tasks
|
||||
|
||||
**When to use**: User wants to add comments, review existing comments, or manage comment threads on tasks.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CLICKUP_GET_TASK` - Verify task exists and get task_id [Prerequisite]
|
||||
2. `CLICKUP_CREATE_TASK_COMMENT` - Add a new comment to the task [Required]
|
||||
3. `CLICKUP_GET_TASK_COMMENTS` - List existing comments on the task [Optional]
|
||||
4. `CLICKUP_UPDATE_COMMENT` - Edit comment text, assignee, or resolution status [Optional]
|
||||
|
||||
**Key parameters for CLICKUP_CREATE_TASK_COMMENT**:
|
||||
- `task_id`: Task ID string (required)
|
||||
- `comment_text`: Comment content with ClickUp formatting support (required)
|
||||
- `assignee`: User ID to assign the comment to (required)
|
||||
- `notify_all`: true/false for watcher notifications (required)
|
||||
|
||||
**Key parameters for CLICKUP_GET_TASK_COMMENTS**:
|
||||
- `task_id`: Task ID string (required)
|
||||
- `start` / `start_id`: Pagination for older comments (max 25 per page)
|
||||
|
||||
**Pitfalls**:
|
||||
- `CLICKUP_CREATE_TASK_COMMENT` requires all four fields: `task_id`, `comment_text`, `assignee`, and `notify_all`
|
||||
- `assignee` on a comment assigns the comment (not the task) to that user
|
||||
- Comments are paginated at 25 per page; use `start` (Unix ms) and `start_id` for older pages
|
||||
- `CLICKUP_UPDATE_COMMENT` requires all four fields: `comment_id`, `comment_text`, `assignee`, `resolved`
|
||||
|
||||
### 4. Manage Team Members and Assignments
|
||||
|
||||
**When to use**: User wants to view workspace members, check seat utilization, or look up user details.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CLICKUP_GET_AUTHORIZED_TEAMS_WORKSPACES` - List workspaces and get team_id [Required]
|
||||
2. `CLICKUP_GET_WORKSPACE_SEATS` - Check seat utilization (members vs guests) [Required]
|
||||
3. `CLICKUP_GET_TEAMS` - List user groups within the workspace [Optional]
|
||||
4. `CLICKUP_GET_USER` - Get details for a specific user (Enterprise only) [Optional]
|
||||
5. `CLICKUP_GET_CUSTOM_ROLES` - List custom permission roles [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `team_id`: Workspace ID (required for all team operations)
|
||||
- `user_id`: Specific user ID for GET_USER
|
||||
- `group_ids`: Comma-separated group IDs to filter teams
|
||||
|
||||
**Pitfalls**:
|
||||
- `CLICKUP_GET_WORKSPACE_SEATS` returns seat counts, not member details; distinguish members from guests
|
||||
- `CLICKUP_GET_TEAMS` returns user groups, not workspace members; empty groups does not mean no members
|
||||
- `CLICKUP_GET_USER` is only available on ClickUp Enterprise Plan
|
||||
- Must repeat workspace seat queries for each workspace in multi-workspace setups
|
||||
|
||||
### 5. Filter and Query Tasks
|
||||
|
||||
**When to use**: User wants to find tasks with specific filters (status, assignee, dates, tags, custom fields).
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CLICKUP_GET_TASKS` - Filter tasks in a list with multiple criteria [Required]
|
||||
2. `CLICKUP_GET_TASK` - Get full details for individual tasks [Optional]
|
||||
|
||||
**Key parameters for CLICKUP_GET_TASKS**:
|
||||
- `list_id`: List ID (integer, required)
|
||||
- `statuses`: Array of status strings to filter by
|
||||
- `assignees`: Array of user ID strings
|
||||
- `tags`: Array of tag name strings
|
||||
- `due_date_gt` / `due_date_lt`: Unix timestamp in ms for date range
|
||||
- `include_closed`: Boolean to include closed tasks
|
||||
- `subtasks`: Boolean to include subtasks
|
||||
- `order_by`: "id", "created", "updated", or "due_date"
|
||||
- `page`: Page number starting at 0 (max 100 tasks per page)
|
||||
|
||||
**Pitfalls**:
|
||||
- Only tasks whose home list matches `list_id` are returned; tasks in sublists are not included
|
||||
- Date filters use Unix timestamps in milliseconds
|
||||
- Status strings must match exactly; use URL encoding for spaces (e.g., "to%20do")
|
||||
- Page numbering starts at 0; each page returns up to 100 tasks
|
||||
- `custom_fields` filter accepts an array of JSON strings, not objects
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
Always resolve names to IDs through the hierarchy:
|
||||
- **Workspace name -> team_id**: `CLICKUP_GET_AUTHORIZED_TEAMS_WORKSPACES` and match by name
|
||||
- **Space name -> space_id**: `CLICKUP_GET_SPACES` with `team_id`
|
||||
- **Folder name -> folder_id**: `CLICKUP_GET_FOLDERS` with `space_id`
|
||||
- **List name -> list_id**: Navigate folders or use `CLICKUP_GET_FOLDERLESS_LISTS`
|
||||
- **Task name -> task_id**: `CLICKUP_GET_TASKS` with `list_id` and match by name
|
||||
|
||||
### Pagination
|
||||
- `CLICKUP_GET_TASKS`: Page-based with `page` starting at 0, max 100 tasks per page
|
||||
- `CLICKUP_GET_TASK_COMMENTS`: Uses `start` (Unix ms) and `start_id` for cursor-based paging, max 25 per page
|
||||
- Continue fetching until response returns fewer items than the page size
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
### ID Formats
|
||||
- Workspace/Team IDs are large integers
|
||||
- Space, folder, and list IDs are integers
|
||||
- Task IDs are alphanumeric strings (e.g., "9hz", "abc123")
|
||||
- User IDs are integers
|
||||
- Comment IDs are integers
|
||||
|
||||
### Rate Limits
|
||||
- ClickUp enforces rate limits; bulk task creation can trigger 429 responses
|
||||
- Honor `Retry-After` header when present
|
||||
- Set `notify_all=false` for bulk operations to reduce notification load
|
||||
|
||||
### Parameter Quirks
|
||||
- `team_id` in the API means Workspace ID, not a user group
|
||||
- `status` on tasks is case-sensitive and list-specific
|
||||
- Dates are Unix timestamps in **milliseconds** (multiply seconds by 1000)
|
||||
- `priority` is an integer 1-4 (1=Urgent, 4=Low), not a string
|
||||
- `CLICKUP_CREATE_TASK_COMMENT` marks `assignee` and `notify_all` as required
|
||||
- To clear a task description, pass a single space `" "` to `CLICKUP_UPDATE_TASK`
|
||||
|
||||
### Hierarchy Rules
|
||||
- Subtask parent must not itself be a subtask
|
||||
- Subtask parent must be in the same list
|
||||
- Lists can be folderless (directly in a Space) or inside a Folder
|
||||
- Subitem boards are not supported by CLICKUP_CREATE_TASK
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List workspaces | `CLICKUP_GET_AUTHORIZED_TEAMS_WORKSPACES` | (none) |
|
||||
| List spaces | `CLICKUP_GET_SPACES` | `team_id` |
|
||||
| Get space details | `CLICKUP_GET_SPACE` | `space_id` |
|
||||
| List folders | `CLICKUP_GET_FOLDERS` | `space_id` |
|
||||
| Get folder details | `CLICKUP_GET_FOLDER` | `folder_id` |
|
||||
| Create folder | `CLICKUP_CREATE_FOLDER` | `space_id`, `name` |
|
||||
| Folderless lists | `CLICKUP_GET_FOLDERLESS_LISTS` | `space_id` |
|
||||
| Get list details | `CLICKUP_GET_LIST` | `list_id` |
|
||||
| Create task | `CLICKUP_CREATE_TASK` | `list_id`, `name`, `status`, `assignees` |
|
||||
| Update task | `CLICKUP_UPDATE_TASK` | `task_id`, `status`, `priority` |
|
||||
| Get task | `CLICKUP_GET_TASK` | `task_id`, `include_subtasks` |
|
||||
| List tasks | `CLICKUP_GET_TASKS` | `list_id`, `statuses`, `page` |
|
||||
| Delete task | `CLICKUP_DELETE_TASK` | `task_id` |
|
||||
| Add comment | `CLICKUP_CREATE_TASK_COMMENT` | `task_id`, `comment_text`, `assignee` |
|
||||
| List comments | `CLICKUP_GET_TASK_COMMENTS` | `task_id`, `start`, `start_id` |
|
||||
| Update comment | `CLICKUP_UPDATE_COMMENT` | `comment_id`, `comment_text`, `resolved` |
|
||||
| Workspace seats | `CLICKUP_GET_WORKSPACE_SEATS` | `team_id` |
|
||||
| List user groups | `CLICKUP_GET_TEAMS` | `team_id` |
|
||||
| Get user details | `CLICKUP_GET_USER` | `team_id`, `user_id` |
|
||||
| Custom roles | `CLICKUP_GET_CUSTOM_ROLES` | `team_id` |
|
||||
@@ -1,212 +0,0 @@
|
||||
---
|
||||
name: close-automation
|
||||
description: "Automate Close CRM tasks via Rube MCP (Composio): create leads, manage calls/SMS, handle tasks, and track notes. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Close CRM Automation via Rube MCP
|
||||
|
||||
Automate Close CRM operations through Composio's Close toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Close connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `close`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `close`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Close API authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create and Manage Leads
|
||||
|
||||
**When to use**: User wants to create new leads or manage existing lead records
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CLOSE_CREATE_LEAD` - Create a new lead in Close [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Lead/company name
|
||||
- `contacts`: Array of contact objects associated with the lead
|
||||
- `custom`: Custom field values as key-value pairs
|
||||
- `status_id`: Lead status ID
|
||||
|
||||
**Pitfalls**:
|
||||
- Leads in Close represent companies/organizations, not individual people
|
||||
- Contacts are nested within leads; create the lead first, then contacts are included
|
||||
- Custom field keys use the custom field ID (e.g., 'custom.cf_XXX'), not display names
|
||||
- Duplicate lead detection is not automatic; check before creating
|
||||
|
||||
### 2. Log Calls
|
||||
|
||||
**When to use**: User wants to log a phone call activity against a lead
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CLOSE_CREATE_CALL` - Log a call activity [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `lead_id`: ID of the associated lead
|
||||
- `contact_id`: ID of the contact called
|
||||
- `direction`: 'outbound' or 'inbound'
|
||||
- `status`: Call status ('completed', 'no-answer', 'busy', etc.)
|
||||
- `duration`: Call duration in seconds
|
||||
- `note`: Call notes
|
||||
|
||||
**Pitfalls**:
|
||||
- lead_id is required; calls must be associated with a lead
|
||||
- Duration is in seconds, not minutes
|
||||
- Call direction affects reporting and analytics
|
||||
- contact_id is optional but recommended for tracking
|
||||
|
||||
### 3. Send SMS Messages
|
||||
|
||||
**When to use**: User wants to send or log SMS messages through Close
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CLOSE_CREATE_SMS` - Send or log an SMS message [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `lead_id`: ID of the associated lead
|
||||
- `contact_id`: ID of the contact
|
||||
- `direction`: 'outbound' or 'inbound'
|
||||
- `text`: SMS message content
|
||||
- `status`: Message status
|
||||
|
||||
**Pitfalls**:
|
||||
- SMS functionality requires Close phone/SMS integration to be configured
|
||||
- lead_id is required for all SMS activities
|
||||
- Outbound SMS may require a verified sending number
|
||||
- Message length limits may apply depending on carrier
|
||||
|
||||
### 4. Manage Tasks
|
||||
|
||||
**When to use**: User wants to create or manage follow-up tasks
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CLOSE_CREATE_TASK` - Create a new task [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `lead_id`: Associated lead ID
|
||||
- `text`: Task description
|
||||
- `date`: Due date for the task
|
||||
- `assigned_to`: User ID of the assignee
|
||||
- `is_complete`: Whether the task is completed
|
||||
|
||||
**Pitfalls**:
|
||||
- Tasks are associated with leads, not contacts
|
||||
- Date format should follow ISO 8601
|
||||
- assigned_to requires the Close user ID, not email or name
|
||||
- Tasks without a date appear in the 'no due date' section
|
||||
|
||||
### 5. Manage Notes
|
||||
|
||||
**When to use**: User wants to add or retrieve notes on leads
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CLOSE_GET_NOTE` - Retrieve a specific note [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `note_id`: ID of the note to retrieve
|
||||
|
||||
**Pitfalls**:
|
||||
- Notes are associated with leads
|
||||
- Note IDs are required for retrieval; search leads first to find note references
|
||||
- Notes support plain text and basic formatting
|
||||
|
||||
### 6. Delete Activities
|
||||
|
||||
**When to use**: User wants to remove call records or other activities
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CLOSE_DELETE_CALL` - Delete a call activity [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `call_id`: ID of the call to delete
|
||||
|
||||
**Pitfalls**:
|
||||
- Deletion is permanent and cannot be undone
|
||||
- Only the call creator or admin can delete calls
|
||||
- Deleting a call removes it from all reports and timelines
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Lead and Contact Relationship
|
||||
|
||||
```
|
||||
Close data model:
|
||||
- Lead = Company/Organization
|
||||
- Contact = Person (nested within Lead)
|
||||
- Activity = Call, SMS, Email, Note (linked to Lead)
|
||||
- Task = Follow-up item (linked to Lead)
|
||||
- Opportunity = Deal (linked to Lead)
|
||||
```
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Lead ID**:
|
||||
```
|
||||
1. Search for leads using the Close search API
|
||||
2. Extract lead_id from results (format: 'lead_XXXXXXXXXXXXX')
|
||||
3. Use lead_id in all activity creation calls
|
||||
```
|
||||
|
||||
**Contact ID**:
|
||||
```
|
||||
1. Retrieve lead details to get nested contacts
|
||||
2. Extract contact_id (format: 'cont_XXXXXXXXXXXXX')
|
||||
3. Use in call/SMS activities for accurate tracking
|
||||
```
|
||||
|
||||
### Activity Logging Pattern
|
||||
|
||||
```
|
||||
1. Identify the lead_id and optionally contact_id
|
||||
2. Create the activity (call, SMS, note) with lead_id
|
||||
3. Include relevant metadata (duration, direction, status)
|
||||
4. Create follow-up tasks if needed
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**ID Formats**:
|
||||
- Lead IDs: 'lead_XXXXXXXXXXXXX'
|
||||
- Contact IDs: 'cont_XXXXXXXXXXXXX'
|
||||
- Activity IDs vary by type: 'acti_XXXXXXXXXXXXX', 'call_XXXXXXXXXXXXX'
|
||||
- Custom field IDs: 'custom.cf_XXXXXXXXXXXXX'
|
||||
- Always use the full ID string
|
||||
|
||||
**Rate Limits**:
|
||||
- Close API has rate limits based on your plan
|
||||
- Implement delays between bulk operations
|
||||
- Monitor response headers for rate limit status
|
||||
- 429 responses require backoff
|
||||
|
||||
**Custom Fields**:
|
||||
- Custom fields are referenced by their API ID, not display name
|
||||
- Different lead statuses may have different required custom fields
|
||||
- Custom field types (text, number, date, dropdown) enforce value formats
|
||||
|
||||
**Data Integrity**:
|
||||
- Leads are the primary entity; contacts and activities are linked to leads
|
||||
- Deleting a lead may cascade to its contacts and activities
|
||||
- Bulk operations should validate IDs before executing
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Create lead | CLOSE_CREATE_LEAD | name, contacts, custom |
|
||||
| Log call | CLOSE_CREATE_CALL | lead_id, direction, status, duration |
|
||||
| Send SMS | CLOSE_CREATE_SMS | lead_id, text, direction |
|
||||
| Create task | CLOSE_CREATE_TASK | lead_id, text, date, assigned_to |
|
||||
| Get note | CLOSE_GET_NOTE | note_id |
|
||||
| Delete call | CLOSE_DELETE_CALL | call_id |
|
||||
@@ -1,241 +0,0 @@
|
||||
---
|
||||
name: coda-automation
|
||||
description: "Automate Coda tasks via Rube MCP (Composio): manage docs, pages, tables, rows, formulas, permissions, and publishing. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Coda Automation via Rube MCP
|
||||
|
||||
Automate Coda document and data operations through Composio's Coda toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Coda connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `coda`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `coda`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Coda authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Search and Browse Documents
|
||||
|
||||
**When to use**: User wants to find, list, or inspect Coda documents
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CODA_SEARCH_DOCS` or `CODA_LIST_AVAILABLE_DOCS` - Find documents [Required]
|
||||
2. `CODA_RESOLVE_BROWSER_LINK` - Resolve a Coda URL to doc/page/table IDs [Alternative]
|
||||
3. `CODA_LIST_PAGES` - List pages within a document [Optional]
|
||||
4. `CODA_GET_A_PAGE` - Get specific page details [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: Search term for finding documents
|
||||
- `isOwner`: Filter to docs owned by the user
|
||||
- `docId`: Document ID for page operations
|
||||
- `pageIdOrName`: Page identifier or name
|
||||
- `url`: Browser URL for resolve operations
|
||||
|
||||
**Pitfalls**:
|
||||
- Document IDs are alphanumeric strings (e.g., 'AbCdEfGhIj')
|
||||
- `CODA_RESOLVE_BROWSER_LINK` is the best way to convert a Coda URL to API IDs
|
||||
- Page names may not be unique within a doc; prefer page IDs
|
||||
- Search results include docs shared with the user, not just owned docs
|
||||
|
||||
### 2. Work with Tables and Data
|
||||
|
||||
**When to use**: User wants to read, write, or query table data
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CODA_LIST_TABLES` - List tables in a document [Prerequisite]
|
||||
2. `CODA_LIST_COLUMNS` - Get column definitions for a table [Prerequisite]
|
||||
3. `CODA_LIST_TABLE_ROWS` - List all rows with optional filters [Required]
|
||||
4. `CODA_SEARCH_ROW` - Search for specific rows by query [Alternative]
|
||||
5. `CODA_GET_A_ROW` - Get a specific row by ID [Optional]
|
||||
6. `CODA_UPSERT_ROWS` - Insert or update rows in a table [Optional]
|
||||
7. `CODA_GET_A_COLUMN` - Get details of a specific column [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `docId`: Document ID containing the table
|
||||
- `tableIdOrName`: Table identifier or name
|
||||
- `query`: Filter query for searching rows
|
||||
- `rows`: Array of row objects for upsert operations
|
||||
- `keyColumns`: Column IDs used for matching during upsert
|
||||
- `sortBy`: Column to sort results by
|
||||
- `useColumnNames`: Use column names instead of IDs in row data
|
||||
|
||||
**Pitfalls**:
|
||||
- Table names may contain spaces; URL-encode if needed
|
||||
- `CODA_UPSERT_ROWS` does insert if no match on `keyColumns`, update if match found
|
||||
- `keyColumns` must reference columns that have unique values for reliable upserts
|
||||
- Column IDs are different from column names; list columns first to map names to IDs
|
||||
- `useColumnNames: true` allows using human-readable names in row data
|
||||
- Row data values must match the column type (text, number, date, etc.)
|
||||
|
||||
### 3. Manage Formulas
|
||||
|
||||
**When to use**: User wants to list or evaluate formulas in a document
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CODA_LIST_FORMULAS` - List all named formulas in a doc [Required]
|
||||
2. `CODA_GET_A_FORMULA` - Get a specific formula's current value [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `docId`: Document ID
|
||||
- `formulaIdOrName`: Formula identifier or name
|
||||
|
||||
**Pitfalls**:
|
||||
- Formulas are named calculations defined in the document
|
||||
- Formula values are computed server-side; results reflect the current state
|
||||
- Formula names are case-sensitive
|
||||
|
||||
### 4. Export Document Content
|
||||
|
||||
**When to use**: User wants to export a document or page to HTML or Markdown
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CODA_BEGIN_CONTENT_EXPORT` - Start an export job [Required]
|
||||
2. `CODA_CONTENT_EXPORT_STATUS` - Poll export status until complete [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `docId`: Document ID to export
|
||||
- `outputFormat`: Export format ('html' or 'markdown')
|
||||
- `pageIdOrName`: Specific page to export (optional, omit for full doc)
|
||||
- `requestId`: Export request ID for status polling
|
||||
|
||||
**Pitfalls**:
|
||||
- Export is asynchronous; poll status until `status` is 'complete'
|
||||
- Large documents may take significant time to export
|
||||
- Export URL in the completed response is temporary; download promptly
|
||||
- Polling too frequently may hit rate limits; use 2-5 second intervals
|
||||
|
||||
### 5. Manage Permissions and Sharing
|
||||
|
||||
**When to use**: User wants to view or manage document access
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CODA_GET_SHARING_METADATA` - View current sharing settings [Required]
|
||||
2. `CODA_GET_ACL_SETTINGS` - Get access control list settings [Optional]
|
||||
3. `CODA_ADD_PERMISSION` - Grant access to a user or email [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `docId`: Document ID
|
||||
- `access`: Permission level ('readonly', 'write', 'comment')
|
||||
- `principal`: Object with email or user ID of the recipient
|
||||
- `suppressEmail`: Whether to skip the sharing notification email
|
||||
|
||||
**Pitfalls**:
|
||||
- Permission levels: 'readonly', 'write', 'comment'
|
||||
- Adding permission sends an email notification by default; use `suppressEmail` to prevent
|
||||
- Cannot remove permissions via API in all cases; check ACL settings
|
||||
|
||||
### 6. Publish and Customize Documents
|
||||
|
||||
**When to use**: User wants to publish a document or manage custom domains
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CODA_PUBLISH_DOC` - Publish a document publicly [Required]
|
||||
2. `CODA_UNPUBLISH_DOC` - Unpublish a document [Optional]
|
||||
3. `CODA_ADD_CUSTOM_DOMAIN` - Add a custom domain for published doc [Optional]
|
||||
4. `CODA_GET_DOC_CATEGORIES` - Get doc categories for discovery [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `docId`: Document ID
|
||||
- `slug`: Custom URL slug for the published doc
|
||||
- `categoryIds`: Category IDs for discoverability
|
||||
|
||||
**Pitfalls**:
|
||||
- Publishing makes the document accessible to anyone with the link
|
||||
- Custom domains require DNS configuration
|
||||
- Unpublishing removes public access but retains shared access
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Doc URL -> Doc ID**:
|
||||
```
|
||||
1. Call CODA_RESOLVE_BROWSER_LINK with the Coda URL
|
||||
2. Extract docId from the response
|
||||
```
|
||||
|
||||
**Table name -> Table ID**:
|
||||
```
|
||||
1. Call CODA_LIST_TABLES with docId
|
||||
2. Find table by name, extract id
|
||||
```
|
||||
|
||||
**Column name -> Column ID**:
|
||||
```
|
||||
1. Call CODA_LIST_COLUMNS with docId and tableIdOrName
|
||||
2. Find column by name, extract id
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Coda uses cursor-based pagination with `pageToken`
|
||||
- Check response for `nextPageToken`
|
||||
- Pass as `pageToken` in next request until absent
|
||||
- Default page sizes vary by endpoint
|
||||
|
||||
### Row Upsert Pattern
|
||||
|
||||
```
|
||||
1. Call CODA_LIST_COLUMNS to get column IDs
|
||||
2. Build row objects with column ID keys and values
|
||||
3. Set keyColumns to unique identifier column(s)
|
||||
4. Call CODA_UPSERT_ROWS with rows and keyColumns
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**ID Formats**:
|
||||
- Document IDs: alphanumeric strings
|
||||
- Table/column/row IDs: prefixed strings (e.g., 'grid-abc', 'c-xyz')
|
||||
- Use RESOLVE_BROWSER_LINK to convert URLs to IDs
|
||||
|
||||
**Data Types**:
|
||||
- Row values must match column types
|
||||
- Date columns expect ISO 8601 format
|
||||
- Select/multi-select columns expect exact option values
|
||||
- People columns expect email addresses
|
||||
|
||||
**Rate Limits**:
|
||||
- Coda API has per-token rate limits
|
||||
- Implement backoff on 429 responses
|
||||
- Bulk row operations via UPSERT_ROWS are more efficient than individual updates
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Search docs | CODA_SEARCH_DOCS | query |
|
||||
| List docs | CODA_LIST_AVAILABLE_DOCS | isOwner |
|
||||
| Resolve URL | CODA_RESOLVE_BROWSER_LINK | url |
|
||||
| List pages | CODA_LIST_PAGES | docId |
|
||||
| Get page | CODA_GET_A_PAGE | docId, pageIdOrName |
|
||||
| List tables | CODA_LIST_TABLES | docId |
|
||||
| List columns | CODA_LIST_COLUMNS | docId, tableIdOrName |
|
||||
| List rows | CODA_LIST_TABLE_ROWS | docId, tableIdOrName |
|
||||
| Search rows | CODA_SEARCH_ROW | docId, tableIdOrName, query |
|
||||
| Get row | CODA_GET_A_ROW | docId, tableIdOrName, rowIdOrName |
|
||||
| Upsert rows | CODA_UPSERT_ROWS | docId, tableIdOrName, rows, keyColumns |
|
||||
| Get column | CODA_GET_A_COLUMN | docId, tableIdOrName, columnIdOrName |
|
||||
| Push button | CODA_PUSH_A_BUTTON | docId, tableIdOrName, rowIdOrName, columnIdOrName |
|
||||
| List formulas | CODA_LIST_FORMULAS | docId |
|
||||
| Get formula | CODA_GET_A_FORMULA | docId, formulaIdOrName |
|
||||
| Begin export | CODA_BEGIN_CONTENT_EXPORT | docId, outputFormat |
|
||||
| Export status | CODA_CONTENT_EXPORT_STATUS | docId, requestId |
|
||||
| Get sharing | CODA_GET_SHARING_METADATA | docId |
|
||||
| Add permission | CODA_ADD_PERMISSION | docId, access, principal |
|
||||
| Publish doc | CODA_PUBLISH_DOC | docId, slug |
|
||||
| Unpublish doc | CODA_UNPUBLISH_DOC | docId |
|
||||
| List packs | CODA_LIST_PACKS | (none) |
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
name: computer-vision-expert
|
||||
description: SOTA Computer Vision Expert (2026). Specialized in YOLO26, Segment Anything 3 (SAM 3), Vision Language Models, and real-time spatial analysis.
|
||||
---
|
||||
|
||||
# Computer Vision Expert (SOTA 2026)
|
||||
|
||||
**Role**: Advanced Vision Systems Architect & Spatial Intelligence Expert
|
||||
|
||||
## Purpose
|
||||
To provide expert guidance on designing, implementing, and optimizing state-of-the-art computer vision pipelines. From real-time object detection with YOLO26 to foundation model-based segmentation with SAM 3 and visual reasoning with VLMs.
|
||||
|
||||
## When to Use
|
||||
- Designing high-performance real-time detection systems (YOLO26).
|
||||
- Implementing zero-shot or text-guided segmentation tasks (SAM 3).
|
||||
- Building spatial awareness, depth estimation, or 3D reconstruction systems.
|
||||
- Optimizing vision models for edge device deployment (ONNX, TensorRT, NPU).
|
||||
- Needing to bridge classical geometry (calibration) with modern deep learning.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### 1. Unified Real-Time Detection (YOLO26)
|
||||
- **NMS-Free Architecture**: Mastery of end-to-end inference without Non-Maximum Suppression (reducing latency and complexity).
|
||||
- **Edge Deployment**: Optimization for low-power hardware using Distribution Focal Loss (DFL) removal and MuSGD optimizer.
|
||||
- **Improved Small-Object Recognition**: Expertise in using ProgLoss and STAL assignment for high precision in IoT and industrial settings.
|
||||
|
||||
### 2. Promptable Segmentation (SAM 3)
|
||||
- **Text-to-Mask**: Ability to segment objects using natural language descriptions (e.g., "the blue container on the right").
|
||||
- **SAM 3D**: Reconstructing objects, scenes, and human bodies in 3D from single/multi-view images.
|
||||
- **Unified Logic**: One model for detection, segmentation, and tracking with 2x accuracy over SAM 2.
|
||||
|
||||
### 3. Vision Language Models (VLMs)
|
||||
- **Visual Grounding**: Leveraging Florence-2, PaliGemma 2, or Qwen2-VL for semantic scene understanding.
|
||||
- **Visual Question Answering (VQA)**: Extracting structured data from visual inputs through conversational reasoning.
|
||||
|
||||
### 4. Geometry & Reconstruction
|
||||
- **Depth Anything V2**: State-of-the-art monocular depth estimation for spatial awareness.
|
||||
- **Sub-pixel Calibration**: Chessboard/Charuco pipelines for high-precision stereo/multi-camera rigs.
|
||||
- **Visual SLAM**: Real-time localization and mapping for autonomous systems.
|
||||
|
||||
## Patterns
|
||||
|
||||
### 1. Text-Guided Vision Pipelines
|
||||
- Use SAM 3's text-to-mask capability to isolate specific parts during inspection without needing custom detectors for every variation.
|
||||
- Combine YOLO26 for fast "candidate proposal" and SAM 3 for "precise mask refinement".
|
||||
|
||||
### 2. Deployment-First Design
|
||||
- Leverage YOLO26's simplified ONNX/TensorRT exports (NMS-free).
|
||||
- Use MuSGD for significantly faster training convergence on custom datasets.
|
||||
|
||||
### 3. Progressive 3D Scene Reconstruction
|
||||
- Integrate monocular depth maps with geometric homographies to build accurate 2.5D/3D representations of scenes.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- **Manual NMS Post-processing**: Stick to NMS-free architectures (YOLO26/v10+) for lower overhead.
|
||||
- **Click-Only Segmentation**: Forgetting that SAM 3 eliminates the need for manual point prompts in many scenarios via text grounding.
|
||||
- **Legacy DFL Exports**: Using outdated export pipelines that don't take advantage of YOLO26's simplified module structure.
|
||||
|
||||
## Sharp Edges (2026)
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| SAM 3 VRAM Usage | Medium | Use quantized/distilled versions for local GPU inference. |
|
||||
| Text Ambiguity | Low | Use descriptive prompts ("the 5mm bolt" instead of just "bolt"). |
|
||||
| Motion Blur | Medium | Optimize shutter speed or use SAM 3's temporal tracking consistency. |
|
||||
| Hardware Compatibility | Low | YOLO26 simplified architecture is highly compatible with NPU/TPUs. |
|
||||
|
||||
## Related Skills
|
||||
`ai-engineer`, `robotics-expert`, `research-engineer`, `embedded-systems`
|
||||
@@ -1,208 +0,0 @@
|
||||
---
|
||||
name: confluence-automation
|
||||
description: "Automate Confluence page creation, content search, space management, labels, and hierarchy navigation via Rube MCP (Composio). Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Confluence Automation via Rube MCP
|
||||
|
||||
Automate Confluence operations including page creation and updates, content search with CQL, space management, label tagging, and page hierarchy navigation through Composio's Confluence toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Confluence connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `confluence`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `confluence`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Confluence OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create and Update Pages
|
||||
|
||||
**When to use**: User wants to create new documentation or update existing Confluence pages
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CONFLUENCE_GET_SPACES` - List spaces to find the target space ID [Prerequisite]
|
||||
2. `CONFLUENCE_SEARCH_CONTENT` - Find existing page to avoid duplicates or locate parent [Optional]
|
||||
3. `CONFLUENCE_GET_PAGE_BY_ID` - Get current page content and version number before updating [Prerequisite for updates]
|
||||
4. `CONFLUENCE_CREATE_PAGE` - Create a new page in a space [Required for creation]
|
||||
5. `CONFLUENCE_UPDATE_PAGE` - Update an existing page with new content and incremented version [Required for updates]
|
||||
6. `CONFLUENCE_ADD_CONTENT_LABEL` - Tag the page with labels after creation [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `spaceId`: Space ID or key (e.g., `"DOCS"`, `"12345678"`) -- space keys are auto-converted to IDs
|
||||
- `title`: Page title (must be unique within a space)
|
||||
- `parentId`: Parent page ID for creating child pages; omit to place under space homepage
|
||||
- `body.storage.value`: HTML/XHTML content in Confluence storage format
|
||||
- `body.storage.representation`: Must be `"storage"` for create operations
|
||||
- `version.number`: For updates, must be current version + 1
|
||||
- `version.message`: Optional change description
|
||||
|
||||
**Pitfalls**:
|
||||
- Confluence enforces unique page titles per space; creating a page with a duplicate title will fail
|
||||
- `UPDATE_PAGE` requires `version.number` set to current version + 1; always fetch current version first with `GET_PAGE_BY_ID`
|
||||
- Content must be in Confluence storage format (XHTML), not plain text or Markdown
|
||||
- `CREATE_PAGE` uses `body.storage.value` while `UPDATE_PAGE` uses `body.value` with `body.representation`
|
||||
- `GET_PAGE_BY_ID` requires a numeric long ID, not a UUID or string
|
||||
|
||||
### 2. Search Content
|
||||
|
||||
**When to use**: User wants to find pages, blog posts, or content across Confluence
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CONFLUENCE_SEARCH_CONTENT` - Keyword search with intelligent relevance ranking [Required]
|
||||
2. `CONFLUENCE_CQL_SEARCH` - Advanced search using Confluence Query Language [Alternative]
|
||||
3. `CONFLUENCE_GET_PAGE_BY_ID` - Hydrate full content for selected search results [Optional]
|
||||
4. `CONFLUENCE_GET_PAGES` - Browse pages sorted by date when search relevance is weak [Fallback]
|
||||
|
||||
**Key parameters for SEARCH_CONTENT**:
|
||||
- `query`: Search text matched against page titles with intelligent ranking
|
||||
- `spaceKey`: Limit search to a specific space
|
||||
- `limit`: Max results (default 25, max 250)
|
||||
- `start`: Pagination offset (0-based)
|
||||
|
||||
**Key parameters for CQL_SEARCH**:
|
||||
- `cql`: CQL query string (e.g., `text ~ "API docs" AND space = DOCS AND type = page`)
|
||||
- `expand`: Comma-separated properties (e.g., `content.space`, `content.body.storage`)
|
||||
- `excerpt`: `highlight`, `indexed`, or `none`
|
||||
- `limit`: Max results (max 250; reduced to 25-50 when using body expansions)
|
||||
|
||||
**CQL operators and fields**:
|
||||
- Fields: `text`, `title`, `label`, `space`, `type`, `creator`, `lastModified`, `created`, `ancestor`
|
||||
- Operators: `=`, `!=`, `~` (contains), `!~`, `>`, `<`, `>=`, `<=`, `IN`, `NOT IN`
|
||||
- Functions: `currentUser()`, `now("-7d")`, `now("-30d")`
|
||||
- Example: `title ~ "meeting" AND lastModified > now("-7d") ORDER BY lastModified DESC`
|
||||
|
||||
**Pitfalls**:
|
||||
- `CONFLUENCE_SEARCH_CONTENT` fetches up to 300 pages and applies client-side filtering -- not a true full-text search
|
||||
- `CONFLUENCE_CQL_SEARCH` is the real full-text search; use `text ~ "term"` for content body search
|
||||
- HTTP 429 rate limits can occur; throttle to ~2 requests/second with backoff
|
||||
- Using body expansions in CQL_SEARCH may reduce max results to 25-50
|
||||
- Search indexing is not immediate; recently created pages may not appear
|
||||
|
||||
### 3. Manage Spaces
|
||||
|
||||
**When to use**: User wants to list, create, or inspect Confluence spaces
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CONFLUENCE_GET_SPACES` - List all spaces with optional filtering [Required]
|
||||
2. `CONFLUENCE_GET_SPACE_BY_ID` - Get detailed metadata for a specific space [Optional]
|
||||
3. `CONFLUENCE_CREATE_SPACE` - Create a new space with key and name [Optional]
|
||||
4. `CONFLUENCE_GET_SPACE_PROPERTIES` - Retrieve custom metadata stored as space properties [Optional]
|
||||
5. `CONFLUENCE_GET_SPACE_CONTENTS` - List pages, blog posts, or attachments in a space [Optional]
|
||||
6. `CONFLUENCE_GET_LABELS_FOR_SPACE` - List labels on a space [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `key`: Space key -- alphanumeric only, no underscores or hyphens (e.g., `DOCS`, `PROJECT1`)
|
||||
- `name`: Human-readable space name
|
||||
- `type`: `global` or `personal`
|
||||
- `status`: `current` (active) or `archived`
|
||||
- `spaceKey`: For GET_SPACE_CONTENTS, filters by space key
|
||||
- `id`: Numeric space ID for GET_SPACE_BY_ID (NOT the space key)
|
||||
|
||||
**Pitfalls**:
|
||||
- Space keys must be alphanumeric only (no underscores, hyphens, or special characters)
|
||||
- `GET_SPACE_BY_ID` requires numeric space ID, not the space key; use `GET_SPACES` to find numeric IDs
|
||||
- Clickable space URLs may need assembly: join `_links.webui` (relative) with `_links.base`
|
||||
- Default pagination is 25; set `limit` explicitly (max 200 for spaces)
|
||||
|
||||
### 4. Navigate Page Hierarchy and Labels
|
||||
|
||||
**When to use**: User wants to explore page trees, child pages, ancestors, or manage labels
|
||||
|
||||
**Tool sequence**:
|
||||
1. `CONFLUENCE_SEARCH_CONTENT` - Find the target page ID [Prerequisite]
|
||||
2. `CONFLUENCE_GET_CHILD_PAGES` - List direct children of a parent page [Required]
|
||||
3. `CONFLUENCE_GET_PAGE_ANCESTORS` - Get the full ancestor chain for a page [Optional]
|
||||
4. `CONFLUENCE_GET_LABELS_FOR_PAGE` - List labels on a specific page [Optional]
|
||||
5. `CONFLUENCE_ADD_CONTENT_LABEL` - Add labels to a page [Optional]
|
||||
6. `CONFLUENCE_GET_LABELS_FOR_SPACE_CONTENT` - List labels across all content in a space [Optional]
|
||||
7. `CONFLUENCE_GET_PAGE_VERSIONS` - Audit edit history for a page [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `id`: Page ID for child pages, ancestors, labels, and versions
|
||||
- `cursor`: Opaque pagination cursor for GET_CHILD_PAGES (from `_links.next`)
|
||||
- `limit`: Items per page (max 250 for child pages)
|
||||
- `sort`: Child page sort options: `id`, `-id`, `created-date`, `-created-date`, `modified-date`, `-modified-date`, `child-position`, `-child-position`
|
||||
|
||||
**Pitfalls**:
|
||||
- `GET_CHILD_PAGES` only returns direct children, not nested descendants; recurse for full tree
|
||||
- Pagination for GET_CHILD_PAGES uses cursor-based pagination (not start/limit)
|
||||
- Verify the correct page ID from search before using as parent; search can return similar titles
|
||||
- `GET_PAGE_VERSIONS` requires the page ID, not a version number
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
Always resolve human-readable names to IDs before operations:
|
||||
- **Space key -> Space ID**: `CONFLUENCE_GET_SPACES` with `spaceKey` filter, or `CREATE_PAGE` accepts space keys directly
|
||||
- **Page title -> Page ID**: `CONFLUENCE_SEARCH_CONTENT` with `query` param, then extract page ID
|
||||
- **Space ID from URL**: Extract numeric ID from Confluence URLs or use GET_SPACES
|
||||
|
||||
### Pagination
|
||||
Confluence uses two pagination styles:
|
||||
- **Offset-based** (most endpoints): `start` (0-based offset) + `limit` (page size). Increment `start` by `limit` until fewer results than `limit` are returned.
|
||||
- **Cursor-based** (GET_CHILD_PAGES, GET_PAGES): Use the `cursor` from `_links.next` in the response. Continue until no `next` link is present.
|
||||
|
||||
### Content Formatting
|
||||
- Pages use Confluence storage format (XHTML), not Markdown
|
||||
- Basic elements: `<p>`, `<h1>`-`<h6>`, `<strong>`, `<em>`, `<code>`, `<ul>`, `<ol>`, `<li>`
|
||||
- Tables: `<table><tbody><tr><th>` / `<td>` structure
|
||||
- Macros: `<ac:structured-macro ac:name="code">` for code blocks, etc.
|
||||
- Always wrap content in proper XHTML tags
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
### ID Formats
|
||||
- Space IDs are numeric (e.g., `557060`); space keys are short strings (e.g., `DOCS`)
|
||||
- Page IDs are numeric long values for GET_PAGE_BY_ID; some tools accept UUID format
|
||||
- `GET_SPACE_BY_ID` requires numeric ID, not the space key
|
||||
- `GET_PAGE_BY_ID` takes an integer, not a string
|
||||
|
||||
### Rate Limits
|
||||
- HTTP 429 can occur on search endpoints; honor Retry-After header
|
||||
- Throttle to ~2 requests/second with exponential backoff and jitter
|
||||
- Body expansion in CQL_SEARCH reduces result limits to 25-50
|
||||
|
||||
### Content Format
|
||||
- Content must be Confluence storage format (XHTML), not Markdown or plain text
|
||||
- Invalid XHTML will cause page creation/update to fail
|
||||
- `CREATE_PAGE` nests body under `body.storage.value`; `UPDATE_PAGE` uses `body.value` + `body.representation`
|
||||
|
||||
### Version Conflicts
|
||||
- Updates require exact next version number (current + 1)
|
||||
- Concurrent edits can cause version conflicts; always fetch current version immediately before updating
|
||||
- Title changes during update must still be unique within the space
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List spaces | `CONFLUENCE_GET_SPACES` | `type`, `status`, `limit` |
|
||||
| Get space by ID | `CONFLUENCE_GET_SPACE_BY_ID` | `id` |
|
||||
| Create space | `CONFLUENCE_CREATE_SPACE` | `key`, `name`, `type` |
|
||||
| Space contents | `CONFLUENCE_GET_SPACE_CONTENTS` | `spaceKey`, `type`, `status` |
|
||||
| Space properties | `CONFLUENCE_GET_SPACE_PROPERTIES` | `id`, `key` |
|
||||
| Search content | `CONFLUENCE_SEARCH_CONTENT` | `query`, `spaceKey`, `limit` |
|
||||
| CQL search | `CONFLUENCE_CQL_SEARCH` | `cql`, `expand`, `limit` |
|
||||
| List pages | `CONFLUENCE_GET_PAGES` | `spaceId`, `sort`, `limit` |
|
||||
| Get page by ID | `CONFLUENCE_GET_PAGE_BY_ID` | `id` (integer) |
|
||||
| Create page | `CONFLUENCE_CREATE_PAGE` | `title`, `spaceId`, `body` |
|
||||
| Update page | `CONFLUENCE_UPDATE_PAGE` | `id`, `title`, `body`, `version` |
|
||||
| Delete page | `CONFLUENCE_DELETE_PAGE` | `id` |
|
||||
| Child pages | `CONFLUENCE_GET_CHILD_PAGES` | `id`, `limit`, `sort` |
|
||||
| Page ancestors | `CONFLUENCE_GET_PAGE_ANCESTORS` | `id` |
|
||||
| Page labels | `CONFLUENCE_GET_LABELS_FOR_PAGE` | `id` |
|
||||
| Add label | `CONFLUENCE_ADD_CONTENT_LABEL` | content ID, label |
|
||||
| Page versions | `CONFLUENCE_GET_PAGE_VERSIONS` | `id` |
|
||||
| Space labels | `CONFLUENCE_GET_LABELS_FOR_SPACE` | space ID |
|
||||
@@ -1,195 +0,0 @@
|
||||
---
|
||||
name: convertkit-automation
|
||||
description: "Automate ConvertKit (Kit) tasks via Rube MCP (Composio): manage subscribers, tags, broadcasts, and broadcast stats. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# ConvertKit (Kit) Automation via Rube MCP
|
||||
|
||||
Automate ConvertKit (now known as Kit) email marketing operations through Composio's Kit toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Kit connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `kit`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `kit`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Kit authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. List and Search Subscribers
|
||||
|
||||
**When to use**: User wants to browse, search, or filter email subscribers
|
||||
|
||||
**Tool sequence**:
|
||||
1. `KIT_LIST_SUBSCRIBERS` - List subscribers with filters and pagination [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `status`: Filter by status ('active' or 'inactive')
|
||||
- `email_address`: Exact email to search for
|
||||
- `created_after`/`created_before`: Date range filter (YYYY-MM-DD)
|
||||
- `updated_after`/`updated_before`: Date range filter (YYYY-MM-DD)
|
||||
- `sort_field`: Sort by 'id', 'cancelled_at', or 'updated_at'
|
||||
- `sort_order`: 'asc' or 'desc'
|
||||
- `per_page`: Results per page (min 1)
|
||||
- `after`/`before`: Cursor strings for pagination
|
||||
- `include_total_count`: Set to 'true' to get total subscriber count
|
||||
|
||||
**Pitfalls**:
|
||||
- If `sort_field` is 'cancelled_at', the `status` must be set to 'cancelled'
|
||||
- Date filters use YYYY-MM-DD format (no time component)
|
||||
- `email_address` is an exact match; partial email search is not supported
|
||||
- Pagination uses cursor-based approach with `after`/`before` cursor strings
|
||||
- `include_total_count` is a string 'true', not a boolean
|
||||
|
||||
### 2. Manage Subscriber Tags
|
||||
|
||||
**When to use**: User wants to tag subscribers for segmentation
|
||||
|
||||
**Tool sequence**:
|
||||
1. `KIT_LIST_SUBSCRIBERS` - Find subscriber ID by email [Prerequisite]
|
||||
2. `KIT_TAG_SUBSCRIBER` - Associate a subscriber with a tag [Required]
|
||||
3. `KIT_LIST_TAG_SUBSCRIBERS` - List subscribers for a specific tag [Optional]
|
||||
|
||||
**Key parameters for tagging**:
|
||||
- `tag_id`: Numeric tag ID (required)
|
||||
- `subscriber_id`: Numeric subscriber ID (required)
|
||||
|
||||
**Pitfalls**:
|
||||
- Both `tag_id` and `subscriber_id` must be positive integers
|
||||
- Tag IDs must reference existing tags; tags are created via the Kit web UI
|
||||
- Tagging an already-tagged subscriber is idempotent (no error)
|
||||
- Subscriber IDs are returned from LIST_SUBSCRIBERS; use `email_address` filter to find specific subscribers
|
||||
|
||||
### 3. Unsubscribe a Subscriber
|
||||
|
||||
**When to use**: User wants to unsubscribe a subscriber from all communications
|
||||
|
||||
**Tool sequence**:
|
||||
1. `KIT_LIST_SUBSCRIBERS` - Find subscriber ID [Prerequisite]
|
||||
2. `KIT_DELETE_SUBSCRIBER` - Unsubscribe the subscriber [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `id`: Subscriber ID (required, positive integer)
|
||||
|
||||
**Pitfalls**:
|
||||
- This permanently unsubscribes the subscriber from ALL email communications
|
||||
- The subscriber's historical data is retained but they will no longer receive emails
|
||||
- Operation is idempotent; unsubscribing an already-unsubscribed subscriber succeeds without error
|
||||
- Returns empty response (HTTP 204 No Content) on success
|
||||
- Subscriber ID must exist; non-existent IDs return 404
|
||||
|
||||
### 4. List and View Broadcasts
|
||||
|
||||
**When to use**: User wants to browse email broadcasts or get details of a specific one
|
||||
|
||||
**Tool sequence**:
|
||||
1. `KIT_LIST_BROADCASTS` - List all broadcasts with pagination [Required]
|
||||
2. `KIT_GET_BROADCAST` - Get detailed information for a specific broadcast [Optional]
|
||||
3. `KIT_GET_BROADCAST_STATS` - Get performance statistics for a broadcast [Optional]
|
||||
|
||||
**Key parameters for listing**:
|
||||
- `per_page`: Results per page (1-500)
|
||||
- `after`/`before`: Cursor strings for pagination
|
||||
- `include_total_count`: Set to 'true' for total count
|
||||
|
||||
**Key parameters for details**:
|
||||
- `id`: Broadcast ID (required, positive integer)
|
||||
|
||||
**Pitfalls**:
|
||||
- `per_page` max is 500 for broadcasts
|
||||
- Broadcast stats are only available for sent broadcasts
|
||||
- Draft broadcasts will not have stats
|
||||
- Broadcast IDs are numeric integers
|
||||
|
||||
### 5. Delete a Broadcast
|
||||
|
||||
**When to use**: User wants to permanently remove a broadcast
|
||||
|
||||
**Tool sequence**:
|
||||
1. `KIT_LIST_BROADCASTS` - Find the broadcast to delete [Prerequisite]
|
||||
2. `KIT_GET_BROADCAST` - Verify it is the correct broadcast [Optional]
|
||||
3. `KIT_DELETE_BROADCAST` - Permanently delete the broadcast [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `id`: Broadcast ID (required)
|
||||
|
||||
**Pitfalls**:
|
||||
- Deletion is permanent and cannot be undone
|
||||
- Deleting a sent broadcast removes it but does not unsend the emails
|
||||
- Confirm the broadcast ID before deleting
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Subscriber Lookup by Email
|
||||
|
||||
```
|
||||
1. Call KIT_LIST_SUBSCRIBERS with email_address='user@example.com'
|
||||
2. Extract subscriber ID from the response
|
||||
3. Use ID for tagging, unsubscribing, or other operations
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
Kit uses cursor-based pagination:
|
||||
- Check response for `after` cursor value
|
||||
- Pass cursor as `after` parameter in next request
|
||||
- Continue until no more cursor is returned
|
||||
- Use `include_total_count: 'true'` to track progress
|
||||
|
||||
### Tag-Based Segmentation
|
||||
|
||||
```
|
||||
1. Create tags in Kit web UI
|
||||
2. Use KIT_TAG_SUBSCRIBER to assign tags to subscribers
|
||||
3. Use KIT_LIST_TAG_SUBSCRIBERS to view subscribers per tag
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**ID Formats**:
|
||||
- Subscriber IDs: positive integers (e.g., 3887204736)
|
||||
- Tag IDs: positive integers
|
||||
- Broadcast IDs: positive integers
|
||||
- All IDs are numeric, not strings
|
||||
|
||||
**Status Values**:
|
||||
- Subscriber statuses: 'active', 'inactive', 'cancelled'
|
||||
- Some operations are restricted by status (e.g., sorting by cancelled_at requires status='cancelled')
|
||||
|
||||
**String vs Boolean Parameters**:
|
||||
- `include_total_count` is a string 'true', not a boolean true
|
||||
- `sort_order` is a string enum: 'asc' or 'desc'
|
||||
|
||||
**Rate Limits**:
|
||||
- Kit API has per-account rate limits
|
||||
- Implement backoff on 429 responses
|
||||
- Bulk operations should be paced appropriately
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` or `data.data`
|
||||
- Parse defensively with fallback patterns
|
||||
- Cursor values are opaque strings; use exactly as returned
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List subscribers | KIT_LIST_SUBSCRIBERS | status, email_address, per_page |
|
||||
| Tag subscriber | KIT_TAG_SUBSCRIBER | tag_id, subscriber_id |
|
||||
| List tag subscribers | KIT_LIST_TAG_SUBSCRIBERS | tag_id |
|
||||
| Unsubscribe | KIT_DELETE_SUBSCRIBER | id |
|
||||
| List broadcasts | KIT_LIST_BROADCASTS | per_page, after |
|
||||
| Get broadcast | KIT_GET_BROADCAST | id |
|
||||
| Get broadcast stats | KIT_GET_BROADCAST_STATS | id |
|
||||
| Delete broadcast | KIT_DELETE_BROADCAST | id |
|
||||
@@ -1,235 +0,0 @@
|
||||
---
|
||||
name: datadog-automation
|
||||
description: "Automate Datadog tasks via Rube MCP (Composio): query metrics, search logs, manage monitors/dashboards, create events and downtimes. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Datadog Automation via Rube MCP
|
||||
|
||||
Automate Datadog monitoring and observability operations through Composio's Datadog toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Datadog connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `datadog`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `datadog`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Datadog authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Query and Explore Metrics
|
||||
|
||||
**When to use**: User wants to query metric data or list available metrics
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DATADOG_LIST_METRICS` - List available metric names [Optional]
|
||||
2. `DATADOG_QUERY_METRICS` - Query metric time series data [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: Datadog metric query string (e.g., `avg:system.cpu.user{host:web01}`)
|
||||
- `from`: Start timestamp (Unix epoch seconds)
|
||||
- `to`: End timestamp (Unix epoch seconds)
|
||||
- `q`: Search string for listing metrics
|
||||
|
||||
**Pitfalls**:
|
||||
- Query syntax follows Datadog's metric query format: `aggregation:metric_name{tag_filters}`
|
||||
- `from` and `to` are Unix epoch timestamps in seconds, not milliseconds
|
||||
- Valid aggregations: `avg`, `sum`, `min`, `max`, `count`
|
||||
- Tag filters use curly braces: `{host:web01,env:prod}`
|
||||
- Time range should not exceed Datadog's retention limits for the metric type
|
||||
|
||||
### 2. Search and Analyze Logs
|
||||
|
||||
**When to use**: User wants to search log entries or list log indexes
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DATADOG_LIST_LOG_INDEXES` - List available log indexes [Optional]
|
||||
2. `DATADOG_SEARCH_LOGS` - Search logs with query and filters [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: Log search query using Datadog log query syntax
|
||||
- `from`: Start time (ISO 8601 or Unix timestamp)
|
||||
- `to`: End time (ISO 8601 or Unix timestamp)
|
||||
- `sort`: Sort order ('asc' or 'desc')
|
||||
- `limit`: Number of log entries to return
|
||||
|
||||
**Pitfalls**:
|
||||
- Log queries use Datadog's log search syntax: `service:web status:error`
|
||||
- Search is limited to retained logs within the configured retention period
|
||||
- Large result sets require pagination; check for cursor/page tokens
|
||||
- Log indexes control routing and retention; filter by index if known
|
||||
|
||||
### 3. Manage Monitors
|
||||
|
||||
**When to use**: User wants to create, update, mute, or inspect monitors
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DATADOG_LIST_MONITORS` - List all monitors with filters [Required]
|
||||
2. `DATADOG_GET_MONITOR` - Get specific monitor details [Optional]
|
||||
3. `DATADOG_CREATE_MONITOR` - Create a new monitor [Optional]
|
||||
4. `DATADOG_UPDATE_MONITOR` - Update monitor configuration [Optional]
|
||||
5. `DATADOG_MUTE_MONITOR` - Silence a monitor temporarily [Optional]
|
||||
6. `DATADOG_UNMUTE_MONITOR` - Re-enable a muted monitor [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `monitor_id`: Numeric monitor ID
|
||||
- `name`: Monitor display name
|
||||
- `type`: Monitor type ('metric alert', 'service check', 'log alert', 'query alert', etc.)
|
||||
- `query`: Monitor query defining the alert condition
|
||||
- `message`: Notification message with @mentions
|
||||
- `tags`: Array of tag strings
|
||||
- `thresholds`: Alert threshold values (`critical`, `warning`, `ok`)
|
||||
|
||||
**Pitfalls**:
|
||||
- Monitor `type` must match the query type; mismatches cause creation failures
|
||||
- `message` supports @mentions for notifications (e.g., `@slack-channel`, `@pagerduty`)
|
||||
- Thresholds vary by monitor type; metric monitors need `critical` at minimum
|
||||
- Muting a monitor suppresses notifications but the monitor still evaluates
|
||||
- Monitor IDs are numeric integers
|
||||
|
||||
### 4. Manage Dashboards
|
||||
|
||||
**When to use**: User wants to list, view, update, or delete dashboards
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DATADOG_LIST_DASHBOARDS` - List all dashboards [Required]
|
||||
2. `DATADOG_GET_DASHBOARD` - Get full dashboard definition [Optional]
|
||||
3. `DATADOG_UPDATE_DASHBOARD` - Update dashboard layout or widgets [Optional]
|
||||
4. `DATADOG_DELETE_DASHBOARD` - Remove a dashboard (irreversible) [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `dashboard_id`: Dashboard identifier string
|
||||
- `title`: Dashboard title
|
||||
- `layout_type`: 'ordered' (grid) or 'free' (freeform positioning)
|
||||
- `widgets`: Array of widget definition objects
|
||||
- `description`: Dashboard description
|
||||
|
||||
**Pitfalls**:
|
||||
- Dashboard IDs are alphanumeric strings (e.g., 'abc-def-ghi'), not numeric
|
||||
- `layout_type` cannot be changed after creation; must recreate the dashboard
|
||||
- Widget definitions are complex nested objects; get existing dashboard first to understand structure
|
||||
- DELETE is permanent; there is no undo
|
||||
|
||||
### 5. Create Events and Manage Downtimes
|
||||
|
||||
**When to use**: User wants to post events or schedule maintenance downtimes
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DATADOG_LIST_EVENTS` - List existing events [Optional]
|
||||
2. `DATADOG_CREATE_EVENT` - Post a new event [Required]
|
||||
3. `DATADOG_CREATE_DOWNTIME` - Schedule a maintenance downtime [Optional]
|
||||
|
||||
**Key parameters for events**:
|
||||
- `title`: Event title
|
||||
- `text`: Event body text (supports markdown)
|
||||
- `alert_type`: Event severity ('error', 'warning', 'info', 'success')
|
||||
- `tags`: Array of tag strings
|
||||
|
||||
**Key parameters for downtimes**:
|
||||
- `scope`: Tag scope for the downtime (e.g., `host:web01`)
|
||||
- `start`: Start time (Unix epoch)
|
||||
- `end`: End time (Unix epoch; omit for indefinite)
|
||||
- `message`: Downtime description
|
||||
- `monitor_id`: Specific monitor to downtime (optional, omit for scope-based)
|
||||
|
||||
**Pitfalls**:
|
||||
- Event `text` supports Datadog's markdown format including @mentions
|
||||
- Downtimes scope uses tag syntax: `host:web01`, `env:staging`
|
||||
- Omitting `end` creates an indefinite downtime; always set an end time for maintenance
|
||||
- Downtime `monitor_id` narrows to a single monitor; scope applies to all matching monitors
|
||||
|
||||
### 6. Manage Hosts and Traces
|
||||
|
||||
**When to use**: User wants to list infrastructure hosts or inspect distributed traces
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DATADOG_LIST_HOSTS` - List all reporting hosts [Required]
|
||||
2. `DATADOG_GET_TRACE_BY_ID` - Get a specific distributed trace [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `filter`: Host search filter string
|
||||
- `sort_field`: Sort hosts by field (e.g., 'name', 'apps', 'cpu')
|
||||
- `sort_dir`: Sort direction ('asc' or 'desc')
|
||||
- `trace_id`: Distributed trace ID for trace lookup
|
||||
|
||||
**Pitfalls**:
|
||||
- Host list includes all hosts reporting to Datadog within the retention window
|
||||
- Trace IDs are long numeric strings; ensure exact match
|
||||
- Hosts that stop reporting are retained for a configured period before removal
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Monitor Query Syntax
|
||||
|
||||
**Metric alerts**:
|
||||
```
|
||||
avg(last_5m):avg:system.cpu.user{env:prod} > 90
|
||||
```
|
||||
|
||||
**Log alerts**:
|
||||
```
|
||||
logs("service:web status:error").index("main").rollup("count").last("5m") > 10
|
||||
```
|
||||
|
||||
### Tag Filtering
|
||||
|
||||
- Tags use `key:value` format: `host:web01`, `env:prod`, `service:api`
|
||||
- Multiple tags: `{host:web01,env:prod}` (AND logic)
|
||||
- Wildcard: `host:web*`
|
||||
|
||||
### Pagination
|
||||
|
||||
- Use `page` and `page_size` or offset-based pagination depending on endpoint
|
||||
- Check response for total count to determine if more pages exist
|
||||
- Continue until all results are retrieved
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Timestamps**:
|
||||
- Most endpoints use Unix epoch seconds (not milliseconds)
|
||||
- Some endpoints accept ISO 8601; check tool schema
|
||||
- Time ranges should be reasonable (not years of data)
|
||||
|
||||
**Query Syntax**:
|
||||
- Metric queries: `aggregation:metric{tags}`
|
||||
- Log queries: `field:value` pairs
|
||||
- Monitor queries vary by type; check Datadog documentation
|
||||
|
||||
**Rate Limits**:
|
||||
- Datadog API has per-endpoint rate limits
|
||||
- Implement backoff on 429 responses
|
||||
- Batch operations where possible
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Query metrics | DATADOG_QUERY_METRICS | query, from, to |
|
||||
| List metrics | DATADOG_LIST_METRICS | q |
|
||||
| Search logs | DATADOG_SEARCH_LOGS | query, from, to, limit |
|
||||
| List log indexes | DATADOG_LIST_LOG_INDEXES | (none) |
|
||||
| List monitors | DATADOG_LIST_MONITORS | tags |
|
||||
| Get monitor | DATADOG_GET_MONITOR | monitor_id |
|
||||
| Create monitor | DATADOG_CREATE_MONITOR | name, type, query, message |
|
||||
| Update monitor | DATADOG_UPDATE_MONITOR | monitor_id |
|
||||
| Mute monitor | DATADOG_MUTE_MONITOR | monitor_id |
|
||||
| Unmute monitor | DATADOG_UNMUTE_MONITOR | monitor_id |
|
||||
| List dashboards | DATADOG_LIST_DASHBOARDS | (none) |
|
||||
| Get dashboard | DATADOG_GET_DASHBOARD | dashboard_id |
|
||||
| Update dashboard | DATADOG_UPDATE_DASHBOARD | dashboard_id, title, widgets |
|
||||
| Delete dashboard | DATADOG_DELETE_DASHBOARD | dashboard_id |
|
||||
| List events | DATADOG_LIST_EVENTS | start, end |
|
||||
| Create event | DATADOG_CREATE_EVENT | title, text, alert_type |
|
||||
| Create downtime | DATADOG_CREATE_DOWNTIME | scope, start, end |
|
||||
| List hosts | DATADOG_LIST_HOSTS | filter, sort_field |
|
||||
| Get trace | DATADOG_GET_TRACE_BY_ID | trace_id |
|
||||
@@ -1,187 +0,0 @@
|
||||
---
|
||||
name: discord-automation
|
||||
description: "Automate Discord tasks via Rube MCP (Composio): messages, channels, roles, webhooks, reactions. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Discord Automation via Rube MCP
|
||||
|
||||
Automate Discord operations through Composio's Discord/Discordbot toolkits via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Discord connection via `RUBE_MANAGE_CONNECTIONS` with toolkits `discord` and `discordbot`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `discordbot` (bot operations) or `discord` (user operations)
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Discord auth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Send Messages
|
||||
|
||||
**When to use**: User wants to send messages to channels or DMs
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DISCORD_LIST_MY_GUILDS` - List guilds the bot belongs to [Prerequisite]
|
||||
2. `DISCORDBOT_LIST_GUILD_CHANNELS` - List channels in a guild [Prerequisite]
|
||||
3. `DISCORDBOT_CREATE_MESSAGE` - Send a message [Required]
|
||||
4. `DISCORDBOT_UPDATE_MESSAGE` - Edit a sent message [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `channel_id`: Channel snowflake ID
|
||||
- `content`: Message text (max 2000 characters)
|
||||
- `embeds`: Array of embed objects for rich content
|
||||
- `guild_id`: Guild ID for channel listing
|
||||
|
||||
**Pitfalls**:
|
||||
- Bot must have SEND_MESSAGES permission in the channel
|
||||
- High-frequency sends can hit per-route rate limits; respect Retry-After headers
|
||||
- Only messages sent by the same bot can be edited
|
||||
|
||||
### 2. Send Direct Messages
|
||||
|
||||
**When to use**: User wants to DM a Discord user
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DISCORDBOT_CREATE_DM` - Create or get DM channel [Required]
|
||||
2. `DISCORDBOT_CREATE_MESSAGE` - Send message to DM channel [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `recipient_id`: User snowflake ID for DM
|
||||
- `channel_id`: DM channel ID from CREATE_DM
|
||||
|
||||
**Pitfalls**:
|
||||
- Cannot DM users who have DMs disabled or have blocked the bot
|
||||
- CREATE_DM returns existing channel if one already exists
|
||||
|
||||
### 3. Manage Roles
|
||||
|
||||
**When to use**: User wants to create, assign, or remove roles
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DISCORDBOT_CREATE_GUILD_ROLE` - Create a new role [Optional]
|
||||
2. `DISCORDBOT_ADD_GUILD_MEMBER_ROLE` - Assign role to member [Optional]
|
||||
3. `DISCORDBOT_DELETE_GUILD_ROLE` - Delete a role [Optional]
|
||||
4. `DISCORDBOT_GET_GUILD_MEMBER` - Get member details [Optional]
|
||||
5. `DISCORDBOT_UPDATE_GUILD_MEMBER` - Update member (roles, nick, etc.) [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `guild_id`: Guild snowflake ID
|
||||
- `user_id`: User snowflake ID
|
||||
- `role_id`: Role snowflake ID
|
||||
- `name`: Role name
|
||||
- `permissions`: Bitwise permission value
|
||||
- `color`: RGB color integer
|
||||
|
||||
**Pitfalls**:
|
||||
- Role assignment requires MANAGE_ROLES permission
|
||||
- Target role must be lower in hierarchy than bot's highest role
|
||||
- DELETE permanently removes the role from all members
|
||||
|
||||
### 4. Manage Webhooks
|
||||
|
||||
**When to use**: User wants to create or use webhooks for external integrations
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DISCORDBOT_GET_GUILD_WEBHOOKS` / `DISCORDBOT_LIST_CHANNEL_WEBHOOKS` - List webhooks [Optional]
|
||||
2. `DISCORDBOT_CREATE_WEBHOOK` - Create a new webhook [Optional]
|
||||
3. `DISCORDBOT_EXECUTE_WEBHOOK` - Send message via webhook [Optional]
|
||||
4. `DISCORDBOT_UPDATE_WEBHOOK` - Update webhook settings [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `webhook_id`: Webhook ID
|
||||
- `webhook_token`: Webhook secret token
|
||||
- `channel_id`: Channel for webhook creation
|
||||
- `name`: Webhook name
|
||||
- `content`/`embeds`: Message content for execution
|
||||
|
||||
**Pitfalls**:
|
||||
- Webhook tokens are secrets; handle securely
|
||||
- Webhooks can post with custom username and avatar per message
|
||||
- MANAGE_WEBHOOKS permission required for creation
|
||||
|
||||
### 5. Manage Reactions
|
||||
|
||||
**When to use**: User wants to view or manage message reactions
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DISCORDBOT_LIST_MESSAGE_REACTIONS_BY_EMOJI` - List users who reacted [Optional]
|
||||
2. `DISCORDBOT_DELETE_ALL_MESSAGE_REACTIONS` - Remove all reactions [Optional]
|
||||
3. `DISCORDBOT_DELETE_ALL_MESSAGE_REACTIONS_BY_EMOJI` - Remove specific emoji reactions [Optional]
|
||||
4. `DISCORDBOT_DELETE_USER_MESSAGE_REACTION` - Remove specific user's reaction [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `channel_id`: Channel ID
|
||||
- `message_id`: Message snowflake ID
|
||||
- `emoji_name`: URL-encoded emoji or `name:id` for custom emojis
|
||||
- `user_id`: User ID for specific reaction removal
|
||||
|
||||
**Pitfalls**:
|
||||
- Unicode emojis must be URL-encoded (e.g., '%F0%9F%91%8D' for thumbs up)
|
||||
- Custom emojis use `name:id` format
|
||||
- DELETE_ALL requires MANAGE_MESSAGES permission
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Snowflake IDs
|
||||
|
||||
Discord uses snowflake IDs (64-bit integers as strings) for all entities:
|
||||
- Guilds, channels, users, roles, messages, webhooks
|
||||
|
||||
### Permission Bitfields
|
||||
|
||||
Permissions are combined using bitwise OR:
|
||||
- SEND_MESSAGES = 0x800
|
||||
- MANAGE_ROLES = 0x10000000
|
||||
- MANAGE_MESSAGES = 0x2000
|
||||
- ADMINISTRATOR = 0x8
|
||||
|
||||
### Pagination
|
||||
|
||||
- Most list endpoints support `limit`, `before`, `after` parameters
|
||||
- Messages: max 100 per request
|
||||
- Reactions: max 100 per request, use `after` for pagination
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Bot vs User Tokens**:
|
||||
- `discordbot` toolkit uses bot tokens; `discord` uses user OAuth
|
||||
- Bot operations are preferred for automation
|
||||
|
||||
**Rate Limits**:
|
||||
- Discord enforces per-route rate limits
|
||||
- Respect `Retry-After` headers on 429 responses
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List guilds | DISCORD_LIST_MY_GUILDS | (none) |
|
||||
| List channels | DISCORDBOT_LIST_GUILD_CHANNELS | guild_id |
|
||||
| Send message | DISCORDBOT_CREATE_MESSAGE | channel_id, content |
|
||||
| Edit message | DISCORDBOT_UPDATE_MESSAGE | channel_id, message_id |
|
||||
| Get messages | DISCORDBOT_LIST_MESSAGES | channel_id, limit |
|
||||
| Create DM | DISCORDBOT_CREATE_DM | recipient_id |
|
||||
| Create role | DISCORDBOT_CREATE_GUILD_ROLE | guild_id, name |
|
||||
| Assign role | DISCORDBOT_ADD_GUILD_MEMBER_ROLE | guild_id, user_id, role_id |
|
||||
| Delete role | DISCORDBOT_DELETE_GUILD_ROLE | guild_id, role_id |
|
||||
| Get member | DISCORDBOT_GET_GUILD_MEMBER | guild_id, user_id |
|
||||
| Update member | DISCORDBOT_UPDATE_GUILD_MEMBER | guild_id, user_id |
|
||||
| Get guild | DISCORDBOT_GET_GUILD | guild_id |
|
||||
| Create webhook | DISCORDBOT_CREATE_WEBHOOK | channel_id, name |
|
||||
| Execute webhook | DISCORDBOT_EXECUTE_WEBHOOK | webhook_id, webhook_token |
|
||||
| List webhooks | DISCORDBOT_GET_GUILD_WEBHOOKS | guild_id |
|
||||
| Get reactions | DISCORDBOT_LIST_MESSAGE_REACTIONS_BY_EMOJI | channel_id, message_id, emoji_name |
|
||||
| Clear reactions | DISCORDBOT_DELETE_ALL_MESSAGE_REACTIONS | channel_id, message_id |
|
||||
| Test auth | DISCORDBOT_TEST_AUTH | (none) |
|
||||
| Get channel | DISCORDBOT_GET_CHANNEL | channel_id |
|
||||
@@ -1,208 +0,0 @@
|
||||
---
|
||||
name: docusign-automation
|
||||
description: "Automate DocuSign tasks via Rube MCP (Composio): templates, envelopes, signatures, document management. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# DocuSign Automation via Rube MCP
|
||||
|
||||
Automate DocuSign e-signature workflows through Composio's DocuSign toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active DocuSign connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `docusign`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `docusign`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete DocuSign OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Browse and Select Templates
|
||||
|
||||
**When to use**: User wants to find available document templates for sending
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DOCUSIGN_LIST_ALL_TEMPLATES` - List all available templates [Required]
|
||||
2. `DOCUSIGN_GET_TEMPLATE` - Get detailed template information [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- For listing: Optional search/filter parameters
|
||||
- For details: `templateId` (from list results)
|
||||
- Response includes template `templateId`, `name`, `description`, roles, and fields
|
||||
|
||||
**Pitfalls**:
|
||||
- Template IDs are GUIDs (e.g., '12345678-abcd-1234-efgh-123456789012')
|
||||
- Templates define recipient roles with signing tabs; understand roles before creating envelopes
|
||||
- Large template libraries require pagination; check for continuation tokens
|
||||
- Template access depends on account permissions
|
||||
|
||||
### 2. Create and Send Envelopes from Templates
|
||||
|
||||
**When to use**: User wants to send documents for signature using a pre-built template
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DOCUSIGN_LIST_ALL_TEMPLATES` - Find the template to use [Prerequisite]
|
||||
2. `DOCUSIGN_GET_TEMPLATE` - Review template roles and fields [Optional]
|
||||
3. `DOCUSIGN_CREATE_ENVELOPE_FROM_TEMPLATE` - Create the envelope [Required]
|
||||
4. `DOCUSIGN_SEND_ENVELOPE` - Send the envelope for signing [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- For CREATE_ENVELOPE_FROM_TEMPLATE:
|
||||
- `templateId`: Template to use
|
||||
- `templateRoles`: Array of role assignments with `roleName`, `name`, `email`
|
||||
- `status`: 'created' (draft) or 'sent' (send immediately)
|
||||
- `emailSubject`: Custom subject line for the signing email
|
||||
- `emailBlurb`: Custom message in the signing email
|
||||
- For SEND_ENVELOPE:
|
||||
- `envelopeId`: Envelope ID from creation response
|
||||
|
||||
**Pitfalls**:
|
||||
- `templateRoles` must match the role names defined in the template exactly (case-sensitive)
|
||||
- Setting `status` to 'sent' during creation sends immediately; use 'created' for drafts
|
||||
- If status is 'sent' at creation, no need to call SEND_ENVELOPE separately
|
||||
- Each role requires at minimum `roleName`, `name`, and `email`
|
||||
- `emailSubject` overrides the template's default email subject
|
||||
|
||||
### 3. Monitor Envelope Status
|
||||
|
||||
**When to use**: User wants to check the status of sent envelopes or track signing progress
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DOCUSIGN_GET_ENVELOPE` - Get envelope details and status [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `envelopeId`: Envelope identifier (GUID)
|
||||
- Response includes `status`, `recipients`, `sentDateTime`, `completedDateTime`
|
||||
|
||||
**Pitfalls**:
|
||||
- Envelope statuses: 'created', 'sent', 'delivered', 'signed', 'completed', 'declined', 'voided'
|
||||
- 'delivered' means the email was opened, not that the document was signed
|
||||
- 'completed' means all recipients have signed
|
||||
- Recipients array shows individual signing status per recipient
|
||||
- Envelope IDs are GUIDs; always resolve from creation or search results
|
||||
|
||||
### 4. Add Templates to Existing Envelopes
|
||||
|
||||
**When to use**: User wants to add additional documents or templates to an existing envelope
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DOCUSIGN_GET_ENVELOPE` - Verify envelope exists and is in draft state [Prerequisite]
|
||||
2. `DOCUSIGN_ADD_TEMPLATES_TO_DOCUMENT_IN_ENVELOPE` - Add template to envelope [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `envelopeId`: Target envelope ID
|
||||
- `documentId`: Document ID within the envelope
|
||||
- `templateId`: Template to add
|
||||
|
||||
**Pitfalls**:
|
||||
- Envelope must be in 'created' (draft) status to add templates
|
||||
- Cannot add templates to already-sent envelopes
|
||||
- Document IDs are sequential within an envelope (starting from '1')
|
||||
- Adding a template merges its fields and roles into the existing envelope
|
||||
|
||||
### 5. Manage Envelope Lifecycle
|
||||
|
||||
**When to use**: User wants to send, void, or manage draft envelopes
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DOCUSIGN_GET_ENVELOPE` - Check current envelope status [Prerequisite]
|
||||
2. `DOCUSIGN_SEND_ENVELOPE` - Send a draft envelope [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `envelopeId`: Envelope to manage
|
||||
- For sending: envelope must be in 'created' status with all required recipients
|
||||
|
||||
**Pitfalls**:
|
||||
- Only 'created' (draft) envelopes can be sent
|
||||
- Sent envelopes cannot be unsent; they can only be voided
|
||||
- Voiding an envelope notifies all recipients
|
||||
- All required recipients must have valid email addresses before sending
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Template name -> Template ID**:
|
||||
```
|
||||
1. Call DOCUSIGN_LIST_ALL_TEMPLATES
|
||||
2. Find template by name in results
|
||||
3. Extract templateId (GUID format)
|
||||
```
|
||||
|
||||
**Envelope tracking**:
|
||||
```
|
||||
1. Store envelopeId from CREATE_ENVELOPE_FROM_TEMPLATE response
|
||||
2. Call DOCUSIGN_GET_ENVELOPE periodically to check status
|
||||
3. Check recipient-level status for individual signing progress
|
||||
```
|
||||
|
||||
### Template Role Mapping
|
||||
|
||||
When creating an envelope from a template:
|
||||
```
|
||||
1. Call DOCUSIGN_GET_TEMPLATE to see defined roles
|
||||
2. Map each role to actual recipients:
|
||||
{
|
||||
"roleName": "Signer 1", // Must match template role name exactly
|
||||
"name": "John Smith",
|
||||
"email": "john@example.com"
|
||||
}
|
||||
3. Include ALL required roles in templateRoles array
|
||||
```
|
||||
|
||||
### Envelope Status Flow
|
||||
|
||||
```
|
||||
created (draft) -> sent -> delivered -> signed -> completed
|
||||
\-> declined
|
||||
\-> voided (by sender)
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Template Roles**:
|
||||
- Role names are case-sensitive; must match template definition exactly
|
||||
- All required roles must be assigned when creating an envelope
|
||||
- Missing role assignments cause envelope creation to fail
|
||||
|
||||
**Envelope Status**:
|
||||
- 'delivered' means email opened, NOT document signed
|
||||
- 'completed' is the final successful state (all parties signed)
|
||||
- Status transitions are one-way; cannot revert to previous states
|
||||
|
||||
**GUIDs**:
|
||||
- All DocuSign IDs (templates, envelopes) are GUID format
|
||||
- Always resolve names to GUIDs via list/search endpoints
|
||||
- Do not hardcode GUIDs; they are unique per account
|
||||
|
||||
**Rate Limits**:
|
||||
- DocuSign API has per-account rate limits
|
||||
- Bulk envelope creation should be throttled
|
||||
- Polling envelope status should use reasonable intervals (30-60 seconds)
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` key
|
||||
- Recipient information is nested within envelope response
|
||||
- Date fields use ISO 8601 format
|
||||
- Parse defensively with fallbacks for optional fields
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List templates | DOCUSIGN_LIST_ALL_TEMPLATES | (optional filters) |
|
||||
| Get template | DOCUSIGN_GET_TEMPLATE | templateId |
|
||||
| Create envelope | DOCUSIGN_CREATE_ENVELOPE_FROM_TEMPLATE | templateId, templateRoles, status |
|
||||
| Send envelope | DOCUSIGN_SEND_ENVELOPE | envelopeId |
|
||||
| Get envelope status | DOCUSIGN_GET_ENVELOPE | envelopeId |
|
||||
| Add template to envelope | DOCUSIGN_ADD_TEMPLATES_TO_DOCUMENT_IN_ENVELOPE | envelopeId, documentId, templateId |
|
||||
@@ -1,266 +0,0 @@
|
||||
---
|
||||
name: dotnet-backend
|
||||
description: Build ASP.NET Core 8+ backend services with EF Core, auth, background jobs, and production API patterns.
|
||||
risk: safe
|
||||
source: self
|
||||
allowed-tools: Read, Write, Edit, Bash
|
||||
model: opus
|
||||
---
|
||||
|
||||
# .NET Backend Agent - ASP.NET Core & Enterprise API Expert
|
||||
|
||||
You are an expert .NET/C# backend developer with 8+ years of experience building enterprise-grade APIs and services.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when the user asks to:
|
||||
|
||||
- Build or refactor ASP.NET Core APIs (controller-based or Minimal APIs)
|
||||
- Implement authentication/authorization in a .NET backend
|
||||
- Design or optimize EF Core data access patterns
|
||||
- Add background workers, scheduled jobs, or integration services in C#
|
||||
- Improve reliability/performance of a .NET backend service
|
||||
|
||||
## Your Expertise
|
||||
|
||||
- **Frameworks**: ASP.NET Core 8+, Minimal APIs, Web API
|
||||
- **ORM**: Entity Framework Core 8+, Dapper
|
||||
- **Databases**: SQL Server, PostgreSQL, MySQL
|
||||
- **Authentication**: ASP.NET Core Identity, JWT, OAuth 2.0, Azure AD
|
||||
- **Authorization**: Policy-based, role-based, claims-based
|
||||
- **API Patterns**: RESTful, gRPC, GraphQL (HotChocolate)
|
||||
- **Background**: IHostedService, BackgroundService, Hangfire
|
||||
- **Real-time**: SignalR
|
||||
- **Testing**: xUnit, NUnit, Moq, FluentAssertions
|
||||
- **Dependency Injection**: Built-in DI container
|
||||
- **Validation**: FluentValidation, Data Annotations
|
||||
|
||||
## Your Responsibilities
|
||||
|
||||
1. **Build ASP.NET Core APIs**
|
||||
- RESTful controllers or Minimal APIs
|
||||
- Model validation
|
||||
- Exception handling middleware
|
||||
- CORS configuration
|
||||
- Response compression
|
||||
|
||||
2. **Entity Framework Core**
|
||||
- DbContext configuration
|
||||
- Code-first migrations
|
||||
- Query optimization
|
||||
- Include/ThenInclude for eager loading
|
||||
- AsNoTracking for read-only queries
|
||||
|
||||
3. **Authentication & Authorization**
|
||||
- JWT token generation/validation
|
||||
- ASP.NET Core Identity integration
|
||||
- Policy-based authorization
|
||||
- Custom authorization handlers
|
||||
|
||||
4. **Background Services**
|
||||
- IHostedService for long-running tasks
|
||||
- Scoped services in background workers
|
||||
- Scheduled jobs with Hangfire/Quartz.NET
|
||||
|
||||
5. **Performance**
|
||||
- Async/await throughout
|
||||
- Connection pooling
|
||||
- Response caching
|
||||
- Output caching (.NET 8+)
|
||||
|
||||
## Code Patterns You Follow
|
||||
|
||||
### Minimal API with EF Core
|
||||
```csharp
|
||||
using Microsoft.EntityFrameworkCore;
|
||||
|
||||
var builder = WebApplication.CreateBuilder(args);
|
||||
|
||||
// Services
|
||||
builder.Services.AddDbContext<AppDbContext>(options =>
|
||||
options.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection")));
|
||||
|
||||
builder.Services.AddAuthentication().AddJwtBearer();
|
||||
builder.Services.AddAuthorization();
|
||||
|
||||
var app = builder.Build();
|
||||
|
||||
// Create user endpoint
|
||||
app.MapPost("/api/users", async (CreateUserRequest request, AppDbContext db) =>
|
||||
{
|
||||
// Validate
|
||||
if (string.IsNullOrEmpty(request.Email))
|
||||
return Results.BadRequest("Email is required");
|
||||
|
||||
// Hash password
|
||||
var hashedPassword = BCrypt.Net.BCrypt.HashPassword(request.Password);
|
||||
|
||||
// Create user
|
||||
var user = new User
|
||||
{
|
||||
Email = request.Email,
|
||||
PasswordHash = hashedPassword,
|
||||
Name = request.Name
|
||||
};
|
||||
|
||||
db.Users.Add(user);
|
||||
await db.SaveChangesAsync();
|
||||
|
||||
return Results.Created($"/api/users/{user.Id}", new UserResponse(user));
|
||||
})
|
||||
.WithName("CreateUser")
|
||||
.WithOpenApi();
|
||||
|
||||
app.Run();
|
||||
|
||||
record CreateUserRequest(string Email, string Password, string Name);
|
||||
record UserResponse(int Id, string Email, string Name);
|
||||
```
|
||||
|
||||
### Controller-based API
|
||||
```csharp
|
||||
[ApiController]
|
||||
[Route("api/[controller]")]
|
||||
public class UsersController : ControllerBase
|
||||
{
|
||||
private readonly AppDbContext _db;
|
||||
private readonly ILogger<UsersController> _logger;
|
||||
|
||||
public UsersController(AppDbContext db, ILogger<UsersController> logger)
|
||||
{
|
||||
_db = db;
|
||||
_logger = logger;
|
||||
}
|
||||
|
||||
[HttpGet]
|
||||
public async Task<ActionResult<List<UserDto>>> GetUsers()
|
||||
{
|
||||
var users = await _db.Users
|
||||
.AsNoTracking()
|
||||
.Select(u => new UserDto(u.Id, u.Email, u.Name))
|
||||
.ToListAsync();
|
||||
|
||||
return Ok(users);
|
||||
}
|
||||
|
||||
[HttpPost]
|
||||
public async Task<ActionResult<UserDto>> CreateUser(CreateUserDto dto)
|
||||
{
|
||||
var user = new User
|
||||
{
|
||||
Email = dto.Email,
|
||||
PasswordHash = BCrypt.Net.BCrypt.HashPassword(dto.Password),
|
||||
Name = dto.Name
|
||||
};
|
||||
|
||||
_db.Users.Add(user);
|
||||
await _db.SaveChangesAsync();
|
||||
|
||||
return CreatedAtAction(nameof(GetUser), new { id = user.Id }, new UserDto(user));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### JWT Authentication
|
||||
```csharp
|
||||
using Microsoft.IdentityModel.Tokens;
|
||||
using System.IdentityModel.Tokens.Jwt;
|
||||
using System.Security.Claims;
|
||||
using System.Text;
|
||||
|
||||
public class TokenService
|
||||
{
|
||||
private readonly IConfiguration _config;
|
||||
|
||||
public TokenService(IConfiguration config) => _config = config;
|
||||
|
||||
public string GenerateToken(User user)
|
||||
{
|
||||
var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_config["Jwt:Key"]!));
|
||||
var credentials = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);
|
||||
|
||||
var claims = new[]
|
||||
{
|
||||
new Claim(ClaimTypes.NameIdentifier, user.Id.ToString()),
|
||||
new Claim(ClaimTypes.Email, user.Email),
|
||||
new Claim(ClaimTypes.Name, user.Name)
|
||||
};
|
||||
|
||||
var token = new JwtSecurityToken(
|
||||
issuer: _config["Jwt:Issuer"],
|
||||
audience: _config["Jwt:Audience"],
|
||||
claims: claims,
|
||||
expires: DateTime.UtcNow.AddHours(1),
|
||||
signingCredentials: credentials
|
||||
);
|
||||
|
||||
return new JwtSecurityTokenHandler().WriteToken(token);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Background Service
|
||||
```csharp
|
||||
public class EmailSenderService : BackgroundService
|
||||
{
|
||||
private readonly ILogger<EmailSenderService> _logger;
|
||||
private readonly IServiceProvider _services;
|
||||
|
||||
public EmailSenderService(ILogger<EmailSenderService> logger, IServiceProvider services)
|
||||
{
|
||||
_logger = logger;
|
||||
_services = services;
|
||||
}
|
||||
|
||||
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
|
||||
{
|
||||
while (!stoppingToken.IsCancellationRequested)
|
||||
{
|
||||
using var scope = _services.CreateScope();
|
||||
var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
|
||||
|
||||
var pendingEmails = await db.PendingEmails
|
||||
.Where(e => !e.Sent)
|
||||
.Take(10)
|
||||
.ToListAsync(stoppingToken);
|
||||
|
||||
foreach (var email in pendingEmails)
|
||||
{
|
||||
await SendEmailAsync(email);
|
||||
email.Sent = true;
|
||||
}
|
||||
|
||||
await db.SaveChangesAsync(stoppingToken);
|
||||
await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken);
|
||||
}
|
||||
}
|
||||
|
||||
private async Task SendEmailAsync(PendingEmail email)
|
||||
{
|
||||
// Send email logic
|
||||
_logger.LogInformation("Sending email to {Email}", email.To);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices You Follow
|
||||
|
||||
- ✅ Async/await for all I/O operations
|
||||
- ✅ Dependency Injection for all services
|
||||
- ✅ appsettings.json for configuration
|
||||
- ✅ User Secrets for local development
|
||||
- ✅ Entity Framework migrations (Add-Migration, Update-Database)
|
||||
- ✅ Global exception handling middleware
|
||||
- ✅ FluentValidation for complex validation
|
||||
- ✅ Serilog for structured logging
|
||||
- ✅ Health checks (AddHealthChecks)
|
||||
- ✅ API versioning
|
||||
- ✅ Swagger/OpenAPI documentation
|
||||
- ✅ AutoMapper for DTO mapping
|
||||
- ✅ CQRS with MediatR (for complex domains)
|
||||
|
||||
## Limitations
|
||||
|
||||
- Assumes modern .NET (ASP.NET Core 8+); older .NET Framework projects may require different patterns.
|
||||
- Does not cover client-side/frontend implementations.
|
||||
- Cloud-provider-specific deployment details (Azure/AWS/GCP) are out of scope unless explicitly requested.
|
||||
@@ -1,230 +0,0 @@
|
||||
---
|
||||
name: dropbox-automation
|
||||
description: "Automate Dropbox file management, sharing, search, uploads, downloads, and folder operations via Rube MCP (Composio). Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Dropbox Automation via Rube MCP
|
||||
|
||||
Automate Dropbox operations including file upload/download, search, folder management, sharing links, batch operations, and metadata retrieval through Composio's Dropbox toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Dropbox connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `dropbox`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `dropbox`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Dropbox OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Search for Files and Folders
|
||||
|
||||
**When to use**: User wants to find files or folders by name, content, or type
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DROPBOX_SEARCH_FILE_OR_FOLDER` - Search by query string with optional path scope and filters [Required]
|
||||
2. `DROPBOX_SEARCH_CONTINUE` - Paginate through additional results using cursor [Required if has_more]
|
||||
3. `DROPBOX_GET_METADATA` - Validate and get canonical path for a search result [Optional]
|
||||
4. `DROPBOX_READ_FILE` - Read file content to verify it is the intended document [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: Search string (case-insensitive, 1+ non-whitespace characters)
|
||||
- `options.path`: Scope search to a folder (e.g., `"/Documents"`); empty string for root
|
||||
- `options.file_categories`: Filter by type (`"image"`, `"document"`, `"pdf"`, `"folder"`, etc.)
|
||||
- `options.file_extensions`: Filter by extension (e.g., `["jpg", "png"]`)
|
||||
- `options.filename_only`: Set `true` to match filenames only (not content)
|
||||
- `options.max_results`: Results per page (default 100, max 1000)
|
||||
|
||||
**Pitfalls**:
|
||||
- Search returns `has_more: true` with a `cursor` when more results exist; MUST continue to avoid silently missing matches
|
||||
- Maximum 10,000 matches total across all pages of search + search_continue
|
||||
- `DROPBOX_GET_METADATA` returned `path_display` may differ in casing from user input; always use the returned canonical path
|
||||
- File content from `DROPBOX_READ_FILE` may be returned as base64-encoded `file_content_bytes`; decode before parsing
|
||||
|
||||
### 2. Upload and Download Files
|
||||
|
||||
**When to use**: User wants to upload files to Dropbox or download files from it
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DROPBOX_UPLOAD_FILE` - Upload a file to a specified path [Required for upload]
|
||||
2. `DROPBOX_READ_FILE` - Download/read a file from Dropbox [Required for download]
|
||||
3. `DROPBOX_DOWNLOAD_ZIP` - Download an entire folder as a zip file [Optional]
|
||||
4. `DROPBOX_SAVE_URL` - Save a file from a public URL directly to Dropbox [Optional]
|
||||
5. `DROPBOX_GET_SHARED_LINK_FILE` - Download a file from a shared link URL [Optional]
|
||||
6. `DROPBOX_EXPORT_FILE` - Export non-downloadable files like Dropbox Paper to markdown/HTML [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `path`: Dropbox path (must start with `/`, e.g., `"/Documents/report.pdf"`)
|
||||
- `mode`: `"add"` (default, fail on conflict) or `"overwrite"` for uploads
|
||||
- `autorename`: `true` to auto-rename on conflict instead of failing
|
||||
- `content`: FileUploadable object with `s3key`, `mimetype`, and `name` for uploads
|
||||
- `url`: Public URL for `DROPBOX_SAVE_URL`
|
||||
- `export_format`: `"markdown"`, `"html"`, or `"plain_text"` for Paper docs
|
||||
|
||||
**Pitfalls**:
|
||||
- `DROPBOX_SAVE_URL` is asynchronous and may take up to 15 minutes for large files
|
||||
- `DROPBOX_DOWNLOAD_ZIP` folder must be under 20 GB with no single file over 4 GB and fewer than 10,000 entries
|
||||
- `DROPBOX_READ_FILE` content may be base64-encoded; check response format
|
||||
- Shared link downloads via `DROPBOX_GET_SHARED_LINK_FILE` may require `link_password` for protected links
|
||||
|
||||
### 3. Share Files and Manage Links
|
||||
|
||||
**When to use**: User wants to create sharing links or manage existing shared links
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DROPBOX_GET_METADATA` - Confirm file/folder exists and get canonical path [Prerequisite]
|
||||
2. `DROPBOX_LIST_SHARED_LINKS` - Check for existing shared links to avoid duplicates [Prerequisite]
|
||||
3. `DROPBOX_CREATE_SHARED_LINK` - Create a new shared link [Required]
|
||||
4. `DROPBOX_GET_SHARED_LINK_METADATA` - Resolve a shared link URL to metadata [Optional]
|
||||
5. `DROPBOX_LIST_SHARED_FOLDERS` - List all shared folders the user has access to [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `path`: File or folder path for link creation
|
||||
- `settings.audience`: `"public"`, `"team"`, or `"no_one"`
|
||||
- `settings.access`: `"viewer"` or `"editor"`
|
||||
- `settings.expires`: ISO 8601 expiration date (e.g., `"2026-12-31T23:59:59Z"`)
|
||||
- `settings.require_password` / `settings.link_password`: Password protection
|
||||
- `settings.allow_download`: Boolean for download permission
|
||||
- `direct_only`: For `LIST_SHARED_LINKS`, set `true` to only return direct links (not parent folder links)
|
||||
|
||||
**Pitfalls**:
|
||||
- `DROPBOX_CREATE_SHARED_LINK` fails with 409 Conflict if a shared link already exists for the path; check with `DROPBOX_LIST_SHARED_LINKS` first
|
||||
- Always validate path with `DROPBOX_GET_METADATA` before creating links to avoid `path/not_found` errors
|
||||
- Reuse existing links from `DROPBOX_LIST_SHARED_LINKS` instead of creating duplicates
|
||||
- `requested_visibility` is deprecated; use `audience` for newer implementations
|
||||
|
||||
### 4. Manage Folders (Create, Move, Delete)
|
||||
|
||||
**When to use**: User wants to create, move, rename, or delete files and folders
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DROPBOX_CREATE_FOLDER` - Create a single folder [Required for create]
|
||||
2. `DROPBOX_CREATE_FOLDER_BATCH` - Create multiple folders at once [Optional]
|
||||
3. `DROPBOX_MOVE_FILE_OR_FOLDER` - Move or rename a single file/folder [Required for move]
|
||||
4. `DROPBOX_MOVE_BATCH` - Move multiple items at once [Optional]
|
||||
5. `DROPBOX_DELETE_FILE_OR_FOLDER` - Delete a single file or folder [Required for delete]
|
||||
6. `DROPBOX_DELETE_BATCH` - Delete multiple items at once [Optional]
|
||||
7. `DROPBOX_COPY_FILE_OR_FOLDER` - Copy a file or folder to a new location [Optional]
|
||||
8. `DROPBOX_CHECK_MOVE_BATCH` / `DROPBOX_CHECK_FOLDER_BATCH` - Poll async batch job status [Required for batch ops]
|
||||
|
||||
**Key parameters**:
|
||||
- `path`: Target path (must start with `/`, case-sensitive)
|
||||
- `from_path` / `to_path`: Source and destination for move/copy operations
|
||||
- `autorename`: `true` to auto-rename on conflict
|
||||
- `entries`: Array of `{from_path, to_path}` for batch moves; array of paths for batch creates
|
||||
- `allow_shared_folder`: Set `true` to allow moving shared folders
|
||||
- `allow_ownership_transfer`: Set `true` if move changes ownership
|
||||
|
||||
**Pitfalls**:
|
||||
- All paths are case-sensitive and must start with `/`
|
||||
- Paths must NOT end with `/` or whitespace
|
||||
- Batch operations may be asynchronous; poll with `DROPBOX_CHECK_MOVE_BATCH` or `DROPBOX_CHECK_FOLDER_BATCH`
|
||||
- `DROPBOX_FILES_MOVE_BATCH` (v1) has "all or nothing" behavior - if any entry fails, entire batch fails
|
||||
- `DROPBOX_MOVE_BATCH` (v2) is preferred over `DROPBOX_FILES_MOVE_BATCH` (v1)
|
||||
- Maximum 1000 entries per batch delete/move; 10,000 paths per batch folder create
|
||||
- Case-only renaming is not supported in batch move operations
|
||||
|
||||
### 5. List Folder Contents
|
||||
|
||||
**When to use**: User wants to browse or enumerate files in a Dropbox folder
|
||||
|
||||
**Tool sequence**:
|
||||
1. `DROPBOX_LIST_FILES_IN_FOLDER` - List contents of a folder [Required]
|
||||
2. `DROPBOX_LIST_FOLDERS` - Alternative folder listing with deleted entries support [Optional]
|
||||
3. `DROPBOX_GET_METADATA` - Get details for a specific item [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `path`: Folder path (empty string `""` for root)
|
||||
- `recursive`: `true` to list all nested contents
|
||||
- `limit`: Max results per request (default/max 2000)
|
||||
- `include_deleted`: `true` to include deleted but recoverable items
|
||||
- `include_media_info`: `true` to get photo/video metadata
|
||||
|
||||
**Pitfalls**:
|
||||
- Use empty string `""` for root folder, not `"/"`
|
||||
- Recursive listings can be very large; use `limit` to control page size
|
||||
- Results may paginate via cursor even with small limits
|
||||
- `DROPBOX_LIST_FILES_IN_FOLDER` returns 409 Conflict with `path/not_found` for incorrect paths
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
- **Path-based**: Most Dropbox tools use path strings (e.g., `"/Documents/file.pdf"`)
|
||||
- **ID-based**: Some tools accept `id:...` format (e.g., `"id:4g0reWVRsAAAAAAAAAAAQ"`)
|
||||
- **Canonical path**: Always use `path_display` or `path_lower` from `DROPBOX_GET_METADATA` responses for subsequent calls
|
||||
- **Shared link URL**: Use `DROPBOX_GET_SHARED_LINK_METADATA` to resolve URLs to paths/IDs
|
||||
|
||||
### Pagination
|
||||
Dropbox uses cursor-based pagination across most endpoints:
|
||||
- Search: Follow `has_more` + `cursor` with `DROPBOX_SEARCH_CONTINUE` (max 10,000 total matches)
|
||||
- Folder listing: Follow cursor from response until no more pages
|
||||
- Shared links: Follow `has_more` + `cursor` in `DROPBOX_LIST_SHARED_LINKS`
|
||||
- Batch job status: Poll with `DROPBOX_CHECK_MOVE_BATCH` / `DROPBOX_CHECK_FOLDER_BATCH`
|
||||
|
||||
### Async Operations
|
||||
Several Dropbox operations run asynchronously:
|
||||
- `DROPBOX_SAVE_URL` - returns job ID; poll or set `wait: true` (up to 120s default)
|
||||
- `DROPBOX_MOVE_BATCH` / `DROPBOX_FILES_MOVE_BATCH` - may return job ID
|
||||
- `DROPBOX_CREATE_FOLDER_BATCH` - may return job ID
|
||||
- `DROPBOX_DELETE_BATCH` - returns job ID
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
### Path Formats
|
||||
- All paths must start with `/` (except empty string for root in some endpoints)
|
||||
- Paths must NOT end with `/` or contain trailing whitespace
|
||||
- Paths are case-sensitive for write operations
|
||||
- `path_display` from API may differ in casing from user input; always prefer API-returned paths
|
||||
|
||||
### Rate Limits
|
||||
- Dropbox API has per-endpoint rate limits; batch operations help reduce call count
|
||||
- Search is limited to 10,000 total matches across all pagination
|
||||
- `DROPBOX_SAVE_URL` has a 15-minute timeout for large files
|
||||
|
||||
### File Content
|
||||
- `DROPBOX_READ_FILE` may return content as base64-encoded `file_content_bytes`
|
||||
- Non-downloadable files (Dropbox Paper, Google Docs) require `DROPBOX_EXPORT_FILE` instead
|
||||
- Download URLs from shared links require proper authentication headers
|
||||
|
||||
### Sharing
|
||||
- Creating a shared link when one already exists returns a 409 Conflict error
|
||||
- Always check `DROPBOX_LIST_SHARED_LINKS` before creating new links
|
||||
- Shared folder access may not appear in standard path listings; use `DROPBOX_LIST_SHARED_FOLDERS`
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Search files | `DROPBOX_SEARCH_FILE_OR_FOLDER` | `query`, `options.path` |
|
||||
| Continue search | `DROPBOX_SEARCH_CONTINUE` | `cursor` |
|
||||
| List folder | `DROPBOX_LIST_FILES_IN_FOLDER` | `path`, `recursive`, `limit` |
|
||||
| List folders | `DROPBOX_LIST_FOLDERS` | `path`, `recursive` |
|
||||
| Get metadata | `DROPBOX_GET_METADATA` | `path` |
|
||||
| Read/download file | `DROPBOX_READ_FILE` | `path` |
|
||||
| Upload file | `DROPBOX_UPLOAD_FILE` | `path`, `content`, `mode` |
|
||||
| Save URL to Dropbox | `DROPBOX_SAVE_URL` | `path`, `url` |
|
||||
| Download folder zip | `DROPBOX_DOWNLOAD_ZIP` | `path` |
|
||||
| Export Paper doc | `DROPBOX_EXPORT_FILE` | `path`, `export_format` |
|
||||
| Download shared link | `DROPBOX_GET_SHARED_LINK_FILE` | `url` |
|
||||
| Create shared link | `DROPBOX_CREATE_SHARED_LINK` | `path`, `settings` |
|
||||
| List shared links | `DROPBOX_LIST_SHARED_LINKS` | `path`, `direct_only` |
|
||||
| Shared link metadata | `DROPBOX_GET_SHARED_LINK_METADATA` | `url` |
|
||||
| List shared folders | `DROPBOX_LIST_SHARED_FOLDERS` | `limit` |
|
||||
| Create folder | `DROPBOX_CREATE_FOLDER` | `path` |
|
||||
| Create folders batch | `DROPBOX_CREATE_FOLDER_BATCH` | `paths` |
|
||||
| Move file/folder | `DROPBOX_MOVE_FILE_OR_FOLDER` | `from_path`, `to_path` |
|
||||
| Move batch | `DROPBOX_MOVE_BATCH` | `entries` |
|
||||
| Delete file/folder | `DROPBOX_DELETE_FILE_OR_FOLDER` | `path` |
|
||||
| Delete batch | `DROPBOX_DELETE_BATCH` | `entries` |
|
||||
| Copy file/folder | `DROPBOX_COPY_FILE_OR_FOLDER` | `from_path`, `to_path` |
|
||||
| Check batch status | `DROPBOX_CHECK_MOVE_BATCH` | `async_job_id` |
|
||||
@@ -1,181 +0,0 @@
|
||||
---
|
||||
name: figma-automation
|
||||
description: "Automate Figma tasks via Rube MCP (Composio): files, components, design tokens, comments, exports. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Figma Automation via Rube MCP
|
||||
|
||||
Automate Figma operations through Composio's Figma toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Figma connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `figma`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `figma`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Figma auth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Get File Data and Components
|
||||
|
||||
**When to use**: User wants to inspect Figma design files or extract component information
|
||||
|
||||
**Tool sequence**:
|
||||
1. `FIGMA_DISCOVER_FIGMA_RESOURCES` - Extract IDs from Figma URLs [Prerequisite]
|
||||
2. `FIGMA_GET_FILE_JSON` - Get file data (simplified by default) [Required]
|
||||
3. `FIGMA_GET_FILE_NODES` - Get specific node data [Optional]
|
||||
4. `FIGMA_GET_FILE_COMPONENTS` - List published components [Optional]
|
||||
5. `FIGMA_GET_FILE_COMPONENT_SETS` - List component sets [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `file_key`: File key from URL (e.g., 'abc123XYZ' from figma.com/design/abc123XYZ/...)
|
||||
- `ids`: Comma-separated node IDs (NOT an array)
|
||||
- `depth`: Tree traversal depth (2 for pages and top-level children)
|
||||
- `simplify`: True for AI-friendly format (70%+ size reduction)
|
||||
|
||||
**Pitfalls**:
|
||||
- Only supports Design files; FigJam boards and Slides return 400 errors
|
||||
- `ids` must be a comma-separated string, not an array
|
||||
- Node IDs may be dash-formatted (1-541) in URLs but need colon format (1:541) for API
|
||||
- Broad ids/depth can trigger oversized payloads (413); narrow scope or reduce depth
|
||||
- Response data may be in `data_preview` instead of `data`
|
||||
|
||||
### 2. Export and Render Images
|
||||
|
||||
**When to use**: User wants to export design assets as images
|
||||
|
||||
**Tool sequence**:
|
||||
1. `FIGMA_GET_FILE_JSON` - Find node IDs to export [Prerequisite]
|
||||
2. `FIGMA_RENDER_IMAGES_OF_FILE_NODES` - Render nodes as images [Required]
|
||||
3. `FIGMA_DOWNLOAD_FIGMA_IMAGES` - Download rendered images [Optional]
|
||||
4. `FIGMA_GET_IMAGE_FILLS` - Get image fill URLs [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `file_key`: File key
|
||||
- `ids`: Comma-separated node IDs to render
|
||||
- `format`: 'png', 'svg', 'jpg', or 'pdf'
|
||||
- `scale`: Scale factor (0.01-4.0) for PNG/JPG
|
||||
- `images`: Array of {node_id, file_name, format} for downloads
|
||||
|
||||
**Pitfalls**:
|
||||
- Images return as node_id-to-URL map; some IDs may be null (failed renders)
|
||||
- URLs are temporary (valid ~30 days)
|
||||
- Images capped at 32 megapixels; larger requests auto-scaled down
|
||||
|
||||
### 3. Extract Design Tokens
|
||||
|
||||
**When to use**: User wants to extract design tokens for development
|
||||
|
||||
**Tool sequence**:
|
||||
1. `FIGMA_EXTRACT_DESIGN_TOKENS` - Extract colors, typography, spacing [Required]
|
||||
2. `FIGMA_DESIGN_TOKENS_TO_TAILWIND` - Convert to Tailwind config [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `file_key`: File key
|
||||
- `include_local_styles`: Include local styles (default true)
|
||||
- `include_variables`: Include Figma variables
|
||||
- `tokens`: Full tokens object from extraction (for Tailwind conversion)
|
||||
|
||||
**Pitfalls**:
|
||||
- Tailwind conversion requires the full tokens object including total_tokens and sources
|
||||
- Do not strip fields from the extraction response before passing to conversion
|
||||
|
||||
### 4. Manage Comments and Versions
|
||||
|
||||
**When to use**: User wants to view or add comments, or inspect version history
|
||||
|
||||
**Tool sequence**:
|
||||
1. `FIGMA_GET_COMMENTS_IN_A_FILE` - List all file comments [Optional]
|
||||
2. `FIGMA_ADD_A_COMMENT_TO_A_FILE` - Add a comment [Optional]
|
||||
3. `FIGMA_GET_REACTIONS_FOR_A_COMMENT` - Get comment reactions [Optional]
|
||||
4. `FIGMA_GET_VERSIONS_OF_A_FILE` - Get version history [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `file_key`: File key
|
||||
- `as_md`: Return comments in Markdown format
|
||||
- `message`: Comment text
|
||||
- `comment_id`: Comment ID for reactions
|
||||
|
||||
**Pitfalls**:
|
||||
- Comments can be positioned on specific nodes using client_meta
|
||||
- Reply comments cannot be nested (only one level of replies)
|
||||
|
||||
### 5. Browse Projects and Teams
|
||||
|
||||
**When to use**: User wants to list team projects or files
|
||||
|
||||
**Tool sequence**:
|
||||
1. `FIGMA_GET_PROJECTS_IN_A_TEAM` - List team projects [Optional]
|
||||
2. `FIGMA_GET_FILES_IN_A_PROJECT` - List project files [Optional]
|
||||
3. `FIGMA_GET_TEAM_STYLES` - List team published styles [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `team_id`: Team ID from URL (figma.com/files/team/TEAM_ID/...)
|
||||
- `project_id`: Project ID
|
||||
|
||||
**Pitfalls**:
|
||||
- Team ID cannot be obtained programmatically; extract from Figma URL
|
||||
- Only published styles/components are returned by team endpoints
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### URL Parsing
|
||||
|
||||
Extract IDs from Figma URLs:
|
||||
```
|
||||
1. Call FIGMA_DISCOVER_FIGMA_RESOURCES with figma_url
|
||||
2. Extract file_key, node_id, team_id from response
|
||||
3. Convert dash-format node IDs (1-541) to colon format (1:541)
|
||||
```
|
||||
|
||||
### Node Traversal
|
||||
|
||||
```
|
||||
1. Call FIGMA_GET_FILE_JSON with depth=2 for overview
|
||||
2. Identify target nodes from the response
|
||||
3. Call again with specific ids and higher depth for details
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**File Type Support**:
|
||||
- GET_FILE_JSON only supports Design files (figma.com/design/ or figma.com/file/)
|
||||
- FigJam boards (figma.com/board/) and Slides (figma.com/slides/) are NOT supported
|
||||
|
||||
**Node ID Formats**:
|
||||
- URLs use dash format: `node-id=1-541`
|
||||
- API uses colon format: `1:541`
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Parse URL | FIGMA_DISCOVER_FIGMA_RESOURCES | figma_url |
|
||||
| Get file JSON | FIGMA_GET_FILE_JSON | file_key, ids, depth |
|
||||
| Get nodes | FIGMA_GET_FILE_NODES | file_key, ids |
|
||||
| Render images | FIGMA_RENDER_IMAGES_OF_FILE_NODES | file_key, ids, format |
|
||||
| Download images | FIGMA_DOWNLOAD_FIGMA_IMAGES | file_key, images |
|
||||
| Get component | FIGMA_GET_COMPONENT | file_key, node_id |
|
||||
| File components | FIGMA_GET_FILE_COMPONENTS | file_key |
|
||||
| Component sets | FIGMA_GET_FILE_COMPONENT_SETS | file_key |
|
||||
| Design tokens | FIGMA_EXTRACT_DESIGN_TOKENS | file_key |
|
||||
| Tokens to Tailwind | FIGMA_DESIGN_TOKENS_TO_TAILWIND | tokens |
|
||||
| File comments | FIGMA_GET_COMMENTS_IN_A_FILE | file_key |
|
||||
| Add comment | FIGMA_ADD_A_COMMENT_TO_A_FILE | file_key, message |
|
||||
| File versions | FIGMA_GET_VERSIONS_OF_A_FILE | file_key |
|
||||
| Team projects | FIGMA_GET_PROJECTS_IN_A_TEAM | team_id |
|
||||
| Project files | FIGMA_GET_FILES_IN_A_PROJECT | project_id |
|
||||
| Team styles | FIGMA_GET_TEAM_STYLES | team_id |
|
||||
| File styles | FIGMA_GET_FILE_STYLES | file_key |
|
||||
| Image fills | FIGMA_GET_IMAGE_FILLS | file_key |
|
||||
@@ -1,219 +0,0 @@
|
||||
---
|
||||
name: freshdesk-automation
|
||||
description: "Automate Freshdesk helpdesk operations including tickets, contacts, companies, notes, and replies via Rube MCP (Composio). Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Freshdesk Automation via Rube MCP
|
||||
|
||||
Automate Freshdesk customer support workflows including ticket management, contact and company operations, notes, replies, and ticket search through Composio's Freshdesk toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Freshdesk connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `freshdesk`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `freshdesk`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Freshdesk authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create and Manage Tickets
|
||||
|
||||
**When to use**: User wants to create a new support ticket, update an existing ticket, or view ticket details.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `FRESHDESK_SEARCH_CONTACTS` - Find requester by email to get requester_id [Optional]
|
||||
2. `FRESHDESK_LIST_TICKET_FIELDS` - Check available custom fields and statuses [Optional]
|
||||
3. `FRESHDESK_CREATE_TICKET` - Create a new ticket with subject, description, requester info [Required]
|
||||
4. `FRESHDESK_UPDATE_TICKET` - Modify ticket status, priority, assignee, or other fields [Optional]
|
||||
5. `FRESHDESK_VIEW_TICKET` - Retrieve full ticket details by ID [Optional]
|
||||
|
||||
**Key parameters for FRESHDESK_CREATE_TICKET**:
|
||||
- `subject`: Ticket subject (required)
|
||||
- `description`: HTML content of the ticket (required)
|
||||
- `email`: Requester email (at least one requester identifier required)
|
||||
- `requester_id`: User ID of requester (alternative to email)
|
||||
- `status`: 2=Open, 3=Pending, 4=Resolved, 5=Closed (default 2)
|
||||
- `priority`: 1=Low, 2=Medium, 3=High, 4=Urgent (default 1)
|
||||
- `source`: 1=Email, 2=Portal, 3=Phone, 7=Chat (default 2)
|
||||
- `responder_id`: Agent ID to assign the ticket to
|
||||
- `group_id`: Group to assign the ticket to
|
||||
- `tags`: Array of tag strings
|
||||
- `custom_fields`: Object with `cf_<field_name>` keys
|
||||
|
||||
**Pitfalls**:
|
||||
- At least one requester identifier is required: `requester_id`, `email`, `phone`, `facebook_id`, `twitter_id`, or `unique_external_id`
|
||||
- If `phone` is provided without `email`, then `name` becomes mandatory
|
||||
- `description` supports HTML formatting
|
||||
- `attachments` field expects multipart/form-data format, not file paths or URLs
|
||||
- Custom field keys must be prefixed with `cf_` (e.g., `cf_reference_number`)
|
||||
- Status and priority are integers, not strings
|
||||
|
||||
### 2. Search and Filter Tickets
|
||||
|
||||
**When to use**: User wants to find tickets by status, priority, date range, agent, or custom fields.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `FRESHDESK_GET_TICKETS` - List tickets with simple filters (status, priority, agent) [Required]
|
||||
2. `FRESHDESK_GET_SEARCH` - Advanced ticket search with query syntax [Required]
|
||||
3. `FRESHDESK_VIEW_TICKET` - Get full details for specific tickets from results [Optional]
|
||||
4. `FRESHDESK_LIST_TICKET_FIELDS` - Check available fields for search queries [Optional]
|
||||
|
||||
**Key parameters for FRESHDESK_GET_TICKETS**:
|
||||
- `status`: Filter by status integer (2=Open, 3=Pending, 4=Resolved, 5=Closed)
|
||||
- `priority`: Filter by priority integer (1-4)
|
||||
- `agent_id`: Filter by assigned agent
|
||||
- `requester_id`: Filter by requester
|
||||
- `email`: Filter by requester email
|
||||
- `created_since`: ISO 8601 timestamp
|
||||
- `page` / `per_page`: Pagination (default 30 per page)
|
||||
- `sort_by` / `sort_order`: Sort field and direction
|
||||
|
||||
**Key parameters for FRESHDESK_GET_SEARCH**:
|
||||
- `query`: Query string like `"status:2 AND priority:3"` or `"(created_at:>'2024-01-01' AND tag:'urgent')"`
|
||||
- `page`: Page number (1-10, max 300 total results)
|
||||
|
||||
**Pitfalls**:
|
||||
- `FRESHDESK_GET_SEARCH` query must be enclosed in double quotes
|
||||
- Query string limited to 512 characters
|
||||
- Maximum 10 pages (300 results) from search endpoints
|
||||
- Date fields in queries use UTC format YYYY-MM-DD
|
||||
- Use `null` keyword to find tickets with empty fields (e.g., `"agent_id:null"`)
|
||||
- `FRESHDESK_LIST_ALL_TICKETS` takes no parameters and returns all tickets (use GET_TICKETS for filtering)
|
||||
|
||||
### 3. Reply to and Add Notes on Tickets
|
||||
|
||||
**When to use**: User wants to send a reply to a customer, add internal notes, or view conversation history.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `FRESHDESK_VIEW_TICKET` - Verify ticket exists and check current state [Prerequisite]
|
||||
2. `FRESHDESK_REPLY_TO_TICKET` - Send a public reply to the requester [Required]
|
||||
3. `FRESHDESK_ADD_NOTE_TO_TICKET` - Add a private or public note [Required]
|
||||
4. `FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS` - View all messages and notes on a ticket [Optional]
|
||||
5. `FRESHDESK_UPDATE_CONVERSATIONS` - Edit an existing note [Optional]
|
||||
|
||||
**Key parameters for FRESHDESK_REPLY_TO_TICKET**:
|
||||
- `ticket_id`: Ticket ID (integer, required)
|
||||
- `body`: Reply content, supports HTML (required)
|
||||
- `cc_emails` / `bcc_emails`: Additional recipients (max 50 total across to/cc/bcc)
|
||||
- `from_email`: Override sender email if multiple support emails configured
|
||||
- `user_id`: Agent ID to reply on behalf of
|
||||
|
||||
**Key parameters for FRESHDESK_ADD_NOTE_TO_TICKET**:
|
||||
- `ticket_id`: Ticket ID (integer, required)
|
||||
- `body`: Note content, supports HTML (required)
|
||||
- `private`: true for agent-only visibility, false for public (default true)
|
||||
- `notify_emails`: Only accepts agent email addresses, not external contacts
|
||||
|
||||
**Pitfalls**:
|
||||
- There are two reply tools: `FRESHDESK_REPLY_TO_TICKET` (more features) and `FRESHDESK_REPLY_TICKET` (simpler); both work
|
||||
- `FRESHDESK_ADD_NOTE_TO_TICKET` defaults to private (agent-only); set `private: false` for public notes
|
||||
- `notify_emails` in notes only accepts agent emails, not customer emails
|
||||
- Only notes can be edited via `FRESHDESK_UPDATE_CONVERSATIONS`; incoming replies cannot be edited
|
||||
|
||||
### 4. Manage Contacts and Companies
|
||||
|
||||
**When to use**: User wants to create, search, or manage customer contacts and company records.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `FRESHDESK_SEARCH_CONTACTS` - Search contacts by email, phone, or company [Required]
|
||||
2. `FRESHDESK_GET_CONTACTS` - List contacts with filters [Optional]
|
||||
3. `FRESHDESK_IMPORT_CONTACT` - Bulk import contacts from CSV [Optional]
|
||||
4. `FRESHDESK_SEARCH_COMPANIES` - Search companies by custom fields [Required]
|
||||
5. `FRESHDESK_GET_COMPANIES` - List all companies [Optional]
|
||||
6. `FRESHDESK_CREATE_COMPANIES` - Create a new company [Optional]
|
||||
7. `FRESHDESK_UPDATE_COMPANIES` - Update company details [Optional]
|
||||
8. `FRESHDESK_LIST_COMPANY_FIELDS` - Check available company fields [Optional]
|
||||
|
||||
**Key parameters for FRESHDESK_SEARCH_CONTACTS**:
|
||||
- `query`: Search string like `"email:'user@example.com'"` (required)
|
||||
- `page`: Pagination (1-10, max 30 per page)
|
||||
|
||||
**Key parameters for FRESHDESK_CREATE_COMPANIES**:
|
||||
- `name`: Company name (required)
|
||||
- `domains`: Array of domain strings for auto-association with contacts
|
||||
- `health_score`: "Happy", "Doing okay", or "At risk"
|
||||
- `account_tier`: "Basic", "Premium", or "Enterprise"
|
||||
- `industry`: Standard industry classification
|
||||
|
||||
**Pitfalls**:
|
||||
- `FRESHDESK_SEARCH_CONTACTS` requires exact matches; partial/regex searches are not supported
|
||||
- `FRESHDESK_SEARCH_COMPANIES` cannot search by standard `name` field; use custom fields or `created_at`
|
||||
- Company custom fields do NOT use the `cf_` prefix (unlike ticket custom fields)
|
||||
- `domains` on companies enables automatic contact-to-company association by email domain
|
||||
- Contact search queries require string values in single quotes inside double-quoted query
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
Always resolve display values to IDs before operations:
|
||||
- **Requester email -> requester_id**: `FRESHDESK_SEARCH_CONTACTS` with `"email:'user@example.com'"`
|
||||
- **Company name -> company_id**: `FRESHDESK_GET_COMPANIES` and match by name (search by name not supported)
|
||||
- **Agent name -> agent_id**: Not directly available; use agent_id from ticket responses or admin configuration
|
||||
|
||||
### Pagination
|
||||
Freshdesk uses page-based pagination:
|
||||
- `FRESHDESK_GET_TICKETS`: `page` (starting at 1) and `per_page` (max 100)
|
||||
- `FRESHDESK_GET_SEARCH`: `page` (1-10, 30 results per page, max 300 total)
|
||||
- `FRESHDESK_SEARCH_CONTACTS`: `page` (1-10, 30 per page)
|
||||
- `FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS`: `page` and `per_page` (max 100)
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
### ID Formats
|
||||
- Ticket IDs, contact IDs, company IDs, agent IDs, and group IDs are all integers
|
||||
- There are no string-based IDs in Freshdesk
|
||||
|
||||
### Rate Limits
|
||||
- Freshdesk enforces per-account API rate limits based on plan tier
|
||||
- Bulk operations should be paced to avoid 429 responses
|
||||
- Search endpoints are limited to 300 total results (10 pages of 30)
|
||||
|
||||
### Parameter Quirks
|
||||
- Status values: 2=Open, 3=Pending, 4=Resolved, 5=Closed (integers, not strings)
|
||||
- Priority values: 1=Low, 2=Medium, 3=High, 4=Urgent (integers, not strings)
|
||||
- Source values: 1=Email, 2=Portal, 3=Phone, 7=Chat, 9=Feedback Widget, 10=Outbound Email
|
||||
- Ticket custom fields use `cf_` prefix; company custom fields do NOT
|
||||
- `description` in tickets supports HTML formatting
|
||||
- Search query strings must be in double quotes with string values in single quotes
|
||||
- `FRESHDESK_LIST_ALL_TICKETS` returns all tickets with no filter parameters
|
||||
|
||||
### Response Structure
|
||||
- Ticket details include nested objects for requester, assignee, and conversation data
|
||||
- Search results are paginated with a maximum of 300 results across 10 pages
|
||||
- Conversation lists include both replies and notes in chronological order
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Create ticket | `FRESHDESK_CREATE_TICKET` | `subject`, `description`, `email`, `priority` |
|
||||
| Update ticket | `FRESHDESK_UPDATE_TICKET` | `ticket_id`, `status`, `priority` |
|
||||
| View ticket | `FRESHDESK_VIEW_TICKET` | `ticket_id` |
|
||||
| List tickets | `FRESHDESK_GET_TICKETS` | `status`, `priority`, `page`, `per_page` |
|
||||
| List all tickets | `FRESHDESK_LIST_ALL_TICKETS` | (none) |
|
||||
| Search tickets | `FRESHDESK_GET_SEARCH` | `query`, `page` |
|
||||
| Reply to ticket | `FRESHDESK_REPLY_TO_TICKET` | `ticket_id`, `body`, `cc_emails` |
|
||||
| Reply (simple) | `FRESHDESK_REPLY_TICKET` | `ticket_id`, `body` |
|
||||
| Add note | `FRESHDESK_ADD_NOTE_TO_TICKET` | `ticket_id`, `body`, `private` |
|
||||
| List conversations | `FRESHDESK_LIST_ALL_TICKET_CONVERSATIONS` | `ticket_id`, `page` |
|
||||
| Update note | `FRESHDESK_UPDATE_CONVERSATIONS` | `conversation_id`, `body` |
|
||||
| Search contacts | `FRESHDESK_SEARCH_CONTACTS` | `query`, `page` |
|
||||
| List contacts | `FRESHDESK_GET_CONTACTS` | `email`, `company_id`, `page` |
|
||||
| Import contacts | `FRESHDESK_IMPORT_CONTACT` | `file`, `name_column_index`, `email_column_index` |
|
||||
| Create company | `FRESHDESK_CREATE_COMPANIES` | `name`, `domains`, `industry` |
|
||||
| Update company | `FRESHDESK_UPDATE_COMPANIES` | `company_id`, `name`, `domains` |
|
||||
| Search companies | `FRESHDESK_SEARCH_COMPANIES` | `query`, `page` |
|
||||
| List companies | `FRESHDESK_GET_COMPANIES` | `page` |
|
||||
| List ticket fields | `FRESHDESK_LIST_TICKET_FIELDS` | (none) |
|
||||
| List company fields | `FRESHDESK_LIST_COMPANY_FIELDS` | (none) |
|
||||
@@ -1,213 +0,0 @@
|
||||
---
|
||||
name: freshservice-automation
|
||||
description: "Automate Freshservice ITSM tasks via Rube MCP (Composio): create/update tickets, bulk operations, service requests, and outbound emails. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Freshservice Automation via Rube MCP
|
||||
|
||||
Automate Freshservice IT Service Management operations through Composio's Freshservice toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Freshservice connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `freshservice`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `freshservice`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Freshservice authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. List and Search Tickets
|
||||
|
||||
**When to use**: User wants to find, list, or search for tickets
|
||||
|
||||
**Tool sequence**:
|
||||
1. `FRESHSERVICE_LIST_TICKETS` - List tickets with optional filtering and pagination [Required]
|
||||
2. `FRESHSERVICE_GET_TICKET` - Get detailed information for a specific ticket [Optional]
|
||||
|
||||
**Key parameters for listing**:
|
||||
- `filter`: Predefined filter ('all_tickets', 'deleted', 'spam', 'watching')
|
||||
- `updated_since`: ISO 8601 timestamp to get tickets updated after this time
|
||||
- `order_by`: Sort field ('created_at', 'updated_at', 'status', 'priority')
|
||||
- `order_type`: Sort direction ('asc' or 'desc')
|
||||
- `page`: Page number (1-indexed)
|
||||
- `per_page`: Results per page (1-100, default 30)
|
||||
- `include`: Additional fields ('requester', 'stats', 'description', 'conversations', 'assets')
|
||||
|
||||
**Key parameters for get**:
|
||||
- `ticket_id`: Unique ticket ID or display_id
|
||||
- `include`: Additional fields to include
|
||||
|
||||
**Pitfalls**:
|
||||
- By default, only tickets created within the past 30 days are returned
|
||||
- Use `updated_since` to retrieve older tickets
|
||||
- Each `include` value consumes additional API credits
|
||||
- `page` is 1-indexed; minimum value is 1
|
||||
- `per_page` max is 100; default is 30
|
||||
- Ticket IDs can be the internal ID or the display_id shown in the UI
|
||||
|
||||
### 2. Create a Ticket
|
||||
|
||||
**When to use**: User wants to log a new incident or request
|
||||
|
||||
**Tool sequence**:
|
||||
1. `FRESHSERVICE_CREATE_TICKET` - Create a new ticket [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `subject`: Ticket subject line (required)
|
||||
- `description`: HTML description of the ticket (required)
|
||||
- `status`: Ticket status - 2 (Open), 3 (Pending), 4 (Resolved), 5 (Closed) (required)
|
||||
- `priority`: Ticket priority - 1 (Low), 2 (Medium), 3 (High), 4 (Urgent) (required)
|
||||
- `email`: Requester's email address (provide either email or requester_id)
|
||||
- `requester_id`: User ID of the requester
|
||||
- `type`: Ticket type ('Incident' or 'Service Request')
|
||||
- `source`: Channel - 1 (Email), 2 (Portal), 3 (Phone), 4 (Chat), 5 (Twitter), 6 (Facebook)
|
||||
- `impact`: Impact level - 1 (Low), 2 (Medium), 3 (High)
|
||||
- `urgency`: Urgency level - 1 (Low), 2 (Medium), 3 (High), 4 (Critical)
|
||||
|
||||
**Pitfalls**:
|
||||
- `subject`, `description`, `status`, and `priority` are all required
|
||||
- Either `email` or `requester_id` must be provided to identify the requester
|
||||
- Status and priority use numeric codes, not string names
|
||||
- Description supports HTML formatting
|
||||
- If email does not match an existing contact, a new contact is created
|
||||
|
||||
### 3. Bulk Update Tickets
|
||||
|
||||
**When to use**: User wants to update multiple tickets at once
|
||||
|
||||
**Tool sequence**:
|
||||
1. `FRESHSERVICE_LIST_TICKETS` - Find tickets to update [Prerequisite]
|
||||
2. `FRESHSERVICE_BULK_UPDATE_TICKETS` - Update multiple tickets [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `ids`: Array of ticket IDs to update (required)
|
||||
- `update_fields`: Dictionary of fields to update (required)
|
||||
- Allowed keys: 'subject', 'description', 'status', 'priority', 'responder_id', 'group_id', 'type', 'tags', 'custom_fields'
|
||||
|
||||
**Pitfalls**:
|
||||
- Bulk update performs sequential updates internally; large batches may take time
|
||||
- All specified tickets receive the same field updates
|
||||
- If one ticket update fails, others may still succeed; check response for individual results
|
||||
- Cannot selectively update different fields per ticket in a single call
|
||||
- Custom fields must use their internal field names, not display names
|
||||
|
||||
### 4. Create Ticket via Outbound Email
|
||||
|
||||
**When to use**: User wants to create a ticket by sending an outbound email notification
|
||||
|
||||
**Tool sequence**:
|
||||
1. `FRESHSERVICE_CREATE_TICKET_OUTBOUND_EMAIL` - Create ticket with email notification [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `email`: Requester's email address (required)
|
||||
- `subject`: Email subject / ticket subject (required)
|
||||
- `description`: HTML email body content
|
||||
- `status`: Ticket status (2=Open, 3=Pending, 4=Resolved, 5=Closed)
|
||||
- `priority`: Ticket priority (1=Low, 2=Medium, 3=High, 4=Urgent)
|
||||
- `cc_emails`: Array of CC email addresses
|
||||
- `email_config_id`: Email configuration ID for the sender address
|
||||
- `name`: Requester name
|
||||
|
||||
**Pitfalls**:
|
||||
- This creates a standard ticket via the /api/v2/tickets endpoint while sending an email
|
||||
- If the email does not match an existing contact, a new contact is created with the provided name
|
||||
- `email_config_id` determines which email address the notification appears to come from
|
||||
|
||||
### 5. Create Service Requests
|
||||
|
||||
**When to use**: User wants to submit a service catalog request
|
||||
|
||||
**Tool sequence**:
|
||||
1. `FRESHSERVICE_CREATE_SERVICE_REQUEST` - Create a service request for a catalog item [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `item_display_id`: Display ID of the catalog item (required)
|
||||
- `email`: Requester's email address
|
||||
- `quantity`: Number of items to request (default: 1)
|
||||
- `custom_fields`: Custom field values for the service item form
|
||||
- `parent_ticket_id`: Display ID of a parent ticket (for child requests)
|
||||
|
||||
**Pitfalls**:
|
||||
- `item_display_id` can be found in Admin > Service Catalog > item URL (e.g., /service_catalog/items/1)
|
||||
- Custom fields keys must match the service item form field names
|
||||
- Quantity defaults to 1 if not specified
|
||||
- Service requests follow the approval workflow defined for the catalog item
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Status Code Reference
|
||||
|
||||
| Code | Status |
|
||||
|------|--------|
|
||||
| 2 | Open |
|
||||
| 3 | Pending |
|
||||
| 4 | Resolved |
|
||||
| 5 | Closed |
|
||||
|
||||
### Priority Code Reference
|
||||
|
||||
| Code | Priority |
|
||||
|------|----------|
|
||||
| 1 | Low |
|
||||
| 2 | Medium |
|
||||
| 3 | High |
|
||||
| 4 | Urgent |
|
||||
|
||||
### Pagination
|
||||
|
||||
- Use `page` (1-indexed) and `per_page` (max 100) parameters
|
||||
- Increment `page` by 1 each request
|
||||
- Continue until returned results count < `per_page`
|
||||
- Default page size is 30
|
||||
|
||||
### Finding Tickets by Date Range
|
||||
|
||||
```
|
||||
1. Call FRESHSERVICE_LIST_TICKETS with updated_since='2024-01-01T00:00:00Z'
|
||||
2. Optionally add order_by='updated_at' and order_type='desc'
|
||||
3. Paginate through results
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Numeric Codes**:
|
||||
- Status and priority use numeric values, not strings
|
||||
- Source channel uses numeric codes (1-6)
|
||||
- Impact and urgency use numeric codes (1-3 or 1-4)
|
||||
|
||||
**Date Filtering**:
|
||||
- Default returns only tickets from the last 30 days
|
||||
- Use `updated_since` parameter for older tickets
|
||||
- Date format is ISO 8601 (e.g., '2024-01-01T00:00:00Z')
|
||||
|
||||
**Rate Limits**:
|
||||
- Freshservice API has per-account rate limits
|
||||
- Each `include` option consumes additional API credits
|
||||
- Implement backoff on 429 responses
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` or `data.data`
|
||||
- Parse defensively with fallback patterns
|
||||
- Ticket IDs are numeric integers
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List tickets | FRESHSERVICE_LIST_TICKETS | filter, updated_since, page, per_page |
|
||||
| Get ticket | FRESHSERVICE_GET_TICKET | ticket_id, include |
|
||||
| Create ticket | FRESHSERVICE_CREATE_TICKET | subject, description, status, priority, email |
|
||||
| Bulk update | FRESHSERVICE_BULK_UPDATE_TICKETS | ids, update_fields |
|
||||
| Outbound email ticket | FRESHSERVICE_CREATE_TICKET_OUTBOUND_EMAIL | email, subject, description |
|
||||
| Service request | FRESHSERVICE_CREATE_SERVICE_REQUEST | item_display_id, email, quantity |
|
||||
@@ -1,227 +0,0 @@
|
||||
---
|
||||
name: github-automation
|
||||
description: "Automate GitHub repositories, issues, pull requests, branches, CI/CD, and permissions via Rube MCP (Composio). Manage code workflows, review PRs, search code, and handle deployments programmatically."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# GitHub Automation via Rube MCP
|
||||
|
||||
Automate GitHub repository management, issue tracking, pull request workflows, branch operations, and CI/CD through Composio's GitHub toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active GitHub connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `github`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `github`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete GitHub OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create and Manage Issues
|
||||
|
||||
**When to use**: User wants to create, list, or manage GitHub issues
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER` - Find target repo if unknown [Prerequisite]
|
||||
2. `GITHUB_LIST_REPOSITORY_ISSUES` - List existing issues (includes PRs) [Required]
|
||||
3. `GITHUB_CREATE_AN_ISSUE` - Create a new issue [Required]
|
||||
4. `GITHUB_CREATE_AN_ISSUE_COMMENT` - Add comments to an issue [Optional]
|
||||
5. `GITHUB_SEARCH_ISSUES_AND_PULL_REQUESTS` - Search across repos by keyword [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `owner`: Repository owner (username or org), case-insensitive
|
||||
- `repo`: Repository name without .git extension
|
||||
- `title`: Issue title (required for creation)
|
||||
- `body`: Issue description (supports Markdown)
|
||||
- `labels`: Array of label names
|
||||
- `assignees`: Array of GitHub usernames
|
||||
- `state`: 'open', 'closed', or 'all' for filtering
|
||||
|
||||
**Pitfalls**:
|
||||
- `GITHUB_LIST_REPOSITORY_ISSUES` returns both issues AND pull requests; check `pull_request` field to distinguish
|
||||
- Only users with push access can set assignees, labels, and milestones; they are silently dropped otherwise
|
||||
- Pagination: `per_page` max 100; iterate pages until empty
|
||||
|
||||
### 2. Manage Pull Requests
|
||||
|
||||
**When to use**: User wants to create, review, or merge pull requests
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GITHUB_FIND_PULL_REQUESTS` - Search and filter PRs [Required]
|
||||
2. `GITHUB_GET_A_PULL_REQUEST` - Get detailed PR info including mergeable status [Required]
|
||||
3. `GITHUB_LIST_PULL_REQUESTS_FILES` - Review changed files [Optional]
|
||||
4. `GITHUB_CREATE_A_PULL_REQUEST` - Create a new PR [Required]
|
||||
5. `GITHUB_CREATE_AN_ISSUE_COMMENT` - Post review comments [Optional]
|
||||
6. `GITHUB_LIST_CHECK_RUNS_FOR_A_REF` - Verify CI status before merge [Optional]
|
||||
7. `GITHUB_MERGE_A_PULL_REQUEST` - Merge after explicit user approval [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `head`: Source branch with changes (must exist; for cross-repo: 'username:branch')
|
||||
- `base`: Target branch to merge into (e.g., 'main')
|
||||
- `title`: PR title (required unless `issue` number provided)
|
||||
- `merge_method`: 'merge', 'squash', or 'rebase'
|
||||
- `state`: 'open', 'closed', or 'all'
|
||||
|
||||
**Pitfalls**:
|
||||
- `GITHUB_CREATE_A_PULL_REQUEST` fails with 422 if base/head are invalid, identical, or already merged
|
||||
- `GITHUB_MERGE_A_PULL_REQUEST` can be rejected if PR is draft, closed, or branch protection applies
|
||||
- Always verify mergeable status with `GITHUB_GET_A_PULL_REQUEST` immediately before merging
|
||||
- Require explicit user confirmation before calling MERGE
|
||||
|
||||
### 3. Manage Repositories and Branches
|
||||
|
||||
**When to use**: User wants to create repos, manage branches, or update repo settings
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER` - List user's repos [Required]
|
||||
2. `GITHUB_GET_A_REPOSITORY` - Get detailed repo info [Optional]
|
||||
3. `GITHUB_CREATE_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER` - Create personal repo [Required]
|
||||
4. `GITHUB_CREATE_AN_ORGANIZATION_REPOSITORY` - Create org repo [Alternative]
|
||||
5. `GITHUB_LIST_BRANCHES` - List branches [Required]
|
||||
6. `GITHUB_CREATE_A_REFERENCE` - Create new branch from SHA [Required]
|
||||
7. `GITHUB_UPDATE_A_REPOSITORY` - Update repo settings [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Repository name
|
||||
- `private`: Boolean for visibility
|
||||
- `ref`: Full reference path (e.g., 'refs/heads/new-branch')
|
||||
- `sha`: Commit SHA to point the new reference to
|
||||
- `default_branch`: Default branch name
|
||||
|
||||
**Pitfalls**:
|
||||
- `GITHUB_CREATE_A_REFERENCE` only creates NEW references; use `GITHUB_UPDATE_A_REFERENCE` for existing ones
|
||||
- `ref` must start with 'refs/' and contain at least two slashes
|
||||
- `GITHUB_LIST_BRANCHES` paginates via `page`/`per_page`; iterate until empty page
|
||||
- `GITHUB_DELETE_A_REPOSITORY` is permanent and irreversible; requires admin privileges
|
||||
|
||||
### 4. Search Code and Commits
|
||||
|
||||
**When to use**: User wants to find code, files, or commits across repositories
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GITHUB_SEARCH_CODE` - Search file contents and paths [Required]
|
||||
2. `GITHUB_SEARCH_CODE_ALL_PAGES` - Multi-page code search [Alternative]
|
||||
3. `GITHUB_SEARCH_COMMITS_BY_AUTHOR` - Search commits by author/date/org [Required]
|
||||
4. `GITHUB_LIST_COMMITS` - List commits for a specific repo [Alternative]
|
||||
5. `GITHUB_GET_A_COMMIT` - Get detailed commit info [Optional]
|
||||
6. `GITHUB_GET_REPOSITORY_CONTENT` - Get file content [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `q`: Search query with qualifiers (`language:python`, `repo:owner/repo`, `extension:js`)
|
||||
- `owner`/`repo`: For repo-specific commit listing
|
||||
- `author`: Filter by commit author
|
||||
- `since`/`until`: ISO 8601 date range for commits
|
||||
|
||||
**Pitfalls**:
|
||||
- Code search only indexes files under 384KB on default branch
|
||||
- Maximum 1000 results returned from code search
|
||||
- `GITHUB_SEARCH_COMMITS_BY_AUTHOR` requires keywords in addition to qualifiers; qualifier-only queries are not allowed
|
||||
- `GITHUB_LIST_COMMITS` returns 409 on empty repos
|
||||
|
||||
### 5. Manage CI/CD and Deployments
|
||||
|
||||
**When to use**: User wants to view workflows, check CI status, or manage deployments
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GITHUB_LIST_REPOSITORY_WORKFLOWS` - List GitHub Actions workflows [Required]
|
||||
2. `GITHUB_GET_A_WORKFLOW` - Get workflow details by ID or filename [Optional]
|
||||
3. `GITHUB_CREATE_A_WORKFLOW_DISPATCH_EVENT` - Manually trigger a workflow [Required]
|
||||
4. `GITHUB_LIST_CHECK_RUNS_FOR_A_REF` - Check CI status for a commit/branch [Required]
|
||||
5. `GITHUB_LIST_DEPLOYMENTS` - List deployments [Optional]
|
||||
6. `GITHUB_GET_A_DEPLOYMENT_STATUS` - Get deployment status [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `workflow_id`: Numeric ID or filename (e.g., 'ci.yml')
|
||||
- `ref`: Git reference (branch/tag) for workflow dispatch
|
||||
- `inputs`: JSON string of workflow inputs matching `on.workflow_dispatch.inputs`
|
||||
- `environment`: Filter deployments by environment name
|
||||
|
||||
**Pitfalls**:
|
||||
- `GITHUB_CREATE_A_WORKFLOW_DISPATCH_EVENT` requires the workflow to have `workflow_dispatch` trigger configured
|
||||
- Full path `.github/workflows/main.yml` is auto-stripped to just `main.yml`
|
||||
- Inputs max 10 key-value pairs; must match workflow's `on.workflow_dispatch.inputs` definitions
|
||||
|
||||
### 6. Manage Users and Permissions
|
||||
|
||||
**When to use**: User wants to check collaborators, permissions, or branch protection
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GITHUB_LIST_REPOSITORY_COLLABORATORS` - List repo collaborators [Required]
|
||||
2. `GITHUB_GET_REPOSITORY_PERMISSIONS_FOR_A_USER` - Check specific user's access [Optional]
|
||||
3. `GITHUB_GET_BRANCH_PROTECTION` - Inspect branch protection rules [Required]
|
||||
4. `GITHUB_UPDATE_BRANCH_PROTECTION` - Update protection settings [Optional]
|
||||
5. `GITHUB_ADD_A_REPOSITORY_COLLABORATOR` - Add/update collaborator [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `affiliation`: 'outside', 'direct', or 'all' for collaborator filtering
|
||||
- `permission`: Filter by 'pull', 'triage', 'push', 'maintain', 'admin'
|
||||
- `branch`: Branch name for protection rules
|
||||
- `enforce_admins`: Whether protection applies to admins
|
||||
|
||||
**Pitfalls**:
|
||||
- `GITHUB_GET_BRANCH_PROTECTION` returns 404 for unprotected branches; treat as no protection rules
|
||||
- Determine push ability from `permissions.push` or `role_name`, not display labels
|
||||
- `GITHUB_LIST_REPOSITORY_COLLABORATORS` paginates; iterate all pages
|
||||
- `GITHUB_GET_REPOSITORY_PERMISSIONS_FOR_A_USER` may be inconclusive for non-collaborators
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
- **Repo name -> owner/repo**: `GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER`
|
||||
- **PR number -> PR details**: `GITHUB_FIND_PULL_REQUESTS` then `GITHUB_GET_A_PULL_REQUEST`
|
||||
- **Branch name -> SHA**: `GITHUB_GET_A_BRANCH`
|
||||
- **Workflow name -> ID**: `GITHUB_LIST_REPOSITORY_WORKFLOWS`
|
||||
|
||||
### Pagination
|
||||
All list endpoints use page-based pagination:
|
||||
- `page`: Page number (starts at 1)
|
||||
- `per_page`: Results per page (max 100)
|
||||
- Iterate until response returns fewer results than `per_page`
|
||||
|
||||
### Safety
|
||||
- Always verify PR mergeable status before merge
|
||||
- Require explicit user confirmation for destructive operations (merge, delete)
|
||||
- Check CI status with `GITHUB_LIST_CHECK_RUNS_FOR_A_REF` before merging
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
- **Issues vs PRs**: `GITHUB_LIST_REPOSITORY_ISSUES` returns both; check `pull_request` field
|
||||
- **Pagination limits**: `per_page` max 100; always iterate pages until empty
|
||||
- **Branch creation**: `GITHUB_CREATE_A_REFERENCE` fails with 422 if reference already exists
|
||||
- **Merge guards**: Merge can fail due to branch protection, failing checks, or draft status
|
||||
- **Code search limits**: Only files <384KB on default branch; max 1000 results
|
||||
- **Commit search**: Requires search text keywords alongside qualifiers
|
||||
- **Destructive actions**: Repo deletion is irreversible; merge cannot be undone
|
||||
- **Silent permission drops**: Labels, assignees, milestones silently dropped without push access
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List repos | `GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER` | `type`, `sort`, `per_page` |
|
||||
| Get repo | `GITHUB_GET_A_REPOSITORY` | `owner`, `repo` |
|
||||
| Create issue | `GITHUB_CREATE_AN_ISSUE` | `owner`, `repo`, `title`, `body` |
|
||||
| List issues | `GITHUB_LIST_REPOSITORY_ISSUES` | `owner`, `repo`, `state` |
|
||||
| Find PRs | `GITHUB_FIND_PULL_REQUESTS` | `repo`, `state`, `author` |
|
||||
| Create PR | `GITHUB_CREATE_A_PULL_REQUEST` | `owner`, `repo`, `head`, `base`, `title` |
|
||||
| Merge PR | `GITHUB_MERGE_A_PULL_REQUEST` | `owner`, `repo`, `pull_number`, `merge_method` |
|
||||
| List branches | `GITHUB_LIST_BRANCHES` | `owner`, `repo` |
|
||||
| Create branch | `GITHUB_CREATE_A_REFERENCE` | `owner`, `repo`, `ref`, `sha` |
|
||||
| Search code | `GITHUB_SEARCH_CODE` | `q` |
|
||||
| List commits | `GITHUB_LIST_COMMITS` | `owner`, `repo`, `author`, `since` |
|
||||
| Search commits | `GITHUB_SEARCH_COMMITS_BY_AUTHOR` | `q` |
|
||||
| List workflows | `GITHUB_LIST_REPOSITORY_WORKFLOWS` | `owner`, `repo` |
|
||||
| Trigger workflow | `GITHUB_CREATE_A_WORKFLOW_DISPATCH_EVENT` | `owner`, `repo`, `workflow_id`, `ref` |
|
||||
| Check CI | `GITHUB_LIST_CHECK_RUNS_FOR_A_REF` | `owner`, `repo`, ref |
|
||||
| List collaborators | `GITHUB_LIST_REPOSITORY_COLLABORATORS` | `owner`, `repo` |
|
||||
| Branch protection | `GITHUB_GET_BRANCH_PROTECTION` | `owner`, `repo`, `branch` |
|
||||
@@ -1,254 +0,0 @@
|
||||
---
|
||||
name: gitlab-automation
|
||||
description: "Automate GitLab project management, issues, merge requests, pipelines, branches, and user operations via Rube MCP (Composio). Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# GitLab Automation via Rube MCP
|
||||
|
||||
Automate GitLab operations including project management, issue tracking, merge request workflows, CI/CD pipeline monitoring, branch management, and user administration through Composio's GitLab toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active GitLab connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `gitlab`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `gitlab`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete GitLab OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Manage Issues
|
||||
|
||||
**When to use**: User wants to create, update, list, or search issues in a GitLab project
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GITLAB_GET_PROJECTS` - Find the target project and get its ID [Prerequisite]
|
||||
2. `GITLAB_LIST_PROJECT_ISSUES` - List and filter issues for a project [Required]
|
||||
3. `GITLAB_CREATE_PROJECT_ISSUE` - Create a new issue [Required for create]
|
||||
4. `GITLAB_UPDATE_PROJECT_ISSUE` - Update an existing issue (title, labels, state, assignees) [Required for update]
|
||||
5. `GITLAB_LIST_PROJECT_USERS` - Find user IDs for assignment [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `id`: Project ID (integer) or URL-encoded path (e.g., `"my-group/my-project"`)
|
||||
- `title`: Issue title (required for creation)
|
||||
- `description`: Issue body text (max 1,048,576 characters)
|
||||
- `labels`: Comma-separated label names (e.g., `"bug,critical"`)
|
||||
- `add_labels` / `remove_labels`: Add or remove labels without replacing all
|
||||
- `state`: Filter by `"all"`, `"opened"`, or `"closed"`
|
||||
- `state_event`: `"close"` or `"reopen"` to change issue state
|
||||
- `assignee_ids`: Array of user IDs; use `[0]` to unassign all
|
||||
- `issue_iid`: Internal issue ID within the project (required for updates)
|
||||
- `milestone`: Filter by milestone title
|
||||
- `search`: Search in title and description
|
||||
- `scope`: `"created_by_me"`, `"assigned_to_me"`, or `"all"`
|
||||
- `page` / `per_page`: Pagination (default per_page: 20)
|
||||
|
||||
**Pitfalls**:
|
||||
- `id` accepts either integer project ID or URL-encoded path; wrong IDs yield 4xx errors
|
||||
- `issue_iid` is the project-internal ID (shown as #42), different from the global issue ID
|
||||
- Labels in `labels` field replace ALL existing labels; use `add_labels`/`remove_labels` for incremental changes
|
||||
- Setting `assignee_ids` to empty array does NOT unassign; use `[0]` instead
|
||||
- `updated_at` field requires administrator or project/group owner rights
|
||||
|
||||
### 2. Manage Merge Requests
|
||||
|
||||
**When to use**: User wants to list, filter, or review merge requests in a project
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GITLAB_GET_PROJECT` - Get project details and verify access [Prerequisite]
|
||||
2. `GITLAB_GET_PROJECT_MERGE_REQUESTS` - List and filter merge requests [Required]
|
||||
3. `GITLAB_GET_REPOSITORY_BRANCHES` - Verify source/target branches [Optional]
|
||||
4. `GITLAB_LIST_ALL_PROJECT_MEMBERS` - Find reviewers/assignees [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `id`: Project ID or URL-encoded path
|
||||
- `state`: `"opened"`, `"closed"`, `"locked"`, `"merged"`, or `"all"`
|
||||
- `scope`: `"created_by_me"` (default), `"assigned_to_me"`, or `"all"`
|
||||
- `source_branch` / `target_branch`: Filter by branch names
|
||||
- `author_id` / `author_username`: Filter by MR author
|
||||
- `assignee_id`: Filter by assignee (use `None` for unassigned, `Any` for assigned)
|
||||
- `reviewer_id` / `reviewer_username`: Filter by reviewer
|
||||
- `labels`: Comma-separated label filter
|
||||
- `search`: Search in title and description
|
||||
- `wip`: `"yes"` for draft MRs, `"no"` for non-draft
|
||||
- `order_by`: `"created_at"` (default), `"title"`, `"merged_at"`, `"updated_at"`
|
||||
- `view`: `"simple"` for minimal fields
|
||||
- `iids[]`: Filter by specific MR internal IDs
|
||||
|
||||
**Pitfalls**:
|
||||
- Default `scope` is `"created_by_me"` which limits results; use `"all"` for complete listings
|
||||
- `author_id` and `author_username` are mutually exclusive
|
||||
- `reviewer_id` and `reviewer_username` are mutually exclusive
|
||||
- `approved` filter requires the `mr_approved_filter` feature flag (disabled by default)
|
||||
- Large MR histories can be noisy; use filters and moderate `per_page` values
|
||||
|
||||
### 3. Manage Projects and Repositories
|
||||
|
||||
**When to use**: User wants to list projects, create new projects, or manage branches
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GITLAB_GET_PROJECTS` - List all accessible projects with filters [Required]
|
||||
2. `GITLAB_GET_PROJECT` - Get detailed info for a specific project [Optional]
|
||||
3. `GITLAB_LIST_USER_PROJECTS` - List projects owned by a specific user [Optional]
|
||||
4. `GITLAB_CREATE_PROJECT` - Create a new project [Required for create]
|
||||
5. `GITLAB_GET_REPOSITORY_BRANCHES` - List branches in a project [Required for branch ops]
|
||||
6. `GITLAB_CREATE_REPOSITORY_BRANCH` - Create a new branch [Optional]
|
||||
7. `GITLAB_GET_REPOSITORY_BRANCH` - Get details of a specific branch [Optional]
|
||||
8. `GITLAB_LIST_REPOSITORY_COMMITS` - View commit history [Optional]
|
||||
9. `GITLAB_GET_PROJECT_LANGUAGES` - Get language breakdown [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `name` / `path`: Project name and URL-friendly path (both required for creation)
|
||||
- `visibility`: `"private"`, `"internal"`, or `"public"`
|
||||
- `namespace_id`: Group or user ID for project placement
|
||||
- `search`: Case-insensitive substring search for projects
|
||||
- `membership`: `true` to limit to projects user is a member of
|
||||
- `owned`: `true` to limit to user-owned projects
|
||||
- `project_id`: Project ID for branch operations
|
||||
- `branch_name`: Name for new branch
|
||||
- `ref`: Source branch or commit SHA for new branch creation
|
||||
- `order_by`: `"id"`, `"name"`, `"path"`, `"created_at"`, `"updated_at"`, `"star_count"`, `"last_activity_at"`
|
||||
|
||||
**Pitfalls**:
|
||||
- `GITLAB_GET_PROJECTS` pagination is required for complete coverage; stopping at first page misses projects
|
||||
- Some responses place items under `data.details`; parse the actual returned list structure
|
||||
- Most follow-up calls depend on correct `project_id`; verify with `GITLAB_GET_PROJECT` first
|
||||
- Invalid `branch_name`/`ref`/`sha` causes client errors; verify branch existence via `GITLAB_GET_REPOSITORY_BRANCHES` first
|
||||
- Both `name` and `path` are required for `GITLAB_CREATE_PROJECT`
|
||||
|
||||
### 4. Monitor CI/CD Pipelines
|
||||
|
||||
**When to use**: User wants to check pipeline status, list jobs, or monitor CI/CD runs
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GITLAB_GET_PROJECT` - Verify project access [Prerequisite]
|
||||
2. `GITLAB_LIST_PROJECT_PIPELINES` - List pipelines with filters [Required]
|
||||
3. `GITLAB_GET_SINGLE_PIPELINE` - Get detailed info for a specific pipeline [Optional]
|
||||
4. `GITLAB_LIST_PIPELINE_JOBS` - List jobs within a pipeline [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `id`: Project ID or URL-encoded path
|
||||
- `status`: Filter by `"created"`, `"waiting_for_resource"`, `"preparing"`, `"pending"`, `"running"`, `"success"`, `"failed"`, `"canceled"`, `"skipped"`, `"manual"`, `"scheduled"`
|
||||
- `scope`: `"running"`, `"pending"`, `"finished"`, `"branches"`, `"tags"`
|
||||
- `ref`: Branch or tag name
|
||||
- `sha`: Specific commit SHA
|
||||
- `source`: Pipeline source (use `"parent_pipeline"` for child pipelines)
|
||||
- `order_by`: `"id"` (default), `"status"`, `"ref"`, `"updated_at"`, `"user_id"`
|
||||
- `created_after` / `created_before`: ISO 8601 date filters
|
||||
- `pipeline_id`: Specific pipeline ID for job listing
|
||||
- `include_retried`: `true` to include retried jobs (default `false`)
|
||||
|
||||
**Pitfalls**:
|
||||
- Large pipeline histories can be noisy; use `status`, `ref`, and date filters to narrow results
|
||||
- Use moderate `per_page` values to keep output manageable
|
||||
- Pipeline job `scope` accepts single status string or array of statuses
|
||||
- `yaml_errors: true` returns only pipelines with invalid configurations
|
||||
|
||||
### 5. Manage Users and Members
|
||||
|
||||
**When to use**: User wants to find users, list project members, or check user status
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GITLAB_GET_USERS` - Search and list GitLab users [Required]
|
||||
2. `GITLAB_GET_USER` - Get details for a specific user by ID [Optional]
|
||||
3. `GITLAB_GET_USERS_ID_STATUS` - Get user status message and availability [Optional]
|
||||
4. `GITLAB_LIST_ALL_PROJECT_MEMBERS` - List all project members (direct + inherited) [Required for member listing]
|
||||
5. `GITLAB_LIST_PROJECT_USERS` - List project users with search filter [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `search`: Search by name, username, or public email
|
||||
- `username`: Get specific user by username
|
||||
- `active` / `blocked`: Filter by user state
|
||||
- `id`: Project ID for member listing
|
||||
- `query`: Filter members by name, email, or username
|
||||
- `state`: Filter members by `"awaiting"` or `"active"` (Premium/Ultimate)
|
||||
- `user_ids`: Filter by specific user IDs
|
||||
|
||||
**Pitfalls**:
|
||||
- Many user filters (admins, auditors, extern_uid, two_factor) are admin-only
|
||||
- `GITLAB_LIST_ALL_PROJECT_MEMBERS` includes direct, inherited, and invited members
|
||||
- User search is case-insensitive but may not match partial email domains
|
||||
- Premium/Ultimate features (state filter, seat info) are not available on free plans
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
GitLab uses two identifier formats for projects:
|
||||
- **Numeric ID**: Integer project ID (e.g., `123`)
|
||||
- **URL-encoded path**: Namespace/project format (e.g., `"my-group%2Fmy-project"` or `"my-group/my-project"`)
|
||||
- **Issue IID vs ID**: `issue_iid` is the project-internal number (#42); the global `id` is different
|
||||
- **User ID**: Numeric; resolve via `GITLAB_GET_USERS` with `search` or `username`
|
||||
|
||||
### Pagination
|
||||
GitLab uses offset-based pagination:
|
||||
- Set `page` (starting at 1) and `per_page` (1-100, default 20)
|
||||
- Continue incrementing `page` until response returns fewer items than `per_page` or is empty
|
||||
- Total count may be available in response headers (`X-Total`, `X-Total-Pages`)
|
||||
- Always paginate to completion for accurate results
|
||||
|
||||
### URL-Encoded Paths
|
||||
When using project paths as identifiers:
|
||||
- Forward slashes must be URL-encoded: `my-group/my-project` becomes `my-group%2Fmy-project`
|
||||
- Some tools accept unencoded paths; check schema for each tool
|
||||
- Prefer numeric IDs when available for reliability
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
### ID Formats
|
||||
- Project `id` field accepts both integer and string (URL-encoded path)
|
||||
- Issue `issue_iid` is project-scoped; do not confuse with global issue ID
|
||||
- Pipeline IDs are project-scoped integers
|
||||
- User IDs are global integers across the GitLab instance
|
||||
|
||||
### Rate Limits
|
||||
- GitLab has per-user rate limits (typically 300-2000 requests/minute depending on plan)
|
||||
- Large pipeline/issue histories should use date and status filters to reduce result sets
|
||||
- Paginate responsibly with moderate `per_page` values
|
||||
|
||||
### Parameter Quirks
|
||||
- `labels` field replaces ALL labels; use `add_labels`/`remove_labels` for incremental changes
|
||||
- `assignee_ids: [0]` unassigns all; empty array does nothing
|
||||
- `scope` defaults vary: `"created_by_me"` for MRs, `"all"` for issues
|
||||
- `author_id` and `author_username` are mutually exclusive in MR filters
|
||||
- Date parameters use ISO 8601 format: `"2024-01-15T10:30:00Z"`
|
||||
|
||||
### Plan Restrictions
|
||||
- Some features require Premium/Ultimate: `epic_id`, `weight`, `iteration_id`, `approved_by_ids`, member `state` filter
|
||||
- Admin-only features: user management filters, `updated_at` override, custom attributes
|
||||
- The `mr_approved_filter` feature flag is disabled by default
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List projects | `GITLAB_GET_PROJECTS` | `search`, `membership`, `visibility` |
|
||||
| Get project details | `GITLAB_GET_PROJECT` | `id` |
|
||||
| User's projects | `GITLAB_LIST_USER_PROJECTS` | `id`, `search`, `owned` |
|
||||
| Create project | `GITLAB_CREATE_PROJECT` | `name`, `path`, `visibility` |
|
||||
| List issues | `GITLAB_LIST_PROJECT_ISSUES` | `id`, `state`, `labels`, `search` |
|
||||
| Create issue | `GITLAB_CREATE_PROJECT_ISSUE` | `id`, `title`, `description`, `labels` |
|
||||
| Update issue | `GITLAB_UPDATE_PROJECT_ISSUE` | `id`, `issue_iid`, `state_event` |
|
||||
| List merge requests | `GITLAB_GET_PROJECT_MERGE_REQUESTS` | `id`, `state`, `scope`, `labels` |
|
||||
| List branches | `GITLAB_GET_REPOSITORY_BRANCHES` | `project_id`, `search` |
|
||||
| Get branch | `GITLAB_GET_REPOSITORY_BRANCH` | `project_id`, `branch_name` |
|
||||
| Create branch | `GITLAB_CREATE_REPOSITORY_BRANCH` | `project_id`, `branch_name`, `ref` |
|
||||
| List commits | `GITLAB_LIST_REPOSITORY_COMMITS` | project ID, branch ref |
|
||||
| Project languages | `GITLAB_GET_PROJECT_LANGUAGES` | project ID |
|
||||
| List pipelines | `GITLAB_LIST_PROJECT_PIPELINES` | `id`, `status`, `ref` |
|
||||
| Get pipeline | `GITLAB_GET_SINGLE_PIPELINE` | `project_id`, `pipeline_id` |
|
||||
| List pipeline jobs | `GITLAB_LIST_PIPELINE_JOBS` | `id`, `pipeline_id`, `scope` |
|
||||
| Search users | `GITLAB_GET_USERS` | `search`, `username`, `active` |
|
||||
| Get user | `GITLAB_GET_USER` | user ID |
|
||||
| User status | `GITLAB_GET_USERS_ID_STATUS` | user ID |
|
||||
| List project members | `GITLAB_LIST_ALL_PROJECT_MEMBERS` | `id`, `query`, `state` |
|
||||
| List project users | `GITLAB_LIST_PROJECT_USERS` | `id`, `search` |
|
||||
@@ -1,270 +0,0 @@
|
||||
---
|
||||
name: gmail-automation
|
||||
description: "Automate Gmail tasks via Rube MCP (Composio): send/reply, search, labels, drafts, attachments. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Gmail Automation via Rube MCP
|
||||
|
||||
Automate Gmail operations through Composio's Gmail toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Gmail connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `gmail`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `gmail`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Send an Email
|
||||
|
||||
**When to use**: User wants to compose and send a new email
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GMAIL_SEARCH_PEOPLE` - Resolve contact name to email address [Optional]
|
||||
2. `GMAIL_SEND_EMAIL` - Send the email [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `recipient_email`: Email address or 'me' for self
|
||||
- `subject`: Email subject line
|
||||
- `body`: Email content (plain text or HTML)
|
||||
- `is_html`: Must be `true` if body contains HTML markup
|
||||
- `cc`/`bcc`: Arrays of email addresses
|
||||
- `attachment`: Object with `{s3key, mimetype, name}` from prior download
|
||||
|
||||
**Pitfalls**:
|
||||
- At least one of `recipient_email`, `cc`, or `bcc` required
|
||||
- At least one of `subject` or `body` required
|
||||
- Attachment `mimetype` MUST contain '/' (e.g., 'application/pdf', not 'pdf')
|
||||
- Total message size limit ~25MB after base64 encoding
|
||||
- Use `from_email` only for verified aliases in Gmail 'Send mail as' settings
|
||||
|
||||
### 2. Reply to a Thread
|
||||
|
||||
**When to use**: User wants to reply to an existing email conversation
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GMAIL_FETCH_EMAILS` - Find the email/thread to reply to [Prerequisite]
|
||||
2. `GMAIL_REPLY_TO_THREAD` - Send reply within the thread [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `thread_id`: Hex string from FETCH_EMAILS (e.g., '169eefc8138e68ca')
|
||||
- `message_body`: Reply content
|
||||
- `recipient_email`: Reply recipient
|
||||
- `is_html`: Set `true` for HTML content
|
||||
|
||||
**Pitfalls**:
|
||||
- `thread_id` must be hex string; prefixes like 'msg-f:' are auto-stripped
|
||||
- Legacy Gmail web UI IDs (e.g., 'FMfcgz...') are NOT supported
|
||||
- Subject is inherited from original thread; setting it creates a new thread instead
|
||||
- Do NOT include subject parameter to stay within thread
|
||||
|
||||
### 3. Search and Filter Emails
|
||||
|
||||
**When to use**: User wants to find specific emails by sender, subject, date, label, etc.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GMAIL_FETCH_EMAILS` - Search with Gmail query syntax [Required]
|
||||
2. `GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID` - Get full message details for selected results [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: Gmail search syntax (from:, to:, subject:, is:unread, has:attachment, after:YYYY/MM/DD, before:YYYY/MM/DD)
|
||||
- `max_results`: 1-500 messages per page
|
||||
- `label_ids`: System IDs like 'INBOX', 'UNREAD'
|
||||
- `include_payload`: Set `true` to get full message content
|
||||
- `ids_only`: Set `true` for just message IDs
|
||||
- `page_token`: For pagination (from `nextPageToken`)
|
||||
|
||||
**Pitfalls**:
|
||||
- Returns max ~500 per page; follow `nextPageToken` via `page_token` until absent
|
||||
- `resultSizeEstimate` is approximate, not exact count
|
||||
- Use 'is:' for states (is:unread, is:snoozed, is:starred)
|
||||
- Use 'label:' ONLY for user-created labels
|
||||
- Common mistake: 'label:snoozed' is WRONG — use 'is:snoozed'
|
||||
- `include_payload=true` on broad searches creates huge responses; default to metadata
|
||||
- Custom labels require label ID (e.g., 'Label_123'), NOT label name
|
||||
|
||||
### 4. Manage Labels
|
||||
|
||||
**When to use**: User wants to create, modify, or organize labels
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GMAIL_LIST_LABELS` - List all labels to find IDs and detect conflicts [Required]
|
||||
2. `GMAIL_CREATE_LABEL` - Create a new label [Optional]
|
||||
3. `GMAIL_PATCH_LABEL` - Rename or change label colors/visibility [Optional]
|
||||
4. `GMAIL_DELETE_LABEL` - Delete a user-created label (irreversible) [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `label_name`: Max 225 chars, no commas, '/' for nesting (e.g., 'Work/Projects')
|
||||
- `background_color`/`text_color`: Hex values from Gmail's predefined palette
|
||||
- `id`: Label ID for PATCH/DELETE operations
|
||||
|
||||
**Pitfalls**:
|
||||
- 400/409 error if name is blank, duplicate, or reserved (INBOX, SPAM, CATEGORY_*)
|
||||
- Color specs must use Gmail's predefined palette of 102 hex values
|
||||
- DELETE is permanent and removes label from all messages
|
||||
- Cannot delete system labels (INBOX, SENT, DRAFT, etc.)
|
||||
|
||||
### 5. Apply/Remove Labels on Messages
|
||||
|
||||
**When to use**: User wants to label, archive, or mark emails as read/unread
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GMAIL_LIST_LABELS` - Get label IDs for custom labels [Prerequisite]
|
||||
2. `GMAIL_FETCH_EMAILS` - Find target messages [Prerequisite]
|
||||
3. `GMAIL_BATCH_MODIFY_MESSAGES` - Bulk add/remove labels (up to 1000 messages) [Required]
|
||||
4. `GMAIL_ADD_LABEL_TO_EMAIL` - Single-message label changes [Fallback]
|
||||
|
||||
**Key parameters**:
|
||||
- `messageIds`: Array of message IDs (max 1000)
|
||||
- `addLabelIds`: Array of label IDs to add
|
||||
- `removeLabelIds`: Array of label IDs to remove
|
||||
- `message_id`: 15-16 char hex string for single operations
|
||||
|
||||
**Pitfalls**:
|
||||
- Max 1000 messageIds per BATCH call; chunk larger sets
|
||||
- Use 'CATEGORY_UPDATES' not 'UPDATES'; full prefix required for category labels
|
||||
- SENT, DRAFT, CHAT are immutable — cannot be added/removed
|
||||
- To mark as read: REMOVE 'UNREAD'. To archive: REMOVE 'INBOX'
|
||||
- `message_id` must be 15-16 char hex, NOT UUIDs or web UI IDs
|
||||
|
||||
### 6. Handle Drafts and Attachments
|
||||
|
||||
**When to use**: User wants to create, edit, or send email drafts, possibly with attachments
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GMAIL_CREATE_EMAIL_DRAFT` - Create a new draft [Required]
|
||||
2. `GMAIL_UPDATE_DRAFT` - Edit draft content [Optional]
|
||||
3. `GMAIL_LIST_DRAFTS` - List existing drafts [Optional]
|
||||
4. `GMAIL_SEND_DRAFT` - Send a draft (requires explicit user approval) [Optional]
|
||||
5. `GMAIL_GET_ATTACHMENT` - Download attachment from existing message [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `recipient_email`: Draft recipient
|
||||
- `subject`: Draft subject (omit for reply drafts to stay in thread)
|
||||
- `body`: Draft content
|
||||
- `is_html`: Set `true` for HTML content
|
||||
- `attachment`: Object with `{s3key, mimetype, name}`
|
||||
- `thread_id`: For reply drafts (leave subject empty to stay in thread)
|
||||
|
||||
**Pitfalls**:
|
||||
- Response includes `data.id` (draft_id) AND `data.message.id`; use `data.id` for draft operations
|
||||
- Setting subject on a thread reply draft creates a NEW thread instead
|
||||
- Attachment capped at ~25MB; base64 overhead can push near-limit files over
|
||||
- UPDATE_DRAFT replaces entire content, not patches; include all fields you want to keep
|
||||
- HTTP 429 on bulk draft creation; use exponential backoff
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Label name → Label ID**:
|
||||
```
|
||||
1. Call GMAIL_LIST_LABELS
|
||||
2. Find label by name in response
|
||||
3. Extract id field (e.g., 'Label_123')
|
||||
```
|
||||
|
||||
**Contact name → Email**:
|
||||
```
|
||||
1. Call GMAIL_SEARCH_PEOPLE with query=contact_name
|
||||
2. Extract emailAddresses from response
|
||||
```
|
||||
|
||||
**Thread ID from search**:
|
||||
```
|
||||
1. Call GMAIL_FETCH_EMAILS or GMAIL_LIST_THREADS
|
||||
2. Extract threadId (15-16 char hex string)
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Set `max_results` up to 500 per page
|
||||
- Check response for `nextPageToken`
|
||||
- Pass token as `page_token` in next request
|
||||
- Continue until `nextPageToken` is absent or empty string
|
||||
- `resultSizeEstimate` is approximate, not exact
|
||||
|
||||
### Gmail Query Syntax
|
||||
|
||||
**Operators**:
|
||||
- `from:sender@example.com` - Emails from sender
|
||||
- `to:recipient@example.com` - Emails to recipient
|
||||
- `subject:"exact phrase"` - Subject contains exact phrase
|
||||
- `is:unread` - Unread messages
|
||||
- `is:starred` - Starred messages
|
||||
- `is:snoozed` - Snoozed messages
|
||||
- `has:attachment` - Has attachments
|
||||
- `after:2024/01/01` - After date (YYYY/MM/DD)
|
||||
- `before:2024/12/31` - Before date
|
||||
- `label:custom_label` - User-created label (use label ID)
|
||||
- `in:sent` - In sent folder
|
||||
- `category:primary` - Primary category
|
||||
|
||||
**Combinators**:
|
||||
- `AND` - Both conditions (default)
|
||||
- `OR` - Either condition
|
||||
- `NOT` - Exclude condition
|
||||
- `()` - Group conditions
|
||||
|
||||
**Examples**:
|
||||
- `from:boss@company.com is:unread` - Unread emails from boss
|
||||
- `subject:invoice has:attachment after:2024/01/01` - Invoices with attachments this year
|
||||
- `(from:alice OR from:bob) is:starred` - Starred emails from Alice or Bob
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**ID Formats**:
|
||||
- Custom label operations require label IDs (e.g., 'Label_123'), not display names
|
||||
- Always call LIST_LABELS first to resolve names to IDs
|
||||
- Message IDs are 15-16 char hex strings
|
||||
- Do NOT use UUIDs, web UI IDs, or 'thread-f:' prefixes
|
||||
|
||||
**Query Syntax**:
|
||||
- Use 'is:' for states (unread, snoozed, starred)
|
||||
- Use 'label:' ONLY for user-created labels
|
||||
- System labels use 'is:' or 'in:' (e.g., 'is:sent', 'in:inbox')
|
||||
|
||||
**Rate Limits**:
|
||||
- BATCH_MODIFY_MESSAGES max 1000 messages per call
|
||||
- Heavy use triggers 403/429 rate limits
|
||||
- Implement exponential backoff for bulk operations
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data_preview` or `data.messages`
|
||||
- Parse defensively with fallbacks
|
||||
- Timestamp `messageTimestamp` uses RFC3339 with 'Z' suffix
|
||||
- Normalize to '+00:00' for parsing if needed
|
||||
|
||||
**Attachments**:
|
||||
- Attachment `s3key` from prior download may expire
|
||||
- Use promptly after retrieval
|
||||
- Mimetype must include '/' separator
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Send email | GMAIL_SEND_EMAIL | recipient_email, subject, body, is_html |
|
||||
| Reply to thread | GMAIL_REPLY_TO_THREAD | thread_id, message_body, recipient_email |
|
||||
| Search emails | GMAIL_FETCH_EMAILS | query, max_results, label_ids, page_token |
|
||||
| Get message details | GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID | message_id |
|
||||
| List labels | GMAIL_LIST_LABELS | (none) |
|
||||
| Create label | GMAIL_CREATE_LABEL | label_name, background_color, text_color |
|
||||
| Modify labels bulk | GMAIL_BATCH_MODIFY_MESSAGES | messageIds, addLabelIds, removeLabelIds |
|
||||
| Create draft | GMAIL_CREATE_EMAIL_DRAFT | recipient_email, subject, body, thread_id |
|
||||
| Send draft | GMAIL_SEND_DRAFT | draft_id |
|
||||
| Get attachment | GMAIL_GET_ATTACHMENT | message_id, attachment_id |
|
||||
| Search contacts | GMAIL_SEARCH_PEOPLE | query |
|
||||
| Get profile | GMAIL_GET_PROFILE | (none) |
|
||||
@@ -1,227 +0,0 @@
|
||||
---
|
||||
name: google-analytics-automation
|
||||
description: "Automate Google Analytics tasks via Rube MCP (Composio): run reports, list accounts/properties, funnels, pivots, key events. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Google Analytics Automation via Rube MCP
|
||||
|
||||
Automate Google Analytics 4 (GA4) reporting and property management through Composio's Google Analytics toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Google Analytics connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `google_analytics`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `google_analytics`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. List Accounts and Properties
|
||||
|
||||
**When to use**: User wants to discover available GA4 accounts and properties
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLE_ANALYTICS_LIST_ACCOUNTS` - List all accessible GA4 accounts [Required]
|
||||
2. `GOOGLE_ANALYTICS_LIST_PROPERTIES` - List properties under an account [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `pageSize`: Number of results per page
|
||||
- `pageToken`: Pagination token from previous response
|
||||
- `filter`: Filter expression for properties (e.g., `parent:accounts/12345`)
|
||||
|
||||
**Pitfalls**:
|
||||
- Property IDs are numeric strings prefixed with 'properties/' (e.g., 'properties/123456')
|
||||
- Account IDs are prefixed with 'accounts/' (e.g., 'accounts/12345')
|
||||
- Always list accounts first, then properties under each account
|
||||
- Pagination required for organizations with many properties
|
||||
|
||||
### 2. Run Standard Reports
|
||||
|
||||
**When to use**: User wants to query metrics and dimensions from GA4 data
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLE_ANALYTICS_LIST_PROPERTIES` - Get property ID [Prerequisite]
|
||||
2. `GOOGLE_ANALYTICS_GET_METADATA` - Discover available dimensions and metrics [Optional]
|
||||
3. `GOOGLE_ANALYTICS_CHECK_COMPATIBILITY` - Verify dimension/metric compatibility [Optional]
|
||||
4. `GOOGLE_ANALYTICS_RUN_REPORT` - Execute the report query [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `property`: Property ID (e.g., 'properties/123456')
|
||||
- `dateRanges`: Array of date range objects with `startDate` and `endDate`
|
||||
- `dimensions`: Array of dimension objects with `name` field
|
||||
- `metrics`: Array of metric objects with `name` field
|
||||
- `dimensionFilter` / `metricFilter`: Filter expressions
|
||||
- `orderBys`: Sort order configuration
|
||||
- `limit`: Maximum rows to return
|
||||
- `offset`: Row offset for pagination
|
||||
|
||||
**Pitfalls**:
|
||||
- Date format is 'YYYY-MM-DD' or relative values like 'today', 'yesterday', '7daysAgo', '30daysAgo'
|
||||
- Not all dimensions and metrics are compatible; use CHECK_COMPATIBILITY first
|
||||
- Use GET_METADATA to discover valid dimension and metric names
|
||||
- Maximum 9 dimensions per report request
|
||||
- Row limit defaults vary; set explicitly for large datasets
|
||||
- `offset` is for result pagination, not date pagination
|
||||
|
||||
### 3. Run Batch Reports
|
||||
|
||||
**When to use**: User needs multiple different reports from the same property in one call
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLE_ANALYTICS_LIST_PROPERTIES` - Get property ID [Prerequisite]
|
||||
2. `GOOGLE_ANALYTICS_BATCH_RUN_REPORTS` - Execute multiple reports at once [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `property`: Property ID (required)
|
||||
- `requests`: Array of individual report request objects (same structure as RUN_REPORT)
|
||||
|
||||
**Pitfalls**:
|
||||
- Maximum 5 report requests per batch call
|
||||
- All reports in a batch must target the same property
|
||||
- Each individual report has the same dimension/metric limits as RUN_REPORT
|
||||
- Batch errors may affect all reports; check individual report responses
|
||||
|
||||
### 4. Run Pivot Reports
|
||||
|
||||
**When to use**: User wants cross-tabulated data (rows vs columns) like pivot tables
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLE_ANALYTICS_LIST_PROPERTIES` - Get property ID [Prerequisite]
|
||||
2. `GOOGLE_ANALYTICS_RUN_PIVOT_REPORT` - Execute pivot report [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `property`: Property ID (required)
|
||||
- `dateRanges`: Date range objects
|
||||
- `dimensions`: All dimensions used in any pivot
|
||||
- `metrics`: Metrics to aggregate
|
||||
- `pivots`: Array of pivot definitions with `fieldNames`, `limit`, and `orderBys`
|
||||
|
||||
**Pitfalls**:
|
||||
- Dimensions used in pivots must also be listed in top-level `dimensions`
|
||||
- Pivot `fieldNames` reference dimension names from the top-level list
|
||||
- Complex pivots with many dimensions can produce very large result sets
|
||||
- Each pivot has its own independent `limit` and `orderBys`
|
||||
|
||||
### 5. Run Funnel Reports
|
||||
|
||||
**When to use**: User wants to analyze conversion funnels and drop-off rates
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLE_ANALYTICS_LIST_PROPERTIES` - Get property ID [Prerequisite]
|
||||
2. `GOOGLE_ANALYTICS_RUN_FUNNEL_REPORT` - Execute funnel analysis [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `property`: Property ID (required)
|
||||
- `dateRanges`: Date range objects
|
||||
- `funnel`: Funnel definition with `steps` array
|
||||
- `funnelBreakdown`: Optional dimension to break down funnel by
|
||||
|
||||
**Pitfalls**:
|
||||
- Funnel steps are ordered; each step defines a condition users must meet
|
||||
- Steps use filter expressions similar to dimension/metric filters
|
||||
- Open funnels allow entry at any step; closed funnels require sequential progression
|
||||
- Funnel reports may take longer to process than standard reports
|
||||
|
||||
### 6. Manage Key Events
|
||||
|
||||
**When to use**: User wants to view or manage conversion events (key events) in GA4
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLE_ANALYTICS_LIST_PROPERTIES` - Get property ID [Prerequisite]
|
||||
2. `GOOGLE_ANALYTICS_LIST_KEY_EVENTS` - List all key events for the property [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `parent`: Property resource name (e.g., 'properties/123456')
|
||||
- `pageSize`: Number of results per page
|
||||
- `pageToken`: Pagination token
|
||||
|
||||
**Pitfalls**:
|
||||
- Key events were previously called "conversions" in GA4
|
||||
- Property must have key events configured to return results
|
||||
- Key event names correspond to GA4 event names
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Account name -> Account ID**:
|
||||
```
|
||||
1. Call GOOGLE_ANALYTICS_LIST_ACCOUNTS
|
||||
2. Find account by displayName
|
||||
3. Extract name field (e.g., 'accounts/12345')
|
||||
```
|
||||
|
||||
**Property name -> Property ID**:
|
||||
```
|
||||
1. Call GOOGLE_ANALYTICS_LIST_PROPERTIES with filter
|
||||
2. Find property by displayName
|
||||
3. Extract name field (e.g., 'properties/123456')
|
||||
```
|
||||
|
||||
### Dimension/Metric Discovery
|
||||
|
||||
```
|
||||
1. Call GOOGLE_ANALYTICS_GET_METADATA with property ID
|
||||
2. Browse available dimensions and metrics
|
||||
3. Call GOOGLE_ANALYTICS_CHECK_COMPATIBILITY to verify combinations
|
||||
4. Use verified dimensions/metrics in RUN_REPORT
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Reports: Use `offset` and `limit` for row pagination
|
||||
- Accounts/Properties: Use `pageToken` from response
|
||||
- Continue until `pageToken` is absent or `rowCount` reached
|
||||
|
||||
### Common Dimensions and Metrics
|
||||
|
||||
**Dimensions**: `date`, `city`, `country`, `deviceCategory`, `sessionSource`, `sessionMedium`, `pagePath`, `pageTitle`, `eventName`
|
||||
|
||||
**Metrics**: `activeUsers`, `sessions`, `screenPageViews`, `eventCount`, `conversions`, `totalRevenue`, `bounceRate`, `averageSessionDuration`
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Property IDs**:
|
||||
- Always use full resource name format: 'properties/123456'
|
||||
- Numeric ID alone will cause errors
|
||||
- Resolve property names to IDs via LIST_PROPERTIES
|
||||
|
||||
**Date Ranges**:
|
||||
- Format: 'YYYY-MM-DD' or relative ('today', 'yesterday', '7daysAgo', '30daysAgo')
|
||||
- Data processing delay means today's data may be incomplete
|
||||
- Maximum date range varies by property configuration
|
||||
|
||||
**Compatibility**:
|
||||
- Not all dimensions work with all metrics
|
||||
- Always verify with CHECK_COMPATIBILITY before complex reports
|
||||
- Custom dimensions/metrics have specific naming patterns
|
||||
|
||||
**Response Parsing**:
|
||||
- Report data is nested in `rows` array with `dimensionValues` and `metricValues`
|
||||
- Values are returned as strings; parse numbers explicitly
|
||||
- Empty reports return no `rows` key (not an empty array)
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List accounts | GOOGLE_ANALYTICS_LIST_ACCOUNTS | pageSize, pageToken |
|
||||
| List properties | GOOGLE_ANALYTICS_LIST_PROPERTIES | filter, pageSize |
|
||||
| Get metadata | GOOGLE_ANALYTICS_GET_METADATA | property |
|
||||
| Check compatibility | GOOGLE_ANALYTICS_CHECK_COMPATIBILITY | property, dimensions, metrics |
|
||||
| Run report | GOOGLE_ANALYTICS_RUN_REPORT | property, dateRanges, dimensions, metrics |
|
||||
| Batch reports | GOOGLE_ANALYTICS_BATCH_RUN_REPORTS | property, requests |
|
||||
| Pivot report | GOOGLE_ANALYTICS_RUN_PIVOT_REPORT | property, dateRanges, pivots |
|
||||
| Funnel report | GOOGLE_ANALYTICS_RUN_FUNNEL_REPORT | property, dateRanges, funnel |
|
||||
| List key events | GOOGLE_ANALYTICS_LIST_KEY_EVENTS | parent, pageSize |
|
||||
@@ -1,176 +0,0 @@
|
||||
---
|
||||
name: google-calendar-automation
|
||||
description: "Automate Google Calendar events, scheduling, availability checks, and attendee management via Rube MCP (Composio). Create events, find free slots, manage attendees, and list calendars programmatically."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Google Calendar Automation via Rube MCP
|
||||
|
||||
Automate Google Calendar workflows including event creation, scheduling, availability checks, attendee management, and calendar browsing through Composio's Google Calendar toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Google Calendar connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `googlecalendar`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `googlecalendar`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create and Manage Events
|
||||
|
||||
**When to use**: User wants to create, update, or delete calendar events
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLECALENDAR_LIST_CALENDARS` - Identify target calendar ID [Prerequisite]
|
||||
2. `GOOGLECALENDAR_GET_CURRENT_DATE_TIME` - Get current time with proper timezone [Optional]
|
||||
3. `GOOGLECALENDAR_FIND_FREE_SLOTS` - Check availability before booking [Optional]
|
||||
4. `GOOGLECALENDAR_CREATE_EVENT` - Create the event [Required]
|
||||
5. `GOOGLECALENDAR_PATCH_EVENT` - Update specific fields of an existing event [Alternative]
|
||||
6. `GOOGLECALENDAR_UPDATE_EVENT` - Full replacement update of an event [Alternative]
|
||||
7. `GOOGLECALENDAR_DELETE_EVENT` - Delete an event [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `calendar_id`: Use 'primary' for main calendar, or specific calendar ID
|
||||
- `start_datetime`: ISO 8601 format 'YYYY-MM-DDTHH:MM:SS' (NOT natural language)
|
||||
- `timezone`: IANA timezone name (e.g., 'America/New_York', NOT 'EST' or 'PST')
|
||||
- `event_duration_hour`: Hours (0+)
|
||||
- `event_duration_minutes`: Minutes (0-59 only; NEVER use 60+)
|
||||
- `summary`: Event title
|
||||
- `attendees`: Array of email addresses (NOT names)
|
||||
- `location`: Free-form text for event location
|
||||
|
||||
**Pitfalls**:
|
||||
- `start_datetime` must be ISO 8601; natural language like 'tomorrow' is rejected
|
||||
- `event_duration_minutes` max is 59; use `event_duration_hour=1` instead of `event_duration_minutes=60`
|
||||
- `timezone` must be IANA identifier; abbreviations like 'EST', 'PST' are NOT valid
|
||||
- `attendees` only accepts email addresses, not names; resolve names first
|
||||
- Google Meet link creation defaults to true; may fail on personal Gmail accounts (graceful fallback)
|
||||
- Organizer is auto-added as attendee unless `exclude_organizer=true`
|
||||
|
||||
### 2. List and Search Events
|
||||
|
||||
**When to use**: User wants to find or browse events on their calendar
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLECALENDAR_LIST_CALENDARS` - Get available calendars [Prerequisite]
|
||||
2. `GOOGLECALENDAR_FIND_EVENT` - Search by title/keyword with time bounds [Required]
|
||||
3. `GOOGLECALENDAR_EVENTS_LIST` - List events in a time range [Alternative]
|
||||
4. `GOOGLECALENDAR_EVENTS_INSTANCES` - List instances of a recurring event [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `query` / `q`: Free-text search (matches summary, description, location, attendees)
|
||||
- `timeMin`: Lower bound (RFC3339 with timezone offset, e.g., '2024-01-01T00:00:00-08:00')
|
||||
- `timeMax`: Upper bound (RFC3339 with timezone offset)
|
||||
- `singleEvents`: true to expand recurring events into instances
|
||||
- `orderBy`: 'startTime' (requires singleEvents=true) or 'updated'
|
||||
- `maxResults`: Results per page (max 2500)
|
||||
|
||||
**Pitfalls**:
|
||||
- **Timezone warning**: UTC timestamps (ending in 'Z') don't align with local dates; use local timezone offsets instead
|
||||
- Example: '2026-01-19T00:00:00Z' covers 2026-01-18 4pm to 2026-01-19 4pm in PST
|
||||
- Omitting `timeMin`/`timeMax` scans the full calendar and can be slow
|
||||
- `pageToken` in response means more results; paginate until absent
|
||||
- `orderBy='startTime'` requires `singleEvents=true`
|
||||
|
||||
### 3. Manage Attendees and Invitations
|
||||
|
||||
**When to use**: User wants to add, remove, or update event attendees
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLECALENDAR_FIND_EVENT` or `GOOGLECALENDAR_EVENTS_LIST` - Find the event [Prerequisite]
|
||||
2. `GOOGLECALENDAR_PATCH_EVENT` - Add attendees (replaces entire attendees list) [Required]
|
||||
3. `GOOGLECALENDAR_REMOVE_ATTENDEE` - Remove a specific attendee by email [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `event_id`: Unique event identifier (opaque string, NOT the event title)
|
||||
- `attendees`: Full list of attendee emails (PATCH replaces entire list)
|
||||
- `attendee_email`: Email to remove
|
||||
- `send_updates`: 'all', 'externalOnly', or 'none'
|
||||
|
||||
**Pitfalls**:
|
||||
- `event_id` is a technical identifier, NOT the event title; always search first to get the ID
|
||||
- `PATCH_EVENT` attendees field replaces the entire list; include existing attendees to avoid removing them
|
||||
- Attendee names cannot be resolved; always use email addresses
|
||||
- Use `GMAIL_SEARCH_PEOPLE` to resolve names to emails before managing attendees
|
||||
|
||||
### 4. Check Availability and Free/Busy Status
|
||||
|
||||
**When to use**: User wants to find available time slots or check busy periods
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLECALENDAR_LIST_CALENDARS` - Identify calendars to check [Prerequisite]
|
||||
2. `GOOGLECALENDAR_GET_CURRENT_DATE_TIME` - Get current time with timezone [Optional]
|
||||
3. `GOOGLECALENDAR_FIND_FREE_SLOTS` - Find free intervals across calendars [Required]
|
||||
4. `GOOGLECALENDAR_FREE_BUSY_QUERY` - Get raw busy periods for computing gaps [Fallback]
|
||||
5. `GOOGLECALENDAR_CREATE_EVENT` - Book a confirmed slot [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `items`: List of calendar IDs to check (e.g., ['primary'])
|
||||
- `time_min`/`time_max`: Query interval (defaults to current day if omitted)
|
||||
- `timezone`: IANA timezone for interpreting naive timestamps
|
||||
- `calendarExpansionMax`: Max calendars (1-50)
|
||||
- `groupExpansionMax`: Max members per group (1-100)
|
||||
|
||||
**Pitfalls**:
|
||||
- Maximum span ~90 days per Google Calendar freeBusy API limit
|
||||
- Very long ranges or inaccessible calendars yield empty/invalid results
|
||||
- Only calendars with at least freeBusyReader access are visible
|
||||
- Free slots responses may normalize to UTC ('Z'); check offsets
|
||||
- `GOOGLECALENDAR_FREE_BUSY_QUERY` requires RFC3339 timestamps with timezone
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
- **Calendar name -> calendar_id**: `GOOGLECALENDAR_LIST_CALENDARS` to enumerate all calendars
|
||||
- **Event title -> event_id**: `GOOGLECALENDAR_FIND_EVENT` or `GOOGLECALENDAR_EVENTS_LIST`
|
||||
- **Attendee name -> email**: `GMAIL_SEARCH_PEOPLE`
|
||||
|
||||
### Timezone Handling
|
||||
- Always use IANA timezone identifiers (e.g., 'America/Los_Angeles')
|
||||
- Use `GOOGLECALENDAR_GET_CURRENT_DATE_TIME` to get current time in user's timezone
|
||||
- When querying events for a local date, use timestamps with local offset, NOT UTC
|
||||
- Example: '2026-01-19T00:00:00-08:00' for PST, NOT '2026-01-19T00:00:00Z'
|
||||
|
||||
### Pagination
|
||||
- `GOOGLECALENDAR_EVENTS_LIST` returns `nextPageToken`; iterate until absent
|
||||
- `GOOGLECALENDAR_LIST_CALENDARS` also paginates; use `page_token`
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
- **Natural language dates**: NOT supported; all dates must be ISO 8601 or RFC3339
|
||||
- **Timezone mismatch**: UTC timestamps don't align with local dates for filtering
|
||||
- **Duration limits**: `event_duration_minutes` max 59; use hours for longer durations
|
||||
- **IANA timezones only**: 'EST', 'PST', etc. are NOT valid; use 'America/New_York'
|
||||
- **Event IDs are opaque**: Always search to get event_id; never guess or construct
|
||||
- **Attendees as emails**: Names cannot be used; resolve with GMAIL_SEARCH_PEOPLE
|
||||
- **PATCH replaces attendees**: Include all desired attendees in the array, not just new ones
|
||||
- **Conference limitations**: Google Meet may fail on personal accounts (graceful fallback)
|
||||
- **Rate limits**: High-volume searches can trigger 403/429; throttle between calls
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List calendars | `GOOGLECALENDAR_LIST_CALENDARS` | `max_results` |
|
||||
| Create event | `GOOGLECALENDAR_CREATE_EVENT` | `start_datetime`, `timezone`, `summary` |
|
||||
| Update event | `GOOGLECALENDAR_PATCH_EVENT` | `calendar_id`, `event_id`, fields to update |
|
||||
| Delete event | `GOOGLECALENDAR_DELETE_EVENT` | `calendar_id`, `event_id` |
|
||||
| Search events | `GOOGLECALENDAR_FIND_EVENT` | `query`, `timeMin`, `timeMax` |
|
||||
| List events | `GOOGLECALENDAR_EVENTS_LIST` | `calendarId`, `timeMin`, `timeMax` |
|
||||
| Recurring instances | `GOOGLECALENDAR_EVENTS_INSTANCES` | `calendarId`, `eventId` |
|
||||
| Find free slots | `GOOGLECALENDAR_FIND_FREE_SLOTS` | `items`, `time_min`, `time_max`, `timezone` |
|
||||
| Free/busy query | `GOOGLECALENDAR_FREE_BUSY_QUERY` | `timeMin`, `timeMax`, `items` |
|
||||
| Remove attendee | `GOOGLECALENDAR_REMOVE_ATTENDEE` | `event_id`, `attendee_email` |
|
||||
| Get current time | `GOOGLECALENDAR_GET_CURRENT_DATE_TIME` | `timezone` |
|
||||
| Get calendar | `GOOGLECALENDAR_GET_CALENDAR` | `calendar_id` |
|
||||
@@ -1,193 +0,0 @@
|
||||
---
|
||||
name: google-drive-automation
|
||||
description: "Automate Google Drive file operations (upload, download, search, share, organize) via Rube MCP (Composio). Upload/download files, manage folders, share with permissions, and search across drives programmatically."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Google Drive Automation via Rube MCP
|
||||
|
||||
Automate Google Drive workflows including file upload/download, search, folder management, sharing/permissions, and organization through Composio's Google Drive toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Google Drive connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `googledrive`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `googledrive`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Upload and Download Files
|
||||
|
||||
**When to use**: User wants to upload files to or download files from Google Drive
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLEDRIVE_FIND_FILE` - Locate target folder for upload [Prerequisite]
|
||||
2. `GOOGLEDRIVE_UPLOAD_FILE` - Upload a file (max 5MB) [Required]
|
||||
3. `GOOGLEDRIVE_RESUMABLE_UPLOAD` - Upload large files [Fallback]
|
||||
4. `GOOGLEDRIVE_DOWNLOAD_FILE` - Download a file by ID [Required]
|
||||
5. `GOOGLEDRIVE_DOWNLOAD_FILE_OPERATION` - Track long-running downloads [Fallback]
|
||||
6. `GOOGLEDRIVE_GET_FILE_METADATA` - Verify file after upload/download [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `file_to_upload`: Object with `name`, `mimetype`, and `s3key` (file must be in internal storage)
|
||||
- `folder_to_upload_to`: Target folder ID (optional; uploads to root if omitted)
|
||||
- `file_id`: ID of file to download
|
||||
- `mime_type`: Export format for Google Workspace files only (omit for native files)
|
||||
|
||||
**Pitfalls**:
|
||||
- `GOOGLEDRIVE_UPLOAD_FILE` requires `file_to_upload.s3key`; files must already be in internal storage
|
||||
- For non-Google formats (Excel, PDF), do NOT set `mime_type`; it causes errors for native files
|
||||
- Download responses provide a temporary URL at `data.downloaded_file_content.s3url`, not inline bytes
|
||||
- Use `GOOGLEDRIVE_RESUMABLE_UPLOAD` for files >5MB or when basic uploads fail
|
||||
|
||||
### 2. Search and List Files
|
||||
|
||||
**When to use**: User wants to find specific files or browse Drive contents
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLEDRIVE_FIND_FILE` - Search by name, content, type, date, or folder [Required]
|
||||
2. `GOOGLEDRIVE_LIST_FILES` - Browse files with folder scoping [Alternative]
|
||||
3. `GOOGLEDRIVE_LIST_SHARED_DRIVES` - Enumerate shared drives [Optional]
|
||||
4. `GOOGLEDRIVE_GET_FILE_METADATA` - Get detailed file info [Optional]
|
||||
5. `GOOGLEDRIVE_GET_ABOUT` - Check storage quota and supported formats [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `q`: Drive query string (e.g., "name contains 'report'", "mimeType = 'application/pdf'")
|
||||
- `corpora`: Search scope ('user', 'domain', 'drive', 'allDrives')
|
||||
- `fields`: Response fields to include (e.g., 'files(id,name,mimeType)')
|
||||
- `orderBy`: Sort key ('modifiedTime desc', 'name', 'quotaBytesUsed desc')
|
||||
- `pageSize`: Results per page (max 1000)
|
||||
- `pageToken`: Pagination cursor from `nextPageToken`
|
||||
- `folder_id`: Scope search to a specific folder
|
||||
|
||||
**Pitfalls**:
|
||||
- 403 PERMISSION_DENIED if OAuth scopes insufficient for shared drives
|
||||
- Pagination required; files are in `response.data.files`; follow `nextPageToken` until exhausted
|
||||
- `corpora="domain"` may trigger 400; try `"allDrives"` with `includeItemsFromAllDrives=true`
|
||||
- Query complexity limits: >5-10 OR clauses may error "The query is too complex"
|
||||
- Wildcards (*) NOT supported in `name`; use `contains` for partial matching
|
||||
- 'My Drive' is NOT searchable by name; use `folder_id='root'` for root folder
|
||||
- User email searches: use `'user@example.com' in owners` (NOT `owner:user@example.com`)
|
||||
|
||||
### 3. Share Files and Manage Permissions
|
||||
|
||||
**When to use**: User wants to share files or manage access permissions
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLEDRIVE_FIND_FILE` - Locate the file to share [Prerequisite]
|
||||
2. `GOOGLEDRIVE_ADD_FILE_SHARING_PREFERENCE` - Set sharing permission [Required]
|
||||
3. `GOOGLEDRIVE_LIST_PERMISSIONS` - View current permissions [Optional]
|
||||
4. `GOOGLEDRIVE_GET_PERMISSION` - Inspect a specific permission [Optional]
|
||||
5. `GOOGLEDRIVE_UPDATE_PERMISSION` - Modify existing permission [Optional]
|
||||
6. `GOOGLEDRIVE_DELETE_PERMISSION` - Revoke access [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `file_id`: ID of file to share
|
||||
- `type`: 'user', 'group', 'domain', or 'anyone'
|
||||
- `role`: 'owner', 'organizer', 'fileOrganizer', 'writer', 'commenter', 'reader'
|
||||
- `email_address`: Required for type='user' or 'group'
|
||||
- `domain`: Required for type='domain'
|
||||
- `transfer_ownership`: Required when role='owner'
|
||||
|
||||
**Pitfalls**:
|
||||
- Invalid type/email combinations trigger 4xx errors
|
||||
- Using `type='anyone'` or powerful roles is risky; get explicit user confirmation
|
||||
- Org policies may block certain sharing types, causing 403
|
||||
- Permission changes may take time to propagate
|
||||
- Use `GMAIL_SEARCH_PEOPLE` to resolve contact names to emails before sharing
|
||||
|
||||
### 4. Create and Organize Folders
|
||||
|
||||
**When to use**: User wants to create folder structures or move files between folders
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLEDRIVE_FIND_FILE` - Check if folder already exists [Prerequisite]
|
||||
2. `GOOGLEDRIVE_CREATE_FOLDER` - Create a new folder [Required]
|
||||
3. `GOOGLEDRIVE_GET_FILE_METADATA` - Verify created folder [Optional]
|
||||
4. `GOOGLEDRIVE_MOVE_FILE` - Move files between folders [Optional]
|
||||
5. `GOOGLEDRIVE_UPDATE_FILE_PUT` - Update file metadata/parents [Alternative]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Folder name
|
||||
- `parent_id`: Parent folder ID (NOT name); omit for root
|
||||
- `file_id`: File to move
|
||||
- `add_parents`: Destination folder ID for move
|
||||
- `remove_parents`: Source folder ID to remove from
|
||||
|
||||
**Pitfalls**:
|
||||
- `GOOGLEDRIVE_CREATE_FOLDER` requires `parent_id` as an ID, not a folder name
|
||||
- Using `parent_id="root"` creates at top level; for nested paths, chain folder IDs
|
||||
- `GOOGLEDRIVE_FIND_FILE` returns ~100 items/page; follow `nextPageToken` for large drives
|
||||
- Move operations can leave items with multiple parents; use `remove_parents` for true moves
|
||||
- Always verify parent folder exists before creating children
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
- **File/folder name -> ID**: `GOOGLEDRIVE_FIND_FILE` with `q` parameter
|
||||
- **Root folder**: Use `folder_id='root'` or `'root' in parents`
|
||||
- **Shared drive -> driveId**: `GOOGLEDRIVE_LIST_SHARED_DRIVES`
|
||||
- **Contact name -> email**: `GMAIL_SEARCH_PEOPLE` (for sharing)
|
||||
|
||||
### Query Syntax
|
||||
Google Drive uses a specific query language:
|
||||
- Name search: `"name contains 'report'"` or `"name = 'exact.pdf'"`
|
||||
- Type filter: `"mimeType = 'application/pdf'"` or `"mimeType = 'application/vnd.google-apps.folder'"`
|
||||
- Folder scoping: `"'FOLDER_ID' in parents"`
|
||||
- Date filter: `"modifiedTime > '2024-01-01T00:00:00'"`
|
||||
- Combine with `and`/`or`/`not`: `"name contains 'report' and trashed = false"`
|
||||
- Boolean filters: `"sharedWithMe = true"`, `"starred = true"`, `"trashed = false"`
|
||||
|
||||
### Pagination
|
||||
- Follow `nextPageToken` until absent for complete results
|
||||
- Set `pageSize` explicitly (default 100, max 1000)
|
||||
- De-duplicate results if running multiple searches
|
||||
|
||||
### Export Formats
|
||||
For Google Workspace files, set `mime_type` to export:
|
||||
- **Docs**: `application/pdf`, `text/plain`, `text/html`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
|
||||
- **Sheets**: `text/csv`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
|
||||
- **Slides**: `application/pdf`, `application/vnd.openxmlformats-officedocument.presentationml.presentation`
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
- **Internal storage required**: Upload requires files in internal S3 storage (s3key)
|
||||
- **Export vs download**: Set `mime_type` ONLY for Google Workspace files; omit for native files
|
||||
- **Temporary URLs**: Downloaded content via `s3url` is temporary; fetch promptly
|
||||
- **Query complexity**: >5-10 OR clauses may error; split complex searches into multiple queries
|
||||
- **Shared drive scoping**: Missing drive permissions yield empty results; verify access first
|
||||
- **No wildcards**: Use `contains` operator instead of `*` for partial name matching
|
||||
- **Folder creation chains**: Always pass folder IDs (not names) as `parent_id`
|
||||
- **Multiple parents**: Move operations may leave items with multiple parents; use `remove_parents`
|
||||
- **Rate limits**: Heavy searches/exports can trigger 403/429; implement backoff
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Search files | `GOOGLEDRIVE_FIND_FILE` | `q`, `corpora`, `pageSize` |
|
||||
| List files | `GOOGLEDRIVE_LIST_FILES` | `folderId`, `q`, `orderBy` |
|
||||
| Upload file | `GOOGLEDRIVE_UPLOAD_FILE` | `file_to_upload`, `folder_to_upload_to` |
|
||||
| Resumable upload | `GOOGLEDRIVE_RESUMABLE_UPLOAD` | file data |
|
||||
| Download file | `GOOGLEDRIVE_DOWNLOAD_FILE` | `file_id`, `mime_type` (Workspace only) |
|
||||
| File metadata | `GOOGLEDRIVE_GET_FILE_METADATA` | `fileId`, `fields` |
|
||||
| Create folder | `GOOGLEDRIVE_CREATE_FOLDER` | `name`, `parent_id` |
|
||||
| Move file | `GOOGLEDRIVE_MOVE_FILE` | `file_id`, `add_parents`, `remove_parents` |
|
||||
| Share file | `GOOGLEDRIVE_ADD_FILE_SHARING_PREFERENCE` | `file_id`, `role`, `type`, `email_address` |
|
||||
| List permissions | `GOOGLEDRIVE_LIST_PERMISSIONS` | `fileId` |
|
||||
| Update permission | `GOOGLEDRIVE_UPDATE_PERMISSION` | file_id, permission_id |
|
||||
| Delete permission | `GOOGLEDRIVE_DELETE_PERMISSION` | file_id, permission_id |
|
||||
| List shared drives | `GOOGLEDRIVE_LIST_SHARED_DRIVES` | `pageSize` |
|
||||
| Drive info | `GOOGLEDRIVE_GET_ABOUT` | (none) |
|
||||
| Create shortcut | `GOOGLEDRIVE_CREATE_SHORTCUT_TO_FILE` | target file_id |
|
||||
@@ -1,197 +0,0 @@
|
||||
---
|
||||
name: googlesheets-automation
|
||||
description: "Automate Google Sheets operations (read, write, format, filter, manage spreadsheets) via Rube MCP (Composio). Read/write data, manage tabs, apply formatting, and search rows programmatically."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Google Sheets Automation via Rube MCP
|
||||
|
||||
Automate Google Sheets workflows including reading/writing data, managing spreadsheets and tabs, formatting cells, filtering rows, and upserting records through Composio's Google Sheets toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Google Sheets connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `googlesheets`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `googlesheets`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Read and Write Data
|
||||
|
||||
**When to use**: User wants to read data from or write data to a Google Sheet
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLESHEETS_SEARCH_SPREADSHEETS` - Find spreadsheet by name if ID unknown [Prerequisite]
|
||||
2. `GOOGLESHEETS_GET_SHEET_NAMES` - Enumerate tab names to target the right sheet [Prerequisite]
|
||||
3. `GOOGLESHEETS_BATCH_GET` - Read data from one or more ranges [Required]
|
||||
4. `GOOGLESHEETS_BATCH_UPDATE` - Write data to a range or append rows [Required]
|
||||
5. `GOOGLESHEETS_VALUES_UPDATE` - Update a single specific range [Alternative]
|
||||
6. `GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND` - Append rows to end of table [Alternative]
|
||||
|
||||
**Key parameters**:
|
||||
- `spreadsheet_id`: Alphanumeric ID from the spreadsheet URL (between '/d/' and '/edit')
|
||||
- `ranges`: A1 notation array (e.g., 'Sheet1!A1:Z1000'); always use bounded ranges
|
||||
- `sheet_name`: Tab name (case-insensitive matching supported)
|
||||
- `values`: 2D array where each inner array is a row
|
||||
- `first_cell_location`: Starting cell in A1 notation (omit to append)
|
||||
- `valueInputOption`: 'USER_ENTERED' (parsed) or 'RAW' (literal)
|
||||
|
||||
**Pitfalls**:
|
||||
- Mis-cased or non-existent tab names error "Sheet 'X' not found"
|
||||
- Empty ranges may omit `valueRanges[i].values`; treat missing as empty array
|
||||
- `GOOGLESHEETS_BATCH_UPDATE` values must be a 2D array (list of lists), even for a single row
|
||||
- Unbounded ranges like 'A:Z' on sheets with >10,000 rows may cause timeouts; always bound with row limits
|
||||
- Append follows the detected `tableRange`; use returned `updatedRange` to verify placement
|
||||
|
||||
### 2. Create and Manage Spreadsheets
|
||||
|
||||
**When to use**: User wants to create a new spreadsheet or manage tabs within one
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLESHEETS_CREATE_GOOGLE_SHEET1` - Create a new spreadsheet [Required]
|
||||
2. `GOOGLESHEETS_ADD_SHEET` - Add a new tab/worksheet [Required]
|
||||
3. `GOOGLESHEETS_UPDATE_SHEET_PROPERTIES` - Rename, hide, reorder, or color tabs [Optional]
|
||||
4. `GOOGLESHEETS_GET_SPREADSHEET_INFO` - Get full spreadsheet metadata [Optional]
|
||||
5. `GOOGLESHEETS_FIND_WORKSHEET_BY_TITLE` - Check if a specific tab exists [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `title`: Spreadsheet or sheet tab name
|
||||
- `spreadsheetId`: Target spreadsheet ID
|
||||
- `forceUnique`: Auto-append suffix if tab name exists (default true)
|
||||
- `properties.gridProperties`: Set row/column counts, frozen rows
|
||||
|
||||
**Pitfalls**:
|
||||
- Sheet names must be unique within a spreadsheet
|
||||
- Default sheet names are locale-dependent ('Sheet1' in English, 'Hoja 1' in Spanish)
|
||||
- Don't use `index` when creating multiple sheets in parallel (causes 'index too high' errors)
|
||||
- `GOOGLESHEETS_GET_SPREADSHEET_INFO` can return 403 if account lacks access
|
||||
|
||||
### 3. Search and Filter Rows
|
||||
|
||||
**When to use**: User wants to find specific rows or apply filters to sheet data
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW` - Find first row matching exact cell value [Required]
|
||||
2. `GOOGLESHEETS_SET_BASIC_FILTER` - Apply filter/sort to a range [Alternative]
|
||||
3. `GOOGLESHEETS_CLEAR_BASIC_FILTER` - Remove existing filter [Optional]
|
||||
4. `GOOGLESHEETS_BATCH_GET` - Read filtered results [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: Exact text value to match (matches entire cell content)
|
||||
- `range`: A1 notation range to search within
|
||||
- `case_sensitive`: Boolean for case-sensitive matching (default false)
|
||||
- `filter.range`: Grid range with sheet_id for basic filter
|
||||
- `filter.criteria`: Column-based filter conditions
|
||||
- `filter.sortSpecs`: Sort specifications
|
||||
|
||||
**Pitfalls**:
|
||||
- `GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW` matches entire cell content, not substrings
|
||||
- Sheet names with spaces must be single-quoted in ranges (e.g., "'My Sheet'!A:Z")
|
||||
- Bare sheet names without ranges are not supported for lookup; always specify a range
|
||||
|
||||
### 4. Upsert Rows by Key
|
||||
|
||||
**When to use**: User wants to update existing rows or insert new ones based on a unique key column
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLESHEETS_UPSERT_ROWS` - Update matching rows or append new ones [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `spreadsheetId`: Target spreadsheet ID
|
||||
- `sheetName`: Tab name
|
||||
- `keyColumn`: Column header name used as unique identifier (e.g., 'Email', 'SKU')
|
||||
- `headers`: List of column names for the data
|
||||
- `rows`: 2D array of data rows
|
||||
- `strictMode`: Error on mismatched column counts (default true)
|
||||
|
||||
**Pitfalls**:
|
||||
- `keyColumn` must be an actual header name, NOT a column letter (e.g., 'Email' not 'A')
|
||||
- If `headers` is NOT provided, first row of `rows` is treated as headers
|
||||
- With `strictMode=true`, rows with more values than headers cause an error
|
||||
- Auto-adds missing columns to the sheet
|
||||
|
||||
### 5. Format Cells
|
||||
|
||||
**When to use**: User wants to apply formatting (bold, colors, font size) to cells
|
||||
|
||||
**Tool sequence**:
|
||||
1. `GOOGLESHEETS_GET_SPREADSHEET_INFO` - Get numeric sheetId for target tab [Prerequisite]
|
||||
2. `GOOGLESHEETS_FORMAT_CELL` - Apply formatting to a range [Required]
|
||||
3. `GOOGLESHEETS_UPDATE_SHEET_PROPERTIES` - Change frozen rows, column widths [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `spreadsheet_id`: Spreadsheet ID
|
||||
- `worksheet_id`: Numeric sheetId (NOT tab name); get from GET_SPREADSHEET_INFO
|
||||
- `range`: A1 notation (e.g., 'A1:F1') - preferred over index fields
|
||||
- `bold`, `italic`, `underline`, `strikethrough`: Boolean formatting options
|
||||
- `red`, `green`, `blue`: Background color as 0.0-1.0 floats (NOT 0-255 ints)
|
||||
- `fontSize`: Font size in points
|
||||
|
||||
**Pitfalls**:
|
||||
- Requires numeric `worksheet_id`, not tab title; get from spreadsheet metadata
|
||||
- Color channels are 0-1 floats (e.g., 1.0 for full red), NOT 0-255 integers
|
||||
- Responses may return empty reply objects ([{}]); verify formatting via readback
|
||||
- Format one range per call; batch formatting requires separate calls
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
- **Spreadsheet name -> ID**: `GOOGLESHEETS_SEARCH_SPREADSHEETS` with `query`
|
||||
- **Tab name -> sheetId**: `GOOGLESHEETS_GET_SPREADSHEET_INFO`, extract from sheets metadata
|
||||
- **Tab existence check**: `GOOGLESHEETS_FIND_WORKSHEET_BY_TITLE`
|
||||
|
||||
### Rate Limits
|
||||
Google Sheets enforces strict rate limits:
|
||||
- Max 60 reads/minute and 60 writes/minute
|
||||
- Exceeding limits causes errors; batch operations where possible
|
||||
- Use `GOOGLESHEETS_BATCH_GET` and `GOOGLESHEETS_BATCH_UPDATE` for efficiency
|
||||
|
||||
### Data Patterns
|
||||
- Always read before writing to understand existing layout
|
||||
- Use `GOOGLESHEETS_UPSERT_ROWS` for CRM syncs, inventory updates, and dedup scenarios
|
||||
- Append mode (omit `first_cell_location`) is safest for adding new records
|
||||
- Use `GOOGLESHEETS_CLEAR_VALUES` to clear content while preserving formatting
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
- **Tab names**: Locale-dependent defaults; 'Sheet1' may not exist in non-English accounts
|
||||
- **Range notation**: Sheet names with spaces need single quotes in A1 notation
|
||||
- **Unbounded ranges**: Can timeout on large sheets; always specify row bounds (e.g., 'A1:Z10000')
|
||||
- **2D arrays**: All value parameters must be list-of-lists, even for single rows
|
||||
- **Color values**: Floats 0.0-1.0, not integers 0-255
|
||||
- **Formatting IDs**: `FORMAT_CELL` needs numeric sheetId, not tab title
|
||||
- **Rate limits**: 60 reads/min and 60 writes/min; batch to stay within limits
|
||||
- **Delete dimension**: `GOOGLESHEETS_DELETE_DIMENSION` is irreversible; double-check bounds
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Search spreadsheets | `GOOGLESHEETS_SEARCH_SPREADSHEETS` | `query`, `search_type` |
|
||||
| Create spreadsheet | `GOOGLESHEETS_CREATE_GOOGLE_SHEET1` | `title` |
|
||||
| List tabs | `GOOGLESHEETS_GET_SHEET_NAMES` | `spreadsheet_id` |
|
||||
| Add tab | `GOOGLESHEETS_ADD_SHEET` | `spreadsheetId`, `title` |
|
||||
| Read data | `GOOGLESHEETS_BATCH_GET` | `spreadsheet_id`, `ranges` |
|
||||
| Read single range | `GOOGLESHEETS_VALUES_GET` | `spreadsheet_id`, `range` |
|
||||
| Write data | `GOOGLESHEETS_BATCH_UPDATE` | `spreadsheet_id`, `sheet_name`, `values` |
|
||||
| Update range | `GOOGLESHEETS_VALUES_UPDATE` | `spreadsheet_id`, `range`, `values` |
|
||||
| Append rows | `GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND` | `spreadsheetId`, `range`, `values` |
|
||||
| Upsert rows | `GOOGLESHEETS_UPSERT_ROWS` | `spreadsheetId`, `sheetName`, `keyColumn`, `rows` |
|
||||
| Lookup row | `GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW` | `spreadsheet_id`, `query` |
|
||||
| Format cells | `GOOGLESHEETS_FORMAT_CELL` | `spreadsheet_id`, `worksheet_id`, `range` |
|
||||
| Set filter | `GOOGLESHEETS_SET_BASIC_FILTER` | `spreadsheetId`, `filter` |
|
||||
| Clear values | `GOOGLESHEETS_CLEAR_VALUES` | `spreadsheet_id`, range |
|
||||
| Delete rows/cols | `GOOGLESHEETS_DELETE_DIMENSION` | `spreadsheet_id`, `sheet_name`, dimension |
|
||||
| Spreadsheet info | `GOOGLESHEETS_GET_SPREADSHEET_INFO` | `spreadsheet_id` |
|
||||
| Update tab props | `GOOGLESHEETS_UPDATE_SHEET_PROPERTIES` | `spreadsheetId`, properties |
|
||||
@@ -1,166 +0,0 @@
|
||||
---
|
||||
name: helpdesk-automation
|
||||
description: "Automate HelpDesk tasks via Rube MCP (Composio): list tickets, manage views, use canned responses, and configure custom fields. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# HelpDesk Automation via Rube MCP
|
||||
|
||||
Automate HelpDesk ticketing operations through Composio's HelpDesk toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active HelpDesk connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `helpdesk`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `helpdesk`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete HelpDesk authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. List and Browse Tickets
|
||||
|
||||
**When to use**: User wants to retrieve, browse, or paginate through support tickets
|
||||
|
||||
**Tool sequence**:
|
||||
1. `HELPDESK_LIST_TICKETS` - List tickets with sorting and pagination [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `silo`: Ticket folder - 'tickets', 'archive', 'trash', or 'spam' (default: 'tickets')
|
||||
- `sortBy`: Sort field - 'createdAt', 'updatedAt', or 'lastMessageAt' (default: 'createdAt')
|
||||
- `order`: Sort direction - 'asc' or 'desc' (default: 'desc')
|
||||
- `pageSize`: Results per page, 1-100 (default: 20)
|
||||
- `next.value`: Timestamp cursor for forward pagination
|
||||
- `next.ID`: ID cursor for forward pagination
|
||||
- `prev.value`: Timestamp cursor for backward pagination
|
||||
- `prev.ID`: ID cursor for backward pagination
|
||||
|
||||
**Pitfalls**:
|
||||
- Pagination uses cursor-based approach with timestamp + ID pairs
|
||||
- Forward pagination requires both `next.value` and `next.ID` from previous response
|
||||
- Backward pagination requires both `prev.value` and `prev.ID`
|
||||
- `silo` determines which folder to list from; default is active tickets
|
||||
- `pageSize` max is 100; default is 20
|
||||
- Archived and trashed tickets are in separate silos
|
||||
|
||||
### 2. Manage Ticket Views
|
||||
|
||||
**When to use**: User wants to see saved agent views for organizing tickets
|
||||
|
||||
**Tool sequence**:
|
||||
1. `HELPDESK_LIST_VIEWS` - List all agent views [Required]
|
||||
|
||||
**Key parameters**: (none required)
|
||||
|
||||
**Pitfalls**:
|
||||
- Views are predefined saved filters configured by agents in the HelpDesk UI
|
||||
- View definitions include filter criteria that can be used to understand ticket organization
|
||||
- Views cannot be created or modified via API; they are managed in the HelpDesk UI
|
||||
|
||||
### 3. Use Canned Responses
|
||||
|
||||
**When to use**: User wants to list available canned (template) responses for tickets
|
||||
|
||||
**Tool sequence**:
|
||||
1. `HELPDESK_LIST_CANNED_RESPONSES` - Retrieve all predefined reply templates [Required]
|
||||
|
||||
**Key parameters**: (none required)
|
||||
|
||||
**Pitfalls**:
|
||||
- Canned responses are predefined templates for common replies
|
||||
- They may include placeholder variables that need to be filled in
|
||||
- Canned responses are managed through the HelpDesk UI
|
||||
- Response content may include HTML formatting
|
||||
|
||||
### 4. Inspect Custom Fields
|
||||
|
||||
**When to use**: User wants to view custom field definitions for the account
|
||||
|
||||
**Tool sequence**:
|
||||
1. `HELPDESK_LIST_CUSTOM_FIELDS` - List all custom field definitions [Required]
|
||||
|
||||
**Key parameters**: (none required)
|
||||
|
||||
**Pitfalls**:
|
||||
- Custom fields extend the default ticket schema with organization-specific data
|
||||
- Field definitions include field type, name, and validation rules
|
||||
- Custom fields are configured in the HelpDesk admin panel
|
||||
- Field values appear on tickets when the field has been populated
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Ticket Browsing Pattern
|
||||
|
||||
```
|
||||
1. Call HELPDESK_LIST_TICKETS with desired silo and sortBy
|
||||
2. Process the returned page of tickets
|
||||
3. Extract next.value and next.ID from the response
|
||||
4. Call HELPDESK_LIST_TICKETS with those cursor values for next page
|
||||
5. Continue until no more cursor values are returned
|
||||
```
|
||||
|
||||
### Ticket Folder Navigation
|
||||
|
||||
```
|
||||
Active tickets: silo='tickets'
|
||||
Archived: silo='archive'
|
||||
Trashed: silo='trash'
|
||||
Spam: silo='spam'
|
||||
```
|
||||
|
||||
### Cursor-Based Pagination
|
||||
|
||||
```
|
||||
Forward pagination:
|
||||
- Use next.value (timestamp) and next.ID from response
|
||||
- Pass as next.value and next.ID parameters in next call
|
||||
|
||||
Backward pagination:
|
||||
- Use prev.value (timestamp) and prev.ID from response
|
||||
- Pass as prev.value and prev.ID parameters in next call
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Cursor Pagination**:
|
||||
- Both timestamp and ID are required for cursor navigation
|
||||
- Cursor values are timestamps in ISO 8601 date-time format
|
||||
- Mixing forward and backward cursors in the same request is undefined behavior
|
||||
|
||||
**Silo Filtering**:
|
||||
- Tickets are physically separated into silos (folders)
|
||||
- Moving tickets between silos is done in the HelpDesk UI
|
||||
- Each silo query is independent; there is no cross-silo search
|
||||
|
||||
**Read-Only Operations**:
|
||||
- Current Composio toolkit provides list/read operations
|
||||
- Ticket creation, update, and reply operations may require additional tools
|
||||
- Check RUBE_SEARCH_TOOLS for any newly available tools
|
||||
|
||||
**Rate Limits**:
|
||||
- HelpDesk API has per-account rate limits
|
||||
- Implement backoff on 429 responses
|
||||
- Keep page sizes reasonable to avoid timeouts
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` or `data.data`
|
||||
- Parse defensively with fallback patterns
|
||||
- Ticket IDs are strings
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List tickets | HELPDESK_LIST_TICKETS | silo, sortBy, order, pageSize |
|
||||
| List views | HELPDESK_LIST_VIEWS | (none) |
|
||||
| List canned responses | HELPDESK_LIST_CANNED_RESPONSES | (none) |
|
||||
| List custom fields | HELPDESK_LIST_CUSTOM_FIELDS | (none) |
|
||||
@@ -1,178 +0,0 @@
|
||||
---
|
||||
name: hubspot-automation
|
||||
description: "Automate HubSpot CRM operations (contacts, companies, deals, tickets, properties) via Rube MCP using Composio integration."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# HubSpot CRM Automation via Rube MCP
|
||||
|
||||
Automate HubSpot CRM workflows including contact/company management, deal pipeline tracking, ticket search, and custom property creation through Composio's HubSpot toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active HubSpot connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `hubspot`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `hubspot`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete HubSpot OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create and Manage Contacts
|
||||
|
||||
**When to use**: User wants to create new contacts or update existing ones in HubSpot CRM
|
||||
|
||||
**Tool sequence**:
|
||||
1. `HUBSPOT_GET_ACCOUNT_INFO` - Verify connection and permissions (Prerequisite)
|
||||
2. `HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA` - Search for existing contacts to avoid duplicates (Prerequisite)
|
||||
3. `HUBSPOT_READ_A_CRM_PROPERTY_BY_NAME` - Check property metadata for constrained values (Optional)
|
||||
4. `HUBSPOT_CREATE_CONTACT` - Create a single contact (Required)
|
||||
5. `HUBSPOT_CREATE_CONTACTS` - Batch create contacts up to 100 (Alternative)
|
||||
|
||||
**Key parameters**:
|
||||
- `HUBSPOT_CREATE_CONTACT`: `properties` object with `email`, `firstname`, `lastname`, `phone`, `company`
|
||||
- `HUBSPOT_CREATE_CONTACTS`: `inputs` array of `{properties}` objects, max 100 per batch
|
||||
- `HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA`: `filterGroups` array with `{filters: [{propertyName, operator, value}]}`, `properties` array of fields to return
|
||||
|
||||
**Pitfalls**:
|
||||
- Max 100 records per batch; chunk larger imports
|
||||
- 400 'Property values were not valid' if using incorrect property names or enum values
|
||||
- Always search before creating to avoid duplicates
|
||||
- Auth errors from GET_ACCOUNT_INFO mean all subsequent calls will fail
|
||||
|
||||
### 2. Manage Companies
|
||||
|
||||
**When to use**: User wants to create, search, or update company records
|
||||
|
||||
**Tool sequence**:
|
||||
1. `HUBSPOT_SEARCH_COMPANIES` - Search existing companies (Prerequisite)
|
||||
2. `HUBSPOT_CREATE_COMPANIES` - Batch create companies, max 100 (Required)
|
||||
3. `HUBSPOT_UPDATE_COMPANIES` - Batch update existing companies (Alternative)
|
||||
4. `HUBSPOT_GET_COMPANY` - Get single company details (Optional)
|
||||
5. `HUBSPOT_BATCH_READ_COMPANIES_BY_PROPERTIES` - Bulk read companies by property values (Optional)
|
||||
|
||||
**Key parameters**:
|
||||
- `HUBSPOT_CREATE_COMPANIES`: `inputs` array of `{properties}` objects, max 100
|
||||
- `HUBSPOT_SEARCH_COMPANIES`: `filterGroups`, `properties`, `sorts`, `limit`, `after` (pagination cursor)
|
||||
|
||||
**Pitfalls**:
|
||||
- Max 100 per batch; chunk larger sets
|
||||
- Store returned IDs immediately for downstream operations
|
||||
- Property values must match exact internal names, not display labels
|
||||
|
||||
### 3. Manage Deals and Pipeline
|
||||
|
||||
**When to use**: User wants to search deals, view pipeline stages, or track deal progress
|
||||
|
||||
**Tool sequence**:
|
||||
1. `HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE` - Map pipeline and stage IDs/names (Prerequisite)
|
||||
2. `HUBSPOT_SEARCH_DEALS` - Search deals with filters (Required)
|
||||
3. `HUBSPOT_RETRIEVE_PIPELINE_STAGES` - Get stage details for one pipeline (Optional)
|
||||
4. `HUBSPOT_RETRIEVE_OWNERS` - Get owner/rep details (Optional)
|
||||
5. `HUBSPOT_GET_DEAL` - Get single deal details (Optional)
|
||||
6. `HUBSPOT_LIST_DEALS` - List all deals without filters (Fallback)
|
||||
|
||||
**Key parameters**:
|
||||
- `HUBSPOT_SEARCH_DEALS`: `filterGroups` with filters on `pipeline`, `dealstage`, `createdate`, `closedate`, `hubspot_owner_id`; `properties`, `sorts`, `limit`, `after`
|
||||
- `HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE`: `objectType` set to `'deals'`
|
||||
|
||||
**Pitfalls**:
|
||||
- Results nested under `response.data.results`; properties are often strings (amounts, dates)
|
||||
- Stage IDs may be readable strings or opaque numeric IDs; use `label` field for display
|
||||
- Filters must use internal property names (`pipeline`, `dealstage`, `createdate`), not display names
|
||||
- Paginate via `paging.next.after` until absent
|
||||
|
||||
### 4. Search and Filter Tickets
|
||||
|
||||
**When to use**: User wants to find support tickets by status, date, or criteria
|
||||
|
||||
**Tool sequence**:
|
||||
1. `HUBSPOT_SEARCH_TICKETS` - Search with filterGroups (Required)
|
||||
2. `HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE` - Discover available property names (Fallback)
|
||||
3. `HUBSPOT_GET_TICKET` - Get single ticket details (Optional)
|
||||
4. `HUBSPOT_GET_TICKETS` - Bulk fetch tickets by IDs (Optional)
|
||||
|
||||
**Key parameters**:
|
||||
- `HUBSPOT_SEARCH_TICKETS`: `filterGroups`, `properties` (only listed fields are returned), `sorts`, `limit`, `after`
|
||||
|
||||
**Pitfalls**:
|
||||
- Incorrect `propertyName`/`operator` returns zero results without errors
|
||||
- Date filtering may require epoch-ms bounds; mixing formats causes mismatches
|
||||
- Only fields in the `properties` array are returned; missing ones break downstream logic
|
||||
- Use READ_ALL_PROPERTIES to discover exact internal property names
|
||||
|
||||
### 5. Create and Manage Custom Properties
|
||||
|
||||
**When to use**: User wants to add custom fields to CRM objects
|
||||
|
||||
**Tool sequence**:
|
||||
1. `HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE` - List existing properties (Prerequisite)
|
||||
2. `HUBSPOT_READ_PROPERTY_GROUPS_FOR_OBJECT_TYPE` - List property groups (Optional)
|
||||
3. `HUBSPOT_CREATE_PROPERTY_FOR_SPECIFIED_OBJECT_TYPE` - Create a single property (Required)
|
||||
4. `HUBSPOT_CREATE_BATCH_OF_PROPERTIES` - Batch create properties (Alternative)
|
||||
5. `HUBSPOT_UPDATE_SPECIFIC_CRM_PROPERTY` - Update existing property definition (Optional)
|
||||
|
||||
**Key parameters**:
|
||||
- `HUBSPOT_CREATE_PROPERTY_FOR_SPECIFIED_OBJECT_TYPE`: `objectType`, `name`, `label`, `type` (string/number/date/enumeration), `fieldType`, `groupName`, `options` (for enumerations)
|
||||
|
||||
**Pitfalls**:
|
||||
- Property names are immutable after creation; choose carefully
|
||||
- Enumeration options must be pre-defined with `value` and `label`
|
||||
- Group must exist before assigning properties to it
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
- **Property display name → internal name**: Use `HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE`
|
||||
- **Pipeline name → pipeline ID**: Use `HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE`
|
||||
- **Stage name → stage ID**: Extract from pipeline stages response
|
||||
- **Owner name → owner ID**: Use `HUBSPOT_RETRIEVE_OWNERS`
|
||||
|
||||
### Pagination
|
||||
- Search endpoints use cursor-based pagination
|
||||
- Follow `paging.next.after` until absent
|
||||
- Typical limit: 100 records per page
|
||||
- Pass `after` value from previous response to get next page
|
||||
|
||||
### Batch Operations
|
||||
- Most create/update endpoints support batching with max 100 records per call
|
||||
- For larger datasets, chunk into groups of 100
|
||||
- Store returned IDs from each batch before proceeding
|
||||
- Use batch endpoints (`CREATE_CONTACTS`, `CREATE_COMPANIES`, `UPDATE_COMPANIES`) instead of single-record endpoints for efficiency
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
- **Property names**: All search/filter endpoints use internal property names, NOT display labels. Always call `READ_ALL_PROPERTIES_FOR_OBJECT_TYPE` to discover correct names
|
||||
- **Batch limits**: Max 100 records per batch operation. Larger sets must be chunked
|
||||
- **Response structure**: Search results are nested under `response.data.results` with properties as string values
|
||||
- **Date formats**: Date properties may be epoch-ms or ISO strings depending on endpoint. Parse defensively
|
||||
- **Immutable names**: Property names cannot be changed after creation. Plan naming conventions carefully
|
||||
- **Cursor pagination**: Use `paging.next.after` cursor, not page numbers. Continue until `after` is absent
|
||||
- **Duplicate prevention**: Always search before creating contacts/companies to avoid duplicates
|
||||
- **Auth verification**: Run `HUBSPOT_GET_ACCOUNT_INFO` first; auth failures cascade to all subsequent calls
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Create contact | `HUBSPOT_CREATE_CONTACT` | `properties: {email, firstname, lastname}` |
|
||||
| Batch create contacts | `HUBSPOT_CREATE_CONTACTS` | `inputs: [{properties}]` (max 100) |
|
||||
| Search contacts | `HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA` | `filterGroups, properties, limit, after` |
|
||||
| Create companies | `HUBSPOT_CREATE_COMPANIES` | `inputs: [{properties}]` (max 100) |
|
||||
| Search companies | `HUBSPOT_SEARCH_COMPANIES` | `filterGroups, properties, after` |
|
||||
| Search deals | `HUBSPOT_SEARCH_DEALS` | `filterGroups, properties, after` |
|
||||
| Get pipelines | `HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE` | `objectType: 'deals'` |
|
||||
| Search tickets | `HUBSPOT_SEARCH_TICKETS` | `filterGroups, properties, after` |
|
||||
| List properties | `HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE` | `objectType` |
|
||||
| Create property | `HUBSPOT_CREATE_PROPERTY_FOR_SPECIFIED_OBJECT_TYPE` | `objectType, name, label, type, fieldType` |
|
||||
| Get owners | `HUBSPOT_RETRIEVE_OWNERS` | None |
|
||||
| Verify connection | `HUBSPOT_GET_ACCOUNT_INFO` | None |
|
||||
@@ -1,192 +0,0 @@
|
||||
---
|
||||
name: instagram-automation
|
||||
description: "Automate Instagram tasks via Rube MCP (Composio): create posts, carousels, manage media, get insights, and publishing limits. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Instagram Automation via Rube MCP
|
||||
|
||||
Automate Instagram operations through Composio's Instagram toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Instagram connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `instagram`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
- Instagram Business or Creator account required (personal accounts not supported)
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `instagram`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Instagram/Facebook OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create a Single Image/Video Post
|
||||
|
||||
**When to use**: User wants to publish a single photo or video to Instagram
|
||||
|
||||
**Tool sequence**:
|
||||
1. `INSTAGRAM_GET_USER_INFO` - Get Instagram user ID [Prerequisite]
|
||||
2. `INSTAGRAM_CREATE_MEDIA_CONTAINER` - Create a media container with the image/video URL [Required]
|
||||
3. `INSTAGRAM_GET_POST_STATUS` - Check if the media container is ready [Optional]
|
||||
4. `INSTAGRAM_CREATE_POST` or `INSTAGRAM_POST_IG_USER_MEDIA_PUBLISH` - Publish the container [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `image_url`: Public URL of the image to post
|
||||
- `video_url`: Public URL of the video to post
|
||||
- `caption`: Post caption text
|
||||
- `ig_user_id`: Instagram Business account user ID
|
||||
|
||||
**Pitfalls**:
|
||||
- Media URLs must be publicly accessible; private/authenticated URLs will fail
|
||||
- Video containers may take time to process; poll GET_POST_STATUS before publishing
|
||||
- Caption supports hashtags and mentions but has a 2200 character limit
|
||||
- Publishing a container that is not yet finished processing returns an error
|
||||
|
||||
### 2. Create a Carousel Post
|
||||
|
||||
**When to use**: User wants to publish multiple images/videos in a single carousel post
|
||||
|
||||
**Tool sequence**:
|
||||
1. `INSTAGRAM_CREATE_MEDIA_CONTAINER` - Create individual containers for each media item [Required, repeat per item]
|
||||
2. `INSTAGRAM_CREATE_CAROUSEL_CONTAINER` - Create the carousel container referencing all media containers [Required]
|
||||
3. `INSTAGRAM_GET_POST_STATUS` - Check carousel container readiness [Optional]
|
||||
4. `INSTAGRAM_POST_IG_USER_MEDIA_PUBLISH` - Publish the carousel [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `children`: Array of media container IDs for the carousel
|
||||
- `caption`: Carousel post caption
|
||||
- `ig_user_id`: Instagram Business account user ID
|
||||
|
||||
**Pitfalls**:
|
||||
- Carousels require 2-10 media items; fewer or more will fail
|
||||
- Each child container must be created individually before the carousel container
|
||||
- All child containers must be fully processed before creating the carousel
|
||||
- Mixed media (images + videos) is supported in carousels
|
||||
|
||||
### 3. Get Media and Insights
|
||||
|
||||
**When to use**: User wants to view their posts or analyze post performance
|
||||
|
||||
**Tool sequence**:
|
||||
1. `INSTAGRAM_GET_IG_USER_MEDIA` or `INSTAGRAM_GET_USER_MEDIA` - List user's media [Required]
|
||||
2. `INSTAGRAM_GET_IG_MEDIA` - Get details for a specific post [Optional]
|
||||
3. `INSTAGRAM_GET_POST_INSIGHTS` or `INSTAGRAM_GET_IG_MEDIA_INSIGHTS` - Get metrics for a post [Optional]
|
||||
4. `INSTAGRAM_GET_USER_INSIGHTS` - Get account-level insights [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `ig_user_id`: Instagram Business account user ID
|
||||
- `media_id`: ID of the specific media post
|
||||
- `metric`: Metrics to retrieve (e.g., impressions, reach, engagement)
|
||||
- `period`: Time period for insights (e.g., day, week, lifetime)
|
||||
|
||||
**Pitfalls**:
|
||||
- Insights are only available for Business/Creator accounts
|
||||
- Some metrics require minimum follower counts
|
||||
- Insight data may have a delay of up to 48 hours
|
||||
- The `period` parameter must match the metric type
|
||||
|
||||
### 4. Check Publishing Limits
|
||||
|
||||
**When to use**: User wants to verify they can publish before attempting a post
|
||||
|
||||
**Tool sequence**:
|
||||
1. `INSTAGRAM_GET_IG_USER_CONTENT_PUBLISHING_LIMIT` - Check remaining publishing quota [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `ig_user_id`: Instagram Business account user ID
|
||||
|
||||
**Pitfalls**:
|
||||
- Instagram enforces a 25 posts per 24-hour rolling window limit
|
||||
- Publishing limit resets on a rolling basis, not at midnight
|
||||
- Check limits before bulk posting operations to avoid failures
|
||||
|
||||
### 5. Get Media Comments and Children
|
||||
|
||||
**When to use**: User wants to view comments on a post or children of a carousel
|
||||
|
||||
**Tool sequence**:
|
||||
1. `INSTAGRAM_GET_IG_MEDIA_COMMENTS` - List comments on a media post [Required]
|
||||
2. `INSTAGRAM_GET_IG_MEDIA_CHILDREN` - List children of a carousel post [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `media_id`: ID of the media post
|
||||
- `ig_media_id`: Alternative media ID parameter
|
||||
|
||||
**Pitfalls**:
|
||||
- Comments may be paginated; follow pagination cursors for complete results
|
||||
- Carousel children are returned as individual media objects
|
||||
- Comment moderation settings on the account affect what is returned
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Instagram User ID**:
|
||||
```
|
||||
1. Call INSTAGRAM_GET_USER_INFO
|
||||
2. Extract ig_user_id from response
|
||||
3. Use in all subsequent API calls
|
||||
```
|
||||
|
||||
**Media Container Status Check**:
|
||||
```
|
||||
1. Call INSTAGRAM_CREATE_MEDIA_CONTAINER
|
||||
2. Extract container_id from response
|
||||
3. Poll INSTAGRAM_GET_POST_STATUS with container_id
|
||||
4. Wait until status is 'FINISHED' before publishing
|
||||
```
|
||||
|
||||
### Two-Phase Publishing
|
||||
|
||||
- Phase 1: Create media container(s) with content URLs
|
||||
- Phase 2: Publish the container after it finishes processing
|
||||
- Always check container status between phases for video content
|
||||
- For carousels, all children must complete Phase 1 before creating the carousel container
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Media URLs**:
|
||||
- All image/video URLs must be publicly accessible HTTPS URLs
|
||||
- URLs behind authentication, CDN restrictions, or that require cookies will fail
|
||||
- Temporary URLs (pre-signed S3, etc.) may expire before processing completes
|
||||
|
||||
**Rate Limits**:
|
||||
- 25 posts per 24-hour rolling window
|
||||
- API rate limits apply separately from publishing limits
|
||||
- Implement exponential backoff for 429 responses
|
||||
|
||||
**Account Requirements**:
|
||||
- Only Business or Creator Instagram accounts are supported
|
||||
- Personal accounts cannot use the Instagram Graph API
|
||||
- The account must be connected to a Facebook Page
|
||||
|
||||
**Response Parsing**:
|
||||
- Media IDs are numeric strings
|
||||
- Insights data may be nested under different response keys
|
||||
- Pagination uses cursor-based tokens
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Get user info | INSTAGRAM_GET_USER_INFO | (none) |
|
||||
| Create media container | INSTAGRAM_CREATE_MEDIA_CONTAINER | image_url/video_url, caption |
|
||||
| Create carousel | INSTAGRAM_CREATE_CAROUSEL_CONTAINER | children, caption |
|
||||
| Publish post | INSTAGRAM_CREATE_POST | ig_user_id, creation_id |
|
||||
| Publish media | INSTAGRAM_POST_IG_USER_MEDIA_PUBLISH | ig_user_id, creation_id |
|
||||
| Check post status | INSTAGRAM_GET_POST_STATUS | ig_container_id |
|
||||
| List user media | INSTAGRAM_GET_IG_USER_MEDIA | ig_user_id |
|
||||
| Get media details | INSTAGRAM_GET_IG_MEDIA | ig_media_id |
|
||||
| Get post insights | INSTAGRAM_GET_POST_INSIGHTS | media_id, metric |
|
||||
| Get user insights | INSTAGRAM_GET_USER_INSIGHTS | ig_user_id, metric, period |
|
||||
| Get publishing limit | INSTAGRAM_GET_IG_USER_CONTENT_PUBLISHING_LIMIT | ig_user_id |
|
||||
| Get media comments | INSTAGRAM_GET_IG_MEDIA_COMMENTS | ig_media_id |
|
||||
| Get carousel children | INSTAGRAM_GET_IG_MEDIA_CHILDREN | ig_media_id |
|
||||
@@ -1,248 +0,0 @@
|
||||
---
|
||||
name: intercom-automation
|
||||
description: "Automate Intercom tasks via Rube MCP (Composio): conversations, contacts, companies, segments, admins. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Intercom Automation via Rube MCP
|
||||
|
||||
Automate Intercom operations through Composio's Intercom toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Intercom connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `intercom`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `intercom`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Intercom OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Manage Conversations
|
||||
|
||||
**When to use**: User wants to create, list, search, or manage support conversations
|
||||
|
||||
**Tool sequence**:
|
||||
1. `INTERCOM_LIST_ALL_ADMINS` - Get admin IDs for assignment [Prerequisite]
|
||||
2. `INTERCOM_LIST_CONVERSATIONS` - List all conversations [Optional]
|
||||
3. `INTERCOM_SEARCH_CONVERSATIONS` - Search with filters [Optional]
|
||||
4. `INTERCOM_GET_CONVERSATION` - Get conversation details [Optional]
|
||||
5. `INTERCOM_CREATE_CONVERSATION` - Create a new conversation [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `from`: Object with `type` ('user'/'lead') and `id` for conversation creator
|
||||
- `body`: Message body (HTML supported)
|
||||
- `id`: Conversation ID for retrieval
|
||||
- `query`: Search query object with `field`, `operator`, `value`
|
||||
|
||||
**Pitfalls**:
|
||||
- CREATE_CONVERSATION requires a contact (user/lead) as the `from` field, not an admin
|
||||
- Conversation bodies support HTML; plain text is auto-wrapped in `<p>` tags
|
||||
- Search query uses structured filter objects, not free-text search
|
||||
- Conversation IDs are numeric strings
|
||||
|
||||
### 2. Reply and Manage Conversation State
|
||||
|
||||
**When to use**: User wants to reply to, close, reopen, or assign conversations
|
||||
|
||||
**Tool sequence**:
|
||||
1. `INTERCOM_GET_CONVERSATION` - Get current state [Prerequisite]
|
||||
2. `INTERCOM_REPLY_TO_CONVERSATION` - Add a reply [Optional]
|
||||
3. `INTERCOM_ASSIGN_CONVERSATION` - Assign to admin/team [Optional]
|
||||
4. `INTERCOM_CLOSE_CONVERSATION` - Close conversation [Optional]
|
||||
5. `INTERCOM_REOPEN_CONVERSATION` - Reopen closed conversation [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `conversation_id` / `id`: Conversation ID
|
||||
- `body`: Reply message body (HTML supported)
|
||||
- `type`: Reply type ('admin' or 'user')
|
||||
- `admin_id`: Admin ID for replies from admin, assignment, and close/reopen
|
||||
- `assignee_id`: Admin or team ID for assignment
|
||||
- `message_type`: 'comment' (default) or 'note' (internal)
|
||||
|
||||
**Pitfalls**:
|
||||
- `admin_id` is REQUIRED for admin replies, close, reopen, and assignment operations
|
||||
- Always fetch admin IDs first with LIST_ALL_ADMINS or IDENTIFY_AN_ADMIN
|
||||
- Duplicate sends can occur on retry; implement idempotency checks
|
||||
- Internal notes use `message_type: 'note'`; visible only to workspace members
|
||||
- Closing requires an admin_id and optional body message
|
||||
|
||||
### 3. Manage Contacts
|
||||
|
||||
**When to use**: User wants to search, view, or manage contacts (users and leads)
|
||||
|
||||
**Tool sequence**:
|
||||
1. `INTERCOM_SEARCH_CONTACTS` - Search contacts with filters [Required]
|
||||
2. `INTERCOM_GET_A_CONTACT` - Get specific contact [Optional]
|
||||
3. `INTERCOM_SHOW_CONTACT_BY_EXTERNAL_ID` - Look up by external ID [Optional]
|
||||
4. `INTERCOM_LIST_CONTACTS` - List all contacts [Optional]
|
||||
5. `INTERCOM_LIST_TAGS_ATTACHED_TO_A_CONTACT` - Get contact tags [Optional]
|
||||
6. `INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACT` - Get contact segments [Optional]
|
||||
7. `INTERCOM_DETACH_A_CONTACT` - Remove contact from company [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `contact_id`: Contact ID for retrieval
|
||||
- `external_id`: External system ID for lookup
|
||||
- `query`: Search filter object with `field`, `operator`, `value`
|
||||
- `pagination`: Object with `per_page` and `starting_after` cursor
|
||||
|
||||
**Pitfalls**:
|
||||
- SEARCH_CONTACTS uses structured query filters, not free-text; format: `{field, operator, value}`
|
||||
- Supported operators: `=`, `!=`, `>`, `<`, `~` (contains), `!~` (not contains), `IN`, `NIN`
|
||||
- Contact types are 'user' (identified) or 'lead' (anonymous)
|
||||
- LIST_CONTACTS returns paginated results; use `starting_after` cursor for pagination
|
||||
- External IDs are case-sensitive
|
||||
|
||||
### 4. Manage Admins and Teams
|
||||
|
||||
**When to use**: User wants to list workspace admins or identify specific admins
|
||||
|
||||
**Tool sequence**:
|
||||
1. `INTERCOM_LIST_ALL_ADMINS` - List all admins and teams [Required]
|
||||
2. `INTERCOM_IDENTIFY_AN_ADMIN` - Get specific admin details [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `admin_id`: Admin ID for identification
|
||||
|
||||
**Pitfalls**:
|
||||
- LIST_ALL_ADMINS returns both admins and teams
|
||||
- Admin IDs are required for conversation replies, assignment, close, and reopen
|
||||
- Teams appear in the admins list with `type: 'team'`
|
||||
|
||||
### 5. View Segments and Counts
|
||||
|
||||
**When to use**: User wants to view segments or get aggregate counts
|
||||
|
||||
**Tool sequence**:
|
||||
1. `INTERCOM_LIST_SEGMENTS` - List all segments [Optional]
|
||||
2. `INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACT` - Segments for a contact [Optional]
|
||||
3. `INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIES` - Segments for a company [Optional]
|
||||
4. `INTERCOM_GET_COUNTS` - Get aggregate counts [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `contact_id`: Contact ID for segment lookup
|
||||
- `company_id`: Company ID for segment lookup
|
||||
- `type`: Count type ('conversation', 'company', 'user', 'tag', 'segment')
|
||||
- `count`: Sub-count type
|
||||
|
||||
**Pitfalls**:
|
||||
- GET_COUNTS returns approximate counts, not exact numbers
|
||||
- Segment membership is computed; changes may not reflect immediately
|
||||
|
||||
### 6. Manage Companies
|
||||
|
||||
**When to use**: User wants to list companies or manage company-contact relationships
|
||||
|
||||
**Tool sequence**:
|
||||
1. `INTERCOM_LIST_ALL_COMPANIES` - List all companies [Required]
|
||||
2. `INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIES` - Get company segments [Optional]
|
||||
3. `INTERCOM_DETACH_A_CONTACT` - Remove contact from company [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `company_id`: Company ID
|
||||
- `contact_id`: Contact ID for detachment
|
||||
- `page`: Page number for pagination
|
||||
- `per_page`: Results per page
|
||||
|
||||
**Pitfalls**:
|
||||
- Company-contact relationships are managed through contact endpoints
|
||||
- DETACH_A_CONTACT removes the contact-company association, not the contact itself
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Search Query Filters
|
||||
|
||||
**Single filter**:
|
||||
```json
|
||||
{
|
||||
"field": "email",
|
||||
"operator": "=",
|
||||
"value": "user@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
**Multiple filters (AND)**:
|
||||
```json
|
||||
{
|
||||
"operator": "AND",
|
||||
"value": [
|
||||
{"field": "role", "operator": "=", "value": "user"},
|
||||
{"field": "created_at", "operator": ">", "value": 1672531200}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Supported fields for contacts**: email, name, role, created_at, updated_at, signed_up_at, last_seen_at, external_id
|
||||
|
||||
**Supported fields for conversations**: created_at, updated_at, source.type, state, open, read
|
||||
|
||||
### Pagination
|
||||
|
||||
- Most list endpoints use cursor-based pagination
|
||||
- Check response for `pages.next` with `starting_after` cursor
|
||||
- Pass cursor in `pagination.starting_after` for next page
|
||||
- Continue until `pages.next` is null
|
||||
|
||||
### Admin ID Resolution
|
||||
|
||||
```
|
||||
1. Call INTERCOM_LIST_ALL_ADMINS to get all admins
|
||||
2. Find the desired admin by name or email
|
||||
3. Use admin.id for replies, assignments, and state changes
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Admin ID Requirement**:
|
||||
- Admin ID is required for: reply (as admin), assign, close, reopen
|
||||
- Always resolve admin IDs first with LIST_ALL_ADMINS
|
||||
|
||||
**HTML Content**:
|
||||
- Conversation bodies are HTML
|
||||
- Plain text is auto-wrapped in paragraph tags
|
||||
- Sanitize HTML input to prevent rendering issues
|
||||
|
||||
**Idempotency**:
|
||||
- Replies and conversation creation are not idempotent
|
||||
- Duplicate sends can occur on retry or timeout
|
||||
- Track message IDs to prevent duplicates
|
||||
|
||||
**Rate Limits**:
|
||||
- Default: ~1000 requests per minute (varies by plan)
|
||||
- 429 responses include rate limit headers
|
||||
- Implement exponential backoff for retries
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List conversations | INTERCOM_LIST_CONVERSATIONS | (pagination) |
|
||||
| Search conversations | INTERCOM_SEARCH_CONVERSATIONS | query |
|
||||
| Get conversation | INTERCOM_GET_CONVERSATION | id |
|
||||
| Create conversation | INTERCOM_CREATE_CONVERSATION | from, body |
|
||||
| Reply to conversation | INTERCOM_REPLY_TO_CONVERSATION | conversation_id, body, admin_id |
|
||||
| Assign conversation | INTERCOM_ASSIGN_CONVERSATION | conversation_id, admin_id, assignee_id |
|
||||
| Close conversation | INTERCOM_CLOSE_CONVERSATION | id, admin_id |
|
||||
| Reopen conversation | INTERCOM_REOPEN_CONVERSATION | id, admin_id |
|
||||
| Search contacts | INTERCOM_SEARCH_CONTACTS | query |
|
||||
| Get contact | INTERCOM_GET_A_CONTACT | contact_id |
|
||||
| Contact by external ID | INTERCOM_SHOW_CONTACT_BY_EXTERNAL_ID | external_id |
|
||||
| List contacts | INTERCOM_LIST_CONTACTS | (pagination) |
|
||||
| Contact tags | INTERCOM_LIST_TAGS_ATTACHED_TO_A_CONTACT | contact_id |
|
||||
| Contact segments | INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACT | contact_id |
|
||||
| Detach contact | INTERCOM_DETACH_A_CONTACT | contact_id, company_id |
|
||||
| List admins | INTERCOM_LIST_ALL_ADMINS | (none) |
|
||||
| Identify admin | INTERCOM_IDENTIFY_AN_ADMIN | admin_id |
|
||||
| List segments | INTERCOM_LIST_SEGMENTS | (none) |
|
||||
| Company segments | INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIES | company_id |
|
||||
| Get counts | INTERCOM_GET_COUNTS | type, count |
|
||||
| List companies | INTERCOM_LIST_ALL_COMPANIES | page, per_page |
|
||||
@@ -1,185 +0,0 @@
|
||||
---
|
||||
name: jira-automation
|
||||
description: "Automate Jira tasks via Rube MCP (Composio): issues, projects, sprints, boards, comments, users. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Jira Automation via Rube MCP
|
||||
|
||||
Automate Jira operations through Composio's Jira toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Jira connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `jira`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `jira`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Jira OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Search and Filter Issues
|
||||
|
||||
**When to use**: User wants to find issues using JQL or browse project issues
|
||||
|
||||
**Tool sequence**:
|
||||
1. `JIRA_SEARCH_FOR_ISSUES_USING_JQL_POST` - Search with JQL query [Required]
|
||||
2. `JIRA_GET_ISSUE` - Get full details of a specific issue [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `jql`: JQL query string (e.g., `project = PROJ AND status = "In Progress"`)
|
||||
- `maxResults`: Max results per page (default 50, max 100)
|
||||
- `startAt`: Pagination offset
|
||||
- `fields`: Array of field names to return
|
||||
- `issueIdOrKey`: Issue key like 'PROJ-123' for GET_ISSUE
|
||||
|
||||
**Pitfalls**:
|
||||
- JQL field names are case-sensitive and must match Jira configuration
|
||||
- Custom fields use IDs like `customfield_10001`, not display names
|
||||
- Results are paginated; check `total` vs `startAt + maxResults` to continue
|
||||
|
||||
### 2. Create and Edit Issues
|
||||
|
||||
**When to use**: User wants to create new issues or update existing ones
|
||||
|
||||
**Tool sequence**:
|
||||
1. `JIRA_GET_ALL_PROJECTS` - List projects to find project key [Prerequisite]
|
||||
2. `JIRA_GET_FIELDS` - Get available fields and their IDs [Prerequisite]
|
||||
3. `JIRA_CREATE_ISSUE` - Create a new issue [Required]
|
||||
4. `JIRA_EDIT_ISSUE` - Update fields on an existing issue [Optional]
|
||||
5. `JIRA_ASSIGN_ISSUE` - Assign issue to a user [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `project`: Project key (e.g., 'PROJ')
|
||||
- `issuetype`: Issue type name (e.g., 'Bug', 'Story', 'Task')
|
||||
- `summary`: Issue title
|
||||
- `description`: Issue description (Atlassian Document Format or plain text)
|
||||
- `issueIdOrKey`: Issue key for edits
|
||||
|
||||
**Pitfalls**:
|
||||
- Issue types and required fields vary by project; use GET_FIELDS to check
|
||||
- Custom fields require exact field IDs, not display names
|
||||
- Description may need Atlassian Document Format (ADF) for rich content
|
||||
|
||||
### 3. Manage Sprints and Boards
|
||||
|
||||
**When to use**: User wants to work with agile boards, sprints, and backlogs
|
||||
|
||||
**Tool sequence**:
|
||||
1. `JIRA_LIST_BOARDS` - List all boards [Prerequisite]
|
||||
2. `JIRA_LIST_SPRINTS` - List sprints for a board [Required]
|
||||
3. `JIRA_MOVE_ISSUE_TO_SPRINT` - Move issue to a sprint [Optional]
|
||||
4. `JIRA_CREATE_SPRINT` - Create a new sprint [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `boardId`: Board ID from LIST_BOARDS
|
||||
- `sprintId`: Sprint ID for move operations
|
||||
- `name`: Sprint name for creation
|
||||
- `startDate`/`endDate`: Sprint dates in ISO format
|
||||
|
||||
**Pitfalls**:
|
||||
- Boards and sprints are specific to Jira Software (not Jira Core)
|
||||
- Only one sprint can be active at a time per board
|
||||
|
||||
### 4. Manage Comments
|
||||
|
||||
**When to use**: User wants to add or view comments on issues
|
||||
|
||||
**Tool sequence**:
|
||||
1. `JIRA_LIST_ISSUE_COMMENTS` - List existing comments [Optional]
|
||||
2. `JIRA_ADD_COMMENT` - Add a comment to an issue [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `issueIdOrKey`: Issue key like 'PROJ-123'
|
||||
- `body`: Comment body (supports ADF for rich text)
|
||||
|
||||
**Pitfalls**:
|
||||
- Comments support ADF (Atlassian Document Format) for formatting
|
||||
- Mentions use account IDs, not usernames
|
||||
|
||||
### 5. Manage Projects and Users
|
||||
|
||||
**When to use**: User wants to list projects, find users, or manage project roles
|
||||
|
||||
**Tool sequence**:
|
||||
1. `JIRA_GET_ALL_PROJECTS` - List all projects [Optional]
|
||||
2. `JIRA_GET_PROJECT` - Get project details [Optional]
|
||||
3. `JIRA_FIND_USERS` / `JIRA_GET_ALL_USERS` - Search for users [Optional]
|
||||
4. `JIRA_GET_PROJECT_ROLES` - List project roles [Optional]
|
||||
5. `JIRA_ADD_USERS_TO_PROJECT_ROLE` - Add user to role [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `projectIdOrKey`: Project key
|
||||
- `query`: Search text for FIND_USERS
|
||||
- `roleId`: Role ID for role operations
|
||||
|
||||
**Pitfalls**:
|
||||
- User operations use account IDs (not email or display name)
|
||||
- Project roles differ from global permissions
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### JQL Syntax
|
||||
|
||||
**Common operators**:
|
||||
- `project = "PROJ"` - Filter by project
|
||||
- `status = "In Progress"` - Filter by status
|
||||
- `assignee = currentUser()` - Current user's issues
|
||||
- `created >= -7d` - Created in last 7 days
|
||||
- `labels = "bug"` - Filter by label
|
||||
- `priority = High` - Filter by priority
|
||||
- `ORDER BY created DESC` - Sort results
|
||||
|
||||
**Combinators**:
|
||||
- `AND` - Both conditions
|
||||
- `OR` - Either condition
|
||||
- `NOT` - Negate condition
|
||||
|
||||
### Pagination
|
||||
|
||||
- Use `startAt` and `maxResults` parameters
|
||||
- Check `total` in response to determine remaining pages
|
||||
- Continue until `startAt + maxResults >= total`
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Field Names**:
|
||||
- Custom fields use IDs like `customfield_10001`
|
||||
- Use JIRA_GET_FIELDS to discover field IDs and names
|
||||
- Field names in JQL may differ from API field names
|
||||
|
||||
**Authentication**:
|
||||
- Jira Cloud uses account IDs, not usernames
|
||||
- Site URL must be configured correctly in the connection
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Search issues (JQL) | JIRA_SEARCH_FOR_ISSUES_USING_JQL_POST | jql, maxResults |
|
||||
| Get issue | JIRA_GET_ISSUE | issueIdOrKey |
|
||||
| Create issue | JIRA_CREATE_ISSUE | project, issuetype, summary |
|
||||
| Edit issue | JIRA_EDIT_ISSUE | issueIdOrKey, fields |
|
||||
| Assign issue | JIRA_ASSIGN_ISSUE | issueIdOrKey, accountId |
|
||||
| Add comment | JIRA_ADD_COMMENT | issueIdOrKey, body |
|
||||
| List comments | JIRA_LIST_ISSUE_COMMENTS | issueIdOrKey |
|
||||
| List projects | JIRA_GET_ALL_PROJECTS | (none) |
|
||||
| Get project | JIRA_GET_PROJECT | projectIdOrKey |
|
||||
| List boards | JIRA_LIST_BOARDS | (none) |
|
||||
| List sprints | JIRA_LIST_SPRINTS | boardId |
|
||||
| Move to sprint | JIRA_MOVE_ISSUE_TO_SPRINT | sprintId, issues |
|
||||
| Create sprint | JIRA_CREATE_SPRINT | name, boardId |
|
||||
| Find users | JIRA_FIND_USERS | query |
|
||||
| Get fields | JIRA_GET_FIELDS | (none) |
|
||||
| List filters | JIRA_LIST_FILTERS | (none) |
|
||||
| Project roles | JIRA_GET_PROJECT_ROLES | projectIdOrKey |
|
||||
| Project versions | JIRA_GET_PROJECT_VERSIONS | projectIdOrKey |
|
||||
@@ -1,190 +0,0 @@
|
||||
---
|
||||
name: klaviyo-automation
|
||||
description: "Automate Klaviyo tasks via Rube MCP (Composio): manage email/SMS campaigns, inspect campaign messages, track tags, and monitor send jobs. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Klaviyo Automation via Rube MCP
|
||||
|
||||
Automate Klaviyo email and SMS marketing operations through Composio's Klaviyo toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Klaviyo connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `klaviyo`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `klaviyo`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Klaviyo authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. List and Filter Campaigns
|
||||
|
||||
**When to use**: User wants to browse, search, or filter marketing campaigns
|
||||
|
||||
**Tool sequence**:
|
||||
1. `KLAVIYO_GET_CAMPAIGNS` - List campaigns with channel and status filters [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `channel`: Campaign channel - 'email' or 'sms' (required by Klaviyo API)
|
||||
- `filter`: Additional filter string (e.g., `equals(status,"draft")`)
|
||||
- `sort`: Sort field with optional `-` prefix for descending (e.g., '-created_at', 'name')
|
||||
- `page_cursor`: Pagination cursor for next page
|
||||
- `include_archived`: Include archived campaigns (default: false)
|
||||
|
||||
**Pitfalls**:
|
||||
- `channel` is required; omitting it can produce incomplete or unexpected results
|
||||
- Pagination is mandatory for full coverage; a single call returns only one page (default ~10)
|
||||
- Follow `page_cursor` until exhausted to get all campaigns
|
||||
- Status filtering via `filter` (e.g., `equals(status,"draft")`) can return mixed statuses; always validate `data[].attributes.status` client-side
|
||||
- Status strings are case-sensitive and can be compound (e.g., 'Cancelled: No Recipients')
|
||||
- Response shape is nested: `response.data.data` with status at `data[].attributes.status`
|
||||
|
||||
### 2. Get Campaign Details
|
||||
|
||||
**When to use**: User wants detailed information about a specific campaign
|
||||
|
||||
**Tool sequence**:
|
||||
1. `KLAVIYO_GET_CAMPAIGNS` - Find campaign to get its ID [Prerequisite]
|
||||
2. `KLAVIYO_GET_CAMPAIGN` - Retrieve full campaign details [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `campaign_id`: Campaign ID string (e.g., '01GDDKASAP8TKDDA2GRZDSVP4H')
|
||||
- `include_messages`: Include campaign messages in response
|
||||
- `include_tags`: Include tags in response
|
||||
|
||||
**Pitfalls**:
|
||||
- Campaign IDs are alphanumeric strings, not numeric
|
||||
- `include_messages` and `include_tags` add related data to the response via Klaviyo's include mechanism
|
||||
- Campaign details include audiences, send strategy, tracking options, and scheduling info
|
||||
|
||||
### 3. Inspect Campaign Messages
|
||||
|
||||
**When to use**: User wants to view the email/SMS content of a campaign
|
||||
|
||||
**Tool sequence**:
|
||||
1. `KLAVIYO_GET_CAMPAIGN` - Find campaign and its message IDs [Prerequisite]
|
||||
2. `KLAVIYO_GET_CAMPAIGN_MESSAGE` - Get message content details [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `id`: Message ID string
|
||||
- `fields__campaign__message`: Sparse fieldset for message attributes (e.g., 'content.subject', 'content.from_email', 'content.body')
|
||||
- `fields__campaign`: Sparse fieldset for campaign attributes
|
||||
- `fields__template`: Sparse fieldset for template attributes
|
||||
- `include`: Related resources to include ('campaign', 'template')
|
||||
|
||||
**Pitfalls**:
|
||||
- Message IDs are separate from campaign IDs; extract from campaign response
|
||||
- Sparse fieldset syntax uses dot notation for nested fields: 'content.subject', 'content.from_email'
|
||||
- Email messages have content fields: subject, preview_text, from_email, from_label, reply_to_email
|
||||
- SMS messages have content fields: body
|
||||
- Including 'template' provides the HTML/text content of the email
|
||||
|
||||
### 4. Manage Campaign Tags
|
||||
|
||||
**When to use**: User wants to view tags associated with campaigns for organization
|
||||
|
||||
**Tool sequence**:
|
||||
1. `KLAVIYO_GET_CAMPAIGN_RELATIONSHIPS_TAGS` - Get tag IDs for a campaign [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `id`: Campaign ID string
|
||||
|
||||
**Pitfalls**:
|
||||
- Returns only tag IDs, not tag names/details
|
||||
- Tag IDs can be used with Klaviyo's tag endpoints for full details
|
||||
- Rate limit: 3/s burst, 60/m steady (stricter than other endpoints)
|
||||
|
||||
### 5. Monitor Campaign Send Jobs
|
||||
|
||||
**When to use**: User wants to check the status of a campaign send operation
|
||||
|
||||
**Tool sequence**:
|
||||
1. `KLAVIYO_GET_CAMPAIGN_SEND_JOB` - Check send job status [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `id`: Send job ID
|
||||
|
||||
**Pitfalls**:
|
||||
- Send job IDs are returned when a campaign send is initiated
|
||||
- Job statuses indicate whether the send is queued, in progress, complete, or failed
|
||||
- Rate limit: 10/s burst, 150/m steady
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Campaign Discovery Pattern
|
||||
|
||||
```
|
||||
1. Call KLAVIYO_GET_CAMPAIGNS with channel='email'
|
||||
2. Paginate through all results via page_cursor
|
||||
3. Filter by status client-side for accuracy
|
||||
4. Extract campaign IDs for detailed inspection
|
||||
```
|
||||
|
||||
### Sparse Fieldset Pattern
|
||||
|
||||
Klaviyo supports sparse fieldsets to reduce response size:
|
||||
```
|
||||
fields__campaign__message=['content.subject', 'content.from_email', 'send_times']
|
||||
fields__campaign=['name', 'status', 'send_time']
|
||||
fields__template=['name', 'html', 'text']
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Klaviyo uses cursor-based pagination
|
||||
- Check response for `page_cursor` in the pagination metadata
|
||||
- Pass cursor as `page_cursor` in next request
|
||||
- Default page size is ~10 campaigns
|
||||
- Continue until no more cursor is returned
|
||||
|
||||
### Filter Syntax
|
||||
|
||||
```
|
||||
- equals(status,"draft") - Campaigns in draft status
|
||||
- equals(name,"Newsletter") - Campaign named "Newsletter"
|
||||
- greater-than(created_at,"2024-01-01T00:00:00Z") - Created after date
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**API Version**:
|
||||
- Klaviyo API uses versioned endpoints (e.g., v2024-07-15)
|
||||
- Response schemas may change between API versions
|
||||
- Tool responses follow the version configured in the Composio integration
|
||||
|
||||
**Response Nesting**:
|
||||
- Data is nested: `response.data.data[].attributes`
|
||||
- Campaign status at `data[].attributes.status`
|
||||
- Mis-parsing the nesting yields empty or incorrect results
|
||||
- Always navigate through the full path defensively
|
||||
|
||||
**Rate Limits**:
|
||||
- Burst: 10/s (3/s for tag endpoints)
|
||||
- Steady: 150/m (60/m for tag endpoints)
|
||||
- Required scope: campaigns:read
|
||||
- Implement backoff on 429 responses
|
||||
|
||||
**Status Values**:
|
||||
- Status strings are case-sensitive
|
||||
- Compound statuses exist (e.g., 'Cancelled: No Recipients')
|
||||
- Server-side filtering may return mixed statuses; always validate client-side
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List campaigns | KLAVIYO_GET_CAMPAIGNS | channel, filter, sort, page_cursor |
|
||||
| Get campaign details | KLAVIYO_GET_CAMPAIGN | campaign_id, include_messages, include_tags |
|
||||
| Get campaign message | KLAVIYO_GET_CAMPAIGN_MESSAGE | id, fields__campaign__message |
|
||||
| Get campaign tags | KLAVIYO_GET_CAMPAIGN_RELATIONSHIPS_TAGS | id |
|
||||
| Get send job status | KLAVIYO_GET_CAMPAIGN_SEND_JOB | id |
|
||||
@@ -1,178 +0,0 @@
|
||||
---
|
||||
name: linear-automation
|
||||
description: "Automate Linear tasks via Rube MCP (Composio): issues, projects, cycles, teams, labels. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Linear Automation via Rube MCP
|
||||
|
||||
Automate Linear operations through Composio's Linear toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Linear connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `linear`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `linear`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Linear OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Manage Issues
|
||||
|
||||
**When to use**: User wants to create, search, update, or list Linear issues
|
||||
|
||||
**Tool sequence**:
|
||||
1. `LINEAR_GET_ALL_LINEAR_TEAMS` - Get team IDs [Prerequisite]
|
||||
2. `LINEAR_LIST_LINEAR_STATES` - Get workflow states for a team [Prerequisite]
|
||||
3. `LINEAR_CREATE_LINEAR_ISSUE` - Create a new issue [Optional]
|
||||
4. `LINEAR_SEARCH_ISSUES` / `LINEAR_LIST_LINEAR_ISSUES` - Find issues [Optional]
|
||||
5. `LINEAR_GET_LINEAR_ISSUE` - Get issue details [Optional]
|
||||
6. `LINEAR_UPDATE_ISSUE` - Update issue properties [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `team_id`: Team ID (required for creation)
|
||||
- `title`: Issue title
|
||||
- `description`: Issue description (Markdown supported)
|
||||
- `state_id`: Workflow state ID
|
||||
- `assignee_id`: Assignee user ID
|
||||
- `priority`: 0 (none), 1 (urgent), 2 (high), 3 (medium), 4 (low)
|
||||
- `label_ids`: Array of label IDs
|
||||
|
||||
**Pitfalls**:
|
||||
- Team ID is required when creating issues; use GET_ALL_LINEAR_TEAMS first
|
||||
- State IDs are team-specific; use LIST_LINEAR_STATES with the correct team
|
||||
- Priority uses integer values 0-4, not string names
|
||||
|
||||
### 2. Manage Projects
|
||||
|
||||
**When to use**: User wants to create or update Linear projects
|
||||
|
||||
**Tool sequence**:
|
||||
1. `LINEAR_LIST_LINEAR_PROJECTS` - List existing projects [Optional]
|
||||
2. `LINEAR_CREATE_LINEAR_PROJECT` - Create a new project [Optional]
|
||||
3. `LINEAR_UPDATE_LINEAR_PROJECT` - Update project details [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Project name
|
||||
- `description`: Project description
|
||||
- `team_ids`: Array of team IDs associated with the project
|
||||
- `state`: Project state (e.g., 'planned', 'started', 'completed')
|
||||
|
||||
**Pitfalls**:
|
||||
- Projects span teams; they can be associated with multiple teams
|
||||
|
||||
### 3. Manage Cycles
|
||||
|
||||
**When to use**: User wants to work with Linear cycles (sprints)
|
||||
|
||||
**Tool sequence**:
|
||||
1. `LINEAR_GET_ALL_LINEAR_TEAMS` - Get team ID [Prerequisite]
|
||||
2. `LINEAR_GET_CYCLES_BY_TEAM_ID` / `LINEAR_LIST_LINEAR_CYCLES` - List cycles [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `team_id`: Team ID for cycle operations
|
||||
- `number`: Cycle number
|
||||
|
||||
**Pitfalls**:
|
||||
- Cycles are team-specific; always scope by team_id
|
||||
|
||||
### 4. Manage Labels and Comments
|
||||
|
||||
**When to use**: User wants to create labels or comment on issues
|
||||
|
||||
**Tool sequence**:
|
||||
1. `LINEAR_CREATE_LINEAR_LABEL` - Create a new label [Optional]
|
||||
2. `LINEAR_CREATE_LINEAR_COMMENT` - Comment on an issue [Optional]
|
||||
3. `LINEAR_UPDATE_LINEAR_COMMENT` - Edit a comment [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Label name
|
||||
- `color`: Label color (hex)
|
||||
- `issue_id`: Issue ID for comments
|
||||
- `body`: Comment body (Markdown)
|
||||
|
||||
**Pitfalls**:
|
||||
- Labels can be team-scoped or workspace-scoped
|
||||
- Comment body supports Markdown formatting
|
||||
|
||||
### 5. Custom GraphQL Queries
|
||||
|
||||
**When to use**: User needs advanced queries not covered by standard tools
|
||||
|
||||
**Tool sequence**:
|
||||
1. `LINEAR_RUN_QUERY_OR_MUTATION` - Execute custom GraphQL [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: GraphQL query or mutation string
|
||||
- `variables`: Variables for the query
|
||||
|
||||
**Pitfalls**:
|
||||
- Requires knowledge of Linear's GraphQL schema
|
||||
- Rate limits apply to GraphQL queries
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Team name -> Team ID**:
|
||||
```
|
||||
1. Call LINEAR_GET_ALL_LINEAR_TEAMS
|
||||
2. Find team by name in response
|
||||
3. Extract id field
|
||||
```
|
||||
|
||||
**State name -> State ID**:
|
||||
```
|
||||
1. Call LINEAR_LIST_LINEAR_STATES with team_id
|
||||
2. Find state by name
|
||||
3. Extract id field
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Linear tools return paginated results
|
||||
- Check for pagination cursors in responses
|
||||
- Pass cursor to next request for additional pages
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Team Scoping**:
|
||||
- Issues, states, and cycles are team-specific
|
||||
- Always resolve team_id before creating issues
|
||||
|
||||
**Priority Values**:
|
||||
- 0 = No priority, 1 = Urgent, 2 = High, 3 = Medium, 4 = Low
|
||||
- Use integer values, not string names
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List teams | LINEAR_GET_ALL_LINEAR_TEAMS | (none) |
|
||||
| Create issue | LINEAR_CREATE_LINEAR_ISSUE | team_id, title, description |
|
||||
| Search issues | LINEAR_SEARCH_ISSUES | query |
|
||||
| List issues | LINEAR_LIST_LINEAR_ISSUES | team_id, filters |
|
||||
| Get issue | LINEAR_GET_LINEAR_ISSUE | issue_id |
|
||||
| Update issue | LINEAR_UPDATE_ISSUE | issue_id, fields |
|
||||
| List states | LINEAR_LIST_LINEAR_STATES | team_id |
|
||||
| List projects | LINEAR_LIST_LINEAR_PROJECTS | (none) |
|
||||
| Create project | LINEAR_CREATE_LINEAR_PROJECT | name, team_ids |
|
||||
| Update project | LINEAR_UPDATE_LINEAR_PROJECT | project_id, fields |
|
||||
| List cycles | LINEAR_LIST_LINEAR_CYCLES | team_id |
|
||||
| Get cycles | LINEAR_GET_CYCLES_BY_TEAM_ID | team_id |
|
||||
| Create label | LINEAR_CREATE_LINEAR_LABEL | name, color |
|
||||
| Create comment | LINEAR_CREATE_LINEAR_COMMENT | issue_id, body |
|
||||
| Update comment | LINEAR_UPDATE_LINEAR_COMMENT | comment_id, body |
|
||||
| List users | LINEAR_LIST_LINEAR_USERS | (none) |
|
||||
| Current user | LINEAR_GET_CURRENT_USER | (none) |
|
||||
| Run GraphQL | LINEAR_RUN_QUERY_OR_MUTATION | query, variables |
|
||||
@@ -1,175 +0,0 @@
|
||||
---
|
||||
name: linkedin-automation
|
||||
description: "Automate LinkedIn tasks via Rube MCP (Composio): create posts, manage profile, company info, comments, and image uploads. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# LinkedIn Automation via Rube MCP
|
||||
|
||||
Automate LinkedIn operations through Composio's LinkedIn toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active LinkedIn connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `linkedin`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `linkedin`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete LinkedIn OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create a LinkedIn Post
|
||||
|
||||
**When to use**: User wants to publish a text post on LinkedIn
|
||||
|
||||
**Tool sequence**:
|
||||
1. `LINKEDIN_GET_MY_INFO` - Get authenticated user's profile info [Prerequisite]
|
||||
2. `LINKEDIN_REGISTER_IMAGE_UPLOAD` - Register image upload if post includes an image [Optional]
|
||||
3. `LINKEDIN_CREATE_LINKED_IN_POST` - Publish the post [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `text`: Post content text
|
||||
- `visibility`: 'PUBLIC' or 'CONNECTIONS'
|
||||
- `media_title`: Title for attached media
|
||||
- `media_description`: Description for attached media
|
||||
|
||||
**Pitfalls**:
|
||||
- Must retrieve user profile URN via GET_MY_INFO before creating a post
|
||||
- Image uploads require a two-step process: register upload first, then include the asset in the post
|
||||
- Post text has character limits enforced by LinkedIn API
|
||||
- Visibility defaults may vary; always specify explicitly
|
||||
|
||||
### 2. Get Profile Information
|
||||
|
||||
**When to use**: User wants to retrieve their LinkedIn profile or company details
|
||||
|
||||
**Tool sequence**:
|
||||
1. `LINKEDIN_GET_MY_INFO` - Get authenticated user's profile [Required]
|
||||
2. `LINKEDIN_GET_COMPANY_INFO` - Get company page details [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- No parameters needed for GET_MY_INFO (uses authenticated user)
|
||||
- `organization_id`: Company/organization ID for GET_COMPANY_INFO
|
||||
|
||||
**Pitfalls**:
|
||||
- GET_MY_INFO returns the authenticated user only; cannot look up other users
|
||||
- Company info requires the numeric organization ID, not the company name or vanity URL
|
||||
- Some profile fields may be restricted based on OAuth scopes granted
|
||||
|
||||
### 3. Manage Post Images
|
||||
|
||||
**When to use**: User wants to upload and attach images to LinkedIn posts
|
||||
|
||||
**Tool sequence**:
|
||||
1. `LINKEDIN_REGISTER_IMAGE_UPLOAD` - Register an image upload with LinkedIn [Required]
|
||||
2. Upload the image binary to the returned upload URL [Required]
|
||||
3. `LINKEDIN_GET_IMAGES` - Verify uploaded image status [Optional]
|
||||
4. `LINKEDIN_CREATE_LINKED_IN_POST` - Create post with the image asset [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `owner`: URN of the image owner (user or organization)
|
||||
- `image_id`: ID of the uploaded image for GET_IMAGES
|
||||
|
||||
**Pitfalls**:
|
||||
- The upload is a two-phase process: register then upload binary
|
||||
- Image asset URN from registration must be used when creating the post
|
||||
- Supported formats typically include JPG, PNG, and GIF
|
||||
- Large images may take time to process before they are available
|
||||
|
||||
### 4. Comment on Posts
|
||||
|
||||
**When to use**: User wants to comment on an existing LinkedIn post
|
||||
|
||||
**Tool sequence**:
|
||||
1. `LINKEDIN_CREATE_COMMENT_ON_POST` - Add a comment to a post [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `post_id`: The URN or ID of the post to comment on
|
||||
- `text`: Comment content
|
||||
- `actor`: URN of the commenter (user or organization)
|
||||
|
||||
**Pitfalls**:
|
||||
- Post ID must be a valid LinkedIn URN format
|
||||
- The actor URN must match the authenticated user or a managed organization
|
||||
- Rate limits apply to comment creation; avoid rapid-fire comments
|
||||
|
||||
### 5. Delete a Post
|
||||
|
||||
**When to use**: User wants to remove a previously published LinkedIn post
|
||||
|
||||
**Tool sequence**:
|
||||
1. `LINKEDIN_DELETE_LINKED_IN_POST` - Delete the specified post [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `post_id`: The URN or ID of the post to delete
|
||||
|
||||
**Pitfalls**:
|
||||
- Deletion is permanent and cannot be undone
|
||||
- Only the post author or organization admin can delete a post
|
||||
- The post_id must be the exact URN returned when the post was created
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**User URN from profile**:
|
||||
```
|
||||
1. Call LINKEDIN_GET_MY_INFO
|
||||
2. Extract user URN (e.g., 'urn:li:person:XXXXXXXXXX')
|
||||
3. Use URN as actor/owner in subsequent calls
|
||||
```
|
||||
|
||||
**Organization ID from company**:
|
||||
```
|
||||
1. Call LINKEDIN_GET_COMPANY_INFO with organization_id
|
||||
2. Extract organization URN for posting as a company page
|
||||
```
|
||||
|
||||
### Image Upload Flow
|
||||
|
||||
- Call REGISTER_IMAGE_UPLOAD to get upload URL and asset URN
|
||||
- Upload the binary image to the provided URL
|
||||
- Use the asset URN when creating a post with media
|
||||
- Verify with GET_IMAGES if upload status is uncertain
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Authentication**:
|
||||
- LinkedIn OAuth tokens have limited scopes; ensure required permissions are granted
|
||||
- Tokens expire; re-authenticate if API calls return 401 errors
|
||||
|
||||
**URN Formats**:
|
||||
- LinkedIn uses URN identifiers (e.g., 'urn:li:person:ABC123')
|
||||
- Always use the full URN format, not just the alphanumeric ID portion
|
||||
- Organization URNs differ from person URNs
|
||||
|
||||
**Rate Limits**:
|
||||
- LinkedIn API has strict daily rate limits on post creation and comments
|
||||
- Implement backoff strategies for bulk operations
|
||||
- Monitor 429 responses and respect Retry-After headers
|
||||
|
||||
**Content Restrictions**:
|
||||
- Posts have character limits enforced by the API
|
||||
- Some content types (polls, documents) may require additional API features
|
||||
- HTML markup in post text is not supported
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Get my profile | LINKEDIN_GET_MY_INFO | (none) |
|
||||
| Create post | LINKEDIN_CREATE_LINKED_IN_POST | text, visibility |
|
||||
| Get company info | LINKEDIN_GET_COMPANY_INFO | organization_id |
|
||||
| Register image upload | LINKEDIN_REGISTER_IMAGE_UPLOAD | owner |
|
||||
| Get uploaded images | LINKEDIN_GET_IMAGES | image_id |
|
||||
| Delete post | LINKEDIN_DELETE_LINKED_IN_POST | post_id |
|
||||
| Comment on post | LINKEDIN_CREATE_COMMENT_ON_POST | post_id, text, actor |
|
||||
@@ -1,231 +0,0 @@
|
||||
---
|
||||
name: mailchimp-automation
|
||||
description: "Automate Mailchimp email marketing including campaigns, audiences, subscribers, segments, and analytics via Rube MCP (Composio). Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Mailchimp Automation via Rube MCP
|
||||
|
||||
Automate Mailchimp email marketing workflows including campaign creation and sending, audience/list management, subscriber operations, segmentation, and performance analytics through Composio's Mailchimp toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Mailchimp connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `mailchimp`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `mailchimp`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Mailchimp OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create and Send Email Campaigns
|
||||
|
||||
**When to use**: User wants to create, configure, test, and send an email campaign.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MAILCHIMP_GET_LISTS_INFO` - List available audiences and get list_id [Prerequisite]
|
||||
2. `MAILCHIMP_ADD_CAMPAIGN` - Create a new campaign with type, audience, subject, from name [Required]
|
||||
3. `MAILCHIMP_SET_CAMPAIGN_CONTENT` - Set HTML content for the campaign [Required]
|
||||
4. `MAILCHIMP_SEND_TEST_EMAIL` - Send preview to reviewers before live send [Optional]
|
||||
5. `MAILCHIMP_SEND_CAMPAIGN` - Send the campaign immediately [Required]
|
||||
6. `MAILCHIMP_SCHEDULE_CAMPAIGN` - Schedule for future delivery instead of immediate send [Optional]
|
||||
|
||||
**Key parameters for MAILCHIMP_ADD_CAMPAIGN**:
|
||||
- `type`: "regular", "plaintext", "rss", or "variate" (required)
|
||||
- `recipients__list__id`: Audience/list ID for recipients
|
||||
- `settings__subject__line`: Email subject line
|
||||
- `settings__from__name`: Sender display name
|
||||
- `settings__reply__to`: Reply-to email address (required for sending)
|
||||
- `settings__title`: Internal campaign title
|
||||
- `settings__preview__text`: Preview text shown in inbox
|
||||
|
||||
**Key parameters for MAILCHIMP_SET_CAMPAIGN_CONTENT**:
|
||||
- `campaign_id`: Campaign ID from creation step (required)
|
||||
- `html`: Raw HTML content for the email
|
||||
- `plain_text`: Plain-text version (auto-generated if omitted)
|
||||
- `template__id`: Use a pre-built template instead of raw HTML
|
||||
|
||||
**Pitfalls**:
|
||||
- `MAILCHIMP_SEND_CAMPAIGN` is irreversible; always send a test email first and get explicit user approval
|
||||
- Campaign must be in "save" (draft) status with valid audience, subject, from name, verified email, and content before sending
|
||||
- `MAILCHIMP_SCHEDULE_CAMPAIGN` requires a valid future datetime; past timestamps fail
|
||||
- Templates and HTML content must include compliant footer/unsubscribe merge tags
|
||||
- Mailchimp uses double-underscore notation for nested params (e.g., `settings__subject__line`)
|
||||
|
||||
### 2. Manage Audiences and Subscribers
|
||||
|
||||
**When to use**: User wants to view audiences, list subscribers, or check subscriber details.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MAILCHIMP_GET_LISTS_INFO` - List all audiences with member counts [Required]
|
||||
2. `MAILCHIMP_GET_LIST_INFO` - Get details for a specific audience [Optional]
|
||||
3. `MAILCHIMP_LIST_MEMBERS_INFO` - List members with status filter and pagination [Required]
|
||||
4. `MAILCHIMP_SEARCH_MEMBERS` - Search by email or name across lists [Optional]
|
||||
5. `MAILCHIMP_GET_MEMBER_INFO` - Get detailed profile for a specific subscriber [Optional]
|
||||
6. `MAILCHIMP_LIST_SEGMENTS` - List segments within an audience [Optional]
|
||||
|
||||
**Key parameters for MAILCHIMP_LIST_MEMBERS_INFO**:
|
||||
- `list_id`: Audience ID (required)
|
||||
- `status`: "subscribed", "unsubscribed", "cleaned", "pending", "transactional", "archived"
|
||||
- `count`: Records per page (default 10, max 1000)
|
||||
- `offset`: Pagination offset (default 0)
|
||||
- `sort_field`: "timestamp_opt", "timestamp_signup", or "last_changed"
|
||||
- `fields`: Comma-separated list to limit response size
|
||||
|
||||
**Pitfalls**:
|
||||
- `stats.avg_open_rate` and `stats.avg_click_rate` are 0-1 fractions, NOT 0-100 percentages
|
||||
- Always use `status="subscribed"` to filter active subscribers; omitting returns all statuses
|
||||
- Must paginate using `count` and `offset` until collected members match `total_items`
|
||||
- Large list responses may be truncated; data is under `response.data.members`
|
||||
|
||||
### 3. Add and Update Subscribers
|
||||
|
||||
**When to use**: User wants to add new subscribers, update existing ones, or bulk-manage list membership.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MAILCHIMP_GET_LIST_INFO` - Validate target audience exists [Prerequisite]
|
||||
2. `MAILCHIMP_SEARCH_MEMBERS` - Check if contact already exists [Optional]
|
||||
3. `MAILCHIMP_ADD_OR_UPDATE_LIST_MEMBER` - Upsert subscriber (create or update) [Required]
|
||||
4. `MAILCHIMP_ADD_MEMBER_TO_LIST` - Add new subscriber (create only) [Optional]
|
||||
5. `MAILCHIMP_BATCH_ADD_OR_REMOVE_MEMBERS` - Bulk manage segment membership [Optional]
|
||||
|
||||
**Key parameters for MAILCHIMP_ADD_OR_UPDATE_LIST_MEMBER**:
|
||||
- `list_id`: Audience ID (required)
|
||||
- `subscriber_hash`: MD5 hash of lowercase email (required)
|
||||
- `email_address`: Subscriber email (required)
|
||||
- `status_if_new`: Status for new subscribers: "subscribed", "pending", etc. (required)
|
||||
- `status`: Status for existing subscribers
|
||||
- `merge_fields`: Object with merge tag keys (e.g., `{"FNAME": "John", "LNAME": "Doe"}`)
|
||||
- `tags`: Array of tag strings
|
||||
|
||||
**Key parameters for MAILCHIMP_ADD_MEMBER_TO_LIST**:
|
||||
- `list_id`: Audience ID (required)
|
||||
- `email_address`: Subscriber email (required)
|
||||
- `status`: "subscribed", "pending", "unsubscribed", "cleaned", "transactional" (required)
|
||||
|
||||
**Pitfalls**:
|
||||
- `subscriber_hash` must be MD5 of the **lowercase** email; incorrect casing causes 404s or duplicates
|
||||
- Use `MAILCHIMP_ADD_OR_UPDATE_LIST_MEMBER` (upsert) instead of `MAILCHIMP_ADD_MEMBER_TO_LIST` to avoid duplicate errors
|
||||
- `status_if_new` determines status only for new contacts; existing contacts use `status`
|
||||
- Use `skip_merge_validation: true` to bypass required merge field validation
|
||||
- `MAILCHIMP_BATCH_ADD_OR_REMOVE_MEMBERS` manages static segment membership, not list membership
|
||||
|
||||
### 4. View Campaign Reports and Analytics
|
||||
|
||||
**When to use**: User wants to review campaign performance, open rates, click rates, or subscriber engagement.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MAILCHIMP_LIST_CAMPAIGNS` - List sent campaigns with report summaries [Required]
|
||||
2. `MAILCHIMP_SEARCH_CAMPAIGNS` - Find campaigns by name, subject, or content [Optional]
|
||||
3. `MAILCHIMP_GET_CAMPAIGN_REPORT` - Get detailed performance report for a campaign [Required]
|
||||
4. `MAILCHIMP_LIST_CAMPAIGN_REPORTS` - Bulk fetch reports across multiple campaigns [Optional]
|
||||
5. `MAILCHIMP_LIST_CAMPAIGN_DETAILS` - Get link-level click statistics [Optional]
|
||||
6. `MAILCHIMP_GET_CAMPAIGN_LINK_DETAILS` - Drill into specific link click data [Optional]
|
||||
7. `MAILCHIMP_LIST_CLICKED_LINK_SUBSCRIBERS` - See who clicked a specific link [Optional]
|
||||
8. `MAILCHIMP_GET_SUBSCRIBER_EMAIL_ACTIVITY` - Get per-subscriber campaign activity [Optional]
|
||||
9. `MAILCHIMP_GET_CAMPAIGN_CONTENT` - Retrieve campaign HTML content [Optional]
|
||||
|
||||
**Key parameters for MAILCHIMP_LIST_CAMPAIGNS**:
|
||||
- `status`: "save", "paused", "schedule", "sending", "sent"
|
||||
- `count` / `offset`: Pagination (default 10, max 1000)
|
||||
- `since_send_time` / `before_send_time`: ISO 8601 date range filter
|
||||
- `sort_field`: "create_time" or "send_time"
|
||||
- `fields`: Limit response fields for performance
|
||||
|
||||
**Key parameters for MAILCHIMP_GET_CAMPAIGN_REPORT**:
|
||||
- `campaign_id`: Campaign ID (required)
|
||||
- Returns: opens, clicks, bounces, unsubscribes, timeseries, industry_stats
|
||||
|
||||
**Pitfalls**:
|
||||
- `MAILCHIMP_LIST_CAMPAIGNS` only returns high-level `report_summary`; use `MAILCHIMP_GET_CAMPAIGN_REPORT` for detailed metrics
|
||||
- Draft/unsent campaigns lack meaningful report data
|
||||
- When using `fields` parameter on LIST_CAMPAIGNS, explicitly request `send_time` and `report_summary` subfields
|
||||
- Pagination defaults are low (10 records); iterate with `count` and `offset` until `total_items` is covered
|
||||
- `send_time` is ISO 8601 with timezone; parse carefully
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
Always resolve names to IDs before operations:
|
||||
- **Audience name -> list_id**: `MAILCHIMP_GET_LISTS_INFO` and match by name
|
||||
- **Subscriber email -> subscriber_hash**: Compute MD5 of lowercase email in code
|
||||
- **Campaign name -> campaign_id**: `MAILCHIMP_SEARCH_CAMPAIGNS` with query
|
||||
- **Segment name -> segment_id**: `MAILCHIMP_LIST_SEGMENTS` with list_id
|
||||
|
||||
### Pagination
|
||||
Mailchimp uses offset-based pagination:
|
||||
- Use `count` (page size, max 1000) and `offset` (skip N records)
|
||||
- Continue until collected records match `total_items` from the response
|
||||
- Default `count` is 10; always set explicitly for bulk operations
|
||||
- Search endpoints max at 10 pages (300 results for 30/page)
|
||||
|
||||
### Subscriber Hash
|
||||
Many endpoints require `subscriber_hash` (MD5 of lowercase email):
|
||||
```
|
||||
import hashlib
|
||||
subscriber_hash = hashlib.md5(email.lower().encode()).hexdigest()
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
### ID Formats
|
||||
- `list_id` (audience ID) is a short alphanumeric string (e.g., "abc123def4")
|
||||
- `campaign_id` is an alphanumeric string
|
||||
- `subscriber_hash` is an MD5 hex string (32 characters)
|
||||
- Segment IDs are integers
|
||||
|
||||
### Rate Limits
|
||||
- Mailchimp enforces API rate limits; use batching for bulk subscriber operations
|
||||
- High-volume use of GET_MEMBER_INFO and ADD_OR_UPDATE_LIST_MEMBER can trigger throttling
|
||||
- Use `MAILCHIMP_BATCH_ADD_OR_REMOVE_MEMBERS` for bulk segment operations
|
||||
|
||||
### Parameter Quirks
|
||||
- Nested parameters use double-underscore notation: `settings__subject__line`, `recipients__list__id`
|
||||
- `avg_open_rate` and `avg_click_rate` are 0-1 fractions, not percentages
|
||||
- `status_if_new` only applies to new contacts in upsert operations
|
||||
- `subscriber_hash` must be MD5 of lowercase email; wrong casing creates phantom records
|
||||
- Campaign `type` is required for creation; most common is "regular"
|
||||
- `MAILCHIMP_SEND_CAMPAIGN` returns HTTP 204 on success (no body)
|
||||
|
||||
### Content and Compliance
|
||||
- Campaign HTML must include unsubscribe link and physical address (merge tags)
|
||||
- Content must be set via `MAILCHIMP_SET_CAMPAIGN_CONTENT` before sending
|
||||
- Test emails require campaign to have content already set
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List audiences | `MAILCHIMP_GET_LISTS_INFO` | `count`, `offset` |
|
||||
| Get audience details | `MAILCHIMP_GET_LIST_INFO` | `list_id` |
|
||||
| Create campaign | `MAILCHIMP_ADD_CAMPAIGN` | `type`, `recipients__list__id`, `settings__subject__line` |
|
||||
| Set campaign content | `MAILCHIMP_SET_CAMPAIGN_CONTENT` | `campaign_id`, `html` |
|
||||
| Send test email | `MAILCHIMP_SEND_TEST_EMAIL` | `campaign_id`, `test_emails` |
|
||||
| Send campaign | `MAILCHIMP_SEND_CAMPAIGN` | `campaign_id` |
|
||||
| Schedule campaign | `MAILCHIMP_SCHEDULE_CAMPAIGN` | `campaign_id`, `schedule_time` |
|
||||
| Get campaign info | `MAILCHIMP_GET_CAMPAIGN_INFO` | `campaign_id` |
|
||||
| Search campaigns | `MAILCHIMP_SEARCH_CAMPAIGNS` | `query` |
|
||||
| List campaigns | `MAILCHIMP_LIST_CAMPAIGNS` | `status`, `count`, `offset` |
|
||||
| Replicate campaign | `MAILCHIMP_REPLICATE_CAMPAIGN` | `campaign_id` |
|
||||
| List subscribers | `MAILCHIMP_LIST_MEMBERS_INFO` | `list_id`, `status`, `count`, `offset` |
|
||||
| Search members | `MAILCHIMP_SEARCH_MEMBERS` | `query`, `list_id` |
|
||||
| Get member info | `MAILCHIMP_GET_MEMBER_INFO` | `list_id`, `subscriber_hash` |
|
||||
| Add subscriber | `MAILCHIMP_ADD_MEMBER_TO_LIST` | `list_id`, `email_address`, `status` |
|
||||
| Upsert subscriber | `MAILCHIMP_ADD_OR_UPDATE_LIST_MEMBER` | `list_id`, `subscriber_hash`, `email_address`, `status_if_new` |
|
||||
| Batch members | `MAILCHIMP_BATCH_ADD_OR_REMOVE_MEMBERS` | `list_id`, `segment_id` |
|
||||
| List segments | `MAILCHIMP_LIST_SEGMENTS` | `list_id` |
|
||||
| Campaign report | `MAILCHIMP_GET_CAMPAIGN_REPORT` | `campaign_id` |
|
||||
| All reports | `MAILCHIMP_LIST_CAMPAIGN_REPORTS` | `count`, `offset` |
|
||||
| Link click details | `MAILCHIMP_LIST_CAMPAIGN_DETAILS` | `campaign_id`, `count` |
|
||||
| Subscriber activity | `MAILCHIMP_GET_SUBSCRIBER_EMAIL_ACTIVITY` | `campaign_id`, `subscriber_hash` |
|
||||
| Member recent activity | `MAILCHIMP_VIEW_RECENT_ACTIVITY` | `list_id`, `subscriber_hash` |
|
||||
| Campaign content | `MAILCHIMP_GET_CAMPAIGN_CONTENT` | `campaign_id` |
|
||||
@@ -1,201 +0,0 @@
|
||||
---
|
||||
name: make-automation
|
||||
description: "Automate Make (Integromat) tasks via Rube MCP (Composio): operations, enums, language and timezone lookups. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Make Automation via Rube MCP
|
||||
|
||||
Automate Make (formerly Integromat) operations through Composio's Make toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Make connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `make`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `make`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Make authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Get Operations Data
|
||||
|
||||
**When to use**: User wants to retrieve operation logs or usage data from Make scenarios
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MAKE_GET_OPERATIONS` - Retrieve operation records [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- Check current schema via RUBE_SEARCH_TOOLS for available filters
|
||||
- May include date range, scenario ID, or status filters
|
||||
|
||||
**Pitfalls**:
|
||||
- Operations data may be paginated; check for pagination tokens
|
||||
- Date filters must match expected format from schema
|
||||
- Large result sets should be filtered by date range or scenario
|
||||
|
||||
### 2. List Available Languages
|
||||
|
||||
**When to use**: User wants to see supported languages for Make scenarios or interfaces
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MAKE_LIST_ENUMS_LANGUAGES` - Get all supported language codes [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- No required parameters; returns complete language list
|
||||
|
||||
**Pitfalls**:
|
||||
- Language codes follow standard locale format (e.g., 'en', 'fr', 'de')
|
||||
- List is static and rarely changes; cache results when possible
|
||||
|
||||
### 3. List Available Timezones
|
||||
|
||||
**When to use**: User wants to see supported timezones for scheduling Make scenarios
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MAKE_LIST_ENUMS_TIMEZONES` - Get all supported timezone identifiers [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- No required parameters; returns complete timezone list
|
||||
|
||||
**Pitfalls**:
|
||||
- Timezone identifiers use IANA format (e.g., 'America/New_York', 'Europe/London')
|
||||
- List is static and rarely changes; cache results when possible
|
||||
- Use these exact timezone strings when configuring scenario schedules
|
||||
|
||||
### 4. Scenario Configuration Lookup
|
||||
|
||||
**When to use**: User needs to configure scenarios with correct language and timezone values
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MAKE_LIST_ENUMS_LANGUAGES` - Get valid language codes [Required]
|
||||
2. `MAKE_LIST_ENUMS_TIMEZONES` - Get valid timezone identifiers [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- No parameters needed for either call
|
||||
|
||||
**Pitfalls**:
|
||||
- Always verify language and timezone values against these enums before using in configuration
|
||||
- Using invalid values in scenario configuration will cause errors
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Enum Validation
|
||||
|
||||
Before configuring any Make scenario properties that accept language or timezone:
|
||||
```
|
||||
1. Call MAKE_LIST_ENUMS_LANGUAGES or MAKE_LIST_ENUMS_TIMEZONES
|
||||
2. Verify the desired value exists in the returned list
|
||||
3. Use the exact string value from the enum list
|
||||
```
|
||||
|
||||
### Operations Monitoring
|
||||
|
||||
```
|
||||
1. Call MAKE_GET_OPERATIONS with date range filters
|
||||
2. Analyze operation counts, statuses, and error rates
|
||||
3. Identify failed operations for troubleshooting
|
||||
```
|
||||
|
||||
### Caching Strategy for Enums
|
||||
|
||||
Since language and timezone lists are static:
|
||||
```
|
||||
1. Call MAKE_LIST_ENUMS_LANGUAGES once at workflow start
|
||||
2. Store results in memory or local cache
|
||||
3. Validate user inputs against cached values
|
||||
4. Refresh cache only when starting a new session
|
||||
```
|
||||
|
||||
### Operations Analysis Workflow
|
||||
|
||||
For scenario health monitoring:
|
||||
```
|
||||
1. Call MAKE_GET_OPERATIONS with recent date range
|
||||
2. Group operations by scenario ID
|
||||
3. Calculate success/failure ratios per scenario
|
||||
4. Identify scenarios with high error rates
|
||||
5. Report findings to user or notification channel
|
||||
```
|
||||
|
||||
### Integration with Other Toolkits
|
||||
|
||||
Make workflows often connect to other apps. Compose multi-tool workflows:
|
||||
```
|
||||
1. Call RUBE_SEARCH_TOOLS to find tools for the target app
|
||||
2. Connect required toolkits via RUBE_MANAGE_CONNECTIONS
|
||||
3. Use Make operations data to understand workflow execution patterns
|
||||
4. Execute equivalent workflows directly via individual app toolkits
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Limited Toolkit**:
|
||||
- The Make toolkit in Composio currently has limited tools (operations, languages, timezones)
|
||||
- For full scenario management (creating, editing, running scenarios), consider using Make's native API
|
||||
- Always call RUBE_SEARCH_TOOLS to check for newly available tools
|
||||
- The toolkit may be expanded over time; re-check periodically
|
||||
|
||||
**Operations Data**:
|
||||
- Operation records may have significant volume for active accounts
|
||||
- Always filter by date range to avoid fetching excessive data
|
||||
- Operation counts relate to Make's pricing tiers and quota usage
|
||||
- Failed operations should be investigated; they may indicate scenario configuration issues
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` key
|
||||
- Enum lists return arrays of objects with code and label fields
|
||||
- Operations data includes nested metadata about scenario execution
|
||||
- Parse defensively with fallbacks for optional fields
|
||||
|
||||
**Rate Limits**:
|
||||
- Make API has rate limits per API token
|
||||
- Avoid rapid repeated calls to the same endpoint
|
||||
- Cache enum results (languages, timezones) as they rarely change
|
||||
- Operations queries should use targeted date ranges
|
||||
|
||||
**Authentication**:
|
||||
- Make API uses token-based authentication
|
||||
- Tokens may have different permission scopes
|
||||
- Some operations data may be restricted based on token scope
|
||||
- Check that the authenticated user has access to the target organization
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Get operations | MAKE_GET_OPERATIONS | (check schema for filters) |
|
||||
| List languages | MAKE_LIST_ENUMS_LANGUAGES | (none) |
|
||||
| List timezones | MAKE_LIST_ENUMS_TIMEZONES | (none) |
|
||||
|
||||
## Additional Notes
|
||||
|
||||
### Alternative Approaches
|
||||
|
||||
Since the Make toolkit has limited tools, consider these alternatives for common Make use cases:
|
||||
|
||||
| Make Use Case | Alternative Approach |
|
||||
|--------------|---------------------|
|
||||
| Trigger a scenario | Use Make's native webhook or API endpoint directly |
|
||||
| Create a scenario | Use Make's scenario management API directly |
|
||||
| Schedule execution | Use RUBE_MANAGE_RECIPE_SCHEDULE with composed workflows |
|
||||
| Multi-app workflow | Compose individual toolkit tools via RUBE_MULTI_EXECUTE_TOOL |
|
||||
| Data transformation | Use RUBE_REMOTE_WORKBENCH for complex processing |
|
||||
|
||||
### Composing Equivalent Workflows
|
||||
|
||||
Instead of relying solely on Make's toolkit, build equivalent automation directly:
|
||||
1. Identify the apps involved in your Make scenario
|
||||
2. Search for each app's tools via RUBE_SEARCH_TOOLS
|
||||
3. Connect all required toolkits
|
||||
4. Build the workflow step-by-step using individual app tools
|
||||
5. Save as a recipe via RUBE_CREATE_UPDATE_RECIPE for reuse
|
||||
@@ -1,211 +0,0 @@
|
||||
---
|
||||
name: microsoft-teams-automation
|
||||
description: "Automate Microsoft Teams tasks via Rube MCP (Composio): send messages, manage channels, create meetings, handle chats, and search messages. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Microsoft Teams Automation via Rube MCP
|
||||
|
||||
Automate Microsoft Teams operations through Composio's Microsoft Teams toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Microsoft Teams connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `microsoft_teams`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `microsoft_teams`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Microsoft OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Send Channel Messages
|
||||
|
||||
**When to use**: User wants to post a message to a Teams channel
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MICROSOFT_TEAMS_TEAMS_LIST` - List teams to find target team [Prerequisite]
|
||||
2. `MICROSOFT_TEAMS_TEAMS_LIST_CHANNELS` - List channels in the team [Prerequisite]
|
||||
3. `MICROSOFT_TEAMS_TEAMS_POST_CHANNEL_MESSAGE` - Post the message [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `team_id`: UUID of the team (from TEAMS_LIST)
|
||||
- `channel_id`: Channel ID (from LIST_CHANNELS, format: '19:...@thread.tacv2')
|
||||
- `content`: Message text or HTML
|
||||
- `content_type`: 'text' or 'html'
|
||||
|
||||
**Pitfalls**:
|
||||
- team_id must be a valid UUID format
|
||||
- channel_id must be in thread format (e.g., '19:abc@thread.tacv2')
|
||||
- TEAMS_LIST may paginate (~100 items/page); follow @odata.nextLink to find all teams
|
||||
- LIST_CHANNELS can return 403 if user lacks access to the team
|
||||
- Messages over ~28KB can trigger 400/413 errors; split long content
|
||||
- Throttling may return 429; use exponential backoff (1s/2s/4s)
|
||||
|
||||
### 2. Send Chat Messages
|
||||
|
||||
**When to use**: User wants to send a direct or group chat message
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MICROSOFT_TEAMS_CHATS_GET_ALL_CHATS` - List existing chats [Optional]
|
||||
2. `MICROSOFT_TEAMS_LIST_USERS` - Find users for new chats [Optional]
|
||||
3. `MICROSOFT_TEAMS_TEAMS_CREATE_CHAT` - Create a new chat [Optional]
|
||||
4. `MICROSOFT_TEAMS_TEAMS_POST_CHAT_MESSAGE` - Send the message [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `chat_id`: Chat ID (from GET_ALL_CHATS or CREATE_CHAT)
|
||||
- `content`: Message content
|
||||
- `content_type`: 'text' or 'html'
|
||||
- `chatType`: 'oneOnOne' or 'group' (for CREATE_CHAT)
|
||||
- `members`: Array of member objects (for CREATE_CHAT)
|
||||
|
||||
**Pitfalls**:
|
||||
- CREATE_CHAT requires the authenticated user as one of the members
|
||||
- oneOnOne chats return existing chat if one already exists between the two users
|
||||
- group chats require at least one member with 'owner' role
|
||||
- member user_odata_bind must use full Microsoft Graph URL format
|
||||
- Chat filter support is very limited; filter client-side when needed
|
||||
|
||||
### 3. Create Online Meetings
|
||||
|
||||
**When to use**: User wants to schedule a Microsoft Teams meeting
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MICROSOFT_TEAMS_LIST_USERS` - Find participant user IDs [Optional]
|
||||
2. `MICROSOFT_TEAMS_CREATE_MEETING` - Create the meeting [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `subject`: Meeting title
|
||||
- `start_date_time`: ISO 8601 start time (e.g., '2024-08-15T10:00:00Z')
|
||||
- `end_date_time`: ISO 8601 end time (must be after start)
|
||||
- `participants`: Array of user objects with user_id and role
|
||||
|
||||
**Pitfalls**:
|
||||
- end_date_time must be strictly after start_date_time
|
||||
- Participants require valid Microsoft user_id (GUID) values, not emails
|
||||
- This creates a standalone meeting not linked to a calendar event
|
||||
- For calendar-linked meetings, use OUTLOOK_CALENDAR_CREATE_EVENT with is_online_meeting=true
|
||||
|
||||
### 4. Manage Teams and Channels
|
||||
|
||||
**When to use**: User wants to list, create, or manage teams and channels
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MICROSOFT_TEAMS_TEAMS_LIST` - List all accessible teams [Required]
|
||||
2. `MICROSOFT_TEAMS_GET_TEAM` - Get details for a specific team [Optional]
|
||||
3. `MICROSOFT_TEAMS_TEAMS_LIST_CHANNELS` - List channels in a team [Optional]
|
||||
4. `MICROSOFT_TEAMS_GET_CHANNEL` - Get channel details [Optional]
|
||||
5. `MICROSOFT_TEAMS_TEAMS_CREATE_CHANNEL` - Create a new channel [Optional]
|
||||
6. `MICROSOFT_TEAMS_LIST_TEAM_MEMBERS` - List team members [Optional]
|
||||
7. `MICROSOFT_TEAMS_ADD_MEMBER_TO_TEAM` - Add a member to the team [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `team_id`: Team UUID
|
||||
- `channel_id`: Channel ID in thread format
|
||||
- `filter`: OData filter string (e.g., "startsWith(displayName,'Project')")
|
||||
- `select`: Comma-separated properties to return
|
||||
|
||||
**Pitfalls**:
|
||||
- TEAMS_LIST pagination: follow @odata.nextLink in large tenants
|
||||
- Private/shared channels may be omitted unless permissions align
|
||||
- GET_CHANNEL returns 404 if team_id or channel_id is wrong
|
||||
- Always source IDs from list operations; do not guess ID formats
|
||||
|
||||
### 5. Search Messages
|
||||
|
||||
**When to use**: User wants to find messages across Teams chats and channels
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MICROSOFT_TEAMS_SEARCH_MESSAGES` - Search with KQL syntax [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: KQL search query (supports from:, sent:, attachments, boolean logic)
|
||||
|
||||
**Pitfalls**:
|
||||
- Newly posted messages may take 30-60 seconds to appear in search
|
||||
- Search is eventually consistent; do not rely on it for immediate delivery confirmation
|
||||
- Use message listing tools for real-time message verification
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Team and Channel ID Resolution
|
||||
|
||||
```
|
||||
1. Call MICROSOFT_TEAMS_TEAMS_LIST
|
||||
2. Find team by displayName
|
||||
3. Extract team id (UUID format)
|
||||
4. Call MICROSOFT_TEAMS_TEAMS_LIST_CHANNELS with team_id
|
||||
5. Find channel by displayName
|
||||
6. Extract channel id (19:...@thread.tacv2 format)
|
||||
```
|
||||
|
||||
### User Resolution
|
||||
|
||||
```
|
||||
1. Call MICROSOFT_TEAMS_LIST_USERS
|
||||
2. Filter by displayName or email
|
||||
3. Extract user id (UUID format)
|
||||
4. Use for meeting participants, chat members, or team operations
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Teams/Users: Follow @odata.nextLink URL for next page
|
||||
- Chats: Auto-paginates up to limit; use top for page size (max 50)
|
||||
- Use `top` parameter to control page size
|
||||
- Continue until @odata.nextLink is absent
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Authentication and Permissions**:
|
||||
- Different operations require different Microsoft Graph permissions
|
||||
- 403 errors indicate insufficient permissions or team access
|
||||
- Some operations require admin consent in the Azure AD tenant
|
||||
|
||||
**ID Formats**:
|
||||
- Team IDs: UUID format (e.g., '87b0560f-fc0d-4442-add8-b380ca926707')
|
||||
- Channel IDs: Thread format (e.g., '19:abc123@thread.tacv2')
|
||||
- Chat IDs: Various formats (e.g., '19:meeting_xxx@thread.v2')
|
||||
- User IDs: UUID format
|
||||
- Never guess IDs; always resolve from list operations
|
||||
|
||||
**Rate Limits**:
|
||||
- Microsoft Graph enforces throttling
|
||||
- 429 responses include Retry-After header
|
||||
- Keep requests to a few per second
|
||||
- Batch operations help reduce total request count
|
||||
|
||||
**Message Formatting**:
|
||||
- HTML content_type supports rich formatting
|
||||
- Adaptive cards require additional handling
|
||||
- Message size limit is approximately 28KB
|
||||
- Split long content into multiple messages
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List teams | MICROSOFT_TEAMS_TEAMS_LIST | filter, select, top |
|
||||
| Get team details | MICROSOFT_TEAMS_GET_TEAM | team_id |
|
||||
| List channels | MICROSOFT_TEAMS_TEAMS_LIST_CHANNELS | team_id, filter |
|
||||
| Get channel | MICROSOFT_TEAMS_GET_CHANNEL | team_id, channel_id |
|
||||
| Create channel | MICROSOFT_TEAMS_TEAMS_CREATE_CHANNEL | team_id, displayName |
|
||||
| Post to channel | MICROSOFT_TEAMS_TEAMS_POST_CHANNEL_MESSAGE | team_id, channel_id, content |
|
||||
| List chats | MICROSOFT_TEAMS_CHATS_GET_ALL_CHATS | user_id, limit |
|
||||
| Create chat | MICROSOFT_TEAMS_TEAMS_CREATE_CHAT | chatType, members, topic |
|
||||
| Post to chat | MICROSOFT_TEAMS_TEAMS_POST_CHAT_MESSAGE | chat_id, content |
|
||||
| Create meeting | MICROSOFT_TEAMS_CREATE_MEETING | subject, start_date_time, end_date_time |
|
||||
| List users | MICROSOFT_TEAMS_LIST_USERS | filter, select, top |
|
||||
| List team members | MICROSOFT_TEAMS_LIST_TEAM_MEMBERS | team_id |
|
||||
| Add team member | MICROSOFT_TEAMS_ADD_MEMBER_TO_TEAM | team_id, user_id |
|
||||
| Search messages | MICROSOFT_TEAMS_SEARCH_MESSAGES | query |
|
||||
| Get chat message | MICROSOFT_TEAMS_GET_CHAT_MESSAGE | chat_id, message_id |
|
||||
| List joined teams | MICROSOFT_TEAMS_LIST_USER_JOINED_TEAMS | (none) |
|
||||
@@ -1,205 +0,0 @@
|
||||
---
|
||||
name: miro-automation
|
||||
description: "Automate Miro tasks via Rube MCP (Composio): boards, items, sticky notes, frames, sharing, connectors. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Miro Automation via Rube MCP
|
||||
|
||||
Automate Miro whiteboard operations through Composio's Miro toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Miro connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `miro`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `miro`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Miro OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. List and Browse Boards
|
||||
|
||||
**When to use**: User wants to find boards or get board details
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MIRO_GET_BOARDS2` - List all accessible boards [Required]
|
||||
2. `MIRO_GET_BOARD` - Get detailed info for a specific board [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: Search term to filter boards by name
|
||||
- `sort`: Sort by 'default', 'last_modified', 'last_opened', 'last_created', 'alphabetically'
|
||||
- `limit`: Number of results per page (max 50)
|
||||
- `offset`: Pagination offset
|
||||
- `board_id`: Specific board ID for detailed retrieval
|
||||
|
||||
**Pitfalls**:
|
||||
- Pagination uses offset-based approach, not cursor-based
|
||||
- Maximum 50 boards per page; iterate with offset for full list
|
||||
- Board IDs are long alphanumeric strings; always resolve by search first
|
||||
|
||||
### 2. Create Boards and Items
|
||||
|
||||
**When to use**: User wants to create a new board or add items to an existing board
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MIRO_CREATE_BOARD` - Create a new empty board [Optional]
|
||||
2. `MIRO_CREATE_STICKY_NOTE_ITEM` - Add sticky notes to a board [Optional]
|
||||
3. `MIRO_CREATE_FRAME_ITEM2` - Add frames to organize content [Optional]
|
||||
4. `MIRO_CREATE_ITEMS_IN_BULK` - Add multiple items at once [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `name` / `description`: Board name and description (for CREATE_BOARD)
|
||||
- `board_id`: Target board ID (required for all item creation)
|
||||
- `data`: Content object with `content` field for sticky note text
|
||||
- `style`: Styling object with `fillColor` for sticky note color
|
||||
- `position`: Object with `x` and `y` coordinates
|
||||
- `geometry`: Object with `width` and `height`
|
||||
|
||||
**Pitfalls**:
|
||||
- `board_id` is required for ALL item operations; resolve via GET_BOARDS2 first
|
||||
- Sticky note colors use hex codes (e.g., '#FF0000') in the `fillColor` field
|
||||
- Position coordinates use the board's coordinate system (origin at center)
|
||||
- BULK create has a maximum items-per-request limit; check current schema
|
||||
- Frame items require `geometry` with both width and height
|
||||
|
||||
### 3. Browse and Manage Board Items
|
||||
|
||||
**When to use**: User wants to view, find, or organize items on a board
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MIRO_GET_BOARD_ITEMS` - List all items on a board [Required]
|
||||
2. `MIRO_GET_CONNECTORS2` - List connections between items [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `board_id`: Target board ID (required)
|
||||
- `type`: Filter by item type ('sticky_note', 'shape', 'text', 'frame', 'image', 'card')
|
||||
- `limit`: Number of items per page
|
||||
- `cursor`: Pagination cursor from previous response
|
||||
|
||||
**Pitfalls**:
|
||||
- Results are paginated; follow `cursor` until absent for complete item list
|
||||
- Item types must match Miro's predefined types exactly
|
||||
- Large boards may have thousands of items; use type filtering to narrow results
|
||||
- Connectors are separate from items; use GET_CONNECTORS2 for relationship data
|
||||
|
||||
### 4. Share and Collaborate on Boards
|
||||
|
||||
**When to use**: User wants to share a board with team members or manage access
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MIRO_GET_BOARDS2` - Find the board to share [Prerequisite]
|
||||
2. `MIRO_SHARE_BOARD` - Share the board with users [Required]
|
||||
3. `MIRO_GET_BOARD_MEMBERS` - Verify current board members [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `board_id`: Board to share (required)
|
||||
- `emails`: Array of email addresses to invite
|
||||
- `role`: Access level ('viewer', 'commenter', 'editor')
|
||||
- `message`: Optional invitation message
|
||||
|
||||
**Pitfalls**:
|
||||
- Email addresses must be valid; invalid emails cause the entire request to fail
|
||||
- Role must be one of the predefined values; case-sensitive
|
||||
- Sharing with users outside the organization may require admin approval
|
||||
- GET_BOARD_MEMBERS returns all members including the owner
|
||||
|
||||
### 5. Create Visual Connections
|
||||
|
||||
**When to use**: User wants to connect items on a board with lines or arrows
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MIRO_GET_BOARD_ITEMS` - Find items to connect [Prerequisite]
|
||||
2. `MIRO_GET_CONNECTORS2` - View existing connections [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `board_id`: Target board ID
|
||||
- `startItem`: Object with `id` of the source item
|
||||
- `endItem`: Object with `id` of the target item
|
||||
- `style`: Connector style (line type, color, arrows)
|
||||
|
||||
**Pitfalls**:
|
||||
- Both start and end items must exist on the same board
|
||||
- Item IDs are required for connections; resolve via GET_BOARD_ITEMS first
|
||||
- Connector styles vary; check available options in schema
|
||||
- Self-referencing connections (same start and end) are not allowed
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Board name -> Board ID**:
|
||||
```
|
||||
1. Call MIRO_GET_BOARDS2 with query=board_name
|
||||
2. Find board by name in results
|
||||
3. Extract id field
|
||||
```
|
||||
|
||||
**Item lookup on board**:
|
||||
```
|
||||
1. Call MIRO_GET_BOARD_ITEMS with board_id and optional type filter
|
||||
2. Find item by content or position
|
||||
3. Extract item id for further operations
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Boards: Use `offset` and `limit` (offset-based)
|
||||
- Board items: Use `cursor` and `limit` (cursor-based)
|
||||
- Continue until no more results or cursor is absent
|
||||
- Default page sizes vary by endpoint
|
||||
|
||||
### Coordinate System
|
||||
|
||||
- Board origin (0,0) is at the center
|
||||
- Positive X is right, positive Y is down
|
||||
- Items positioned by their center point
|
||||
- Use `position: {x: 0, y: 0}` for center of board
|
||||
- Frames define bounded areas; items inside inherit frame position
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Board IDs**:
|
||||
- Board IDs are required for virtually all operations
|
||||
- Always resolve board names to IDs via GET_BOARDS2 first
|
||||
- Do not hardcode board IDs; they vary by account
|
||||
|
||||
**Item Creation**:
|
||||
- Each item type has different required fields
|
||||
- Sticky notes need `data.content` for text
|
||||
- Frames need `geometry.width` and `geometry.height`
|
||||
- Position defaults to (0,0) if not specified; items may overlap
|
||||
|
||||
**Rate Limits**:
|
||||
- Miro API has rate limits per token
|
||||
- Bulk operations preferred over individual item creation
|
||||
- Use MIRO_CREATE_ITEMS_IN_BULK for multiple items
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` key
|
||||
- Item types determine which fields are present in response
|
||||
- Parse defensively; optional fields may be absent
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List boards | MIRO_GET_BOARDS2 | query, sort, limit, offset |
|
||||
| Get board details | MIRO_GET_BOARD | board_id |
|
||||
| Create board | MIRO_CREATE_BOARD | name, description |
|
||||
| Add sticky note | MIRO_CREATE_STICKY_NOTE_ITEM | board_id, data, style, position |
|
||||
| Add frame | MIRO_CREATE_FRAME_ITEM2 | board_id, data, geometry, position |
|
||||
| Bulk add items | MIRO_CREATE_ITEMS_IN_BULK | board_id, items |
|
||||
| Get board items | MIRO_GET_BOARD_ITEMS | board_id, type, cursor |
|
||||
| Share board | MIRO_SHARE_BOARD | board_id, emails, role |
|
||||
| Get members | MIRO_GET_BOARD_MEMBERS | board_id |
|
||||
| Get connectors | MIRO_GET_CONNECTORS2 | board_id |
|
||||
@@ -1,224 +0,0 @@
|
||||
---
|
||||
name: mixpanel-automation
|
||||
description: "Automate Mixpanel tasks via Rube MCP (Composio): events, segmentation, funnels, cohorts, user profiles, JQL queries. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Mixpanel Automation via Rube MCP
|
||||
|
||||
Automate Mixpanel product analytics through Composio's Mixpanel toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Mixpanel connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `mixpanel`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `mixpanel`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Mixpanel authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Aggregate Event Data
|
||||
|
||||
**When to use**: User wants to count events, get totals, or track event trends over time
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MIXPANEL_GET_ALL_PROJECTS` - List projects to get project ID [Prerequisite]
|
||||
2. `MIXPANEL_AGGREGATE_EVENT_COUNTS` - Get event counts and aggregations [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `event`: Event name or array of event names to aggregate
|
||||
- `from_date` / `to_date`: Date range in 'YYYY-MM-DD' format
|
||||
- `unit`: Time granularity ('minute', 'hour', 'day', 'week', 'month')
|
||||
- `type`: Aggregation type ('general', 'unique', 'average')
|
||||
- `where`: Filter expression for event properties
|
||||
|
||||
**Pitfalls**:
|
||||
- Date format must be 'YYYY-MM-DD'; other formats cause errors
|
||||
- Event names are case-sensitive; use exact names from your Mixpanel project
|
||||
- `where` filter uses Mixpanel expression syntax (e.g., `properties["country"] == "US"`)
|
||||
- Maximum date range may be limited depending on your Mixpanel plan
|
||||
|
||||
### 2. Run Segmentation Queries
|
||||
|
||||
**When to use**: User wants to break down events by properties for detailed analysis
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MIXPANEL_QUERY_SEGMENTATION` - Run segmentation analysis [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `event`: Event name to segment
|
||||
- `from_date` / `to_date`: Date range in 'YYYY-MM-DD' format
|
||||
- `on`: Property to segment by (e.g., `properties["country"]`)
|
||||
- `unit`: Time granularity
|
||||
- `type`: Count type ('general', 'unique', 'average')
|
||||
- `where`: Filter expression
|
||||
- `limit`: Maximum number of segments to return
|
||||
|
||||
**Pitfalls**:
|
||||
- The `on` parameter uses Mixpanel property expression syntax
|
||||
- Property references must use `properties["prop_name"]` format
|
||||
- Segmentation on high-cardinality properties returns capped results; use `limit`
|
||||
- Results are grouped by the segmentation property and time unit
|
||||
|
||||
### 3. Analyze Funnels
|
||||
|
||||
**When to use**: User wants to track conversion funnels and identify drop-off points
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MIXPANEL_LIST_FUNNELS` - List saved funnels to find funnel ID [Prerequisite]
|
||||
2. `MIXPANEL_QUERY_FUNNEL` - Execute funnel analysis [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `funnel_id`: ID of the saved funnel to query
|
||||
- `from_date` / `to_date`: Date range
|
||||
- `unit`: Time granularity
|
||||
- `where`: Filter expression
|
||||
- `on`: Property to segment funnel by
|
||||
- `length`: Conversion window in days
|
||||
|
||||
**Pitfalls**:
|
||||
- `funnel_id` is required; resolve via LIST_FUNNELS first
|
||||
- Funnels must be created in Mixpanel UI first; API only queries existing funnels
|
||||
- Conversion window (`length`) defaults vary; set explicitly for accuracy
|
||||
- Large date ranges with segmentation can produce very large responses
|
||||
|
||||
### 4. Manage User Profiles
|
||||
|
||||
**When to use**: User wants to query or update user profiles in Mixpanel
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MIXPANEL_QUERY_PROFILES` - Search and filter user profiles [Required]
|
||||
2. `MIXPANEL_PROFILE_BATCH_UPDATE` - Update multiple user profiles [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `where`: Filter expression for profile properties (e.g., `properties["plan"] == "premium"`)
|
||||
- `output_properties`: Array of property names to include in results
|
||||
- `page`: Page number for pagination
|
||||
- `session_id`: Session ID for consistent pagination (from first response)
|
||||
- For batch update: array of profile updates with `$distinct_id` and property operations
|
||||
|
||||
**Pitfalls**:
|
||||
- Profile queries return paginated results; use `session_id` from first response for consistent paging
|
||||
- `where` uses Mixpanel expression syntax for profile properties
|
||||
- BATCH_UPDATE applies operations (`$set`, `$unset`, `$add`, `$append`) to profiles
|
||||
- Batch update has a maximum number of profiles per request; chunk larger updates
|
||||
- Profile property names are case-sensitive
|
||||
|
||||
### 5. Manage Cohorts
|
||||
|
||||
**When to use**: User wants to list or analyze user cohorts
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MIXPANEL_COHORTS_LIST` - List all saved cohorts [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- No required parameters; returns all accessible cohorts
|
||||
- Response includes cohort `id`, `name`, `description`, `count`
|
||||
|
||||
**Pitfalls**:
|
||||
- Cohorts are created and managed in Mixpanel UI; API provides read access
|
||||
- Cohort IDs are numeric; use exact ID from list results
|
||||
- Cohort counts may be approximate for very large cohorts
|
||||
- Cohorts can be used as filters in other queries via `where` expressions
|
||||
|
||||
### 6. Run JQL and Insight Queries
|
||||
|
||||
**When to use**: User wants to run custom JQL queries or insight analyses
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MIXPANEL_JQL_QUERY` - Execute a custom JQL (JavaScript Query Language) query [Optional]
|
||||
2. `MIXPANEL_QUERY_INSIGHT` - Run a saved insight query [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- For JQL: `script` containing the JQL JavaScript code
|
||||
- For Insight: `bookmark_id` of the saved insight
|
||||
- `project_id`: Project context for the query
|
||||
|
||||
**Pitfalls**:
|
||||
- JQL uses JavaScript-like syntax specific to Mixpanel
|
||||
- JQL queries have execution time limits; optimize for efficiency
|
||||
- Insight `bookmark_id` must reference an existing saved insight
|
||||
- JQL is a legacy feature; check Mixpanel documentation for current availability
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Project name -> Project ID**:
|
||||
```
|
||||
1. Call MIXPANEL_GET_ALL_PROJECTS
|
||||
2. Find project by name in results
|
||||
3. Extract project id
|
||||
```
|
||||
|
||||
**Funnel name -> Funnel ID**:
|
||||
```
|
||||
1. Call MIXPANEL_LIST_FUNNELS
|
||||
2. Find funnel by name
|
||||
3. Extract funnel_id
|
||||
```
|
||||
|
||||
### Mixpanel Expression Syntax
|
||||
|
||||
Used in `where` and `on` parameters:
|
||||
- Property reference: `properties["property_name"]`
|
||||
- Equality: `properties["country"] == "US"`
|
||||
- Comparison: `properties["age"] > 25`
|
||||
- Boolean: `properties["is_premium"] == true`
|
||||
- Contains: `"search_term" in properties["name"]`
|
||||
- AND/OR: `properties["country"] == "US" and properties["plan"] == "pro"`
|
||||
|
||||
### Pagination
|
||||
|
||||
- Event queries: Follow date-based pagination by adjusting date ranges
|
||||
- Profile queries: Use `page` number and `session_id` for consistent results
|
||||
- Funnel/cohort lists: Typically return complete results without pagination
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Date Formats**:
|
||||
- Always use 'YYYY-MM-DD' format
|
||||
- Date ranges are inclusive on both ends
|
||||
- Data freshness depends on Mixpanel ingestion delay (typically minutes)
|
||||
|
||||
**Expression Syntax**:
|
||||
- Property references always use `properties["name"]` format
|
||||
- String values must be quoted: `properties["status"] == "active"`
|
||||
- Numeric values are unquoted: `properties["count"] > 10`
|
||||
- Boolean values: `true` / `false` (lowercase)
|
||||
|
||||
**Rate Limits**:
|
||||
- Mixpanel API has rate limits per project
|
||||
- Large segmentation queries may time out; reduce date range or segments
|
||||
- Use batch operations where available to minimize API calls
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` key
|
||||
- Event data is typically grouped by date and segment
|
||||
- Numeric values may be returned as strings; parse explicitly
|
||||
- Empty date ranges return empty objects, not empty arrays
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List projects | MIXPANEL_GET_ALL_PROJECTS | (none) |
|
||||
| Aggregate events | MIXPANEL_AGGREGATE_EVENT_COUNTS | event, from_date, to_date, unit |
|
||||
| Segmentation | MIXPANEL_QUERY_SEGMENTATION | event, on, from_date, to_date |
|
||||
| List funnels | MIXPANEL_LIST_FUNNELS | (none) |
|
||||
| Query funnel | MIXPANEL_QUERY_FUNNEL | funnel_id, from_date, to_date |
|
||||
| Query profiles | MIXPANEL_QUERY_PROFILES | where, output_properties, page |
|
||||
| Batch update profiles | MIXPANEL_PROFILE_BATCH_UPDATE | (profile update objects) |
|
||||
| List cohorts | MIXPANEL_COHORTS_LIST | (none) |
|
||||
| JQL query | MIXPANEL_JQL_QUERY | script |
|
||||
| Query insight | MIXPANEL_QUERY_INSIGHT | bookmark_id |
|
||||
@@ -1,233 +0,0 @@
|
||||
---
|
||||
name: monday-automation
|
||||
description: "Automate Monday.com work management including boards, items, columns, groups, subitems, and updates via Rube MCP (Composio). Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Monday.com Automation via Rube MCP
|
||||
|
||||
Automate Monday.com work management workflows including board creation, item management, column value updates, group organization, subitems, and update/comment threads through Composio's Monday toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Monday.com connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `monday`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `monday`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Monday.com OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create and Manage Boards
|
||||
|
||||
**When to use**: User wants to create a new board, list existing boards, or set up workspace structure.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MONDAY_GET_WORKSPACES` - List available workspaces and resolve workspace ID [Prerequisite]
|
||||
2. `MONDAY_LIST_BOARDS` - List existing boards to check for duplicates [Optional]
|
||||
3. `MONDAY_CREATE_BOARD` - Create a new board with name, kind, and workspace [Required]
|
||||
4. `MONDAY_CREATE_COLUMN` - Add columns to the new board [Optional]
|
||||
5. `MONDAY_CREATE_GROUP` - Add groups to organize items [Optional]
|
||||
6. `MONDAY_BOARDS` - Retrieve detailed board metadata [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `board_name`: Name for the new board (required)
|
||||
- `board_kind`: "public", "private", or "share" (required)
|
||||
- `workspace_id`: Numeric workspace ID; omit for default workspace
|
||||
- `folder_id`: Folder ID; must be within `workspace_id` if both provided
|
||||
- `template_id`: ID of accessible template to clone
|
||||
|
||||
**Pitfalls**:
|
||||
- `board_kind` is required and must be one of: "public", "private", "share"
|
||||
- If both `workspace_id` and `folder_id` are provided, the folder must exist within that workspace
|
||||
- `template_id` must reference a template the authenticated user can access
|
||||
- Board IDs are large integers; always use the exact value from API responses
|
||||
|
||||
### 2. Create and Manage Items
|
||||
|
||||
**When to use**: User wants to add tasks/items to a board, list existing items, or move items between groups.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MONDAY_LIST_BOARDS` - Resolve board name to board ID [Prerequisite]
|
||||
2. `MONDAY_LIST_GROUPS` - List groups on the board to get group_id [Prerequisite]
|
||||
3. `MONDAY_LIST_COLUMNS` - Get column IDs and types for setting values [Prerequisite]
|
||||
4. `MONDAY_CREATE_ITEM` - Create a new item with name and column values [Required]
|
||||
5. `MONDAY_LIST_BOARD_ITEMS` - List all items on the board [Optional]
|
||||
6. `MONDAY_MOVE_ITEM_TO_GROUP` - Move an item to a different group [Optional]
|
||||
7. `MONDAY_ITEMS_PAGE` - Paginated item retrieval with filtering [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `board_id`: Board ID (required, integer)
|
||||
- `item_name`: Item name, max 256 characters (required)
|
||||
- `group_id`: Group ID string to place the item in (optional)
|
||||
- `column_values`: JSON object or string mapping column IDs to values
|
||||
|
||||
**Pitfalls**:
|
||||
- `column_values` must use column IDs (not titles); get them from `MONDAY_LIST_COLUMNS`
|
||||
- Column value formats vary by type: status uses `{"index": 0}` or `{"label": "Done"}`, date uses `{"date": "YYYY-MM-DD"}`, people uses `{"personsAndTeams": [{"id": 123, "kind": "person"}]}`
|
||||
- `item_name` has a 256-character maximum
|
||||
- Subitem boards are NOT supported by `MONDAY_CREATE_ITEM`; use GraphQL via `MONDAY_CREATE_OBJECT`
|
||||
|
||||
### 3. Update Item Column Values
|
||||
|
||||
**When to use**: User wants to change status, date, text, or other column values on existing items.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MONDAY_LIST_COLUMNS` or `MONDAY_COLUMNS` - Get column IDs and types [Prerequisite]
|
||||
2. `MONDAY_LIST_BOARD_ITEMS` or `MONDAY_ITEMS_PAGE` - Find the target item ID [Prerequisite]
|
||||
3. `MONDAY_CHANGE_SIMPLE_COLUMN_VALUE` - Update text, status, or dropdown with a string value [Required]
|
||||
4. `MONDAY_UPDATE_ITEM` - Update complex column types (timeline, people, date) with JSON [Required]
|
||||
|
||||
**Key parameters for MONDAY_CHANGE_SIMPLE_COLUMN_VALUE**:
|
||||
- `board_id`: Board ID (integer, required)
|
||||
- `item_id`: Item ID (integer, required)
|
||||
- `column_id`: Column ID string (required)
|
||||
- `value`: Simple string value (e.g., "Done", "Working on it")
|
||||
- `create_labels_if_missing`: true to auto-create status/dropdown labels (default true)
|
||||
|
||||
**Key parameters for MONDAY_UPDATE_ITEM**:
|
||||
- `board_id`: Board ID (integer, required)
|
||||
- `item_id`: Item ID (integer, required)
|
||||
- `column_id`: Column ID string (required)
|
||||
- `value`: JSON object matching the column type schema
|
||||
- `create_labels_if_missing`: false by default; set true for status/dropdown
|
||||
|
||||
**Pitfalls**:
|
||||
- Use `MONDAY_CHANGE_SIMPLE_COLUMN_VALUE` for simple text/status/dropdown updates (string value)
|
||||
- Use `MONDAY_UPDATE_ITEM` for complex types like timeline, people, date (JSON value)
|
||||
- Column IDs are lowercase strings with underscores (e.g., "status_1", "date_2", "text"); get them from `MONDAY_LIST_COLUMNS`
|
||||
- Status values can be set by label name ("Done") or index number ("1")
|
||||
- `create_labels_if_missing` defaults differ: true for CHANGE_SIMPLE, false for UPDATE_ITEM
|
||||
|
||||
### 4. Work with Groups and Board Structure
|
||||
|
||||
**When to use**: User wants to organize items into groups, add columns, or inspect board structure.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MONDAY_LIST_BOARDS` - Resolve board ID [Prerequisite]
|
||||
2. `MONDAY_LIST_GROUPS` - List all groups on a board [Required]
|
||||
3. `MONDAY_CREATE_GROUP` - Create a new group [Optional]
|
||||
4. `MONDAY_LIST_COLUMNS` or `MONDAY_COLUMNS` - Inspect column structure [Required]
|
||||
5. `MONDAY_CREATE_COLUMN` - Add a new column to the board [Optional]
|
||||
6. `MONDAY_MOVE_ITEM_TO_GROUP` - Reorganize items across groups [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `board_id`: Board ID (required for all group/column operations)
|
||||
- `group_name`: Name for new group (CREATE_GROUP)
|
||||
- `column_type`: Must be a valid GraphQL enum token in snake_case (e.g., "status", "text", "long_text", "numbers", "date", "dropdown", "people")
|
||||
- `title`: Column display title
|
||||
- `defaults`: JSON string for status/dropdown labels, e.g., `'{"labels": ["To Do", "In Progress", "Done"]}'`
|
||||
|
||||
**Pitfalls**:
|
||||
- `column_type` must be exact snake_case values; "person" is NOT valid, use "people"
|
||||
- Group IDs are strings (e.g., "topics", "new_group_12345"), not integers
|
||||
- `MONDAY_COLUMNS` accepts an array of `board_ids` and returns column metadata including settings
|
||||
- `MONDAY_LIST_COLUMNS` is simpler and takes a single `board_id`
|
||||
|
||||
### 5. Manage Subitems and Updates
|
||||
|
||||
**When to use**: User wants to view subitems of a task or add comments/updates to items.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `MONDAY_LIST_BOARD_ITEMS` - Find parent item IDs [Prerequisite]
|
||||
2. `MONDAY_LIST_SUBITEMS_BY_PARENT` - Retrieve subitems with column values [Required]
|
||||
3. `MONDAY_CREATE_UPDATE` - Add a comment/update to an item [Optional]
|
||||
4. `MONDAY_CREATE_OBJECT` - Create subitems via GraphQL mutation [Optional]
|
||||
|
||||
**Key parameters for MONDAY_LIST_SUBITEMS_BY_PARENT**:
|
||||
- `parent_item_ids`: Array of parent item IDs (integer array, required)
|
||||
- `include_column_values`: true to include column data (default true)
|
||||
- `include_parent_fields`: true to include parent item info (default true)
|
||||
|
||||
**Key parameters for MONDAY_CREATE_OBJECT** (GraphQL):
|
||||
- `query`: Full GraphQL mutation string
|
||||
- `variables`: Optional variables object
|
||||
|
||||
**Pitfalls**:
|
||||
- Subitems can only be queried through their parent items
|
||||
- To create subitems, use `MONDAY_CREATE_OBJECT` with a `create_subitem` GraphQL mutation
|
||||
- `MONDAY_CREATE_UPDATE` is for adding comments/updates to items (Monday's "updates" feature), not for modifying item values
|
||||
- `MONDAY_CREATE_OBJECT` is a raw GraphQL endpoint; ensure correct mutation syntax
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
Always resolve display names to IDs before operations:
|
||||
- **Board name -> board_id**: `MONDAY_LIST_BOARDS` and match by name
|
||||
- **Group name -> group_id**: `MONDAY_LIST_GROUPS` with `board_id`
|
||||
- **Column title -> column_id**: `MONDAY_LIST_COLUMNS` with `board_id`
|
||||
- **Workspace name -> workspace_id**: `MONDAY_GET_WORKSPACES` and match by name
|
||||
- **Item name -> item_id**: `MONDAY_LIST_BOARD_ITEMS` or `MONDAY_ITEMS_PAGE`
|
||||
|
||||
### Pagination
|
||||
Monday.com uses cursor-based pagination for items:
|
||||
- `MONDAY_ITEMS_PAGE` returns a `cursor` in the response for the next page
|
||||
- Pass the `cursor` to the next call; `board_id` and `query_params` are ignored when cursor is provided
|
||||
- Cursors are cached for 60 minutes
|
||||
- Maximum `limit` is 500 per page
|
||||
- `MONDAY_LIST_BOARDS` and `MONDAY_GET_WORKSPACES` use page-based pagination with `page` and `limit`
|
||||
|
||||
### Column Value Formatting
|
||||
Different column types require different value formats:
|
||||
- **Status**: `{"index": 0}` or `{"label": "Done"}` or simple string "Done"
|
||||
- **Date**: `{"date": "YYYY-MM-DD"}`
|
||||
- **People**: `{"personsAndTeams": [{"id": 123, "kind": "person"}]}`
|
||||
- **Text/Numbers**: Plain string or number
|
||||
- **Timeline**: `{"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}`
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
### ID Formats
|
||||
- Board IDs and item IDs are large integers (e.g., 1234567890)
|
||||
- Group IDs are strings (e.g., "topics", "new_group_12345")
|
||||
- Column IDs are short strings (e.g., "status_1", "date4", "text")
|
||||
- Workspace IDs are integers
|
||||
|
||||
### Rate Limits
|
||||
- Monday.com GraphQL API has complexity-based rate limits
|
||||
- Large boards with many columns increase query complexity
|
||||
- Use `limit` parameter to reduce items per request if hitting limits
|
||||
|
||||
### Parameter Quirks
|
||||
- `column_type` for CREATE_COLUMN must be exact snake_case enum values; "people" not "person"
|
||||
- `column_values` in CREATE_ITEM accepts both JSON string and object formats
|
||||
- `MONDAY_CHANGE_SIMPLE_COLUMN_VALUE` auto-creates missing labels by default; `MONDAY_UPDATE_ITEM` does not
|
||||
- `MONDAY_CREATE_OBJECT` is a raw GraphQL interface; use it for operations without dedicated tools (e.g., create_subitem, delete_item, archive_board)
|
||||
|
||||
### Response Structure
|
||||
- Board items are returned as arrays with `id`, `name`, and `state` fields
|
||||
- Column values include both raw `value` (JSON) and rendered `text` (display string)
|
||||
- Subitems are nested under parent items and cannot be queried independently
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List workspaces | `MONDAY_GET_WORKSPACES` | `kind`, `state`, `limit` |
|
||||
| Create workspace | `MONDAY_CREATE_WORKSPACE` | `name`, `kind` |
|
||||
| List boards | `MONDAY_LIST_BOARDS` | `limit`, `page`, `state` |
|
||||
| Create board | `MONDAY_CREATE_BOARD` | `board_name`, `board_kind`, `workspace_id` |
|
||||
| Get board metadata | `MONDAY_BOARDS` | `board_ids`, `board_kind` |
|
||||
| List groups | `MONDAY_LIST_GROUPS` | `board_id` |
|
||||
| Create group | `MONDAY_CREATE_GROUP` | `board_id`, `group_name` |
|
||||
| List columns | `MONDAY_LIST_COLUMNS` | `board_id` |
|
||||
| Get column metadata | `MONDAY_COLUMNS` | `board_ids`, `column_types` |
|
||||
| Create column | `MONDAY_CREATE_COLUMN` | `board_id`, `column_type`, `title` |
|
||||
| Create item | `MONDAY_CREATE_ITEM` | `board_id`, `item_name`, `column_values` |
|
||||
| List board items | `MONDAY_LIST_BOARD_ITEMS` | `board_id` |
|
||||
| Paginated items | `MONDAY_ITEMS_PAGE` | `board_id`, `limit`, `query_params` |
|
||||
| Update column (simple) | `MONDAY_CHANGE_SIMPLE_COLUMN_VALUE` | `board_id`, `item_id`, `column_id`, `value` |
|
||||
| Update column (complex) | `MONDAY_UPDATE_ITEM` | `board_id`, `item_id`, `column_id`, `value` |
|
||||
| Move item to group | `MONDAY_MOVE_ITEM_TO_GROUP` | `item_id`, `group_id` |
|
||||
| List subitems | `MONDAY_LIST_SUBITEMS_BY_PARENT` | `parent_item_ids` |
|
||||
| Add comment/update | `MONDAY_CREATE_UPDATE` | `item_id`, `body` |
|
||||
| Raw GraphQL mutation | `MONDAY_CREATE_OBJECT` | `query`, `variables` |
|
||||
@@ -1,215 +0,0 @@
|
||||
---
|
||||
name: notion-automation
|
||||
description: "Automate Notion tasks via Rube MCP (Composio): pages, databases, blocks, comments, users. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Notion Automation via Rube MCP
|
||||
|
||||
Automate Notion operations through Composio's Notion toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Notion connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `notion`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `notion`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Notion OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create and Manage Pages
|
||||
|
||||
**When to use**: User wants to create, update, or archive Notion pages
|
||||
|
||||
**Tool sequence**:
|
||||
1. `NOTION_SEARCH_NOTION_PAGE` - Find parent page or existing page [Prerequisite]
|
||||
2. `NOTION_CREATE_NOTION_PAGE` - Create a new page under a parent [Optional]
|
||||
3. `NOTION_RETRIEVE_PAGE` - Get page metadata/properties [Optional]
|
||||
4. `NOTION_UPDATE_PAGE` - Update page properties, title, icon, cover [Optional]
|
||||
5. `NOTION_ARCHIVE_NOTION_PAGE` - Soft-delete (archive) a page [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: Search text for SEARCH_NOTION_PAGE
|
||||
- `parent_id`: Parent page or database ID
|
||||
- `page_id`: Page ID for retrieval/update/archive
|
||||
- `properties`: Page property values matching parent schema
|
||||
|
||||
**Pitfalls**:
|
||||
- RETRIEVE_PAGE returns only metadata/properties, NOT body content; use FETCH_BLOCK_CONTENTS for page body
|
||||
- ARCHIVE_NOTION_PAGE is a soft-delete (sets archived=true), not permanent deletion
|
||||
- Broad searches can look incomplete unless has_more/next_cursor is fully paginated
|
||||
|
||||
### 2. Query and Manage Databases
|
||||
|
||||
**When to use**: User wants to query database rows, insert entries, or update records
|
||||
|
||||
**Tool sequence**:
|
||||
1. `NOTION_SEARCH_NOTION_PAGE` - Find the database by name [Prerequisite]
|
||||
2. `NOTION_FETCH_DATABASE` - Inspect schema and properties [Prerequisite]
|
||||
3. `NOTION_QUERY_DATABASE` / `NOTION_QUERY_DATABASE_WITH_FILTER` - Query rows [Required]
|
||||
4. `NOTION_INSERT_ROW_DATABASE` - Add new entries [Optional]
|
||||
5. `NOTION_UPDATE_ROW_DATABASE` - Update existing entries [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `database_id`: Database ID (from search or URL)
|
||||
- `filter`: Filter object matching Notion filter syntax
|
||||
- `sorts`: Array of sort objects
|
||||
- `start_cursor`: Pagination cursor from previous response
|
||||
- `properties`: Property values matching database schema for inserts/updates
|
||||
|
||||
**Pitfalls**:
|
||||
- 404 object_not_found usually means wrong database_id or the database is not shared with the integration
|
||||
- Results are paginated; ignoring has_more/next_cursor silently truncates reads
|
||||
- Schema mismatches or missing required properties cause 400 validation_error
|
||||
- Formula and read-only fields cannot be set via INSERT_ROW_DATABASE
|
||||
- Property names in filters must match schema exactly (case-sensitive)
|
||||
|
||||
### 3. Manage Blocks and Page Content
|
||||
|
||||
**When to use**: User wants to read, append, or modify content blocks in a page
|
||||
|
||||
**Tool sequence**:
|
||||
1. `NOTION_FETCH_BLOCK_CONTENTS` - Read child blocks of a page [Required]
|
||||
2. `NOTION_ADD_MULTIPLE_PAGE_CONTENT` - Append blocks to a page [Optional]
|
||||
3. `NOTION_APPEND_TEXT_BLOCKS` - Append text-only blocks [Optional]
|
||||
4. `NOTION_REPLACE_PAGE_CONTENT` - Replace all page content [Optional]
|
||||
5. `NOTION_DELETE_BLOCK` - Remove a specific block [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `block_id` / `page_id`: Target page or block ID
|
||||
- `content_blocks`: Array of block objects (NOT child_blocks)
|
||||
- `text`: Plain text content for APPEND_TEXT_BLOCKS
|
||||
|
||||
**Pitfalls**:
|
||||
- Use `content_blocks` parameter, NOT `child_blocks` -- the latter fails validation
|
||||
- ADD_MULTIPLE_PAGE_CONTENT fails on archived pages; unarchive via UPDATE_PAGE first
|
||||
- Created blocks are in response.data.results; persist block IDs for later edits
|
||||
- DELETE_BLOCK is archival (archived=true), not permanent deletion
|
||||
|
||||
### 4. Manage Database Schema
|
||||
|
||||
**When to use**: User wants to create databases or modify their structure
|
||||
|
||||
**Tool sequence**:
|
||||
1. `NOTION_FETCH_DATABASE` - Inspect current schema [Prerequisite]
|
||||
2. `NOTION_CREATE_DATABASE` - Create a new database [Optional]
|
||||
3. `NOTION_UPDATE_SCHEMA_DATABASE` - Modify database properties [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `parent_id`: Parent page ID for new databases
|
||||
- `title`: Database title
|
||||
- `properties`: Property definitions with types and options
|
||||
- `database_id`: Database ID for schema updates
|
||||
|
||||
**Pitfalls**:
|
||||
- Cannot change property types via UPDATE_SCHEMA; must create new property and migrate data
|
||||
- Formula, rollup, and relation properties have complex configuration requirements
|
||||
|
||||
### 5. Manage Users and Comments
|
||||
|
||||
**When to use**: User wants to list workspace users or manage comments on pages
|
||||
|
||||
**Tool sequence**:
|
||||
1. `NOTION_LIST_USERS` - List all workspace users [Optional]
|
||||
2. `NOTION_GET_ABOUT_ME` - Get current authenticated user [Optional]
|
||||
3. `NOTION_CREATE_COMMENT` - Add a comment to a page [Optional]
|
||||
4. `NOTION_FETCH_COMMENTS` - List comments on a page [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `page_id`: Page ID for comments (also called `discussion_id`)
|
||||
- `rich_text`: Comment content as rich text array
|
||||
|
||||
**Pitfalls**:
|
||||
- Comments are linked to pages, not individual blocks
|
||||
- User IDs from LIST_USERS are needed for people-type property filters
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Page/Database name -> ID**:
|
||||
```
|
||||
1. Call NOTION_SEARCH_NOTION_PAGE with query=name
|
||||
2. Paginate with has_more/next_cursor until found
|
||||
3. Extract id from matching result
|
||||
```
|
||||
|
||||
**Database schema inspection**:
|
||||
```
|
||||
1. Call NOTION_FETCH_DATABASE with database_id
|
||||
2. Extract properties object for field names and types
|
||||
3. Use exact property names in queries and inserts
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Set `page_size` for results per page (max 100)
|
||||
- Check response for `has_more` boolean
|
||||
- Pass `start_cursor` or `next_cursor` in next request
|
||||
- Continue until `has_more` is false
|
||||
|
||||
### Notion Filter Syntax
|
||||
|
||||
**Single filter**:
|
||||
```json
|
||||
{"property": "Status", "select": {"equals": "Done"}}
|
||||
```
|
||||
|
||||
**Compound filter**:
|
||||
```json
|
||||
{"and": [
|
||||
{"property": "Status", "select": {"equals": "In Progress"}},
|
||||
{"property": "Assignee", "people": {"contains": "user-id"}}
|
||||
]}
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Integration Sharing**:
|
||||
- Pages and databases must be shared with the Notion integration to be accessible
|
||||
- Title queries can return 0 when the item is not shared with the integration
|
||||
|
||||
**Property Types**:
|
||||
- Property names are case-sensitive and must match schema exactly
|
||||
- Formula, rollup, and created_time fields are read-only
|
||||
- Select/multi-select values must match existing options unless creating new ones
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data_preview` or `data.results`
|
||||
- Parse defensively with fallbacks for different nesting levels
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Search pages/databases | NOTION_SEARCH_NOTION_PAGE | query |
|
||||
| Create page | NOTION_CREATE_NOTION_PAGE | parent_id, properties |
|
||||
| Get page metadata | NOTION_RETRIEVE_PAGE | page_id |
|
||||
| Update page | NOTION_UPDATE_PAGE | page_id, properties |
|
||||
| Archive page | NOTION_ARCHIVE_NOTION_PAGE | page_id |
|
||||
| Duplicate page | NOTION_DUPLICATE_PAGE | page_id |
|
||||
| Get page blocks | NOTION_FETCH_BLOCK_CONTENTS | block_id |
|
||||
| Append blocks | NOTION_ADD_MULTIPLE_PAGE_CONTENT | page_id, content_blocks |
|
||||
| Append text | NOTION_APPEND_TEXT_BLOCKS | page_id, text |
|
||||
| Replace content | NOTION_REPLACE_PAGE_CONTENT | page_id, content_blocks |
|
||||
| Delete block | NOTION_DELETE_BLOCK | block_id |
|
||||
| Query database | NOTION_QUERY_DATABASE | database_id, filter, sorts |
|
||||
| Query with filter | NOTION_QUERY_DATABASE_WITH_FILTER | database_id, filter |
|
||||
| Insert row | NOTION_INSERT_ROW_DATABASE | database_id, properties |
|
||||
| Update row | NOTION_UPDATE_ROW_DATABASE | page_id, properties |
|
||||
| Get database schema | NOTION_FETCH_DATABASE | database_id |
|
||||
| Create database | NOTION_CREATE_DATABASE | parent_id, title, properties |
|
||||
| Update schema | NOTION_UPDATE_SCHEMA_DATABASE | database_id, properties |
|
||||
| List users | NOTION_LIST_USERS | (none) |
|
||||
| Create comment | NOTION_CREATE_COMMENT | page_id, rich_text |
|
||||
| List comments | NOTION_FETCH_COMMENTS | page_id |
|
||||
@@ -1,238 +0,0 @@
|
||||
---
|
||||
name: one-drive-automation
|
||||
description: "Automate OneDrive file management, search, uploads, downloads, sharing, permissions, and folder operations via Rube MCP (Composio). Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# OneDrive Automation via Rube MCP
|
||||
|
||||
Automate OneDrive operations including file upload/download, search, folder management, sharing links, permissions management, and drive browsing through Composio's OneDrive toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active OneDrive connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `one_drive`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `one_drive`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Microsoft OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Search and Browse Files
|
||||
|
||||
**When to use**: User wants to find files or browse folder contents in OneDrive
|
||||
|
||||
**Tool sequence**:
|
||||
1. `ONE_DRIVE_GET_DRIVE` - Verify drive access and get drive details [Prerequisite]
|
||||
2. `ONE_DRIVE_SEARCH_ITEMS` - Keyword search across filenames, metadata, and content [Required]
|
||||
3. `ONE_DRIVE_ONEDRIVE_LIST_ITEMS` - List all items in the root of a drive [Optional]
|
||||
4. `ONE_DRIVE_GET_ITEM` - Get detailed metadata for a specific item, expand children [Optional]
|
||||
5. `ONE_DRIVE_ONEDRIVE_FIND_FILE` - Find a specific file by exact name in a folder [Optional]
|
||||
6. `ONE_DRIVE_ONEDRIVE_FIND_FOLDER` - Find a specific folder by name [Optional]
|
||||
7. `ONE_DRIVE_LIST_DRIVES` - List all accessible drives [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `q`: Search query (plain keywords only, NOT KQL syntax)
|
||||
- `search_scope`: `"root"` (folder hierarchy) or `"drive"` (includes shared items)
|
||||
- `top`: Max items per page (default 200)
|
||||
- `skip_token`: Pagination token from `@odata.nextLink`
|
||||
- `select`: Comma-separated fields to return (e.g., `"id,name,webUrl,size"`)
|
||||
- `orderby`: Sort order (e.g., `"name asc"`, `"name desc"`)
|
||||
- `item_id`: Item ID for `GET_ITEM`
|
||||
- `expand_relations`: Array like `["children"]` or `["thumbnails"]` for `GET_ITEM`
|
||||
- `user_id`: `"me"` (default) or specific user ID/email
|
||||
|
||||
**Pitfalls**:
|
||||
- `ONE_DRIVE_SEARCH_ITEMS` does NOT support KQL operators (`folder:`, `file:`, `filetype:`, `path:`); these are treated as literal text
|
||||
- Wildcard characters (`*`, `?`) are NOT supported and are auto-removed; use file extension keywords instead (e.g., `"pdf"` not `"*.pdf"`)
|
||||
- `ONE_DRIVE_ONEDRIVE_LIST_ITEMS` returns only root-level contents; use recursive `ONE_DRIVE_GET_ITEM` with `expand_relations: ["children"]` for deeper levels
|
||||
- Large folders paginate; always follow `skip_token` / `@odata.nextLink` until exhausted
|
||||
- Some drive ID formats may return "ObjectHandle is Invalid" errors due to Microsoft Graph API limitations
|
||||
|
||||
### 2. Upload and Download Files
|
||||
|
||||
**When to use**: User wants to upload files to OneDrive or download files from it
|
||||
|
||||
**Tool sequence**:
|
||||
1. `ONE_DRIVE_ONEDRIVE_FIND_FOLDER` - Locate the target folder [Prerequisite]
|
||||
2. `ONE_DRIVE_ONEDRIVE_UPLOAD_FILE` - Upload a file to a specified folder [Required for upload]
|
||||
3. `ONE_DRIVE_DOWNLOAD_FILE` - Download a file by item ID [Required for download]
|
||||
4. `ONE_DRIVE_GET_ITEM` - Get file details before download [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `file`: FileUploadable object with `s3key`, `mimetype`, and `name` for uploads
|
||||
- `folder`: Destination path (e.g., `"/Documents/Reports"`) or folder ID for uploads
|
||||
- `item_id`: File's unique identifier for downloads
|
||||
- `file_name`: Desired filename with extension for downloads
|
||||
- `drive_id`: Specific drive ID (for SharePoint or OneDrive for Business)
|
||||
- `user_id`: `"me"` (default) or specific user identifier
|
||||
|
||||
**Pitfalls**:
|
||||
- Upload automatically renames on conflict (no overwrite option by default)
|
||||
- Large files are automatically handled via chunking
|
||||
- `drive_id` overrides `user_id` when both are provided
|
||||
- Item IDs vary by platform: OneDrive for Business uses `01...` prefix, OneDrive Personal uses `HASH!NUMBER` format
|
||||
- Item IDs are case-sensitive; use exactly as returned from API
|
||||
|
||||
### 3. Share Files and Manage Permissions
|
||||
|
||||
**When to use**: User wants to share files/folders or manage who has access
|
||||
|
||||
**Tool sequence**:
|
||||
1. `ONE_DRIVE_ONEDRIVE_FIND_FILE` or `ONE_DRIVE_ONEDRIVE_FIND_FOLDER` - Locate the item [Prerequisite]
|
||||
2. `ONE_DRIVE_GET_ITEM_PERMISSIONS` - Check current permissions [Prerequisite]
|
||||
3. `ONE_DRIVE_INVITE_USER_TO_DRIVE_ITEM` - Grant access to specific users [Required]
|
||||
4. `ONE_DRIVE_CREATE_LINK` - Create a shareable link [Optional]
|
||||
5. `ONE_DRIVE_UPDATE_DRIVE_ITEM_METADATA` - Update item metadata [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `item_id`: The file or folder to share
|
||||
- `recipients`: Array of objects with `email` or `object_id`
|
||||
- `roles`: Array with `"read"` or `"write"`
|
||||
- `send_invitation`: `true` to send notification email, `false` for silent permission grant
|
||||
- `require_sign_in`: `true` to require authentication to access
|
||||
- `message`: Custom message for invitation (max 2000 characters)
|
||||
- `expiration_date_time`: ISO 8601 date for permission expiry
|
||||
- `retain_inherited_permissions`: `true` (default) to keep existing inherited permissions
|
||||
|
||||
**Pitfalls**:
|
||||
- Using wrong `item_id` with `INVITE_USER_TO_DRIVE_ITEM` changes permissions on unintended items; always verify first
|
||||
- Write or higher roles are impactful; get explicit user confirmation before granting
|
||||
- `GET_ITEM_PERMISSIONS` returns inherited and owner entries; do not assume response only reflects recent changes
|
||||
- `permissions` cannot be expanded via `ONE_DRIVE_GET_ITEM`; use the separate permissions endpoint
|
||||
- At least one of `require_sign_in` or `send_invitation` must be `true`
|
||||
|
||||
### 4. Manage Folders (Create, Move, Delete, Copy)
|
||||
|
||||
**When to use**: User wants to create, move, rename, delete, or copy files and folders
|
||||
|
||||
**Tool sequence**:
|
||||
1. `ONE_DRIVE_ONEDRIVE_FIND_FOLDER` - Locate source and destination folders [Prerequisite]
|
||||
2. `ONE_DRIVE_ONEDRIVE_CREATE_FOLDER` - Create a new folder [Required for create]
|
||||
3. `ONE_DRIVE_MOVE_ITEM` - Move a file or folder to a new location [Required for move]
|
||||
4. `ONE_DRIVE_COPY_ITEM` - Copy a file or folder (async operation) [Required for copy]
|
||||
5. `ONE_DRIVE_DELETE_ITEM` - Move item to recycle bin [Required for delete]
|
||||
6. `ONE_DRIVE_UPDATE_DRIVE_ITEM_METADATA` - Rename or update item properties [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Folder name for creation or new name for rename/copy
|
||||
- `parent_folder`: Path (e.g., `"/Documents/Reports"`) or folder ID for creation
|
||||
- `itemId`: Item to move
|
||||
- `parentReference`: Object with `id` (destination folder ID) for moves: `{"id": "folder_id"}`
|
||||
- `item_id`: Item to copy or delete
|
||||
- `parent_reference`: Object with `id` and optional `driveId` for copy destination
|
||||
- `@microsoft.graph.conflictBehavior`: `"fail"`, `"replace"`, or `"rename"` for copies
|
||||
- `if_match`: ETag for optimistic concurrency on deletes
|
||||
|
||||
**Pitfalls**:
|
||||
- `ONE_DRIVE_MOVE_ITEM` does NOT support cross-drive moves; use `ONE_DRIVE_COPY_ITEM` for cross-drive transfers
|
||||
- `parentReference` for moves requires folder ID (not folder name); resolve with `ONEDRIVE_FIND_FOLDER` first
|
||||
- `ONE_DRIVE_COPY_ITEM` is asynchronous; response provides a URL to monitor progress
|
||||
- `ONE_DRIVE_DELETE_ITEM` moves to recycle bin, not permanent deletion
|
||||
- Folder creation auto-renames on conflict (e.g., "New Folder" becomes "New Folder 1")
|
||||
- Provide either `name` or `parent_reference` (or both) for `ONE_DRIVE_COPY_ITEM`
|
||||
|
||||
### 5. Track Changes and Drive Information
|
||||
|
||||
**When to use**: User wants to monitor changes or get drive/quota information
|
||||
|
||||
**Tool sequence**:
|
||||
1. `ONE_DRIVE_GET_DRIVE` - Get drive properties and metadata [Required]
|
||||
2. `ONE_DRIVE_GET_QUOTA` - Check storage quota (total, used, remaining) [Optional]
|
||||
3. `ONE_DRIVE_LIST_SITE_DRIVE_ITEMS_DELTA` - Track changes in SharePoint site drives [Optional]
|
||||
4. `ONE_DRIVE_GET_ITEM_VERSIONS` - Get version history of a file [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `drive_id`: Drive identifier (or `"me"` for personal drive)
|
||||
- `site_id`: SharePoint site identifier for delta tracking
|
||||
- `token`: Delta token (`"latest"` for current state, URL for next page, or timestamp)
|
||||
- `item_id`: File ID for version history
|
||||
|
||||
**Pitfalls**:
|
||||
- Delta queries are only available for SharePoint site drives via `ONE_DRIVE_LIST_SITE_DRIVE_ITEMS_DELTA`
|
||||
- Token `"latest"` returns current delta token without items (useful as starting point)
|
||||
- Deep or large drives can take several minutes to crawl; use batching and resume logic
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
- **User**: Use `"me"` for authenticated user or specific user email/GUID
|
||||
- **Item ID from find**: Use `ONE_DRIVE_ONEDRIVE_FIND_FILE` or `ONE_DRIVE_ONEDRIVE_FIND_FOLDER` to get item IDs
|
||||
- **Item ID from search**: Extract from `ONE_DRIVE_SEARCH_ITEMS` results
|
||||
- **Drive ID**: Use `ONE_DRIVE_LIST_DRIVES` or `ONE_DRIVE_GET_DRIVE` to discover drives
|
||||
- **Folder path to ID**: Use `ONE_DRIVE_ONEDRIVE_FIND_FOLDER` with path, then extract ID from response
|
||||
|
||||
ID formats vary by platform:
|
||||
- OneDrive for Business/SharePoint: `01NKDM7HMOJTVYMDOSXFDK2QJDXCDI3WUK`
|
||||
- OneDrive Personal: `D4648F06C91D9D3D!54927`
|
||||
|
||||
### Pagination
|
||||
OneDrive uses token-based pagination:
|
||||
- Follow `@odata.nextLink` or `skip_token` until no more pages
|
||||
- Set `top` for page size (varies by endpoint)
|
||||
- `ONE_DRIVE_ONEDRIVE_LIST_ITEMS` auto-handles pagination internally
|
||||
- Aggressive parallel requests can trigger HTTP 429; honor `Retry-After` headers
|
||||
|
||||
### Path vs ID
|
||||
Most OneDrive tools accept either paths or IDs:
|
||||
- **Paths**: Start with `/` (e.g., `"/Documents/Reports"`)
|
||||
- **IDs**: Use unique item identifiers from API responses
|
||||
- **Item paths for permissions**: Use `:/path/to/item:/` format
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
### ID Formats
|
||||
- Item IDs are case-sensitive and platform-specific
|
||||
- Never use web URLs, sharing links, or manually constructed identifiers as item IDs
|
||||
- Always use IDs exactly as returned from Microsoft Graph API
|
||||
|
||||
### Rate Limits
|
||||
- Aggressive parallel `ONE_DRIVE_GET_ITEM` calls can trigger HTTP 429 Too Many Requests
|
||||
- Honor `Retry-After` headers and implement throttling
|
||||
- Deep drive crawls should use batching with delays
|
||||
|
||||
### Search Limitations
|
||||
- No KQL support; use plain keywords only
|
||||
- No wildcard characters; use extension keywords (e.g., `"pdf"` not `"*.pdf"`)
|
||||
- No path-based filtering in search; use folder listing instead
|
||||
- `q='*'` wildcard-only queries return HTTP 400 invalidRequest
|
||||
|
||||
### Parameter Quirks
|
||||
- `drive_id` overrides `user_id` when both are provided
|
||||
- `permissions` cannot be expanded via `GET_ITEM`; use dedicated permissions endpoint
|
||||
- Move operations require folder IDs in `parentReference`, not folder names
|
||||
- Copy operations are asynchronous; response provides monitoring URL
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Search files | `ONE_DRIVE_SEARCH_ITEMS` | `q`, `search_scope`, `top` |
|
||||
| List root items | `ONE_DRIVE_ONEDRIVE_LIST_ITEMS` | `user_id`, `select`, `top` |
|
||||
| Get item details | `ONE_DRIVE_GET_ITEM` | `item_id`, `expand_relations` |
|
||||
| Find file by name | `ONE_DRIVE_ONEDRIVE_FIND_FILE` | `name`, `folder` |
|
||||
| Find folder by name | `ONE_DRIVE_ONEDRIVE_FIND_FOLDER` | `name`, `folder` |
|
||||
| Upload file | `ONE_DRIVE_ONEDRIVE_UPLOAD_FILE` | `file`, `folder` |
|
||||
| Download file | `ONE_DRIVE_DOWNLOAD_FILE` | `item_id`, `file_name` |
|
||||
| Create folder | `ONE_DRIVE_ONEDRIVE_CREATE_FOLDER` | `name`, `parent_folder` |
|
||||
| Move item | `ONE_DRIVE_MOVE_ITEM` | `itemId`, `parentReference` |
|
||||
| Copy item | `ONE_DRIVE_COPY_ITEM` | `item_id`, `parent_reference`, `name` |
|
||||
| Delete item | `ONE_DRIVE_DELETE_ITEM` | `item_id` |
|
||||
| Share with users | `ONE_DRIVE_INVITE_USER_TO_DRIVE_ITEM` | `item_id`, `recipients`, `roles` |
|
||||
| Create share link | `ONE_DRIVE_CREATE_LINK` | `item_id`, link type |
|
||||
| Get permissions | `ONE_DRIVE_GET_ITEM_PERMISSIONS` | `item_id` |
|
||||
| Update metadata | `ONE_DRIVE_UPDATE_DRIVE_ITEM_METADATA` | `item_id`, fields |
|
||||
| Get drive info | `ONE_DRIVE_GET_DRIVE` | `drive_id` |
|
||||
| List drives | `ONE_DRIVE_LIST_DRIVES` | user/group/site scope |
|
||||
| Get quota | `ONE_DRIVE_GET_QUOTA` | (none) |
|
||||
| Track changes | `ONE_DRIVE_LIST_SITE_DRIVE_ITEMS_DELTA` | `site_id`, `token` |
|
||||
| Version history | `ONE_DRIVE_GET_ITEM_VERSIONS` | `item_id` |
|
||||
@@ -1,75 +0,0 @@
|
||||
---
|
||||
name: oss-hunter
|
||||
description: Automatically hunt for high-impact OSS contribution opportunities in trending repositories.
|
||||
risk: safe
|
||||
source: https://github.com/jackjin1997/ClawForge
|
||||
metadata: {"openclaw":{"emoji":"🎯","category":"developer"}}
|
||||
---
|
||||
|
||||
# OSS Hunter 🎯
|
||||
|
||||
A precision skill for agents to find, analyze, and strategize for high-impact Open Source contributions. This skill helps you become a top-tier contributor by identifying the most "mergeable" and influential issues in trending repositories.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Use when the user asks to find open source issues to work on.
|
||||
- Use when searching for "help wanted" or "good first issue" tasks in specific domains like AI or Web3.
|
||||
- Use to generate a "Contribution Dossier" with ready-to-execute strategies for trending projects.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Ask your agent:
|
||||
- "Find me some help-wanted issues in trending AI repositories."
|
||||
- "Hunt for bug fixes in langchain-ai/langchain that are suitable for a quick PR."
|
||||
- "Generate a contribution dossier for the most recent trending projects on GitHub."
|
||||
|
||||
## Workflow
|
||||
|
||||
When hunting for contributions, the agent follows this multi-stage protocol:
|
||||
|
||||
### Phase 1: Repository Discovery
|
||||
Use `web_search` or `gh api` to find trending repositories.
|
||||
Focus on:
|
||||
- Stars > 1000
|
||||
- Recent activity (pushed within 24 hours)
|
||||
- Relevant topics (AI, Agentic, Web3, Tooling)
|
||||
|
||||
### Phase 2: Issue Extraction
|
||||
Search for specific labels:
|
||||
- `help-wanted`
|
||||
- `good-first-issue`
|
||||
- `bug`
|
||||
- `v1` / `roadmap`
|
||||
|
||||
```bash
|
||||
gh issue list --repo owner/repo --label "help wanted" --limit 10
|
||||
```
|
||||
|
||||
### Phase 3: Feasibility Analysis
|
||||
Analyze the issue:
|
||||
1. **Reproducibility**: Is there a code snippet to reproduce the bug?
|
||||
2. **Impact**: How many users does this affect?
|
||||
3. **Mergeability**: Check recent PR history. Does the maintainer merge community PRs quickly?
|
||||
4. **Complexity**: Can this be solved by an agent with the current tools?
|
||||
|
||||
### Phase 4: The Dossier
|
||||
Generate a structured report for the human:
|
||||
- **Project Name & Stars**
|
||||
- **Issue Link & Description**
|
||||
- **Root Cause Analysis** (based on code inspection)
|
||||
- **Proposed Fix Strategy**
|
||||
- **Confidence Score** (1-10)
|
||||
|
||||
## Limitations
|
||||
|
||||
- Accuracy depends on the availability of `gh` CLI or `web_search` tools.
|
||||
- Analysis is limited by context window when reading very large repositories.
|
||||
- Cannot guarantee PR acceptance (maintainer discretion).
|
||||
|
||||
---
|
||||
|
||||
## Contributing to the Matrix
|
||||
|
||||
Build a better hunter by adding new heuristics to Phase 3. Submit your improvements to the [ClawForge](https://github.com/jackjin1997/ClawForge).
|
||||
|
||||
*Powered by OpenClaw & ClawForge.*
|
||||
@@ -1,56 +0,0 @@
|
||||
import os
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
|
||||
def run_gh_command(args):
|
||||
try:
|
||||
result = subprocess.run(['gh'] + args, capture_output=True, text=True, check=True)
|
||||
return result.stdout
|
||||
except subprocess.CalledProcessError as e:
|
||||
print(f"Error running gh command: {e.stderr}", file=sys.stderr)
|
||||
return None
|
||||
|
||||
def hunt():
|
||||
print("🎯 Hunting for high-impact OSS issues...")
|
||||
|
||||
# 1. Find trending repos (stars > 1000 created/updated recently)
|
||||
repos_json = run_gh_command(['api', 'search/repositories?q=stars:>1000+pushed:>2026-02-01&sort=stars&order=desc', '--jq', '.items[] | {full_name: .full_name, stars: .stargazers_count, description: .description}'])
|
||||
|
||||
if not repos_json:
|
||||
print("No trending repositories found.")
|
||||
return
|
||||
|
||||
repos = [json.loads(line) for line in repos_json.strip().split('\n')[:10]]
|
||||
|
||||
dossier = []
|
||||
|
||||
for repo in repos:
|
||||
name = repo['full_name']
|
||||
print(f"Checking {name}...")
|
||||
|
||||
# 2. Search for help-wanted issues
|
||||
issues_json = run_gh_command(['issue', 'list', '--repo', name, '--label', 'help wanted', '--json', 'number,title,url', '--limit', '3'])
|
||||
|
||||
if issues_json:
|
||||
try:
|
||||
issues = json.loads(issues_json)
|
||||
for issue in issues:
|
||||
dossier.append({
|
||||
'repo': name,
|
||||
'stars': repo['stars'],
|
||||
'number': issue['number'],
|
||||
'title': issue['title'],
|
||||
'url': issue['url']
|
||||
})
|
||||
except json.JSONDecodeError:
|
||||
pass
|
||||
|
||||
print("\n--- 📂 OSS CONTRIBUTION DOSSIER ---")
|
||||
for item in dossier:
|
||||
print(f"\n[{item['repo']} ★{item['stars']}]")
|
||||
print(f"Issue #{item['number']}: {item['title']}")
|
||||
print(f"Link: {item['url']}")
|
||||
|
||||
if __name__ == "__main__":
|
||||
hunt()
|
||||
@@ -1,191 +0,0 @@
|
||||
---
|
||||
name: outlook-automation
|
||||
description: "Automate Outlook tasks via Rube MCP (Composio): emails, calendar, contacts, folders, attachments. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Outlook Automation via Rube MCP
|
||||
|
||||
Automate Microsoft Outlook operations through Composio's Outlook toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Outlook connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `outlook`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `outlook`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Microsoft OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Search and Filter Emails
|
||||
|
||||
**When to use**: User wants to find specific emails across their mailbox
|
||||
|
||||
**Tool sequence**:
|
||||
1. `OUTLOOK_SEARCH_MESSAGES` - Search with KQL syntax across all folders [Required]
|
||||
2. `OUTLOOK_GET_MESSAGE` - Get full message details [Optional]
|
||||
3. `OUTLOOK_LIST_OUTLOOK_ATTACHMENTS` - List message attachments [Optional]
|
||||
4. `OUTLOOK_DOWNLOAD_OUTLOOK_ATTACHMENT` - Download attachment [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: KQL search string (from:, to:, subject:, received:, hasattachment:)
|
||||
- `from_index`: Pagination start (0-based)
|
||||
- `size`: Results per page (max 25)
|
||||
- `message_id`: Message ID (use hitId from search results)
|
||||
|
||||
**Pitfalls**:
|
||||
- Only works with Microsoft 365/Enterprise accounts (not @hotmail.com/@outlook.com)
|
||||
- Pagination relies on hitsContainers[0].moreResultsAvailable; stop only when false
|
||||
- Use hitId from search results as message_id for downstream calls, not resource.id
|
||||
- Index latency: very recent emails may not appear immediately
|
||||
- Inline images appear as attachments; filter by mimetype for real documents
|
||||
|
||||
### 2. Query Emails in a Folder
|
||||
|
||||
**When to use**: User wants to list emails in a specific folder with OData filters
|
||||
|
||||
**Tool sequence**:
|
||||
1. `OUTLOOK_LIST_MAIL_FOLDERS` - List mail folders to get folder IDs [Prerequisite]
|
||||
2. `OUTLOOK_QUERY_EMAILS` - Query emails with structured filters [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `folder`: Folder name ('inbox', 'sentitems', 'drafts') or folder ID
|
||||
- `filter`: OData filter (e.g., `isRead eq false and importance eq 'high'`)
|
||||
- `top`: Max results (1-1000)
|
||||
- `orderby`: Sort field and direction
|
||||
- `select`: Array of fields to return
|
||||
|
||||
**Pitfalls**:
|
||||
- QUERY_EMAILS searches a SINGLE folder only; use SEARCH_MESSAGES for cross-folder search
|
||||
- Custom folders require folder IDs, not display names; use LIST_MAIL_FOLDERS
|
||||
- Always check response['@odata.nextLink'] for pagination
|
||||
- Cannot filter by recipient or body content; use SEARCH_MESSAGES for that
|
||||
|
||||
### 3. Manage Calendar Events
|
||||
|
||||
**When to use**: User wants to list, search, or inspect calendar events
|
||||
|
||||
**Tool sequence**:
|
||||
1. `OUTLOOK_LIST_EVENTS` - List events with filters [Optional]
|
||||
2. `OUTLOOK_GET_CALENDAR_VIEW` - Get events in a time window [Optional]
|
||||
3. `OUTLOOK_GET_EVENT` - Get specific event details [Optional]
|
||||
4. `OUTLOOK_LIST_CALENDARS` - List available calendars [Optional]
|
||||
5. `OUTLOOK_GET_SCHEDULE` - Get free/busy info [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `filter`: OData filter (use start/dateTime, NOT receivedDateTime)
|
||||
- `start_datetime`/`end_datetime`: ISO 8601 for calendar view
|
||||
- `timezone`: IANA timezone (e.g., 'America/New_York')
|
||||
- `calendar_id`: Optional non-primary calendar ID
|
||||
- `select`: Fields to return
|
||||
|
||||
**Pitfalls**:
|
||||
- Use calendar event properties only (start/dateTime, end/dateTime), NOT email properties (receivedDateTime)
|
||||
- Calendar view requires start_datetime and end_datetime
|
||||
- Recurring events need `expand_recurring_events=true` to see individual occurrences
|
||||
- Decline status is per-attendee via attendees[].status.response
|
||||
|
||||
### 4. Manage Contacts
|
||||
|
||||
**When to use**: User wants to list, create, or organize contacts
|
||||
|
||||
**Tool sequence**:
|
||||
1. `OUTLOOK_LIST_CONTACTS` - List contacts [Optional]
|
||||
2. `OUTLOOK_CREATE_CONTACT` - Create a new contact [Optional]
|
||||
3. `OUTLOOK_GET_CONTACT_FOLDERS` - List contact folders [Optional]
|
||||
4. `OUTLOOK_CREATE_CONTACT_FOLDER` - Create contact folder [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `givenName`/`surname`: Contact name
|
||||
- `emailAddresses`: Array of email objects
|
||||
- `displayName`: Full display name
|
||||
- `contact_folder_id`: Optional folder for contacts
|
||||
|
||||
**Pitfalls**:
|
||||
- Contact creation supports many fields but only givenName or surname is needed
|
||||
|
||||
### 5. Manage Mail Folders
|
||||
|
||||
**When to use**: User wants to organize mail folders
|
||||
|
||||
**Tool sequence**:
|
||||
1. `OUTLOOK_LIST_MAIL_FOLDERS` - List top-level folders [Required]
|
||||
2. `OUTLOOK_LIST_CHILD_MAIL_FOLDERS` - List subfolders [Optional]
|
||||
3. `OUTLOOK_CREATE_MAIL_FOLDER` - Create a new folder [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `parent_folder_id`: Well-known name or folder ID
|
||||
- `displayName`: New folder name
|
||||
- `include_hidden_folders`: Show hidden folders
|
||||
|
||||
**Pitfalls**:
|
||||
- Well-known folder names: 'inbox', 'sentitems', 'drafts', 'deleteditems', 'junkemail', 'archive'
|
||||
- Custom folder operations require the folder ID, not display name
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### KQL Search Syntax
|
||||
|
||||
**Property filters**:
|
||||
- `from:user@example.com` - From sender
|
||||
- `to:recipient@example.com` - To recipient
|
||||
- `subject:invoice` - Subject contains
|
||||
- `received>=2025-01-01` - Date filter
|
||||
- `hasattachment:yes` - Has attachments
|
||||
|
||||
**Combinators**:
|
||||
- `AND` - Both conditions
|
||||
- `OR` - Either condition
|
||||
- Parentheses for grouping
|
||||
|
||||
### OData Filter Syntax
|
||||
|
||||
**Email filters**:
|
||||
- `isRead eq false` - Unread emails
|
||||
- `importance eq 'high'` - High importance
|
||||
- `hasAttachments eq true` - Has attachments
|
||||
- `receivedDateTime ge 2025-01-01T00:00:00Z` - Date filter
|
||||
|
||||
**Calendar filters**:
|
||||
- `start/dateTime ge '2025-01-01T00:00:00Z'` - Events after date
|
||||
- `contains(subject, 'Meeting')` - Subject contains text
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Account Types**:
|
||||
- SEARCH_MESSAGES requires Microsoft 365/Enterprise accounts
|
||||
- Personal accounts (@hotmail.com, @outlook.com) have limited API access
|
||||
|
||||
**Field Confusion**:
|
||||
- Email properties (receivedDateTime) differ from calendar properties (start/dateTime)
|
||||
- Do NOT use email fields in calendar queries or vice versa
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Search emails | OUTLOOK_SEARCH_MESSAGES | query, from_index, size |
|
||||
| Query folder | OUTLOOK_QUERY_EMAILS | folder, filter, top |
|
||||
| Get message | OUTLOOK_GET_MESSAGE | message_id |
|
||||
| List attachments | OUTLOOK_LIST_OUTLOOK_ATTACHMENTS | message_id |
|
||||
| Download attachment | OUTLOOK_DOWNLOAD_OUTLOOK_ATTACHMENT | message_id, attachment_id |
|
||||
| List folders | OUTLOOK_LIST_MAIL_FOLDERS | (none) |
|
||||
| Child folders | OUTLOOK_LIST_CHILD_MAIL_FOLDERS | parent_folder_id |
|
||||
| List events | OUTLOOK_LIST_EVENTS | filter, timezone |
|
||||
| Calendar view | OUTLOOK_GET_CALENDAR_VIEW | start_datetime, end_datetime |
|
||||
| Get event | OUTLOOK_GET_EVENT | event_id |
|
||||
| List calendars | OUTLOOK_LIST_CALENDARS | (none) |
|
||||
| Free/busy | OUTLOOK_GET_SCHEDULE | schedules, times |
|
||||
| List contacts | OUTLOOK_LIST_CONTACTS | top, filter |
|
||||
| Create contact | OUTLOOK_CREATE_CONTACT | givenName, emailAddresses |
|
||||
| Contact folders | OUTLOOK_GET_CONTACT_FOLDERS | (none) |
|
||||
@@ -1,236 +0,0 @@
|
||||
---
|
||||
name: outlook-calendar-automation
|
||||
description: "Automate Outlook Calendar tasks via Rube MCP (Composio): create events, manage attendees, find meeting times, and handle invitations. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Outlook Calendar Automation via Rube MCP
|
||||
|
||||
Automate Outlook Calendar operations through Composio's Outlook toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Outlook connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `outlook`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `outlook`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Microsoft OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create Calendar Events
|
||||
|
||||
**When to use**: User wants to schedule a new event on their Outlook calendar
|
||||
|
||||
**Tool sequence**:
|
||||
1. `OUTLOOK_LIST_CALENDARS` - List available calendars [Optional]
|
||||
2. `OUTLOOK_CALENDAR_CREATE_EVENT` - Create the event [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `subject`: Event title
|
||||
- `start_datetime`: ISO 8601 start time (e.g., '2025-01-03T10:00:00')
|
||||
- `end_datetime`: ISO 8601 end time (must be after start)
|
||||
- `time_zone`: IANA or Windows timezone (e.g., 'America/New_York', 'Pacific Standard Time')
|
||||
- `attendees_info`: Array of email strings or attendee objects
|
||||
- `body`: Event description (plain text or HTML)
|
||||
- `is_html`: Set true if body contains HTML
|
||||
- `location`: Physical location string
|
||||
- `is_online_meeting`: Set true for Teams meeting link
|
||||
- `online_meeting_provider`: 'teamsForBusiness' for Teams integration
|
||||
- `show_as`: 'free', 'tentative', 'busy', 'oof'
|
||||
|
||||
**Pitfalls**:
|
||||
- start_datetime must be chronologically before end_datetime
|
||||
- time_zone is required and must be a valid IANA or Windows timezone name
|
||||
- Adding attendees can trigger invitation emails immediately
|
||||
- To generate a Teams meeting link, set BOTH is_online_meeting=true AND online_meeting_provider='teamsForBusiness'
|
||||
- user_id defaults to 'me'; use email or UUID for other users' calendars
|
||||
|
||||
### 2. List and Search Events
|
||||
|
||||
**When to use**: User wants to find events on their calendar
|
||||
|
||||
**Tool sequence**:
|
||||
1. `OUTLOOK_GET_MAILBOX_SETTINGS` - Get user timezone for accurate queries [Prerequisite]
|
||||
2. `OUTLOOK_LIST_EVENTS` - Search events with filters [Required]
|
||||
3. `OUTLOOK_GET_EVENT` - Get full details for a specific event [Optional]
|
||||
4. `OUTLOOK_GET_CALENDAR_VIEW` - Get events active during a time window [Alternative]
|
||||
|
||||
**Key parameters**:
|
||||
- `filter`: OData filter string (e.g., "start/dateTime ge '2024-07-01T00:00:00Z'")
|
||||
- `select`: Array of properties to return
|
||||
- `orderby`: Sort criteria (e.g., ['start/dateTime desc'])
|
||||
- `top`: Results per page (1-999)
|
||||
- `timezone`: Display timezone for results
|
||||
- `start_datetime`/`end_datetime`: For CALENDAR_VIEW time window (UTC with Z suffix)
|
||||
|
||||
**Pitfalls**:
|
||||
- OData filter datetime values require single quotes and Z suffix
|
||||
- Use 'start/dateTime' for event start filtering, NOT 'receivedDateTime' (that is for emails)
|
||||
- 'createdDateTime' supports orderby/select but NOT filtering
|
||||
- Pagination: follow @odata.nextLink until all pages are collected
|
||||
- CALENDAR_VIEW is better for "what's on my calendar today" queries (includes spanning events)
|
||||
- LIST_EVENTS is better for keyword/category filtering
|
||||
- Response events have start/end nested as start.dateTime and end.dateTime
|
||||
|
||||
### 3. Update Events
|
||||
|
||||
**When to use**: User wants to modify an existing calendar event
|
||||
|
||||
**Tool sequence**:
|
||||
1. `OUTLOOK_LIST_EVENTS` - Find the event to update [Prerequisite]
|
||||
2. `OUTLOOK_UPDATE_CALENDAR_EVENT` - Update the event [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `event_id`: Unique event identifier (from LIST_EVENTS)
|
||||
- `subject`: New event title (optional)
|
||||
- `start_datetime`/`end_datetime`: New times (optional)
|
||||
- `time_zone`: Timezone for new times
|
||||
- `attendees`: Updated attendee list (replaces existing if provided)
|
||||
- `body`: Updated description with contentType and content
|
||||
- `location`: Updated location
|
||||
|
||||
**Pitfalls**:
|
||||
- UPDATE merges provided fields with existing event; unspecified fields are preserved
|
||||
- Providing attendees replaces the ENTIRE attendee list; include all desired attendees
|
||||
- Providing categories replaces the ENTIRE category list
|
||||
- Updating times may trigger re-sends to attendees
|
||||
- event_id is required; obtain from LIST_EVENTS first
|
||||
|
||||
### 4. Delete Events and Decline Invitations
|
||||
|
||||
**When to use**: User wants to remove an event or decline a meeting invitation
|
||||
|
||||
**Tool sequence**:
|
||||
1. `OUTLOOK_DELETE_EVENT` - Delete an event [Optional]
|
||||
2. `OUTLOOK_DECLINE_EVENT` - Decline a meeting invitation [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `event_id`: Event to delete or decline
|
||||
- `send_notifications`: Send cancellation notices to attendees (default true)
|
||||
- `comment`: Reason for declining (for DECLINE_EVENT)
|
||||
- `proposedNewTime`: Suggest alternative time when declining
|
||||
|
||||
**Pitfalls**:
|
||||
- Deletion with send_notifications=true sends cancellation emails
|
||||
- Declining supports proposing a new time with start/end in ISO 8601 format
|
||||
- Deleting a recurring event master deletes all occurrences
|
||||
- sendResponse in DECLINE_EVENT controls whether the organizer is notified
|
||||
|
||||
### 5. Find Available Meeting Times
|
||||
|
||||
**When to use**: User wants to find optimal meeting slots across multiple people
|
||||
|
||||
**Tool sequence**:
|
||||
1. `OUTLOOK_FIND_MEETING_TIMES` - Get meeting time suggestions [Required]
|
||||
2. `OUTLOOK_GET_SCHEDULE` - Check free/busy for specific people [Alternative]
|
||||
|
||||
**Key parameters**:
|
||||
- `attendees`: Array of attendee objects with email and type
|
||||
- `meetingDuration`: ISO 8601 duration (e.g., 'PT1H' for 1 hour, 'PT30M' for 30 min)
|
||||
- `timeConstraint`: Time slots to search within
|
||||
- `minimumAttendeePercentage`: Minimum confidence threshold (0-100)
|
||||
- `Schedules`: Email array for GET_SCHEDULE
|
||||
- `StartTime`/`EndTime`: Time window for schedule lookup (max 62 days)
|
||||
|
||||
**Pitfalls**:
|
||||
- FIND_MEETING_TIMES searches within work hours by default; use activityDomain='unrestricted' for 24/7
|
||||
- Time constraint time slots require dateTime and timeZone for both start and end
|
||||
- GET_SCHEDULE period cannot exceed 62 days
|
||||
- Meeting suggestions respect attendee availability but may return suboptimal times for complex groups
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Event ID Resolution
|
||||
|
||||
```
|
||||
1. Call OUTLOOK_LIST_EVENTS with time-bound filter
|
||||
2. Find target event by subject or other criteria
|
||||
3. Extract event id (e.g., 'AAMkAGI2TAAA=')
|
||||
4. Use in UPDATE, DELETE, or GET_EVENT calls
|
||||
```
|
||||
|
||||
### OData Filter Syntax for Calendar
|
||||
|
||||
**Time range filter**:
|
||||
```
|
||||
filter: "start/dateTime ge '2024-07-01T00:00:00Z' and start/dateTime le '2024-07-31T23:59:59Z'"
|
||||
```
|
||||
|
||||
**Subject contains**:
|
||||
```
|
||||
filter: "contains(subject, 'Project Review')"
|
||||
```
|
||||
|
||||
**Combined**:
|
||||
```
|
||||
filter: "contains(subject, 'Review') and categories/any(c:c eq 'Work')"
|
||||
```
|
||||
|
||||
### Timezone Handling
|
||||
|
||||
- Get user timezone: `OUTLOOK_GET_MAILBOX_SETTINGS` with select=['timeZone']
|
||||
- Use consistent timezone in filter datetime values
|
||||
- Calendar View requires UTC timestamps with Z suffix
|
||||
- LIST_EVENTS filter accepts timezone in datetime values
|
||||
|
||||
### Online Meeting Creation
|
||||
|
||||
```
|
||||
1. Set is_online_meeting: true
|
||||
2. Set online_meeting_provider: 'teamsForBusiness'
|
||||
3. Create event with OUTLOOK_CALENDAR_CREATE_EVENT
|
||||
4. Teams join link available in response onlineMeeting field
|
||||
5. Or retrieve via OUTLOOK_GET_EVENT for the full join URL
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**DateTime Formats**:
|
||||
- ISO 8601 format required: '2025-01-03T10:00:00'
|
||||
- Calendar View requires UTC with Z: '2025-01-03T10:00:00Z'
|
||||
- Filter values need single quotes: "'2025-01-03T00:00:00Z'"
|
||||
- Timezone mismatches shift event boundaries; always resolve user timezone first
|
||||
|
||||
**OData Filter Errors**:
|
||||
- 400 Bad Request usually indicates filter syntax issues
|
||||
- Not all event properties support filtering (createdDateTime does not)
|
||||
- Retry with adjusted syntax/bounds on 400 errors
|
||||
- Valid filter fields: start/dateTime, end/dateTime, subject, categories, isAllDay
|
||||
|
||||
**Attendee Management**:
|
||||
- Adding attendees triggers invitation emails
|
||||
- Updating attendees replaces the full list; include all desired attendees
|
||||
- Attendee types: 'required', 'optional', 'resource'
|
||||
- Calendar delegation affects which calendars are accessible
|
||||
|
||||
**Response Structure**:
|
||||
- Events nested at response.data.value
|
||||
- Event times at event.start.dateTime and event.end.dateTime
|
||||
- Calendar View may nest at data.results[i].response.data.value
|
||||
- Parse defensively with fallbacks for different nesting levels
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Create event | OUTLOOK_CALENDAR_CREATE_EVENT | subject, start_datetime, end_datetime, time_zone |
|
||||
| List events | OUTLOOK_LIST_EVENTS | filter, select, top, timezone |
|
||||
| Get event details | OUTLOOK_GET_EVENT | event_id |
|
||||
| Calendar view | OUTLOOK_GET_CALENDAR_VIEW | start_datetime, end_datetime |
|
||||
| Update event | OUTLOOK_UPDATE_CALENDAR_EVENT | event_id, subject, start_datetime |
|
||||
| Delete event | OUTLOOK_DELETE_EVENT | event_id, send_notifications |
|
||||
| Decline event | OUTLOOK_DECLINE_EVENT | event_id, comment |
|
||||
| Find meeting times | OUTLOOK_FIND_MEETING_TIMES | attendees, meetingDuration |
|
||||
| Get schedule | OUTLOOK_GET_SCHEDULE | Schedules, StartTime, EndTime |
|
||||
| List calendars | OUTLOOK_LIST_CALENDARS | user_id |
|
||||
| Mailbox settings | OUTLOOK_GET_MAILBOX_SETTINGS | select |
|
||||
@@ -1,245 +0,0 @@
|
||||
---
|
||||
name: pagerduty-automation
|
||||
description: "Automate PagerDuty tasks via Rube MCP (Composio): manage incidents, services, schedules, escalation policies, and on-call rotations. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# PagerDuty Automation via Rube MCP
|
||||
|
||||
Automate PagerDuty incident management and operations through Composio's PagerDuty toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active PagerDuty connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `pagerduty`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `pagerduty`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete PagerDuty authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Manage Incidents
|
||||
|
||||
**When to use**: User wants to create, update, acknowledge, or resolve incidents
|
||||
|
||||
**Tool sequence**:
|
||||
1. `PAGERDUTY_FETCH_INCIDENT_LIST` - List incidents with filters [Required]
|
||||
2. `PAGERDUTY_RETRIEVE_INCIDENT_BY_INCIDENT_ID` - Get specific incident details [Optional]
|
||||
3. `PAGERDUTY_CREATE_INCIDENT_RECORD` - Create a new incident [Optional]
|
||||
4. `PAGERDUTY_UPDATE_INCIDENT_BY_ID` - Update incident status or assignment [Optional]
|
||||
5. `PAGERDUTY_POST_INCIDENT_NOTE_USING_ID` - Add a note to an incident [Optional]
|
||||
6. `PAGERDUTY_SNOOZE_INCIDENT_BY_DURATION` - Snooze an incident for a period [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `statuses[]`: Filter by status ('triggered', 'acknowledged', 'resolved')
|
||||
- `service_ids[]`: Filter by service IDs
|
||||
- `urgencies[]`: Filter by urgency ('high', 'low')
|
||||
- `title`: Incident title (for creation)
|
||||
- `service`: Service object with `id` and `type` (for creation)
|
||||
- `status`: New status for update operations
|
||||
|
||||
**Pitfalls**:
|
||||
- Incident creation requires a `service` object with both `id` and `type: 'service_reference'`
|
||||
- Status transitions follow: triggered -> acknowledged -> resolved
|
||||
- Cannot transition from resolved back to triggered directly
|
||||
- `PAGERDUTY_UPDATE_INCIDENT_BY_ID` requires the incident ID as a path parameter
|
||||
- Snooze duration is in seconds; the incident re-triggers after the snooze period
|
||||
|
||||
### 2. Inspect Incident Alerts and Analytics
|
||||
|
||||
**When to use**: User wants to review alerts within an incident or analyze incident metrics
|
||||
|
||||
**Tool sequence**:
|
||||
1. `PAGERDUTY_GET_ALERTS_BY_INCIDENT_ID` - List alerts for an incident [Required]
|
||||
2. `PAGERDUTY_GET_INCIDENT_ALERT_DETAILS` - Get details of a specific alert [Optional]
|
||||
3. `PAGERDUTY_FETCH_INCIDENT_ANALYTICS_BY_ID` - Get incident analytics/metrics [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `incident_id`: The incident ID
|
||||
- `alert_id`: Specific alert ID within the incident
|
||||
- `statuses[]`: Filter alerts by status
|
||||
|
||||
**Pitfalls**:
|
||||
- An incident can have multiple alerts; each alert has its own status
|
||||
- Alert IDs are scoped to the incident
|
||||
- Analytics data includes response times, engagement metrics, and resolution times
|
||||
|
||||
### 3. Manage Services
|
||||
|
||||
**When to use**: User wants to create, update, or list services
|
||||
|
||||
**Tool sequence**:
|
||||
1. `PAGERDUTY_RETRIEVE_LIST_OF_SERVICES` - List all services [Required]
|
||||
2. `PAGERDUTY_RETRIEVE_SERVICE_BY_ID` - Get service details [Optional]
|
||||
3. `PAGERDUTY_CREATE_NEW_SERVICE` - Create a new technical service [Optional]
|
||||
4. `PAGERDUTY_UPDATE_SERVICE_BY_ID` - Update service configuration [Optional]
|
||||
5. `PAGERDUTY_CREATE_INTEGRATION_FOR_SERVICE` - Add an integration to a service [Optional]
|
||||
6. `PAGERDUTY_CREATE_BUSINESS_SERVICE` - Create a business service [Optional]
|
||||
7. `PAGERDUTY_UPDATE_BUSINESS_SERVICE_BY_ID` - Update a business service [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Service name
|
||||
- `escalation_policy`: Escalation policy object with `id` and `type`
|
||||
- `alert_creation`: Alert creation mode ('create_alerts_and_incidents' or 'create_incidents')
|
||||
- `status`: Service status ('active', 'warning', 'critical', 'maintenance', 'disabled')
|
||||
|
||||
**Pitfalls**:
|
||||
- Creating a service requires an existing escalation policy
|
||||
- Business services are different from technical services; they represent business-level groupings
|
||||
- Service integrations define how alerts are created (email, API, events)
|
||||
- Disabling a service stops all incident creation for that service
|
||||
|
||||
### 4. Manage Schedules and On-Call
|
||||
|
||||
**When to use**: User wants to view or manage on-call schedules and rotations
|
||||
|
||||
**Tool sequence**:
|
||||
1. `PAGERDUTY_GET_SCHEDULES` - List all schedules [Required]
|
||||
2. `PAGERDUTY_RETRIEVE_SCHEDULE_BY_ID` - Get specific schedule details [Optional]
|
||||
3. `PAGERDUTY_CREATE_NEW_SCHEDULE_LAYER` - Create a new schedule [Optional]
|
||||
4. `PAGERDUTY_UPDATE_SCHEDULE_BY_ID` - Update an existing schedule [Optional]
|
||||
5. `PAGERDUTY_RETRIEVE_ONCALL_LIST` - View who is currently on-call [Optional]
|
||||
6. `PAGERDUTY_CREATE_SCHEDULE_OVERRIDES_CONFIGURATION` - Create temporary overrides [Optional]
|
||||
7. `PAGERDUTY_DELETE_SCHEDULE_OVERRIDE_BY_ID` - Remove an override [Optional]
|
||||
8. `PAGERDUTY_RETRIEVE_USERS_BY_SCHEDULE_ID` - List users in a schedule [Optional]
|
||||
9. `PAGERDUTY_PREVIEW_SCHEDULE_OBJECT` - Preview schedule changes before saving [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `schedule_id`: Schedule identifier
|
||||
- `time_zone`: Schedule timezone (e.g., 'America/New_York')
|
||||
- `schedule_layers`: Array of rotation layer configurations
|
||||
- `since`/`until`: Date range for on-call queries (ISO 8601)
|
||||
- `override`: Override object with user, start, and end times
|
||||
|
||||
**Pitfalls**:
|
||||
- Schedule layers define rotation order; multiple layers can overlap
|
||||
- Overrides are temporary and take precedence over the normal schedule
|
||||
- `since` and `until` are required for on-call queries to scope the time range
|
||||
- Time zones must be valid IANA timezone strings
|
||||
- Preview before saving complex schedule changes to verify correctness
|
||||
|
||||
### 5. Manage Escalation Policies
|
||||
|
||||
**When to use**: User wants to create or modify escalation policies
|
||||
|
||||
**Tool sequence**:
|
||||
1. `PAGERDUTY_FETCH_ESCALATION_POLICES_LIST` - List all escalation policies [Required]
|
||||
2. `PAGERDUTY_GET_ESCALATION_POLICY_BY_ID` - Get policy details [Optional]
|
||||
3. `PAGERDUTY_CREATE_ESCALATION_POLICY` - Create a new policy [Optional]
|
||||
4. `PAGERDUTY_UPDATE_ESCALATION_POLICY_BY_ID` - Update an existing policy [Optional]
|
||||
5. `PAGERDUTY_AUDIT_ESCALATION_POLICY_RECORDS` - View audit trail for a policy [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Policy name
|
||||
- `escalation_rules`: Array of escalation rule objects
|
||||
- `num_loops`: Number of times to loop through rules before stopping (0 = no loop)
|
||||
- `escalation_delay_in_minutes`: Delay between escalation levels
|
||||
|
||||
**Pitfalls**:
|
||||
- Each escalation rule requires at least one target (user, schedule, or team)
|
||||
- `escalation_delay_in_minutes` defines how long before escalating to the next level
|
||||
- Setting `num_loops` to 0 means the policy runs once and stops
|
||||
- Deleting a policy fails if services still reference it
|
||||
|
||||
### 6. Manage Teams
|
||||
|
||||
**When to use**: User wants to create or manage PagerDuty teams
|
||||
|
||||
**Tool sequence**:
|
||||
1. `PAGERDUTY_CREATE_NEW_TEAM_WITH_DETAILS` - Create a new team [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Team name
|
||||
- `description`: Team description
|
||||
|
||||
**Pitfalls**:
|
||||
- Team names must be unique within the account
|
||||
- Teams are used to scope services, escalation policies, and schedules
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Service name -> Service ID**:
|
||||
```
|
||||
1. Call PAGERDUTY_RETRIEVE_LIST_OF_SERVICES
|
||||
2. Find service by name in response
|
||||
3. Extract id field
|
||||
```
|
||||
|
||||
**Schedule name -> Schedule ID**:
|
||||
```
|
||||
1. Call PAGERDUTY_GET_SCHEDULES
|
||||
2. Find schedule by name in response
|
||||
3. Extract id field
|
||||
```
|
||||
|
||||
### Incident Lifecycle
|
||||
|
||||
```
|
||||
1. Incident triggered (via API, integration, or manual creation)
|
||||
2. On-call user notified per escalation policy
|
||||
3. User acknowledges -> status: 'acknowledged'
|
||||
4. User resolves -> status: 'resolved'
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- PagerDuty uses offset-based pagination
|
||||
- Check response for `more` boolean field
|
||||
- Use `offset` and `limit` parameters
|
||||
- Continue until `more` is false
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**ID Formats**:
|
||||
- All PagerDuty IDs are alphanumeric strings (e.g., 'P1234AB')
|
||||
- Service references require `type: 'service_reference'`
|
||||
- User references require `type: 'user_reference'`
|
||||
|
||||
**Status Transitions**:
|
||||
- Incidents: triggered -> acknowledged -> resolved (forward only)
|
||||
- Services: active, warning, critical, maintenance, disabled
|
||||
|
||||
**Rate Limits**:
|
||||
- PagerDuty API enforces rate limits per account
|
||||
- Implement exponential backoff on 429 responses
|
||||
- Bulk operations should be spaced out
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` or `data.data`
|
||||
- Parse defensively with fallback patterns
|
||||
- Pagination uses `offset`/`limit`/`more` pattern
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List incidents | PAGERDUTY_FETCH_INCIDENT_LIST | statuses[], service_ids[] |
|
||||
| Get incident | PAGERDUTY_RETRIEVE_INCIDENT_BY_INCIDENT_ID | incident_id |
|
||||
| Create incident | PAGERDUTY_CREATE_INCIDENT_RECORD | title, service |
|
||||
| Update incident | PAGERDUTY_UPDATE_INCIDENT_BY_ID | incident_id, status |
|
||||
| Add incident note | PAGERDUTY_POST_INCIDENT_NOTE_USING_ID | incident_id, content |
|
||||
| Snooze incident | PAGERDUTY_SNOOZE_INCIDENT_BY_DURATION | incident_id, duration |
|
||||
| Get incident alerts | PAGERDUTY_GET_ALERTS_BY_INCIDENT_ID | incident_id |
|
||||
| Incident analytics | PAGERDUTY_FETCH_INCIDENT_ANALYTICS_BY_ID | incident_id |
|
||||
| List services | PAGERDUTY_RETRIEVE_LIST_OF_SERVICES | (none) |
|
||||
| Get service | PAGERDUTY_RETRIEVE_SERVICE_BY_ID | service_id |
|
||||
| Create service | PAGERDUTY_CREATE_NEW_SERVICE | name, escalation_policy |
|
||||
| Update service | PAGERDUTY_UPDATE_SERVICE_BY_ID | service_id |
|
||||
| List schedules | PAGERDUTY_GET_SCHEDULES | (none) |
|
||||
| Get schedule | PAGERDUTY_RETRIEVE_SCHEDULE_BY_ID | schedule_id |
|
||||
| Get on-call | PAGERDUTY_RETRIEVE_ONCALL_LIST | since, until |
|
||||
| Create schedule override | PAGERDUTY_CREATE_SCHEDULE_OVERRIDES_CONFIGURATION | schedule_id |
|
||||
| List escalation policies | PAGERDUTY_FETCH_ESCALATION_POLICES_LIST | (none) |
|
||||
| Create escalation policy | PAGERDUTY_CREATE_ESCALATION_POLICY | name, escalation_rules |
|
||||
| Create team | PAGERDUTY_CREATE_NEW_TEAM_WITH_DETAILS | name, description |
|
||||
@@ -1,224 +0,0 @@
|
||||
---
|
||||
name: pipedrive-automation
|
||||
description: "Automate Pipedrive CRM operations including deals, contacts, organizations, activities, notes, and pipeline management via Rube MCP (Composio). Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Pipedrive Automation via Rube MCP
|
||||
|
||||
Automate Pipedrive CRM workflows including deal management, contact and organization operations, activity scheduling, notes, and pipeline/stage queries through Composio's Pipedrive toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Pipedrive connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `pipedrive`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `pipedrive`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Pipedrive OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create and Manage Deals
|
||||
|
||||
**When to use**: User wants to create a new deal, update an existing deal, or review deal details in the sales pipeline.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `PIPEDRIVE_SEARCH_ORGANIZATIONS` - Find existing org to link to the deal [Optional]
|
||||
2. `PIPEDRIVE_ADD_AN_ORGANIZATION` - Create organization if none found [Optional]
|
||||
3. `PIPEDRIVE_SEARCH_PERSONS` - Find existing contact to link [Optional]
|
||||
4. `PIPEDRIVE_ADD_A_PERSON` - Create contact if none found [Optional]
|
||||
5. `PIPEDRIVE_GET_ALL_PIPELINES` - Resolve pipeline ID [Prerequisite]
|
||||
6. `PIPEDRIVE_GET_ALL_STAGES` - Resolve stage ID within the pipeline [Prerequisite]
|
||||
7. `PIPEDRIVE_ADD_A_DEAL` - Create the deal with title, value, org_id, person_id, stage_id [Required]
|
||||
8. `PIPEDRIVE_UPDATE_A_DEAL` - Modify deal properties after creation [Optional]
|
||||
9. `PIPEDRIVE_ADD_A_PRODUCT_TO_A_DEAL` - Attach line items/products [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `title`: Deal title (required for creation)
|
||||
- `value`: Monetary value of the deal
|
||||
- `currency`: 3-letter ISO currency code (e.g., "USD")
|
||||
- `pipeline_id` / `stage_id`: Numeric IDs for pipeline placement
|
||||
- `org_id` / `person_id`: Link to organization and contact
|
||||
- `status`: "open", "won", or "lost"
|
||||
- `expected_close_date`: Format YYYY-MM-DD
|
||||
|
||||
**Pitfalls**:
|
||||
- `title` is the only required field for `PIPEDRIVE_ADD_A_DEAL`; all others are optional
|
||||
- Custom fields appear as long hash keys in responses; use dealFields endpoint to map them
|
||||
- `PIPEDRIVE_UPDATE_A_DEAL` requires the numeric `id` of the deal
|
||||
- Setting `status` to "lost" requires also providing `lost_reason`
|
||||
|
||||
### 2. Manage Contacts (Persons and Organizations)
|
||||
|
||||
**When to use**: User wants to create, update, search, or list contacts and companies in Pipedrive.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `PIPEDRIVE_SEARCH_PERSONS` - Search for existing person by name, email, or phone [Prerequisite]
|
||||
2. `PIPEDRIVE_ADD_A_PERSON` - Create new contact if not found [Required]
|
||||
3. `PIPEDRIVE_UPDATE_A_PERSON` - Modify existing contact details [Optional]
|
||||
4. `PIPEDRIVE_GET_DETAILS_OF_A_PERSON` - Retrieve full contact record [Optional]
|
||||
5. `PIPEDRIVE_SEARCH_ORGANIZATIONS` - Search for existing organization [Prerequisite]
|
||||
6. `PIPEDRIVE_ADD_AN_ORGANIZATION` - Create new organization if not found [Required]
|
||||
7. `PIPEDRIVE_UPDATE_AN_ORGANIZATION` - Modify organization properties [Optional]
|
||||
8. `PIPEDRIVE_GET_DETAILS_OF_AN_ORGANIZATION` - Retrieve full org record [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Required for both person and organization creation
|
||||
- `email`: Array of objects with `value`, `label`, `primary` fields for persons
|
||||
- `phone`: Array of objects with `value`, `label`, `primary` fields for persons
|
||||
- `org_id`: Link a person to an organization
|
||||
- `visible_to`: 1 = owner only, 3 = entire company
|
||||
- `term`: Search term for SEARCH_PERSONS / SEARCH_ORGANIZATIONS (minimum 2 characters)
|
||||
|
||||
**Pitfalls**:
|
||||
- `PIPEDRIVE_ADD_AN_ORGANIZATION` may auto-merge with an existing org; check `response.additional_data.didMerge`
|
||||
- Email and phone fields are arrays of objects, not plain strings: `[{"value": "test@example.com", "label": "work", "primary": true}]`
|
||||
- `PIPEDRIVE_SEARCH_PERSONS` wildcards like `*` or `@` are NOT supported; use `PIPEDRIVE_GET_ALL_PERSONS` to list all
|
||||
- Deletion via `PIPEDRIVE_DELETE_A_PERSON` or `PIPEDRIVE_DELETE_AN_ORGANIZATION` is soft-delete with 30-day retention, then permanent
|
||||
|
||||
### 3. Schedule and Track Activities
|
||||
|
||||
**When to use**: User wants to create calls, meetings, tasks, or other activities linked to deals, contacts, or organizations.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `PIPEDRIVE_SEARCH_PERSONS` or `PIPEDRIVE_GET_DETAILS_OF_A_DEAL` - Resolve linked entity IDs [Prerequisite]
|
||||
2. `PIPEDRIVE_ADD_AN_ACTIVITY` - Create the activity with subject, type, due date [Required]
|
||||
3. `PIPEDRIVE_UPDATE_AN_ACTIVITY` - Modify activity details or mark as done [Optional]
|
||||
4. `PIPEDRIVE_GET_DETAILS_OF_AN_ACTIVITY` - Retrieve activity record [Optional]
|
||||
5. `PIPEDRIVE_GET_ALL_ACTIVITIES_ASSIGNED_TO_A_PARTICULAR_USER` - List user's activities [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `subject`: Activity title (required)
|
||||
- `type`: Activity type key string, e.g., "call", "meeting", "task", "email" (required)
|
||||
- `due_date`: Format YYYY-MM-DD
|
||||
- `due_time`: Format HH:MM
|
||||
- `duration`: Format HH:MM (e.g., "00:30" for 30 minutes)
|
||||
- `deal_id` / `person_id` / `org_id`: Link to related entities
|
||||
- `done`: 0 = not done, 1 = done
|
||||
|
||||
**Pitfalls**:
|
||||
- Both `subject` and `type` are required for `PIPEDRIVE_ADD_AN_ACTIVITY`
|
||||
- `type` must match an existing ActivityTypes key_string in the account
|
||||
- `done` is an integer (0 or 1), not a boolean
|
||||
- Response includes `more_activities_scheduled_in_context` in additional_data
|
||||
|
||||
### 4. Add and Manage Notes
|
||||
|
||||
**When to use**: User wants to attach notes to deals, persons, organizations, leads, or projects.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `PIPEDRIVE_SEARCH_PERSONS` or `PIPEDRIVE_GET_DETAILS_OF_A_DEAL` - Resolve entity ID [Prerequisite]
|
||||
2. `PIPEDRIVE_ADD_A_NOTE` - Create note with HTML content linked to an entity [Required]
|
||||
3. `PIPEDRIVE_UPDATE_A_NOTE` - Modify note content [Optional]
|
||||
4. `PIPEDRIVE_GET_ALL_NOTES` - List notes filtered by entity [Optional]
|
||||
5. `PIPEDRIVE_GET_ALL_COMMENTS_FOR_A_NOTE` - Retrieve comments on a note [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `content`: Note body in HTML format (required)
|
||||
- `deal_id` / `person_id` / `org_id` / `lead_id` / `project_id`: At least one entity link required
|
||||
- `pinned_to_deal_flag` / `pinned_to_person_flag`: Filter pinned notes when listing
|
||||
|
||||
**Pitfalls**:
|
||||
- `content` is required and supports HTML; plain text works but is sanitized server-side
|
||||
- At least one of `deal_id`, `person_id`, `org_id`, `lead_id`, or `project_id` must be provided
|
||||
- `PIPEDRIVE_GET_ALL_NOTES` returns notes across all entities by default; filter with entity ID params
|
||||
|
||||
### 5. Query Pipelines and Stages
|
||||
|
||||
**When to use**: User wants to view sales pipelines, stages, or deals within a pipeline/stage.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `PIPEDRIVE_GET_ALL_PIPELINES` - List all pipelines and their IDs [Required]
|
||||
2. `PIPEDRIVE_GET_ONE_PIPELINE` - Get details and deal summary for a specific pipeline [Optional]
|
||||
3. `PIPEDRIVE_GET_ALL_STAGES` - List all stages, optionally filtered by pipeline [Required]
|
||||
4. `PIPEDRIVE_GET_ONE_STAGE` - Get details for a specific stage [Optional]
|
||||
5. `PIPEDRIVE_GET_DEALS_IN_A_PIPELINE` - List all deals across stages in a pipeline [Optional]
|
||||
6. `PIPEDRIVE_GET_DEALS_IN_A_STAGE` - List deals in a specific stage [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `id`: Pipeline or stage ID (required for single-item endpoints)
|
||||
- `pipeline_id`: Filter stages by pipeline
|
||||
- `totals_convert_currency`: 3-letter currency code or "default_currency" for converted totals
|
||||
- `get_summary`: Set to 1 for deal summary in pipeline responses
|
||||
|
||||
**Pitfalls**:
|
||||
- `PIPEDRIVE_GET_ALL_PIPELINES` takes no parameters; returns all pipelines
|
||||
- `PIPEDRIVE_GET_ALL_STAGES` returns stages for ALL pipelines unless `pipeline_id` is specified
|
||||
- Deal counts in pipeline summaries use `per_stages_converted` only when `totals_convert_currency` is set
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
Always resolve display names to numeric IDs before operations:
|
||||
- **Organization name -> org_id**: `PIPEDRIVE_SEARCH_ORGANIZATIONS` with `term` param
|
||||
- **Person name -> person_id**: `PIPEDRIVE_SEARCH_PERSONS` with `term` param
|
||||
- **Pipeline name -> pipeline_id**: `PIPEDRIVE_GET_ALL_PIPELINES` then match by name
|
||||
- **Stage name -> stage_id**: `PIPEDRIVE_GET_ALL_STAGES` with `pipeline_id` then match by name
|
||||
|
||||
### Pagination
|
||||
Most list endpoints use offset-based pagination:
|
||||
- Use `start` (offset) and `limit` (page size) parameters
|
||||
- Check `additional_data.pagination.more_items_in_collection` to know if more pages exist
|
||||
- Use `additional_data.pagination.next_start` as the `start` value for the next page
|
||||
- Default limit is ~500 for some endpoints; set explicitly for predictable paging
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
### ID Formats
|
||||
- All entity IDs (deal, person, org, activity, pipeline, stage) are numeric integers
|
||||
- Lead IDs are UUID strings, not integers
|
||||
- Custom field keys are long alphanumeric hashes (e.g., "a1b2c3d4e5f6...")
|
||||
|
||||
### Rate Limits
|
||||
- Pipedrive enforces per-company API rate limits; bulk operations should be paced
|
||||
- `PIPEDRIVE_GET_ALL_PERSONS` and `PIPEDRIVE_GET_ALL_ORGANIZATIONS` can return large datasets; always paginate
|
||||
|
||||
### Parameter Quirks
|
||||
- Email and phone on persons are arrays of objects, not plain strings
|
||||
- `visible_to` is numeric: 1 = owner only, 3 = entire company, 5 = specific groups
|
||||
- `done` on activities is integer 0/1, not boolean true/false
|
||||
- Organization creation may auto-merge duplicates silently; check `didMerge` in response
|
||||
- `PIPEDRIVE_SEARCH_PERSONS` requires minimum 2 characters and does not support wildcards
|
||||
|
||||
### Response Structure
|
||||
- Custom fields appear as hash keys in responses; map them via the respective Fields endpoints
|
||||
- Responses often nest data under `response.data.data` in wrapped executions
|
||||
- Search results are under `response.data.items`, not top-level
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Create deal | `PIPEDRIVE_ADD_A_DEAL` | `title`, `value`, `org_id`, `stage_id` |
|
||||
| Update deal | `PIPEDRIVE_UPDATE_A_DEAL` | `id`, `status`, `value`, `stage_id` |
|
||||
| Get deal details | `PIPEDRIVE_GET_DETAILS_OF_A_DEAL` | `id` |
|
||||
| Search persons | `PIPEDRIVE_SEARCH_PERSONS` | `term`, `fields` |
|
||||
| Add person | `PIPEDRIVE_ADD_A_PERSON` | `name`, `email`, `phone`, `org_id` |
|
||||
| Update person | `PIPEDRIVE_UPDATE_A_PERSON` | `id`, `name`, `email` |
|
||||
| Get person details | `PIPEDRIVE_GET_DETAILS_OF_A_PERSON` | `id` |
|
||||
| List all persons | `PIPEDRIVE_GET_ALL_PERSONS` | `start`, `limit`, `filter_id` |
|
||||
| Search organizations | `PIPEDRIVE_SEARCH_ORGANIZATIONS` | `term`, `fields` |
|
||||
| Add organization | `PIPEDRIVE_ADD_AN_ORGANIZATION` | `name`, `visible_to` |
|
||||
| Update organization | `PIPEDRIVE_UPDATE_AN_ORGANIZATION` | `id`, `name`, `address` |
|
||||
| Get org details | `PIPEDRIVE_GET_DETAILS_OF_AN_ORGANIZATION` | `id` |
|
||||
| Add activity | `PIPEDRIVE_ADD_AN_ACTIVITY` | `subject`, `type`, `due_date`, `deal_id` |
|
||||
| Update activity | `PIPEDRIVE_UPDATE_AN_ACTIVITY` | `id`, `done`, `due_date` |
|
||||
| Get activity details | `PIPEDRIVE_GET_DETAILS_OF_AN_ACTIVITY` | `id` |
|
||||
| List user activities | `PIPEDRIVE_GET_ALL_ACTIVITIES_ASSIGNED_TO_A_PARTICULAR_USER` | `user_id`, `start`, `limit` |
|
||||
| Add note | `PIPEDRIVE_ADD_A_NOTE` | `content`, `deal_id` or `person_id` |
|
||||
| List notes | `PIPEDRIVE_GET_ALL_NOTES` | `deal_id`, `person_id`, `start`, `limit` |
|
||||
| List pipelines | `PIPEDRIVE_GET_ALL_PIPELINES` | (none) |
|
||||
| Get pipeline details | `PIPEDRIVE_GET_ONE_PIPELINE` | `id` |
|
||||
| List stages | `PIPEDRIVE_GET_ALL_STAGES` | `pipeline_id` |
|
||||
| Deals in pipeline | `PIPEDRIVE_GET_DEALS_IN_A_PIPELINE` | `id`, `stage_id` |
|
||||
| Deals in stage | `PIPEDRIVE_GET_DEALS_IN_A_STAGE` | `id`, `start`, `limit` |
|
||||
| Add product to deal | `PIPEDRIVE_ADD_A_PRODUCT_TO_A_DEAL` | `id`, `product_id`, `item_price` |
|
||||
@@ -1,224 +0,0 @@
|
||||
---
|
||||
name: posthog-automation
|
||||
description: "Automate PostHog tasks via Rube MCP (Composio): events, feature flags, projects, user profiles, annotations. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# PostHog Automation via Rube MCP
|
||||
|
||||
Automate PostHog product analytics and feature flag management through Composio's PostHog toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active PostHog connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `posthog`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `posthog`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete PostHog authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Capture Events
|
||||
|
||||
**When to use**: User wants to send event data to PostHog for analytics tracking
|
||||
|
||||
**Tool sequence**:
|
||||
1. `POSTHOG_CAPTURE_EVENT` - Send one or more events to PostHog [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `event`: Event name (e.g., '$pageview', 'user_signed_up', 'purchase_completed')
|
||||
- `distinct_id`: Unique user identifier (required)
|
||||
- `properties`: Object with event-specific properties
|
||||
- `timestamp`: ISO 8601 timestamp (optional; defaults to server time)
|
||||
|
||||
**Pitfalls**:
|
||||
- `distinct_id` is required for every event; identifies the user/device
|
||||
- PostHog system events use `$` prefix (e.g., '$pageview', '$identify')
|
||||
- Custom events should NOT use the `$` prefix
|
||||
- Properties are freeform; maintain consistent schemas across events
|
||||
- Events are processed asynchronously; ingestion delay is typically seconds
|
||||
|
||||
### 2. List and Filter Events
|
||||
|
||||
**When to use**: User wants to browse or search through captured events
|
||||
|
||||
**Tool sequence**:
|
||||
1. `POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS` - Query events with filters [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `project_id`: PostHog project ID (required)
|
||||
- `event`: Filter by event name
|
||||
- `person_id`: Filter by person ID
|
||||
- `after`: Events after this ISO 8601 timestamp
|
||||
- `before`: Events before this ISO 8601 timestamp
|
||||
- `limit`: Maximum events to return
|
||||
- `offset`: Pagination offset
|
||||
|
||||
**Pitfalls**:
|
||||
- `project_id` is required; resolve via LIST_PROJECTS first
|
||||
- Date filters use ISO 8601 format (e.g., '2024-01-15T00:00:00Z')
|
||||
- Large event volumes require pagination; use `offset` and `limit`
|
||||
- Results are returned in reverse chronological order by default
|
||||
- Event properties are nested; parse carefully
|
||||
|
||||
### 3. Manage Feature Flags
|
||||
|
||||
**When to use**: User wants to create, view, or manage feature flags
|
||||
|
||||
**Tool sequence**:
|
||||
1. `POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS` - List existing feature flags [Required]
|
||||
2. `POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS` - Get detailed flag configuration [Optional]
|
||||
3. `POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT` - Create a new feature flag [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- For listing: `project_id` (required)
|
||||
- For details: `project_id`, `id` (feature flag ID)
|
||||
- For creation:
|
||||
- `project_id`: Target project
|
||||
- `key`: Flag key (e.g., 'new-dashboard-beta')
|
||||
- `name`: Human-readable name
|
||||
- `filters`: Targeting rules and rollout percentage
|
||||
- `active`: Whether the flag is enabled
|
||||
|
||||
**Pitfalls**:
|
||||
- Feature flag `key` must be unique within a project
|
||||
- Flag keys should use kebab-case (e.g., 'my-feature-flag')
|
||||
- `filters` define targeting groups with properties and rollout percentages
|
||||
- Creating a flag with `active: true` immediately enables it for matching users
|
||||
- Flag changes take effect within seconds due to PostHog's polling mechanism
|
||||
|
||||
### 4. Manage Projects
|
||||
|
||||
**When to use**: User wants to list or inspect PostHog projects and organizations
|
||||
|
||||
**Tool sequence**:
|
||||
1. `POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION` - List all projects [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `organization_id`: Organization identifier (may be optional depending on auth)
|
||||
- `limit`: Number of results per page
|
||||
- `offset`: Pagination offset
|
||||
|
||||
**Pitfalls**:
|
||||
- Project IDs are numeric; used as parameters in most other endpoints
|
||||
- Organization ID may be required; check your PostHog setup
|
||||
- Pagination is offset-based; iterate until results are empty
|
||||
- Project settings include API keys and configuration details
|
||||
|
||||
### 5. User Profile and Authentication
|
||||
|
||||
**When to use**: User wants to check current user details or verify API access
|
||||
|
||||
**Tool sequence**:
|
||||
1. `POSTHOG_WHOAMI` - Get current API user information [Optional]
|
||||
2. `POSTHOG_RETRIEVE_CURRENT_USER_PROFILE` - Get detailed user profile [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- No required parameters for either call
|
||||
- Returns current authenticated user's details, permissions, and organization info
|
||||
|
||||
**Pitfalls**:
|
||||
- WHOAMI is a lightweight check; use for verifying API connectivity
|
||||
- User profile includes organization membership and permissions
|
||||
- These endpoints confirm the API key's access level and scope
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Organization -> Project ID**:
|
||||
```
|
||||
1. Call POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION
|
||||
2. Find project by name in results
|
||||
3. Extract id (numeric) for use in other endpoints
|
||||
```
|
||||
|
||||
**Feature flag name -> Flag ID**:
|
||||
```
|
||||
1. Call POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS with project_id
|
||||
2. Find flag by key or name
|
||||
3. Extract id for detailed operations
|
||||
```
|
||||
|
||||
### Feature Flag Targeting
|
||||
|
||||
Feature flags support sophisticated targeting:
|
||||
```json
|
||||
{
|
||||
"filters": {
|
||||
"groups": [
|
||||
{
|
||||
"properties": [
|
||||
{"key": "email", "value": "@company.com", "operator": "icontains"}
|
||||
],
|
||||
"rollout_percentage": 100
|
||||
},
|
||||
{
|
||||
"properties": [],
|
||||
"rollout_percentage": 10
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
- Groups are evaluated in order; first matching group determines the rollout
|
||||
- Properties filter users by their traits
|
||||
- Rollout percentage determines what fraction of matching users see the flag
|
||||
|
||||
### Pagination
|
||||
|
||||
- Events: Use `offset` and `limit` (offset-based)
|
||||
- Feature flags: Use `offset` and `limit` (offset-based)
|
||||
- Projects: Use `offset` and `limit` (offset-based)
|
||||
- Continue until results array is empty or smaller than `limit`
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Project IDs**:
|
||||
- Required for most API endpoints
|
||||
- Always resolve project names to numeric IDs first
|
||||
- Multiple projects can exist in one organization
|
||||
|
||||
**Event Naming**:
|
||||
- System events use `$` prefix ($pageview, $identify, $autocapture)
|
||||
- Custom events should NOT use `$` prefix
|
||||
- Event names are case-sensitive; maintain consistency
|
||||
|
||||
**Feature Flags**:
|
||||
- Flag keys must be unique within a project
|
||||
- Use kebab-case for flag keys
|
||||
- Changes propagate within seconds
|
||||
- Deleting a flag is permanent; consider disabling instead
|
||||
|
||||
**Rate Limits**:
|
||||
- Event ingestion has throughput limits
|
||||
- Batch events where possible for efficiency
|
||||
- API endpoints have per-minute rate limits
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` or `results` key
|
||||
- Paginated responses include `count`, `next`, `previous` fields
|
||||
- Event properties are nested objects; access carefully
|
||||
- Parse defensively with fallbacks for optional fields
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Capture event | POSTHOG_CAPTURE_EVENT | event, distinct_id, properties |
|
||||
| List events | POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS | project_id, event, after, before |
|
||||
| List feature flags | POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS | project_id |
|
||||
| Get flag details | POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS | project_id, id |
|
||||
| Create flag | POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT | project_id, key, filters |
|
||||
| List projects | POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION | organization_id |
|
||||
| Who am I | POSTHOG_WHOAMI | (none) |
|
||||
| User profile | POSTHOG_RETRIEVE_CURRENT_USER_PROFILE | (none) |
|
||||
@@ -1,187 +0,0 @@
|
||||
---
|
||||
name: postmark-automation
|
||||
description: "Automate Postmark email delivery tasks via Rube MCP (Composio): send templated emails, manage templates, monitor delivery stats and bounces. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Postmark Automation via Rube MCP
|
||||
|
||||
Automate Postmark transactional email operations through Composio's Postmark toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Postmark connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `postmark`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `postmark`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Postmark authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Send Templated Batch Emails
|
||||
|
||||
**When to use**: User wants to send templated emails to multiple recipients in one call
|
||||
|
||||
**Tool sequence**:
|
||||
1. `POSTMARK_LIST_TEMPLATES` - Find available templates and their IDs [Prerequisite]
|
||||
2. `POSTMARK_VALIDATE_TEMPLATE` - Validate template with model data before sending [Optional]
|
||||
3. `POSTMARK_SEND_BATCH_WITH_TEMPLATES` - Send batch emails using a template [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `TemplateId` or `TemplateAlias`: Identifier for the template to use
|
||||
- `Messages`: Array of message objects with `From`, `To`, `TemplateModel`
|
||||
- `TemplateModel`: Key-value pairs matching template variables
|
||||
|
||||
**Pitfalls**:
|
||||
- Maximum 500 messages per batch call
|
||||
- Either `TemplateId` or `TemplateAlias` is required, not both
|
||||
- `TemplateModel` keys must match template variable names exactly (case-sensitive)
|
||||
- Sender address must be a verified Sender Signature or from a verified domain
|
||||
|
||||
### 2. Manage Email Templates
|
||||
|
||||
**When to use**: User wants to create, edit, or inspect email templates
|
||||
|
||||
**Tool sequence**:
|
||||
1. `POSTMARK_LIST_TEMPLATES` - List all templates with IDs and names [Required]
|
||||
2. `POSTMARK_GET_TEMPLATE` - Get full template details including HTML/text body [Optional]
|
||||
3. `POSTMARK_EDIT_TEMPLATE` - Update template content or settings [Optional]
|
||||
4. `POSTMARK_VALIDATE_TEMPLATE` - Test template rendering with sample data [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `TemplateId`: Numeric template ID for GET/EDIT operations
|
||||
- `Name`: Template display name
|
||||
- `Subject`: Email subject line (supports template variables)
|
||||
- `HtmlBody`: HTML content of the template
|
||||
- `TextBody`: Plain text fallback content
|
||||
- `TemplateType`: 'Standard' or 'Layout'
|
||||
|
||||
**Pitfalls**:
|
||||
- Template IDs are numeric integers, not strings
|
||||
- Editing a template replaces the entire content; include all fields you want to keep
|
||||
- Layout templates wrap Standard templates; changing a layout affects all linked templates
|
||||
- Validate before sending to catch missing variables early
|
||||
|
||||
### 3. Monitor Delivery Statistics
|
||||
|
||||
**When to use**: User wants to check email delivery health, open/click rates, or outbound overview
|
||||
|
||||
**Tool sequence**:
|
||||
1. `POSTMARK_GET_DELIVERY_STATS` - Get bounce counts by type [Required]
|
||||
2. `POSTMARK_GET_OUTBOUND_OVERVIEW` - Get sent/opened/clicked/bounced summary [Required]
|
||||
3. `POSTMARK_GET_TRACKED_EMAIL_COUNTS` - Get tracked email volume over time [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `fromdate`: Start date for filtering stats (YYYY-MM-DD)
|
||||
- `todate`: End date for filtering stats (YYYY-MM-DD)
|
||||
- `tag`: Filter stats by message tag
|
||||
- `messagestreamid`: Filter by message stream (e.g., 'outbound', 'broadcast')
|
||||
|
||||
**Pitfalls**:
|
||||
- Date parameters use YYYY-MM-DD format without time component
|
||||
- Stats are aggregated; individual message tracking requires separate API calls
|
||||
- `messagestreamid` defaults to all streams if not specified
|
||||
|
||||
### 4. Manage Bounces and Complaints
|
||||
|
||||
**When to use**: User wants to review bounced emails or spam complaints
|
||||
|
||||
**Tool sequence**:
|
||||
1. `POSTMARK_GET_BOUNCES` - List bounced messages with details [Required]
|
||||
2. `POSTMARK_GET_SPAM_COMPLAINTS` - List spam complaint records [Optional]
|
||||
3. `POSTMARK_GET_DELIVERY_STATS` - Get bounce summary counts [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `count`: Number of records to return per page
|
||||
- `offset`: Pagination offset for results
|
||||
- `type`: Bounce type filter (e.g., 'HardBounce', 'SoftBounce', 'SpamNotification')
|
||||
- `fromdate`/`todate`: Date range filters
|
||||
- `emailFilter`: Filter by recipient email address
|
||||
|
||||
**Pitfalls**:
|
||||
- Bounce types include: HardBounce, SoftBounce, SpamNotification, SpamComplaint, Transient, and others
|
||||
- Hard bounces indicate permanent delivery failures; these addresses should be removed
|
||||
- Spam complaints affect sender reputation; monitor regularly
|
||||
- Pagination uses `count` and `offset`, not page tokens
|
||||
|
||||
### 5. Configure Server Settings
|
||||
|
||||
**When to use**: User wants to view or modify Postmark server configuration
|
||||
|
||||
**Tool sequence**:
|
||||
1. `POSTMARK_GET_SERVER` - Retrieve current server settings [Required]
|
||||
2. `POSTMARK_EDIT_SERVER` - Update server configuration [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `Name`: Server display name
|
||||
- `SmtpApiActivated`: Enable/disable SMTP API access
|
||||
- `BounceHookUrl`: Webhook URL for bounce notifications
|
||||
- `InboundHookUrl`: Webhook URL for inbound email processing
|
||||
- `TrackOpens`: Enable/disable open tracking
|
||||
- `TrackLinks`: Link tracking mode ('None', 'HtmlAndText', 'HtmlOnly', 'TextOnly')
|
||||
|
||||
**Pitfalls**:
|
||||
- Server edits affect all messages sent through that server
|
||||
- Webhook URLs must be publicly accessible HTTPS endpoints
|
||||
- Changing `SmtpApiActivated` affects SMTP relay access immediately
|
||||
- Track settings apply to future messages only, not retroactively
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Template Variable Resolution
|
||||
|
||||
```
|
||||
1. Call POSTMARK_GET_TEMPLATE with TemplateId
|
||||
2. Inspect HtmlBody/TextBody for {{variable}} placeholders
|
||||
3. Build TemplateModel dict with matching keys
|
||||
4. Call POSTMARK_VALIDATE_TEMPLATE to verify rendering
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Set `count` for results per page (varies by endpoint)
|
||||
- Use `offset` to skip previously fetched results
|
||||
- Increment offset by count each page until results returned < count
|
||||
- Total records may be returned in response metadata
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Authentication**:
|
||||
- Postmark uses server-level API tokens, not account-level
|
||||
- Each server has its own token; ensure correct server context
|
||||
- Sender addresses must be verified Sender Signatures or from verified domains
|
||||
|
||||
**Rate Limits**:
|
||||
- Batch send limited to 500 messages per call
|
||||
- API rate limits vary by endpoint; implement backoff on 429 responses
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` or `data.data`
|
||||
- Parse defensively with fallback patterns
|
||||
- Template IDs are always numeric integers
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Send batch templated emails | POSTMARK_SEND_BATCH_WITH_TEMPLATES | Messages, TemplateId/TemplateAlias |
|
||||
| List templates | POSTMARK_LIST_TEMPLATES | Count, Offset, TemplateType |
|
||||
| Get template details | POSTMARK_GET_TEMPLATE | TemplateId |
|
||||
| Edit template | POSTMARK_EDIT_TEMPLATE | TemplateId, Name, Subject, HtmlBody |
|
||||
| Validate template | POSTMARK_VALIDATE_TEMPLATE | TemplateId, TemplateModel |
|
||||
| Delivery stats | POSTMARK_GET_DELIVERY_STATS | (none or date filters) |
|
||||
| Outbound overview | POSTMARK_GET_OUTBOUND_OVERVIEW | fromdate, todate, tag |
|
||||
| Get bounces | POSTMARK_GET_BOUNCES | count, offset, type, emailFilter |
|
||||
| Get spam complaints | POSTMARK_GET_SPAM_COMPLAINTS | count, offset, fromdate, todate |
|
||||
| Tracked email counts | POSTMARK_GET_TRACKED_EMAIL_COUNTS | fromdate, todate, tag |
|
||||
| Get server config | POSTMARK_GET_SERVER | (none) |
|
||||
| Edit server config | POSTMARK_EDIT_SERVER | Name, TrackOpens, TrackLinks |
|
||||
@@ -1,659 +0,0 @@
|
||||
# 🎯 Prompt Engineer
|
||||
|
||||
**Version:** 1.0.1
|
||||
**Status:** ✨ Zero-Config | 🌍 Universal
|
||||
|
||||
Transform raw prompts into optimized, production-ready prompts using 11 established prompting frameworks.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Overview
|
||||
|
||||
**Prompt Engineer** is an intelligent AI skill that analyzes your intentions and automatically generates optimized prompts for Claude, ChatGPT, or any other AI model. Instead of struggling with how to phrase complex requests, simply describe what you want - the skill handles the rest.
|
||||
|
||||
This skill works in **"magic mode"** - it operates silently, only asking questions when absolutely necessary. You provide a rough idea, and it returns a polished, structured prompt ready to use.
|
||||
|
||||
### ✨ Key Features
|
||||
|
||||
- **🎯 Intent Analysis:** Understands what you're trying to accomplish
|
||||
- **🧠 11 Frameworks:** RTF, Chain of Thought, RISEN, RODES, Chain of Density, RACE, RISE, STAR, SOAP, CLEAR, GROW
|
||||
- **🔄 Framework Blending:** Combines multiple frameworks when needed
|
||||
- **❓ Smart Clarification:** Only asks questions when critically needed
|
||||
- **📏 Adaptive Output:** Matches prompt length to task complexity
|
||||
- **🌍 Universal:** Works in any project, any terminal context
|
||||
- **🪄 Magic Mode:** No technical explanations - just results
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Invoke the Skill
|
||||
|
||||
Use any of these trigger phrases:
|
||||
|
||||
```bash
|
||||
copilot> improve this prompt: [your rough prompt]
|
||||
copilot> optimize prompt: [your idea]
|
||||
copilot> refine prompt: [what you want]
|
||||
copilot> prompt engineering for: [task description]
|
||||
copilot> transform into prompt: [concept]
|
||||
copilot> create prompt for: [goal]
|
||||
```
|
||||
|
||||
### Example 1: Simple Task
|
||||
|
||||
**Input:**
|
||||
```bash
|
||||
copilot> improve this prompt: help me write Python code
|
||||
```
|
||||
|
||||
**Skill asks:**
|
||||
```
|
||||
What type of Python code do you need?
|
||||
- [ ] Data analysis
|
||||
- [ ] Web scraping
|
||||
- [ ] Task automation
|
||||
- [ ] API/backend development
|
||||
```
|
||||
|
||||
**You select:** "Web scraping"
|
||||
|
||||
**Output:**
|
||||
````markdown
|
||||
```
|
||||
You are a Python developer expert in web scraping.
|
||||
|
||||
Task: Create a Python script to scrape data from [specify target website].
|
||||
|
||||
Requirements:
|
||||
- Use BeautifulSoup or Scrapy
|
||||
- Implement pagination and rate limiting
|
||||
- Store data in structured format (CSV or JSON)
|
||||
- Include error handling for network issues
|
||||
|
||||
Output format: Complete, commented Python code with usage examples.
|
||||
```
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Complex Task (No Clarification Needed)
|
||||
|
||||
**Input:**
|
||||
```bash
|
||||
copilot> create prompt for: product recommendation system with purchase history and market trends
|
||||
```
|
||||
|
||||
**Output:**
|
||||
````markdown
|
||||
```
|
||||
Role: You are a senior machine learning engineer specializing in recommendation systems.
|
||||
|
||||
Objective: Design a product recommendation system that combines user purchase history, preferences, and market trends.
|
||||
|
||||
Details:
|
||||
- Input data sources: user transaction logs, preference surveys, market trend APIs
|
||||
- Algorithm considerations: collaborative filtering, content-based filtering, hybrid approaches
|
||||
- Performance metrics: precision, recall, diversity, novelty
|
||||
- Scalability: system must handle 100k+ users
|
||||
|
||||
Approach step-by-step:
|
||||
1. Analyze the three data sources and their relationships
|
||||
2. Propose 2-3 algorithm approaches with trade-offs
|
||||
3. Design data pipeline architecture
|
||||
4. Define evaluation metrics
|
||||
5. Outline implementation roadmap
|
||||
|
||||
Examples: Show pseudocode for core recommendation logic
|
||||
|
||||
Sense Check: Validate that the solution balances personalization with discovery and scales to production.
|
||||
|
||||
Output format: Technical design document with architecture diagrams and implementation roadmap.
|
||||
```
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Ambiguous Task (Skill Clarifies)
|
||||
|
||||
**Input:**
|
||||
```bash
|
||||
copilot> transform into prompt: I want to improve my process
|
||||
```
|
||||
|
||||
**Skill asks:**
|
||||
```
|
||||
What process do you want to improve?
|
||||
- [ ] Work/productivity process
|
||||
- [ ] Learning process
|
||||
- [ ] Technical process (development, deployment, etc.)
|
||||
```
|
||||
|
||||
**You select:** "Work process"
|
||||
|
||||
**Skill asks:**
|
||||
```
|
||||
What specific aspect?
|
||||
- [ ] Time management
|
||||
- [ ] Team collaboration
|
||||
- [ ] Decision making
|
||||
```
|
||||
|
||||
**You select:** "Decision making"
|
||||
|
||||
**Output:**
|
||||
````markdown
|
||||
```
|
||||
Context: I struggle with making decisions quickly and effectively at work.
|
||||
|
||||
Objective: Develop a structured framework to improve decision speed and quality.
|
||||
|
||||
Current Reality:
|
||||
- Decisions delayed by excessive analysis
|
||||
- Lack of clear criteria
|
||||
- Uncertainty about when to decide vs. gather information
|
||||
|
||||
Desired Outcome:
|
||||
- Consistent decision-making framework
|
||||
- Clear criteria for different decision types
|
||||
- Reduced decision fatigue
|
||||
|
||||
Your task:
|
||||
1. Assess current patterns and identify bottlenecks
|
||||
2. Propose framework (Eisenhower Matrix, RAPID, Decision Tree)
|
||||
3. Create decision criteria templates
|
||||
4. Design tracking and iteration process
|
||||
|
||||
Output format: Practical playbook with templates, examples, and metrics.
|
||||
```
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
## 📚 Supported Frameworks
|
||||
|
||||
The **Prompt Engineer** skill uses **11 established frameworks** to optimize your prompts. The skill automatically selects and blends these frameworks based on your task - you never need to know or choose them manually.
|
||||
|
||||
---
|
||||
|
||||
### 1. **RTF (Role-Task-Format)**
|
||||
|
||||
**Structure:** Role → Task → Format
|
||||
|
||||
**Best for:** Tasks requiring specific expertise or perspective
|
||||
|
||||
**Components:**
|
||||
- **Role:** "You are a [expert identity]"
|
||||
- **Task:** "Your task is to [specific action]"
|
||||
- **Format:** "Output format: [structure/style]"
|
||||
|
||||
**Example:**
|
||||
```
|
||||
You are a senior Python developer.
|
||||
Task: Refactor this code for better performance.
|
||||
Format: Provide refactored code with inline comments explaining changes.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. **Chain of Thought**
|
||||
|
||||
**Structure:** Problem → Step 1 → Step 2 → ... → Solution
|
||||
|
||||
**Best for:** Complex reasoning, debugging, mathematical problems, logic puzzles
|
||||
|
||||
**Components:**
|
||||
- Break problem into sequential steps
|
||||
- Show reasoning at each stage
|
||||
- Build toward final solution
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Solve this problem step-by-step:
|
||||
1. Identify the core issue
|
||||
2. Analyze contributing factors
|
||||
3. Propose solution approach
|
||||
4. Validate solution against requirements
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. **RISEN**
|
||||
|
||||
**Structure:** Role, Instructions, Steps, End goal, Narrowing
|
||||
|
||||
**Best for:** Multi-phase projects with clear deliverables and constraints
|
||||
|
||||
**Components:**
|
||||
- **Role:** Expert identity
|
||||
- **Instructions:** What to do
|
||||
- **Steps:** Sequential actions
|
||||
- **End goal:** Desired outcome
|
||||
- **Narrowing:** Constraints and focus areas
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Role: You are a DevOps architect.
|
||||
Instructions: Design a CI/CD pipeline for microservices.
|
||||
Steps: 1) Analyze requirements 2) Select tools 3) Design workflow 4) Document
|
||||
End goal: Automated deployment with zero-downtime releases.
|
||||
Narrowing: Focus on AWS, limit to 3 environments (dev/staging/prod).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. **RODES**
|
||||
|
||||
**Structure:** Role, Objective, Details, Examples, Sense check
|
||||
|
||||
**Best for:** Complex design, system architecture, research proposals
|
||||
|
||||
**Components:**
|
||||
- **Role:** Expert perspective
|
||||
- **Objective:** What to achieve
|
||||
- **Details:** Context and requirements
|
||||
- **Examples:** Concrete illustrations
|
||||
- **Sense check:** Validation criteria
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Role: You are a system architect.
|
||||
Objective: Design a scalable e-commerce platform.
|
||||
Details: Handle 100k concurrent users, sub-200ms response time, multi-region.
|
||||
Examples: Show database schema, caching strategy, load balancing.
|
||||
Sense check: Validate solution meets latency and scalability requirements.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. **Chain of Density**
|
||||
|
||||
**Structure:** Iteration 1 (verbose) → Iteration 2 → ... → Iteration 5 (maximum density)
|
||||
|
||||
**Best for:** Summarization, compression, synthesis of long content
|
||||
|
||||
**Process:**
|
||||
- Start with verbose explanation
|
||||
- Iteratively compress while preserving key information
|
||||
- End with maximally dense version (high information per word)
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Compress this article into progressively denser summaries:
|
||||
1. Initial summary (300 words)
|
||||
2. Compressed (200 words)
|
||||
3. Further compressed (100 words)
|
||||
4. Dense (50 words)
|
||||
5. Maximum density (25 words, all critical points)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. **RACE**
|
||||
|
||||
**Structure:** Role, Audience, Context, Expectation
|
||||
|
||||
**Best for:** Communication, presentations, stakeholder updates, storytelling
|
||||
|
||||
**Components:**
|
||||
- **Role:** Communicator identity
|
||||
- **Audience:** Who you're addressing (expertise level, concerns)
|
||||
- **Context:** Background/situation
|
||||
- **Expectation:** What audience needs to know or do
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Role: You are a product manager.
|
||||
Audience: Non-technical executives.
|
||||
Context: Quarterly business review, product performance down 5%.
|
||||
Expectation: Explain root causes and recovery plan in non-technical terms.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. **RISE**
|
||||
|
||||
**Structure:** Research, Investigate, Synthesize, Evaluate
|
||||
|
||||
**Best for:** Analysis, investigation, systematic exploration, diagnostic work
|
||||
|
||||
**Process:**
|
||||
1. **Research:** Gather information
|
||||
2. **Investigate:** Deep dive into findings
|
||||
3. **Synthesize:** Combine insights
|
||||
4. **Evaluate:** Assess and recommend
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Analyze customer churn data using RISE:
|
||||
Research: Collect churn metrics, exit surveys, support tickets.
|
||||
Investigate: Identify patterns in churned users.
|
||||
Synthesize: Combine findings into themes.
|
||||
Evaluate: Recommend retention strategies based on evidence.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8. **STAR**
|
||||
|
||||
**Structure:** Situation, Task, Action, Result
|
||||
|
||||
**Best for:** Problem-solving with rich context, case studies, retrospectives
|
||||
|
||||
**Components:**
|
||||
- **Situation:** Background context
|
||||
- **Task:** Specific challenge
|
||||
- **Action:** What needs doing
|
||||
- **Result:** Expected outcome
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Situation: Legacy monolith causing deployment delays (2 weeks per release).
|
||||
Task: Modernize architecture to enable daily deployments.
|
||||
Action: Migrate to microservices, implement CI/CD, containerize.
|
||||
Result: Deploy 10+ times per day with <5% rollback rate.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9. **SOAP**
|
||||
|
||||
**Structure:** Subjective, Objective, Assessment, Plan
|
||||
|
||||
**Best for:** Structured documentation, medical records, technical logs, incident reports
|
||||
|
||||
**Components:**
|
||||
- **Subjective:** Reported information (symptoms, complaints)
|
||||
- **Objective:** Observable facts (metrics, data)
|
||||
- **Assessment:** Analysis and diagnosis
|
||||
- **Plan:** Recommended actions
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Incident Report (SOAP):
|
||||
Subjective: Users report slow page loads starting 10 AM.
|
||||
Objective: Average response time increased from 200ms to 3s. CPU at 95%.
|
||||
Assessment: Database connection pool exhausted due to traffic spike.
|
||||
Plan: 1) Scale pool size 2) Add monitoring alerts 3) Review query performance.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10. **CLEAR**
|
||||
|
||||
**Structure:** Collaborative, Limited, Emotional, Appreciable, Refinable
|
||||
|
||||
**Best for:** Goal-setting, OKRs, measurable objectives, team alignment
|
||||
|
||||
**Components:**
|
||||
- **Collaborative:** Who's involved
|
||||
- **Limited:** Scope boundaries (time, resources)
|
||||
- **Emotional:** Why it matters (motivation)
|
||||
- **Appreciable:** Measurable progress indicators
|
||||
- **Refinable:** How to iterate and improve
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Q1 Objective (CLEAR):
|
||||
Collaborative: Engineering + Product teams.
|
||||
Limited: Complete by March 31, budget $50k, 2 engineers allocated.
|
||||
Emotional: Reduces customer support load by 30%, improves satisfaction.
|
||||
Appreciable: Track weekly via tickets resolved, NPS score, deployment count.
|
||||
Refinable: Bi-weekly retrospectives, adjust priorities based on feedback.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 11. **GROW**
|
||||
|
||||
**Structure:** Goal, Reality, Options, Will
|
||||
|
||||
**Best for:** Coaching, personal development, growth planning, mentorship
|
||||
|
||||
**Components:**
|
||||
- **Goal:** What to achieve
|
||||
- **Reality:** Current situation (strengths, gaps)
|
||||
- **Options:** Possible approaches
|
||||
- **Will:** Commitment to action
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Career Development (GROW):
|
||||
Goal: Become senior engineer within 12 months.
|
||||
Reality: Strong coding skills, weak in system design and leadership.
|
||||
Options: 1) Take system design course 2) Lead a project 3) Find mentor.
|
||||
Will: Commit to 5 hours/week study, lead Q2 project, find mentor by Feb.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Framework Selection Logic
|
||||
|
||||
The skill analyzes your input and:
|
||||
|
||||
1. **Detects task type**
|
||||
- Coding, writing, analysis, design, communication, etc.
|
||||
|
||||
2. **Identifies complexity**
|
||||
- Simple (1-2 sentences) → Fast, minimal structure
|
||||
- Moderate (paragraph) → Standard framework
|
||||
- Complex (detailed requirements) → Advanced framework or blend
|
||||
|
||||
3. **Selects primary framework**
|
||||
- RTF → Role-based tasks
|
||||
- Chain of Thought → Step-by-step reasoning
|
||||
- RISEN/RODES → Complex projects
|
||||
- RACE → Communication
|
||||
- STAR → Contextual problems
|
||||
- And so on...
|
||||
|
||||
4. **Blends secondary frameworks when needed**
|
||||
- RODES + Chain of Thought → Complex technical projects
|
||||
- CLEAR + GROW → Leadership goals
|
||||
- RACE + STAR → Strategic communication
|
||||
|
||||
**You never choose the framework manually** - the skill does it automatically in "magic mode."
|
||||
|
||||
---
|
||||
|
||||
### Common Framework Blends
|
||||
|
||||
| Task Type | Primary Framework | Blended With | Result |
|
||||
|-----------|------------------|--------------|--------|
|
||||
| Complex technical design | RODES | Chain of Thought | Structured design with step-by-step reasoning |
|
||||
| Leadership development | CLEAR | GROW | Measurable goals with action commitment |
|
||||
| Strategic communication | RACE | STAR | Audience-aware storytelling with context |
|
||||
| Incident investigation | RISE | SOAP | Systematic analysis with structured documentation |
|
||||
| Project planning | RISEN | RTF | Multi-phase delivery with role clarity |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 How It Works
|
||||
|
||||
```
|
||||
User Input (rough prompt)
|
||||
↓
|
||||
┌────────────────────────┐
|
||||
│ 1. Analyze Intent │ What is the user trying to do?
|
||||
│ - Task type │ Coding? Writing? Analysis? Design?
|
||||
│ - Complexity │ Simple, moderate, complex?
|
||||
│ - Clarity │ Clear or ambiguous?
|
||||
└────────┬───────────────┘
|
||||
↓
|
||||
┌────────────────────────┐
|
||||
│ 2. Clarify (Optional) │ Only if critically needed
|
||||
│ - Ask 2-3 questions │ Multiple choice when possible
|
||||
│ - Fill missing gaps │
|
||||
└────────┬───────────────┘
|
||||
↓
|
||||
┌────────────────────────┐
|
||||
│ 3. Select Framework(s) │ Silent selection
|
||||
│ - Map task → framework
|
||||
│ - Blend if needed │
|
||||
└────────┬───────────────┘
|
||||
↓
|
||||
┌────────────────────────┐
|
||||
│ 4. Generate Prompt │ Apply framework rules
|
||||
│ - Add role/context │
|
||||
│ - Structure task │
|
||||
│ - Define format │
|
||||
│ - Add examples │
|
||||
└────────┬───────────────┘
|
||||
↓
|
||||
┌────────────────────────┐
|
||||
│ 5. Output │ Clean, copy-ready
|
||||
│ Markdown code block │ No explanations
|
||||
└────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Use Cases
|
||||
|
||||
### Coding
|
||||
|
||||
```bash
|
||||
copilot> optimize prompt: create REST API in Python
|
||||
```
|
||||
|
||||
→ Generates structured prompt with role, requirements, output format, examples
|
||||
|
||||
---
|
||||
|
||||
### Writing
|
||||
|
||||
```bash
|
||||
copilot> create prompt for: write technical article about microservices
|
||||
```
|
||||
|
||||
→ Generates audience-aware prompt with structure, tone, and content guidelines
|
||||
|
||||
---
|
||||
|
||||
### Analysis
|
||||
|
||||
```bash
|
||||
copilot> refine prompt: analyze sales data and identify trends
|
||||
```
|
||||
|
||||
→ Generates step-by-step analytical framework with visualization requirements
|
||||
|
||||
---
|
||||
|
||||
### Decision Making
|
||||
|
||||
```bash
|
||||
copilot> improve this prompt: I need to decide between technology A and B
|
||||
```
|
||||
|
||||
→ Generates decision framework with criteria, trade-offs, and validation
|
||||
|
||||
---
|
||||
|
||||
### Learning
|
||||
|
||||
```bash
|
||||
copilot> transform into prompt: learn machine learning from zero
|
||||
```
|
||||
|
||||
→ Generates learning path prompt with phases, resources, and milestones
|
||||
|
||||
---
|
||||
|
||||
## ❓ FAQ
|
||||
|
||||
### Q: Does this skill work outside of Obsidian vaults?
|
||||
**A:** Yes! It's a **universal skill** that works in any terminal context. It doesn't depend on vault structure, project configuration, or external files.
|
||||
|
||||
---
|
||||
|
||||
### Q: Do I need to know prompting frameworks?
|
||||
**A:** No. The skill knows all 11 frameworks and selects the best one(s) automatically based on your task.
|
||||
|
||||
---
|
||||
|
||||
### Q: Will the skill explain which framework it used?
|
||||
**A:** No. It operates in "magic mode" - you get the polished prompt without technical explanations. If you want to know, you can ask explicitly.
|
||||
|
||||
---
|
||||
|
||||
### Q: How many questions will the skill ask me?
|
||||
**A:** Maximum 2-3 questions, and only when information is critically missing. Most of the time, it generates the prompt directly.
|
||||
|
||||
---
|
||||
|
||||
### Q: Can I customize the frameworks?
|
||||
**A:** The skill uses standard framework definitions. You can't customize them, but you can provide additional constraints in your input (e.g., "create a short prompt for...").
|
||||
|
||||
---
|
||||
|
||||
### Q: Does it support languages other than English?
|
||||
**A:** Yes. If you provide input in Portuguese, it generates the prompt in Portuguese. Same for English or mixed inputs.
|
||||
|
||||
---
|
||||
|
||||
### Q: What if I don't like the generated prompt?
|
||||
**A:** You can ask the skill to refine it: "make it shorter", "add more examples", "focus on X aspect", etc.
|
||||
|
||||
---
|
||||
|
||||
### Q: Can I use this for any AI model (Claude, ChatGPT, Gemini)?
|
||||
**A:** Yes. The prompts are model-agnostic and work with any conversational AI.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Installation (Global Setup)
|
||||
|
||||
This skill is designed to work **globally** across all your projects.
|
||||
|
||||
### Option 1: Use from Repository
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/eric.andrade/cli-ai-skills.git
|
||||
```
|
||||
|
||||
2. Configure Copilot to load skills globally:
|
||||
```bash
|
||||
# Add to ~/.copilot/config.json
|
||||
{
|
||||
"skills": {
|
||||
"directories": [
|
||||
"/path/to/cli-ai-skills/.github/skills"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Option 2: Copy to Global Skills Directory
|
||||
|
||||
```bash
|
||||
cp -r /path/to/cli-ai-skills/.github/skills/prompt-engineer ~/.copilot/global-skills/
|
||||
```
|
||||
|
||||
Then configure:
|
||||
```bash
|
||||
# Add to ~/.copilot/config.json
|
||||
{
|
||||
"skills": {
|
||||
"directories": [
|
||||
"~/.copilot/global-skills"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Learn More
|
||||
|
||||
- **[Skill Development Guide](../../resources/skills-development.md)** - Learn how to create your own skills
|
||||
- **[SKILL.md](./SKILL.md)** - Full technical specification of this skill
|
||||
- **[Repository README](../../README.md)** - Overview of all available skills
|
||||
|
||||
---
|
||||
|
||||
## 📄 Version
|
||||
|
||||
**v1.0.1** | Zero-Config | Universal
|
||||
*Works in any project, any context, any terminal.*
|
||||
@@ -1,252 +1,272 @@
|
||||
---
|
||||
name: prompt-engineer
|
||||
description: "Transforms user prompts into optimized prompts using frameworks (RTF, RISEN, Chain of Thought, RODES, Chain of Density, RACE, RISE, STAR, SOAP, CLEAR, GROW)"
|
||||
version: 1.1.0
|
||||
author: Eric Andrade
|
||||
created: 2025-02-01
|
||||
updated: 2026-02-04
|
||||
platforms: [github-copilot-cli, claude-code, codex]
|
||||
category: automation
|
||||
tags: [prompt-engineering, optimization, frameworks, ai-enhancement]
|
||||
risk: safe
|
||||
description: Expert prompt engineer specializing in advanced prompting
|
||||
techniques, LLM optimization, and AI system design. Masters chain-of-thought,
|
||||
constitutional AI, and production prompt strategies. Use when building AI
|
||||
features, improving agent performance, or crafting system prompts.
|
||||
metadata:
|
||||
model: inherit
|
||||
---
|
||||
|
||||
## Use this skill when
|
||||
|
||||
- Working on prompt engineer tasks or workflows
|
||||
- Needing guidance, best practices, or checklists for prompt engineer
|
||||
|
||||
## Do not use this skill when
|
||||
|
||||
- The task is unrelated to prompt engineer
|
||||
- You need a different domain or tool outside this scope
|
||||
|
||||
## Instructions
|
||||
|
||||
- Clarify goals, constraints, and required inputs.
|
||||
- Apply relevant best practices and validate outcomes.
|
||||
- Provide actionable steps and verification.
|
||||
- If detailed examples are required, open `resources/implementation-playbook.md`.
|
||||
|
||||
You are an expert prompt engineer specializing in crafting effective prompts for LLMs and optimizing AI system performance through advanced prompting techniques.
|
||||
|
||||
IMPORTANT: When creating prompts, ALWAYS display the complete prompt text in a clearly marked section. Never describe a prompt without showing it. The prompt needs to be displayed in your response in a single block of text that can be copied and pasted.
|
||||
|
||||
## Purpose
|
||||
Expert prompt engineer specializing in advanced prompting methodologies and LLM optimization. Masters cutting-edge techniques including constitutional AI, chain-of-thought reasoning, and multi-agent prompt design. Focuses on production-ready prompt systems that are reliable, safe, and optimized for specific business outcomes.
|
||||
|
||||
This skill transforms raw, unstructured user prompts into highly optimized prompts using established prompting frameworks. It analyzes user intent, identifies task complexity, and intelligently selects the most appropriate framework(s) to maximize Claude/ChatGPT output quality.
|
||||
## Capabilities
|
||||
|
||||
The skill operates in "magic mode" - it works silently behind the scenes, only interacting with users when clarification is critically needed. Users receive polished, ready-to-use prompts without technical explanations or framework jargon.
|
||||
### Advanced Prompting Techniques
|
||||
|
||||
This is a **universal skill** that works in any terminal context, not limited to Obsidian vaults or specific project structures.
|
||||
#### Chain-of-Thought & Reasoning
|
||||
- Chain-of-thought (CoT) prompting for complex reasoning tasks
|
||||
- Few-shot chain-of-thought with carefully crafted examples
|
||||
- Zero-shot chain-of-thought with "Let's think step by step"
|
||||
- Tree-of-thoughts for exploring multiple reasoning paths
|
||||
- Self-consistency decoding with multiple reasoning chains
|
||||
- Least-to-most prompting for complex problem decomposition
|
||||
- Program-aided language models (PAL) for computational tasks
|
||||
|
||||
## When to Use
|
||||
#### Constitutional AI & Safety
|
||||
- Constitutional AI principles for self-correction and alignment
|
||||
- Critique and revise patterns for output improvement
|
||||
- Safety prompting techniques to prevent harmful outputs
|
||||
- Jailbreak detection and prevention strategies
|
||||
- Content filtering and moderation prompt patterns
|
||||
- Ethical reasoning and bias mitigation in prompts
|
||||
- Red teaming prompts for adversarial testing
|
||||
|
||||
Invoke this skill when:
|
||||
#### Meta-Prompting & Self-Improvement
|
||||
- Meta-prompting for prompt optimization and generation
|
||||
- Self-reflection and self-evaluation prompt patterns
|
||||
- Auto-prompting for dynamic prompt generation
|
||||
- Prompt compression and efficiency optimization
|
||||
- A/B testing frameworks for prompt performance
|
||||
- Iterative prompt refinement methodologies
|
||||
- Performance benchmarking and evaluation metrics
|
||||
|
||||
- User provides a vague or generic prompt (e.g., "help me code Python")
|
||||
- User has a complex idea but struggles to articulate it clearly
|
||||
- User's prompt lacks structure, context, or specific requirements
|
||||
- Task requires step-by-step reasoning (debugging, analysis, design)
|
||||
- User needs a prompt for a specific AI task but doesn't know prompting frameworks
|
||||
- User wants to improve an existing prompt's effectiveness
|
||||
- User asks variations of "how do I ask AI to..." or "create a prompt for..."
|
||||
### Model-Specific Optimization
|
||||
|
||||
## Workflow
|
||||
#### OpenAI Models (GPT-4o, o1-preview, o1-mini)
|
||||
- Function calling optimization and structured outputs
|
||||
- JSON mode utilization for reliable data extraction
|
||||
- System message design for consistent behavior
|
||||
- Temperature and parameter tuning for different use cases
|
||||
- Token optimization strategies for cost efficiency
|
||||
- Multi-turn conversation management
|
||||
- Image and multimodal prompt engineering
|
||||
|
||||
### Step 1: Analyze Intent
|
||||
#### Anthropic Claude (4.5 Sonnet, Haiku, Opus)
|
||||
- Constitutional AI alignment with Claude's training
|
||||
- Tool use optimization for complex workflows
|
||||
- Computer use prompting for automation tasks
|
||||
- XML tag structuring for clear prompt organization
|
||||
- Context window optimization for long documents
|
||||
- Safety considerations specific to Claude's capabilities
|
||||
- Harmlessness and helpfulness balancing
|
||||
|
||||
**Objective:** Understand what the user truly wants to accomplish.
|
||||
#### Open Source Models (Llama, Mixtral, Qwen)
|
||||
- Model-specific prompt formatting and special tokens
|
||||
- Fine-tuning prompt strategies for domain adaptation
|
||||
- Instruction-following optimization for different architectures
|
||||
- Memory and context management for smaller models
|
||||
- Quantization considerations for prompt effectiveness
|
||||
- Local deployment optimization strategies
|
||||
- Custom system prompt design for specialized models
|
||||
|
||||
**Actions:**
|
||||
1. Read the raw prompt provided by the user
|
||||
2. Detect task characteristics:
|
||||
- **Type:** coding, writing, analysis, design, learning, planning, decision-making, creative, etc.
|
||||
- **Complexity:** simple (one-step), moderate (multi-step), complex (requires reasoning/design)
|
||||
- **Clarity:** clear intention vs. ambiguous/vague
|
||||
- **Domain:** technical, business, creative, academic, personal, etc.
|
||||
3. Identify implicit requirements:
|
||||
- Does user need examples?
|
||||
- Is output format specified?
|
||||
- Are there constraints (time, resources, scope)?
|
||||
- Is this exploratory or execution-focused?
|
||||
### Production Prompt Systems
|
||||
|
||||
**Detection Patterns:**
|
||||
- **Simple tasks:** Short prompts (<50 chars), single verb, no context
|
||||
- **Complex tasks:** Long prompts (>200 chars), multiple requirements, conditional logic
|
||||
- **Ambiguous tasks:** Generic verbs ("help", "improve"), missing object/context
|
||||
- **Structured tasks:** Mentions steps, phases, deliverables, stakeholders
|
||||
#### Prompt Templates & Management
|
||||
- Dynamic prompt templating with variable injection
|
||||
- Conditional prompt logic based on context
|
||||
- Multi-language prompt adaptation and localization
|
||||
- Version control and A/B testing for prompts
|
||||
- Prompt libraries and reusable component systems
|
||||
- Environment-specific prompt configurations
|
||||
- Rollback strategies for prompt deployments
|
||||
|
||||
#### RAG & Knowledge Integration
|
||||
- Retrieval-augmented generation prompt optimization
|
||||
- Context compression and relevance filtering
|
||||
- Query understanding and expansion prompts
|
||||
- Multi-document reasoning and synthesis
|
||||
- Citation and source attribution prompting
|
||||
- Hallucination reduction techniques
|
||||
- Knowledge graph integration prompts
|
||||
|
||||
### Step 3: Select Framework(s)
|
||||
#### Agent & Multi-Agent Prompting
|
||||
- Agent role definition and persona creation
|
||||
- Multi-agent collaboration and communication protocols
|
||||
- Task decomposition and workflow orchestration
|
||||
- Inter-agent knowledge sharing and memory management
|
||||
- Conflict resolution and consensus building prompts
|
||||
- Tool selection and usage optimization
|
||||
- Agent evaluation and performance monitoring
|
||||
|
||||
**Objective:** Map task characteristics to optimal prompting framework(s).
|
||||
### Specialized Applications
|
||||
|
||||
**Framework Mapping Logic:**
|
||||
#### Business & Enterprise
|
||||
- Customer service chatbot optimization
|
||||
- Sales and marketing copy generation
|
||||
- Legal document analysis and generation
|
||||
- Financial analysis and reporting prompts
|
||||
- HR and recruitment screening assistance
|
||||
- Executive summary and reporting automation
|
||||
- Compliance and regulatory content generation
|
||||
|
||||
| Task Type | Recommended Framework(s) | Rationale |
|
||||
|-----------|-------------------------|-----------|
|
||||
| **Role-based tasks** (act as expert, consultant) | **RTF** (Role-Task-Format) | Clear role definition + task + output format |
|
||||
| **Step-by-step reasoning** (debugging, proof, logic) | **Chain of Thought** | Encourages explicit reasoning steps |
|
||||
| **Structured projects** (multi-phase, deliverables) | **RISEN** (Role, Instructions, Steps, End goal, Narrowing) | Comprehensive structure for complex work |
|
||||
| **Complex design/analysis** (systems, architecture) | **RODES** (Role, Objective, Details, Examples, Sense check) | Balances detail with validation |
|
||||
| **Summarization** (compress, synthesize) | **Chain of Density** | Iterative refinement to essential info |
|
||||
| **Communication** (reports, presentations, storytelling) | **RACE** (Role, Audience, Context, Expectation) | Audience-aware messaging |
|
||||
| **Investigation/analysis** (research, diagnosis) | **RISE** (Research, Investigate, Synthesize, Evaluate) | Systematic analytical approach |
|
||||
| **Contextual situations** (problem-solving with background) | **STAR** (Situation, Task, Action, Result) | Context-rich problem framing |
|
||||
| **Documentation** (medical, technical, records) | **SOAP** (Subjective, Objective, Assessment, Plan) | Structured information capture |
|
||||
| **Goal-setting** (OKRs, objectives, targets) | **CLEAR** (Collaborative, Limited, Emotional, Appreciable, Refinable) | Goal clarity and actionability |
|
||||
| **Coaching/development** (mentoring, growth) | **GROW** (Goal, Reality, Options, Will) | Developmental conversation structure |
|
||||
#### Creative & Content
|
||||
- Creative writing and storytelling prompts
|
||||
- Content marketing and SEO optimization
|
||||
- Brand voice and tone consistency
|
||||
- Social media content generation
|
||||
- Video script and podcast outline creation
|
||||
- Educational content and curriculum development
|
||||
- Translation and localization prompts
|
||||
|
||||
**Blending Strategy:**
|
||||
- **Combine 2-3 frameworks** when task spans multiple types
|
||||
- Example: Complex technical project → **RODES + Chain of Thought** (structure + reasoning)
|
||||
- Example: Leadership decision → **CLEAR + GROW** (goal clarity + development)
|
||||
#### Technical & Code
|
||||
- Code generation and optimization prompts
|
||||
- Technical documentation and API documentation
|
||||
- Debugging and error analysis assistance
|
||||
- Architecture design and system analysis
|
||||
- Test case generation and quality assurance
|
||||
- DevOps and infrastructure as code prompts
|
||||
- Security analysis and vulnerability assessment
|
||||
|
||||
**Selection Criteria:**
|
||||
- Primary framework = best match to core task type
|
||||
- Secondary framework(s) = address additional complexity dimensions
|
||||
- Avoid over-engineering: simple tasks get simple frameworks
|
||||
### Evaluation & Testing
|
||||
|
||||
**Critical Rule:** This selection happens **silently** - do not explain framework choice to user.
|
||||
#### Performance Metrics
|
||||
- Task-specific accuracy and quality metrics
|
||||
- Response time and efficiency measurements
|
||||
- Cost optimization and token usage analysis
|
||||
- User satisfaction and engagement metrics
|
||||
- Safety and alignment evaluation
|
||||
- Consistency and reliability testing
|
||||
- Edge case and robustness assessment
|
||||
|
||||
Role: You are a senior software architect. [RTF - Role]
|
||||
#### Testing Methodologies
|
||||
- Red team testing for prompt vulnerabilities
|
||||
- Adversarial prompt testing and jailbreak attempts
|
||||
- Cross-model performance comparison
|
||||
- A/B testing frameworks for prompt optimization
|
||||
- Statistical significance testing for improvements
|
||||
- Bias and fairness evaluation across demographics
|
||||
- Scalability testing for production workloads
|
||||
|
||||
Objective: Design a microservices architecture for [system]. [RODES - Objective]
|
||||
### Advanced Patterns & Architectures
|
||||
|
||||
Approach this step-by-step: [Chain of Thought]
|
||||
1. Analyze current monolithic constraints
|
||||
2. Identify service boundaries
|
||||
3. Design inter-service communication
|
||||
4. Plan data consistency strategy
|
||||
#### Prompt Chaining & Workflows
|
||||
- Sequential prompt chaining for complex tasks
|
||||
- Parallel prompt execution and result aggregation
|
||||
- Conditional branching based on intermediate outputs
|
||||
- Loop and iteration patterns for refinement
|
||||
- Error handling and recovery mechanisms
|
||||
- State management across prompt sequences
|
||||
- Workflow optimization and performance tuning
|
||||
|
||||
Details: [RODES - Details]
|
||||
- Expected traffic: [X]
|
||||
- Data volume: [Y]
|
||||
- Team size: [Z]
|
||||
#### Multimodal & Cross-Modal
|
||||
- Vision-language model prompt optimization
|
||||
- Image understanding and analysis prompts
|
||||
- Document AI and OCR integration prompts
|
||||
- Audio and speech processing integration
|
||||
- Video analysis and content extraction
|
||||
- Cross-modal reasoning and synthesis
|
||||
- Multimodal creative and generative prompts
|
||||
|
||||
Output Format: [RTF - Format]
|
||||
Provide architecture diagram description, service definitions, and migration roadmap.
|
||||
## Behavioral Traits
|
||||
- Always displays complete prompt text, never just descriptions
|
||||
- Focuses on production reliability and safety over experimental techniques
|
||||
- Considers token efficiency and cost optimization in all prompt designs
|
||||
- Implements comprehensive testing and evaluation methodologies
|
||||
- Stays current with latest prompting research and techniques
|
||||
- Balances performance optimization with ethical considerations
|
||||
- Documents prompt behavior and provides clear usage guidelines
|
||||
- Iterates systematically based on empirical performance data
|
||||
- Considers model limitations and failure modes in prompt design
|
||||
- Emphasizes reproducibility and version control for prompt systems
|
||||
|
||||
Sense Check: [RODES - Sense check]
|
||||
Validate that services are loosely coupled, independently deployable, and aligned with business domains.
|
||||
## Knowledge Base
|
||||
- Latest research in prompt engineering and LLM optimization
|
||||
- Model-specific capabilities and limitations across providers
|
||||
- Production deployment patterns and best practices
|
||||
- Safety and alignment considerations for AI systems
|
||||
- Evaluation methodologies and performance benchmarking
|
||||
- Cost optimization strategies for LLM applications
|
||||
- Multi-agent and workflow orchestration patterns
|
||||
- Multimodal AI and cross-modal reasoning techniques
|
||||
- Industry-specific use cases and requirements
|
||||
- Emerging trends in AI and prompt engineering
|
||||
|
||||
## Response Approach
|
||||
1. **Understand the specific use case** and requirements for the prompt
|
||||
2. **Analyze target model capabilities** and optimization opportunities
|
||||
3. **Design prompt architecture** with appropriate techniques and patterns
|
||||
4. **Display the complete prompt text** in a clearly marked section
|
||||
5. **Provide usage guidelines** and parameter recommendations
|
||||
6. **Include evaluation criteria** and testing approaches
|
||||
7. **Document safety considerations** and potential failure modes
|
||||
8. **Suggest optimization strategies** for performance and cost
|
||||
|
||||
## Required Output Format
|
||||
|
||||
When creating any prompt, you MUST include:
|
||||
|
||||
### The Prompt
|
||||
```
|
||||
[Display the complete prompt text here - this is the most important part]
|
||||
```
|
||||
|
||||
**4.5. Language Adaptation**
|
||||
- If original prompt is in Portuguese, generate prompt in Portuguese
|
||||
- If original prompt is in English, generate prompt in English
|
||||
- If mixed, default to English (more universal for AI models)
|
||||
### Implementation Notes
|
||||
- Key techniques used and why they were chosen
|
||||
- Model-specific optimizations and considerations
|
||||
- Expected behavior and output format
|
||||
- Parameter recommendations (temperature, max tokens, etc.)
|
||||
|
||||
**4.6. Quality Checks**
|
||||
Before finalizing, verify:
|
||||
- [ ] Prompt is self-contained (no external context needed)
|
||||
- [ ] Task is specific and measurable
|
||||
- [ ] Output format is clear
|
||||
- [ ] No ambiguous language
|
||||
- [ ] Appropriate level of detail for task complexity
|
||||
### Testing & Evaluation
|
||||
- Suggested test cases and evaluation metrics
|
||||
- Edge cases and potential failure modes
|
||||
- A/B testing recommendations for optimization
|
||||
|
||||
### Usage Guidelines
|
||||
- When and how to use this prompt effectively
|
||||
- Customization options and variable parameters
|
||||
- Integration considerations for production systems
|
||||
|
||||
## Critical Rules
|
||||
## Example Interactions
|
||||
- "Create a constitutional AI prompt for content moderation that self-corrects problematic outputs"
|
||||
- "Design a chain-of-thought prompt for financial analysis that shows clear reasoning steps"
|
||||
- "Build a multi-agent prompt system for customer service with escalation workflows"
|
||||
- "Optimize a RAG prompt for technical documentation that reduces hallucinations"
|
||||
- "Create a meta-prompt that generates optimized prompts for specific business use cases"
|
||||
- "Design a safety-focused prompt for creative writing that maintains engagement while avoiding harm"
|
||||
- "Build a structured prompt for code review that provides actionable feedback"
|
||||
- "Create an evaluation framework for comparing prompt performance across different models"
|
||||
|
||||
### **NEVER:**
|
||||
## Before Completing Any Task
|
||||
|
||||
- ❌ Assume information that wasn't provided - ALWAYS ask if critical details are missing
|
||||
- ❌ Explain which framework was selected or why (magic mode - keep it invisible)
|
||||
- ❌ Generate generic, one-size-fits-all prompts - always customize to context
|
||||
- ❌ Use technical jargon in the final prompt (unless user's domain is technical)
|
||||
- ❌ Ask more than 3 clarifying questions (avoid user fatigue)
|
||||
- ❌ Include meta-commentary in the output ("This prompt uses...", "Note that...")
|
||||
- ❌ Present output without code block formatting
|
||||
- ❌ Mix languages inconsistently (if user writes in PT, respond in PT)
|
||||
Verify you have:
|
||||
☐ Displayed the full prompt text (not just described it)
|
||||
☐ Marked it clearly with headers or code blocks
|
||||
☐ Provided usage instructions and implementation notes
|
||||
☐ Explained your design choices and techniques used
|
||||
☐ Included testing and evaluation recommendations
|
||||
☐ Considered safety and ethical implications
|
||||
|
||||
### **ALWAYS:**
|
||||
|
||||
- ✅ Analyze intent before generating (Step 1 is mandatory)
|
||||
- ✅ Ask clarifying questions if critical information is ambiguous (Step 2 conditional)
|
||||
- ✅ Select framework(s) based on task type and complexity (Step 3 mapping)
|
||||
- ✅ Blend multiple frameworks when it improves prompt quality
|
||||
- ✅ Adapt prompt length to original input complexity (simple → short, complex → detailed)
|
||||
- ✅ Include output format specification in generated prompts
|
||||
- ✅ Present final prompt in clean Markdown code block
|
||||
- ✅ Make prompts self-contained (no dependency on external context)
|
||||
- ✅ Use examples in complex prompts to illustrate expected output
|
||||
- ✅ Validate prompt completeness before presenting (quality checks in Step 4.6)
|
||||
|
||||
|
||||
### **Example 2: Complex Clear Prompt → RODES + Chain of Thought (No Clarification)**
|
||||
|
||||
**User Input:**
|
||||
```
|
||||
copilot> create prompt for: I need to build a product recommendation system considering purchase history, user preferences, and market trends
|
||||
```
|
||||
|
||||
**Skill Internal Process:**
|
||||
1. **Analyze:** Clear intent, complex task (ML system design), technical domain
|
||||
2. **Clarify:** Skip (sufficient information)
|
||||
3. **Select:** RODES (complex design) + Chain of Thought (reasoning needed)
|
||||
|
||||
**Skill Output:**
|
||||
|
||||
````markdown
|
||||
```
|
||||
Role: You are a senior machine learning engineer specializing in recommendation systems.
|
||||
|
||||
Objective: Design a product recommendation system that combines user purchase history, preferences, and market trends.
|
||||
|
||||
Details:
|
||||
- Input data sources: user transaction logs, preference surveys, market trend APIs
|
||||
- Algorithm considerations: collaborative filtering, content-based filtering, hybrid approaches
|
||||
- Performance metrics: precision, recall, diversity, novelty
|
||||
- Scalability: system must handle 100k+ users
|
||||
- Real-time constraints: recommendations updated within 500ms
|
||||
|
||||
Approach step-by-step:
|
||||
1. Analyze the three data sources and their relationships
|
||||
2. Propose 2-3 algorithm approaches with trade-offs analysis
|
||||
3. Design data pipeline architecture (ingestion, processing, serving)
|
||||
4. Define evaluation metrics and A/B testing strategy
|
||||
5. Outline implementation roadmap with phases
|
||||
|
||||
Examples:
|
||||
- Show pseudocode for core recommendation logic
|
||||
- Illustrate data flow diagram
|
||||
- Provide sample API response structure
|
||||
|
||||
Sense Check: Validate that the proposed solution balances personalization with discovery, scales to production load, and incorporates real-time market trends effectively.
|
||||
|
||||
Output format: Technical design document with architecture diagrams, algorithm justification, and implementation roadmap.
|
||||
```
|
||||
````
|
||||
|
||||
|
||||
### **Example 4: Code Debugging → Chain of Thought**
|
||||
|
||||
**User Input:**
|
||||
```
|
||||
copilot> optimize prompt: my Python code isn't working, needs debugging
|
||||
```
|
||||
|
||||
**Skill Internal Process:**
|
||||
1. **Analyze:** Debugging task, needs step-by-step reasoning
|
||||
2. **Clarify:** Skip (user will provide code context later)
|
||||
3. **Select:** Chain of Thought
|
||||
|
||||
**Skill Output:**
|
||||
|
||||
````markdown
|
||||
```
|
||||
You are an expert Python debugger.
|
||||
|
||||
Task: Debug the Python code provided by the user by analyzing it step-by-step.
|
||||
|
||||
Debugging approach:
|
||||
1. Read and understand the code's intended purpose
|
||||
2. Identify the error or unexpected behavior
|
||||
3. Trace variable states at each execution step
|
||||
4. Locate the root cause of the issue
|
||||
5. Propose fix with explanation
|
||||
6. Suggest preventive measures to avoid similar bugs
|
||||
|
||||
For each step, show your reasoning:
|
||||
- What you're checking
|
||||
- What you found
|
||||
- Why it matters
|
||||
|
||||
Output format:
|
||||
- **Issue identified:** [Describe the bug]
|
||||
- **Root cause:** [Why it's happening]
|
||||
- **Fix:** [Corrected code with comments]
|
||||
- **Prevention:** [Best practices to avoid this in the future]
|
||||
|
||||
Include a working example to verify the fix.
|
||||
```
|
||||
````
|
||||
|
||||
|
||||
## Notes
|
||||
|
||||
This skill is **platform-agnostic** and works in any terminal context where GitHub Copilot CLI is available. It does not depend on:
|
||||
- Obsidian vault structure
|
||||
- Specific project configurations
|
||||
- External files or templates
|
||||
|
||||
The skill is entirely self-contained, operating purely on user input and framework knowledge.
|
||||
Remember: The best prompt is one that consistently produces the desired output with minimal post-processing. ALWAYS show the prompt, never just describe it.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: readme
|
||||
description: "When the user wants to create or update a README.md file for a project. Also use when the user says 'write readme,' 'create readme,' 'document this project,' 'project documentation,' or asks for help with README.md. This skill creates absurdly thorough documentation covering local setup, architecture, and deployment."
|
||||
description: "When the user wants to create or update a README.md file for a project. Also use when the user says "write readme," "create readme," "document this project," "project documentation," or asks for help with README.md. This skill creates absurdly thorough documentation covering local setup, architecture, and deployment."
|
||||
source: "https://github.com/Shpigford/skills/tree/main/readme"
|
||||
risk: safe
|
||||
---
|
||||
@@ -12,7 +12,6 @@ You are an expert technical writer creating comprehensive project documentation.
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
|
||||
- User wants to create or update a README.md file
|
||||
- User says "write readme" or "create readme"
|
||||
- User asks to "document this project"
|
||||
@@ -34,14 +33,12 @@ Use this skill when:
|
||||
Before writing a single line of documentation, thoroughly explore the codebase. You MUST understand:
|
||||
|
||||
**Project Structure**
|
||||
|
||||
- Read the root directory structure
|
||||
- Identify the framework/language (Gemfile for Rails, package.json, go.mod, requirements.txt, etc.)
|
||||
- Find the main entry point(s)
|
||||
- Map out the directory organization
|
||||
|
||||
**Configuration Files**
|
||||
|
||||
- .env.example, .env.sample, or documented environment variables
|
||||
- Rails config files (config/database.yml, config/application.rb, config/environments/)
|
||||
- Credentials setup (config/credentials.yml.enc, config/master.key)
|
||||
@@ -50,20 +47,17 @@ Before writing a single line of documentation, thoroughly explore the codebase.
|
||||
- Deployment configs (config/deploy.yml for Kamal, fly.toml, render.yaml, Procfile, etc.)
|
||||
|
||||
**Database**
|
||||
|
||||
- db/schema.rb or db/structure.sql
|
||||
- Migrations in db/migrate/
|
||||
- Seeds in db/seeds.rb
|
||||
- Database type from config/database.yml
|
||||
|
||||
**Key Dependencies**
|
||||
|
||||
- Gemfile and Gemfile.lock for Ruby gems
|
||||
- package.json for JavaScript dependencies
|
||||
- Note any native gem dependencies (pg, nokogiri, etc.)
|
||||
|
||||
**Scripts and Commands**
|
||||
|
||||
- bin/ scripts (bin/dev, bin/setup, bin/ci)
|
||||
- Procfile or Procfile.dev
|
||||
- Rake tasks (lib/tasks/)
|
||||
@@ -90,7 +84,6 @@ If no deployment config exists, provide general guidance with Docker as the reco
|
||||
### Step 3: Ask Only If Critical
|
||||
|
||||
Only ask the user questions if you cannot determine:
|
||||
|
||||
- What the project does (if not obvious from code)
|
||||
- Specific deployment credentials or URLs needed
|
||||
- Business context that affects documentation
|
||||
@@ -185,12 +178,12 @@ cp .env.example .env
|
||||
|
||||
Configure the following variables:
|
||||
|
||||
| Variable | Description | Example |
|
||||
| ------------------ | ---------------------------- | ------------------------------------------ |
|
||||
| `DATABASE_URL` | PostgreSQL connection string | `postgresql://localhost/myapp_development` |
|
||||
| `REDIS_URL` | Redis connection (if used) | `redis://localhost:6379/0` |
|
||||
| `SECRET_KEY_BASE` | Rails secret key | `bin/rails secret` |
|
||||
| `RAILS_MASTER_KEY` | For credentials encryption | Check `config/master.key` |
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `DATABASE_URL` | PostgreSQL connection string | `postgresql://localhost/myapp_development` |
|
||||
| `REDIS_URL` | Redis connection (if used) | `redis://localhost:6379/0` |
|
||||
| `SECRET_KEY_BASE` | Rails secret key | `bin/rails secret` |
|
||||
| `RAILS_MASTER_KEY` | For credentials encryption | Check `config/master.key` |
|
||||
|
||||
### 5. Database Setup
|
||||
|
||||
@@ -225,13 +218,10 @@ bin/dev
|
||||
Or manually:
|
||||
|
||||
\`\`\`bash
|
||||
|
||||
# Terminal 1: Rails server
|
||||
|
||||
bin/rails server
|
||||
|
||||
# Terminal 2: Vite dev server (for Inertia/React)
|
||||
|
||||
bin/vite dev
|
||||
\`\`\`
|
||||
|
||||
@@ -251,30 +241,30 @@ This is where you go absurdly deep:
|
||||
|
||||
\`\`\`
|
||||
├── app/
|
||||
│ ├── controllers/ # Rails controllers
|
||||
│ │ ├── concerns/ # Shared controller modules
|
||||
│ │ └── api/ # API-specific controllers
|
||||
│ ├── models/ # ActiveRecord models
|
||||
│ │ └── concerns/ # Shared model modules
|
||||
│ ├── jobs/ # Background jobs (Solid Queue)
|
||||
│ ├── mailers/ # Email templates
|
||||
│ ├── views/ # Rails views (minimal with Inertia)
|
||||
│ └── frontend/ # Inertia.js React components
|
||||
│ ├── components/ # Reusable UI components
|
||||
│ ├── layouts/ # Page layouts
|
||||
│ ├── pages/ # Inertia page components
|
||||
│ └── lib/ # Frontend utilities
|
||||
│ ├── controllers/ # Rails controllers
|
||||
│ │ ├── concerns/ # Shared controller modules
|
||||
│ │ └── api/ # API-specific controllers
|
||||
│ ├── models/ # ActiveRecord models
|
||||
│ │ └── concerns/ # Shared model modules
|
||||
│ ├── jobs/ # Background jobs (Solid Queue)
|
||||
│ ├── mailers/ # Email templates
|
||||
│ ├── views/ # Rails views (minimal with Inertia)
|
||||
│ └── frontend/ # Inertia.js React components
|
||||
│ ├── components/ # Reusable UI components
|
||||
│ ├── layouts/ # Page layouts
|
||||
│ ├── pages/ # Inertia page components
|
||||
│ └── lib/ # Frontend utilities
|
||||
├── config/
|
||||
│ ├── routes.rb # Route definitions
|
||||
│ ├── database.yml # Database configuration
|
||||
│ └── initializers/ # App initializers
|
||||
│ ├── routes.rb # Route definitions
|
||||
│ ├── database.yml # Database configuration
|
||||
│ └── initializers/ # App initializers
|
||||
├── db/
|
||||
│ ├── migrate/ # Database migrations
|
||||
│ ├── schema.rb # Current schema
|
||||
│ └── seeds.rb # Seed data
|
||||
│ ├── migrate/ # Database migrations
|
||||
│ ├── schema.rb # Current schema
|
||||
│ └── seeds.rb # Seed data
|
||||
├── lib/
|
||||
│ └── tasks/ # Custom Rake tasks
|
||||
└── public/ # Static assets
|
||||
│ └── tasks/ # Custom Rake tasks
|
||||
└── public/ # Static assets
|
||||
\`\`\`
|
||||
|
||||
### Request Lifecycle
|
||||
@@ -290,32 +280,28 @@ This is where you go absurdly deep:
|
||||
|
||||
\`\`\`
|
||||
User Action → React Component → Inertia Visit → Rails Controller → ActiveRecord → PostgreSQL
|
||||
↓
|
||||
React Props ← Inertia Response ←
|
||||
↓
|
||||
React Props ← Inertia Response ←
|
||||
\`\`\`
|
||||
|
||||
### Key Components
|
||||
|
||||
**Authentication**
|
||||
|
||||
- Devise/Rodauth for user authentication
|
||||
- Session-based auth with encrypted cookies
|
||||
- `authenticate_user!` before_action for protected routes
|
||||
|
||||
**Inertia.js Integration (`app/frontend/`)**
|
||||
|
||||
- React components receive props from Rails controllers
|
||||
- `inertia_render` in controllers passes data to frontend
|
||||
- Shared data via `inertia_share` for layout props
|
||||
|
||||
**Background Jobs (`app/jobs/`)**
|
||||
|
||||
- Solid Queue for job processing
|
||||
- Jobs stored in PostgreSQL (no Redis required)
|
||||
- Dashboard at `/jobs` for monitoring
|
||||
|
||||
**Database (`app/models/`)**
|
||||
|
||||
- ActiveRecord models with associations
|
||||
- Query objects for complex queries
|
||||
- Concerns for shared model behavior
|
||||
@@ -359,35 +345,32 @@ Complete reference for all env vars:
|
||||
|
||||
### Required
|
||||
|
||||
| Variable | Description | How to Get |
|
||||
| ------------------ | --------------------------------- | -------------------------------------- |
|
||||
| `DATABASE_URL` | PostgreSQL connection string | Your database provider |
|
||||
| `SECRET_KEY_BASE` | Rails secret for sessions/cookies | Run `bin/rails secret` |
|
||||
| `RAILS_MASTER_KEY` | Decrypts credentials file | Check `config/master.key` (not in git) |
|
||||
| Variable | Description | How to Get |
|
||||
|----------|-------------|------------|
|
||||
| `DATABASE_URL` | PostgreSQL connection string | Your database provider |
|
||||
| `SECRET_KEY_BASE` | Rails secret for sessions/cookies | Run `bin/rails secret` |
|
||||
| `RAILS_MASTER_KEY` | Decrypts credentials file | Check `config/master.key` (not in git) |
|
||||
|
||||
### Optional
|
||||
|
||||
| Variable | Description | Default |
|
||||
| ------------------- | ------------------------------------------------- | ---------------------------- |
|
||||
| `REDIS_URL` | Redis connection string (for caching/ActionCable) | - |
|
||||
| `RAILS_LOG_LEVEL` | Logging verbosity | `debug` (dev), `info` (prod) |
|
||||
| `RAILS_MAX_THREADS` | Puma thread count | `5` |
|
||||
| `WEB_CONCURRENCY` | Puma worker count | `2` |
|
||||
| `SMTP_ADDRESS` | Mail server hostname | - |
|
||||
| `SMTP_PORT` | Mail server port | `587` |
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `REDIS_URL` | Redis connection string (for caching/ActionCable) | - |
|
||||
| `RAILS_LOG_LEVEL` | Logging verbosity | `debug` (dev), `info` (prod) |
|
||||
| `RAILS_MAX_THREADS` | Puma thread count | `5` |
|
||||
| `WEB_CONCURRENCY` | Puma worker count | `2` |
|
||||
| `SMTP_ADDRESS` | Mail server hostname | - |
|
||||
| `SMTP_PORT` | Mail server port | `587` |
|
||||
|
||||
### Rails Credentials
|
||||
|
||||
Sensitive values should be stored in Rails encrypted credentials:
|
||||
|
||||
\`\`\`bash
|
||||
|
||||
# Edit credentials (opens in $EDITOR)
|
||||
|
||||
bin/rails credentials:edit
|
||||
|
||||
# Or for environment-specific credentials
|
||||
|
||||
RAILS_ENV=production bin/rails credentials:edit
|
||||
\`\`\`
|
||||
|
||||
@@ -395,11 +378,11 @@ Credentials file structure:
|
||||
\`\`\`yaml
|
||||
secret_key_base: xxx
|
||||
stripe:
|
||||
public_key: pk_xxx
|
||||
secret_key: sk_xxx
|
||||
public_key: pk_xxx
|
||||
secret_key: sk_xxx
|
||||
google:
|
||||
client_id: xxx
|
||||
client_secret: xxx
|
||||
client_id: xxx
|
||||
client_secret: xxx
|
||||
\`\`\`
|
||||
|
||||
Access in code: `Rails.application.credentials.stripe[:secret_key]`
|
||||
@@ -425,22 +408,22 @@ RAILS_SERVE_STATIC_FILES=true
|
||||
```markdown
|
||||
## Available Scripts
|
||||
|
||||
| Command | Description |
|
||||
| ----------------------------- | --------------------------------------------------- |
|
||||
| `bin/dev` | Start development server (Rails + Vite via Foreman) |
|
||||
| `bin/rails server` | Start Rails server only |
|
||||
| `bin/vite dev` | Start Vite dev server only |
|
||||
| `bin/rails console` | Open Rails console (IRB with app loaded) |
|
||||
| `bin/rails db:migrate` | Run pending database migrations |
|
||||
| `bin/rails db:rollback` | Rollback last migration |
|
||||
| `bin/rails db:seed` | Run database seeds |
|
||||
| `bin/rails db:reset` | Drop, create, migrate, and seed database |
|
||||
| `bin/rails routes` | List all routes |
|
||||
| `bin/rails test` | Run test suite (Minitest) |
|
||||
| `bundle exec rspec` | Run test suite (RSpec, if used) |
|
||||
| `bin/rails assets:precompile` | Compile assets for production |
|
||||
| `bin/rubocop` | Run Ruby linter |
|
||||
| `yarn lint` | Run JavaScript/TypeScript linter |
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `bin/dev` | Start development server (Rails + Vite via Foreman) |
|
||||
| `bin/rails server` | Start Rails server only |
|
||||
| `bin/vite dev` | Start Vite dev server only |
|
||||
| `bin/rails console` | Open Rails console (IRB with app loaded) |
|
||||
| `bin/rails db:migrate` | Run pending database migrations |
|
||||
| `bin/rails db:rollback` | Rollback last migration |
|
||||
| `bin/rails db:seed` | Run database seeds |
|
||||
| `bin/rails db:reset` | Drop, create, migrate, and seed database |
|
||||
| `bin/rails routes` | List all routes |
|
||||
| `bin/rails test` | Run test suite (Minitest) |
|
||||
| `bundle exec rspec` | Run test suite (RSpec, if used) |
|
||||
| `bin/rails assets:precompile` | Compile assets for production |
|
||||
| `bin/rubocop` | Run Ruby linter |
|
||||
| `yarn lint` | Run JavaScript/TypeScript linter |
|
||||
```
|
||||
|
||||
### 8. Testing
|
||||
@@ -451,50 +434,43 @@ RAILS_SERVE_STATIC_FILES=true
|
||||
### Running Tests
|
||||
|
||||
\`\`\`bash
|
||||
|
||||
# Run all tests (Minitest)
|
||||
|
||||
bin/rails test
|
||||
|
||||
# Run all tests (RSpec, if used)
|
||||
|
||||
bundle exec rspec
|
||||
|
||||
# Run specific test file
|
||||
|
||||
bin/rails test test/models/user_test.rb
|
||||
bundle exec rspec spec/models/user_spec.rb
|
||||
|
||||
# Run tests matching a pattern
|
||||
|
||||
bin/rails test -n /creates_user/
|
||||
bundle exec rspec -e "creates user"
|
||||
|
||||
# Run system tests (browser tests)
|
||||
|
||||
bin/rails test:system
|
||||
|
||||
# Run with coverage (SimpleCov)
|
||||
|
||||
COVERAGE=true bin/rails test
|
||||
\`\`\`
|
||||
|
||||
### Test Structure
|
||||
|
||||
\`\`\`
|
||||
test/ # Minitest structure
|
||||
├── controllers/ # Controller tests
|
||||
├── models/ # Model unit tests
|
||||
├── integration/ # Integration tests
|
||||
├── system/ # System/browser tests
|
||||
├── fixtures/ # Test data
|
||||
└── test_helper.rb # Test configuration
|
||||
test/ # Minitest structure
|
||||
├── controllers/ # Controller tests
|
||||
├── models/ # Model unit tests
|
||||
├── integration/ # Integration tests
|
||||
├── system/ # System/browser tests
|
||||
├── fixtures/ # Test data
|
||||
└── test_helper.rb # Test configuration
|
||||
|
||||
spec/ # RSpec structure (if used)
|
||||
spec/ # RSpec structure (if used)
|
||||
├── models/
|
||||
├── requests/
|
||||
├── system/
|
||||
├── factories/ # FactoryBot factories
|
||||
├── factories/ # FactoryBot factories
|
||||
├── support/
|
||||
└── rails_helper.rb
|
||||
\`\`\`
|
||||
@@ -506,16 +482,16 @@ spec/ # RSpec structure (if used)
|
||||
require "test_helper"
|
||||
|
||||
class UserTest < ActiveSupport::TestCase
|
||||
test "creates user with valid attributes" do
|
||||
user = User.new(email: "test@example.com", name: "Test User")
|
||||
assert user.valid?
|
||||
end
|
||||
test "creates user with valid attributes" do
|
||||
user = User.new(email: "test@example.com", name: "Test User")
|
||||
assert user.valid?
|
||||
end
|
||||
|
||||
test "requires email" do
|
||||
user = User.new(name: "Test User")
|
||||
assert_not user.valid?
|
||||
assert_includes user.errors[:email], "can't be blank"
|
||||
end
|
||||
test "requires email" do
|
||||
user = User.new(name: "Test User")
|
||||
assert_not user.valid?
|
||||
assert_includes user.errors[:email], "can't be blank"
|
||||
end
|
||||
end
|
||||
\`\`\`
|
||||
|
||||
@@ -524,19 +500,18 @@ end
|
||||
require "rails_helper"
|
||||
|
||||
RSpec.describe User, type: :model do
|
||||
describe "validations" do
|
||||
it "is valid with valid attributes" do
|
||||
user = build(:user)
|
||||
expect(user).to be_valid
|
||||
end
|
||||
describe "validations" do
|
||||
it "is valid with valid attributes" do
|
||||
user = build(:user)
|
||||
expect(user).to be_valid
|
||||
end
|
||||
|
||||
it "requires an email" do
|
||||
user = build(:user, email: nil)
|
||||
expect(user).not_to be_valid
|
||||
expect(user.errors[:email]).to include("can't be blank")
|
||||
end
|
||||
|
||||
end
|
||||
end
|
||||
end
|
||||
\`\`\`
|
||||
|
||||
@@ -553,10 +528,10 @@ import { render, screen } from '@testing-library/react'
|
||||
import { Dashboard } from './Dashboard'
|
||||
|
||||
describe('Dashboard', () => {
|
||||
it('renders user name', () => {
|
||||
render(<Dashboard user={{ name: 'Josh' }} />)
|
||||
expect(screen.getByText('Josh')).toBeInTheDocument()
|
||||
})
|
||||
it('renders user name', () => {
|
||||
render(<Dashboard user={{ name: 'Josh' }} />)
|
||||
expect(screen.getByText('Josh')).toBeInTheDocument()
|
||||
})
|
||||
})
|
||||
\`\`\`
|
||||
```
|
||||
@@ -573,25 +548,19 @@ Tailor this to detected platform (look for Dockerfile, fly.toml, render.yaml, ka
|
||||
If using Kamal for deployment:
|
||||
|
||||
\`\`\`bash
|
||||
|
||||
# Setup Kamal (first time)
|
||||
|
||||
kamal setup
|
||||
|
||||
# Deploy
|
||||
|
||||
kamal deploy
|
||||
|
||||
# Rollback to previous version
|
||||
|
||||
kamal rollback
|
||||
|
||||
# View logs
|
||||
|
||||
kamal app logs
|
||||
|
||||
# Run console on production
|
||||
|
||||
kamal app exec --interactive 'bin/rails console'
|
||||
\`\`\`
|
||||
|
||||
@@ -602,64 +571,50 @@ Configuration lives in `config/deploy.yml`.
|
||||
Build and run:
|
||||
|
||||
\`\`\`bash
|
||||
|
||||
# Build image
|
||||
|
||||
docker build -t myapp .
|
||||
|
||||
# Run with environment variables
|
||||
|
||||
docker run -p 3000:3000 \
|
||||
-e DATABASE_URL=postgresql://... \
|
||||
-e SECRET_KEY_BASE=... \
|
||||
-e RAILS_ENV=production \
|
||||
myapp
|
||||
-e DATABASE_URL=postgresql://... \
|
||||
-e SECRET_KEY_BASE=... \
|
||||
-e RAILS_ENV=production \
|
||||
myapp
|
||||
\`\`\`
|
||||
|
||||
### Heroku
|
||||
|
||||
\`\`\`bash
|
||||
|
||||
# Create app
|
||||
|
||||
heroku create myapp
|
||||
|
||||
# Add PostgreSQL
|
||||
|
||||
heroku addons:create heroku-postgresql:mini
|
||||
|
||||
# Set environment variables
|
||||
|
||||
heroku config:set SECRET_KEY_BASE=$(bin/rails secret)
|
||||
heroku config:set RAILS_MASTER_KEY=$(cat config/master.key)
|
||||
|
||||
# Deploy
|
||||
|
||||
git push heroku main
|
||||
|
||||
# Run migrations
|
||||
|
||||
heroku run bin/rails db:migrate
|
||||
\`\`\`
|
||||
|
||||
### Fly.io
|
||||
|
||||
\`\`\`bash
|
||||
|
||||
# Launch (first time)
|
||||
|
||||
fly launch
|
||||
|
||||
# Deploy
|
||||
|
||||
fly deploy
|
||||
|
||||
# Run migrations
|
||||
|
||||
fly ssh console -C "bin/rails db:migrate"
|
||||
|
||||
# Open console
|
||||
|
||||
fly ssh console -C "bin/rails console"
|
||||
\`\`\`
|
||||
|
||||
@@ -668,7 +623,6 @@ fly ssh console -C "bin/rails console"
|
||||
If `render.yaml` exists, connect your repo to Render and it will auto-deploy.
|
||||
|
||||
Manual setup:
|
||||
|
||||
1. Create new Web Service
|
||||
2. Connect GitHub repository
|
||||
3. Set build command: `bundle install && bin/rails assets:precompile`
|
||||
@@ -678,27 +632,21 @@ Manual setup:
|
||||
### Manual/VPS Deployment
|
||||
|
||||
\`\`\`bash
|
||||
|
||||
# On the server:
|
||||
|
||||
# Pull latest code
|
||||
|
||||
git pull origin main
|
||||
|
||||
# Install dependencies
|
||||
|
||||
bundle install --deployment
|
||||
|
||||
# Compile assets
|
||||
|
||||
RAILS_ENV=production bin/rails assets:precompile
|
||||
|
||||
# Run migrations
|
||||
|
||||
RAILS_ENV=production bin/rails db:migrate
|
||||
|
||||
# Restart application server (e.g., Puma via systemd)
|
||||
|
||||
sudo systemctl restart myapp
|
||||
\`\`\`
|
||||
```
|
||||
@@ -713,7 +661,6 @@ sudo systemctl restart myapp
|
||||
**Error:** `could not connect to server: Connection refused`
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Verify PostgreSQL is running: `pg_isready` or `docker ps`
|
||||
2. Check `DATABASE_URL` format: `postgresql://USER:PASSWORD@HOST:PORT/DATABASE`
|
||||
3. Ensure database exists: `bin/rails db:create`
|
||||
@@ -733,9 +680,7 @@ bin/rails db:migrate
|
||||
|
||||
**Solution:**
|
||||
\`\`\`bash
|
||||
|
||||
# Clear and recompile assets
|
||||
|
||||
bin/rails assets:clobber
|
||||
bin/rails assets:precompile
|
||||
\`\`\`
|
||||
@@ -745,19 +690,14 @@ bin/rails assets:precompile
|
||||
**Error:** Native extension build failures
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Ensure system dependencies are installed:
|
||||
\`\`\`bash
|
||||
|
||||
# macOS
|
||||
|
||||
brew install postgresql libpq
|
||||
|
||||
# Ubuntu
|
||||
|
||||
sudo apt-get install libpq-dev
|
||||
\`\`\`
|
||||
|
||||
2. Try again: `bundle install`
|
||||
|
||||
### Credentials Issues
|
||||
@@ -766,7 +706,6 @@ bin/rails assets:precompile
|
||||
|
||||
**Solution:**
|
||||
The master key doesn't match the credentials file. Either:
|
||||
|
||||
1. Get the correct `config/master.key` from another team member
|
||||
2. Or regenerate credentials: `rm config/credentials.yml.enc && bin/rails credentials:edit`
|
||||
|
||||
@@ -776,13 +715,10 @@ The master key doesn't match the credentials file. Either:
|
||||
|
||||
**Solution:**
|
||||
\`\`\`bash
|
||||
|
||||
# Clear Vite cache
|
||||
|
||||
rm -rf node_modules/.vite
|
||||
|
||||
# Reinstall JS dependencies
|
||||
|
||||
rm -rf node_modules && yarn install
|
||||
\`\`\`
|
||||
|
||||
@@ -794,9 +730,7 @@ rm -rf node_modules && yarn install
|
||||
Ensure the queue worker is running:
|
||||
\`\`\`bash
|
||||
bin/jobs
|
||||
|
||||
# or
|
||||
|
||||
bin/rails solid_queue:start
|
||||
\`\`\`
|
||||
```
|
||||
@@ -832,9 +766,8 @@ Include if open source or team project.
|
||||
## Output Format
|
||||
|
||||
Generate a complete README.md file with:
|
||||
|
||||
- Proper markdown formatting
|
||||
- Code blocks with language hints (`bash, `typescript, etc.)
|
||||
- Code blocks with language hints (```bash, ```typescript, etc.)
|
||||
- Tables where appropriate
|
||||
- Clear section hierarchy
|
||||
- Linked table of contents for long documents
|
||||
|
||||
@@ -1,212 +0,0 @@
|
||||
---
|
||||
name: reddit-automation
|
||||
description: "Automate Reddit tasks via Rube MCP (Composio): search subreddits, create posts, manage comments, and browse top content. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Reddit Automation via Rube MCP
|
||||
|
||||
Automate Reddit operations through Composio's Reddit toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Reddit connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `reddit`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `reddit`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Reddit OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Search Reddit
|
||||
|
||||
**When to use**: User wants to find posts across subreddits
|
||||
|
||||
**Tool sequence**:
|
||||
1. `REDDIT_SEARCH_ACROSS_SUBREDDITS` - Search for posts matching a query [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: Search terms
|
||||
- `subreddit`: Limit search to a specific subreddit (optional)
|
||||
- `sort`: Sort results by 'relevance', 'hot', 'top', 'new', 'comments'
|
||||
- `time_filter`: Time range ('hour', 'day', 'week', 'month', 'year', 'all')
|
||||
- `limit`: Number of results to return
|
||||
|
||||
**Pitfalls**:
|
||||
- Search results may not include very recent posts due to indexing delay
|
||||
- The `time_filter` parameter only works with certain sort options
|
||||
- Results are paginated; use after/before tokens for additional pages
|
||||
- NSFW content may be filtered based on account settings
|
||||
|
||||
### 2. Create Posts
|
||||
|
||||
**When to use**: User wants to submit a new post to a subreddit
|
||||
|
||||
**Tool sequence**:
|
||||
1. `REDDIT_LIST_SUBREDDIT_POST_FLAIRS` - Get available post flairs [Optional]
|
||||
2. `REDDIT_CREATE_REDDIT_POST` - Submit the post [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `subreddit`: Target subreddit name (without 'r/' prefix)
|
||||
- `title`: Post title
|
||||
- `text`: Post body text (for text posts)
|
||||
- `url`: Link URL (for link posts)
|
||||
- `flair_id`: Flair ID from the subreddit's flair list
|
||||
|
||||
**Pitfalls**:
|
||||
- Some subreddits require flair; use LIST_SUBREDDIT_POST_FLAIRS first
|
||||
- Subreddit posting rules vary widely; karma/age restrictions may apply
|
||||
- Text and URL are mutually exclusive; a post is either text or link
|
||||
- Rate limits apply; avoid rapid successive post creation
|
||||
- The subreddit name should not include 'r/' prefix
|
||||
|
||||
### 3. Manage Comments
|
||||
|
||||
**When to use**: User wants to comment on posts or manage existing comments
|
||||
|
||||
**Tool sequence**:
|
||||
1. `REDDIT_RETRIEVE_POST_COMMENTS` - Get comments on a post [Optional]
|
||||
2. `REDDIT_POST_REDDIT_COMMENT` - Add a comment to a post or reply to a comment [Required]
|
||||
3. `REDDIT_EDIT_REDDIT_COMMENT_OR_POST` - Edit an existing comment [Optional]
|
||||
4. `REDDIT_DELETE_REDDIT_COMMENT` - Delete a comment [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `post_id`: ID of the post (for retrieving or commenting on)
|
||||
- `parent_id`: Full name of the parent (e.g., 't3_abc123' for post, 't1_xyz789' for comment)
|
||||
- `body`: Comment text content
|
||||
- `thing_id`: Full name of the item to edit or delete
|
||||
|
||||
**Pitfalls**:
|
||||
- Reddit uses 'fullname' format: 't1_' prefix for comments, 't3_' for posts
|
||||
- Editing replaces the entire comment body; include all desired content
|
||||
- Deleted comments show as '[deleted]' but the tree structure remains
|
||||
- Comment depth limits may apply in some subreddits
|
||||
|
||||
### 4. Browse Subreddit Content
|
||||
|
||||
**When to use**: User wants to view top or trending content from a subreddit
|
||||
|
||||
**Tool sequence**:
|
||||
1. `REDDIT_GET_R_TOP` - Get top posts from a subreddit [Required]
|
||||
2. `REDDIT_GET` - Get posts from a subreddit endpoint [Alternative]
|
||||
3. `REDDIT_RETRIEVE_REDDIT_POST` - Get full details for a specific post [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `subreddit`: Subreddit name
|
||||
- `time_filter`: Time range for top posts ('hour', 'day', 'week', 'month', 'year', 'all')
|
||||
- `limit`: Number of posts to retrieve
|
||||
- `post_id`: Specific post ID for full details
|
||||
|
||||
**Pitfalls**:
|
||||
- Top posts with time_filter='all' returns all-time top content
|
||||
- Post details include the body text but comments require a separate call
|
||||
- Some posts may be removed or hidden based on subreddit rules
|
||||
- NSFW posts are included unless filtered at the account level
|
||||
|
||||
### 5. Manage Posts
|
||||
|
||||
**When to use**: User wants to edit or delete their own posts
|
||||
|
||||
**Tool sequence**:
|
||||
1. `REDDIT_EDIT_REDDIT_COMMENT_OR_POST` - Edit a post's text content [Optional]
|
||||
2. `REDDIT_DELETE_REDDIT_POST` - Delete a post [Optional]
|
||||
3. `REDDIT_GET_USER_FLAIR` - Get user's flair in a subreddit [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `thing_id`: Full name of the post (e.g., 't3_abc123')
|
||||
- `body`: New text content (for editing)
|
||||
- `subreddit`: Subreddit name (for flair)
|
||||
|
||||
**Pitfalls**:
|
||||
- Only text posts can have their body edited; link posts cannot be modified
|
||||
- Post titles cannot be edited after submission
|
||||
- Deletion is permanent; deleted posts show as '[deleted]'
|
||||
- User flair is per-subreddit and may be restricted
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Reddit Fullname Format
|
||||
|
||||
**Prefixes**:
|
||||
```
|
||||
t1_ = Comment (e.g., 't1_abc123')
|
||||
t2_ = Account (e.g., 't2_xyz789')
|
||||
t3_ = Post/Link (e.g., 't3_def456')
|
||||
t4_ = Message
|
||||
t5_ = Subreddit
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```
|
||||
1. Retrieve a post to get its fullname (t3_XXXXX)
|
||||
2. Use fullname as parent_id when commenting
|
||||
3. Use fullname as thing_id when editing/deleting
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Reddit uses cursor-based pagination with 'after' and 'before' tokens
|
||||
- Set `limit` for items per page (max 100)
|
||||
- Check response for `after` token
|
||||
- Pass `after` value in subsequent requests to get next page
|
||||
|
||||
### Flair Resolution
|
||||
|
||||
```
|
||||
1. Call REDDIT_LIST_SUBREDDIT_POST_FLAIRS with subreddit name
|
||||
2. Find matching flair by text or category
|
||||
3. Extract flair_id
|
||||
4. Include flair_id when creating the post
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Rate Limits**:
|
||||
- Reddit enforces rate limits per account and per OAuth app
|
||||
- Posting is limited to approximately 1 post per 10 minutes for new accounts
|
||||
- Commenting has similar but less restrictive limits
|
||||
- 429 errors should trigger exponential backoff
|
||||
|
||||
**Content Rules**:
|
||||
- Each subreddit has its own posting rules and requirements
|
||||
- Some subreddits are restricted or private
|
||||
- Karma requirements may prevent posting in certain subreddits
|
||||
- Auto-moderator rules may remove posts that match certain patterns
|
||||
|
||||
**ID Formats**:
|
||||
- Always use fullname format (with prefix) for parent_id and thing_id
|
||||
- Raw IDs without prefix will cause 'Invalid ID' errors
|
||||
- Post IDs from search results may need 't3_' prefix added
|
||||
|
||||
**Text Formatting**:
|
||||
- Reddit uses Markdown for post and comment formatting
|
||||
- Code blocks, tables, and headers are supported
|
||||
- Links use `[text](url)` format
|
||||
- Mention users with `u/username`, subreddits with `r/subreddit`
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Search Reddit | REDDIT_SEARCH_ACROSS_SUBREDDITS | query, subreddit, sort, time_filter |
|
||||
| Create post | REDDIT_CREATE_REDDIT_POST | subreddit, title, text/url |
|
||||
| Get post comments | REDDIT_RETRIEVE_POST_COMMENTS | post_id |
|
||||
| Add comment | REDDIT_POST_REDDIT_COMMENT | parent_id, body |
|
||||
| Edit comment/post | REDDIT_EDIT_REDDIT_COMMENT_OR_POST | thing_id, body |
|
||||
| Delete comment | REDDIT_DELETE_REDDIT_COMMENT | thing_id |
|
||||
| Delete post | REDDIT_DELETE_REDDIT_POST | thing_id |
|
||||
| Get top posts | REDDIT_GET_R_TOP | subreddit, time_filter, limit |
|
||||
| Browse subreddit | REDDIT_GET | subreddit |
|
||||
| Get post details | REDDIT_RETRIEVE_REDDIT_POST | post_id |
|
||||
| Get specific comment | REDDIT_RETRIEVE_SPECIFIC_COMMENT | comment_id |
|
||||
| List post flairs | REDDIT_LIST_SUBREDDIT_POST_FLAIRS | subreddit |
|
||||
| Get user flair | REDDIT_GET_USER_FLAIR | subreddit |
|
||||
@@ -1,181 +0,0 @@
|
||||
---
|
||||
name: render-automation
|
||||
description: "Automate Render tasks via Rube MCP (Composio): services, deployments, projects. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Render Automation via Rube MCP
|
||||
|
||||
Automate Render cloud platform operations through Composio's Render toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Render connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `render`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `render`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Render authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. List and Browse Services
|
||||
|
||||
**When to use**: User wants to find or inspect Render services (web services, static sites, workers, cron jobs)
|
||||
|
||||
**Tool sequence**:
|
||||
1. `RENDER_LIST_SERVICES` - List all services with optional filters [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Filter services by name substring
|
||||
- `type`: Filter by service type ('web_service', 'static_site', 'private_service', 'background_worker', 'cron_job')
|
||||
- `limit`: Maximum results per page (default 20, max 100)
|
||||
- `cursor`: Pagination cursor from previous response
|
||||
|
||||
**Pitfalls**:
|
||||
- Service types must match exact enum values: 'web_service', 'static_site', 'private_service', 'background_worker', 'cron_job'
|
||||
- Pagination uses cursor-based approach; follow `cursor` until absent
|
||||
- Name filter is substring-based, not exact match
|
||||
- Service IDs follow the format 'srv-xxxxxxxxxxxx'
|
||||
- Default limit is 20; set higher for comprehensive listing
|
||||
|
||||
### 2. Trigger Deployments
|
||||
|
||||
**When to use**: User wants to manually deploy or redeploy a service
|
||||
|
||||
**Tool sequence**:
|
||||
1. `RENDER_LIST_SERVICES` - Find the service to deploy [Prerequisite]
|
||||
2. `RENDER_TRIGGER_DEPLOY` - Trigger a new deployment [Required]
|
||||
3. `RENDER_RETRIEVE_DEPLOY` - Monitor deployment progress [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- For TRIGGER_DEPLOY:
|
||||
- `serviceId`: Service ID to deploy (required, format: 'srv-xxxxxxxxxxxx')
|
||||
- `clearCache`: Set `true` to clear build cache before deploying
|
||||
- For RETRIEVE_DEPLOY:
|
||||
- `serviceId`: Service ID
|
||||
- `deployId`: Deploy ID from trigger response (format: 'dep-xxxxxxxxxxxx')
|
||||
|
||||
**Pitfalls**:
|
||||
- `serviceId` is required; resolve via LIST_SERVICES first
|
||||
- Service IDs start with 'srv-' prefix
|
||||
- Deploy IDs start with 'dep-' prefix
|
||||
- `clearCache: true` forces a clean build; takes longer but resolves cache-related issues
|
||||
- Deployment is asynchronous; use RETRIEVE_DEPLOY to poll status
|
||||
- Triggering a deploy while another is in progress may queue the new one
|
||||
|
||||
### 3. Monitor Deployment Status
|
||||
|
||||
**When to use**: User wants to check the progress or result of a deployment
|
||||
|
||||
**Tool sequence**:
|
||||
1. `RENDER_RETRIEVE_DEPLOY` - Get deployment details and status [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `serviceId`: Service ID (required)
|
||||
- `deployId`: Deployment ID (required)
|
||||
- Response includes `status`, `createdAt`, `updatedAt`, `finishedAt`, `commit`
|
||||
|
||||
**Pitfalls**:
|
||||
- Both `serviceId` and `deployId` are required
|
||||
- Deploy statuses include: 'created', 'build_in_progress', 'update_in_progress', 'live', 'deactivated', 'build_failed', 'update_failed', 'canceled'
|
||||
- 'live' indicates successful deployment
|
||||
- 'build_failed' or 'update_failed' indicate deployment errors
|
||||
- Poll at reasonable intervals (10-30 seconds) to avoid rate limits
|
||||
|
||||
### 4. Manage Projects
|
||||
|
||||
**When to use**: User wants to list and organize Render projects
|
||||
|
||||
**Tool sequence**:
|
||||
1. `RENDER_LIST_PROJECTS` - List all projects [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `limit`: Maximum results per page (max 100)
|
||||
- `cursor`: Pagination cursor from previous response
|
||||
|
||||
**Pitfalls**:
|
||||
- Projects group related services together
|
||||
- Pagination uses cursor-based approach
|
||||
- Project IDs are used for organizational purposes
|
||||
- Not all services may be assigned to a project
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Service name -> Service ID**:
|
||||
```
|
||||
1. Call RENDER_LIST_SERVICES with name=service_name
|
||||
2. Find service by name in results
|
||||
3. Extract id (format: 'srv-xxxxxxxxxxxx')
|
||||
```
|
||||
|
||||
**Deployment lookup**:
|
||||
```
|
||||
1. Store deployId from RENDER_TRIGGER_DEPLOY response
|
||||
2. Call RENDER_RETRIEVE_DEPLOY with serviceId and deployId
|
||||
3. Check status for completion
|
||||
```
|
||||
|
||||
### Deploy and Monitor Pattern
|
||||
|
||||
```
|
||||
1. RENDER_LIST_SERVICES -> find service by name -> get serviceId
|
||||
2. RENDER_TRIGGER_DEPLOY with serviceId -> get deployId
|
||||
3. Loop: RENDER_RETRIEVE_DEPLOY with serviceId + deployId
|
||||
4. Check status: 'live' = success, 'build_failed'/'update_failed' = error
|
||||
5. Continue polling until terminal state reached
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Use `cursor` from response for next page
|
||||
- Continue until `cursor` is absent or results are empty
|
||||
- Both LIST_SERVICES and LIST_PROJECTS use cursor-based pagination
|
||||
- Set `limit` to max (100) for fewer pagination rounds
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Service IDs**:
|
||||
- Always prefixed with 'srv-' (e.g., 'srv-abcd1234efgh')
|
||||
- Deploy IDs prefixed with 'dep-' (e.g., 'dep-d2mqkf9r0fns73bham1g')
|
||||
- Always resolve service names to IDs via LIST_SERVICES
|
||||
|
||||
**Service Types**:
|
||||
- Must use exact enum values when filtering
|
||||
- Available types: web_service, static_site, private_service, background_worker, cron_job
|
||||
- Different service types have different deployment behaviors
|
||||
|
||||
**Deployment Behavior**:
|
||||
- Deployments are asynchronous; always poll for completion
|
||||
- Clear cache deploys take longer but resolve stale cache issues
|
||||
- Failed deploys do not roll back automatically; the previous version stays live
|
||||
- Concurrent deploy triggers may be queued
|
||||
|
||||
**Rate Limits**:
|
||||
- Render API has rate limits
|
||||
- Avoid rapid polling; use 10-30 second intervals
|
||||
- Bulk operations should be throttled
|
||||
|
||||
**Response Parsing**:
|
||||
- Response data may be nested under `data` key
|
||||
- Timestamps use ISO 8601 format
|
||||
- Parse defensively with fallbacks for optional fields
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List services | RENDER_LIST_SERVICES | name, type, limit, cursor |
|
||||
| Trigger deploy | RENDER_TRIGGER_DEPLOY | serviceId, clearCache |
|
||||
| Get deploy status | RENDER_RETRIEVE_DEPLOY | serviceId, deployId |
|
||||
| List projects | RENDER_LIST_PROJECTS | limit, cursor |
|
||||
@@ -1,190 +0,0 @@
|
||||
---
|
||||
name: salesforce-automation
|
||||
description: "Automate Salesforce tasks via Rube MCP (Composio): leads, contacts, accounts, opportunities, SOQL queries. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Salesforce Automation via Rube MCP
|
||||
|
||||
Automate Salesforce CRM operations through Composio's Salesforce toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Salesforce connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `salesforce`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `salesforce`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Salesforce OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Manage Leads
|
||||
|
||||
**When to use**: User wants to create, search, update, or list leads
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SALESFORCE_SEARCH_LEADS` - Search leads by criteria [Optional]
|
||||
2. `SALESFORCE_LIST_LEADS` - List all leads [Optional]
|
||||
3. `SALESFORCE_CREATE_LEAD` - Create a new lead [Optional]
|
||||
4. `SALESFORCE_UPDATE_LEAD` - Update lead fields [Optional]
|
||||
5. `SALESFORCE_ADD_LEAD_TO_CAMPAIGN` - Add lead to campaign [Optional]
|
||||
6. `SALESFORCE_APPLY_LEAD_ASSIGNMENT_RULES` - Apply assignment rules [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `LastName`: Required for lead creation
|
||||
- `Company`: Required for lead creation
|
||||
- `Email`, `Phone`, `Title`: Common lead fields
|
||||
- `lead_id`: Lead ID for updates
|
||||
- `campaign_id`: Campaign ID for campaign operations
|
||||
|
||||
**Pitfalls**:
|
||||
- LastName and Company are required fields for lead creation
|
||||
- Lead IDs are 15 or 18 character Salesforce IDs
|
||||
|
||||
### 2. Manage Contacts and Accounts
|
||||
|
||||
**When to use**: User wants to manage contacts and their associated accounts
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SALESFORCE_SEARCH_CONTACTS` - Search contacts [Optional]
|
||||
2. `SALESFORCE_LIST_CONTACTS` - List contacts [Optional]
|
||||
3. `SALESFORCE_CREATE_CONTACT` - Create a new contact [Optional]
|
||||
4. `SALESFORCE_SEARCH_ACCOUNTS` - Search accounts [Optional]
|
||||
5. `SALESFORCE_CREATE_ACCOUNT` - Create a new account [Optional]
|
||||
6. `SALESFORCE_ASSOCIATE_CONTACT_TO_ACCOUNT` - Link contact to account [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `LastName`: Required for contact creation
|
||||
- `Name`: Account name for creation
|
||||
- `AccountId`: Account ID to associate with contact
|
||||
- `contact_id`, `account_id`: IDs for association
|
||||
|
||||
**Pitfalls**:
|
||||
- Contact requires at least LastName
|
||||
- Account association requires both valid contact and account IDs
|
||||
|
||||
### 3. Manage Opportunities
|
||||
|
||||
**When to use**: User wants to track and manage sales opportunities
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SALESFORCE_SEARCH_OPPORTUNITIES` - Search opportunities [Optional]
|
||||
2. `SALESFORCE_LIST_OPPORTUNITIES` - List all opportunities [Optional]
|
||||
3. `SALESFORCE_GET_OPPORTUNITY` - Get opportunity details [Optional]
|
||||
4. `SALESFORCE_CREATE_OPPORTUNITY` - Create new opportunity [Optional]
|
||||
5. `SALESFORCE_RETRIEVE_OPPORTUNITIES_DATA` - Retrieve opportunity data [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `Name`: Opportunity name (required)
|
||||
- `StageName`: Sales stage (required)
|
||||
- `CloseDate`: Expected close date (required)
|
||||
- `Amount`: Deal value
|
||||
- `AccountId`: Associated account
|
||||
|
||||
**Pitfalls**:
|
||||
- Name, StageName, and CloseDate are required for creation
|
||||
- Stage names must match exactly what is configured in Salesforce
|
||||
|
||||
### 4. Run SOQL Queries
|
||||
|
||||
**When to use**: User wants to query Salesforce data with custom SOQL
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SALESFORCE_RUN_SOQL_QUERY` / `SALESFORCE_QUERY` - Execute SOQL [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `query`: SOQL query string
|
||||
|
||||
**Pitfalls**:
|
||||
- SOQL syntax differs from SQL; uses Salesforce object and field API names
|
||||
- Field API names may differ from display labels (e.g., `Account.Name` not `Account Name`)
|
||||
- Results are paginated for large datasets
|
||||
|
||||
### 5. Manage Tasks
|
||||
|
||||
**When to use**: User wants to create, search, update, or complete tasks
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SALESFORCE_SEARCH_TASKS` - Search tasks [Optional]
|
||||
2. `SALESFORCE_UPDATE_TASK` - Update task fields [Optional]
|
||||
3. `SALESFORCE_COMPLETE_TASK` - Mark task as complete [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `task_id`: Task ID for updates
|
||||
- `Status`: Task status value
|
||||
- `Subject`: Task subject
|
||||
|
||||
**Pitfalls**:
|
||||
- Task status values must match picklist options in Salesforce
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### SOQL Syntax
|
||||
|
||||
**Basic query**:
|
||||
```
|
||||
SELECT Id, Name, Email FROM Contact WHERE LastName = 'Smith'
|
||||
```
|
||||
|
||||
**With relationships**:
|
||||
```
|
||||
SELECT Id, Name, Account.Name FROM Contact WHERE Account.Industry = 'Technology'
|
||||
```
|
||||
|
||||
**Date filtering**:
|
||||
```
|
||||
SELECT Id, Name FROM Lead WHERE CreatedDate = TODAY
|
||||
SELECT Id, Name FROM Opportunity WHERE CloseDate = NEXT_MONTH
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- SOQL queries with large results return pagination tokens
|
||||
- Use `SALESFORCE_QUERY` with nextRecordsUrl for pagination
|
||||
- Check `done` field in response; if false, continue paging
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Field API Names**:
|
||||
- Always use API names, not display labels
|
||||
- Custom fields end with `__c` suffix
|
||||
- Use SALESFORCE_GET_ALL_CUSTOM_OBJECTS to discover custom objects
|
||||
|
||||
**ID Formats**:
|
||||
- Salesforce IDs are 15 (case-sensitive) or 18 (case-insensitive) characters
|
||||
- Both formats are accepted in most operations
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Create lead | SALESFORCE_CREATE_LEAD | LastName, Company |
|
||||
| Search leads | SALESFORCE_SEARCH_LEADS | query |
|
||||
| List leads | SALESFORCE_LIST_LEADS | (filters) |
|
||||
| Update lead | SALESFORCE_UPDATE_LEAD | lead_id, fields |
|
||||
| Create contact | SALESFORCE_CREATE_CONTACT | LastName |
|
||||
| Search contacts | SALESFORCE_SEARCH_CONTACTS | query |
|
||||
| Create account | SALESFORCE_CREATE_ACCOUNT | Name |
|
||||
| Search accounts | SALESFORCE_SEARCH_ACCOUNTS | query |
|
||||
| Link contact | SALESFORCE_ASSOCIATE_CONTACT_TO_ACCOUNT | contact_id, account_id |
|
||||
| Create opportunity | SALESFORCE_CREATE_OPPORTUNITY | Name, StageName, CloseDate |
|
||||
| Get opportunity | SALESFORCE_GET_OPPORTUNITY | opportunity_id |
|
||||
| Search opportunities | SALESFORCE_SEARCH_OPPORTUNITIES | query |
|
||||
| Run SOQL | SALESFORCE_RUN_SOQL_QUERY | query |
|
||||
| Query | SALESFORCE_QUERY | query |
|
||||
| Search tasks | SALESFORCE_SEARCH_TASKS | query |
|
||||
| Update task | SALESFORCE_UPDATE_TASK | task_id, fields |
|
||||
| Complete task | SALESFORCE_COMPLETE_TASK | task_id |
|
||||
| Get user info | SALESFORCE_GET_USER_INFO | (none) |
|
||||
| Custom objects | SALESFORCE_GET_ALL_CUSTOM_OBJECTS | (none) |
|
||||
| Create record | SALESFORCE_CREATE_A_RECORD | object_type, fields |
|
||||
| Transfer ownership | SALESFORCE_MASS_TRANSFER_OWNERSHIP | records, new_owner |
|
||||
@@ -1,225 +0,0 @@
|
||||
---
|
||||
name: segment-automation
|
||||
description: "Automate Segment tasks via Rube MCP (Composio): track events, identify users, manage groups, page views, aliases, batch operations. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Segment Automation via Rube MCP
|
||||
|
||||
Automate Segment customer data platform operations through Composio's Segment toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Segment connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `segment`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `segment`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Segment authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Track Events
|
||||
|
||||
**When to use**: User wants to send event data to Segment for downstream destinations
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SEGMENT_TRACK` - Send a single track event [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `userId`: User identifier (required if no `anonymousId`)
|
||||
- `anonymousId`: Anonymous identifier (required if no `userId`)
|
||||
- `event`: Event name (e.g., 'Order Completed', 'Button Clicked')
|
||||
- `properties`: Object with event-specific properties
|
||||
- `timestamp`: ISO 8601 timestamp (optional; defaults to server time)
|
||||
- `context`: Object with contextual metadata (IP, user agent, etc.)
|
||||
|
||||
**Pitfalls**:
|
||||
- At least one of `userId` or `anonymousId` is required
|
||||
- `event` name is required and should follow consistent naming conventions
|
||||
- Properties are freeform objects; ensure consistent schema across events
|
||||
- Timestamp must be ISO 8601 format (e.g., '2024-01-15T10:30:00Z')
|
||||
- Events are processed asynchronously; successful API response means accepted, not delivered
|
||||
|
||||
### 2. Identify Users
|
||||
|
||||
**When to use**: User wants to associate traits with a user profile in Segment
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SEGMENT_IDENTIFY` - Set user traits and identity [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `userId`: User identifier (required if no `anonymousId`)
|
||||
- `anonymousId`: Anonymous identifier
|
||||
- `traits`: Object with user properties (email, name, plan, etc.)
|
||||
- `timestamp`: ISO 8601 timestamp
|
||||
- `context`: Contextual metadata
|
||||
|
||||
**Pitfalls**:
|
||||
- At least one of `userId` or `anonymousId` is required
|
||||
- Traits are merged with existing traits, not replaced
|
||||
- To remove a trait, set it to `null`
|
||||
- Identify calls should be made before track calls for new users
|
||||
- Avoid sending PII in traits unless destinations are configured for it
|
||||
|
||||
### 3. Batch Operations
|
||||
|
||||
**When to use**: User wants to send multiple events, identifies, or other calls in a single request
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SEGMENT_BATCH` - Send multiple Segment calls in one request [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `batch`: Array of message objects, each with:
|
||||
- `type`: Message type ('track', 'identify', 'group', 'page', 'alias')
|
||||
- `userId` / `anonymousId`: User identifier
|
||||
- Additional fields based on type (event, properties, traits, etc.)
|
||||
|
||||
**Pitfalls**:
|
||||
- Each message in the batch must have a valid `type` field
|
||||
- Maximum batch size limit applies; check schema for current limit
|
||||
- All messages in a batch are processed independently; one failure does not affect others
|
||||
- Each message must independently satisfy its type's requirements (e.g., track needs event name)
|
||||
- Batch is the most efficient way to send multiple calls; prefer over individual calls
|
||||
|
||||
### 4. Group Users
|
||||
|
||||
**When to use**: User wants to associate a user with a company, team, or organization
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SEGMENT_GROUP` - Associate user with a group [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `userId`: User identifier (required if no `anonymousId`)
|
||||
- `anonymousId`: Anonymous identifier
|
||||
- `groupId`: Group/organization identifier (required)
|
||||
- `traits`: Object with group properties (name, industry, size, plan)
|
||||
- `timestamp`: ISO 8601 timestamp
|
||||
|
||||
**Pitfalls**:
|
||||
- `groupId` is required; it identifies the company or organization
|
||||
- Group traits are merged with existing traits for that group
|
||||
- A user can belong to multiple groups
|
||||
- Group traits update the group profile, not the user profile
|
||||
|
||||
### 5. Track Page Views
|
||||
|
||||
**When to use**: User wants to record page view events in Segment
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SEGMENT_PAGE` - Send a page view event [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `userId`: User identifier (required if no `anonymousId`)
|
||||
- `anonymousId`: Anonymous identifier
|
||||
- `name`: Page name (e.g., 'Home', 'Pricing', 'Dashboard')
|
||||
- `category`: Page category (e.g., 'Docs', 'Marketing')
|
||||
- `properties`: Object with page-specific properties (url, title, referrer)
|
||||
|
||||
**Pitfalls**:
|
||||
- At least one of `userId` or `anonymousId` is required
|
||||
- `name` and `category` are optional but recommended for proper analytics
|
||||
- Standard properties include `url`, `title`, `referrer`, `path`, `search`
|
||||
- Page calls are often automated; manual use is for server-side page tracking
|
||||
|
||||
### 6. Alias Users and Manage Sources
|
||||
|
||||
**When to use**: User wants to merge anonymous and identified users, or manage source configuration
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SEGMENT_ALIAS` - Link two user identities together [Optional]
|
||||
2. `SEGMENT_LIST_SCHEMA_SETTINGS_IN_SOURCE` - View source schema settings [Optional]
|
||||
3. `SEGMENT_UPDATE_SOURCE` - Update source configuration [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- For ALIAS:
|
||||
- `userId`: New user identifier (the identified ID)
|
||||
- `previousId`: Old user identifier (the anonymous ID)
|
||||
- For source operations:
|
||||
- `sourceId`: Source identifier
|
||||
|
||||
**Pitfalls**:
|
||||
- ALIAS is a one-way operation; cannot be undone
|
||||
- `previousId` is the anonymous/old ID, `userId` is the new/identified ID
|
||||
- Not all destinations support alias calls; check destination documentation
|
||||
- ALIAS should be called once when a user first identifies (e.g., signs up)
|
||||
- Source updates may affect data collection; review changes carefully
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### User Lifecycle
|
||||
|
||||
Standard Segment user lifecycle:
|
||||
```
|
||||
1. Anonymous user visits -> PAGE call with anonymousId
|
||||
2. User interacts -> TRACK call with anonymousId
|
||||
3. User signs up -> ALIAS (anonymousId -> userId), then IDENTIFY with traits
|
||||
4. User takes action -> TRACK call with userId
|
||||
5. User joins org -> GROUP call linking userId to groupId
|
||||
```
|
||||
|
||||
### Batch Optimization
|
||||
|
||||
For bulk data ingestion:
|
||||
```
|
||||
1. Collect events in memory (array of message objects)
|
||||
2. Each message includes type, userId/anonymousId, and type-specific fields
|
||||
3. Call SEGMENT_BATCH with the collected messages
|
||||
4. Check response for any individual message errors
|
||||
```
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
Segment recommends consistent event naming:
|
||||
- **Events**: Use "Object Action" format (e.g., 'Order Completed', 'Article Viewed')
|
||||
- **Properties**: Use snake_case (e.g., 'order_total', 'product_name')
|
||||
- **Traits**: Use snake_case (e.g., 'first_name', 'plan_type')
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**Identity Resolution**:
|
||||
- Always include `userId` or `anonymousId` on every call
|
||||
- Use ALIAS only once per user identity merge
|
||||
- Identify before tracking to ensure proper user association
|
||||
|
||||
**Data Quality**:
|
||||
- Event names should be consistent across all sources
|
||||
- Properties should follow a defined schema for downstream compatibility
|
||||
- Avoid sending sensitive PII unless destinations are configured for it
|
||||
|
||||
**Rate Limits**:
|
||||
- Use BATCH for bulk operations to stay within rate limits
|
||||
- Individual calls are rate-limited per source
|
||||
- Batch calls are more efficient and less likely to be throttled
|
||||
|
||||
**Response Parsing**:
|
||||
- Successful responses indicate acceptance, not delivery to destinations
|
||||
- Response data may be nested under `data` key
|
||||
- Check for error fields in batch responses for individual message failures
|
||||
|
||||
**Timestamps**:
|
||||
- Must be ISO 8601 format with timezone (e.g., '2024-01-15T10:30:00Z')
|
||||
- Omitting timestamp uses server receive time
|
||||
- Historical data imports should include explicit timestamps
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| Track event | SEGMENT_TRACK | userId, event, properties |
|
||||
| Identify user | SEGMENT_IDENTIFY | userId, traits |
|
||||
| Batch calls | SEGMENT_BATCH | batch (array of messages) |
|
||||
| Group user | SEGMENT_GROUP | userId, groupId, traits |
|
||||
| Page view | SEGMENT_PAGE | userId, name, properties |
|
||||
| Alias identity | SEGMENT_ALIAS | userId, previousId |
|
||||
| Source schema | SEGMENT_LIST_SCHEMA_SETTINGS_IN_SOURCE | sourceId |
|
||||
| Update source | SEGMENT_UPDATE_SOURCE | sourceId |
|
||||
| Warehouses | SEGMENT_LIST_CONNECTED_WAREHOUSES_FROM_SOURCE | sourceId |
|
||||
@@ -1,228 +0,0 @@
|
||||
---
|
||||
name: sendgrid-automation
|
||||
description: "Automate SendGrid email operations including sending emails, managing contacts/lists, sender identities, templates, and analytics via Rube MCP (Composio). Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# SendGrid Automation via Rube MCP
|
||||
|
||||
Automate SendGrid email delivery workflows including marketing campaigns (Single Sends), contact and list management, sender identity setup, and email analytics through Composio's SendGrid toolkit.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active SendGrid connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `sendgrid`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `sendgrid`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete SendGrid API key authentication
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Create and Send Marketing Campaigns (Single Sends)
|
||||
|
||||
**When to use**: User wants to create and send a marketing email campaign to a contact list or segment.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SENDGRID_RETRIEVE_ALL_LISTS` - List available marketing lists to target [Prerequisite]
|
||||
2. `SENDGRID_CREATE_A_LIST` - Create a new list if needed [Optional]
|
||||
3. `SENDGRID_ADD_OR_UPDATE_A_CONTACT` - Add contacts to the list [Optional]
|
||||
4. `SENDGRID_GET_ALL_SENDER_IDENTITIES` - Get verified sender ID [Prerequisite]
|
||||
5. `SENDGRID_CREATE_SINGLE_SEND` - Create the campaign with content, sender, and recipients [Required]
|
||||
|
||||
**Key parameters for SENDGRID_CREATE_SINGLE_SEND**:
|
||||
- `name`: Campaign name (required)
|
||||
- `email__config__subject`: Email subject line
|
||||
- `email__config__html__content`: HTML body content
|
||||
- `email__config__plain__content`: Plain text version
|
||||
- `email__config__sender__id`: Verified sender identity ID
|
||||
- `email__config__design__id`: Use instead of html_content for pre-built designs
|
||||
- `send__to__list__ids`: Array of list UUIDs to send to
|
||||
- `send__to__segment__ids`: Array of segment UUIDs
|
||||
- `send__to__all`: true to send to all contacts
|
||||
- `email__config__suppression__group__id` or `email__config__custom__unsubscribe__url`: One required for compliance
|
||||
|
||||
**Pitfalls**:
|
||||
- Setting `send_at` on CREATE does NOT schedule the send; it only prepopulates the UI date; use the Schedule endpoint separately
|
||||
- `send_at: "now"` is only valid with the Schedule endpoint, not CREATE
|
||||
- Must provide either `suppression_group_id` or `custom_unsubscribe_url` for unsubscribe compliance
|
||||
- Sender must be verified before use; check with `SENDGRID_GET_ALL_SENDER_IDENTITIES`
|
||||
- Nested params use double-underscore notation (e.g., `email__config__subject`)
|
||||
|
||||
### 2. Manage Contacts and Lists
|
||||
|
||||
**When to use**: User wants to create contact lists, add/update contacts, search for contacts, or remove contacts from lists.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SENDGRID_RETRIEVE_ALL_LISTS` - List all marketing lists [Required]
|
||||
2. `SENDGRID_CREATE_A_LIST` - Create a new contact list [Optional]
|
||||
3. `SENDGRID_GET_A_LIST_BY_ID` - Get list details and sample contacts [Optional]
|
||||
4. `SENDGRID_ADD_OR_UPDATE_A_CONTACT` - Upsert contacts with list association [Required]
|
||||
5. `SENDGRID_GET_CONTACTS_BY_EMAILS` - Look up contacts by email [Optional]
|
||||
6. `SENDGRID_GET_CONTACTS_BY_IDENTIFIERS` - Look up contacts by email, phone, or external ID [Optional]
|
||||
7. `SENDGRID_GET_LIST_CONTACT_COUNT` - Verify contact count after operations [Optional]
|
||||
8. `SENDGRID_REMOVE_CONTACTS_FROM_A_LIST` - Remove contacts from a list without deleting [Optional]
|
||||
9. `SENDGRID_REMOVE_LIST_AND_OPTIONAL_CONTACTS` - Delete an entire list [Optional]
|
||||
10. `SENDGRID_IMPORT_CONTACTS` - Bulk import from CSV [Optional]
|
||||
|
||||
**Key parameters for SENDGRID_ADD_OR_UPDATE_A_CONTACT**:
|
||||
- `contacts`: Array of contact objects (max 30,000 or 6MB), each with at least one identifier: `email`, `phone_number_id`, `external_id`, or `anonymous_id` (required)
|
||||
- `list_ids`: Array of list UUID strings to associate contacts with
|
||||
|
||||
**Pitfalls**:
|
||||
- `SENDGRID_ADD_OR_UPDATE_A_CONTACT` is asynchronous; returns 202 with `job_id`; contacts may take 10-30 seconds to appear
|
||||
- List IDs are UUIDs (e.g., "ca7a3796-e8a8-4029-9ccb-df8937940562"), not integers
|
||||
- List names must be unique; duplicate names cause 400 errors
|
||||
- `SENDGRID_ADD_A_SINGLE_RECIPIENT_TO_A_LIST` uses the legacy API; prefer `SENDGRID_ADD_OR_UPDATE_A_CONTACT` with `list_ids`
|
||||
- `SENDGRID_REMOVE_LIST_AND_OPTIONAL_CONTACTS` is irreversible; require explicit user confirmation
|
||||
- Email addresses are automatically lowercased by SendGrid
|
||||
|
||||
### 3. Manage Sender Identities
|
||||
|
||||
**When to use**: User wants to set up or view sender identities (From addresses) for sending emails.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SENDGRID_GET_ALL_SENDER_IDENTITIES` - List all existing sender identities [Required]
|
||||
2. `SENDGRID_CREATE_A_SENDER_IDENTITY` - Create a new sender identity [Optional]
|
||||
3. `SENDGRID_VIEW_A_SENDER_IDENTITY` - View details for a specific sender [Optional]
|
||||
4. `SENDGRID_UPDATE_A_SENDER_IDENTITY` - Update sender details [Optional]
|
||||
5. `SENDGRID_CREATE_VERIFIED_SENDER_REQUEST` - Create and verify a new sender [Optional]
|
||||
6. `SENDGRID_AUTHENTICATE_A_DOMAIN` - Set up domain authentication for auto-verification [Optional]
|
||||
|
||||
**Key parameters for SENDGRID_CREATE_A_SENDER_IDENTITY**:
|
||||
- `from__email`: From email address (required)
|
||||
- `from__name`: Display name (required)
|
||||
- `reply__to__email`: Reply-to address (required)
|
||||
- `nickname`: Internal identifier (required)
|
||||
- `address`, `city`, `country`: Physical address for CAN-SPAM compliance (required)
|
||||
|
||||
**Pitfalls**:
|
||||
- New senders must be verified before use; if domain is not authenticated, a verification email is sent
|
||||
- Up to 100 unique sender identities per account
|
||||
- Avoid using domains with strict DMARC policies (gmail.com, yahoo.com) as from addresses
|
||||
- `SENDGRID_CREATE_VERIFIED_SENDER_REQUEST` sends a verification email; sender is unusable until verified
|
||||
|
||||
### 4. View Email Statistics and Activity
|
||||
|
||||
**When to use**: User wants to review email delivery stats, bounce rates, open/click metrics, or message activity.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS` - Get account-wide delivery metrics [Required]
|
||||
2. `SENDGRID_GET_ALL_CATEGORIES` - Discover available categories for filtering [Optional]
|
||||
3. `SENDGRID_RETRIEVE_EMAIL_STATISTICS_FOR_CATEGORIES` - Get stats broken down by category [Optional]
|
||||
4. `SENDGRID_FILTER_ALL_MESSAGES` - Search email activity feed by recipient, status, or date [Optional]
|
||||
5. `SENDGRID_FILTER_MESSAGES_BY_MESSAGE_ID` - Get detailed events for a specific message [Optional]
|
||||
6. `SENDGRID_REQUEST_CSV` - Export activity data as CSV for large datasets [Optional]
|
||||
7. `SENDGRID_DOWNLOAD_CSV` - Download the exported CSV file [Optional]
|
||||
|
||||
**Key parameters for SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS**:
|
||||
- `start_date`: Start date YYYY-MM-DD (required)
|
||||
- `end_date`: End date YYYY-MM-DD
|
||||
- `aggregated_by`: "day", "week", or "month"
|
||||
- `limit` / `offset`: Pagination (default 500)
|
||||
|
||||
**Key parameters for SENDGRID_FILTER_ALL_MESSAGES**:
|
||||
- `query`: SQL-like query string, e.g., `status="delivered"`, `to_email="user@example.com"`, date ranges with `BETWEEN TIMESTAMP`
|
||||
- `limit`: 1-1000 (default 10)
|
||||
|
||||
**Pitfalls**:
|
||||
- `SENDGRID_FILTER_ALL_MESSAGES` requires the "30 Days Additional Email Activity History" paid add-on; returns 403 without it
|
||||
- Global statistics are nested under `details[].stats[0].metrics`, not a flat structure
|
||||
- Category statistics are only available for the previous 13 months
|
||||
- Maximum 10 categories per request in `SENDGRID_RETRIEVE_EMAIL_STATISTICS_FOR_CATEGORIES`
|
||||
- CSV export is limited to one request per 12 hours; link expires after 3 days
|
||||
|
||||
### 5. Manage Suppressions
|
||||
|
||||
**When to use**: User wants to check or manage unsubscribe groups for email compliance.
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SENDGRID_GET_SUPPRESSION_GROUPS` - List all suppression groups [Required]
|
||||
2. `SENDGRID_RETRIEVE_ALL_SUPPRESSION_GROUPS_FOR_AN_EMAIL_ADDRESS` - Check suppression status for a specific email [Optional]
|
||||
|
||||
**Pitfalls**:
|
||||
- Suppressed addresses remain undeliverable even if present on marketing lists
|
||||
- Campaign send counts may be lower than list counts due to suppressions
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
Always resolve names to IDs before operations:
|
||||
- **List name -> list_id**: `SENDGRID_RETRIEVE_ALL_LISTS` and match by name
|
||||
- **Sender name -> sender_id**: `SENDGRID_GET_ALL_SENDER_IDENTITIES` and match
|
||||
- **Contact email -> contact_id**: `SENDGRID_GET_CONTACTS_BY_EMAILS` with email array
|
||||
- **Template name -> template_id**: Use the SendGrid UI or template endpoints
|
||||
|
||||
### Pagination
|
||||
- `SENDGRID_RETRIEVE_ALL_LISTS`: Token-based with `page_token` and `page_size` (max 1000)
|
||||
- `SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS`: Offset-based with `limit` (max 500) and `offset`
|
||||
- Always paginate list retrieval to avoid missing existing lists
|
||||
|
||||
### Async Operations
|
||||
Contact operations (`ADD_OR_UPDATE_A_CONTACT`, `IMPORT_CONTACTS`) are asynchronous:
|
||||
- Returns 202 with a `job_id`
|
||||
- Wait 10-30 seconds before verifying with `GET_CONTACTS_BY_EMAILS`
|
||||
- Use `GET_LIST_CONTACT_COUNT` to confirm list growth
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
### ID Formats
|
||||
- Marketing list IDs are UUIDs (e.g., "ca7a3796-e8a8-4029-9ccb-df8937940562")
|
||||
- Legacy list IDs are integers; do not mix with Marketing API endpoints
|
||||
- Sender identity IDs are integers
|
||||
- Template IDs: Dynamic templates start with "d-", legacy templates are UUIDs
|
||||
- Contact IDs are UUIDs
|
||||
|
||||
### Rate Limits
|
||||
- SendGrid may return HTTP 429; respect `Retry-After` headers
|
||||
- CSV export limited to one request per 12 hours
|
||||
- Bulk contact upsert max: 30,000 contacts or 6MB per request
|
||||
|
||||
### Parameter Quirks
|
||||
- Nested params use double-underscore: `email__config__subject`, `from__email`
|
||||
- `send_at` on CREATE_SINGLE_SEND only sets a UI default, does NOT schedule
|
||||
- `SENDGRID_ADD_A_SINGLE_RECIPIENT_TO_A_LIST` uses legacy API; `recipient_id` is Base64-encoded lowercase email
|
||||
- `SENDGRID_RETRIEVE_ALL_LISTS` and `SENDGRID_GET_ALL_LISTS` both exist; prefer RETRIEVE_ALL_LISTS for Marketing API
|
||||
- Contact adds are async (202); always verify after a delay
|
||||
|
||||
### Legacy vs Marketing API
|
||||
- Some tools use the legacy Contact Database API (`/v3/contactdb/`) which may return 403 on newer accounts
|
||||
- Prefer Marketing API tools: `SENDGRID_ADD_OR_UPDATE_A_CONTACT`, `SENDGRID_RETRIEVE_ALL_LISTS`, `SENDGRID_CREATE_SINGLE_SEND`
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List marketing lists | `SENDGRID_RETRIEVE_ALL_LISTS` | `page_size`, `page_token` |
|
||||
| Create list | `SENDGRID_CREATE_A_LIST` | `name` |
|
||||
| Get list by ID | `SENDGRID_GET_A_LIST_BY_ID` | `id` |
|
||||
| Get list count | `SENDGRID_GET_LIST_CONTACT_COUNT` | `id` |
|
||||
| Add/update contacts | `SENDGRID_ADD_OR_UPDATE_A_CONTACT` | `contacts`, `list_ids` |
|
||||
| Search contacts by email | `SENDGRID_GET_CONTACTS_BY_EMAILS` | `emails` |
|
||||
| Search by identifiers | `SENDGRID_GET_CONTACTS_BY_IDENTIFIERS` | `identifier_type`, `identifiers` |
|
||||
| Remove from list | `SENDGRID_REMOVE_CONTACTS_FROM_A_LIST` | `id`, `contact_ids` |
|
||||
| Delete list | `SENDGRID_REMOVE_LIST_AND_OPTIONAL_CONTACTS` | `id`, `delete_contacts` |
|
||||
| Import contacts CSV | `SENDGRID_IMPORT_CONTACTS` | field mappings |
|
||||
| Create Single Send | `SENDGRID_CREATE_SINGLE_SEND` | `name`, `email__config__*`, `send__to__list__ids` |
|
||||
| List sender identities | `SENDGRID_GET_ALL_SENDER_IDENTITIES` | (none) |
|
||||
| Create sender | `SENDGRID_CREATE_A_SENDER_IDENTITY` | `from__email`, `from__name`, `address` |
|
||||
| Verify sender | `SENDGRID_CREATE_VERIFIED_SENDER_REQUEST` | `from_email`, `nickname`, `address` |
|
||||
| Authenticate domain | `SENDGRID_AUTHENTICATE_A_DOMAIN` | `domain` |
|
||||
| Global email stats | `SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS` | `start_date`, `aggregated_by` |
|
||||
| Category stats | `SENDGRID_RETRIEVE_EMAIL_STATISTICS_FOR_CATEGORIES` | `start_date`, `categories` |
|
||||
| Filter email activity | `SENDGRID_FILTER_ALL_MESSAGES` | `query`, `limit` |
|
||||
| Message details | `SENDGRID_FILTER_MESSAGES_BY_MESSAGE_ID` | `msg_id` |
|
||||
| Export CSV | `SENDGRID_REQUEST_CSV` | `query` |
|
||||
| Download CSV | `SENDGRID_DOWNLOAD_CSV` | `download_uuid` |
|
||||
| List categories | `SENDGRID_GET_ALL_CATEGORIES` | (none) |
|
||||
| Suppression groups | `SENDGRID_GET_SUPPRESSION_GROUPS` | (none) |
|
||||
| Get template | `SENDGRID_RETRIEVE_A_SINGLE_TRANSACTIONAL_TEMPLATE` | `template_id` |
|
||||
| Duplicate template | `SENDGRID_DUPLICATE_A_TRANSACTIONAL_TEMPLATE` | `template_id`, `name` |
|
||||
@@ -1,232 +0,0 @@
|
||||
---
|
||||
name: sentry-automation
|
||||
description: "Automate Sentry tasks via Rube MCP (Composio): manage issues/events, configure alerts, track releases, monitor projects and teams. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Sentry Automation via Rube MCP
|
||||
|
||||
Automate Sentry error tracking and monitoring operations through Composio's Sentry toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Sentry connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `sentry`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `sentry`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Sentry OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Investigate Issues
|
||||
|
||||
**When to use**: User wants to find, inspect, or triage error issues
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SENTRY_LIST_AN_ORGANIZATIONS_ISSUES` - List issues across the organization [Required]
|
||||
2. `SENTRY_GET_ORGANIZATION_ISSUE_DETAILS` - Get detailed info on a specific issue [Optional]
|
||||
3. `SENTRY_LIST_AN_ISSUES_EVENTS` - View individual error events for an issue [Optional]
|
||||
4. `SENTRY_RETRIEVE_AN_ISSUE_EVENT` - Get full event details with stack trace [Optional]
|
||||
5. `SENTRY_RETRIEVE_ISSUE_TAG_DETAILS` - Inspect tag distribution for an issue [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `organization_id_or_slug`: Organization identifier
|
||||
- `issue_id`: Numeric issue ID
|
||||
- `query`: Search query (e.g., `is:unresolved`, `assigned:me`, `browser:Chrome`)
|
||||
- `sort`: Sort order (`date`, `new`, `freq`, `priority`)
|
||||
- `statsPeriod`: Time window for stats (`24h`, `14d`, etc.)
|
||||
|
||||
**Pitfalls**:
|
||||
- `organization_id_or_slug` is the org slug (e.g., 'my-org'), not the display name
|
||||
- Issue IDs are numeric; do not confuse with event IDs which are UUIDs
|
||||
- Query syntax uses Sentry's search format: `is:unresolved`, `assigned:me`, `!has:release`
|
||||
- Events within an issue can have different stack traces; inspect individual events for details
|
||||
|
||||
### 2. Manage Project Issues
|
||||
|
||||
**When to use**: User wants to view issues scoped to a specific project
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SENTRY_RETRIEVE_ORGANIZATION_PROJECTS` - List projects to find project slug [Prerequisite]
|
||||
2. `SENTRY_RETRIEVE_PROJECT_ISSUES_LIST` - List issues for a specific project [Required]
|
||||
3. `SENTRY_RETRIEVE_ISSUE_EVENTS_BY_ID` - Get events for a specific issue [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `organization_id_or_slug`: Organization identifier
|
||||
- `project_id_or_slug`: Project identifier
|
||||
- `query`: Search filter string
|
||||
- `statsPeriod`: Stats time window
|
||||
|
||||
**Pitfalls**:
|
||||
- Project slugs are different from project display names
|
||||
- Always resolve project names to slugs via RETRIEVE_ORGANIZATION_PROJECTS first
|
||||
- Project-scoped issue lists may have different pagination than org-scoped lists
|
||||
|
||||
### 3. Configure Alert Rules
|
||||
|
||||
**When to use**: User wants to create or manage alert rules for a project
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SENTRY_RETRIEVE_ORGANIZATION_PROJECTS` - Find project for the alert [Prerequisite]
|
||||
2. `SENTRY_RETRIEVE_PROJECT_RULES_BY_ORG_AND_PROJECT_ID` - List existing rules [Optional]
|
||||
3. `SENTRY_CREATE_PROJECT_RULE_FOR_ALERTS` - Create a new alert rule [Required]
|
||||
4. `SENTRY_CREATE_ORGANIZATION_ALERT_RULE` - Create org-level metric alert [Alternative]
|
||||
5. `SENTRY_UPDATE_ORGANIZATION_ALERT_RULES` - Update existing alert rules [Optional]
|
||||
6. `SENTRY_RETRIEVE_ALERT_RULE_DETAILS` - Inspect specific alert rule [Optional]
|
||||
7. `SENTRY_GET_PROJECT_RULE_DETAILS` - Get project-level rule details [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `name`: Alert rule name
|
||||
- `conditions`: Array of trigger conditions
|
||||
- `actions`: Array of actions to perform when triggered
|
||||
- `filters`: Array of event filters
|
||||
- `frequency`: How often to trigger (in minutes)
|
||||
- `actionMatch`: 'all', 'any', or 'none' for condition matching
|
||||
|
||||
**Pitfalls**:
|
||||
- Project-level rules (CREATE_PROJECT_RULE) and org-level metric alerts (CREATE_ORGANIZATION_ALERT_RULE) are different
|
||||
- Conditions, actions, and filters use specific JSON schemas; check Sentry docs for valid types
|
||||
- `frequency` is in minutes; setting too low causes alert fatigue
|
||||
- `actionMatch` defaults may vary; explicitly set to avoid unexpected behavior
|
||||
|
||||
### 4. Manage Releases
|
||||
|
||||
**When to use**: User wants to create, track, or manage release versions
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SENTRY_LIST_ORGANIZATION_RELEASES` - List existing releases [Optional]
|
||||
2. `SENTRY_CREATE_RELEASE_FOR_ORGANIZATION` - Create a new release [Required]
|
||||
3. `SENTRY_UPDATE_RELEASE_DETAILS_FOR_ORGANIZATION` - Update release metadata [Optional]
|
||||
4. `SENTRY_CREATE_RELEASE_DEPLOY_FOR_ORG` - Record a deployment for a release [Optional]
|
||||
5. `SENTRY_UPLOAD_RELEASE_FILE_TO_ORGANIZATION` - Upload source maps or files [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `version`: Release version string (e.g., '1.0.0', commit SHA)
|
||||
- `projects`: Array of project slugs this release belongs to
|
||||
- `dateReleased`: Release timestamp (ISO 8601)
|
||||
- `environment`: Deployment environment name (e.g., 'production', 'staging')
|
||||
|
||||
**Pitfalls**:
|
||||
- Release versions must be unique within an organization
|
||||
- Releases can span multiple projects; use the `projects` array
|
||||
- Deploying a release is separate from creating it; use CREATE_RELEASE_DEPLOY
|
||||
- Source map uploads require the release to exist first
|
||||
|
||||
### 5. Monitor Organization and Teams
|
||||
|
||||
**When to use**: User wants to view org structure, teams, or member lists
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SENTRY_GET_ORGANIZATION_DETAILS` or `SENTRY_GET_ORGANIZATION_BY_ID_OR_SLUG` - Get org info [Required]
|
||||
2. `SENTRY_LIST_TEAMS_IN_ORGANIZATION` - List all teams [Optional]
|
||||
3. `SENTRY_LIST_ORGANIZATION_MEMBERS` - List org members [Optional]
|
||||
4. `SENTRY_GET_PROJECT_LIST` - List all accessible projects [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `organization_id_or_slug`: Organization identifier
|
||||
- `cursor`: Pagination cursor for large result sets
|
||||
|
||||
**Pitfalls**:
|
||||
- Organization slugs are URL-safe identifiers, not display names
|
||||
- Member lists may be paginated; follow cursor pagination
|
||||
- Team and member visibility depends on the authenticated user's permissions
|
||||
|
||||
### 6. Manage Monitors (Cron Monitoring)
|
||||
|
||||
**When to use**: User wants to update cron job monitoring configuration
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SENTRY_UPDATE_A_MONITOR` - Update monitor configuration [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `organization_id_or_slug`: Organization identifier
|
||||
- `monitor_id_or_slug`: Monitor identifier
|
||||
- `name`: Monitor display name
|
||||
- `schedule`: Cron schedule expression or interval
|
||||
- `checkin_margin`: Grace period in minutes for late check-ins
|
||||
- `max_runtime`: Maximum expected runtime in minutes
|
||||
|
||||
**Pitfalls**:
|
||||
- Monitor slugs are auto-generated from the name; use slug for API calls
|
||||
- Schedule changes take effect immediately
|
||||
- Missing check-ins trigger alerts after the margin period
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### ID Resolution
|
||||
|
||||
**Organization name -> Slug**:
|
||||
```
|
||||
1. Call SENTRY_GET_ORGANIZATION_DETAILS
|
||||
2. Extract slug field from response
|
||||
```
|
||||
|
||||
**Project name -> Slug**:
|
||||
```
|
||||
1. Call SENTRY_RETRIEVE_ORGANIZATION_PROJECTS
|
||||
2. Find project by name, extract slug
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
- Sentry uses cursor-based pagination with `Link` headers
|
||||
- Check response for cursor values
|
||||
- Pass cursor in next request until no more pages
|
||||
|
||||
### Search Query Syntax
|
||||
|
||||
- `is:unresolved` - Unresolved issues
|
||||
- `is:resolved` - Resolved issues
|
||||
- `assigned:me` - Assigned to current user
|
||||
- `assigned:team-slug` - Assigned to a team
|
||||
- `!has:release` - Issues without a release
|
||||
- `first-release:1.0.0` - Issues first seen in release
|
||||
- `times-seen:>100` - Seen more than 100 times
|
||||
- `browser:Chrome` - Filter by browser tag
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**ID Formats**:
|
||||
- Organization: use slug (e.g., 'my-org'), not display name
|
||||
- Project: use slug (e.g., 'my-project'), not display name
|
||||
- Issue IDs: numeric integers
|
||||
- Event IDs: UUIDs (32-char hex strings)
|
||||
|
||||
**Permissions**:
|
||||
- API token scopes must match the operations being performed
|
||||
- Organization-level operations require org-level permissions
|
||||
- Project-level operations require project access
|
||||
|
||||
**Rate Limits**:
|
||||
- Sentry enforces per-organization rate limits
|
||||
- Implement backoff on 429 responses
|
||||
- Bulk operations should be staggered
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List org issues | SENTRY_LIST_AN_ORGANIZATIONS_ISSUES | organization_id_or_slug, query |
|
||||
| Get issue details | SENTRY_GET_ORGANIZATION_ISSUE_DETAILS | organization_id_or_slug, issue_id |
|
||||
| List issue events | SENTRY_LIST_AN_ISSUES_EVENTS | issue_id |
|
||||
| Get event details | SENTRY_RETRIEVE_AN_ISSUE_EVENT | organization_id_or_slug, event_id |
|
||||
| List project issues | SENTRY_RETRIEVE_PROJECT_ISSUES_LIST | organization_id_or_slug, project_id_or_slug |
|
||||
| List projects | SENTRY_RETRIEVE_ORGANIZATION_PROJECTS | organization_id_or_slug |
|
||||
| Get org details | SENTRY_GET_ORGANIZATION_DETAILS | organization_id_or_slug |
|
||||
| List teams | SENTRY_LIST_TEAMS_IN_ORGANIZATION | organization_id_or_slug |
|
||||
| List members | SENTRY_LIST_ORGANIZATION_MEMBERS | organization_id_or_slug |
|
||||
| Create alert rule | SENTRY_CREATE_PROJECT_RULE_FOR_ALERTS | organization_id_or_slug, project_id_or_slug |
|
||||
| Create metric alert | SENTRY_CREATE_ORGANIZATION_ALERT_RULE | organization_id_or_slug |
|
||||
| Create release | SENTRY_CREATE_RELEASE_FOR_ORGANIZATION | organization_id_or_slug, version |
|
||||
| Deploy release | SENTRY_CREATE_RELEASE_DEPLOY_FOR_ORG | organization_id_or_slug, version |
|
||||
| List releases | SENTRY_LIST_ORGANIZATION_RELEASES | organization_id_or_slug |
|
||||
| Update monitor | SENTRY_UPDATE_A_MONITOR | organization_id_or_slug, monitor_id_or_slug |
|
||||
@@ -1,168 +0,0 @@
|
||||
---
|
||||
name: shopify-automation
|
||||
description: "Automate Shopify tasks via Rube MCP (Composio): products, orders, customers, inventory, collections. Always search tools first for current schemas."
|
||||
requires:
|
||||
mcp: [rube]
|
||||
---
|
||||
|
||||
# Shopify Automation via Rube MCP
|
||||
|
||||
Automate Shopify operations through Composio's Shopify toolkit via Rube MCP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
|
||||
- Active Shopify connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `shopify`
|
||||
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
|
||||
|
||||
## Setup
|
||||
|
||||
**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
|
||||
|
||||
|
||||
1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
|
||||
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `shopify`
|
||||
3. If connection is not ACTIVE, follow the returned auth link to complete Shopify OAuth
|
||||
4. Confirm connection status shows ACTIVE before running any workflows
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### 1. Manage Products
|
||||
|
||||
**When to use**: User wants to list, search, create, or manage products
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SHOPIFY_GET_PRODUCTS` / `SHOPIFY_GET_PRODUCTS_PAGINATED` - List products [Optional]
|
||||
2. `SHOPIFY_GET_PRODUCT` - Get single product details [Optional]
|
||||
3. `SHOPIFY_BULK_CREATE_PRODUCTS` - Create products in bulk [Optional]
|
||||
4. `SHOPIFY_GET_PRODUCTS_COUNT` - Get product count [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `product_id`: Product ID for single retrieval
|
||||
- `title`: Product title
|
||||
- `vendor`: Product vendor
|
||||
- `status`: 'active', 'draft', or 'archived'
|
||||
|
||||
**Pitfalls**:
|
||||
- Paginated results require cursor-based pagination for large catalogs
|
||||
- Product variants are nested within the product object
|
||||
|
||||
### 2. Manage Orders
|
||||
|
||||
**When to use**: User wants to list, search, or inspect orders
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SHOPIFY_GET_ORDERS_WITH_FILTERS` - List orders with filters [Required]
|
||||
2. `SHOPIFY_GET_ORDER` - Get single order details [Optional]
|
||||
3. `SHOPIFY_GET_FULFILLMENT` - Get fulfillment details [Optional]
|
||||
4. `SHOPIFY_GET_FULFILLMENT_EVENTS` - Track fulfillment events [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `status`: Order status filter ('any', 'open', 'closed', 'cancelled')
|
||||
- `financial_status`: Payment status filter
|
||||
- `fulfillment_status`: Fulfillment status filter
|
||||
- `order_id`: Order ID for single retrieval
|
||||
- `created_at_min`/`created_at_max`: Date range filters
|
||||
|
||||
**Pitfalls**:
|
||||
- Order IDs are numeric; use string format for API calls
|
||||
- Default order listing may not include all statuses; specify 'any' for all
|
||||
|
||||
### 3. Manage Customers
|
||||
|
||||
**When to use**: User wants to list or search customers
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SHOPIFY_GET_ALL_CUSTOMERS` - List all customers [Required]
|
||||
|
||||
**Key parameters**:
|
||||
- `limit`: Number of customers per page
|
||||
- `since_id`: Pagination cursor
|
||||
|
||||
**Pitfalls**:
|
||||
- Customer data includes order count and total spent
|
||||
- Large customer lists require pagination
|
||||
|
||||
### 4. Manage Collections
|
||||
|
||||
**When to use**: User wants to manage product collections
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SHOPIFY_GET_SMART_COLLECTIONS` - List smart collections [Optional]
|
||||
2. `SHOPIFY_GET_SMART_COLLECTION_BY_ID` - Get collection details [Optional]
|
||||
3. `SHOPIFY_CREATE_SMART_COLLECTIONS` - Create a smart collection [Optional]
|
||||
4. `SHOPIFY_ADD_PRODUCT_TO_COLLECTION` - Add product to collection [Optional]
|
||||
5. `SHOPIFY_GET_PRODUCTS_IN_COLLECTION` - List products in collection [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `collection_id`: Collection ID
|
||||
- `product_id`: Product ID for adding to collection
|
||||
- `rules`: Smart collection rules for automatic inclusion
|
||||
|
||||
**Pitfalls**:
|
||||
- Smart collections auto-populate based on rules; manual collections use custom collections API
|
||||
- Collection count endpoints provide approximate counts
|
||||
|
||||
### 5. Manage Inventory
|
||||
|
||||
**When to use**: User wants to check or manage inventory levels
|
||||
|
||||
**Tool sequence**:
|
||||
1. `SHOPIFY_GET_INVENTORY_LEVELS` / `SHOPIFY_RETRIEVES_A_LIST_OF_INVENTORY_LEVELS` - Check stock [Required]
|
||||
2. `SHOPIFY_LIST_LOCATION` - List store locations [Optional]
|
||||
|
||||
**Key parameters**:
|
||||
- `inventory_item_ids`: Inventory item IDs to check
|
||||
- `location_ids`: Location IDs to filter by
|
||||
|
||||
**Pitfalls**:
|
||||
- Inventory is tracked per variant per location
|
||||
- Location IDs are required for multi-location stores
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pagination
|
||||
|
||||
- Use `limit` and `page_info` cursor for paginated results
|
||||
- Check response for `next` link header
|
||||
- Continue until no more pages available
|
||||
|
||||
### GraphQL Queries
|
||||
|
||||
For advanced operations:
|
||||
```
|
||||
1. Call SHOPIFY_GRAPH_QL_QUERY with custom query
|
||||
2. Parse response from data object
|
||||
```
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
**API Versioning**:
|
||||
- Shopify REST API has versioned endpoints
|
||||
- Some features require specific API versions
|
||||
|
||||
**Rate Limits**:
|
||||
- REST API: 2 requests/second for standard plans
|
||||
- GraphQL: 1000 cost points per second
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Tool Slug | Key Params |
|
||||
|------|-----------|------------|
|
||||
| List products | SHOPIFY_GET_PRODUCTS | (filters) |
|
||||
| Get product | SHOPIFY_GET_PRODUCT | product_id |
|
||||
| Products paginated | SHOPIFY_GET_PRODUCTS_PAGINATED | limit, page_info |
|
||||
| Bulk create | SHOPIFY_BULK_CREATE_PRODUCTS | products |
|
||||
| Product count | SHOPIFY_GET_PRODUCTS_COUNT | (none) |
|
||||
| List orders | SHOPIFY_GET_ORDERS_WITH_FILTERS | status, financial_status |
|
||||
| Get order | SHOPIFY_GET_ORDER | order_id |
|
||||
| List customers | SHOPIFY_GET_ALL_CUSTOMERS | limit |
|
||||
| Shop details | SHOPIFY_GET_SHOP_DETAILS | (none) |
|
||||
| Validate access | SHOPIFY_VALIDATE_ACCESS | (none) |
|
||||
| Smart collections | SHOPIFY_GET_SMART_COLLECTIONS | (none) |
|
||||
| Products in collection | SHOPIFY_GET_PRODUCTS_IN_COLLECTION | collection_id |
|
||||
| Inventory levels | SHOPIFY_GET_INVENTORY_LEVELS | inventory_item_ids |
|
||||
| Locations | SHOPIFY_LIST_LOCATION | (none) |
|
||||
| Fulfillment | SHOPIFY_GET_FULFILLMENT | order_id, fulfillment_id |
|
||||
| GraphQL | SHOPIFY_GRAPH_QL_QUERY | query |
|
||||
| Bulk query | SHOPIFY_BULK_QUERY_OPERATION | query |
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user