@qikdev/mcp 1.0.0

package/build/src/index.js

@@ -0,0 +1,731 @@
+#!/usr/bin/env node
+/**
+ * Qik Platform MCP Server
+ *
+ * This MCP server provides comprehensive integration with the Qik platform,
+ * enabling AI assistants to interact with Qik's content management system,
+ * user management, forms, files, and more.
+ *
+ * Features:
+ * - Content management (CRUD operations)
+ * - Content type discovery via glossary
+ * - User and profile management
+ * - Form handling and submissions
+ * - File upload and management
+ * - Search and filtering capabilities
+ * - Scope and permission management
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import axios from 'axios';
+import FormData from 'form-data';
+// Environment variables
+const QIK_API_URL = process.env.QIK_API_URL || 'https://api.qik.dev';
+const QIK_ACCESS_TOKEN = process.env.QIK_ACCESS_TOKEN;
+export class QikMCPServer {
+    server;
+    axiosInstance;
+    glossary = {};
+    constructor() {
+        if (!QIK_ACCESS_TOKEN) {
+            throw new Error('QIK_ACCESS_TOKEN environment variable is required. Run "qik-mcp-server setup" to configure.');
+        }
+        this.server = new Server({
+            name: "qik-mcp-server",
+            version: "1.0.0",
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        // Configure axios instance with Qik API settings
+        this.axiosInstance = axios.create({
+            baseURL: QIK_API_URL,
+            headers: {
+                'Authorization': `Bearer ${QIK_ACCESS_TOKEN}`,
+                'Content-Type': 'application/json',
+            },
+            timeout: 30000,
+        });
+        this.setupToolHandlers();
+        this.initializeGlossary();
+        // Error handling
+        this.server.onerror = (error) => console.error('[MCP Error]', error);
+        process.on('SIGINT', async () => {
+            await this.server.close();
+            process.exit(0);
+        });
+    }
+    async initializeGlossary() {
+        try {
+            const response = await this.axiosInstance.get('/glossary');
+            this.glossary = response.data || {};
+            console.error(`[Qik MCP] Loaded ${Object.keys(this.glossary).length} content types from glossary`);
+        }
+        catch (error) {
+            console.error('[Qik MCP] Failed to load glossary:', this.formatError(error));
+        }
+    }
+    formatError(error) {
+        if (axios.isAxiosError(error)) {
+            const axiosError = error;
+            if (axiosError.response) {
+                return `HTTP ${axiosError.response.status}: ${JSON.stringify(axiosError.response.data)}`;
+            }
+            return `Network error: ${axiosError.message}`;
+        }
+        return error.message || String(error);
+    }
+    setupToolHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: [
+                // Authentication & Session
+                {
+                    name: 'qik_get_user_session',
+                    description: 'Get current user session information',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {},
+                    },
+                },
+                // Content Type Discovery
+                {
+                    name: 'qik_get_glossary',
+                    description: 'Get all available content types and their definitions',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {},
+                    },
+                },
+                {
+                    name: 'qik_get_content_definition',
+                    description: 'Get definition for a specific content type',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            type: {
+                                type: 'string',
+                                description: 'Content type key (e.g., "article", "profile", "event")',
+                            },
+                        },
+                        required: ['type'],
+                    },
+                },
+                // Content Management
+                {
+                    name: 'qik_get_content',
+                    description: 'Get content item by ID or slug',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'string',
+                                description: 'Content ID',
+                            },
+                            slug: {
+                                type: 'string',
+                                description: 'Content slug (e.g., "article:my-post" or "car:pathfinder")',
+                            },
+                        },
+                        oneOf: [
+                            { required: ['id'] },
+                            { required: ['slug'] },
+                        ],
+                    },
+                },
+                {
+                    name: 'qik_list_content',
+                    description: 'List content items with filtering and search',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            type: {
+                                type: 'string',
+                                description: 'Content type to list (e.g., "article", "profile", "event")',
+                            },
+                            search: {
+                                type: 'string',
+                                description: 'Search keywords',
+                            },
+                            filter: {
+                                type: 'object',
+                                description: 'Filter criteria using Qik filter syntax',
+                            },
+                            sort: {
+                                type: 'object',
+                                properties: {
+                                    key: { type: 'string' },
+                                    direction: { type: 'string', enum: ['asc', 'desc'] },
+                                    type: { type: 'string', enum: ['string', 'number', 'date'] },
+                                },
+                            },
+                            page: {
+                                type: 'object',
+                                properties: {
+                                    size: { type: 'number', minimum: 1, maximum: 100 },
+                                    index: { type: 'number', minimum: 1 },
+                                },
+                            },
+                            select: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Fields to include in response',
+                            },
+                        },
+                        required: ['type'],
+                    },
+                },
+                {
+                    name: 'qik_create_content',
+                    description: 'Create new content item',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            type: {
+                                type: 'string',
+                                description: 'Content type to create',
+                            },
+                            title: {
+                                type: 'string',
+                                description: 'Content title',
+                            },
+                            data: {
+                                type: 'object',
+                                description: 'Content data fields',
+                            },
+                            meta: {
+                                type: 'object',
+                                description: 'Meta information (scopes, tags, etc.)',
+                            },
+                        },
+                        required: ['type', 'title'],
+                    },
+                },
+                {
+                    name: 'qik_update_content',
+                    description: 'Update existing content item',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'string',
+                                description: 'Content ID to update',
+                            },
+                            data: {
+                                type: 'object',
+                                description: 'Data to update (partial update)',
+                            },
+                            replace: {
+                                type: 'boolean',
+                                description: 'Whether to replace entire content (PUT) or merge (PATCH)',
+                                default: false,
+                            },
+                        },
+                        required: ['id', 'data'],
+                    },
+                },
+                {
+                    name: 'qik_delete_content',
+                    description: 'Delete content item',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'string',
+                                description: 'Content ID to delete',
+                            },
+                        },
+                        required: ['id'],
+                    },
+                },
+                // Profile Management
+                {
+                    name: 'qik_list_profiles',
+                    description: 'Search and list profiles/people',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            search: {
+                                type: 'string',
+                                description: 'Search by name or email',
+                            },
+                            filter: {
+                                type: 'object',
+                                description: 'Filter criteria',
+                            },
+                            page: {
+                                type: 'object',
+                                properties: {
+                                    size: { type: 'number', minimum: 1, maximum: 100 },
+                                    index: { type: 'number', minimum: 1 },
+                                },
+                            },
+                        },
+                    },
+                },
+                {
+                    name: 'qik_create_profile',
+                    description: 'Create new profile/person',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            firstName: {
+                                type: 'string',
+                                description: 'First name',
+                            },
+                            lastName: {
+                                type: 'string',
+                                description: 'Last name',
+                            },
+                            emails: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Email addresses',
+                            },
+                            phoneNumbers: {
+                                type: 'array',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        label: { type: 'string' },
+                                        countryCode: { type: 'string' },
+                                        number: { type: 'string' },
+                                    },
+                                },
+                                description: 'Phone numbers',
+                            },
+                            data: {
+                                type: 'object',
+                                description: 'Additional profile data',
+                            },
+                            meta: {
+                                type: 'object',
+                                description: 'Meta information (scopes, tags, etc.)',
+                            },
+                        },
+                        required: ['firstName', 'lastName'],
+                    },
+                },
+                // Form Management
+                {
+                    name: 'qik_get_form',
+                    description: 'Get form definition',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'string',
+                                description: 'Form ID',
+                            },
+                        },
+                        required: ['id'],
+                    },
+                },
+                {
+                    name: 'qik_submit_form',
+                    description: 'Submit form data',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'string',
+                                description: 'Form ID',
+                            },
+                            data: {
+                                type: 'object',
+                                description: 'Form submission data',
+                            },
+                        },
+                        required: ['id', 'data'],
+                    },
+                },
+                // File Management
+                {
+                    name: 'qik_upload_file',
+                    description: 'Upload file to Qik',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            title: {
+                                type: 'string',
+                                description: 'File title',
+                            },
+                            fileData: {
+                                type: 'string',
+                                description: 'Base64 encoded file data',
+                            },
+                            fileName: {
+                                type: 'string',
+                                description: 'Original file name',
+                            },
+                            mimeType: {
+                                type: 'string',
+                                description: 'File MIME type',
+                            },
+                            meta: {
+                                type: 'object',
+                                description: 'Meta information (scopes, tags, etc.)',
+                            },
+                        },
+                        required: ['title', 'fileData', 'fileName'],
+                    },
+                },
+                // Search & Discovery
+                {
+                    name: 'qik_search_content',
+                    description: 'Global content search across all types',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            query: {
+                                type: 'string',
+                                description: 'Search query',
+                            },
+                            types: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Content types to search in',
+                            },
+                            limit: {
+                                type: 'number',
+                                minimum: 1,
+                                maximum: 100,
+                                default: 20,
+                            },
+                        },
+                        required: ['query'],
+                    },
+                },
+                {
+                    name: 'qik_get_scopes',
+                    description: 'Get available scopes/permissions tree',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {},
+                    },
+                },
+                // Utility Tools
+                {
+                    name: 'qik_get_smartlist',
+                    description: 'Execute a smartlist query',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'string',
+                                description: 'Smartlist ID',
+                            },
+                        },
+                        required: ['id'],
+                    },
+                },
+            ],
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            try {
+                switch (request.params.name) {
+                    case 'qik_get_user_session':
+                        return await this.getUserSession();
+                    case 'qik_get_glossary':
+                        return await this.getGlossary();
+                    case 'qik_get_content_definition':
+                        return await this.getContentDefinition(request.params.arguments);
+                    case 'qik_get_content':
+                        return await this.getContent(request.params.arguments);
+                    case 'qik_list_content':
+                        return await this.listContent(request.params.arguments);
+                    case 'qik_create_content':
+                        return await this.createContent(request.params.arguments);
+                    case 'qik_update_content':
+                        return await this.updateContent(request.params.arguments);
+                    case 'qik_delete_content':
+                        return await this.deleteContent(request.params.arguments);
+                    case 'qik_list_profiles':
+                        return await this.listProfiles(request.params.arguments);
+                    case 'qik_create_profile':
+                        return await this.createProfile(request.params.arguments);
+                    case 'qik_get_form':
+                        return await this.getForm(request.params.arguments);
+                    case 'qik_submit_form':
+                        return await this.submitForm(request.params.arguments);
+                    case 'qik_upload_file':
+                        return await this.uploadFile(request.params.arguments);
+                    case 'qik_search_content':
+                        return await this.searchContent(request.params.arguments);
+                    case 'qik_get_scopes':
+                        return await this.getScopes();
+                    case 'qik_get_smartlist':
+                        return await this.getSmartlist(request.params.arguments);
+                    default:
+                        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
+                }
+            }
+            catch (error) {
+                console.error(`[Qik MCP] Error in ${request.params.name}:`, error);
+                if (axios.isAxiosError(error)) {
+                    const axiosError = error;
+                    if (axiosError.response?.status === 401) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: 'Authentication failed. Please check your access token configuration.',
+                                }],
+                            isError: true,
+                        };
+                    }
+                    else if (axiosError.response?.status === 403) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: 'Access denied. Your token may not have permission for this operation.',
+                                }],
+                            isError: true,
+                        };
+                    }
+                    else if (axiosError.response?.status === 429) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: 'Rate limit exceeded. Please try again later.',
+                                }],
+                            isError: true,
+                        };
+                    }
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Error: ${this.formatError(error)}`,
+                        }],
+                    isError: true,
+                };
+            }
+        });
+    }
+    // Tool implementations
+    async getUserSession() {
+        const response = await this.axiosInstance.get('/user');
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                }],
+        };
+    }
+    async getGlossary() {
+        if (Object.keys(this.glossary).length === 0) {
+            await this.initializeGlossary();
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(this.glossary, null, 2),
+                }],
+        };
+    }
+    async getContentDefinition(args) {
+        const response = await this.axiosInstance.get(`/content/${args.type}/definition`);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                }],
+        };
+    }
+    async getContent(args) {
+        let response;
+        if (args.id) {
+            response = await this.axiosInstance.get(`/content/${args.id}`);
+        }
+        else if (args.slug) {
+            response = await this.axiosInstance.get(`/content/slug/${args.slug}`);
+        }
+        else {
+            throw new Error('Either id or slug must be provided');
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                }],
+        };
+    }
+    async listContent(args) {
+        const response = await this.axiosInstance.post(`/content/${args.type}/list`, {
+            search: args.search || '',
+            filter: args.filter || {},
+            sort: args.sort || { key: 'meta.created', direction: 'desc', type: 'date' },
+            page: args.page || { size: 20, index: 1 },
+            select: args.select || [],
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                }],
+        };
+    }
+    async createContent(args) {
+        const payload = {
+            title: args.title,
+            data: args.data || {},
+            meta: args.meta || {},
+        };
+        const response = await this.axiosInstance.post(`/content/${args.type}/create`, payload);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                }],
+        };
+    }
+    async updateContent(args) {
+        const method = args.replace ? 'put' : 'patch';
+        const response = await this.axiosInstance[method](`/content/${args.id}`, args.data);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                }],
+        };
+    }
+    async deleteContent(args) {
+        await this.axiosInstance.delete(`/content/${args.id}`);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Content ${args.id} deleted successfully`,
+                }],
+        };
+    }
+    async listProfiles(args) {
+        const response = await this.axiosInstance.post('/content/profile/list', {
+            search: args.search || '',
+            filter: args.filter || {},
+            page: args.page || { size: 20, index: 1 },
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                }],
+        };
+    }
+    async createProfile(args) {
+        const payload = {
+            firstName: args.firstName,
+            lastName: args.lastName,
+            emails: args.emails || [],
+            phoneNumbers: args.phoneNumbers || [],
+            data: args.data || {},
+            meta: args.meta || {},
+        };
+        const response = await this.axiosInstance.post('/content/profile/create', payload);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                }],
+        };
+    }
+    async getForm(args) {
+        const response = await this.axiosInstance.get(`/form/${args.id}`);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                }],
+        };
+    }
+    async submitForm(args) {
+        const response = await this.axiosInstance.post(`/form/${args.id}`, args.data);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                }],
+        };
+    }
+    async uploadFile(args) {
+        const formData = new FormData();
+        // Convert base64 to buffer
+        const fileBuffer = Buffer.from(args.fileData, 'base64');
+        formData.append('file', fileBuffer, args.fileName);
+        const jsonData = {
+            title: args.title,
+            meta: args.meta || {},
+        };
+        formData.append('json', JSON.stringify(jsonData));
+        const response = await this.axiosInstance.post('/file/upload', formData, {
+            headers: {
+                ...formData.getHeaders(),
+                'Authorization': `Bearer ${QIK_ACCESS_TOKEN}`,
+            },
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                }],
+        };
+    }
+    async searchContent(args) {
+        const results = [];
+        const types = args.types || Object.keys(this.glossary);
+        for (const type of types.slice(0, 5)) { // Limit to 5 types to avoid too many requests
+            try {
+                const response = await this.axiosInstance.post(`/content/${type}/list`, {
+                    search: args.query,
+                    page: { size: args.limit || 20, index: 1 },
+                });
+                if (response.data.items && response.data.items.length > 0) {
+                    results.push({
+                        type,
+                        items: response.data.items,
+                        total: response.data.total,
+                    });
+                }
+            }
+            catch (error) {
+                // Skip types that error (might not exist or no permission)
+                continue;
+            }
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(results, null, 2),
+                }],
+        };
+    }
+    async getScopes() {
+        const response = await this.axiosInstance.get('/scope/tree');
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                }],
+        };
+    }
+    async getSmartlist(args) {
+        const response = await this.axiosInstance.get(`/smartlist/${args.id}`);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                }],
+        };
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error('Qik MCP server running on stdio');
+    }
+}
+// Only run the server if this file is executed directly (not imported)
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const server = new QikMCPServer();
+    server.run().catch(console.error);
+}
+//# sourceMappingURL=index.js.map