feat: add new example "with-composio-mcp"

examples/with-composio-mcp/.env.example

@@ -0,0 +1 @@
+OPENAI_API_KEY=sk-proj-

examples/with-composio-mcp/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.env
+.voltagent

examples/with-composio-mcp/README.md

@@ -0,0 +1,118 @@
+# VoltAgent Example: With Composio MCP
+
+This example demonstrates how to integrate VoltAgent with Composio's Model Context Protocol (MCP) server, allowing your agent to access and interact with various third-party services through a unified interface.
+
+## Features
+
+- **Composio MCP Integration:** Shows how to configure `MCPConfiguration` for an HTTP-based MCP server.
+- **Third-Party Service Access:** Connect to services like Gmail, Google Calendar, Google Drive, and 100+ other services.
+- **Built-in Authentication:** Leverage Composio's managed authentication for seamless integration.
+- **Customizable Permissions:** Specify exactly which actions and data your agent can access.
+
+## Prerequisites
+
+- Node.js (v18 or later recommended)
+- pnpm (or npm/yarn)
+- An OpenAI API key (or setup for another supported LLM provider)
+- A Composio MCP account (sign up at [https://mcp.composio.dev/](https://mcp.composio.dev/))
+
+## Setup
+
+1. **Clone the repository (if you haven't already):**
+
+   ```bash
+   git clone https://github.com/voltagent/voltagent.git
+   cd voltagent/examples/with-composio-mcp
+   ```
+
+2. **Install dependencies:**
+
+   ```bash
+   pnpm install
+   # or npm install / yarn install
+   ```
+
+3. **Create Environment File:**
+   Create a `.env` file in the `examples/with-composio-mcp` directory:
+
+   ```env
+   # .env
+   OPENAI_API_KEY=your_openai_api_key_here
+   ```
+
+   Replace `your_openai_api_key_here` with your actual OpenAI API key. Adjust the variable if using a different LLM provider.
+
+4. **Create a Composio MCP Account:**
+   - Visit [https://mcp.composio.dev/](https://mcp.composio.dev/)
+   - You can sign up using your Google account
+   - Once logged in, you'll see the MCP dashboard
+
+5. **Create an MCP Server:**
+   - From the dashboard, create a new MCP server for each application you want to integrate (Gmail, Google Drive, etc.)
+   - Alternatively, create a custom MCP with a combination of services
+   - After creating your MCP server, you'll need to copy the MCP server URL from the dashboard
+   - This URL will look like: `https://mcp.composio.dev/composio/server/YOUR-SERVER-ID`
+   - You'll need this URL to configure your agent in the `src/index.ts` file
+
+## Configuring Your MCP Server
+
+When setting up your MCP server, you'll need to:
+
+1. **Choose a Service:** Select from 100+ fully managed MCP servers with built-in authentication support
+2. **Configure Authentication:** For example, when connecting Google Calendar:
+   - Select authentication method:
+     - **OAuth 2.0 (Managed)**: Authenticate via OAuth login flow (managed by Composio)
+     - **Bearer Token**: Provide a bearer token for authentication
+   - For simplified authentication, choose the Composio-managed option where you won't need to provide any credentials
+3. **Select Actions:** Choose which specific actions your agent can perform with the service
+4. **Set Permissions:** Specify the exact permissions for each MCP server
+
+Clicking "Connect" will create an integration named "mcp-server" and immediately start the account connection process.
+
+## Running the Agent
+
+Start the agent in development mode:
+
+```bash
+pnpm run dev
+# or npm run dev / yarn dev
+```
+
+You should see logs indicating the MCP connection and tool fetching, followed by the standard VoltAgent startup message.
+
+## Interacting with the Agent
+
+1. Open the VoltAgent Developer Console: [`https://console.voltagent.dev`](https://console.voltagent.dev)
+2. Find the agent named `Composio MCP Agent`
+3. Click on the agent name, then click the chat icon
+4. Try sending messages that require interaction with the connected services
+
+The agent will use the Composio MCP tools to perform these actions.
+
+## Stopping the Agent
+
+Press `Ctrl+C` in the terminal where the agent is running to stop the agent.
+
+## Customizing the Integration
+
+In the `src/index.ts` file, you can modify the MCP configuration to use your own Composio MCP server URL:
+
+```typescript
+const mcpConfig = new MCPConfiguration({
+  servers: {
+    composio: {
+      type: "http",
+      url: "https://mcp.composio.dev/composio/server/YOUR-SERVER-ID",
+    }
+  },
+});
+```
+
+Replace `YOUR-SERVER-ID` with the ID of your Composio MCP server. You can find this URL in your Composio MCP dashboard after creating a server:
+
+1. Go to your Composio MCP dashboard at [https://mcp.composio.dev/](https://mcp.composio.dev/)
+2. Select the MCP server you created
+3. Look for the "MCP Server URL" or copy the URL from the server details
+4. Replace the URL in your `src/index.ts` file with the one from your dashboard
+
+This ensures your agent connects to your specific MCP server with the permissions and services you've configured.

examples/with-composio-mcp/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "voltagent-example-with-composio-mcp",
+  "version": "0.1.0",
+  "private": true,
+  "description": "VoltAgent example demonstrating Composio MCP integration.",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch --env-file=.env ./src",
+    "start": "node dist/index.js",
+    "volt": "volt"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^1.3.10",
+    "@voltagent/cli": "^0.1.3",
+    "@voltagent/core": "^0.1.7",
+    "@voltagent/vercel-ai": "^0.1.3",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.5",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}

examples/with-composio-mcp/src/index.ts

@@ -0,0 +1,34 @@
+import { VoltAgent, Agent, MCPConfiguration } from "@voltagent/core";
+import { VercelAIProvider } from "@voltagent/vercel-ai";
+import { openai } from "@ai-sdk/openai";
+
+async function main() {
+  try {
+    const mcpConfig = new MCPConfiguration({
+      servers: {
+        composio: {
+          type: "http",
+          url: "https://mcp.composio.dev/composio/server/YOUR-SERVER-ID",
+        }
+      },
+    });
+
+    const agent = new Agent({
+      name: "Composio MCP Agent",
+      description: "A helpful assistant using a lightweight provider",
+      tools: await mcpConfig.getTools(),
+      llm: new VercelAIProvider(),
+      model: openai("gpt-4o-mini"),
+    });
+
+    new VoltAgent({
+      agents: {
+        agent,
+      },
+    });
+  } catch (error) {
+    console.error("Failed to initialize VoltAgent:", error);
+  }
+}
+
+main();

examples/with-composio-mcp/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "outDir": "dist",
+    "strict": true,
+    "skipLibCheck": true // Often useful in examples
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}