Integrate Sdk

Tests License: MIT

A type-safe TypeScript SDK for connecting to the Integrate MCP (Model Context Protocol) server. Access GitHub, Gmail, Notion, and other integrations through a simple, integration-based API.

📚 Full Documentation | Server: https://mcp.integrate.dev/api/v1/mcp

Features

• 🔌 Integration-Based Architecture - Enable only the integrations you need
• 🔒 Fully Typed API - Type-safe methods with autocomplete (e.g., client.github.createIssue())
• 💡 IntelliSense Support - Full TypeScript support with parameter hints
• ⚡ Automatic Connection Management - Lazy connection, auto-cleanup, singleton pattern
• 🔐 Complete OAuth Flow - Built-in OAuth 2.0 with PKCE (popup/redirect modes)
• ⏰ Scheduled Triggers - Schedule tool executions with one-time or recurring triggers
• 🌍 Universal - Works in browser and Node.js environments
• 🛠️ Extensible - Configure integrations for any server-supported integration
• 📦 Zero Dependencies - Lightweight implementation

Installation

npm install integrate-sdk
# or
bun add integrate-sdk

Quick Start (2 Files Only!)

0. Configure OAuth Redirect URI

⚠️ Important: Configure your OAuth apps with this redirect URI:

http://localhost:3000/api/integrate/oauth/callback

• GitHub: Settings → Developer settings → OAuth Apps → Authorization callback URL
• Google/Gmail: Google Cloud Console → Credentials → Authorized redirect URIs

For production, use: https://yourdomain.com/api/integrate/oauth/callback

1. Create Server Config

Define your OAuth providers once. Integrations automatically read credentials from environment variables:

// lib/integrate-server.ts (server-side only!)
import {
  createMCPServer,
  githubIntegration,
  gmailIntegration,
} from "integrate-sdk/server";

// Integrations automatically use GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET,
// GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET from environment
export const { client: serverClient } = createMCPServer({
  integrations: [
    githubIntegration({
      scopes: ["repo", "user"],
    }),
    gmailIntegration({
      scopes: ["gmail.readonly"],
    }),
  ],
});

2. Create Single Catch-All Route

That's it! Just import and export:

// app/api/integrate/[...all]/route.ts
import { serverClient } from "@/lib/integrate-server";
import { toNextJsHandler } from "integrate-sdk/server";

export const { POST, GET } = toNextJsHandler({
  client: serverClient, // Pass the client
  redirectUrl: "/dashboard",
});

This imports your config from step 1 and handles ALL OAuth operations (authorize, callback, status, disconnect) in one file!

3. Use in Your App

Use the server client in API routes or server components:

// app/api/repos/route.ts
import { serverClient } from "@/lib/integrate-server";

export async function GET() {
  // Automatically connects on first call - no manual setup needed!
  const repos = await serverClient.github.listOwnRepos({ per_page: 10 });
  return Response.json({ repos });
}

Client-Side Setup

Use in your client components (no secrets needed):

"use client";
import { createMCPClient, githubIntegration } from "integrate-sdk";

const client = createMCPClient({
  integrations: [
    githubIntegration({
      scopes: ["repo", "user"],
      // No clientId or clientSecret needed!
    }),
  ],
  oauthFlow: { mode: "popup" },
});

// Authorize user (opens popup)
await client.authorize("github");

// Use the client - automatically connects!
const result = await client.github.createIssue({
  owner: "owner",
  repo: "repo",
  title: "Bug report",
  body: "Description of the bug",
});

console.log("Issue created:", result);

That's it! The SDK automatically:

• ✅ Connects on first method call (no manual connect() needed)
• ✅ Cleans up on exit (no manual disconnect() needed)
• ✅ Manages OAuth tokens securely through your API routes
• ✅ Provides full type safety with autocomplete

Connection Management

The SDK automatically manages connections for you - no manual connect() or disconnect() calls needed!

Features:

• Lazy Connection: Automatically connects on first method call
• Auto-Cleanup: Cleans up on process exit
• Singleton Pattern: Reuses connections efficiently (configurable)

// ✅ Default behavior - automatic connection
// Integrations automatically use GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET from environment
const client = createMCPClient({
  integrations: [
    githubIntegration({
      scopes: ["repo", "user"],
    }),
  ],
});

// Use immediately - no connect() needed!
await client.authorize("github");
await client.github.listRepos({ username: "octocat" });

// ✅ Want manual control? Use manual mode
const manualClient = createMCPClient({
  integrations: [githubIntegration({ scopes: ["repo"] })],
  connectionMode: "manual",
  singleton: false,
});

await manualClient.connect();
await manualClient.authorize("github");
await manualClient.github.listRepos({ username: "octocat" });
await manualClient.disconnect();

Need help? Check out the complete documentation for detailed guides, examples, and API reference.

Browser & Server Support

The SDK works in both environments:

• Browser: Use createMCPClient() from 'integrate-sdk' - handles OAuth UI (popup/redirect)
• Server: Use createMCPServer() from 'integrate-sdk/server' - includes OAuth secrets for API routes

See Quick Start above for complete examples.

Why Use Integrate SDK?

Typed Integration Methods

Instead of generic tool calls, use typed methods with full autocomplete:

// ✅ New: Typed methods with autocomplete
await client.github.createIssue({
  owner: "user",
  repo: "project",
  title: "Bug",
});
await client.gmail.sendEmail({ to: "[email protected]", subject: "Hello" });

Benefits

• Type Safety: Parameters are validated at compile time
• Autocomplete: Your IDE suggests available methods and parameters
• Documentation: Inline JSDoc comments for every method
• Refactoring: Rename methods safely across your codebase

Three Ways to Call Tools

// 1. Typed integration methods (recommended for built-in integrations like GitHub/Gmail)
await client.github.createIssue({
  owner: "user",
  repo: "project",
  title: "Bug",
});
await client.gmail.sendEmail({ to: "[email protected]", subject: "Hello" });

// 2. Typed server methods (for server-level tools)
await client.server.listToolsByIntegration({ integration: "github" });

// 3. Direct tool calls (for other server-supported integrations)
await client._callToolByName("slack_send_message", {
  channel: "#general",
  text: "Hello",
});

OAuth Authorization

The SDK implements OAuth 2.0 Authorization Code Flow with PKCE for secure authorization.

Key Features:

• ✅ Popup or redirect flow modes
• ✅ Session token management
• ✅ Multiple provider support
• ✅ PKCE security

Basic Usage:

// Check authorization
if (!(await client.isAuthorized("github"))) {
  await client.authorize("github"); // Opens popup or redirects
}

// Use authorized client
const repos = await client.github.listOwnRepos({});

For complete OAuth setup including:

• Popup vs redirect flows
• Session token management
• Multiple providers
• Callback page setup

See the /examples directory or OAuth documentation.

Scheduled Triggers

Schedule tool executions for specific times or recurring intervals. Perfect for sending scheduled emails, daily reports, automated reminders, and AI agents that need to schedule actions.

Key Features:

• ⏰ One-time triggers (specific date/time)
• 🔄 Recurring triggers (cron expressions)
• 📊 Execution tracking and history
• ⏸️ Pause/resume capabilities
• 🔧 Manual execution for testing

Quick Example:

// One-time trigger: Send email at specific time
const trigger = await client.trigger.create({
  name: "Follow-up Email",
  toolName: "gmail_send_email",
  toolArguments: {
    to: "[email protected]",
    subject: "About the dog",
    body: "Hey, just wanted to follow up...",
  },
  schedule: {
    type: "once",
    runAt: new Date("2024-12-13T22:00:00Z"),
  },
});

// Recurring trigger: Daily standup reminder
await client.trigger.create({
  name: "Daily Standup",
  toolName: "slack_send_message",
  toolArguments: {
    channel: "#engineering",
    text: "Time for standup! 🚀",
  },
  schedule: {
    type: "cron",
    expression: "0 9 * * 1-5", // 9 AM weekdays
  },
});

// Manage triggers
const { triggers } = await client.trigger.list({ status: "active" });
await client.trigger.pause("trig_abc123");
await client.trigger.resume("trig_abc123");
await client.trigger.run("trig_abc123"); // Execute immediately

Setup Requirements:

1. Configure database callbacks in createMCPServer() to store triggers
2. Triggers stored in your database, executed by MCP server scheduler
3. Full TypeScript support with type-safe methods

→ Complete Triggers documentation

Built-in Integrations

GitHub Integration

Access GitHub repositories, issues, pull requests, and more with type-safe methods.

// Available methods
await client.github.getRepo({ owner: "facebook", repo: "react" });
await client.github.createIssue({ owner: "user", repo: "repo", title: "Bug" });
await client.github.listPullRequests({
  owner: "user",
  repo: "repo",
  state: "open",
});
await client.github.listOwnRepos({});

→ GitHub integration documentation

Gmail Integration

Send emails, manage labels, and search messages with type-safe methods.

// Available methods
await client.gmail.sendEmail({
  to: "[email protected]",
  subject: "Hello",
  body: "Hi!",
});
await client.gmail.listEmails({ maxResults: 10, q: "is:unread" });
await client.gmail.searchEmails({ query: "from:[email protected]" });

→ Gmail integration documentation

Additional Integrations

Use genericOAuthIntegration to configure any server-supported integration:

import { genericOAuthIntegration } from "integrate-sdk/server";

// Automatically uses SLACK_CLIENT_ID and SLACK_CLIENT_SECRET from environment
const slackIntegration = genericOAuthIntegration({
  id: "slack",
  provider: "slack",
  scopes: ["chat:write", "channels:read"],
  tools: ["slack_send_message", "slack_list_channels"],
});

See /examples for complete setup patterns.

Vercel AI SDK Integration

Give AI models access to all your integrations with built-in Vercel AI SDK support.

import { getVercelAITools } from "integrate-sdk";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

// Convert MCP tools to Vercel AI SDK format
const tools = getVercelAITools(mcpClient);

// Use with AI models
const result = await generateText({
  model: openai("gpt-5"),
  prompt: "Create a GitHub issue about the login bug",
  tools,
  maxToolRoundtrips: 5,
});

→ View Vercel AI SDK integration guide

Documentation

For detailed guides, API reference, and examples, visit the complete documentation:

• Getting Started - Installation and quick start
• OAuth Flow - OAuth 2.0 authorization guide
• Integrations - Built-in integrations and configuration
• Vercel AI SDK - AI model integration
• Advanced Usage - Error handling, retries, and more
• API Reference - Complete API documentation
• Architecture - How the SDK works

TypeScript Support

The SDK is built with TypeScript and provides full type safety with IntelliSense support out of the box.

Contributing

Contributions are welcome! Please check the issues for ways to contribute.

Testing

# Run all tests
bun test

# Run with coverage
bun run test:coverage

See the tests/ directory for unit and integration test examples.

License

MIT © Revyo