AISDK MCP Bridge

A bridge package that enables seamless integration between the Model Context Protocol (MCP) and AI SDK, allowing for efficient communication and tool execution between MCP servers and AI models.

Features

Seamless integration between MCP servers and AI SDK
Support for various MCP server types (Node.js, Python, UVX)
Multi-server support with independent configuration
Flexible configuration through mcp.config.json
TypeScript support with full type definitions
Robust error handling and logging
Easy-to-use API for tool execution

Installation

npm install aisdk-mcp-bridge

Quick Start

Create an mcp.config.json file in your project root:

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@enescinar/twitter-mcp"],
      "env": {
        "API_KEY": "your-twitter-api-key",
        "API_SECRET_KEY": "your-twitter-api-secret",
        "ACCESS_TOKEN": "your-twitter-access-token",
        "ACCESS_TOKEN_SECRET": "your-twitter-access-token-secret"
      }
    },
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "mcp-server-firecrawl"],
      "env": {
        "FIRE_CRAWL_API_KEY": "your-firecrawl-api-key",
        "FIRE_CRAWL_API_URL": "https://api.firecrawl.com"
      }
    }
  }
}

Import and use the bridge in your code:

import { generateText } from 'ai';
import { google } from '@ai-sdk/google';
import { getMcpTools, cleanupMcp, initializeMcp } from 'aisdk-mcp-bridge';
import dotenv from 'dotenv';
dotenv.config();

async function main() {
  try {
    // Initialize MCP
    await initializeMcp({ debug: true });

    // Get tools from all servers
    const allTools = await getMcpTools({ debug: true });


            
        
            
                    // Or get tools from a specific server
    const twitterTools = await getMcpTools({
      debug: true,
      serverName: 'twitter-mcp',
    });

    // Use tools with AI SDK
    const result = await generateText({
      model: google('gemini-1.5-pro'),
      messages: [
        {
          role: 'system',
          content:
            'You are an AI assistant that uses various tools to help users.',
        },
        {
          role: 'user',
          content: 'Your task description here',
        },
      ],
      tools: twitterTools, // or allTools for all available tools
    });

    console.log('Result:', result.text);
  } finally {
    // Clean up resources
    await cleanupMcp();
  }
}

main().catch(error => {
  console.error('Error:', error);
  process.exit(1);
});

Configuration

The mcp.config.json file supports multiple servers and communication modes. Each server can be configured independently.

Server Configuration Examples:

Twitter MCP Server

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@enescinar/twitter-mcp"],
      "env": {
        "API_KEY": "your-twitter-api-key",
        "API_SECRET_KEY": "your-twitter-api-secret",
        "ACCESS_TOKEN": "your-twitter-access-token",
        "ACCESS_TOKEN_SECRET": "your-twitter-access-token-secret"
      }
    }
  }
}

Firecrawl Server

{
  "mcpServers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "mcp-server-firecrawl"],
      "env": {
        "FIRE_CRAWL_API_KEY": "your-firecrawl-api-key",
        "FIRE_CRAWL_API_URL": "https://api.firecrawl.com"
      }
    }
  }
}

SSE Server

{
  "mcpServers": {
    "sse-server": {
      "command": "node",
      "args": ["./server.js"],
      "mode": "sse",
      "sseOptions": {
        "endpoint": "http://localhost:3000/events",
        "headers": {},
        "reconnectTimeout": 5000
      }
    }
  }
}

Server Modes

            The bridge supports different communication modes:

stdio Mode (Default)
- Direct communication through standard input/output
- Best for simple integrations and local development
- Low latency and minimal setup required
SSE Mode (Server-Sent Events)
- Real-time, one-way communication from server to client
- Ideal for streaming updates and long-running operations
- Built-in reconnection handling

API Reference

Core Functions

`initializeMcp(options?: InitOptions): Promise`

Initialize the MCP service with the provided options.

interface InitOptions {
  configPath?: string; // Path to mcp.config.json
  debug?: boolean; // Enable debug logging
}

`getMcpTools(options?: ToolOptions): Promise`

Get AI SDK-compatible tools from MCP servers.

interface ToolOptions {
  debug?: boolean; // Enable debug logging
  serverName?: string; // Optional server name to get tools from a specific server
}

`executeMcpFunction(serverName: string, functionName: string, args: Record): Promise`

Execute a specific function on an MCP server directly.

// Example
const result = await executeMcpFunction('twitter-mcp', 'postTweet', {
  text: 'Hello from MCP!',
});

Core Types

`MCPConfig` (alias for `MCPServersConfig`)

Configuration type for MCP servers.

interface MCPConfig {
  mcpServers: {
    [key: string]: ServerConfig;
  };
}

`ServerConfig`

Configuration for individual MCP servers.

interface ServerConfig {
  command: string;
  args?: string[];
  env?: Record;
  mode?: 'stdio' | 'sse';
  sseOptions?: {
    endpoint: string;
    headers?: Record;
    reconnectTimeout?: number;
  };
}

`MCPToolResult`

Result type for MCP tool executions.

interface MCPToolResult {
  success: boolean;
  data?: unknown;
  error?: string;
}

            #### `cleanupMcp(): Promise`

Clean up MCP resources and close all server connections.

Error Handling

The bridge includes comprehensive error handling for:

Server initialization failures
Communication errors
Tool execution failures
Configuration issues
Server connection issues

Logging

The bridge provides detailed logging through:

mcp-tools.log: Server-side tool execution logs
Console output for debugging and errors

Debug Logging

You can enable detailed debug logging by setting the DEBUG environment variable:

# Enable all debug logs
DEBUG=* npm start

# Enable MCP debug logs
DEBUG=mcp npm start

# Enable all MCP namespace logs
DEBUG=mcp:* npm start

Debug logs will show:

Server initialization and shutdown events
Tool registration and execution details
Communication with MCP servers
Schema conversions and validations
Error details with stack traces
Performance metrics and timing information

Log Types

The logging system supports three types of logs:

info: General operational information
debug: Detailed debugging information (requires DEBUG env variable)
error: Error messages and stack traces (always logged)

Log File

All logs are written to logs/mcp-tools.log with the following format:

[TIMESTAMP] [TYPE] Message
{Optional JSON data}

Development

Prerequisites

Node.js 20.x or higher
npm 7.x or higher

Setup

Clone the repository
Install dependencies:

npm install

Testing

Run the test suite:

npm test

Run specific tests:


npm run test:twitter
npm run test:firecrawl

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

Setting up the development environment
Coding standards
Pull request process

Adding new MCP servers

          Please note that this project is released with a [Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.

Support

For support:

Check the documentation
Search existing issues
Create a new issue if your problem persists

Changelog

See CHANGELOG.md for a list of changes and migration guides.

Security

For security issues, please email ravi@caw.tech instead of using the public issue tracker.

Authors

Ravi Kiran - Initial work - @vrknetha

See also the list of contributors who participated in this project.

Acknowledgments

AI SDK team for their excellent SDK
MCP community for the protocol specification
All contributors who have helped with the project

License

This project is licensed under the MIT License - see the LICENSE file for details.

aisdk-mcp-bridge

Categories

Language:

Stars:

Forks: