diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 62b155af2a1..ffc94561ac5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -79,16 +79,55 @@ To contribute to the documentation: 1. Make sure you have Node.js installed on your system. -2. Install Fern CLI globally: +2. Generate the SDK documentation first: + + a. Make sure you're in your virtual environment: + ```bash + source .venv/bin/activate # On Windows: .venv\Scripts\activate + ``` + + b. Install typing-extensions (required for documentation generation): + ```bash + pip install typing-extensions + ``` + + c. Generate Python SDK documentation: + ```bash + python scripts/generate_api_docs.py --source ./python/composio --output ./fern/sdk + ``` + + d. Install Bun (required for TypeScript documentation): + ```bash + curl -fsSL https://bun.sh/install | bash + ``` + + e. Install TypeDoc dependencies: + ```bash + bun install typedoc typedoc-plugin-markdown + ``` + + f. Generate TypeScript SDK documentation: + ```bash + bun run typedoc --plugin typedoc-plugin-markdown js/src/index.ts js/src/sdk/index.ts --out ./fern/sdk/composio/js --skipErrorChecking + ``` + + g. Install Fern globally: ```bash npm install -g fern-api ``` 3. Start the docs server from the project root: ```bash - fern docs dev + make docs-dev ``` 4. View and edit docs at http://localhost:3000 -5. When you're happy with your changes, create a PR. \ No newline at end of file +5. Before submitting your PR, check for broken links: + ```bash + fern docs broken-links + ``` + This will ensure your documentation changes don't introduce any broken references. + +6. When you're happy with your changes, create a PR. + diff --git a/fern/assets/images/mcp_server_client.png b/fern/assets/images/mcp_server_client.png new file mode 100644 index 00000000000..6a25b70f264 Binary files /dev/null and b/fern/assets/images/mcp_server_client.png differ diff --git a/fern/assets/videos/mcp-claude-oauth.mp4 b/fern/assets/videos/mcp-claude-oauth.mp4 new file mode 100644 index 00000000000..087cd1ee5b1 Binary files /dev/null and b/fern/assets/videos/mcp-claude-oauth.mp4 differ diff --git a/fern/assets/videos/mcp-claude.mp4 b/fern/assets/videos/mcp-claude.mp4 new file mode 100644 index 00000000000..58ea64bfc25 Binary files /dev/null and b/fern/assets/videos/mcp-claude.mp4 differ diff --git a/fern/assets/videos/mcp-cursor-oauth.mp4 b/fern/assets/videos/mcp-cursor-oauth.mp4 new file mode 100644 index 00000000000..9d560484bdd Binary files /dev/null and b/fern/assets/videos/mcp-cursor-oauth.mp4 differ diff --git a/fern/assets/videos/mcp-cursor.mp4 b/fern/assets/videos/mcp-cursor.mp4 new file mode 100644 index 00000000000..f65c894134f Binary files /dev/null and b/fern/assets/videos/mcp-cursor.mp4 differ diff --git a/fern/docs.yml b/fern/docs.yml index fd249a025fa..2e7d66b1980 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -220,23 +220,27 @@ navigation: contents: - page: Using Triggers path: triggers/triggers.mdx - - section: Resources - icon: book + + - section: MCP + icon: plug contents: - - page: Glossary - path: resources/glossary.mdx - icon: asterisk - hidden: true - - link: Cursor MCP - href: https://composio.notion.site/Cursor-MCP-Docs-1adf261a6dfe80b4ba5fe492bf41441c - icon: fa-solid fa-mouse-pointer - - link: Claude MCP - href: - https://composio.notion.site/Composio-MCP-Integration-for-Claude-1adf261a6dfe80609836e4e5021e9d44 - icon: asterisk - - link: Windsurf MCP - href: https://composio.notion.site/Windsurf-1adf261a6dfe80c2b538c6b0a02b44c8 - icon: fa-solid fa-water + - page: Introduction + path: mcp/introduction.mdx + - page: Cursor + path: mcp/cursor.mdx + - page: Claude + path: mcp/claude.mdx + - page: Windsurf + path: mcp/windsurf.mdx + + # - section: Resources + # icon: book + # contents: + # - page: Glossary + # path: resources/glossary.mdx + # icon: asterisk + # hidden: true + - tab: frameworks layout: - section: Model Providers diff --git a/fern/mcp/claude.mdx b/fern/mcp/claude.mdx new file mode 100644 index 00000000000..7e4bf34de89 --- /dev/null +++ b/fern/mcp/claude.mdx @@ -0,0 +1,87 @@ +--- +title: Composio MCP with Claude +--- + + +Node.js versions below 10 are not supported and may cause issues. **Uninstall any older Node.js versions** before proceeding. + + +This guide covers installation, authentication flows, and troubleshooting for MCP tools in Claude Desktop. + +## Installation + +1. **Check NodeJS Installation** + - Verify NodeJS is installed on your system: `node -v` + + - If not installed, download from [nodejs.org](https://nodejs.org/). + +2. **Install MCP Tools** + - Paste the command generated from the [mcp.composio.dev](http://mcp.composio.dev): + + ```bash + Your generated code + ``` + +3. **Verify Installation** + - Restart the Claude Desktop app and check installed tools by clicking the "hammer" icon in the Claude chat interface. + + + + + +## Authentication Methods + +Composio MCP supports two authentication methods: + +### OAuth Authentication + +1. **Connection Check:** +Ask the LLM if there is any active connection with the said app. +2. **Initiate Connection:** +If no active connection exists, ask the LLM to initiate a connection. +3. **Complete Authentication:** +Click the provided authentication link and complete the OAuth flow in your browser. +4. **Execute Actions:** +Once authenticated, the LLM can execute authorized actions. + + + + + +### API Key Authentication + +1. **Connection Verification:** +Ask the LLM if there is any active connection with the said app. +2. **Initiate Connection:** +If no active connection exists, ask the LLM to initiate a connection. +3. **Request API Key:** +The LLM initiates a connection and prompts for your API key. +4. **Enter Credentials:** +Paste your API key when prompted in the chat interface. + + + API key entry will be streamlined in future updates. + + +5. Execute actions +After successful authentication, the tool is ready for use. + + + +### 1. Missing Authentication Link + +If the authentication link doesn't appear in chat: + +- Explicitly request the link by asking: "Connect to [App name] first and output the auth link." +- Or specify: "Run COMPOSIO_INITIATE_CONNECTION for [App name] and output the auth link" + +### 2. Connection Verification Issues + +If the LLM skips connection verification and starts executing tools: + +- Manually request connection initiation: "Run COMPOSIO_INITIATE_CONNECTION for [app name] and provide the authentication link." + + +Important: We are actively working on improving the tool execution flow. These troubleshooting steps are quick solutions to help you get started. + + \ No newline at end of file diff --git a/fern/mcp/cursor.mdx b/fern/mcp/cursor.mdx new file mode 100644 index 00000000000..d2a2d5d96d8 --- /dev/null +++ b/fern/mcp/cursor.mdx @@ -0,0 +1,101 @@ +--- +title: Composio MCP with Cursor +--- + +This guide covers installation, authentication flows, and troubleshooting for MCP tools in Cursor. + +## Installation + +1. **Check Node.js Installation** + - Make sure Node.js is installed on your system by running: + + ```bash + node -v + ``` + + - If Node.js is not installed, download it from [nodejs.org](https://nodejs.org/). + - **Note**: For best results, use Node.js 10 or higher. We don't support earlier versions. +2. **Install MCP Tools** + - Paste the `npx` command generated by [mcp.composio.dev](http://mcp.composio.dev/) into your terminal: + + ```bash + # Example: + Your generated code + ``` + + - This command installs the MCP tools and configures them for use in Cursor. +3. **Verify Installation** + - Open Cursor settings and navigate to **MCP** to confirm the MCP servers are installed. + - If everything looks correct, you can start using MCP features directly in Cursor. + + + + + +## Authentication Methods + +Composio MCP supports two authentication methods: + +### OAuth Authentication + +1. **Connection Check:** +Ask the LLM if there is any active connection with the said app. +2. **Initiate Connection:** +If no active connection exists, ask the LLM to initiate a connection. +3. **Complete Authentication:** +Click the provided authentication link and complete the OAuth flow in your browser. +4. **Execute Actions:** +Once authenticated, the LLM can execute authorized actions. + + + + + +### API Key Authentication + +1. **Connection Verification:** +Ask the LLM if there is any active connection with the said app. +2. **Initiate Connection:** +If no active connection exists, ask the LLM to initiate a connection. +3. **Request API Key:** +The LLM initiates a connection and prompts for your API key. +4. **Enter Credentials:** +Paste your API key when prompted in the chat interface. + + + API key entry will be streamlined in future updates. + + +5. Execute actions +After successful authentication, the tool is ready for use. + + + +### 1. Missing Authentication Link + +If the authentication link doesn't appear in chat: + +- Explicitly request the link by asking: "Connect to [App name] first and output the auth link." +- Or specify: "Run COMPOSIO_INITIATE_CONNECTION for [App name] and output the auth link" + +### 2. Connection Verification Issues + +If the LLM skips connection verification and starts executing tools: + +- Manually request connection initiation: "Run COMPOSIO_INITIATE_CONNECTION for [app name] and provide the authentication link." + + +Important: We are actively working on improving the tool execution flow. These troubleshooting steps are temporary solutions to help you get started. + + + +## Best Practices + +For optimal performance and reliability, follow these recommended practices when using MCP tools in Cursor: + +- **Limit MCP Servers:** + - To ensure stable connectivity and proper functionality, connect **no more than 3 MCP servers simultaneously**. Connecting more than 3 servers may result in authentication issues or connection failures. + + +Connecting more than the recommended number of MCP servers can lead to unexpected behavior. Adhering to these best practices will help you get the most out of MCP tools in Cursor. + diff --git a/fern/mcp/introduction.mdx b/fern/mcp/introduction.mdx new file mode 100644 index 00000000000..0e197f22e66 --- /dev/null +++ b/fern/mcp/introduction.mdx @@ -0,0 +1,46 @@ +### What is MCP? + +The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open standard developed by Anthropic to help AI models, especially Large Language Models (LLMs), connect with external data sources and tools. Think of it like a universal adapter that lets AI systems access real-time information from places like databases, APIs, or business tools, making their responses more relevant and accurate. This is particularly useful for AI-powered applications like chatbots or IDEs, where access to up-to-date data can enhance functionality. + +### How Server-Client Interactions Work + +MCP operates on a client-server model: + +- The **client** (or host) is the AI application, like Claude Desktop or an IDE, that needs data. +- The **server** exposes tools, prompts, and resources that the client can use. + + + Client and server + + +Interactions happen through two kinds of [transport layers](https://modelcontextprotocol.io/docs/concepts/transports#built-in-transport-types): + +- **Stdio transport:** Used when the server runs locally with the client, communicating through standard input and output. This is great for local development, as it’s simple and fast. +- **HTTP with SSE (Server-Sent Events) transport:** Used for remote servers, allowing real-time updates over HTTP. This is ideal for cloud-based setups, enabling the server to push updates to the client as they happen. + +### How Servers Are Deployed + +Servers can be set up in two main ways, depending on your needs: + +- **Local Deployment:** If you have the server code locally or can pull it from a repository, you can start it using simple commands. For example, the [GitHub MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/github) maintained by the `modelcontextprotocol` repository can be started by running `npx -y @modelcontextprotocol/server-github` with the GitHub personal access token specified in the environment. Most MCP clients let you specify the command to run, so they can start the server directly when needed, which is great for development. +- **Remote Deployment (SSE Servers):** For remote use, servers are deployed to a web endpoint somewhere, and all you need is the SSE URL to connect your client. There’s no need for local setup or running commands; the server is managed separately, making it hassle-free. Clients typically have an option to just take this URL and connect, which is convenient for cloud-based setups. + +Composio manages SSE servers for users, handling setup and maintenance, which means you don’t need to worry about the technical details. Check out the full list of [servers here](https://mcp.composio.dev/). + + +Currently we are not envisioning our fully managed MCP servers to function like a devtool and something you build on top of but rather for providers who have MCP as a way to quickly integrate with our tools. Read more about this here: [Building on top of Composio MCP](https://composio.notion.site/mcp-faq?pvs=4) + + +### Benefits of Using Composio MCP Servers + +Choosing Composio for hosting your MCP servers comes with several advantages: + +- **No Management Needed:** Composio takes care of server setup, updates, and maintenance, freeing you to focus on development. +- **Automatic Authentication:** Authentication is handled through [Composio’s integrations](https://composio.dev/tools), so you don’t need to manage API keys or credentials, reducing setup friction. +- **One-Click Installation:** You can connect to hundreds of servers with simple instructions, often integrating with clients in a single line of code, which is unexpectedly convenient for rapid deployment. + +### Exploring Further + +You can check out Composio’s offerings and find a list of available servers with one-click installation instructions at [Composio MCP](https://composio.dev/mcp/). For detailed setup guides on clients like Cursor, Windsurf, and Claude, refer to their documentation pages ([Cursor](./cursor.mdx), [Windsurf](./windsurf.mdx) and [Claude](./claude.mdx)). + +We also wrote an [extensive blogpost](https://composio.dev/blog/mcp-server-step-by-step-guide-to-building-from-scrtch/) that has a step-by-step guide to building MCP servers from scratch, what the different components of MCP are, how they work and more details on the Composio MCP integration. \ No newline at end of file diff --git a/fern/mcp/windsurf.mdx b/fern/mcp/windsurf.mdx new file mode 100644 index 00000000000..02f055f2de2 --- /dev/null +++ b/fern/mcp/windsurf.mdx @@ -0,0 +1,75 @@ +--- +title: Composio MCP with Windsurf +--- + +This guide covers installation, authentication flows, and troubleshooting for MCP tools in Windsurf IDE. + +## Installation + +1. **Check NodeJS Installation** + - Verify NodeJS is installed on your system: `node -v` + + - If not installed, download from [nodejs.org](https://nodejs.org/). + +2. **Install MCP Tools** + - Run the following command in your terminal: + + ```bash + npx composio-core@rc mcp "https://mcp.composio.dev/notion/RANDOM_SUFFIX" --client windsurf + ``` + +3. **Verify Installation** + - After running the command, restart Windsurf to start using the integration. + +## Authentication Methods + +Composio MCP supports two authentication methods: + +### OAuth Authentication + +1. **Connection Check:** +Ask the LLM if there is any active connection with the said app. +2. **Initiate Connection:** +If no active connection exists, ask the LLM to initiate a connection. +3. **Complete Authentication:** +Click the provided authentication link and complete the OAuth flow in your browser. +4. **Execute Actions:** +Once authenticated, the LLM can execute authorized actions. + +### API Key Authentication + +1. **Connection Verification:** +Ask the LLM if there is any active connection with the said app. +2. **Initiate Connection:** +If no active connection exists, ask the LLM to initiate a connection. +3. **Request API Key:** +The LLM initiates a connection and prompts for your API key. +4. **Enter Credentials:** +Paste your API key when prompted in the chat interface. + + + API key entry will be streamlined in future updates. + + +5. Execute actions +After successful authentication, the tool is ready for use. + + + +### 1. Missing Authentication Link + +If the authentication link doesn't appear in chat: + +- Explicitly request the link by asking: "Connect to [App name] first and output the auth link." +- Or specify: "Run COMPOSIO_INITIATE_CONNECTION for [App name] and output the auth link" + +### 2. Connection Verification Issues + +If the LLM skips connection verification and starts executing tools: + +- Manually request connection initiation: "Run COMPOSIO_INITIATE_CONNECTION for [app name] and provide the authentication link." + + +We are actively working on improving the tool execution flow. These troubleshooting steps are temporary solutions to help you get started. + + \ No newline at end of file diff --git a/package.json b/package.json index 9fd2554bb73..fc5cf9dd6bb 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,10 @@ { "dependencies": { "supergateway": "^2.1.0" + }, + "devDependencies": { + "typedoc": "^0.28.1", + "typedoc-plugin-markdown": "^4.6.0" } + }