instance-mcp 0.0.0-stage → 0.1.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.
- package/dist/client.d.ts +56 -0
- package/dist/client.js +92 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +178 -0
- package/package.json +28 -4
- package/README.md +0 -3
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
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
|
+
}
|
package/dist/client.js
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
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
|
+
}
|
|
92
|
+
exports.InstanceClient = InstanceClient;
|
package/dist/index.d.ts
ADDED
package/dist/index.js
ADDED
|
@@ -0,0 +1,178 @@
|
|
|
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
|
+
async function main() {
|
|
171
|
+
const transport = new stdio_js_1.StdioServerTransport();
|
|
172
|
+
await server.connect(transport);
|
|
173
|
+
console.error("[Instance MCP Server] Started successfully via stdio");
|
|
174
|
+
}
|
|
175
|
+
main().catch((err) => {
|
|
176
|
+
console.error("[Instance MCP Server] Fatal error:", err);
|
|
177
|
+
process.exit(1);
|
|
178
|
+
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,30 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "instance-mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.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