使用说明

集成SDK

一个类型安全的TypeScript SDK，用于连接到集成MCP（模型上下文协议）服务器。通过简单的基于集成的API访问GitHub、Gmail、Notion和其他集成。

📚 全部文件 | 服务器： https://mcp.integrate.dev/api/v1/mcp

特征

🔌 基于集成的体系结构 -仅启用所需的集成
🔒 全类型API -具有自动补全功能的类型安全方法（例如。， client.github.createIssue())
💡 智能感知支持 -带有参数提示的完全TypeScript支持
⚡ 自动连接管理 -延迟连接、自动清理、单例模式
🔐 完整的OAuth流程 -内置OAuth 2.0和PKCE（弹出/重定向模式）
⏰ 计划触发器 -使用一次性或重复触发来安排工具执行
🌍 通用的 -适用于浏览器和Node.js环境
🛠️ 可扩展 -为任何服务器支持的集成配置集成
📦 零依赖 -轻量级实现

安装

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

快速入门（仅限2个文件！）

0.配置OAuth重定向类型

⚠️ 重要：使用此重定向URI配置OAuth应用程序：

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

GitHub：设置→ 开发者设置→ OAuth应用程序→ 授权回调URL
谷歌/Gmail：谷歌云控制台→ 凭证→ 授权重定向URI

生产时，使用： https://yourdomain.com/api/integrate/oauth/callback

1.创建服务器配置

定义一次OAuth提供者。集成会自动从环境变量中读取凭据：

// 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.创建单一的包罗万象的路线

就是这样！只需导入和导出：

// 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",
});

这将从步骤1导入您的配置，并在一个文件中处理所有OAuth操作（授权、回调、状态、断开连接）！

3.在您的应用程序中使用

在API路由或服务器组件中使用服务器客户端：

// 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 });
}

客户端设置

在客户端组件中使用（无需保密）：

"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);

API关键集成

使用像Granola这样的API-key集成，将凭据直接传递给集成助手：

import { createMCPClient, granolaIntegration } from "integrate-sdk";

const client = createMCPClient({
  integrations: [
    granolaIntegration({
      apiKey: process.env.GRANOLA_API_KEY!,
    }),
  ],
});

const notes = await client.callTool("granola_list_notes", {
  page_size: 10,
});

const note = await client.callTool("granola_get_note", {
  note_id: "not_123",
  include_transcript: true,
});

const folders = await client.callTool("granola_list_folders", {
  page_size: 10,
});

Mercury使用相同的API模式：

import { createMCPClient, mercuryIntegration } from "integrate-sdk";

const client = createMCPClient({
  integrations: [
    mercuryIntegration({
      apiKey: process.env.MERCURY_API_KEY!,
    }),
  ],
});

const org = await client.callTool("mercury_get_organization");
const accounts = await client.callTool("mercury_list_accounts", {
  limit: 50,
});
const txns = await client.callTool("mercury_list_transactions", {
  start: "2026-01-01",
  end: "2026-01-31",
  limit: 100,
});

OAuth文件存储集成

Dropbox遵循标准的OAuth集成流程：

import { createMCPClient, dropboxIntegration } from "integrate-sdk";

const client = createMCPClient({
  integrations: [
    dropboxIntegration({
      scopes: [
        "account_info.read",
        "files.metadata.read",
        "files.content.read",
        "files.content.write",
        "sharing.read",
        "sharing.write",
      ],
    }),
  ],
});

const account = await client.callTool("dropbox_get_current_account");
const files = await client.callTool("dropbox_list_folder", {
  path: "/",
  limit: 50,
});

就是这样！ SDK会自动执行以下操作：

✅ 在第一次方法调用时连接（无需手动 connect() 需要）
✅ 出口清理（无需手动 disconnect() 需要）
✅ 通过API路由安全地管理OAuth令牌
✅ 通过自动补全功能提供全类型安全

连接管理

SDK会自动为您管理连接-无需手动 connect() 或 disconnect() 需要电话！

特征：

延迟连接：在第一次方法调用时自动连接
自动清理：进程退出时进行清理
单例模式：高效重用连接（可配置）

// ✅ 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();

需要帮助？ 看看完整文档获取详细指南、示例和API参考资料。

浏览器和服务器支持

SDK可在两种环境中工作：

浏览器：使用 createMCPClient() 从 'integrate-sdk' -处理OAuth UI（弹出/重定向）
服务器：使用 createMCPServer() 从 'integrate-sdk/server' -包括API路由的OAuth机密

看快速开始以上为完整示例。

为什么要使用集成SDK？

类型化集成方法

使用具有完全自动补全功能的类型化方法，而不是通用工具调用：

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

好处

类型安全：参数在编译时进行验证
自动完成：IDE建议可用的方法和参数
文档：每个方法的内联JSDoc注释
重构：在代码库中安全地重命名方法

调用工具的三种方法

// 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: "user@example.com", 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授权

SDK使用PKCE实现了OAuth 2.0授权代码流，以实现安全授权。

主要特点：

✅ 弹出或重定向流模式
✅ 会话令牌管理
✅ 多提供商支持
✅ PKCE安全

基本用法：

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

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

完整的OAuth设置，包括：

弹出流与重定向流
会话令牌管理
多个供应商
回调页面设置

请参阅 /examples 目录或 OAuth文档.

计划触发器

为特定时间或重复间隔安排工具执行。非常适合发送预定的电子邮件、每日报告、自动提醒和需要安排操作的AI代理。

主要特点：

⏰ 一次性触发器（特定日期/时间）
🔄 重复触发器（cron表达式）
📊 执行跟踪和历史记录
⏸️ 暂停/恢复功能
🔧 手动执行测试

快速示例：

// One-time trigger: Send email at specific time
const trigger = await client.trigger.create({
  name: "Follow-up Email",
  toolName: "gmail_send_email",
  toolArguments: {
    to: "friend@example.com",
    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

设置要求：

在中配置数据库回调 createMCPServer() 存储触发器
存储在数据库中的触发器，由MCP服务器调度程序执行
带有类型安全方法的完全TypeScript支持

→ 完整的触发器文档

内置集成

GitHub集成

使用类型安全方法访问GitHub存储库、问题、拉取请求等。

// 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集成文档

Gmail集成

使用类型安全的方法发送电子邮件、管理标签和搜索邮件。

// Available methods
await client.gmail.sendEmail({
  to: "user@example.com",
  subject: "Hello",
  body: "Hi!",
});
await client.gmail.listEmails({ maxResults: 10, q: "is:unread" });
await client.gmail.searchEmails({ query: "from:notifications@github.com" });

→ Gmail集成文档

其他集成

使用 genericOAuthIntegration 要配置任何服务器支持的集成，请执行以下操作：

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"],
});

看 /examples 以获取完整的设置模式。

Vercel AI SDK集成

通过内置的Vercel AI SDK支持，让AI模型访问您的所有集成。

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,
});

→ 查看Vercel AI SDK集成指南

文档

有关详细指南、API参考资料和示例，请访问完整文档:

入门指南 -安装和快速启动
OAuth流 -OAuth 2.0授权指南
集成 -内置集成和配置
Vercel AI SDK -AI模型集成
高级用法 -错误处理、重试等
API 参考 -完整的API文件
建筑 -SDK的工作原理

TypeScript支持

SDK是用TypeScript构建的，并通过开箱即用的IntelliSense支持提供了完全的类型安全。

贡献

欢迎投稿！请检查问题关于如何做出贡献。

测试

# Run all tests
bun test

# Run with coverage
bun run test:coverage

请参阅 tests/ 单元和集成测试示例目录。