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.
@@ -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;
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
@@ -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.