integrate-sdk 0.2.4 → 0.3.1
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.
- package/README.md +148 -242
- package/dist/adapters/auto-routes.d.ts +51 -0
- package/dist/adapters/auto-routes.d.ts.map +1 -0
- package/dist/adapters/base-handler.d.ts +106 -0
- package/dist/adapters/base-handler.d.ts.map +1 -0
- package/dist/adapters/nextjs.d.ts +223 -0
- package/dist/adapters/nextjs.d.ts.map +1 -0
- package/dist/adapters/tanstack-start.d.ts +169 -0
- package/dist/adapters/tanstack-start.d.ts.map +1 -0
- package/dist/config/types.d.ts +20 -0
- package/dist/config/types.d.ts.map +1 -1
- package/dist/index.d.ts +4 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/oauth/manager.d.ts +6 -4
- package/dist/oauth/manager.d.ts.map +1 -1
- package/dist/oauth.js +194 -0
- package/dist/plugins/github.d.ts +24 -7
- package/dist/plugins/github.d.ts.map +1 -1
- package/dist/plugins/gmail.d.ts +25 -7
- package/dist/plugins/gmail.d.ts.map +1 -1
- package/dist/plugins/types.d.ts +16 -4
- package/dist/plugins/types.d.ts.map +1 -1
- package/dist/server.d.ts +54 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/src/index.js +1556 -0
- package/dist/{index.js → src/server.js} +232 -71
- package/oauth.ts +20 -0
- package/package.json +13 -3
- package/server.ts +12 -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
|
-
-
|
|
16
|
-
- 🔐 **OAuth
|
|
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
|
-
|
|
36
|
+
// lib/integrate-server.ts (server-side only!)
|
|
37
|
+
import { createMCPServer, githubPlugin, gmailPlugin } from 'integrate-sdk/server';
|
|
32
38
|
|
|
33
|
-
|
|
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: [
|
|
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
|
-
|
|
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
|
-
//
|
|
76
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
91
|
-
|
|
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
|
-
|
|
98
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
125
|
-
clientSecret
|
|
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
|
-
//
|
|
137
|
-
|
|
93
|
+
// Authorize user (opens popup)
|
|
94
|
+
await client.authorize('github');
|
|
138
95
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
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
|
-
|
|
145
|
-
const repos = await client.github.listOwnRepos({});
|
|
104
|
+
console.log('Issue created:', result);
|
|
146
105
|
```
|
|
147
106
|
|
|
148
|
-
|
|
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
|
-
|
|
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: [
|
|
155
|
-
|
|
125
|
+
plugins: [
|
|
126
|
+
githubPlugin({
|
|
127
|
+
scopes: ['repo', 'user'],
|
|
128
|
+
}),
|
|
129
|
+
],
|
|
156
130
|
});
|
|
157
131
|
|
|
158
|
-
//
|
|
132
|
+
// Use immediately - no connect() needed!
|
|
159
133
|
await client.authorize('github');
|
|
134
|
+
await client.github.listRepos({ username: 'octocat' });
|
|
160
135
|
|
|
161
|
-
//
|
|
162
|
-
const
|
|
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
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
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
|
-
|
|
149
|
+
**Need help?** Check out the [complete documentation](https://integrate.dev) for detailed guides, examples, and API reference.
|
|
190
150
|
|
|
191
|
-
|
|
151
|
+
## Browser & Server Support
|
|
192
152
|
|
|
193
|
-
|
|
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
|
-
|
|
201
|
-
|
|
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
|
-
|
|
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
|
-
|
|
212
|
-
|
|
213
|
-
|
|
160
|
+
## Why Use Integrate SDK?
|
|
161
|
+
|
|
162
|
+
### Typed Plugin Methods
|
|
214
163
|
|
|
215
|
-
|
|
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
|
-
###
|
|
172
|
+
### Benefits
|
|
219
173
|
|
|
220
|
-
|
|
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
|
-
//
|
|
224
|
-
|
|
225
|
-
|
|
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
|
-
//
|
|
230
|
-
|
|
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
|
-
//
|
|
235
|
-
|
|
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
|
-
|
|
193
|
+
## OAuth Authorization
|
|
240
194
|
|
|
241
|
-
|
|
195
|
+
The SDK implements OAuth 2.0 Authorization Code Flow with PKCE for secure authorization.
|
|
242
196
|
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
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
|
-
|
|
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
|
|
210
|
+
// Use authorized client
|
|
266
211
|
const repos = await client.github.listOwnRepos({});
|
|
267
|
-
const messages = await client.gmail.listMessages({});
|
|
268
212
|
```
|
|
269
213
|
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
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
|
-
|
|
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
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
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
|
-
[→
|
|
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
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
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
|
-
[→
|
|
249
|
+
[→ Gmail plugin documentation](https://integrate.dev/docs/plugins/gmail)
|
|
332
250
|
|
|
333
|
-
###
|
|
251
|
+
### Additional Integrations
|
|
334
252
|
|
|
335
|
-
|
|
253
|
+
Use `genericOAuthPlugin` to configure any server-supported integration:
|
|
336
254
|
|
|
337
255
|
```typescript
|
|
338
|
-
import { genericOAuthPlugin } from
|
|
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:
|
|
343
|
-
provider:
|
|
344
|
-
clientId: process.env.SLACK_CLIENT_ID
|
|
345
|
-
clientSecret: process.env.SLACK_CLIENT_SECRET
|
|
346
|
-
scopes: [
|
|
347
|
-
tools: [
|
|
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
|
-
|
|
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
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Auto-generated OAuth Routes
|
|
3
|
+
* Automatically creates the correct route handlers based on framework detection
|
|
4
|
+
*/
|
|
5
|
+
import { type OAuthHandlerConfig } from './base-handler.js';
|
|
6
|
+
/**
|
|
7
|
+
* Set the global OAuth configuration
|
|
8
|
+
* Called internally by createMCPClient
|
|
9
|
+
*/
|
|
10
|
+
export declare function setGlobalOAuthConfig(config: OAuthHandlerConfig): void;
|
|
11
|
+
/**
|
|
12
|
+
* Get the global OAuth configuration
|
|
13
|
+
*/
|
|
14
|
+
export declare function getGlobalOAuthConfig(): OAuthHandlerConfig | null;
|
|
15
|
+
/**
|
|
16
|
+
* Universal OAuth route handler
|
|
17
|
+
* Automatically detects framework and handles all OAuth actions
|
|
18
|
+
*
|
|
19
|
+
* This is the magic function that makes everything "just work"
|
|
20
|
+
*
|
|
21
|
+
* @example
|
|
22
|
+
* ```typescript
|
|
23
|
+
* // app/api/integrate/oauth/[action]/route.ts (Next.js)
|
|
24
|
+
* export * from 'integrate-sdk/oauth';
|
|
25
|
+
* ```
|
|
26
|
+
*
|
|
27
|
+
* @example
|
|
28
|
+
* ```typescript
|
|
29
|
+
* // app/routes/api/integrate/oauth/[action].ts (TanStack Start)
|
|
30
|
+
* export * from 'integrate-sdk/oauth';
|
|
31
|
+
* ```
|
|
32
|
+
*/
|
|
33
|
+
/**
|
|
34
|
+
* Universal POST handler
|
|
35
|
+
* Handles authorize and callback actions
|
|
36
|
+
*/
|
|
37
|
+
export declare function POST(req: any, context?: {
|
|
38
|
+
params: {
|
|
39
|
+
action: string;
|
|
40
|
+
};
|
|
41
|
+
}): Promise<any>;
|
|
42
|
+
/**
|
|
43
|
+
* Universal GET handler
|
|
44
|
+
* Handles status action
|
|
45
|
+
*/
|
|
46
|
+
export declare function GET(req: any, context?: {
|
|
47
|
+
params: {
|
|
48
|
+
action: string;
|
|
49
|
+
};
|
|
50
|
+
}): Promise<any>;
|
|
51
|
+
//# sourceMappingURL=auto-routes.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"auto-routes.d.ts","sourceRoot":"","sources":["../../src/adapters/auto-routes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAQ1E;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAErE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,kBAAkB,GAAG,IAAI,CAEhE;AAED;;;;;;;;;;;;;;;;;GAiBG;AAkBH;;;GAGG;AACH,wBAAsB,IAAI,CACxB,GAAG,EAAE,GAAG,EACR,OAAO,CAAC,EAAE;IAAE,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACvC,OAAO,CAAC,GAAG,CAAC,CAgCd;AAED;;;GAGG;AACH,wBAAsB,GAAG,CACvB,GAAG,EAAE,GAAG,EACR,OAAO,CAAC,EAAE;IAAE,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACvC,OAAO,CAAC,GAAG,CAAC,CAkCd"}
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Base OAuth Handler
|
|
3
|
+
* Framework-agnostic OAuth route logic for secure server-side token management
|
|
4
|
+
*/
|
|
5
|
+
/**
|
|
6
|
+
* OAuth handler configuration
|
|
7
|
+
* OAuth credentials for each provider
|
|
8
|
+
*/
|
|
9
|
+
export interface OAuthHandlerConfig {
|
|
10
|
+
/** OAuth configurations by provider */
|
|
11
|
+
providers: Record<string, {
|
|
12
|
+
/** OAuth client ID from environment variables */
|
|
13
|
+
clientId: string;
|
|
14
|
+
/** OAuth client secret from environment variables */
|
|
15
|
+
clientSecret: string;
|
|
16
|
+
/** Optional redirect URI override */
|
|
17
|
+
redirectUri?: string;
|
|
18
|
+
}>;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Request body for authorize endpoint
|
|
22
|
+
*/
|
|
23
|
+
export interface AuthorizeRequest {
|
|
24
|
+
provider: string;
|
|
25
|
+
scopes: string[];
|
|
26
|
+
state: string;
|
|
27
|
+
codeChallenge: string;
|
|
28
|
+
codeChallengeMethod: string;
|
|
29
|
+
redirectUri?: string;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Response from authorize endpoint
|
|
33
|
+
*/
|
|
34
|
+
export interface AuthorizeResponse {
|
|
35
|
+
authorizationUrl: string;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Request body for callback endpoint
|
|
39
|
+
*/
|
|
40
|
+
export interface CallbackRequest {
|
|
41
|
+
provider: string;
|
|
42
|
+
code: string;
|
|
43
|
+
codeVerifier: string;
|
|
44
|
+
state: string;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Response from callback endpoint
|
|
48
|
+
*/
|
|
49
|
+
export interface CallbackResponse {
|
|
50
|
+
sessionToken: string;
|
|
51
|
+
provider: string;
|
|
52
|
+
scopes: string[];
|
|
53
|
+
expiresAt?: number;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Response from status endpoint
|
|
57
|
+
*/
|
|
58
|
+
export interface StatusResponse {
|
|
59
|
+
authorized: boolean;
|
|
60
|
+
provider: string;
|
|
61
|
+
scopes?: string[];
|
|
62
|
+
expiresAt?: number;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* OAuth Handler
|
|
66
|
+
* Handles OAuth authorization flows by proxying requests to MCP server
|
|
67
|
+
* with server-side OAuth credentials from environment variables
|
|
68
|
+
*/
|
|
69
|
+
export declare class OAuthHandler {
|
|
70
|
+
private config;
|
|
71
|
+
private readonly serverUrl;
|
|
72
|
+
constructor(config: OAuthHandlerConfig);
|
|
73
|
+
/**
|
|
74
|
+
* Handle authorization URL request
|
|
75
|
+
* Gets authorization URL from MCP server with full OAuth credentials
|
|
76
|
+
*
|
|
77
|
+
* @param request - Authorization request from client
|
|
78
|
+
* @returns Authorization URL to redirect/open for user
|
|
79
|
+
*
|
|
80
|
+
* @throws Error if provider is not configured
|
|
81
|
+
* @throws Error if MCP server request fails
|
|
82
|
+
*/
|
|
83
|
+
handleAuthorize(request: AuthorizeRequest): Promise<AuthorizeResponse>;
|
|
84
|
+
/**
|
|
85
|
+
* Handle OAuth callback
|
|
86
|
+
* Exchanges authorization code for session token
|
|
87
|
+
*
|
|
88
|
+
* @param request - Callback request with authorization code
|
|
89
|
+
* @returns Session token and authorization details
|
|
90
|
+
*
|
|
91
|
+
* @throws Error if MCP server request fails
|
|
92
|
+
*/
|
|
93
|
+
handleCallback(request: CallbackRequest): Promise<CallbackResponse>;
|
|
94
|
+
/**
|
|
95
|
+
* Handle authorization status check
|
|
96
|
+
* Checks if a provider is currently authorized
|
|
97
|
+
*
|
|
98
|
+
* @param provider - Provider to check
|
|
99
|
+
* @param sessionToken - Session token from client
|
|
100
|
+
* @returns Authorization status
|
|
101
|
+
*
|
|
102
|
+
* @throws Error if MCP server request fails
|
|
103
|
+
*/
|
|
104
|
+
handleStatus(provider: string, sessionToken: string): Promise<StatusResponse>;
|
|
105
|
+
}
|
|
106
|
+
//# sourceMappingURL=base-handler.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"base-handler.d.ts","sourceRoot":"","sources":["../../src/adapters/base-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;QACxB,iDAAiD;QACjD,QAAQ,EAAE,MAAM,CAAC;QACjB,qDAAqD;QACrD,YAAY,EAAE,MAAM,CAAC;QACrB,qCAAqC;QACrC,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,qBAAa,YAAY;IAGX,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;gBAExB,MAAM,EAAE,kBAAkB;IAE9C;;;;;;;;;OASG;IACG,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0C5E;;;;;;;;OAQG;IACG,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA0BzE;;;;;;;;;OASG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CA4BpF"}
|