diff --git a/AGENTS.md b/AGENTS.md index e53c96b..9a2b9bd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,7 @@ marketingskills/ │ └── SKILL.md # Required skill file ├── tools/ │ ├── clis/ # Zero-dependency Node.js CLI tools (51 tools) +│ ├── composio/ # Composio integration layer (quick start + toolkit mapping) │ ├── integrations/ # API integration guides per tool │ └── REGISTRY.md # Tool index with capabilities ├── CONTRIBUTING.md @@ -167,7 +168,8 @@ This repository includes a tools registry for agent-compatible marketing tools. - **Tool discovery**: Read `tools/REGISTRY.md` to see available tools and their capabilities - **Integration details**: See `tools/integrations/{tool}.md` for API endpoints, auth, and common operations -- **MCP-enabled tools**: ga4, stripe, mailchimp, google-ads, resend, zapier, zoominfo, clay, supermetrics, coupler, outreach, crossbeam +- **MCP-enabled tools**: ga4, stripe, mailchimp, google-ads, resend, zapier, zoominfo, clay, supermetrics, coupler, outreach, crossbeam, composio +- **Composio** (integration layer): Adds MCP access to OAuth-heavy tools without native MCP servers (HubSpot, Salesforce, Meta Ads, LinkedIn Ads, Google Sheets, Slack, etc.). See `tools/integrations/composio.md` ### Registry Structure @@ -189,6 +191,8 @@ Skills reference relevant tools for implementation. For example: - `email-sequence` skill → customer-io, mailchimp, resend guides - `paid-ads` skill → google-ads, meta-ads, linkedin-ads guides +For tools without native MCP servers (HubSpot, Salesforce, Meta Ads, LinkedIn Ads, Google Sheets, Slack, Notion), Composio provides MCP access via a single server. See `tools/integrations/composio.md` for setup and `tools/composio/marketing-tools.md` for the full toolkit mapping. + ## Checking for Updates When using any skill from this repository: diff --git a/tools/REGISTRY.md b/tools/REGISTRY.md index 3f005f1..dbad514 100644 --- a/tools/REGISTRY.md +++ b/tools/REGISTRY.md @@ -85,6 +85,7 @@ Quick reference for AI agents to discover tool capabilities and integration meth | sanity | Headless CMS | ✓ | - | ✓ | ✓ | [sanity.md](integrations/sanity.md) | | contentful | Headless CMS | ✓ | - | ✓ | ✓ | [contentful.md](integrations/contentful.md) | | strapi | Headless CMS | ✓ | - | ✓ | ✓ | [strapi.md](integrations/strapi.md) | +| composio | Integration Layer | ✓ | ✓ | ✓ | ✓ | [composio.md](integrations/composio.md) | --- @@ -428,6 +429,16 @@ These tools have Model Context Protocol servers available, enabling direct agent To use MCP tools, ensure the appropriate MCP server is configured in your environment. +### Composio Integration + +[Composio](integrations/composio.md) provides managed OAuth and pre-built connectors for 500+ tools via a single MCP server. It adds MCP access to tools that don't have native MCP servers, including HubSpot, Salesforce, Meta Ads, LinkedIn Ads, Google Sheets, Slack, Notion, and more. + +- **Setup**: `npx @composio/mcp@latest setup` +- **Quick start**: See [tools/composio/README.md](composio/README.md) +- **Marketing tool mapping**: See [tools/composio/marketing-tools.md](composio/marketing-tools.md) + +Use Composio when you need MCP access to OAuth-heavy tools. Prefer native MCP servers (GA4, Stripe, Mailchimp, etc.) when available — they have deeper coverage. + --- ## Quick Start by Use Case diff --git a/tools/composio/README.md b/tools/composio/README.md new file mode 100644 index 0000000..213ee67 --- /dev/null +++ b/tools/composio/README.md @@ -0,0 +1,105 @@ +# Composio Quick Start + +Get MCP access to 500+ marketing tools through a single integration. + +## Prerequisites + +- Node.js 18+ +- Claude Code installed + +## Install + +```bash +npx @composio/mcp@latest setup +``` + +Verify by running `/mcp` in Claude Code — `composio` should appear in the server list. + +## Connect a Tool + +When you ask the agent to use a Composio-backed tool for the first time, it will provide a Connect Link. Open the link in your browser, authorize the app, and you're set. The connection persists across sessions. + +``` +You: "Get my top HubSpot contacts" +Agent: "Please connect HubSpot first: https://app.composio.dev/connect/..." +# Click the link → authorize → return to Claude Code +Agent: "Here are your top contacts: ..." +``` + +## Usage Examples + +### Pull CRM contacts + +``` +"Show me my 10 most recent HubSpot contacts with their deal stages" +``` + +### Get ad performance + +``` +"What's my Meta Ads spend and ROAS for the last 7 days?" +``` + +### Write to a spreadsheet + +``` +"Add a row to my 'Campaign Tracker' Google Sheet with today's LinkedIn Ads metrics" +``` + +### Cross-tool workflow + +``` +"Find Salesforce leads from this week and post a summary in Slack #new-leads" +``` + +## Available Marketing Tools + +See [marketing-tools.md](marketing-tools.md) for the full list of Composio toolkits mapped to marketing use cases. + +Key tools with new MCP access (no native MCP server in this repo): +- **HubSpot** — contacts, deals, companies, lists +- **Salesforce** — SOQL queries, leads, opportunities +- **Meta Ads** — campaigns, ad sets, insights +- **LinkedIn Ads** — campaigns, analytics +- **Google Sheets** — read, write, create spreadsheets +- **Slack** — messages, channels +- **Notion** — pages, databases +- **Klaviyo** — profiles, lists, campaigns +- **ActiveCampaign** — contacts, automations + +## Troubleshooting + +### "Tool not found" error + +The tool may not be connected yet. Ask the agent to connect it, or run: + +```bash +npx composio apps list +``` + +### Expired authentication + +OAuth tokens expire. If a tool stops working, re-authenticate: + +```bash +npx composio connections list # Find the connection +npx composio connections remove {id} # Remove it +# Then ask the agent to use the tool again to trigger re-auth +``` + +### Rate limit errors + +Composio has its own rate limits (free: 20K calls/mo, 10 req/sec). If you hit them: +- Reduce request frequency +- Upgrade your Composio plan +- Use native CLI tools for high-volume operations + +### MCP server not appearing + +Re-run the setup command: + +```bash +npx @composio/mcp@latest setup +``` + +Then restart Claude Code. diff --git a/tools/composio/marketing-tools.md b/tools/composio/marketing-tools.md new file mode 100644 index 0000000..7b399b9 --- /dev/null +++ b/tools/composio/marketing-tools.md @@ -0,0 +1,91 @@ +# Composio Marketing Tools + +Detailed mapping of Composio toolkits to marketing use cases. Organized by the same categories as [REGISTRY.md](../REGISTRY.md). + +## CRM + +| Composio Toolkit | Auth | Key Marketing Actions | Depth | +|-----------------|------|----------------------|-------| +| `HUBSPOT` | OAuth 2.0 | Get/create contacts, list deals by stage, get company info, manage lists, search contacts by property | Deep | +| `SALESFORCE` | OAuth 2.0 | Run SOQL queries, get/create leads, list opportunities, get account details, update records | Deep | + +## Email & SMS + +| Composio Toolkit | Auth | Key Marketing Actions | Depth | +|-----------------|------|----------------------|-------| +| `ACTIVECAMPAIGN` | API Key | Get contacts, list automations, add contacts to lists, get campaign stats | Medium | +| `KLAVIYO` | API Key | Get profiles, list segments, get campaign metrics, add to lists | Medium | +| `MAILCHIMP` | OAuth 2.0 | Get audiences, list campaigns, get campaign reports, add subscribers | Deep | +| `GMAIL` | OAuth 2.0 | Send emails, search inbox, read messages, manage labels | Deep | + +## Advertising + +| Composio Toolkit | Auth | Key Marketing Actions | Depth | +|-----------------|------|----------------------|-------| +| `FACEBOOKADS` | OAuth 2.0 | Get campaign insights, list ad sets, get ad performance, read audience data | Medium | +| `LINKEDIN` | OAuth 2.0 | Get campaign analytics, list campaigns, get company page stats | Medium | +| `GOOGLEADS` | OAuth 2.0 | Get campaign performance, list ad groups, keyword stats | Medium | + +## Productivity & Collaboration + +| Composio Toolkit | Auth | Key Marketing Actions | Depth | +|-----------------|------|----------------------|-------| +| `GOOGLESHEETS` | OAuth 2.0 | Read/write cells, create sheets, format ranges, append rows | Deep | +| `SLACK` | OAuth 2.0 | Send messages, read channels, upload files, search messages | Deep | +| `NOTION` | OAuth 2.0 | Read/create pages, query databases, update blocks, search | Deep | +| `AIRTABLE` | OAuth 2.0 | List/create/update records, query views, manage tables | Deep | + +## Commerce + +| Composio Toolkit | Auth | Key Marketing Actions | Depth | +|-----------------|------|----------------------|-------| +| `SHOPIFY` | OAuth 2.0 | Get products, list orders, get customer data, inventory levels | Deep | + +## Analytics + +| Composio Toolkit | Auth | Key Marketing Actions | Depth | +|-----------------|------|----------------------|-------| +| `GOOGLEANALYTICS` | OAuth 2.0 | Run reports, get real-time data, list properties | Medium | + +## Coverage Depth Guide + +- **Deep** — 20+ actions, covers most common operations, suitable for daily use +- **Medium** — 5-20 actions, covers core read operations and some writes +- **Shallow** — Under 5 actions, basic read-only access + +## Coverage vs. Native Tools + +This table shows where Composio adds value compared to what's already in the MarketingSkills registry: + +| Tool | Native MCP | Native CLI | Composio MCP | Recommendation | +|------|:----------:|:----------:|:------------:|----------------| +| HubSpot | - | ✓ | ✓ | **Use Composio** — adds MCP access | +| Salesforce | - | ✓ | ✓ | **Use Composio** — adds MCP access | +| Meta Ads | - | ✓ | ✓ | **Use Composio** — adds MCP access | +| LinkedIn Ads | - | ✓ | ✓ | **Use Composio** — adds MCP access | +| Google Sheets | - | - | ✓ | **Use Composio** — only MCP option | +| Slack | - | - | ✓ | **Use Composio** — only MCP option | +| Notion | - | - | ✓ | **Use Composio** — only MCP option | +| Airtable | - | - | ✓ | **Use Composio** — only MCP option | +| ActiveCampaign | - | ✓ | ✓ | **Use Composio** — adds MCP access | +| Klaviyo | - | ✓ | ✓ | **Use Composio** — adds MCP access | +| Shopify | - | ✓ | ✓ | **Use Composio** — adds MCP access | +| Gmail | - | - | ✓ | **Use Composio** — only MCP option | +| GA4 | ✓ | ✓ | ✓ | **Use native** — deeper coverage | +| Stripe | ✓ | ✓ | ✓ | **Use native** — deeper coverage | +| Mailchimp | ✓ | ✓ | ✓ | **Use native** — deeper coverage | +| Google Ads | ✓ | ✓ | ✓ | **Use native** — deeper coverage | + +## Toolkit Reference + +Each Composio toolkit name maps to its `TOOL_NAME` identifier used in the Composio platform. When searching for available actions, use these exact names: + +```bash +# List all actions for a toolkit +npx composio actions list --app HUBSPOT + +# Search for specific actions +npx composio actions list --app FACEBOOKADS --search "insights" +``` + +For the full integration guide including setup, pricing, and limitations, see [composio.md](../integrations/composio.md). diff --git a/tools/integrations/composio.md b/tools/integrations/composio.md new file mode 100644 index 0000000..a3e79d8 --- /dev/null +++ b/tools/integrations/composio.md @@ -0,0 +1,190 @@ +# Composio + +Managed OAuth and pre-built tool connectors for 500+ apps via a single MCP server. Provides agent-native access to marketing tools that lack native MCP support. + +## Capabilities + +| Integration | Available | Notes | +|-------------|-----------|-------| +| API | ✓ | REST API for managing connections and triggering actions | +| MCP | ✓ | Single MCP server exposes all connected tools | +| CLI | ✓ | `npx composio` for managing apps, connections, and actions | +| SDK | ✓ | TypeScript and Python SDKs | + +## Authentication + +- **Type**: OAuth 2.0 (per-tool, managed by Composio) or API Key +- **Setup**: `npx @composio/mcp@latest setup` to install, then authenticate each tool via Connect Link in browser +- **API Key** (optional): `COMPOSIO_API_KEY` env var for advanced/team usage + +Composio handles OAuth token management, refresh, and storage for all connected tools. Individual tool auth types are listed in the Marketing Tools table below. + +## When to Use Composio vs. Native Tools + +Composio is an **alternative integration method**, not a replacement. Use this decision guide: + +| Scenario | Use | +|----------|-----| +| Tool has native MCP server (GA4, Stripe, Mailchimp) | Native MCP server | +| Tool has CLI but no MCP (Meta Ads, LinkedIn Ads, HubSpot) | Composio for MCP access | +| OAuth-heavy tool with no CLI (Google Sheets, Slack, Notion) | Composio | +| Need deep, customized integration | Native API + CLI | +| Need quick read/write access across many tools | Composio | +| Tool not covered by Composio | Native API guide | + +## Setup + +### 1. Install the MCP server + +```bash +npx @composio/mcp@latest setup +``` + +This adds the Composio MCP server to your Claude Code configuration. + +### 2. Verify installation + +In Claude Code, run `/mcp` to confirm `composio` appears in your MCP server list. + +### 3. Authenticate a tool + +When you first use a Composio-backed tool, you'll receive a Connect Link. Open it in your browser to complete OAuth. The connection persists across sessions. + +``` +# Example: connect HubSpot +> "Pull my top 10 HubSpot contacts" +# Agent will prompt: "Please authenticate HubSpot: [Connect Link]" +# Click link → authorize → done +``` + +### 4. API key (optional) + +For advanced usage or team setups, set your Composio API key: + +```bash +export COMPOSIO_API_KEY=your_key_here +``` + +## Marketing Tools Available via Composio + +### New MCP Coverage + +These tools have API guides in this repo but **no native MCP server**. Composio adds MCP access: + +| Tool | Composio Toolkit | Auth Type | Coverage Depth | +|------|-----------------|-----------|----------------| +| HubSpot | `HUBSPOT` | OAuth 2.0 | Deep (contacts, deals, companies, lists, email) | +| Salesforce | `SALESFORCE` | OAuth 2.0 | Deep (SOQL, objects, leads, opportunities) | +| Meta Ads | `FACEBOOKADS` | OAuth 2.0 | Medium (campaigns, ad sets, insights) | +| LinkedIn Ads | `LINKEDIN` | OAuth 2.0 | Medium (campaigns, analytics, company pages) | +| Google Sheets | `GOOGLESHEETS` | OAuth 2.0 | Deep (read, write, create, format) | +| Slack | `SLACK` | OAuth 2.0 | Deep (messages, channels, files) | +| Notion | `NOTION` | OAuth 2.0 | Deep (pages, databases, blocks) | +| Airtable | `AIRTABLE` | OAuth 2.0 | Deep (records, tables, views) | +| ActiveCampaign | `ACTIVECAMPAIGN` | API Key | Medium (contacts, lists, automations) | +| Klaviyo | `KLAVIYO` | API Key | Medium (profiles, lists, campaigns) | +| Shopify | `SHOPIFY` | OAuth 2.0 | Deep (products, orders, customers) | +| Gmail | `GMAIL` | OAuth 2.0 | Deep (read, send, labels, search) | + +### Alternative to Existing Tools + +These tools **already have native MCP or CLI** in this repo. Composio provides an alternative path: + +| Tool | Native Integration | Composio Toolkit | When to Use Composio | +|------|-------------------|-----------------|---------------------| +| Mailchimp | MCP ✓, CLI ✓ | `MAILCHIMP` | If native MCP setup fails | +| Google Ads | MCP ✓, CLI ✓ | `GOOGLEADS` | If OAuth is simpler via Composio | +| Stripe | MCP ✓, CLI ✓ | `STRIPE` | Prefer native (deeper coverage) | +| GA4 | MCP ✓, CLI ✓ | `GOOGLEANALYTICS` | Prefer native (deeper coverage) | + +## Common Agent Operations + +### List available tools + +```bash +# Via Composio CLI +npx composio apps list +``` + +### Check connection status + +```bash +npx composio connections list +``` + +### Trigger an action programmatically + +```bash +POST https://backend.composio.dev/api/v1/actions/{action_id}/execute + +{ + "connectedAccountId": "account_xxx", + "input": { + "query": "contact email = user@example.com" + } +} +``` + +### Disconnect a tool + +```bash +npx composio connections remove {connection_id} +``` + +## Example Workflows + +### Pull CRM data into a spreadsheet + +``` +> "Get my top 20 HubSpot contacts by last activity and add them to a Google Sheet" +``` +Agent uses Composio's `HUBSPOT` to fetch contacts and `GOOGLESHEETS` to write rows. + +### Cross-platform ad reporting + +``` +> "Compare my Meta Ads and LinkedIn Ads spend this month" +``` +Agent uses `FACEBOOKADS` and `LINKEDIN` toolkits to pull campaign data. + +### Notify team about new leads + +``` +> "Get my Salesforce leads from today and post a summary in Slack #sales" +``` +Agent uses `SALESFORCE` to read leads and `SLACK` to post messages. + +## Limitations + +- **Coverage depth varies** — some toolkits expose hundreds of actions (HubSpot, Google Sheets), others only a handful +- **No customization** — you can't modify Composio's action schemas or add custom endpoints +- **Vendor dependency** — if Composio's servers are down, all connected tools are unavailable +- **Rate limits apply** — Composio enforces its own rate limits on top of each tool's native limits +- **OAuth tokens** — managed by Composio; you don't control token refresh or storage +- **Action naming** — Composio action names may differ from native API terminology + +## Pricing + +| Plan | Monthly Price | API Calls | Notes | +|------|--------------|-----------|-------| +| Free | $0 | 20,000 | Good for exploration and personal use | +| Growth | $29 | 200,000 | For regular use across multiple tools | +| Business | $229 | 2,000,000 | For teams and heavy automation | + +## Rate Limits + +- Free tier: 20,000 calls/month, 10 req/sec +- Growth tier: 200,000 calls/month, 50 req/sec +- Business tier: 2,000,000 calls/month, 100 req/sec + +## See Also + +- [Quick start guide](../composio/README.md) — install, connect, and use in 5 minutes +- [Marketing tools mapping](../composio/marketing-tools.md) — detailed toolkit-to-category reference + +## Relevant Skills + +- analytics-tracking (cross-platform data via Composio connectors) +- email-sequence (ActiveCampaign, Klaviyo access) +- paid-ads (Meta Ads, LinkedIn Ads MCP access) +- referral-program (Shopify integration)