integrate-sdk 0.1.2 → 0.1.4

package/README.md

@@ -1,19 +1,51 @@
 # Integrate SDK
 
-A type-safe TypeScript SDK for building MCP (Model Context Protocol) clients with plugin-based OAuth provider configuration.
+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, plugin-based API.
+
+**Server:** `https://mcp.integrate.dev/api/v1/mcp`
+
+## Table of Contents
+
+- [What is this SDK?](#what-is-this-sdk)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Built-in Plugins](#built-in-plugins)
+  - [GitHub Plugin](#github-plugin)
+  - [Gmail Plugin](#gmail-plugin)
+- [Creating Custom Plugins](#creating-custom-plugins)
+- [Integration with Vercel AI SDK](#integration-with-vercel-ai-sdk)
+- [Advanced Usage](#advanced-usage)
+- [API Reference](#api-reference)
+- [Architecture](#architecture)
+- [How It Works](#how-it-works)
+
+## What is this SDK?
+
+This SDK is a **client library** that connects to the Integrate MCP server to access various third-party integrations.
+
+**Key concepts:**
+1. **Connect to the Integrate MCP server** - The SDK connects to `https://mcp.integrate.dev/api/v1/mcp`
+2. **Configure OAuth credentials** - You provide your own OAuth app credentials for each integration (GitHub, Gmail, etc.)
+3. **Call tools** - Execute actions like creating GitHub issues, sending emails, searching Notion pages
+4. **OAuth flow happens server-side** - The SDK sends your OAuth config to the server, which handles the actual authentication flow
+
+**Important:** You need to create your own OAuth apps (e.g., GitHub OAuth app, Google OAuth app) and provide the credentials to the SDK. The SDK does not provide OAuth credentials.
 
 ## Features
 
-- 🔌 **Plugin-Based Architecture** - Enable only the tools you need with a BetterAuth-inspired plugin pattern
-- 🔒 **Type-Safe Configuration** - Full TypeScript support with IntelliSense for tools and configurations
-- 🌊 **HTTP Streaming** - Real-time bidirectional communication via HTTP streaming with newline-delimited JSON (NDJSON)
-- 🔐 **OAuth Support** - Built-in OAuth configuration for multiple providers
-- 🛠️ **Extensible** - Easy to create custom plugins for any OAuth provider or tool set
-- 📦 **Zero Dependencies** - Lightweight with no external runtime dependencies
+- 🔌 **Plugin-Based Architecture** - Enable only the integrations you need
+- 🔒 **Type-Safe** - Full TypeScript support with IntelliSense
+- 🌊 **Real-time Communication** - HTTP streaming with NDJSON
+- 🔐 **OAuth Ready** - Configure OAuth credentials for each provider
+- 🛠️ **Extensible** - Create custom plugins for new integrations
+- 📦 **Zero Dependencies** - Lightweight implementation
 
 ## Installation
 
 ```bash
+npm install integrate-sdk
+# or
 bun add integrate-sdk
 ```
 
@@ -133,10 +165,10 @@ const slackPlugin = genericOAuthPlugin({
   clientSecret: process.env.SLACK_CLIENT_SECRET!,
   scopes: ['chat:write', 'channels:read', 'users:read'],
   tools: [
-    'slack/sendMessage',
-    'slack/listChannels',
-    'slack/getChannel',
-    'slack/inviteUser',
+    'slack_send_message',
+    'slack_list_channels',
+    'slack_get_channel',
+    'slack_invite_user',
   ],
   redirectUri: 'https://your-app.com/callback',
 });
@@ -155,7 +187,7 @@ import { createSimplePlugin } from 'integrate-sdk';
 
 const mathPlugin = createSimplePlugin({
   id: 'math',
-  tools: ['math/add', 'math/subtract', 'math/multiply', 'math/divide'],
+  tools: ['math_add', 'math_subtract', 'math_multiply', 'math_divide'],
   onInit: async (client) => {
     console.log('Math plugin initialized');
   },
@@ -170,7 +202,7 @@ import type { MCPPlugin } from 'integrate-sdk';
 export function customPlugin(config: CustomConfig): MCPPlugin {
   return {
     id: 'custom',
-    tools: ['custom/tool1', 'custom/tool2'],
+    tools: ['custom_tool1', 'custom_tool2'],
     oauth: {
       provider: 'custom-provider',
       clientId: config.clientId,
@@ -198,6 +230,57 @@ export function customPlugin(config: CustomConfig): MCPPlugin {
 }
 ```
 
+## Integration with Vercel AI SDK
+
+The SDK includes built-in support for Vercel's AI SDK, allowing you to give AI models access to all your integrations.
+
+### Quick Example
+
+```typescript
+import { createMCPClient, githubPlugin, getVercelAITools } from 'integrate-sdk';
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+// 1. Create and connect MCP client
+const mcpClient = createMCPClient({
+  plugins: [
+    githubPlugin({
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    }),
+  ],
+});
+
+await mcpClient.connect();
+
+// 2. Get tools in Vercel AI SDK format
+const tools = getVercelAITools(mcpClient);
+
+// 3. Use with AI models
+const result = await generateText({
+  model: openai('gpt-4'),
+  prompt: 'Create a GitHub issue titled "Bug in login" in myrepo',
+  tools,
+  maxToolRoundtrips: 5,
+});
+
+console.log(result.text);
+```
+
+### How It Works
+
+1. **`getVercelAITools(client)`** - Converts all enabled MCP tools to Vercel AI SDK format
+2. **Automatic execution** - When the AI calls a tool, it executes through your MCP client
+3. **Type-safe** - Full TypeScript support with proper types
+
+### Available Functions
+
+- **`getVercelAITools(client)`** - Get all enabled tools in Vercel AI SDK format
+- **`convertMCPToolsToVercelAI(client)`** - Same as above, alternative name
+- **`convertMCPToolToVercelAI(tool, client)`** - Convert a single MCP tool
+
+See `examples/vercel-ai-integration.ts` for a complete working example.
+
 ## Advanced Usage
 
 ### Accessing OAuth Configurations
@@ -345,29 +428,21 @@ The SDK uses HTTP streaming with newline-delimited JSON (NDJSON) for bidirection
 - Automatic heartbeat to keep connection alive
 - Compatible with MCP's `StreamableHTTPServer`
 
-## MCP Server Requirements
-
-Your MCP server should implement HTTP streaming transport compatible with MCP's `StreamableHTTPServer`:
+## How It Works
 
-- A single streaming endpoint (e.g., `POST /api/v1/mcp`) that:
-  - Accepts HTTP POST with streaming request body (NDJSON format)
-  - Returns streaming response body (NDJSON format)
-  - Supports bidirectional communication over a single persistent connection
-  - Messages are newline-delimited JSON (one JSON object per line)
+1. **Client Configuration**: You configure the SDK with plugins for the integrations you want to use (GitHub, Gmail, etc.)
+2. **Connection**: The SDK connects to `https://mcp.integrate.dev/api/v1/mcp` using HTTP streaming (NDJSON)
+3. **Tool Discovery**: The SDK fetches available tools from the server and filters them based on your enabled plugins
+4. **OAuth Configuration**: Your OAuth credentials are stored in the client configuration (not sent to the server yet)
+5. **Tool Calls**: When you call a tool, the SDK sends a JSON-RPC request to the server
+6. **OAuth Flow**: The server uses your OAuth configuration to authenticate and execute the tool
 
-And support these MCP protocol methods:
-- `initialize` - Initialize the protocol connection
-- `tools/list` - List available tools
-- `tools/call` - Invoke a tool
+## Server Information
 
-**Example Go server setup:**
-```go
-httpServer := server.NewStreamableHTTPServer(s,
-    server.WithEndpointPath("/api/v1/mcp"),
-    server.WithHeartbeatInterval(30*time.Second),
-    server.WithStateLess(false),
-)
-```
+**Endpoint:** `https://mcp.integrate.dev/api/v1/mcp`  
+**Protocol:** MCP (Model Context Protocol) over HTTP streaming  
+**Format:** Newline-delimited JSON (NDJSON)  
+**Methods:** `initialize`, `tools/list`, `tools/call`
 
 ## TypeScript Support
 
@@ -394,9 +469,9 @@ const result: MCPToolCallResponse = await client.callTool('github_create_issue',
 });
 ```
 
-# Test Suite
+## Contributing
 
-Comprehensive test suite for the Integrate SDK.
+Contributions are welcome! Please see the tests in the `tests/` directory for examples of how to test new features.
 
 ## Test Structure
 

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export { gmailPlugin } from "./plugins/gmail.js";
 export type { GmailPluginConfig, GmailTools } from "./plugins/gmail.js";
 export { genericOAuthPlugin, createSimplePlugin, } from "./plugins/generic.js";
 export type { GenericOAuthPluginConfig } from "./plugins/generic.js";
+export { convertMCPToolToVercelAI, convertMCPToolsToVercelAI, getVercelAITools, } from "./integrations/vercel-ai.js";
+export type { VercelAITool } from "./integrations/vercel-ai.js";
 export type { JSONRPCRequest, JSONRPCResponse, JSONRPCSuccessResponse, JSONRPCErrorResponse, JSONRPCNotification, MCPTool, MCPToolsListResponse, MCPToolCallParams, MCPToolCallResponse, MCPInitializeParams, MCPInitializeResponse, } from "./protocol/messages.js";
 export { MCPMethod } from "./protocol/messages.js";
 export { HttpSessionTransport } from "./transport/http-session.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGzD,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzD,YAAY,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAExE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAGrE,YAAY,EACV,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,OAAO,EACP,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,YAAY,EACV,cAAc,EACd,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGzD,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzD,YAAY,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAExE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAGrE,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE,YAAY,EACV,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,OAAO,EACP,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,YAAY,EACV,cAAc,EACd,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -431,12 +431,40 @@ function createSimplePlugin(config) {
     onDisconnect: config.onDisconnect
   };
 }
+// src/integrations/vercel-ai.ts
+function convertMCPSchemaToParameters(inputSchema) {
+  return inputSchema;
+}
+function convertMCPToolToVercelAI(mcpTool, client) {
+  return {
+    description: mcpTool.description || `Execute ${mcpTool.name}`,
+    parameters: convertMCPSchemaToParameters(mcpTool.inputSchema),
+    execute: async (args) => {
+      const result = await client.callTool(mcpTool.name, args);
+      return result;
+    }
+  };
+}
+function convertMCPToolsToVercelAI(client) {
+  const mcpTools = client.getEnabledTools();
+  const vercelTools = {};
+  for (const mcpTool of mcpTools) {
+    vercelTools[mcpTool.name] = convertMCPToolToVercelAI(mcpTool, client);
+  }
+  return vercelTools;
+}
+function getVercelAITools(client) {
+  return convertMCPToolsToVercelAI(client);
+}
 export {
   gmailPlugin,
   githubPlugin,
+  getVercelAITools,
   genericOAuthPlugin,
   createSimplePlugin,
   createMCPClient,
+  convertMCPToolsToVercelAI,
+  convertMCPToolToVercelAI,
   MCPMethod,
   MCPClient,
   HttpSessionTransport

package/dist/integrations/vercel-ai.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Vercel AI SDK Integration
+ *
+ * Helper functions to convert MCP tools to Vercel AI SDK format
+ */
+import type { MCPClient } from "../client.js";
+import type { MCPTool } from "../protocol/messages.js";
+/**
+ * Tool definition for Vercel AI SDK
+ */
+export interface VercelAITool {
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (args: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * Convert a single MCP tool to Vercel AI SDK format
+ *
+ * @param mcpTool - The MCP tool definition
+ * @param client - The MCP client instance (used for executing the tool)
+ * @returns Vercel AI SDK compatible tool definition
+ */
+export declare function convertMCPToolToVercelAI(mcpTool: MCPTool, client: MCPClient): VercelAITool;
+/**
+ * Convert all enabled MCP tools to Vercel AI SDK format
+ *
+ * @param client - The MCP client instance (must be connected)
+ * @returns Object mapping tool names to Vercel AI SDK tool definitions
+ *
+ * @example
+ * ```typescript
+ * import { createMCPClient, githubPlugin } from 'integrate-sdk';
+ * import { convertMCPToolsToVercelAI } from 'integrate-sdk/vercel-ai';
+ * import { generateText } from 'ai';
+ *
+ * const mcpClient = createMCPClient({
+ *   plugins: [githubPlugin({ clientId: '...', clientSecret: '...' })],
+ * });
+ *
+ * await mcpClient.connect();
+ *
+ * const tools = convertMCPToolsToVercelAI(mcpClient);
+ *
+ * const result = await generateText({
+ *   model: openai('gpt-4'),
+ *   prompt: 'Create a GitHub issue in my repo',
+ *   tools,
+ * });
+ * ```
+ */
+export declare function convertMCPToolsToVercelAI(client: MCPClient): Record<string, VercelAITool>;
+/**
+ * Get tools in a format compatible with Vercel AI SDK's tools parameter
+ *
+ * This is an alternative that returns the tools in the exact format expected by ai.generateText()
+ *
+ * @param client - The MCP client instance (must be connected)
+ * @returns Tools object ready to pass to generateText({ tools: ... })
+ */
+export declare function getVercelAITools(client: MCPClient): Record<string, VercelAITool>;
+//# sourceMappingURL=vercel-ai.d.ts.map

package/dist/integrations/vercel-ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-ai.d.ts","sourceRoot":"","sources":["../../src/integrations/vercel-ai.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D;AAcD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,SAAS,GAChB,YAAY,CASd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,SAAS,GAChB,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAS9B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,gCAEjD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "integrate-sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Type-safe TypeScript SDK for MCP Client with plugin-based OAuth provider configuration",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,11 +28,11 @@
     "build:types": "tsc --emitDeclarationOnly --declaration --declarationMap",
     "dev": "bun --watch src/index.ts",
     "type-check": "tsc --noEmit",
-    "test": "bun test tests/protocol tests/plugins tests/client tests/integration/simple-integration.test.ts",
-    "test:watch": "bun test --watch tests/protocol tests/plugins tests/client tests/integration/simple-integration.test.ts",
-    "test:unit": "bun test tests/protocol tests/plugins tests/client",
+    "test": "bun test tests/protocol tests/plugins tests/client tests/integrations tests/integration/simple-integration.test.ts",
+    "test:watch": "bun test --watch tests/protocol tests/plugins tests/client tests/integrations tests/integration/simple-integration.test.ts",
+    "test:unit": "bun test tests/protocol tests/plugins tests/client tests/integrations",
     "test:integration": "bun test tests/integration/simple-integration.test.ts",
-    "test:coverage": "bun test --coverage tests/protocol tests/plugins tests/client tests/integration/simple-integration.test.ts"
+    "test:coverage": "bun test --coverage tests/protocol tests/plugins tests/client tests/integrations tests/integration/simple-integration.test.ts"
   },
   "keywords": [
     "mcp",