integrate-SDK

集成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);

就是这样！ 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

设置要求：

1. 在中配置数据库回调 createMCPServer() 存储触发器
2. 存储在数据库中的触发器，由MCP服务器调度程序执行
3. 带有类型安全方法的完全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({});

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 开发工具包 -AI模型集成
• 高级用法 -错误处理、重试等
• API 参考 -完整的API文件
• 建筑 -SDK的工作原理

TypeScript支持

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

贡献

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

测试

# Run all tests
bun test

# Run with coverage
bun run test:coverage

看 tests/ 单元和集成测试示例目录。

许可证

MIT© NS2RW 如何