Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Add MCP, Resources, Migration Guide, and Troubleshooting sections
Sushmithamalleshdac857cb343b
diff --git a/fumadocs/content/docs/cli.mdx b/fumadocs/content/docs/cli.mdxnew file mode 100644index 000000000..7e753f756--- /dev/null+++ b/fumadocs/content/docs/cli.mdx@@ -0,0 +1,131 @@+---+title: CLI+description: Generate type definitions and manage authentication+---++The Composio CLI helps you generate type-safe code and manage your Composio workspace.++## Installation++Install the Composio CLI using the installation script:++```bash+curl -fsSL https://composio.dev/install | bash+```++Or using wget:+```bash+wget -qO- https://composio.dev/install | bash+```++## Authentication++Manage your Composio authentication directly from the terminal.++### Login++Authenticate with your Composio account:++```bash+composio login+```++This opens your browser to complete authentication and stores your API key locally.++To authenticate without opening a browser (useful for SSH/remote sessions):++```bash+composio login --no-browser+```++This displays a URL to manually open in your browser.++### Check authentication status++Verify your current authentication:++```bash+composio whoami+```++This displays your current API key or indicates if you're not authenticated.++### Logout++Remove stored authentication:++```bash+composio logout+```++## Generate type definitions++Generate TypeScript or Python type definitions for all Composio tools. These types provide type safety when using direct tool execution (`composio.tools.execute()`), helping you pass the correct parameters and catch errors early.++### Auto-detect and generate++The CLI auto-detects your project language.+In your project directory:++```bash+composio generate+```++For TypeScript projects only, include individual tool types:+```bash+composio generate --type-tools+```++The CLI automatically:+- Detects your project type (Python or TypeScript)+- Generates appropriate type definitions++### Specify output directory++```bash+composio generate --output-dir ./my-types+```++### Language-specific commands++For explicit control, use language-specific commands:++<Tabs items={['TypeScript', 'Python']}>+ <Tab value="TypeScript">+ Basic generation:+ ```bash+ composio ts generate+ ```++ Generate as single file:+ ```bash+ composio ts generate --compact+ ```++ Include individual tool types:+ ```bash+ composio ts generate --type-tools+ ```++ Generate both .ts and .js files:+ ```bash+ composio ts generate --transpiled+ ```++ Custom output directory:+ ```bash+ composio ts generate --output-dir ./my-types+ ```+ </Tab>+ <Tab value="Python">+ Basic generation:+ ```bash+ composio py generate+ ```++ Custom output directory:+ ```bash+ composio py generate --output-dir ./my_types+ ```+ </Tab>+</Tabs>diff --git a/fumadocs/content/docs/debugging-info.mdx b/fumadocs/content/docs/debugging-info.mdxnew file mode 100644index 000000000..370ae178b--- /dev/null+++ b/fumadocs/content/docs/debugging-info.mdx@@ -0,0 +1,45 @@+---+title: Debugging Info+description: Share your debugging info with Composio team for faster issue resolution+---++Your debugging info is tied to your project and it helps us trace what happened and debug the issue faster.++## Finding Your Debugging Info++Navigate to your project settings to find your debugging information:++<Figure src="/images/project-settings.jpeg" alt="Project Settings Debugging Info" />++<Figure src="/images/debugging-info.png" alt="Debugging Info Location" />++## What to Share++When reaching out for support, share these identifiers:++```+@project_id: pr_xxxxxxxxxxxxx+@org_id: ok_xxxxxxxxxxxxx+@org_member_email: [email protected]+```++The identifiers with `pr_` (project) and `ok_` (organization) prefixes let us quickly check your logs inside our internal tracing tools, helping us resolve issues faster.++## Getting Help++import { MessageCircle, Github, Bug, Mail } from 'lucide-react';++<Cards>+ <Card title="Join Discord" href="https://discord.gg/composio" icon={<MessageCircle />}>+ Get basic support from the community and Composio team+ </Card>+ <Card title="GitHub Discussions" href="https://github.com/ComposioHQ/composio/discussions" icon={<Github />}>+ Request new tools and share feedback+ </Card>+ <Card title="File an Issue" href="https://github.com/ComposioHQ/composio/issues" icon={<Bug />}>+ Report SDK issues and bugs+ </Card>+ <Card title="Contact Support" href="mailto:[email protected]" icon={<Mail />}>+ Reach out for dedicated support channels on Growth and Enterprise plans+ </Card>+</Cards>diff --git a/fumadocs/content/docs/mcp-providers.mdx b/fumadocs/content/docs/mcp-providers.mdxnew file mode 100644index 000000000..69b08b74b--- /dev/null+++ b/fumadocs/content/docs/mcp-providers.mdx@@ -0,0 +1,254 @@+---+title: Providers+description: Connect MCP servers to AI frameworks+---++Integrate your MCP servers with popular AI SDKs and frameworks.++<Callout type="info">+Composio MCP servers only support Streamable HTTP transport.+</Callout>++## Anthropic SDK++Use MCP servers with the Anthropic Claude API.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+from anthropic import Anthropic+from composio import Composio++# Initialize clients+composio = Composio()+anthropic = Anthropic(api_key="your-anthropic-api-key")++# Create MCP server with GitHub and Linear tools+server = composio.mcp.create(+ name="dev-workflow-server",+ toolkits=[+ {"toolkit": "github", "auth_config": "ac_github_id"},+ {"toolkit": "linear", "auth_config": "ac_linear_id"}+ ],+ allowed_tools=["GITHUB_LIST_PRS", "GITHUB_CREATE_COMMENT", "LINEAR_CREATE_ISSUE"]+)++# Generate MCP instance for user+instance = server.generate("[email protected]")++# Use MCP with Anthropic to manage development workflow+response = anthropic.beta.messages.create(+ model="claude-sonnet-4-5",+ system="You are a helpful assistant with access to GitHub and Linear tools. Use these tools to help manage development workflows. Do not ask for confirmation before using the tools.",+ max_tokens=1000,+ messages=[{+ "role": "user",+ "content": "Check my GitHub PRs for review comments, create Linear tasks for any requested changes, and update the PR descriptions with task links"+ }],+ mcp_servers=[{+ "type": "url",+ "url": instance['url'],+ "name": "composio-mcp-server"+ }],+ betas=["mcp-client-2025-04-04"] # Enable MCP beta+)++print(response.content)+```+ </Tab>+ <Tab value="TypeScript">+```typescript+import Anthropic from '@anthropic-ai/sdk';+import { Composio } from '@composio/core';++// Initialize clients+const composio = new Composio();+const anthropic = new Anthropic({+ apiKey: process.env.ANTHROPIC_API_KEY,+});++// Create MCP server with Google Sheets tools+const server = await composio.mcp.create(+ "analytics-server",+ {+ toolkits: [+ { toolkit: "googlesheets", authConfigId: "ac_sheets_id" }+ ],+ allowedTools: ["GOOGLESHEETS_GET_DATA", "GOOGLESHEETS_UPDATE_DATA", "GOOGLESHEETS_CREATE_SHEET"]+ }+);++// Generate MCP instance for user+const instance = await server.generate("[email protected]");++// Use MCP with Anthropic for spreadsheet operations+const response = await anthropic.beta.messages.create({+ model: "claude-sonnet-4-5",+ system: "You are a helpful assistant with access to Google Sheets tools. Use these tools to analyze and manage spreadsheet data. Do not ask for confirmation before using the tools.",+ max_tokens: 1000,+ messages: [{+ role: "user",+ content: "Analyze the sales data in my Google Sheets 'Q4 Revenue' spreadsheet, calculate month-over-month growth, and add a new summary sheet with visualizations"+ }],+ mcp_servers: [{+ type: "url",+ url: instance.url,+ name: "composio-mcp-server"+ }],+ betas: ["mcp-client-2025-04-04"] // Enable MCP beta+});++console.log(response.content);+```+ </Tab>+</Tabs>++## OpenAI SDK++Integrate MCP servers with OpenAI GPT models.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+from openai import OpenAI+from composio import Composio++# Initialize clients+composio = Composio()+openai = OpenAI(api_key="your-openai-api-key")++# Create MCP server with Google Sheets and Notion tools+server = composio.mcp.create(+ name="data-docs-server",+ toolkits=[+ {"toolkit": "googlesheets", "auth_config": "ac_sheets_id"},+ {"toolkit": "notion", "auth_config": "ac_notion_id"}+ ],+ allowed_tools=["GOOGLESHEETS_GET_DATA", "GOOGLESHEETS_UPDATE_DATA", "NOTION_CREATE_PAGE"]+)++# Generate MCP instance for user+instance = server.generate("[email protected]")++# Use MCP with OpenAI for data management+response = openai.responses.create(+ model="gpt-5",+ tools=[+ {+ "type": "mcp",+ "server_label": "composio-server",+ "server_description": "Composio MCP server with Google Sheets and Notion integrations",+ "server_url": instance['url'],+ "require_approval": "never",+ },+ ],+ input="Export the Q4 metrics from Google Sheets and create a comprehensive Notion page with charts and analysis",+)++print("OpenAI MCP Response:", response.output_text)+```+ </Tab>+ <Tab value="TypeScript">+```typescript+import OpenAI from 'openai';+import { Composio } from '@composio/core';++// Initialize clients+const composio = new Composio();+const openai = new OpenAI({+ apiKey: process.env.OPENAI_API_KEY,+});++// Create MCP server with Linear and Notion tools+const server = await composio.mcp.create(+ "project-docs-server",+ {+ toolkits: [+ { toolkit: "linear", authConfigId: "ac_linear_id" },+ { toolkit: "notion", authConfigId: "ac_notion_id" }+ ],+ allowedTools: ["LINEAR_LIST_ISSUES", "LINEAR_GET_ISSUE", "NOTION_CREATE_PAGE"]+ }+);++// Generate MCP instance for user+const instance = await server.generate("[email protected]");++// Use MCP with OpenAI for project documentation+const response = await openai.responses.create({+ model: "gpt-5",+ tools: [+ {+ type: "mcp",+ server_label: "composio-server",+ server_description: "Composio MCP server with Linear and Notion integrations",+ server_url: instance.url,+ require_approval: "never",+ },+ ],+ input: "Find all completed Linear issues from this sprint and create a Notion page documenting the release notes",+});++console.log("OpenAI MCP Response:", response.output_text);+```+ </Tab>+</Tabs>++## Mastra++Use MCP servers with Mastra framework.++```typescript+import { MCPClient } from "@mastra/mcp";+import { openai } from "@ai-sdk/openai";+import { Agent } from "@mastra/core/agent";+import { Composio } from "@composio/core";++// Initialize Composio+const composio = new Composio();++// Create MCP server with GitHub, Linear, and Notion tools+const server = await composio.mcp.create(+ "dev-automation-server",+ {+ toolkits: [+ { toolkit: "github", authConfigId: "ac_github_id" },+ { toolkit: "linear", authConfigId: "ac_linear_id" },+ { toolkit: "notion", authConfigId: "ac_notion_id" }+ ],+ allowedTools: [+ "GITHUB_LIST_ISSUES", "GITHUB_CREATE_ISSUE",+ "LINEAR_CREATE_ISSUE", "LINEAR_UPDATE_ISSUE",+ "NOTION_CREATE_PAGE", "NOTION_UPDATE_PAGE"+ ]+ }+);++// Generate MCP instance for user+const instance = await server.generate("[email protected]");++// Create MCP client with Composio server+export const mcpClient = new MCPClient({+ id: "composio-mcp-client",+ servers: {+ composio: { url: new URL(instance.url) },+ }+});++// Create a development workflow agent+export const devAgent = new Agent({+ name: "Dev Assistant",+ description: "AI assistant for development workflow automation",+ instructions: "Help manage GitHub repos, Linear issues, and Notion documentation.",+ model: openai("gpt-4-turbo"),+ tools: await mcpClient.getTools()+});++// Example: Automate development workflow+(async () => {+ const response = await devAgent.generate(+ "Review open GitHub issues, create Linear tasks for bugs labeled 'priority', and update the Notion roadmap page"+ );+ console.log(response.text);+})();+```diff --git a/fumadocs/content/docs/mcp-quickstart.mdx b/fumadocs/content/docs/mcp-quickstart.mdxnew file mode 100644index 000000000..ee343516f--- /dev/null+++ b/fumadocs/content/docs/mcp-quickstart.mdx@@ -0,0 +1,263 @@+---+title: Quickstart+description: Create your first MCP server+---++[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open-source standard for connecting AI applications to external tools. All the 500+ tools available in Composio are also available as MCP servers.++Composio lets you create MCP servers that handle authentication (OAuth, API keys), generate unique URLs for each user, and control which tools are exposed. You can combine multiple toolkits in a single server.++<Callout type="info">+Composio MCP servers only support Streamable HTTP transport.+</Callout>++## Install the SDK++First, install the Composio SDK for your preferred language:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```bash+pip install composio+```+ </Tab>+ <Tab value="TypeScript">+```bash+npm install @composio/core+```+ </Tab>+</Tabs>++## Create an MCP server++<Steps>+ <Step>+ ### Initialize Composio++ <Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+from composio import Composio++# Initialize Composio+composio = Composio(api_key="YOUR_API_KEY")+```+ </Tab>+ <Tab value="TypeScript">+```typescript+import { Composio } from '@composio/core';++// Initialize Composio+const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY+});+```+ </Tab>+ </Tabs>+ </Step>++ <Step>+ ### Create server configuration++ <Callout type="warn">+ **Before you begin:** [Create an auth configuration](/docs/authenticating-tools#creating-an-auth-config) for your toolkit.+ </Callout>++ Create an MCP server with your auth config. You can also set list of specific tools to enable across all toolkits.++ <Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+# Create MCP server with multiple toolkits+server = composio.mcp.create(+ name="mcp-config-73840", # Pick a unique name for your MCP server+ toolkits=[+ {+ "toolkit": "gmail",+ "auth_config": "ac_xyz123" # Your Gmail auth config ID+ },+ {+ "toolkit": "googlecalendar",+ "auth_config": "ac_abc456" # Your Google Calendar auth config ID+ }+ ],+ allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL", "GOOGLECALENDAR_EVENTS_LIST"]+)++print(f"Server created: {server.id}")+print(server.id)+```+ </Tab>+ <Tab value="TypeScript">+```typescript+// Create MCP server with multiple toolkits+const server = await composio.mcp.create("mcp-config-73840", { // Pick a unique name for your MCP server+ toolkits: [+ {+ authConfigId: "ac_xyz123", // Your Gmail auth config ID+ toolkit: "gmail"+ },+ {+ authConfigId: "ac_abc456", // Your Google Calendar auth config ID+ toolkit: "googlecalendar"+ }+ ],+ allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL", "GOOGLECALENDAR_EVENTS_LIST"]+});++console.log(`Server created: ${server.id}`);+console.log(server.id);+```+ </Tab>+ </Tabs>++ <Callout type="info">+ **Alternative:** You can also create and manage MCP configs directly from the [Composio dashboard → MCP Configs](https://platform.composio.dev?next_page=/mcp-configs).+ </Callout>+ </Step>++ <Step>+ ### Generate user URLs++ <Callout type="warn">+ **Before generating URLs:** Users must authenticate with the toolkits configured in your MCP server. See [hosted authentication](/docs/authenticating-tools#hosted-authentication-connect-link) for how to connect user accounts.+ </Callout>++ Get server URLs for your users to connect:++ <Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+# Generate server instance for user+instance = composio.mcp.generate(user_id="user-73840", mcp_config_id=server.id) # Use the user ID for which you created the connected account++print(f"MCP Server URL: {instance['url']}")+```+ </Tab>+ <Tab value="TypeScript">+```typescript+// Generate server instance for user+const instance = await composio.mcp.generate("user-73840", server.id); // Use the user ID for which you created the connected account++console.log("MCP Server URL:", instance.url);+```+ </Tab>+ </Tabs>++ <Callout type="info">+ If users haven't authenticated, the MCP server will still generate a URL but tools requiring authentication won't work until the user connects their accounts.+ </Callout>+ </Step>++ <Step>+ ### Use with AI providers++ Use the MCP server URL with your AI provider:++ <Tabs items={['OpenAI (Python)', 'Anthropic (Python)', 'Mastra (TypeScript)']}>+ <Tab value="OpenAI (Python)">+```python+from openai import OpenAI++# Initialize OpenAI client+client = OpenAI(api_key="your-openai-api-key")++# Use the MCP server URL you generated+mcp_server_url = "https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?include_composio_helper_actions=true&user_id=YOUR_USER_ID"++# Use MCP with OpenAI Responses API+response = client.responses.create(+ model="gpt-5",+ tools=[+ {+ "type": "mcp",+ "server_label": "composio-server",+ "server_description": "Composio MCP server for Gmail and Calendar integrations",+ "server_url": mcp_server_url,+ "require_approval": "never",+ },+ ],+ input="What meetings do I have tomorrow? Also check if I have any urgent emails",+)++print("OpenAI MCP Response:", response.output_text)+```+ </Tab>+ <Tab value="Anthropic (Python)">+```python+from anthropic import Anthropic++# Initialize Anthropic client+client = Anthropic(api_key="your-anthropic-api-key")++# Use the MCP server URL you generated+mcp_server_url = "https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?include_composio_helper_actions=true&user_id=YOUR_USER_ID"++# Use MCP with Anthropic (beta feature)+response = client.beta.messages.create(+ model="claude-sonnet-4-5",+ system="You are a helpful assistant with access to various tools through MCP. Use these tools to help the user. Do not ask for confirmation before using the tools.",+ max_tokens=1000,+ messages=[{+ "role": "user",+ "content": "What meetings do I have tomorrow? Also check if I have any urgent emails"+ }],+ mcp_servers=[{+ "type": "url",+ "url": mcp_server_url,+ "name": "composio-gmail-calendar-mcp-server"+ }],+ betas=["mcp-client-2025-04-04"] # Enable MCP beta+)++print(response.content)+```+ </Tab>+ <Tab value="Mastra (TypeScript)">+```typescript+import { MCPClient } from "@mastra/mcp";+import { openai } from "@ai-sdk/openai";+import { Agent } from "@mastra/core/agent";++// Use the MCP server URL you generated+const MCP_URL = "https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?include_composio_helper_actions=true&user_id=YOUR_USER_ID";++export const client = new MCPClient({+ id: "docs-mcp-client",+ servers: {+ composio: { url: new URL(MCP_URL) },+ }+});++export const agent = new Agent({+ name: "Assistant",+ description: "Helpful AI with MCP tools",+ instructions: "Use the MCP tools to answer.",+ model: openai("gpt-4-turbo"),+ tools: await client.getTools()+});++(async () => {+ const res = await agent.generate("What meetings do I have tomorrow? Also check if I have any urgent emails");+ console.log(res.text);+})();+```+ </Tab>+ </Tabs>+ </Step>+</Steps>++## Next steps++<Cards>+ <Card title="Server management" href="/docs/mcp-server-management">+ Create and manage MCP servers+ </Card>+ <Card title="Providers" href="/docs/mcp-providers">+ Use with Anthropic, OpenAI, and other frameworks+ </Card>+</Cards>++<Callout type="info">+Need help? Join our [Discord](https://discord.com/invite/composio) or [raise an issue on GitHub](https://github.com/ComposioHQ/composio/issues/new?labels=bug).+</Callout>diff --git a/fumadocs/content/docs/mcp-server-management.mdx b/fumadocs/content/docs/mcp-server-management.mdxnew file mode 100644index 000000000..4725e952b--- /dev/null+++ b/fumadocs/content/docs/mcp-server-management.mdx@@ -0,0 +1,284 @@+---+title: Server management+description: Create, update, and manage MCP servers+---++This guide covers all server management operations for MCP servers.++## Create a server++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+server = composio.mcp.create(+ name="my-gmail-server",+ toolkits=[{+ "toolkit": "gmail",+ "auth_config": "ac_xyz123"+ }],+ allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]+)++print(f"Created server: {server.id}")+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const server = await composio.mcp.create(+ "my-gmail-server",+ {+ toolkits: [+ {+ authConfigId: "ac_xyz123",+ toolkit: "gmail"+ }+ ],+ allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],+ manuallyManageConnections: false+ }+);++console.log(`Created server: ${server.id}`);+```+ </Tab>+</Tabs>++## List servers++Find and filter your MCP servers.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+# List all servers+servers = composio.mcp.list()+print(f"Found {len(servers['items'])} servers")++# Filter by toolkit+gmail_servers = composio.mcp.list(+ toolkits="gmail",+ limit=20+)++# Filter by name+production_servers = composio.mcp.list(+ name="production"+)+```+ </Tab>+ <Tab value="TypeScript">+```typescript+// List all servers+const servers = await composio.mcp.list({+ limit: 10,+ page: 1,+ authConfigs: [],+ toolkits: []+});+console.log(`Found ${servers.items.length} servers`);++// Filter by toolkit+const gmailServers = await composio.mcp.list({+ limit: 20,+ page: 1,+ authConfigs: [],+ toolkits: ["gmail"]+});++// Filter by name+const productionServers = await composio.mcp.list({+ limit: 10,+ page: 1,+ authConfigs: [],+ toolkits: [],+ name: "production"+});+```+ </Tab>+</Tabs>++## Get server details++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+# Get by ID+server = composio.mcp.get("mcp_server_id")+print(f"Server name: {server.name}")+print(f"Toolkits: {server.toolkits}")+```+ </Tab>+ <Tab value="TypeScript">+```typescript+// Get by ID+const server = await composio.mcp.get("mcp_server_id");++console.log(`Server: ${server.name}`);+console.log(`Toolkits: ${server.toolkits}`);+```+ </Tab>+</Tabs>++## Update a server++Modify server configuration, tools, or auth configs.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+updated = composio.mcp.update(+ server_id="mcp_server_id",+ name="updated-name",+ allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEARCH_EMAILS"]+)+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const updated = await composio.mcp.update(+ "mcp_server_id",+ {+ name: "updated-name",+ toolkits: [+ {+ toolkit: "gmail",+ authConfigId: "ac_new_config"+ }+ ],+ allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEARCH_EMAILS"],+ manuallyManageConnections: false+ }+);++console.log(updated);+```+ </Tab>+</Tabs>++## Delete a server++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+result = composio.mcp.delete("mcp_server_id")+if result['deleted']:+ print("Server deleted successfully")+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const result = await composio.mcp.delete("mcp_server_id");+if (result.deleted) {+ console.log("Server deleted successfully");+}+```+ </Tab>+</Tabs>++## Multi-toolkit servers++Combine multiple services in a single MCP server.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+server = composio.mcp.create(+ name="productivity-suite",+ toolkits=[+ {"toolkit": "gmail", "auth_config": "ac_gmail"},+ {"toolkit": "slack", "auth_config": "ac_slack"},+ {"toolkit": "github", "auth_config": "ac_github"}+ ],+ allowed_tools=[+ "GMAIL_FETCH_EMAILS",+ "SLACK_SEND_MESSAGE",+ "GITHUB_CREATE_ISSUE"+ ]+)+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const server = await composio.mcp.create(+ "productivity-suite",+ {+ toolkits: [+ {+ authConfigId: "ac_gmail",+ toolkit: "gmail"+ },+ {+ authConfigId: "ac_slack",+ toolkit: "slack"+ },+ {+ authConfigId: "ac_github",+ toolkit: "github"+ }+ ],+ allowedTools: [+ "GMAIL_FETCH_EMAILS",+ "SLACK_SEND_MESSAGE",+ "GITHUB_CREATE_ISSUE"+ ],+ manuallyManageConnections: false+ }+);+```+ </Tab>+</Tabs>++## Generate user URLs++After creating a server, generate unique URLs for each user.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+# Generate instance for user+instance = server.generate("[email protected]")++print(f"URL: {instance['url']}")+print(f"Tools: {instance['allowed_tools']}")++# Chat-based authentication is enabled by default+# Set manually_manage_connections=True to disable it:+instance_manual = server.generate(+ "[email protected]",+ manually_manage_connections=True+)+```+ </Tab>+ <Tab value="TypeScript">+```typescript+// Generate instance for user+const instance = await server.generate("[email protected]");++console.log("URL:", instance.url);+console.log("Tools:", instance.allowedTools);++// Chat-based authentication is enabled by default+// Set manuallyManageConnections: true to disable it:+const instanceManual = await composio.mcp.generate(+ "[email protected]",+ server.id,+ { manuallyManageConnections: true }+);+```+ </Tab>+</Tabs>++<Callout type="info">+**Chat-based authentication:**+- **TypeScript**: Enabled by default (set `manuallyManageConnections=false` or omit it)+- **Python**: Enabled by default (set `manually_manage_connections=False` or omit it)++When enabled, the agent can authenticate users dynamically during conversation if they're missing required connections. Set `manuallyManageConnections=true` (TypeScript) or `manually_manage_connections=True` (Python) to disable it.+</Callout>++## Best practices++- **Use descriptive names** - Makes servers easy to find+- **Limit tools appropriately** - Only include necessary tools+- **Reuse servers** - Don't create duplicates for same configuration+- **Store server IDs** - Keep track of created server IDsdiff --git a/fumadocs/content/docs/meta.json b/fumadocs/content/docs/meta.jsonindex fff7db9b6..77df35f94 100644--- a/fumadocs/content/docs/meta.json+++ b/fumadocs/content/docs/meta.json@@ -17,6 +17,15 @@"programmatic-auth-configs","custom-auth-params","connected-accounts",- "user-management"+ "user-management",+ "---MCP---",+ "mcp-quickstart",+ "mcp-server-management",+ "mcp-providers",+ "---Resources---",+ "cli",+ "debugging-info",+ "migration-guide",+ "troubleshooting"]}diff --git a/fumadocs/content/docs/migration-guide/index.mdx b/fumadocs/content/docs/migration-guide/index.mdxnew file mode 100644index 000000000..802053447--- /dev/null+++ b/fumadocs/content/docs/migration-guide/index.mdx@@ -0,0 +1,20 @@+---+title: Migration guides+description: Guides for migrating to newer versions of Composio+---++## Available migration guides++<Accordions>+ <Accordion title="New SDK migration">+ Migrate from the old Composio SDK to the new SDK, including breaking changes, new features, and updated APIs.++ [View SDK migration guide →](/docs/migration-guide/new-sdk)+ </Accordion>++ <Accordion title="Toolkit versioning migration">+ Migrate to use the toolkit versioning system.++ [View versioning migration guide →](/docs/migration-guide/toolkit-versioning)+ </Accordion>+</Accordions>diff --git a/fumadocs/content/docs/migration-guide/meta.json b/fumadocs/content/docs/migration-guide/meta.jsonnew file mode 100644index 000000000..bf103a9c1--- /dev/null+++ b/fumadocs/content/docs/migration-guide/meta.json@@ -0,0 +1,8 @@+{+ "title": "Migration Guide",+ "pages": [+ "index",+ "new-sdk",+ "toolkit-versioning"+ ]+}diff --git a/fumadocs/content/docs/migration-guide/new-sdk.mdx b/fumadocs/content/docs/migration-guide/new-sdk.mdxnew file mode 100644index 000000000..f313d0857--- /dev/null+++ b/fumadocs/content/docs/migration-guide/new-sdk.mdx@@ -0,0 +1,1259 @@+---+title: Our next generation SDKs+description: Learn more about Composio's next generation SDKs and how to migrate+---++In the last few months, we have experienced very rapid growth in usage of our platform. As such, our team has been working hard to radically improve the performance and developer experience of our platform.++A lot of these changes have happened in the background, but we are excited to finally share our new SDKs with you that complement our new infra.++The new API features improved usability, enhanced stability, and better scalability. The SDKs built on top of it simplify the developer experience, making it easier than ever to build useful agents.++## What's new?++A lot of the changes are on the infra side, but from the SDK point of view, here is what you can expect:+- Faster and more reliable tool execution+- A simpler but more opinionated SDK+- Much more intuitive and consistent naming conventions+- A vastly improved TypeScript SDK that is meaningfully more type-safe and has full feature parity with the Python SDK++There aren't too many new flashy features here (yet) mainly because we wanted to get the bones right — but we feel we have a solid foundation to ship incredible new experiences on top very quickly.++## State of the new SDK and what is happening with the old SDKs?++Currently, the new SDKs are in a preview release. These new SDKs come almost fully formed, we do not expect many breaking changes to them but are releasing them in a preview state to get feedback and make necessary changes before locking them in.++As we lock the new SDKs in place, we will deprecate support for the old SDKs. They will continue to work for the foreseeable future but are no longer actively maintained. We will continue to push security updates and fix any critical bugs but will not support any new functionality in them.++We urge you to upgrade to the new SDKs as soon as possible.++## Nomenclature++We have updated several key terms in the SDK and API to improve clarity and consistency. The following table summarizes these changes:++| Previous Term | Current Term | Definition |+|---------------|--------------------|--------------------------------------------------------------------------|+| Actions | Tools | Individual operations or capabilities that can be performed by an LLM agent |+| Apps | Toolkits | A collection of tools grouped under a single application |+| Integration | Auth Config | Configuration containing developer credentials and application-level settings such as scopes and API endpoints. Scoped to a toolkit. |+| Connection | Connected accounts | User-linked accounts associated with a toolkit |+| Entity ID | User ID | The identifier of the user performing the action (UUID or email) |+| Trigger | Trigger | An event that can be subscribed to |+| Toolsets | Providers | LLM or agent framework that can be used with Composio to create agents |++## Switch to nano IDs from UUIDs++We have transitioned from UUIDs to nano IDs throughout the platform for the following reasons:++- **Improved readability**: UUIDs are lengthy and difficult to read+- **Better usability**: Easier to copy with a single double-click+- **Better organization**: Nano IDs allow us to distinguish between different resource types through prefixes++| Feature | Nano ID Prefix | Example |+|-------------------|----------------|--------------------|+| Connected Account | `ca_` | `ca_8x9w2l3k5m` |+| Auth Config | `ac_` | `ac_1234567890` |+| Trigger | `ti_` | `ti_So9EQf8XnAcy` |++<Callout type="info">+Nano IDs are short, unique, and prefixed to indicate the resource type.+</Callout>++## SDK Changes++Upgrade to the latest SDK version using the appropriate package manager:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```bash+pip install -U composio+```+ </Tab>+ <Tab value="TypeScript">+```bash+npm install @composio/core+```+ </Tab>+</Tabs>++Both SDKs now implement proper namespacing for each concept.++### User ID scoping++The concept of `entity_id` has been expanded and renamed to `user_id`.++All operations are now scoped to a user ID, including:+- Fetching tools+- Initiating connections+- Executing tools+- Managing triggers++This change provides explicit specification of the user for whom the action is being performed. When a user may have multiple accounts (such as work and personal Gmail connections), you can use the more specific connected account ID.++### Replacing ToolSets with Providers++We have deprecated "toolsets" in favor of "providers". This change allows Composio to provide deeper standardization for tool implementation across different frameworks.++Previously, you needed to import and use a framework-specific `ComposioToolSet` class:++<Tabs groupId="language" items={['Python (previous)', 'TypeScript (previous)']} persist>+ <Tab value="Python (previous)">+```python+from composio_openai import ComposioToolSet, Action, App+from openai import OpenAI++toolset = ComposioToolSet()+```+ </Tab>+ <Tab value="TypeScript (previous)">+```typescript+import { OpenAIToolSet } from 'composio-core';++const toolset = new OpenAIToolSet();+```+ </Tab>+</Tabs>++The SDK structure is now framework-agnostic and includes the OpenAI provider out of the box:++<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>+ <Tab value="Python (current)">+```python+from composio import Composio+# from composio_langchain import LangchainProvider++composio = Composio()+# composio = Composio(provider=LangchainProvider())++tools = composio.tools.get(+ user_id="0001",+ tools=["LINEAR_CREATE_LINEAR_ISSUE", "GITHUB_CREATE_COMMIT"]+)+# tools returned is formatted for the provider. by default, OpenAI.+```+ </Tab>+ <Tab value="TypeScript (current)">+```typescript+import { Composio } from '@composio/core';+// import { VercelProvider } from '@composio/vercel';++const composio = new Composio({+ // provider: new VercelProvider(),+});+// Can specify other providers too, like OpenAI, Anthropic, Vercel AI SDK.++const tools = await composio.tools.get('[email protected]', {+ tools: ['LINEAR_CREATE_LINEAR_ISSUE', 'GITHUB_CREATE_COMMIT'],+});+// tools returned is formatted for the provider. by default, OpenAI.+```+ </Tab>+</Tabs>++You can now use the same tools across any framework with our unified interface, or create custom toolsets for frameworks we don't yet support.++Read more about [providers in our documentation](/docs/providers) and explore the [complete list of available providers](/providers/openai).++### Fetching and filtering tools++Previously, you could filter tools by:+- Apps+- Action names (tool names)+- Tags++You could also specify an `important` flag to retrieve the most important tools:++<Tabs groupId="language" items={['Python (previous)', 'TypeScript (previous)']} persist>+ <Tab value="Python (previous)">+```python+from composio_openai import ComposioToolSet, Action, App+from openai import OpenAI++toolset = ComposioToolSet()+client = OpenAI()++tools = toolset.get_tools(+ actions=[Action.GITHUB_GET_THE_AUTHENTICATED_USER], check_connected_accounts=True+)++tools = toolset.get_tools(apps=[App.GITHUB, App.LINEAR, App.SLACK], check_connected_accounts=True)+```+ </Tab>+ <Tab value="TypeScript (previous)">+```typescript+import { OpenAIToolSet } from 'composio-core';++const toolset = new OpenAIToolSet();++const tools_1 = await toolset.getTools({ apps: ['GITHUB'] });+const tools_2 = await toolset.getTools({+ actions: ['GITHUB_GET_THE_AUTHENTICATED_USER', 'LINEAR_CREATE_LINEAR_ISSUE'],+});+```+ </Tab>+</Tabs>++You can now filter tools by:+- Toolkits+- Tool slugs+- Limit parameter+- Search query++The `important` flag has been removed. Instead, tools are returned in order of importance by default:++<Callout type="info">+Since `user_id` is now explicitly required, the `check_connected_accounts` flag is no longer necessary.+</Callout>++<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>+ <Tab value="Python (current)">+```python+from composio import Composio++composio = Composio()++user_id = "[email protected]"++tools_1 = composio.tools.get(user_id=user_id, toolkits=["GITHUB", "LINEAR"])++tools_2 = composio.tools.get(user_id=user_id, toolkits=["SLACK"], limit=5) # Default limit=20++tools_3 = composio.tools.get(+ user_id=user_id,+ tools=["GITHUB_CREATE_AN_ISSUE", "GITHUB_CREATE_AN_ISSUE_COMMENT", "GITHUB_CREATE_A_COMMIT"],+)++tools_4 = composio.tools.get(user_id="john", search="hackernews posts")+```+ </Tab>+ <Tab value="TypeScript (current)">+```typescript+import { Composio } from '@composio/core';++const userId = '[email protected]';++const composio = new Composio();++const tools_1 = await composio.tools.get(userId, {+ toolkits: ['GITHUB', 'LINEAR'],+});++const tools_2 = await composio.tools.get(userId, {+ toolkits: ['GITHUB'],+ limit: 5, // Default limit=20+});++const tools_3 = await composio.tools.get(userId, {+ tools: ['GITHUB_CREATE_AN_ISSUE', 'GITHUB_CREATE_AN_ISSUE_COMMENT', 'GITHUB_CREATE_A_COMMIT'],+});++const tools_4 = await composio.tools.get(userId, {+ search: 'hackernews posts',+});+```+ </Tab>+</Tabs>++### Fetching raw tool data++To examine the raw schema definition of a tool for understanding input/output parameters or building custom logic around tool definitions, use the following methods:++<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>+ <Tab value="Python (current)">+```python+from composio import Composio++composio = Composio()++tool = composio.tools.get_raw_composio_tool_by_slug("HACKERNEWS_GET_LATEST_POSTS")++print(tool.model_dump_json())+```+ </Tab>+ <Tab value="TypeScript (current)">+```typescript+import { Composio } from '@composio/core';++const composio = new Composio();++const tool = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_OCTOCAT');++console.log(JSON.stringify(tool, null, 2));+```+ </Tab>+</Tabs>++### Executing tools++Tool execution remains largely unchanged, with `user_id` now explicitly required.++For agentic frameworks, the tool object returned from `tools.get` is now the respective framework's native tool object. Tool call execution is handled by the agentic framework itself.++<Callout type="info">+For non-agentic frameworks, Composio provides a helper function to execute tool calls.+</Callout>++<Tabs groupId="language" items={['Python v3', 'TypeScript v3']} persist>+ <Tab value="Python v3">+```python+from composio import Composio+from openai import OpenAI++openai_client = OpenAI()+composio = Composio()++tools = composio.tools.get(user_id="[email protected]", tools=["GITHUB_GET_THE_ZEN_OF_GITHUB"])+response = openai_client.chat.completions.create(+ model="gpt-4.1",+ messages=[{"role": "user", "content": "gimme some zen."}],+ tools=tools,+)++result = composio.provider.handle_tool_calls(user_id="[email protected]", response=response)+print(result)+```+ </Tab>+ <Tab value="TypeScript v3">+```typescript+import { Composio } from '@composio/core';+import { AnthropicProvider } from '@composio/anthropic';+import Anthropic from '@anthropic-ai/sdk';++const anthropic = new Anthropic();+const composio = new Composio({+ provider: new AnthropicProvider(),+});++const userId = '[email protected]';+const tools = await composio.tools.get(userId, {+ toolkits: ['GMAIL'],+});++const msg = await anthropic.messages.create({+ model: 'claude-3-7-sonnet-latest',+ tools: tools,+ messages: [+ {+ role: 'user',+ content: "Say hi to '[email protected]'",+ },+ ],+ max_tokens: 1024,+});++const result = await composio.provider.handleToolCalls(userId, msg);+console.log('Tool results:', result);+```+ </Tab>+</Tabs>++For more information on executing tools for different frameworks, see [Replacing ToolSets with Providers](#replacing-toolsets-with-providers).++### Tool Modifiers (formerly Tool Processors)++Tool processors have been renamed to *tool modifiers* and now provide an improved developer experience. The implementation is now available in TypeScript too! (previously Python-only).++```python title="Python (previous)"+from composio_openai import ComposioToolSet, Action++toolset = ComposioToolSet()+++def my_schema_processor(schema: dict) -> dict: ...+def my_preprocessor(inputs: dict) -> dict: ...+def my_postprocessor(result: dict) -> dict: ...+++# Get tools with the modified schema+processed_tools = toolset.get_tools(+ actions=[Action.GMAIL_SEND_EMAIL],+ processors={+ # Applied BEFORE the LLM sees the schema+ "schema": {Action.SOME_ACTION: my_schema_processor},+ # Applied BEFORE the tool executes+ "pre": {Action.SOME_ACTION: my_preprocessor},+ # Applied AFTER the tool executes, BEFORE the result is returned+ "post": {Action.SOME_ACTION: my_postprocessor},+ },+)+```++| Previous | Current |+|-------------------|-------------------------|+| `pre` processor | `beforeExecute` modifier |+| `post` processor | `afterExecute` modifier |+| `schema` processor| `schema` modifier |++The modifiers now leverage language-specific features to provide a more natural developer experience.++While tool processors could previously be applied during SDK initialization, tool fetching, and tool execution, we have restructured them as follows:+- **Chat Completion providers**: Modifiers are specified and applied during tool execution+- **Agentic frameworks**: Modifiers are specified and applied during tool fetching++#### Schema Modifiers++The following example demonstrates schema modifier usage, applicable across all providers:++<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>+ <Tab value="Python (current)">+```python+from composio import Composio, schema_modifier+from composio.types import Tool++user_id = "[email protected]"++@schema_modifier(tools=["HACKERNEWS_GET_LATEST_POSTS"])+def modify_schema(+ tool: str,+ toolkit: str,+ schema: Tool,+) -> Tool:+ _ = schema.input_parameters["properties"].pop("page", None)+ schema.input_parameters["required"] = ["size"]+ return schema++tools = composio.tools.get(+ user_id=user_id,+ tools=["HACKERNEWS_GET_LATEST_POSTS", "HACKERNEWS_GET_USER"],+ modifiers=[+ modify_schema,+ ]+)+```+ </Tab>+ <Tab value="TypeScript (current)">+```typescript+import { Composio } from '@composio/core';+import { OpenAI } from 'openai';++const userId = '[email protected]';+const composio = new Composio();++// Schema modifier to delete the `page` argument from the `HACKERNEWS_GET_LATEST_POSTS` tool+const tools = await composio.tools.get(+ userId,+ {+ tools: ['HACKERNEWS_GET_LATEST_POSTS', 'HACKERNEWS_GET_USER'],+ },+ {+ modifySchema: ({ toolSlug, toolkitSlug, schema }) => {+ if (toolSlug === 'HACKERNEWS_GET_LATEST_POSTS') {+ const { inputParameters } = schema;+ if (inputParameters?.properties) {+ delete inputParameters.properties['page'];+ }+ inputParameters.required = ['size'];+ }+ return schema;+ },+ }+);++console.log(JSON.stringify(tools, null, 2));+```+ </Tab>+</Tabs>++#### Before Modifiers++The following example shows creating and using a before modifier for a Chat Completion provider. For agentic frameworks, view the [complete before modifier documentation](/docs/modify-tool-behavior/before-execution-modifiers):++<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>+ <Tab value="Python (current)">+```python+@before_execute(tools=["HACKERNEWS_GET_LATEST_POSTS"])+def before_execute_modifier(+ tool: str,+ toolkit: str,+ params: ToolExecuteParams,+) -> ToolExecuteParams:+ params["arguments"]["size"] = 1+ return params+++# Get tools+tools = composio.tools.get(user_id=user_id, slug="HACKERNEWS_GET_LATEST_POSTS")+```+ </Tab>+ <Tab value="TypeScript (current)">+```typescript+const result_1 = await composio.tools.execute(+ 'HACKERNEWS_GET_LATEST_POSTS',+ {+ userId,+ arguments: JSON.parse(toolArgs),+ },+ {+ beforeExecute: ({ toolSlug, toolkitSlug, params }) => {+ if (toolSlug === 'HACKERNEWS_GET_LATEST_POSTS') {+ params.arguments.size = 1;+ }+ console.log(params);+ return params;+ },+ }+);+```+ </Tab>+</Tabs>++#### After Modifiers++The following example shows creating and using an after modifier for a Chat Completion provider. For agentic frameworks, view the [complete after modifier documentation](/docs/modify-tool-behavior/after-execution-modifiers):++<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>+ <Tab value="Python (current)">+```python+@after_execute(tools=["HACKERNEWS_GET_USER"])+def after_execute_modifier(+ tool: str,+ toolkit: str,+ response: ToolExecutionResponse,+) -> ToolExecutionResponse:+ return {+ **response,+ "data": {+ "karma": response["data"]["karma"],+ },+ }++tools = composio.tools.get(user_id=user_id, slug="HACKERNEWS_GET_USER")+```+ </Tab>+ <Tab value="TypeScript (current)">+```typescript+const result_2 = await composio.tools.execute(+ 'HACKERNEWS_GET_USER',+ {+ userId,+ arguments: JSON.parse(toolArgs),+ },+ {+ afterExecute: ({ toolSlug, toolkitSlug, result }) => {+ if (toolSlug === 'HACKERNEWS_GET_USER') {+ const { data } = result;+ const { karma } = data.response_data as { karma: number };+ return {+ ...result,+ data: { karma },+ };+ }+ return result;+ },+ }+);+```+ </Tab>+</Tabs>++### Custom Tools++The SDK continues to support custom tools. [Creating tools from your methods](/docs/custom-tools#creating-a-custom-tool) remains possible. We recommend reviewing the [detailed custom tools documentation](/docs/custom-tools#creating-a-custom-tool) for more information.++Due to changes in the SDK architecture, creating custom tools that use Composio's managed authentication has been modified. In the previous SDK, you could create a custom tool as follows:++<Tabs groupId="language" items={['Python (previous)', 'TypeScript (previous)']} persist>+ <Tab value="Python (previous)">+```python+# Python Example using execute_request+from composio import action, ComposioToolSet+import typing as t++toolset = ComposioToolSet()++@action(toolname="github") # Associate with GitHub app for auth+def get_github_repo_topics(+ owner: t.Annotated[str, "Repository owner username"],+ repo: t.Annotated[str, "Repository name"],+ execute_request: t.Callable # Injected by Composio+) -> dict:+ """Gets the topics associated with a specific GitHub repository."""+ response_data = execute_request(+ endpoint=f"/repos/{owner}/{repo}/topics", # API path relative to base URL+ method="GET"+ )+ if isinstance(response_data, dict):+ return {"topics": response_data.get("names", [])}+```+ </Tab>+ <Tab value="TypeScript (previous)">+```typescript+import { OpenAIToolSet, type ActionExecutionResDto } from "composio-core";+import { z } from "zod";++const toolset = new OpenAIToolSet();++await toolset.createAction({+ actionName: "get_github_repo_topics",+ toolName: "github",+ description: "Gets the topics associated with a specific GitHub repository.",+ inputParams: z.object({+ owner: z.string().describe("Repository owner username"),+ repo: z.string().describe("Repository name"),+ }),+ callback: async (inputParams, _authCredentials, executeRequest): Promise<ActionExecutionResDto> => {+ const { owner, repo } = inputParams as { owner: string, repo: string };+ const response = await executeRequest({+ endpoint: `/repos/${owner}/${repo}/topics`,+ method: "GET",+ parameters: [],+ });++ const topics = (response as any)?.names ?? [];+ return { successful: true, data: { topics: topics } };+ }+});+```+ </Tab>+</Tabs>++The *execute tool request* method handles injection of the appropriate base URL and authentication credentials for the tool:++<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>+ <Tab value="Python (current)">+```python+from pydantic import BaseModel, Field+from composio import Composio+from composio.core.models.custom_tools import ExecuteRequestFn+++composio = Composio()++class GetIssueInfoInput(BaseModel):+ issue_number: int = Field(+ ...,+ description="The number of the issue to get information about",+ )++# function name will be used as slug[email protected]_tool(toolkit="github")+def get_issue_info(+ request: GetIssueInfoInput,+ execute_request: ExecuteRequestFn,+ auth_credentials: dict,+) -> dict:+ """Get information about a GitHub issue."""+ response = execute_request(+ endpoint=f"/repos/composiohq/composio/issues/{request.issue_number}",+ method="GET",+ parameters=[+ {+ "name": "Accept",+ "value": "application/vnd.github.v3+json",+ "type": "header",+ },+ {+ "name": "Authorization",+ "value": f"Bearer {auth_credentials['access_token']}",+ "type": "header",+ },+ ],+ )+ return {"data": response.data}+```+ </Tab>+ <Tab value="TypeScript (current)">+```typescript+import { Composio } from "@composio/core";+import z from "zod";++const composio = new Composio();++const tool = await composio.tools.createCustomTool({+ slug: 'GITHUB_STAR_COMPOSIOHQ_REPOSITORY',+ name: 'Github star composio repositories',+ toolkitSlug: 'github',+ description: 'Star any specificied repo of `composiohq` user',+ inputParams: z.object({+ repository: z.string().describe('The repository to star'),+ page: z.number().optional().describe('Pagination page number'),+ customHeader: z.string().optional().describe('Custom header'),+ }),+ execute: async (input, connectionConfig, executeToolRequest) => {+ const result = await executeToolRequest({+ endpoint: `/user/starred/composiohq/${input.repository}`,+ method: 'PUT',+ body: {},+ parameters: [+ {+ name: 'page',+ value: input.page?.toString() || '1',+ in: 'query',+ },+ {+ name: 'x-custom-header',+ value: input.customHeader || 'default-value',+ in: 'header',+ },+ ],+ });+ return result;+ },+ });+```+ </Tab>+</Tabs>++For more information, including executing custom tools and defining custom headers and query parameters, refer to the [Custom Tools](/docs/custom-tools) documentation.++### Auth configs (formerly integrations)++Integrations are now called *auth configs*. While the terminology has changed, the underlying concept remains the same.++Auth configs store the configuration required for authentication with a given toolkit, including OAuth developer credentials, configurable base URLs, and scopes.++Auth configs now use nano IDs instead of UUIDs:++| Previous (UUID) Example | Current (Nano ID) Example |+| :----------------------------------- | :------------------------ |+| `b7a9c1e2-3f4d-4a6b-8c2e-1d2f3a4b5c6d` | `ac_8x9w2l3k5m` |++We recommend storing auth config nano IDs in your database for connecting users to the appropriate auth configuration.++For most use cases, you will create auth configs through the dashboard, and this process remains unchanged. Read more about [creating auth configs](/docs/authenticating-tools#creating-an-auth-config) and [customizing auth configs](/docs/custom-auth-configs).++Creating auth configs programmatically in the previous SDK:++<Tabs groupId="language" items={['Python (previous)', 'TypeScript (previous)']} persist>+ <Tab value="Python (previous)">+```python+from composio_openai import App, ComposioToolSet++toolset = ComposioToolSet()++integration = toolset.create_integration(+ app=App.GITHUB,+ auth_mode="OAUTH2",+ use_composio_oauth_app=True,+ # For use_composio_oauth_app=False, you can provide your own OAuth app credentials here+ # auth_config={+ # "client_id": "123456",+ # "client_secret": "123456"+ # }++)+print(integration.id)+```+ </Tab>+ <Tab value="TypeScript (previous)">+```typescript+import { OpenAIToolSet } from "composio-core";++const composioToolset = new OpenAIToolSet();++const integration = await composioToolset.integrations.create({+ name: "gmail_integration",+ appUniqueKey: "gmail",+ forceNewIntegration: true,+ useComposioAuth: false,+ // For useComposioAuth: false, you can provide your own OAuth app credentials here+ // authScheme: "OAUTH2",+ // authConfig: {+ // clientId: "123456",+ // clientSecret: "123456"+ // }+})++console.log(integration.id)+```+ </Tab>+</Tabs>++Creating auth configs programmatically in the current SDK:++<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>+ <Tab value="Python (current)">+```python+from composio import Composio++composio = Composio()++# Use composio managed auth+auth_config = composio.auth_configs.create(+ toolkit="notion",+ options={+ "type": "use_composio_managed_auth",+ # "type": "use_custom_auth",+ # "auth_scheme": "OAUTH2",+ # "credentials": {+ # "client_id": "1234567890",+ # "client_secret": "1234567890",+ # "oauth_redirect_uri": "https://backend.composio.dev/api/v3/toolkits/auth/callback",+ # },+ },+)+print(auth_config)+```+ </Tab>+ <Tab value="TypeScript (current)">+```typescript+import { Composio } from '@composio/core';++const composio = new Composio();++const authConfig = await composio.authConfigs.create('LINEAR', {+ name: 'Linear',+ type: 'use_composio_managed_auth',+ // type: "use_custom_auth",+ // credentials: {+ // client_id: "1234567890",+ // client_secret: "1234567890",+ // oauth_redirect_uri: "https://backend.composio.dev/api/v3/toolkits/auth/callback",+ // },+});++console.log(authConfig);+```+ </Tab>+</Tabs>++For using custom authentication credentials, refer to the [Programmatic Auth Configs](/docs/programmatic-auth-configs) documentation.++<Callout type="info">+The callback URL for creating custom OAuth configs is now `https://backend.composio.dev/api/v3/toolkits/auth/callback`. The previous URL was `https://backend.composio.dev/api/v1/auth-apps/add`.+</Callout>++### Connected accounts / User IDs++The primary change in connected accounts and user IDs is that user IDs are now a more prominent concept compared to entities in previous versions.++We have simplified the process of connecting a user to a toolkit. Instead of multiple methods and parameters for initiating a connection, both the SDK and API now require only a `user_id` and `auth_config_id` to initiate a connection.++This approach is more explicit and works well with the ability for developers to have multiple auth configs for a given toolkit.++Connected accounts now use nano IDs instead of UUIDs:++| Previous (UUID) Example | Current (Nano ID) Example |+| :----------------------------------- | :------------------------ |+| `b7a9c1e2-3f4d-4a6b-8c2e-1d2f3a4b5c6d` | `ca_8x9w2l3k5m` |++Previously, you might have initiated a connection like this:++<Tabs groupId="language" items={['Python (previous)', 'TypeScript (previous)']} persist>+ <Tab value="Python (previous)">+```python+from composio_openai import ComposioToolSet++toolset = ComposioToolSet()+user_id = "your_user_unique_id"+google_integration_id = "0000-0000"++entity = toolset.get_entity(id=user_id)++try:+ print(f"Initiating OAuth connection for entity {entity.id}...")+ connection_request = toolset.initiate_connection(+ integration_id=google_integration_id,+ entity_id=user_id,+ # Optionally add: redirect_url="https://yourapp.com/final-destination"+ # if you want user sent somewhere specific *after* Composio finishes.+ )++ # Check if a redirect URL was provided (expected for OAuth)+ if connection_request.redirectUrl:+ print(f"Received redirect URL: {connection_request.redirectUrl}")+ else:+ print("Error: Expected a redirectUrl for OAuth flow but didn't receive one.")+++except Exception as e:+ print(f"Error initiating connection: {e}")+```+ </Tab>+ <Tab value="TypeScript (previous)">+```typescript+import { OpenAIToolSet } from "composio-core";++const toolset = new OpenAIToolSet();+const userId = "your_user_unique_id";+const googleIntegrationId = "0000-0000";++console.log(`Initiating OAuth connection for entity ${userId}...`);+const connectionRequest = await toolset.connectedAccounts.initiate({+ integrationId: googleIntegrationId,+ entityId: userId,+ // Optionally add: redirectUri: "https://yourapp.com/final-destination"+ // if you want user sent somewhere specific *after* Composio finishes.+});++// Check if a redirect URL was provided (expected for OAuth)+if (connectionRequest?.redirectUrl) {+ console.log(`Received redirect URL: ${connectionRequest.redirectUrl}`);+ // Proceed to Step 2: Redirect the user+ // Return or pass connectionRequest to the next stage+} else {+ console.error("Error: Expected a redirectUrl for OAuth flow but didn't receive one.");+}+```+ </Tab>+</Tabs>++The current process for initiating a connection is as follows:++<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>+ <Tab value="Python (current)">+```python+from composio import Composio++linear_auth_config_id = "ac_1234"+user_id = "[email protected]"+composio = Composio()++# Create a new connected account+connection_request = composio.connected_accounts.initiate(+ user_id=user_id,+ auth_config_id=linear_auth_config_id,+)+print(connection_request.redirect_url)++# Wait for the connection to be established+connected_account = connection_request.wait_for_connection()+print(connected_account)+```+ </Tab>+ <Tab value="TypeScript (current)">+```typescript+import { Composio } from "@composio/core";++const composio = new Composio();+const linearAuthConfigId = "ac_1234";+const userId = "[email protected]";++// Initiate the OAuth connection request+const connRequest = await composio.connectedAccounts.initiate(userId, linearAuthConfigId);++const { redirectUrl, id } = connRequest;+console.log(redirectUrl);++// Wait for the connection to be established+await connRequest.waitForConnection();++// If you only have the connection request ID, you can also wait using:+await composio.connectedAccounts.waitForConnection(id);+```+ </Tab>+</Tabs>++### Triggers++Composio continues to support listening to application events using triggers through WebSockets and webhooks.++#### Creating triggers++The process for creating triggers and specifying their configuration has been redesigned for improved clarity and intuitiveness.++Some triggers require configuration, such as repository names for GitHub triggers or channel names for Slack triggers. The process usually follows the pattern of fetching the trigger type and then creating the trigger with the appropriate configuration.++<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>+ <Tab value="Python (current)">+```python+from composio import Composio++composio = Composio()++user_id = "[email protected]"+trigger_config = composio.triggers.get_type("GITHUB_COMMIT_EVENT")+print(trigger_config.config)+### Trigger Config+# {+# "properties": {+# "owner": {+# "description": "Owner of the repository",+# "title": "Owner",+# "type": "string"+# },+# "repo": {+# "description": "Repository name",+# "title": "Repo",+# "type": "string"+# }+# },+# "required": ["owner", "repo"],+# "title": "WebhookConfigSchema",+# "type": "object"++trigger = composio.triggers.create(+ slug="GITHUB_COMMIT_EVENT",+ user_id=user_id,+ trigger_config={"repo": "composiohq", "owner": "composio"},+)+print(trigger)+++# Managing triggers++composio.triggers.enable(id="ti_abcd123")+```+ </Tab>+ <Tab value="TypeScript (current)">+```typescript+import { Composio } from '@composio/core';++const composio = new Composio();++const userId = '[email protected]';+// Fetch the trigger details+const triggerType = await composio.triggers.getType('GITHUB_COMMIT_EVENT');+console.log(JSON.stringify(triggerType.config, null, 2));+/*--- Trigger config ---+{+ "properties": {+ "owner": {+ "description": "Owner of the repository",+ "title": "Owner",+ "type": "string"+ },+ "repo": {+ "description": "Repository name",+ "title": "Repo",+ "type": "string"+ }+ },+ "required": ["owner", "repo"],+ "title": "WebhookConfigSchema",+ "type": "object"+}+*/++const createResponse = await composio.triggers.create(userId, 'GITHUB_COMMIT_EVENT', {+ triggerConfig: {+ owner: 'composiohq',+ repo: 'composio',+ },+});+console.log(createResponse);+```+ </Tab>+</Tabs>++#### Enabling/Disabling triggers++You can enable or disable triggers through either the SDK or the dashboard. The dashboard process remains unchanged.++Managing triggers with the SDK:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+# Disable a trigger instance+disabled_instance = composio.triggers.disable(trigger_id="ti_abcd123")+print(disabled_instance)+```+ </Tab>+ <Tab value="TypeScript">+```typescript+await composio.triggers.disable("ti_abcd123");+```+ </Tab>+</Tabs>++If needed, the trigger can be enabled again.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+# Enable a trigger instance+enabled_instance = composio.triggers.enable(trigger_id="ti_abcd123")+print(enabled_instance)+```+ </Tab>+ <Tab value="TypeScript">+```typescript+await composio.triggers.enable("ti_abcd123");+```+ </Tab>+</Tabs>++#### Listening to triggers++We recommend listening to triggers through webhooks. The following are example routes for Next.js and FastAPI.++For development, you can also [listen to triggers through the SDK](/docs/using-triggers#subscribing-to-triggers-using-the-sdk-for-development).++<Tabs items={['FastAPI', 'Next.js']}>+ <Tab value="FastAPI">+```python title="app/route.py"+from fastapi import FastAPI, Request, HTTPException+from typing import Dict, Any+import uvicorn+import json+import hmac+import hashlib+import base64+import os++def verify_webhook_signature(request: Request, body: bytes) -> bool:+ """Verify Composio webhook signature"""+ webhook_signature = request.headers.get("webhook-signature")+ webhook_id = request.headers.get("webhook-id")+ webhook_timestamp = request.headers.get("webhook-timestamp")+ webhook_secret = os.getenv("COMPOSIO_WEBHOOK_SECRET")++ if not all([webhook_signature, webhook_id, webhook_timestamp, webhook_secret]):+ raise HTTPException(status_code=400, detail="Missing required webhook headers or secret")++ if not webhook_signature.startswith("v1,"):+ raise HTTPException(status_code=401, detail="Invalid signature format")++ received = webhook_signature[3:]+ signing_string = f"{webhook_id}.{webhook_timestamp}.{body.decode()}"+ expected = base64.b64encode(+ hmac.new(webhook_secret.encode(), signing_string.encode(), hashlib.sha256).digest()+ ).decode()++ if not hmac.compare_digest(received, expected):+ raise HTTPException(status_code=401, detail="Invalid webhook signature")++ return True+[email protected]("/webhook")+async def webhook_handler(request: Request):+ payload = await request.json()++ trigger_type = payload.get("type")+ event_data = payload.get("data", {})++ if trigger_type == "github_star_added_event":+ repo_name = event_data.get("repository_name")+ starred_by = event_data.get("starred_by")+ print(f"Repository {repo_name} starred by {starred_by}")+ # Add your business logic here++ return {"status": "success", "message": "Webhook processed"}+```+ </Tab>+ <Tab value="Next.js">+```typescript title="app/api/webhook/route.ts"+import type { NextApiRequest, NextApiResponse } from 'next';+import { TriggerEvent } from '@composio/core';+import crypto from 'crypto';++type GitHubStarEventData = {+ repository_name: string;+ repository_url: string;+ starred_by: string;+ starred_at: string;+};++function verifyWebhookSignature(+ req: NextApiRequest,+ body: string+): boolean {+ const signature = req.headers['webhook-signature'] as string | undefined;+ const msgId = req.headers['webhook-id'] as string | undefined;+ const timestamp = req.headers['webhook-timestamp'] as string | undefined;+ const secret = process.env.COMPOSIO_WEBHOOK_SECRET;++ if (!signature || !msgId || !timestamp || !secret) {+ throw new Error('Missing required webhook headers or secret');+ }++ if (!signature.startsWith('v1,')) {+ throw new Error('Invalid signature format');+ }++ const received = signature.slice(3);+ const signingString = `${msgId}.${timestamp}.${body}`;+ const expected = crypto+ .createHmac('sha256', secret)+ .update(signingString)+ .digest('base64');++ return crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));+}++export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {+ const payload = req.body;++ if (payload.type === 'github_star_added_event') {+ const event: TriggerEvent<GitHubStarEventData> = {+ type: payload.type,+ timestamp: payload.timestamp,+ data: payload.data+ };++ console.log(`Repository ${event.data.repository_name} starred by ${event.data.starred_by}`);+ // Add your business logic here+ }++ res.status(200).json({+ status: 'success',+ message: 'Webhook processed'+ });+}+```+ </Tab>+</Tabs>++## Coming Soon++### Local tools++Previously, the Python SDK included *[local tools](https://github.com/ComposioHQ/composio/tree/master/python/composio/tools/local)*. These were tools defined within the SDK and consisted of local shell and code-related tools such as "clipboard", "sqltool", and "shelltool".++This feature is currently in development for both Python and TypeScript SDKs, with newly created tools built for improved agent accuracy.++This feature is currently in development for both Python and TypeScript SDKs.++## API Endpoints++The following table lists important API endpoints that have changed. You can use this reference to quickly find the new v3 API endpoint for migration:++<Callout type="info">+This list is not exhaustive. Please refer to the [API Reference](/api-reference) for the complete list of endpoints.+</Callout>++### Toolkits (formerly Apps)++| Previous Endpoint | Current Endpoint |+| :--- | :--- |+| `GET /api/v1/apps` | `GET /api/v3/toolkits` |+| `GET /api/v1/apps/list/categories` | `GET /api/v3/toolkits/categories` |+| `GET /api/v1/apps/{appName}` | `GET /api/v3/toolkits/{slug}` |++### Tools (formerly Actions)++| Previous Endpoint | Current Endpoint |+| :--- | :--- |+| `GET /api/v2/actions` | `GET /api/v3/tools` |+| `GET /api/v2/actions/list/enums` | `GET /api/v3/tools/enum` |+| `GET /api/v2/actions/{actionId}` | `GET /api/v3/tools/{tool_slug}` |+| `POST /api/v2/actions/{actionId}/execute` | `POST /api/v3/tools/execute/{tool_slug}` |+| `POST /api/v2/actions/{actionId}/execute/get.inputs` | `POST /api/v3/tools/execute/{tool_slug}/input` |+| `POST /api/v2/actions/proxy` | `POST /api/v3/tools/execute/proxy` |++### Auth Configs (formerly Integrations/Connectors)++| Previous Endpoint | Current Endpoint |+| :--- | :--- |+| `GET /api/v1/integrations` | `GET /api/v3/auth_configs` |+| `POST /api/v1/integrations` | `POST /api/v3/auth_configs` |+| `GET /api/v1/integrations/{integrationId}` | `GET /api/v3/auth_configs/{nanoid}` |+| `PATCH /api/v1/integrations/{integrationId}` | `PATCH /api/v3/auth_configs/{nanoid}` |+| `DELETE /api/v1/integrations/{integrationId}` | `DELETE /api/v3/auth_configs/{nanoid}` |+| `POST /api/v2/integrations/create` | `POST /api/v3/auth_configs` |++### Connected Accounts (formerly Connections)++| Previous Endpoint | Current Endpoint |+| :--- | :--- |+| `GET /api/v1/connectedAccounts` | `GET /api/v3/connected_accounts` |+| `POST /api/v1/connectedAccounts` | `POST /api/v3/connected_accounts` |+| `POST /api/v2/connectedAccounts/initiateConnection` | `POST /api/v3/connected_accounts` |+| `GET /api/v1/connectedAccounts/{connectedAccountId}` | `GET /api/v3/connected_accounts/{nanoid}` |+| `DELETE /api/v1/connectedAccounts/{connectedAccountId}` | `DELETE /api/v3/connected_accounts/{nanoid}` |+| `POST /api/v1/connectedAccounts/{connectedAccountId}/disable` | `PATCH /api/v3/connected_accounts/{nanoId}/status` |+| `POST /api/v1/connectedAccounts/{connectedAccountId}/enable` | `PATCH /api/v3/connected_accounts/{nanoId}/status` |+| `POST /api/v1/connectedAccounts/{connectedAccountId}/reinitiate` | `POST /api/v3/connected_accounts/{nanoid}/refresh` |++### Triggers++| Previous Endpoint | Current Endpoint |+| :--- | :--- |+| `GET /api/v1/triggers` | `GET /api/v3/triggers_types` |+| `GET /api/v1/triggers/list/enums` | `GET /api/v3/triggers_types/list/enum` |+| `GET /api/v2/triggers/{triggerName}` | `GET /api/v3/triggers_types/{slug}` |+| `GET /api/v1/triggers/active_triggers` | `GET /api/v3/trigger_instances/active` |+| `POST /api/v1/triggers/enable/{connectedAccountId}/{triggerName}` | `POST /api/v3/trigger_instances/{slug}/upsert` |+| `DELETE /api/v1/triggers/instance/{triggerInstanceId}` | `DELETE /api/v3/trigger_instances/manage/{triggerId}` |+| `PATCH /api/v1/triggers/instance/{triggerId}/status` | `PATCH /api/v3/trigger_instances/manage/{triggerId}` |diff --git a/fumadocs/content/docs/migration-guide/toolkit-versioning.mdx b/fumadocs/content/docs/migration-guide/toolkit-versioning.mdxnew file mode 100644index 000000000..2468aea9a--- /dev/null+++ b/fumadocs/content/docs/migration-guide/toolkit-versioning.mdx@@ -0,0 +1,157 @@+---+title: Toolkit versioning migration+description: Migrate to the new toolkit versioning system+---++Starting with Python SDK v0.9.0 and TypeScript SDK v0.2.0, manual tool execution requires explicit version specification. This is a breaking change from earlier versions where toolkit versioning was optional.++## Breaking change++Manual tool execution now requires explicit version specification. The `tools.execute()` method will fail without a version.++### Before (will fail)++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+# Raises ToolVersionRequiredError+result = composio.tools.execute(+ "GITHUB_CREATE_ISSUE",+ {"user_id": "user-123", "arguments": {...}}+)+```+ </Tab>+ <Tab value="TypeScript">+```typescript+// Throws ComposioToolVersionRequiredError+const result = await composio.tools.execute({+ toolSlug: "GITHUB_CREATE_ISSUE",+ userId: "user-123",+ arguments: {...}+});+```+ </Tab>+</Tabs>++### After (required)++Choose one of three migration strategies:++#### Option 1: Configure version at SDK level++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+from composio import Composio++# Pin specific versions for each toolkit+composio = Composio(+ api_key="YOUR_API_KEY",+ toolkit_versions={+ "github": "20251027_00",+ "slack": "20251027_00",+ "gmail": "20251027_00"+ }+)+```+ </Tab>+ <Tab value="TypeScript">+```typescript+import { Composio } from "@composio/core";++// Pin specific versions for each toolkit+const composio = new Composio({+ apiKey: "YOUR_API_KEY",+ toolkitVersions: {+ github: "20251027_00",+ slack: "20251027_00",+ gmail: "20251027_00"+ }+});+```+ </Tab>+</Tabs>++#### Option 2: Pass version with each execution++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+# Specify version directly in execute call+result = composio.tools.execute(+ "GITHUB_LIST_STARGAZERS",+ arguments={+ "owner": "ComposioHQ",+ "repo": "composio"+ },+ user_id="user-k7334",+ version="20251027_00" # Override version for this execution+)+print(result)+```+ </Tab>+ <Tab value="TypeScript">+```typescript+// Specify version directly in execute call+const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {+ userId: "user-k7334",+ arguments: {+ owner: "ComposioHQ",+ repo: "composio"+ },+ version: "20251027_00" // Override version for this execution+});+console.log(result);+```+ </Tab>+</Tabs>++#### Option 3: Use environment variables++```bash+export COMPOSIO_TOOLKIT_VERSION_GITHUB="20251027_00"+```++## Migration checklist++1. **Audit your code**: Find all `tools.execute()` calls in your codebase+2. **Choose a strategy**: Select one of the three options above based on your needs+3. **Test thoroughly**: Verify tools work correctly with pinned versions+4. **Deploy gradually**: Roll out changes incrementally to minimize risk++## Temporary workaround++During migration, you can temporarily skip version checks (not recommended for production):++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+result = composio.tools.execute(+ "GITHUB_CREATE_ISSUE",+ {+ "user_id": "user-123",+ "arguments": {...}+ },+ dangerously_skip_version_check=True+)+```+ </Tab>+ <Tab value="TypeScript">+```typescript+const result = await composio.tools.execute({+ toolSlug: "GITHUB_CREATE_ISSUE",+ userId: "user-123",+ arguments: {...},+ dangerouslySkipVersionCheck: true+});+```+ </Tab>+</Tabs>++<Callout type="warn">+The `dangerouslySkipVersionCheck` flag is only for migration or debugging. Never use in production.+</Callout>++## Next steps++For complete documentation on toolkit versioning, including best practices and advanced configuration, see [Toolkit versioning](/docs/toolkit-versioning).diff --git a/fumadocs/content/docs/troubleshooting/api.mdx b/fumadocs/content/docs/troubleshooting/api.mdxnew file mode 100644index 000000000..376cafc7c--- /dev/null+++ b/fumadocs/content/docs/troubleshooting/api.mdx@@ -0,0 +1,18 @@+---+title: API+description: Troubleshooting API issues+---++## Reporting API issues++When reporting API issues to support, provide the following:++- **cURL command**: Include the exact cURL to reproduce the issue+- **Request ID**: Add `x-request-id: <uuid>` header to your request and share the UUID (generate at [uuidgenerator.net](https://www.uuidgenerator.net/))+- **Error details**: Share the complete error message+- **Reproduction steps**: Include any steps needed to reproduce the issue++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)diff --git a/fumadocs/content/docs/troubleshooting/authentication.mdx b/fumadocs/content/docs/troubleshooting/authentication.mdxnew file mode 100644index 000000000..6357f0b15--- /dev/null+++ b/fumadocs/content/docs/troubleshooting/authentication.mdx@@ -0,0 +1,43 @@+---+title: Authentication+description: Troubleshooting authentication issues+---++## Using Composio's default OAuth app++When using our default OAuth configuration:++- **Don't add additional scopes** - They may not be approved in our OAuth app+- Use only the pre-configured scopes provided++## Using custom OAuth apps++Ensure your OAuth app is configured correctly:++- **Redirect URL**: Must match exactly what's configured in your OAuth provider+- **Scopes**: Auth config scopes must match your OAuth app configuration+- **Credentials**: Verify client ID and secret are correct++For setup guides by toolkit: [OAuth Configuration Guides](https://composio.dev/oauth)++## Common authentication issues++- **Invalid redirect URI**: Check the callback URL matches exactly+- **Scope mismatch**: Ensure requested scopes are configured in both auth config and OAuth app+- **Expired tokens**: Try refreshing the connection+- **Rate limits**: Some providers limit authentication attempts+- **Credentials showing as `REDACTED`**: The "Mask Connected Account Secrets" setting is enabled on your account, which redacts all sensitive credential data. Navigate to **Settings → Project Settings → Project Configuration** and disable "Mask Connected Account Secrets" to view actual values++## Reporting authentication issues++When reporting to support, provide:++- **Error message**: Complete error details and screenshots+- **Auth config ID**: The `authConfigId` being used+- **Connected account ID**: If a connection was already created+- **OAuth provider**: Which service you're trying to connect++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)diff --git a/fumadocs/content/docs/troubleshooting/cli.mdx b/fumadocs/content/docs/troubleshooting/cli.mdxnew file mode 100644index 000000000..d2f6c2935--- /dev/null+++ b/fumadocs/content/docs/troubleshooting/cli.mdx@@ -0,0 +1,91 @@+---+title: CLI+description: Troubleshooting CLI issues+---++## Command not found++Verify the CLI is installed and in your PATH:++```bash+which composio+```++If not found, reinstall:++```bash+curl -fsSL https://composio.dev/install | bash+```++Or add to PATH:++```bash+echo 'export PATH="$HOME/.composio:$PATH"' >> ~/.bashrc && source ~/.bashrc+```++## Authentication errors++Check current authentication:++```bash+composio whoami+```++Re-authenticate if needed:++```bash+composio logout+composio login+```++For CI/CD, use environment variable:++```bash+export COMPOSIO_API_KEY="your-api-key"+```++## Type generation issues++### Project type not detected++Use language-specific commands:++```bash+composio ts generate # TypeScript+composio py generate # Python+```++### Output directory missing++Specify output directory explicitly:++```bash+composio generate --output-dir ./my-types+```++## Debug CLI issues++Enable debug logging:++```bash+composio --log-level debug [command]+```++Check version compatibility:++```bash+composio version+```++## Common issues++- **API key not found**: Run `composio login`+- **Project type detection fails**: Use language-specific commands or ensure you're in project root+- **Network timeout**: Check internet connection and proxy settings+- **Permission denied**: Check directory write permissions++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)+- **GitHub**: [Create an issue](https://github.com/ComposioHQ/composio/issues/new?labels=bug)diff --git a/fumadocs/content/docs/troubleshooting/dashboard.mdx b/fumadocs/content/docs/troubleshooting/dashboard.mdxnew file mode 100644index 000000000..2b675ec20--- /dev/null+++ b/fumadocs/content/docs/troubleshooting/dashboard.mdx@@ -0,0 +1,20 @@+---+title: Dashboard+description: Troubleshooting dashboard issues+---++## Reporting dashboard issues++When reporting dashboard issues to support, provide:++- **Screenshot or recording**: Visual evidence of the issue+- **Error details**: Complete error message shown in the UI+- **Network logs**: Check browser DevTools for failing API calls and share:+ - Error message+ - Request ID (`x-request-id` header)+ - Failed endpoint URL++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)diff --git a/fumadocs/content/docs/troubleshooting/index.mdx b/fumadocs/content/docs/troubleshooting/index.mdxnew file mode 100644index 000000000..fffb65062--- /dev/null+++ b/fumadocs/content/docs/troubleshooting/index.mdx@@ -0,0 +1,31 @@+---+title: Troubleshooting+description: Common issues and quick links+---++import { Bug, Brain, Sparkles, MessageCircle, MessageSquare, BookOpen } from 'lucide-react';++This section is designed to help you quickly identify and resolve common issues encountered with Composio.++Some quick links:++<Cards>+ <Card title="Report issues" href="https://github.com/ComposioHQ/composio/issues/new?labels=bug" icon={<Bug />}>+ Found a bug? Please create a Github issue!+ </Card>+ <Card title="Ask AI" href="https://deepwiki.com/ComposioHQ/composio" icon={<Brain />}>+ Try to use Ask AI in the docs or deepwiki to get the fastest responses on features, types, and best practices.+ </Card>+ <Card title="Feature requests" href="https://github.com/ComposioHQ/composio/issues/new?labels=enhancement" icon={<Sparkles />}>+ Have an idea for improving Composio? Share your feature suggestions with us and we will prioritise your requests+ </Card>+ <Card title="Ask the community" href="https://github.com/ComposioHQ/composio/discussions" icon={<MessageCircle />}>+ Join our GitHub discussions to get help from the community+ </Card>+ <Card title="Discord community" href="https://discord.com/channels/1170785031560646836/1268871288156323901" icon={<MessageSquare />}>+ Post support queries on our discord channel or reach out to [email protected]+ </Card>+ <Card title="Migration guides" href="/docs/migration-guide" icon={<BookOpen />}>+ Check out our migration guides to help you upgrade to the latest version.+ </Card>+</Cards>diff --git a/fumadocs/content/docs/troubleshooting/mcp.mdx b/fumadocs/content/docs/troubleshooting/mcp.mdxnew file mode 100644index 000000000..bf4c7a81d--- /dev/null+++ b/fumadocs/content/docs/troubleshooting/mcp.mdx@@ -0,0 +1,48 @@+---+title: MCP+description: Troubleshooting MCP server issues+---++## Connected account not found error++This error occurs when MCP cannot find a valid connected account for authentication:++- **Specify an account**: Provide either `connected_account_id` or `user_id` in your MCP configuration+- **Default behavior**: Without specification, MCP uses `user_id=default`. If multiple connections exist with the same user_id, the most recent is used+- **Verification checklist**:+ - Account status is `ACTIVE` (not deleted)+ - Account belongs to the same auth config used to create the MCP server++Learn more: [MCP Quickstart](/docs/mcp-quickstart)++## Getting 404 errors++Verify your URL format matches one of these patterns:++- `https://mcp.composio.dev/composio/server/<UUID>/mcp`+- `https://apollo-<randomID>-composio.vercel.app/v3/mcp/<UUID>`+- `https://apollo.composio.dev/v3/mcp/<UUID>`++## Testing and debugging++If experiencing issues, test your MCP server with:++- [Postman MCP Requests](https://learning.postman.com/docs/postman-ai-developer-tools/mcp-requests/create/)+- [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)++This helps identify whether the issue is with your MCP client or the server.++## Reporting MCP issues++When reporting to support, provide:++- **Error message**: Complete error details+- **MCP server URL**: The exact URL you're connecting to+- **Testing results**: Whether issue reproduces in MCP Inspector/Postman or only in specific client+- **Connected account ID**: If facing connection issues+- **Reproduction steps**: Clear steps to reproduce the issue++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)diff --git a/fumadocs/content/docs/troubleshooting/meta.json b/fumadocs/content/docs/troubleshooting/meta.jsonnew file mode 100644index 000000000..ab36ebb3c--- /dev/null+++ b/fumadocs/content/docs/troubleshooting/meta.json@@ -0,0 +1,14 @@+{+ "title": "Troubleshooting",+ "pages": [+ "index",+ "api",+ "authentication",+ "cli",+ "dashboard",+ "mcp",+ "sdks",+ "tools",+ "triggers"+ ]+}diff --git a/fumadocs/content/docs/troubleshooting/sdks.mdx b/fumadocs/content/docs/troubleshooting/sdks.mdxnew file mode 100644index 000000000..25915c9c5--- /dev/null+++ b/fumadocs/content/docs/troubleshooting/sdks.mdx@@ -0,0 +1,55 @@+---+title: SDKs+description: Troubleshooting SDK issues+---++## Debug network issues++Enable debug logging to see API calls and identify if issues are SDK or API related. Look for the `x-request-id` in logs to share with support.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```bash+# Set environment variable+COMPOSIO_LOGGING_LEVEL=debug+```+ </Tab>+ <Tab value="TypeScript">+```bash+// Set environment variable+COMPOSIO_LOG_LEVEL=debug+```+ </Tab>+</Tabs>++## Check SDK version++Ensure you're using the latest version:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```bash+pip install --upgrade composio+```+ </Tab>+ <Tab value="TypeScript">+```bash+npm install @composio/core@latest+```+ </Tab>+</Tabs>++Check current version:+- Python: [PyPI](https://pypi.org/project/composio/)+- TypeScript: [npm](https://www.npmjs.com/package/@composio/core)++## Common issues++- **Type errors or parameter confusion**: Search [DeepWiki](https://deepwiki.com/ComposioHQ/composio) or use the Ask AI assistant+- **Tool-specific issues**: Check the [specific tool's documentation](/toolkits/introduction)+- **Bug reporting**: Create a [GitHub issue](https://github.com/ComposioHQ/composio/issues/new?labels=bug) with debug logs and reproduction steps++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)diff --git a/fumadocs/content/docs/troubleshooting/tools.mdx b/fumadocs/content/docs/troubleshooting/tools.mdxnew file mode 100644index 000000000..d46ce67a7--- /dev/null+++ b/fumadocs/content/docs/troubleshooting/tools.mdx@@ -0,0 +1,52 @@+---+title: Tools & Toolkits+description: Troubleshooting tool execution issues+---++## Tool execution failures (401/403 errors)++Authentication and permission errors typically occur due to:++### Missing scopes++Check if your connection has the required scopes using this API:++```bash+curl --location 'https://backend.composio.dev/api/v3/tools/get_scopes_required' \+--header 'x-api-key: YOUR_COMPOSIO_API_KEY' \+--header 'Content-Type: application/json' \+--data '{+ "tools": [+ "SLACK_SENDS_A_MESSAGE_TO_A_SLACK_CHANNEL",+ "SLACK_CREATE_A_REMINDER"+ ]+}'+```++### Insufficient permissions++Verify the connected account has necessary permissions:++- **Admin requirements**: Some tools require admin-level access+- **Paid accounts**: Certain toolkits need paid subscriptions+ - Example: MS Teams requires Microsoft 365 account + Azure AD tenant++## Tool not working++- Check [tool-specific documentation](/toolkits/introduction) for requirements+- Verify the connected account is active and properly authenticated+- Test with the latest SDK version++## Reporting tool issues++When reporting to support, provide:++- **Error message**: Complete error details+- **Log ID**: From the error response+- **Tool name**: Exact tool slug being executed+- **Connected account ID**: Account used for execution++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)diff --git a/fumadocs/content/docs/troubleshooting/triggers.mdx b/fumadocs/content/docs/troubleshooting/triggers.mdxnew file mode 100644index 000000000..f85d666d7--- /dev/null+++ b/fumadocs/content/docs/troubleshooting/triggers.mdx@@ -0,0 +1,33 @@+---+title: Triggers+description: Troubleshooting trigger issues+---++## Unable to create trigger++Check the error message - the account might not have sufficient permissions or required scopes.++## Type errors with trigger payloads++Having issues with trigger payload types? Search [DeepWiki](https://deepwiki.com/ComposioHQ/composio) or use the Ask AI assistant for type definitions and examples.++## Not receiving trigger payloads++Even if the action occurred (email received, Jira issue created, etc.), there may be delays:++- **Gmail triggers**: Uses polling with minimum 1-minute frequency - expect delays of up to a minute+- **Other services**: May have their own polling intervals or webhook delivery delays++## Reporting trigger issues++When reporting to support, provide:++- **Error message**: Complete error details+- **Connected account**: The account ID used for creating the trigger+- **cURL command**: To reproduce the issue+- **Reproduction steps**: Any additional steps needed++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)diff --git a/fumadocs/public/images/debugging-info.png b/fumadocs/public/images/debugging-info.pngnew file mode 100644index 000000000..ee83003e0Binary files /dev/null and b/fumadocs/public/images/debugging-info.png differdiff --git a/fumadocs/public/images/project-settings.jpeg b/fumadocs/public/images/project-settings.jpegnew file mode 100644index 000000000..01cb30d7dBinary files /dev/null and b/fumadocs/public/images/project-settings.jpeg differ