integrate-sdk 0.2.4 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/README.md +148 -242
  2. package/dist/index.d.ts +17 -24
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +260 -24
  5. package/dist/oauth.d.ts +19 -0
  6. package/dist/oauth.d.ts.map +1 -0
  7. package/dist/oauth.js +194 -0
  8. package/dist/server.d.ts +11 -0
  9. package/dist/server.d.ts.map +1 -0
  10. package/dist/server.js +1481 -0
  11. package/dist/src/adapters/auto-routes.d.ts +51 -0
  12. package/dist/src/adapters/auto-routes.d.ts.map +1 -0
  13. package/dist/src/adapters/base-handler.d.ts +106 -0
  14. package/dist/src/adapters/base-handler.d.ts.map +1 -0
  15. package/dist/src/adapters/nextjs.d.ts +223 -0
  16. package/dist/src/adapters/nextjs.d.ts.map +1 -0
  17. package/dist/src/adapters/tanstack-start.d.ts +169 -0
  18. package/dist/src/adapters/tanstack-start.d.ts.map +1 -0
  19. package/dist/src/client.d.ts.map +1 -0
  20. package/dist/{config → src/config}/types.d.ts +20 -0
  21. package/dist/src/config/types.d.ts.map +1 -0
  22. package/dist/src/errors.d.ts.map +1 -0
  23. package/dist/src/index.d.ts +31 -0
  24. package/dist/src/index.d.ts.map +1 -0
  25. package/dist/src/integrations/vercel-ai.d.ts.map +1 -0
  26. package/dist/{oauth → src/oauth}/manager.d.ts +6 -4
  27. package/dist/src/oauth/manager.d.ts.map +1 -0
  28. package/dist/src/oauth/pkce.d.ts.map +1 -0
  29. package/dist/src/oauth/types.d.ts.map +1 -0
  30. package/dist/src/oauth/window-manager.d.ts.map +1 -0
  31. package/dist/src/plugins/generic.d.ts.map +1 -0
  32. package/dist/src/plugins/github-client.d.ts.map +1 -0
  33. package/dist/{plugins → src/plugins}/github.d.ts +24 -7
  34. package/dist/src/plugins/github.d.ts.map +1 -0
  35. package/dist/src/plugins/gmail-client.d.ts.map +1 -0
  36. package/dist/{plugins → src/plugins}/gmail.d.ts +25 -7
  37. package/dist/src/plugins/gmail.d.ts.map +1 -0
  38. package/dist/src/plugins/server-client.d.ts.map +1 -0
  39. package/dist/{plugins → src/plugins}/types.d.ts +16 -4
  40. package/dist/src/plugins/types.d.ts.map +1 -0
  41. package/dist/src/protocol/jsonrpc.d.ts.map +1 -0
  42. package/dist/src/protocol/messages.d.ts.map +1 -0
  43. package/dist/src/server.d.ts +54 -0
  44. package/dist/src/server.d.ts.map +1 -0
  45. package/dist/src/transport/http-session.d.ts.map +1 -0
  46. package/dist/src/transport/http-stream.d.ts.map +1 -0
  47. package/dist/src/utils/naming.d.ts.map +1 -0
  48. package/index.ts +21 -0
  49. package/oauth.ts +20 -0
  50. package/package.json +14 -3
  51. package/server.ts +12 -0
  52. package/dist/client.d.ts.map +0 -1
  53. package/dist/config/types.d.ts.map +0 -1
  54. package/dist/errors.d.ts.map +0 -1
  55. package/dist/integrations/vercel-ai.d.ts.map +0 -1
  56. package/dist/oauth/manager.d.ts.map +0 -1
  57. package/dist/oauth/pkce.d.ts.map +0 -1
  58. package/dist/oauth/types.d.ts.map +0 -1
  59. package/dist/oauth/window-manager.d.ts.map +0 -1
  60. package/dist/plugins/generic.d.ts.map +0 -1
  61. package/dist/plugins/github-client.d.ts.map +0 -1
  62. package/dist/plugins/github.d.ts.map +0 -1
  63. package/dist/plugins/gmail-client.d.ts.map +0 -1
  64. package/dist/plugins/gmail.d.ts.map +0 -1
  65. package/dist/plugins/server-client.d.ts.map +0 -1
  66. package/dist/plugins/types.d.ts.map +0 -1
  67. package/dist/protocol/jsonrpc.d.ts.map +0 -1
  68. package/dist/protocol/messages.d.ts.map +0 -1
  69. package/dist/transport/http-session.d.ts.map +0 -1
  70. package/dist/transport/http-stream.d.ts.map +0 -1
  71. package/dist/utils/naming.d.ts.map +0 -1
  72. /package/dist/{client.d.ts → src/client.d.ts} +0 -0
  73. /package/dist/{errors.d.ts → src/errors.d.ts} +0 -0
  74. /package/dist/{integrations → src/integrations}/vercel-ai.d.ts +0 -0
  75. /package/dist/{oauth → src/oauth}/pkce.d.ts +0 -0
  76. /package/dist/{oauth → src/oauth}/types.d.ts +0 -0
  77. /package/dist/{oauth → src/oauth}/window-manager.d.ts +0 -0
  78. /package/dist/{plugins → src/plugins}/generic.d.ts +0 -0
  79. /package/dist/{plugins → src/plugins}/github-client.d.ts +0 -0
  80. /package/dist/{plugins → src/plugins}/gmail-client.d.ts +0 -0
  81. /package/dist/{plugins → src/plugins}/server-client.d.ts +0 -0
  82. /package/dist/{protocol → src/protocol}/jsonrpc.d.ts +0 -0
  83. /package/dist/{protocol → src/protocol}/messages.d.ts +0 -0
  84. /package/dist/{transport → src/transport}/http-session.d.ts +0 -0
  85. /package/dist/{transport → src/transport}/http-stream.d.ts +0 -0
  86. /package/dist/{utils → src/utils}/naming.d.ts +0 -0
package/README.md CHANGED
@@ -12,8 +12,9 @@ A type-safe TypeScript SDK for connecting to the Integrate MCP (Model Context Pr
12
12
  - 🔌 **Plugin-Based Architecture** - Enable only the integrations you need
13
13
  - 🔒 **Fully Typed API** - Type-safe methods with autocomplete (e.g., `client.github.createIssue()`)
14
14
  - 💡 **IntelliSense Support** - Full TypeScript support with parameter hints
15
- - 🌊 **Real-time Communication** - HTTP streaming with NDJSON
16
- - 🔐 **OAuth Ready** - Configure OAuth credentials for each provider
15
+ - **Automatic Connection Management** - Lazy connection, auto-cleanup, singleton pattern
16
+ - 🔐 **Complete OAuth Flow** - Built-in OAuth 2.0 with PKCE (popup/redirect modes)
17
+ - 🌍 **Universal** - Works in browser and Node.js environments
17
18
  - 🛠️ **Extensible** - Configure plugins for any server-supported integration
18
19
  - 📦 **Zero Dependencies** - Lightweight implementation
19
20
 
@@ -27,340 +28,244 @@ bun add integrate-sdk
27
28
 
28
29
  ## Quick Start
29
30
 
31
+ ### Server-Side Setup
32
+
33
+ First, create your server configuration with OAuth secrets:
34
+
30
35
  ```typescript
31
- import { createMCPClient, githubPlugin } from "integrate-sdk";
36
+ // lib/integrate-server.ts (server-side only!)
37
+ import { createMCPServer, githubPlugin, gmailPlugin } from 'integrate-sdk/server';
32
38
 
33
- // Create a client with plugins
34
- const client = createMCPClient({
39
+ export const { client: serverClient, handlers } = createMCPServer({
35
40
  plugins: [
36
41
  githubPlugin({
37
- clientId: process.env.GITHUB_CLIENT_ID!,
38
- clientSecret: process.env.GITHUB_CLIENT_SECRET!,
39
- scopes: ["repo", "user"],
42
+ clientId: process.env.GITHUB_CLIENT_ID,
43
+ clientSecret: process.env.GITHUB_CLIENT_SECRET,
44
+ scopes: ['repo', 'user'],
45
+ }),
46
+ gmailPlugin({
47
+ clientId: process.env.GMAIL_CLIENT_ID,
48
+ clientSecret: process.env.GMAIL_CLIENT_SECRET,
49
+ scopes: ['gmail.readonly'],
40
50
  }),
41
51
  ],
42
52
  });
43
-
44
- // Connect to the server
45
- await client.connect();
46
-
47
- // Call GitHub methods with full type safety
48
- const result = await client.github.createIssue({
49
- owner: "owner",
50
- repo: "repo",
51
- title: "Bug report",
52
- body: "Description of the bug",
53
- });
54
-
55
- console.log("Issue created:", result);
56
-
57
- // Call server-level tools with typed methods
58
- const tools = await client.server.listToolsByIntegration({
59
- integration: "github",
60
- });
61
-
62
- // Disconnect when done
63
- await client.disconnect();
64
53
  ```
65
54
 
66
- **Need help?** Check out the [complete documentation](https://integrate.dev) for detailed guides, examples, and API reference.
67
-
68
- ## Why Use Integrate SDK?
69
-
70
- ### Typed Plugin Methods
71
-
72
- Instead of generic tool calls, use typed methods with full autocomplete:
55
+ Create OAuth route (handles authorization automatically):
73
56
 
74
57
  ```typescript
75
- // ✅ New: Typed methods with autocomplete
76
- await client.github.createIssue({ owner: "user", repo: "project", title: "Bug" });
77
- await client.gmail.sendEmail({ to: "user@example.com", subject: "Hello" });
58
+ // app/api/integrate/oauth/[action]/route.ts
59
+ export * from 'integrate-sdk/oauth';
78
60
  ```
79
61
 
80
- ### Benefits
81
-
82
- - **Type Safety**: Parameters are validated at compile time
83
- - **Autocomplete**: Your IDE suggests available methods and parameters
84
- - **Documentation**: Inline JSDoc comments for every method
85
- - **Refactoring**: Rename methods safely across your codebase
86
-
87
- ### Three Ways to Call Tools
62
+ Use the server client in API routes or server components:
88
63
 
89
64
  ```typescript
90
- // 1. Typed plugin methods (recommended for built-in plugins like GitHub/Gmail)
91
- await client.github.createIssue({ owner: "user", repo: "project", title: "Bug" });
92
- await client.gmail.sendEmail({ to: "user@example.com", subject: "Hello" });
93
-
94
- // 2. Typed server methods (for server-level tools)
95
- await client.server.listToolsByIntegration({ integration: "github" });
65
+ // app/api/repos/route.ts
66
+ import { serverClient } from '@/lib/integrate-server';
96
67
 
97
- // 3. Direct tool calls (for other server-supported integrations)
98
- await client._callToolByName("slack_send_message", { channel: "#general", text: "Hello" });
68
+ export async function GET() {
69
+ // Automatically connects on first call - no manual setup needed!
70
+ const repos = await serverClient.github.listOwnRepos({ per_page: 10 });
71
+ return Response.json({ repos });
72
+ }
99
73
  ```
100
74
 
101
- ## OAuth Authorization
102
-
103
- The SDK implements OAuth 2.0 Authorization Code Flow with PKCE for secure third-party service authorization. Users must authorize your application to access their GitHub, Gmail, or other accounts.
104
-
105
- ### How It Works
75
+ ### Client-Side Setup
106
76
 
107
- 1. **Your App**: Creates client with OAuth configuration
108
- 2. **SDK**: Initiates OAuth flow (popup or redirect)
109
- 3. **User**: Authorizes permissions on provider's website
110
- 4. **Provider**: Redirects back with authorization code
111
- 5. **Your Server**: Exchanges code for tokens and stores them
112
- 6. **SDK**: Includes session token in all API requests
113
- 7. **Your Server**: Uses stored OAuth tokens for API calls
114
-
115
- ### Quick Start
77
+ Use in your client components (no secrets needed):
116
78
 
117
79
  ```typescript
118
- import { createMCPClient, githubPlugin } from "integrate-sdk";
80
+ 'use client';
81
+ import { createMCPClient, githubPlugin } from 'integrate-sdk';
119
82
 
120
- // Create client with OAuth flow configuration
121
83
  const client = createMCPClient({
122
84
  plugins: [
123
85
  githubPlugin({
124
- clientId: process.env.GITHUB_CLIENT_ID!,
125
- clientSecret: process.env.GITHUB_CLIENT_SECRET!,
126
- scopes: ["repo", "user"],
127
- redirectUri: "http://localhost:3000/oauth/callback",
86
+ scopes: ['repo', 'user'],
87
+ // No clientId or clientSecret needed!
128
88
  }),
129
89
  ],
130
- oauthFlow: {
131
- mode: 'popup', // or 'redirect'
132
- popupOptions: { width: 600, height: 700 },
133
- },
90
+ oauthFlow: { mode: 'popup' },
134
91
  });
135
92
 
136
- // Check if authorized
137
- const isAuthorized = await client.isAuthorized('github');
93
+ // Authorize user (opens popup)
94
+ await client.authorize('github');
138
95
 
139
- if (!isAuthorized) {
140
- // Initiate OAuth flow - opens popup or redirects
141
- await client.authorize('github');
142
- }
96
+ // Use the client - automatically connects!
97
+ const result = await client.github.createIssue({
98
+ owner: 'owner',
99
+ repo: 'repo',
100
+ title: 'Bug report',
101
+ body: 'Description of the bug',
102
+ });
143
103
 
144
- // Now you can use GitHub tools
145
- const repos = await client.github.listOwnRepos({});
104
+ console.log('Issue created:', result);
146
105
  ```
147
106
 
148
- ### Popup Flow (Recommended for SPAs)
107
+ **That's it!** The SDK automatically:
108
+ - ✅ Connects on first method call (no manual `connect()` needed)
109
+ - ✅ Cleans up on exit (no manual `disconnect()` needed)
110
+ - ✅ Manages OAuth tokens securely through your API routes
111
+ - ✅ Provides full type safety with autocomplete
112
+
113
+ ### Connection Management
149
114
 
150
- Best for single-page applications - authorization happens in a popup without leaving your app.
115
+ The SDK automatically manages connections for you - no manual `connect()` or `disconnect()` calls needed!
116
+
117
+ **Features:**
118
+ - **Lazy Connection**: Automatically connects on first method call
119
+ - **Auto-Cleanup**: Cleans up on process exit
120
+ - **Singleton Pattern**: Reuses connections efficiently (configurable)
151
121
 
152
122
  ```typescript
123
+ // ✅ Default behavior - automatic connection
153
124
  const client = createMCPClient({
154
- plugins: [githubPlugin({ ... })],
155
- oauthFlow: { mode: 'popup' },
125
+ plugins: [
126
+ githubPlugin({
127
+ scopes: ['repo', 'user'],
128
+ }),
129
+ ],
156
130
  });
157
131
 
158
- // This opens a popup for authorization
132
+ // Use immediately - no connect() needed!
159
133
  await client.authorize('github');
134
+ await client.github.listRepos({ username: 'octocat' });
160
135
 
161
- // After user approves, continues automatically
162
- const repos = await client.github.listOwnRepos({});
163
- ```
136
+ // Want manual control? Use manual mode
137
+ const manualClient = createMCPClient({
138
+ plugins: [githubPlugin({ scopes: ['repo'] })],
139
+ connectionMode: 'manual',
140
+ singleton: false,
141
+ });
164
142
 
165
- **Callback Page**: Create `/oauth/callback.html`:
166
-
167
- ```html
168
- <!DOCTYPE html>
169
- <html>
170
- <head>
171
- <title>OAuth Callback</title>
172
- <script type="module">
173
- import { sendCallbackToOpener } from 'integrate-sdk';
174
-
175
- const params = new URLSearchParams(window.location.search);
176
- sendCallbackToOpener({
177
- code: params.get('code'),
178
- state: params.get('state'),
179
- error: params.get('error')
180
- });
181
- </script>
182
- </head>
183
- <body>
184
- <p>Authorization successful! Closing...</p>
185
- </body>
186
- </html>
143
+ await manualClient.connect();
144
+ await manualClient.authorize('github');
145
+ await manualClient.github.listRepos({ username: 'octocat' });
146
+ await manualClient.disconnect();
187
147
  ```
188
148
 
189
- ### Redirect Flow (Traditional Web Apps)
149
+ **Need help?** Check out the [complete documentation](https://integrate.dev) for detailed guides, examples, and API reference.
190
150
 
191
- Best for traditional server-rendered applications.
151
+ ## Browser & Server Support
192
152
 
193
- ```typescript
194
- // Main page
195
- const client = createMCPClient({
196
- plugins: [githubPlugin({ ... })],
197
- oauthFlow: { mode: 'redirect' },
198
- });
153
+ The SDK works in both environments:
199
154
 
200
- if (!await client.isAuthorized('github')) {
201
- await client.authorize('github'); // Redirects to GitHub
202
- }
155
+ - **Browser**: Use `createMCPClient()` from `'integrate-sdk'` - handles OAuth UI (popup/redirect)
156
+ - **Server**: Use `createMCPServer()` from `'integrate-sdk/server'` - includes OAuth secrets for API routes
203
157
 
204
- // Callback page (e.g., /oauth/callback)
205
- const params = new URLSearchParams(window.location.search);
206
- await client.handleOAuthCallback({
207
- code: params.get('code')!,
208
- state: params.get('state')!
209
- });
158
+ See [Quick Start](#quick-start) above for complete examples.
210
159
 
211
- // Save session token for future use
212
- const sessionToken = client.getSessionToken();
213
- localStorage.setItem('session_token', sessionToken);
160
+ ## Why Use Integrate SDK?
161
+
162
+ ### Typed Plugin Methods
214
163
 
215
- // Redirect back to main app
164
+ Instead of generic tool calls, use typed methods with full autocomplete:
165
+
166
+ ```typescript
167
+ // ✅ New: Typed methods with autocomplete
168
+ await client.github.createIssue({ owner: "user", repo: "project", title: "Bug" });
169
+ await client.gmail.sendEmail({ to: "user@example.com", subject: "Hello" });
216
170
  ```
217
171
 
218
- ### Session Token Management
172
+ ### Benefits
219
173
 
220
- Store and restore sessions to avoid re-authorization:
174
+ - **Type Safety**: Parameters are validated at compile time
175
+ - **Autocomplete**: Your IDE suggests available methods and parameters
176
+ - **Documentation**: Inline JSDoc comments for every method
177
+ - **Refactoring**: Rename methods safely across your codebase
178
+
179
+ ### Three Ways to Call Tools
221
180
 
222
181
  ```typescript
223
- // Restore previous session
224
- const client = createMCPClient({
225
- plugins: [githubPlugin({ ... })],
226
- sessionToken: localStorage.getItem('session_token'),
227
- });
182
+ // 1. Typed plugin methods (recommended for built-in plugins like GitHub/Gmail)
183
+ await client.github.createIssue({ owner: "user", repo: "project", title: "Bug" });
184
+ await client.gmail.sendEmail({ to: "user@example.com", subject: "Hello" });
228
185
 
229
- // Check if session is still valid
230
- if (!await client.isAuthorized('github')) {
231
- await client.authorize('github');
232
- }
186
+ // 2. Typed server methods (for server-level tools)
187
+ await client.server.listToolsByIntegration({ integration: "github" });
233
188
 
234
- // Store token after new authorization
235
- const token = client.getSessionToken();
236
- localStorage.setItem('session_token', token);
189
+ // 3. Direct tool calls (for other server-supported integrations)
190
+ await client._callToolByName("slack_send_message", { channel: "#general", text: "Hello" });
237
191
  ```
238
192
 
239
- ### Multiple Providers
193
+ ## OAuth Authorization
240
194
 
241
- Authorize multiple services independently:
195
+ The SDK implements OAuth 2.0 Authorization Code Flow with PKCE for secure authorization.
242
196
 
243
- ```typescript
244
- const client = createMCPClient({
245
- plugins: [
246
- githubPlugin({ ... }),
247
- gmailPlugin({ ... }),
248
- ],
249
- oauthFlow: { mode: 'popup' },
250
- });
251
-
252
- // Get list of all authorized providers
253
- const authorized = await client.authorizedProviders();
254
- console.log('Authorized:', authorized); // ['github', 'gmail']
197
+ **Key Features:**
198
+ - Popup or redirect flow modes
199
+ - ✅ Session token management
200
+ - Multiple provider support
201
+ - PKCE security
255
202
 
256
- // Or check and authorize each provider individually
203
+ **Basic Usage:**
204
+ ```typescript
205
+ // Check authorization
257
206
  if (!await client.isAuthorized('github')) {
258
- await client.authorize('github');
259
- }
260
-
261
- if (!await client.isAuthorized('gmail')) {
262
- await client.authorize('gmail');
207
+ await client.authorize('github'); // Opens popup or redirects
263
208
  }
264
209
 
265
- // Use both services
210
+ // Use authorized client
266
211
  const repos = await client.github.listOwnRepos({});
267
- const messages = await client.gmail.listMessages({});
268
212
  ```
269
213
 
270
- ### Server Requirements
271
-
272
- Your MCP server must implement these OAuth endpoints:
214
+ For complete OAuth setup including:
215
+ - Popup vs redirect flows
216
+ - Session token management
217
+ - Multiple providers
218
+ - Callback page setup
273
219
 
274
- **GET `/oauth/authorize`** - Returns authorization URL
275
- **POST `/oauth/callback`** - Exchanges code for tokens, returns session token
276
- **GET `/oauth/status`** - Checks authorization status
277
-
278
- All tool endpoints must accept `X-Session-Token` header and use stored OAuth tokens for API calls.
279
-
280
- [→ View complete OAuth flow implementation guide](/docs/guides/oauth-flow.md)
220
+ See the [`/examples`](/examples) directory or [OAuth documentation](https://integrate.dev/docs/guides/oauth-flow).
281
221
 
282
222
  ## Built-in Plugins
283
223
 
284
224
  ### GitHub Plugin
285
225
 
286
- Access GitHub repositories, issues, pull requests, and more.
226
+ Access GitHub repositories, issues, pull requests, and more with type-safe methods.
287
227
 
288
228
  ```typescript
289
- const client = createMCPClient({
290
- plugins: [
291
- githubPlugin({
292
- clientId: process.env.GITHUB_CLIENT_ID!,
293
- clientSecret: process.env.GITHUB_CLIENT_SECRET!,
294
- scopes: ["repo", "user"],
295
- }),
296
- ],
297
- });
298
-
299
- await client.connect();
300
-
301
- // Use typed methods
302
- await client.github.getRepo({ owner: "facebook", repo: "react" });
303
- await client.github.createIssue({ owner: "user", repo: "repo", title: "Bug" });
304
- await client.github.listPullRequests({ owner: "user", repo: "repo", state: "open" });
229
+ // Available methods
230
+ await client.github.getRepo({ owner: 'facebook', repo: 'react' });
231
+ await client.github.createIssue({ owner: 'user', repo: 'repo', title: 'Bug' });
232
+ await client.github.listPullRequests({ owner: 'user', repo: 'repo', state: 'open' });
233
+ await client.github.listOwnRepos({});
305
234
  ```
306
235
 
307
- [→ View GitHub plugin documentation](https://integrate.dev/docs/plugins/github)
236
+ [→ GitHub plugin documentation](https://integrate.dev/docs/plugins/github)
308
237
 
309
238
  ### Gmail Plugin
310
239
 
311
- Send emails, manage labels, and search messages.
240
+ Send emails, manage labels, and search messages with type-safe methods.
312
241
 
313
242
  ```typescript
314
- const client = createMCPClient({
315
- plugins: [
316
- gmailPlugin({
317
- clientId: process.env.GMAIL_CLIENT_ID!,
318
- clientSecret: process.env.GMAIL_CLIENT_SECRET!,
319
- }),
320
- ],
321
- });
322
-
323
- await client.connect();
324
-
325
- // Use typed methods
326
- await client.gmail.sendEmail({ to: "user@example.com", subject: "Hello", body: "Hi!" });
327
- await client.gmail.listEmails({ maxResults: 10, q: "is:unread" });
328
- await client.gmail.searchEmails({ query: "from:notifications@github.com" });
243
+ // Available methods
244
+ await client.gmail.sendEmail({ to: 'user@example.com', subject: 'Hello', body: 'Hi!' });
245
+ await client.gmail.listEmails({ maxResults: 10, q: 'is:unread' });
246
+ await client.gmail.searchEmails({ query: 'from:notifications@github.com' });
329
247
  ```
330
248
 
331
- [→ View Gmail plugin documentation](https://integrate.dev/docs/plugins/gmail)
249
+ [→ Gmail plugin documentation](https://integrate.dev/docs/plugins/gmail)
332
250
 
333
- ### Configure Additional Integrations
251
+ ### Additional Integrations
334
252
 
335
- The server may support additional integrations beyond GitHub and Gmail. You can configure OAuth and enable these tools using `genericOAuthPlugin`:
253
+ Use `genericOAuthPlugin` to configure any server-supported integration:
336
254
 
337
255
  ```typescript
338
- import { genericOAuthPlugin } from "integrate-sdk";
256
+ import { genericOAuthPlugin } from 'integrate-sdk/server';
339
257
 
340
- // Configure a plugin for any server-supported integration
341
258
  const slackPlugin = genericOAuthPlugin({
342
- id: "slack",
343
- provider: "slack",
344
- clientId: process.env.SLACK_CLIENT_ID!,
345
- clientSecret: process.env.SLACK_CLIENT_SECRET!,
346
- scopes: ["chat:write", "channels:read"],
347
- tools: ["slack_send_message", "slack_list_channels"], // Must exist on server
348
- });
349
-
350
- const client = createMCPClient({
351
- plugins: [slackPlugin],
352
- });
353
-
354
- await client.connect();
355
-
356
- // Use _callToolByName to call the tools
357
- await client._callToolByName("slack_send_message", {
358
- channel: "#general",
359
- text: "Hello!"
259
+ id: 'slack',
260
+ provider: 'slack',
261
+ clientId: process.env.SLACK_CLIENT_ID,
262
+ clientSecret: process.env.SLACK_CLIENT_SECRET,
263
+ scopes: ['chat:write', 'channels:read'],
264
+ tools: ['slack_send_message', 'slack_list_channels'],
360
265
  });
361
266
  ```
362
267
 
363
- **Note**: Plugins configure access to server-provided tools - they don't create new tools. All tool implementations must exist on the Integrate MCP server.
268
+ See [`/examples`](/examples) for complete setup patterns.
364
269
 
365
270
  ## Vercel AI SDK Integration
366
271
 
@@ -390,6 +295,7 @@ const result = await generateText({
390
295
  For detailed guides, API reference, and examples, visit the [complete documentation](https://integrate.dev):
391
296
 
392
297
  - **[Getting Started](https://integrate.dev/docs/getting-started/installation)** - Installation and quick start
298
+ - **[OAuth Flow](https://integrate.dev/docs/guides/oauth-flow)** - OAuth 2.0 authorization guide
393
299
  - **[Plugins](https://integrate.dev/docs/plugins)** - Built-in plugins and configuration
394
300
  - **[Vercel AI SDK](https://integrate.dev/docs/integrations/vercel-ai)** - AI model integration
395
301
  - **[Advanced Usage](https://integrate.dev/docs/guides/advanced-usage)** - Error handling, retries, and more
package/dist/index.d.ts CHANGED
@@ -1,27 +1,20 @@
1
1
  /**
2
- * Integrate SDK
3
- * Type-safe TypeScript SDK for MCP Client
2
+ * Integrate SDK - Main Entry Point
3
+ *
4
+ * Client-side SDK for MCP with plugin-based configuration
5
+ *
6
+ * @example
7
+ * ```typescript
8
+ * import { createMCPClient, githubPlugin } from 'integrate-sdk';
9
+ *
10
+ * const client = createMCPClient({
11
+ * plugins: [
12
+ * githubPlugin({
13
+ * scopes: ['repo', 'user'],
14
+ * }),
15
+ * ],
16
+ * });
17
+ * ```
4
18
  */
5
- export { MCPClient, createMCPClient, clearClientCache } from "./client.js";
6
- export type { ToolInvocationOptions } from "./client.js";
7
- export { OAuthManager } from "./oauth/manager.js";
8
- export { OAuthWindowManager, sendCallbackToOpener } from "./oauth/window-manager.js";
9
- export { generateCodeVerifier, generateCodeChallenge, generateState } from "./oauth/pkce.js";
10
- export type { OAuthFlowConfig, PopupOptions, AuthStatus, PendingAuth, AuthorizationUrlResponse, OAuthCallbackResponse, OAuthCallbackParams, } from "./oauth/types.js";
11
- export type { MCPClientConfig, ReauthContext, ReauthHandler } from "./config/types.js";
12
- export { IntegrateSDKError, AuthenticationError, AuthorizationError, TokenExpiredError, ConnectionError, ToolCallError, isAuthError, isTokenExpiredError, isAuthorizationError, parseServerError, } from "./errors.js";
13
- export type { MCPPlugin, OAuthConfig, ExtractPluginIds, ExtractPluginTools, } from "./plugins/types.js";
14
- export { githubPlugin } from "./plugins/github.js";
15
- export type { GitHubPluginConfig, GitHubTools, GitHubPluginClient } from "./plugins/github.js";
16
- export { gmailPlugin } from "./plugins/gmail.js";
17
- export type { GmailPluginConfig, GmailTools, GmailPluginClient } from "./plugins/gmail.js";
18
- export type { ServerPluginClient } from "./plugins/server-client.js";
19
- export { genericOAuthPlugin, createSimplePlugin, } from "./plugins/generic.js";
20
- export type { GenericOAuthPluginConfig } from "./plugins/generic.js";
21
- export { convertMCPToolToVercelAI, convertMCPToolsToVercelAI, getVercelAITools, } from "./integrations/vercel-ai.js";
22
- export type { VercelAITool } from "./integrations/vercel-ai.js";
23
- export type { JSONRPCRequest, JSONRPCResponse, JSONRPCSuccessResponse, JSONRPCErrorResponse, JSONRPCNotification, MCPTool, MCPToolsListResponse, MCPToolCallParams, MCPToolCallResponse, MCPInitializeParams, MCPInitializeResponse, } from "./protocol/messages.js";
24
- export { MCPMethod } from "./protocol/messages.js";
25
- export { HttpSessionTransport } from "./transport/http-session.js";
26
- export type { MessageHandler, HttpSessionTransportOptions, } from "./transport/http-session.js";
19
+ export * from './src/index.js';
27
20
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC3E,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGzD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7F,YAAY,EACV,eAAe,EACf,YAAY,EACZ,UAAU,EACV,WAAW,EACX,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvF,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAGrB,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,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE/F,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG3F,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE,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"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,cAAc,gBAAgB,CAAC"}