instance-mcp 0.0.0-stage → 0.2.0

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.
@@ -0,0 +1,84 @@
1
+ export interface InstanceApiConfig {
2
+ baseUrl: string;
3
+ apiKey: string;
4
+ }
5
+ export declare class InstanceClient {
6
+ private baseUrl;
7
+ private apiKey;
8
+ constructor(config?: Partial<InstanceApiConfig>);
9
+ private request;
10
+ getWorkspaceInfo(): Promise<any>;
11
+ getTags(): Promise<any>;
12
+ createTag(name: string): Promise<any>;
13
+ deleteTag(name: string): Promise<any>;
14
+ getAutomations(): Promise<any>;
15
+ getPipelines(): Promise<any>;
16
+ listContacts(params?: {
17
+ page?: number;
18
+ limit?: number;
19
+ search?: string;
20
+ status?: string;
21
+ tag?: string;
22
+ qualified?: string;
23
+ minScore?: number;
24
+ maxScore?: number;
25
+ }): Promise<any>;
26
+ findContact(params: {
27
+ username?: string;
28
+ email?: string;
29
+ phone?: string;
30
+ }): Promise<any>;
31
+ getContact(id: string): Promise<any>;
32
+ createContact(data: {
33
+ username?: string;
34
+ name?: string;
35
+ email?: string;
36
+ phone?: string;
37
+ status?: string;
38
+ tags?: string[];
39
+ }): Promise<any>;
40
+ updateContact(id: string, data: {
41
+ name?: string;
42
+ email?: string;
43
+ phone?: string;
44
+ status?: string;
45
+ tags?: string[];
46
+ }): Promise<any>;
47
+ addTags(id: string, tags: string[]): Promise<any>;
48
+ removeTag(id: string, tagName: string): Promise<any>;
49
+ updateStatus(id: string, status: string): Promise<any>;
50
+ triggerAutomation(automationId: string, params: {
51
+ contactId?: string;
52
+ username?: string;
53
+ variables?: Record<string, any>;
54
+ }): Promise<any>;
55
+ sendMessage(contactId: string, text: string, mediaUrl?: string): Promise<any>;
56
+ listScheduledPosts(params?: {
57
+ startDate?: string;
58
+ endDate?: string;
59
+ status?: string;
60
+ }): Promise<any>;
61
+ schedulePost(data: {
62
+ mediaUrls: string[];
63
+ caption: string;
64
+ scheduledAt: string;
65
+ mediaType?: string;
66
+ }): Promise<any>;
67
+ cancelScheduledPost(postId: string): Promise<any>;
68
+ getAudienceLists(): Promise<any>;
69
+ createAudienceList(data: {
70
+ name: string;
71
+ description?: string;
72
+ color?: string;
73
+ }): Promise<any>;
74
+ queryAudienceContacts(listId: string, params?: {
75
+ channelFilter?: string;
76
+ search?: string;
77
+ minScore?: number;
78
+ maxScore?: number;
79
+ page?: number;
80
+ limit?: number;
81
+ }): Promise<any>;
82
+ assignToAudienceList(listId: string, contactIds: string[]): Promise<any>;
83
+ deleteAudienceList(listId: string): Promise<any>;
84
+ }
package/dist/client.js ADDED
@@ -0,0 +1,118 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.InstanceClient = void 0;
4
+ class InstanceClient {
5
+ baseUrl;
6
+ apiKey;
7
+ constructor(config) {
8
+ this.baseUrl = (config?.baseUrl || process.env.INSTANCE_API_URL || 'https://api.instance.sale').replace(/\/+$/, '');
9
+ this.apiKey = config?.apiKey || process.env.INSTANCE_API_KEY || '';
10
+ if (!this.apiKey) {
11
+ console.error('[Instance MCP] Warning: INSTANCE_API_KEY environment variable is not set.');
12
+ }
13
+ }
14
+ async request(method, path, options = {}) {
15
+ const url = new URL(`${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`);
16
+ if (options.query) {
17
+ Object.entries(options.query).forEach(([k, v]) => {
18
+ if (v !== undefined && v !== null && v !== '') {
19
+ url.searchParams.append(k, String(v));
20
+ }
21
+ });
22
+ }
23
+ const headers = {
24
+ 'Content-Type': 'application/json',
25
+ 'X-API-Key': this.apiKey,
26
+ };
27
+ const res = await fetch(url.toString(), {
28
+ method,
29
+ headers,
30
+ body: options.body ? JSON.stringify(options.body) : undefined,
31
+ });
32
+ const json = await res.json().catch(() => ({}));
33
+ if (!res.ok) {
34
+ const errMsg = json.message || json.error || `Request failed with status ${res.status}`;
35
+ throw new Error(`[Instance API Error ${res.status}] ${errMsg}`);
36
+ }
37
+ return json;
38
+ }
39
+ // Workspace
40
+ async getWorkspaceInfo() {
41
+ return this.request('GET', '/api/v1/workspace/info');
42
+ }
43
+ async getTags() {
44
+ return this.request('GET', '/api/v1/tags');
45
+ }
46
+ async createTag(name) {
47
+ return this.request('POST', '/api/v1/tags', { body: { name } });
48
+ }
49
+ async deleteTag(name) {
50
+ return this.request('DELETE', `/api/v1/tags/${encodeURIComponent(name)}`);
51
+ }
52
+ async getAutomations() {
53
+ return this.request('GET', '/api/v1/automations');
54
+ }
55
+ async getPipelines() {
56
+ return this.request('GET', '/api/v1/pipelines');
57
+ }
58
+ // Contacts
59
+ async listContacts(params) {
60
+ return this.request('GET', '/api/v1/contacts', { query: params });
61
+ }
62
+ async findContact(params) {
63
+ return this.request('GET', '/api/v1/contacts/find', { query: params });
64
+ }
65
+ async getContact(id) {
66
+ return this.request('GET', `/api/v1/contacts/${id}`);
67
+ }
68
+ async createContact(data) {
69
+ return this.request('POST', '/api/v1/contacts', { body: data });
70
+ }
71
+ async updateContact(id, data) {
72
+ return this.request('PATCH', `/api/v1/contacts/${id}`, { body: data });
73
+ }
74
+ async addTags(id, tags) {
75
+ return this.request('POST', `/api/v1/contacts/${id}/tags`, { body: { tags } });
76
+ }
77
+ async removeTag(id, tagName) {
78
+ return this.request('DELETE', `/api/v1/contacts/${id}/tags/${encodeURIComponent(tagName)}`);
79
+ }
80
+ async updateStatus(id, status) {
81
+ return this.request('POST', `/api/v1/contacts/${id}/status`, { body: { status } });
82
+ }
83
+ // Automations
84
+ async triggerAutomation(automationId, params) {
85
+ return this.request('POST', `/api/v1/automations/${automationId}/trigger`, { body: params });
86
+ }
87
+ // Messaging
88
+ async sendMessage(contactId, text, mediaUrl) {
89
+ return this.request('POST', '/api/v1/messages/send', { body: { contactId, text, mediaUrl } });
90
+ }
91
+ // Content Scheduling
92
+ async listScheduledPosts(params) {
93
+ return this.request('GET', '/api/v1/posts', { query: params });
94
+ }
95
+ async schedulePost(data) {
96
+ return this.request('POST', '/api/v1/posts/schedule', { body: data });
97
+ }
98
+ async cancelScheduledPost(postId) {
99
+ return this.request('DELETE', `/api/v1/posts/${postId}`);
100
+ }
101
+ // Audience Lists & Segmentation
102
+ async getAudienceLists() {
103
+ return this.request('GET', '/api/v1/audience-lists');
104
+ }
105
+ async createAudienceList(data) {
106
+ return this.request('POST', '/api/v1/audience-lists', { body: data });
107
+ }
108
+ async queryAudienceContacts(listId, params) {
109
+ return this.request('GET', `/api/v1/audience-lists/${listId}/contacts`, { query: params });
110
+ }
111
+ async assignToAudienceList(listId, contactIds) {
112
+ return this.request('POST', `/api/v1/audience-lists/${listId}/assign`, { body: { contactIds } });
113
+ }
114
+ async deleteAudienceList(listId) {
115
+ return this.request('DELETE', `/api/v1/audience-lists/${listId}`);
116
+ }
117
+ }
118
+ exports.InstanceClient = InstanceClient;
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
package/dist/index.js ADDED
@@ -0,0 +1,307 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ Object.defineProperty(exports, "__esModule", { value: true });
4
+ const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
5
+ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
6
+ const zod_1 = require("zod");
7
+ const client_js_1 = require("./client.js");
8
+ const server = new mcp_js_1.McpServer({
9
+ name: "instance-mcp",
10
+ version: "0.1.0",
11
+ });
12
+ const client = new client_js_1.InstanceClient();
13
+ // 1. Workspace Info
14
+ const workspaceInfoHandler = async () => {
15
+ try {
16
+ const data = await client.getWorkspaceInfo();
17
+ return {
18
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
19
+ };
20
+ }
21
+ catch (err) {
22
+ return {
23
+ isError: true,
24
+ content: [{ type: "text", text: err.message || "Failed to fetch workspace info" }],
25
+ };
26
+ }
27
+ };
28
+ server.tool("instance_workspace_info", "Inspect the Instance workspace details, connected Instagram accounts, handle, and metadata.", {}, workspaceInfoHandler);
29
+ server.tool("instance_get_workspace_info", "Inspect the Instance workspace details, connected Instagram accounts, handle, and metadata.", {}, workspaceInfoHandler);
30
+ // 2. List Contacts / Leads
31
+ server.tool("instance_list_contacts", "List and search leads / contacts with optional filters for status, score, or search query.", {
32
+ page: zod_1.z.number().optional().describe("Page number (default: 1)"),
33
+ limit: zod_1.z.number().optional().describe("Number of contacts to return (default: 25, max: 100)"),
34
+ search: zod_1.z.string().optional().describe("Search term matching username, name, or email"),
35
+ status: zod_1.z.string().optional().describe("Pipeline stage / deal status filter"),
36
+ tag: zod_1.z.string().optional().describe("Filter by specific tag"),
37
+ qualified: zod_1.z.string().optional().describe("Filter by qualification status ('true' or 'false')"),
38
+ minScore: zod_1.z.number().optional().describe("Minimum AI qualification score (0-100)"),
39
+ maxScore: zod_1.z.number().optional().describe("Maximum AI qualification score (0-100)"),
40
+ }, async (args) => {
41
+ try {
42
+ const data = await client.listContacts(args);
43
+ return {
44
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
45
+ };
46
+ }
47
+ catch (err) {
48
+ return {
49
+ isError: true,
50
+ content: [{ type: "text", text: err.message || "Failed to list contacts" }],
51
+ };
52
+ }
53
+ });
54
+ // 3. Find Single Contact
55
+ server.tool("instance_find_contact", "Find a specific lead by their Instagram username (@username), email, or phone number.", {
56
+ username: zod_1.z.string().optional().describe("Instagram username (with or without @)"),
57
+ email: zod_1.z.string().optional().describe("Contact email address"),
58
+ phone: zod_1.z.string().optional().describe("Contact phone number"),
59
+ }, async (args) => {
60
+ try {
61
+ const data = await client.findContact(args);
62
+ return {
63
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
64
+ };
65
+ }
66
+ catch (err) {
67
+ return {
68
+ isError: true,
69
+ content: [{ type: "text", text: err.message || "Failed to find contact" }],
70
+ };
71
+ }
72
+ });
73
+ // 4. Create Unified Contact
74
+ server.tool("instance_create_contact", "Create or sync a unified contact record in the CRM.", {
75
+ username: zod_1.z.string().optional().describe("Instagram handle"),
76
+ name: zod_1.z.string().optional().describe("Full name of the contact"),
77
+ email: zod_1.z.string().optional().describe("Email address"),
78
+ phone: zod_1.z.string().optional().describe("Phone number"),
79
+ status: zod_1.z.string().optional().describe("Initial pipeline status (e.g. New, Qualified)"),
80
+ tags: zod_1.z.array(zod_1.z.string()).optional().describe("List of initial tags"),
81
+ }, async (args) => {
82
+ try {
83
+ const data = await client.createContact(args);
84
+ return {
85
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
86
+ };
87
+ }
88
+ catch (err) {
89
+ return {
90
+ isError: true,
91
+ content: [{ type: "text", text: err.message || "Failed to create contact" }],
92
+ };
93
+ }
94
+ });
95
+ // 5. Update Contact Status
96
+ server.tool("instance_update_contact_status", "Update the deal pipeline stage or status for an existing lead.", {
97
+ contactId: zod_1.z.string().describe("Contact ID"),
98
+ status: zod_1.z.string().describe("New pipeline stage (e.g. Qualified, In Negotiation, Closed Won)"),
99
+ }, async ({ contactId, status }) => {
100
+ try {
101
+ const data = await client.updateStatus(contactId, status);
102
+ return {
103
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
104
+ };
105
+ }
106
+ catch (err) {
107
+ return {
108
+ isError: true,
109
+ content: [{ type: "text", text: err.message || "Failed to update contact status" }],
110
+ };
111
+ }
112
+ });
113
+ // 6. Add Tags to Contact
114
+ server.tool("instance_add_tags", "Add tags to an existing lead in the CRM.", {
115
+ contactId: zod_1.z.string().describe("Contact ID"),
116
+ tags: zod_1.z.array(zod_1.z.string()).describe("Tags to add (e.g. ['VIP', 'Hot Lead'])"),
117
+ }, async ({ contactId, tags }) => {
118
+ try {
119
+ const data = await client.addTags(contactId, tags);
120
+ return {
121
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
122
+ };
123
+ }
124
+ catch (err) {
125
+ return {
126
+ isError: true,
127
+ content: [{ type: "text", text: err.message || "Failed to add tags" }],
128
+ };
129
+ }
130
+ });
131
+ // 7. Trigger Automation Flow
132
+ server.tool("instance_trigger_automation", "Trigger an automated Instagram sales funnel or flow for a contact.", {
133
+ automationId: zod_1.z.string().describe("Automation Flow ID to trigger"),
134
+ contactId: zod_1.z.string().optional().describe("Target contact ID"),
135
+ username: zod_1.z.string().optional().describe("Target Instagram username (alternative to contactId)"),
136
+ variables: zod_1.z.record(zod_1.z.any()).optional().describe("Optional dynamic variables to inject into flow"),
137
+ }, async ({ automationId, contactId, username, variables }) => {
138
+ try {
139
+ const data = await client.triggerAutomation(automationId, { contactId, username, variables });
140
+ return {
141
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
142
+ };
143
+ }
144
+ catch (err) {
145
+ return {
146
+ isError: true,
147
+ content: [{ type: "text", text: err.message || "Failed to trigger automation" }],
148
+ };
149
+ }
150
+ });
151
+ // 8. Send Direct Message (Meta 24h Window)
152
+ server.tool("instance_send_message", "Send a direct message to a contact on Instagram (enforces Meta 24-hour customer window).", {
153
+ contactId: zod_1.z.string().describe("Target contact ID"),
154
+ text: zod_1.z.string().describe("Message text content to send"),
155
+ mediaUrl: zod_1.z.string().optional().describe("Optional image or media URL attachment"),
156
+ }, async ({ contactId, text, mediaUrl }) => {
157
+ try {
158
+ const data = await client.sendMessage(contactId, text, mediaUrl);
159
+ return {
160
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
161
+ };
162
+ }
163
+ catch (err) {
164
+ return {
165
+ isError: true,
166
+ content: [{ type: "text", text: err.message || "Failed to send message" }],
167
+ };
168
+ }
169
+ });
170
+ // 9. List Scheduled Posts
171
+ server.tool("instance_list_scheduled_posts", "List upcoming and past scheduled posts on Instagram with optional date and status filters.", {
172
+ startDate: zod_1.z.string().optional().describe("Optional start ISO date filter"),
173
+ endDate: zod_1.z.string().optional().describe("Optional end ISO date filter"),
174
+ status: zod_1.z.enum(["SCHEDULED", "PUBLISHED", "FAILED", "ALL"]).optional().describe("Filter by post status"),
175
+ }, async (args) => {
176
+ try {
177
+ const data = await client.listScheduledPosts(args);
178
+ return {
179
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
180
+ };
181
+ }
182
+ catch (err) {
183
+ return {
184
+ isError: true,
185
+ content: [{ type: "text", text: err.message || "Failed to list scheduled posts" }],
186
+ };
187
+ }
188
+ });
189
+ // 10. Schedule Post
190
+ server.tool("instance_schedule_post", "Schedule an Instagram post (image, reel, carousel, or story) with caption and publication time.", {
191
+ mediaUrls: zod_1.z.array(zod_1.z.string()).describe("Array of public media URLs to publish"),
192
+ caption: zod_1.z.string().describe("Post caption including hashtags"),
193
+ scheduledAt: zod_1.z.string().describe("ISO-8601 publication date/time string (must be in future)"),
194
+ mediaType: zod_1.z.enum(["IMAGE", "REEL", "CAROUSEL", "STORY"]).optional().describe("Post type (default: IMAGE)"),
195
+ }, async ({ mediaUrls, caption, scheduledAt, mediaType }) => {
196
+ try {
197
+ const data = await client.schedulePost({ mediaUrls, caption, scheduledAt, mediaType });
198
+ return {
199
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
200
+ };
201
+ }
202
+ catch (err) {
203
+ return {
204
+ isError: true,
205
+ content: [{ type: "text", text: err.message || "Failed to schedule post" }],
206
+ };
207
+ }
208
+ });
209
+ // 11. Cancel Scheduled Post
210
+ server.tool("instance_cancel_scheduled_post", "Cancel or delete an upcoming scheduled post before it is published.", {
211
+ postId: zod_1.z.string().describe("ID of the scheduled post to cancel"),
212
+ }, async ({ postId }) => {
213
+ try {
214
+ const data = await client.cancelScheduledPost(postId);
215
+ return {
216
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
217
+ };
218
+ }
219
+ catch (err) {
220
+ return {
221
+ isError: true,
222
+ content: [{ type: "text", text: err.message || "Failed to cancel scheduled post" }],
223
+ };
224
+ }
225
+ });
226
+ // 12. Get Audience Lists
227
+ server.tool("instance_get_audience_lists", "Get all audience lists and segmentation groups in the workspace with contact counts.", {}, async () => {
228
+ try {
229
+ const data = await client.getAudienceLists();
230
+ return {
231
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
232
+ };
233
+ }
234
+ catch (err) {
235
+ return {
236
+ isError: true,
237
+ content: [{ type: "text", text: err.message || "Failed to fetch audience lists" }],
238
+ };
239
+ }
240
+ });
241
+ // 13. Create Audience List
242
+ server.tool("instance_create_audience_list", "Create a new audience segmentation list (e.g. 'VIP Buyers', 'Black Friday Leads').", {
243
+ name: zod_1.z.string().describe("Name of the audience list"),
244
+ description: zod_1.z.string().optional().describe("Optional description"),
245
+ color: zod_1.z.string().optional().describe("Optional hex color or tag color"),
246
+ }, async (args) => {
247
+ try {
248
+ const data = await client.createAudienceList(args);
249
+ return {
250
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
251
+ };
252
+ }
253
+ catch (err) {
254
+ return {
255
+ isError: true,
256
+ content: [{ type: "text", text: err.message || "Failed to create audience list" }],
257
+ };
258
+ }
259
+ });
260
+ // 14. Query Audience Contacts
261
+ server.tool("instance_query_audience_contacts", "Query contacts in an audience list with deep channel (email/phone), score, and search filters.", {
262
+ listId: zod_1.z.string().describe("Target audience list ID"),
263
+ channelFilter: zod_1.z.enum(["all", "email", "phone", "both"]).optional().describe("Filter by available contact channel"),
264
+ search: zod_1.z.string().optional().describe("Search term for contact name, email, or username"),
265
+ page: zod_1.z.number().optional().describe("Page number (default: 1)"),
266
+ limit: zod_1.z.number().optional().describe("Page size (default: 25, max: 100)"),
267
+ }, async ({ listId, ...params }) => {
268
+ try {
269
+ const data = await client.queryAudienceContacts(listId, params);
270
+ return {
271
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
272
+ };
273
+ }
274
+ catch (err) {
275
+ return {
276
+ isError: true,
277
+ content: [{ type: "text", text: err.message || "Failed to query audience contacts" }],
278
+ };
279
+ }
280
+ });
281
+ // 15. Assign to Audience List
282
+ server.tool("instance_assign_to_audience_list", "Assign one or more contact IDs into an audience list.", {
283
+ listId: zod_1.z.string().describe("Target audience list ID"),
284
+ contactIds: zod_1.z.array(zod_1.z.string()).describe("Array of contact IDs to assign"),
285
+ }, async ({ listId, contactIds }) => {
286
+ try {
287
+ const data = await client.assignToAudienceList(listId, contactIds);
288
+ return {
289
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
290
+ };
291
+ }
292
+ catch (err) {
293
+ return {
294
+ isError: true,
295
+ content: [{ type: "text", text: err.message || "Failed to assign to audience list" }],
296
+ };
297
+ }
298
+ });
299
+ async function main() {
300
+ const transport = new stdio_js_1.StdioServerTransport();
301
+ await server.connect(transport);
302
+ console.error("[Instance MCP Server] Started successfully via stdio");
303
+ }
304
+ main().catch((err) => {
305
+ console.error("[Instance MCP Server] Fatal error:", err);
306
+ process.exit(1);
307
+ });
package/package.json CHANGED
@@ -1,6 +1,30 @@
1
1
  {
2
2
  "name": "instance-mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "Official Model Context Protocol (MCP) server for Instance AI Sales CRM",
5
+ "private": false,
6
+ "publishConfig": {
7
+ "access": "public"
8
+ },
9
+ "files": [
10
+ "dist"
11
+ ],
12
+ "bin": {
13
+ "instance-mcp": "dist/index.js"
14
+ },
15
+ "main": "./dist/index.js",
16
+ "types": "./dist/index.d.ts",
17
+ "scripts": {
18
+ "build": "tsc -p tsconfig.json",
19
+ "start": "node dist/index.js",
20
+ "typecheck": "tsc --noEmit"
21
+ },
22
+ "dependencies": {
23
+ "@modelcontextprotocol/sdk": "^1.6.1",
24
+ "zod": "^3.24.2"
25
+ },
26
+ "devDependencies": {
27
+ "@types/node": "^20.19.37",
28
+ "typescript": "^5.9.3"
29
+ }
30
+ }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.