Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 163 lines 5.19 KB
Rendered Raw
1 # Connect Clients Sync
2
3 Syncs AI client definitions from the dashboard repo (`ComposioHQ/composio_dashboard`) to the Composio Connect docs page.
4
5 ## When This Runs
6
7 Triggered by `repository_dispatch` from dashboard production deploys, or manually via `workflow_dispatch`. Creates a PR if client definitions have changed.
8
9 ## Source of Truth
10
11 The dashboard repo's client definitions file:
12 ```
13 ComposioHQ/composio_dashboard
14 src/app/(connect)/[org]/~/connect/clients/_components/client-definitions.ts
15 ```
16
17 This file contains the `ALL_CLIENTS` array with every client's:
18 - `id`, `name`, `description`, `icon`, `category`
19 - `authMethods` with step-by-step setup instructions
20 - Auth types: `oauth` and/or `api-key`
21
22 ## Target File
23
24 ```
25 docs/content/docs/composio-connect.mdx
26 ```
27
28 ## Process
29
30 1. Fetch `client-definitions.ts` from `ComposioHQ/composio_dashboard` (main branch) using the GitHub API
31 2. Read the current `docs/content/docs/composio-connect.mdx`
32 3. Compare the client list, categories, and setup steps
33 4. If there are differences, update `composio-connect.mdx` to match the dashboard
34
35 ## MDX Structure
36
37 The page uses `<ConnectFlow>` and `<ConnectClientOption>` components:
38
39 ```mdx
40 <ConnectFlow>
41
42 <ConnectClientOption id="client-id" name="Client Name" description="..." icon="/images/clients/logo.svg" category="popular|ide|other">
43
44 <Steps>
45 <Step>
46 <StepTitle>Step title</StepTitle>
47
48 Step description.
49
50 </Step>
51 </Steps>
52
53 </ConnectClientOption>
54
55 </ConnectFlow>
56 ```
57
58 ### Category Mapping
59
60 Only these 4 clients should have `category="popular"` (shown as tabs):
61 - `claude-code`
62 - `codex`
63 - `openclaw`
64 - `claude-desktop`
65
66 All other clients go in the dropdown:
67 - Dashboard `IDEs` category → `category="ide"`
68 - Everything else → `category="other"`
69
70 ### Auth Method Selection
71
72 Show **all auth methods** from the dashboard. When a client has both OAuth and API key methods, use `<Tabs>` to let the user choose:
73
74 ```mdx
75 <Tabs items={["OAuth (recommended)", "API Key"]}>
76 <Tab value="OAuth (recommended)">
77
78 <Steps>
79 <Step>
80 <StepTitle>Step title</StepTitle>
81
82 OAuth step content.
83
84 </Step>
85 </Steps>
86
87 </Tab>
88 <Tab value="API Key">
89
90 <Steps>
91 <Step>
92 <StepTitle>Get your API key</StepTitle>
93
94 Open the [Composio dashboard](https://dashboard.composio.dev) and click **AI Clients** in the sidebar. Select your client and copy your API key.
95
96 </Step>
97 <Step>
98 <StepTitle>Step title</StepTitle>
99
100 API key step content.
101
102 </Step>
103 </Steps>
104
105 </Tab>
106 </Tabs>
107 ```
108
109 For clients with only one auth method (OAuth-only like Claude Desktop/ChatGPT, or API-key-only like n8n), use `<Steps>` directly without `<Tabs>`.
110
111 For API key methods, always prepend this step before the client-specific steps:
112
113 ```mdx
114 <Step>
115 <StepTitle>Get your API key</StepTitle>
116
117 Open the [Composio dashboard](https://dashboard.composio.dev) and click **AI Clients** in the sidebar. Select your client and copy your API key.
118
119 </Step>
120 ```
121
122 Use the tab labels from the dashboard's `authMethods[].label` field (e.g., "OAuth (recommended)", "API Key").
123
124 ### Code Blocks
125
126 - Use `YOUR_API_KEY` as the placeholder (not the `${token}` variable from the dashboard)
127 - Use `https://connect.composio.dev/mcp` as the MCP URL (not the `${MCP_URL}` variable)
128 - Detect the correct language: `bash` for CLI commands, `toml` for TOML config, `json` for JSON config, `text` for plain text/prompts
129 - Include the `title` attribute from the dashboard's `label` field when present
130
131 ### Client Logos
132
133 Client logos live in `docs/public/images/clients/`. When syncing, **always check for new or updated logos**:
134
135 1. Fetch the logo file list from the dashboard repo's `public/images/clients/` and `public/images/logos/` directories using the GitHub API
136 2. For each client in the definitions, check if its logo already exists in `docs/public/images/clients/`
137 3. If a logo is missing or has been updated, download it from the dashboard repo and save it to `docs/public/images/clients/`
138 4. For clients that need dark mode variants (white-on-dark icons), check if a `-dark` variant exists in the dashboard. If not, check if the existing icon works on dark backgrounds. If it doesn't, create a dark variant by changing fills to white
139 5. Reference logos as `/images/clients/filename.ext` in the MDX, and use `iconDark` prop when a dark variant is available
140
141 The dashboard stores logos at:
142 - `public/images/clients/` (primary location)
143 - `public/images/logos/` (fallback location)
144
145 ### Client Order
146
147 Popular tab clients come first (in the order listed above), then other clients in the order they appear in the dashboard's `ALL_CLIENTS` array.
148
149 ## What NOT to Change
150
151 - Do NOT modify the frontmatter (title, description) unless new clients need to be added to keywords
152 - Do NOT modify the intro text ("Give any AI agent...")
153 - Do NOT modify the "Connect your apps" section at the bottom
154 - Do NOT modify `connect-flow.tsx` or other component files
155 - Do NOT modify `source.ts` or `mdx-components.tsx`
156
157 ## Rules
158
159 - Only modify `docs/content/docs/composio-connect.mdx` and files in `docs/public/images/clients/`
160 - Match the exact step text from the dashboard (resolve template variables like `${MCP_URL}` and `${token}`)
161 - If a client has `comingSoon: true` in the dashboard, skip it
162 - If no changes are needed, make no file changes
163 - Keep the `keywords` frontmatter array updated with all client names (lowercase)