项目介绍
集成SDK
一个类型安全的TypeScript SDK，用于连接到Integrate MCP（模型上下文协议）服务器。通过简单的集成式API访问GitHub、Gmail、Notion和其他集成。
📚 完整文档 | 服务器: https://mcp.integrate.dev/api/v1/mcp
特性
- 🔌 基于集成的架构 - 启用你需要的集成
- 🔒 完全类型化的API - 类型安全的方法支持自动补全（例如，
client.github.createIssue()） - 💡 IntelliSense支持 - 完整的TypeScript支持，带有参数提示
- ⚡ 自动连接管理 - 惰性连接，自动清理，单例模式
- 🔐 完整的OAuth流程 - 内置OAuth 2.0与PKCE（弹出窗口/重定向模式）
- 🌍 通用性 - 在浏览器和Node.js环境中工作
- 🛠️ 可扩展性 - 配置任何服务器支持的集成
- 📦 零依赖 - 轻量级实现
安装
npm install integrate-sdk
# 或
bun add integrate-sdk
快速开始（仅需两个文件！）
0. 配置OAuth重定向URI
⚠️ 重要：使用此重定向URI配置你的OAuth应用：
http://localhost:3000/api/integrate/oauth/callback
- GitHub：设置 → 开发者设置 → OAuth应用 → 授权回调URL
- Google/Gmail：Google Cloud控制台 → 凭据 → 授权的重定向URI
生产环境使用：https://yourdomain.com/api/integrate/oauth/callback
1. 创建服务器配置
定义一次OAuth提供商。集成会自动从环境变量中读取凭证：
// lib/integrate-server.ts（仅限服务器端！）
import {
createMCPServer,
githubIntegration,
gmailIntegration,
} from "integrate-sdk/server";
// 集成会自动使用GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET,
// GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET从环境变量
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, // 传递客户端
redirectUrl: "/dashboard",
});
这会从步骤1导入你的配置，并处理所有的OAuth操作（授权、回调、状态、断开连接）在一个文件中！
3. 在你的应用中使用
在API路由或服务器组件中使用服务器客户端：
// app/api/repos/route.ts
import { serverClient } from "@/lib/integrate-server";
export async function GET() {
// 在第一次调用时自动连接 - 不需要手动设置！
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"],
// 不需要clientId或clientSecret！
}),
],
oauthFlow: { mode: "popup" },
});
// 授权用户（打开弹出窗口）
await client.authorize("github");
// 使用客户端 - 自动连接！
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()调用！
特性：
- 惰性连接：在第一次方法调用时自动连接
- 自动清理：在进程退出时清理
- 单例模式：高效复用连接（可配置）
// ✅ 默认行为 - 自动连接
// 集成会自动使用GITHUB_CLIENT_ID和GITHUB_CLIENT_SECRET从环境变量
const client = createMCPClient({
integrations: [
githubIntegration({
scopes: ["repo", "user"],
}),
],
});
// 立即使用 - 不需要connect()！
await client.authorize("github");
await client.github.listRepos({ username: "octocat" });
// ✅ 想要手动控制？使用手动模式
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在两种环境中都能工作：
- 浏览器：从
'integrate-sdk'使用createMCPClient()- 处理OAuth UI（弹出窗口/重定向） - 服务器：从
'integrate-sdk/server'使用createMCPServer()- 包含API路由的OAuth密钥
查看上面的快速开始以获取完整示例。
为什么使用Integrate SDK？
类型化集成方法
使用完整的自动补全的类型化方法，而不是通用工具调用：
// ✅ 新：带有自动补全的类型化方法
await client.github.createIssue({
owner: "user",
repo: "project",
title: "Bug",
});
await client.gmail.sendEmail({ to: "user@example.com", subject: "Hello" });
优点
- 类型安全：参数在编译时被验证
- 自动补全：IDE会建议可用的方法和参数
- 文档：每个方法都有内联JSDoc注释
- 重构：在整个代码库中安全地重命名方法
调用工具的三种方式
// 1. 类型化集成方法（推荐用于内置集成如GitHub/Gmail）
await client.github.createIssue({
owner: "user",
repo: "project",
title: "Bug",
});
await client.gmail.sendEmail({ to: "user@example.com", subject: "Hello" });
// 2. 类型化服务器方法（用于服务器级别的工具）
await client.server.listToolsByIntegration({ integration: "github" });
// 3. 直接调用工具（用于其他服务器支持的集成）
await client._callToolByName("slack_send_message", {
channel: "#general",
text: "Hello",
});
OAuth授权
SDK实现了OAuth 2.0授权码流与PKCE进行安全授权。
关键特性：
- ✅ 弹出窗口或重定向流模式
- ✅ 会话令牌管理
- ✅ 多个提供商支持
- ✅ PKCE安全性
基本用法：
// 检查授权
if (!(await client.isAuthorized("github"))) {
await client.authorize("github"); // 打开弹出窗口或重定向
}
// 使用已授权的客户端
const repos = await client.github.listOwnRepos({});
对于完整的OAuth设置包括：
- 弹出窗口与重定向流
- 会话令牌管理
- 多个提供商
- 回调页面设置
内置集成
GitHub集成
使用类型安全的方法访问GitHub仓库、问题、拉取请求等。
// 可用方法
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集成
使用类型安全的方法发送邮件、管理标签和搜索消息。
// 可用方法
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" });
其他集成
使用genericOAuthIntegration配置任何服务器支持的集成：
import { genericOAuthIntegration } from "integrate-sdk/server";
// 自动使用SLACK_CLIENT_ID和SLACK_CLIENT_SECRET从环境变量
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";
// 将MCP工具转换为Vercel AI SDK格式
const tools = getVercelAITools(mcpClient);
// 与AI模型一起使用
const result = await generateText({
model: openai("gpt-5"),
prompt: "创建一个关于登录bug的GitHub问题",
tools,
maxToolRoundtrips: 5,
});
文档
对于详细的指南、API参考和示例，请访问完整文档：
- 入门 - 安装和快速开始
- OAuth流程 - OAuth 2.0授权指南
- 集成 - 内置集成和配置
- Vercel AI SDK - AI模型集成
- 高级用法 - 错误处理、重试等
- API参考 - 完整API文档
- 架构 - SDK的工作原理
TypeScript支持
SDK是用TypeScript构建的，并提供了完整的类型安全和IntelliSense支持。
贡献
欢迎贡献！请查看问题了解如何贡献。
测试
# 运行所有测试
bun test
# 带覆盖率运行
bun run test:coverage
查看tests/目录以获取单元和集成测试示例。
许可证
MIT © Revyo