@qikdev/mcp 1.0.0 → 2.0.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.
Files changed (6) hide show
  1. package/README.md +175 -175
  2. package/build/src/index.d.ts +21 -10
  3. package/build/src/index.d.ts.map +1 -1
  4. package/build/src/index.js +544 -155
  5. package/build/src/index.js.map +1 -1
  6. package/package.json +2 -2
package/README.md CHANGED
@@ -1,237 +1,237 @@
1
1
  # Qik MCP Server
2
2
 
3
- A plug-and-play Model Context Protocol (MCP) server that connects Claude and other AI assistants to the Qik platform. Enable your AI assistant to interact with your Qik content management system, user profiles, forms, files, and more.
3
+ A comprehensive Model Context Protocol (MCP) server for the Qik platform, enabling AI assistants to interact intelligently with Qik's content management system, user management, forms, files, and more.
4
4
 
5
- ## 🚀 Quick Start
5
+ ## 🚀 Key Features
6
6
 
7
- Get up and running in 3 simple steps:
7
+ ### Glossary-Driven Architecture
8
+ - **Dynamic Content Type Discovery**: Automatically discovers and understands all content types defined in your Qik instance
9
+ - **Smart Validation**: Validates requests against actual content type definitions before making API calls
10
+ - **Dynamic Tool Schema Generation**: Tool schemas are generated based on your actual content types, not static definitions
11
+ - **Context-Aware Error Handling**: Provides specific, helpful error messages based on your content structure
8
12
 
9
- ```bash
10
- # 1. Run the setup (will prompt for your access token)
11
- npx qik-mcp-server
12
-
13
- # 2. That's it! The server is now configured and ready to use in Claude
14
- ```
15
-
16
- ## 📋 What You'll Need
13
+ ### Enhanced API Integration
14
+ - **Comprehensive Coverage**: Supports all major Qik API endpoints including content management, profiles, forms, files, and more
15
+ - **Intelligent Request Building**: Auto-validates field types, required fields, and constraints
16
+ - **Proper Error Context**: Explains permission issues and suggests fixes based on the specific operation
17
+ - **Rate Limit Handling**: Gracefully handles API rate limits and provides appropriate feedback
17
18
 
18
- - **Qik Access Token**: Get yours from your Qik application settings
19
- - Should start with `at-` (Application Access Token)
20
- - Must have appropriate permissions for the operations you want to perform
21
- - **Node.js**: Version 18 or higher
19
+ ### Advanced Content Management
20
+ - **Field-Level Validation**: Validates data types, required fields, and constraints before API calls
21
+ - **Reference Validation**: Understands and validates content references between different types
22
+ - **Scope and Permission Awareness**: Respects content scopes and user permissions
23
+ - **Batch Operations**: Supports efficient bulk operations where available
22
24
 
23
- ## 🛠️ Installation Options
25
+ ## 📦 Installation
24
26
 
25
- ### Option 1: One-time Setup (Recommended)
26
27
  ```bash
27
- npx qik-mcp-server
28
+ npm install -g @qikdev/mcp
28
29
  ```
29
30
 
30
- ### Option 2: Global Installation
31
- ```bash
32
- npm install -g qik-mcp-server
33
- qik-mcp-server setup
34
- ```
31
+ ## 🔧 Setup
35
32
 
36
- ### Option 3: Local Installation
33
+ ### Quick Setup
37
34
  ```bash
38
- npm install qik-mcp-server
39
- npx qik-mcp-server setup
35
+ qik-mcp-server setup
40
36
  ```
41
37
 
42
- ## 🔧 Commands
43
-
44
- | Command | Description |
45
- |---------|-------------|
46
- | `qik-mcp-server` | Interactive setup (default) |
47
- | `qik-mcp-server setup` | Run the setup wizard |
48
- | `qik-mcp-server status` | Check configuration status |
49
- | `qik-mcp-server update-token` | Update your access token |
50
- | `qik-mcp-server run` | Run the MCP server directly |
51
-
52
- ## 🎯 Available Tools
53
-
54
- Once configured, you'll have access to these tools in Claude:
38
+ This will guide you through:
39
+ 1. Entering your Qik API access token
40
+ 2. Configuring your API URL (defaults to https://api.qik.dev)
41
+ 3. Automatically adding the server to your MCP configuration
42
+
43
+ ### Manual Setup
44
+
45
+ 1. **Get your Qik API Access Token**:
46
+ - Log in to your Qik dashboard at https://app.qik.dev
47
+ - Navigate to Settings → API Access
48
+ - Generate a new access token
49
+
50
+ 2. **Configure Environment Variables**:
51
+ ```bash
52
+ export QIK_ACCESS_TOKEN="your_access_token_here"
53
+ export QIK_API_URL="https://api.qik.dev" # Optional, defaults to this
54
+ ```
55
+
56
+ 3. **Add to MCP Configuration**:
57
+ Add this to your MCP settings file:
58
+ ```json
59
+ {
60
+ "mcpServers": {
61
+ "qik": {
62
+ "command": "npx",
63
+ "args": ["@qikdev/mcp", "run"]
64
+ }
65
+ }
66
+ }
67
+ ```
68
+
69
+ ## 🛠️ Available Tools
70
+
71
+ ### Authentication & Session
72
+ - `qik_get_user_session` - Get current user session information
73
+
74
+ ### Content Type Discovery
75
+ - `qik_get_glossary` - Get all available content types and their definitions
76
+ - `qik_get_content_definition` - Get detailed definition for a specific content type
55
77
 
56
78
  ### Content Management
57
- - **`qik_get_content`** - Get content by ID or slug
58
- - **`qik_list_content`** - List and search content with filters
59
- - **`qik_create_content`** - Create new content items
60
- - **`qik_update_content`** - Update existing content
61
- - **`qik_delete_content`** - Delete content items
62
-
63
- ### Content Discovery
64
- - **`qik_get_glossary`** - Get all available content types and definitions
65
- - **`qik_get_content_definition`** - Get definition for specific content types
66
- - **`qik_search_content`** - Global search across all content types
79
+ - `qik_get_content` - Get content item by ID or slug
80
+ - `qik_list_content` - List content items with filtering and search
81
+ - `qik_create_content` - Create new content item with validation
82
+ - `qik_update_content` - Update existing content item (partial or full replace)
83
+ - `qik_delete_content` - Delete content item
67
84
 
68
85
  ### Profile Management
69
- - **`qik_list_profiles`** - Search and list people/profiles
70
- - **`qik_create_profile`** - Create new profiles
86
+ - `qik_list_profiles` - Search and list profiles/people
87
+ - `qik_create_profile` - Create new profile/person
71
88
 
72
- ### Forms & Submissions
73
- - **`qik_get_form`** - Get form definitions
74
- - **`qik_submit_form`** - Submit form data
89
+ ### Form Management
90
+ - `qik_get_form` - Get form definition
91
+ - `qik_submit_form` - Submit form data
75
92
 
76
93
  ### File Management
77
- - **`qik_upload_file`** - Upload files to Qik
78
-
79
- ### System & Permissions
80
- - **`qik_get_user_session`** - Get current user session info
81
- - **`qik_get_scopes`** - Get available scopes/permissions
82
- - **`qik_get_smartlist`** - Execute smartlist queries
94
+ - `qik_upload_file` - Upload files to Qik (supports base64 encoding)
83
95
 
84
- ## 💡 Usage Examples
96
+ ### Search & Discovery
97
+ - `qik_search_content` - Global content search across all types
98
+ - `qik_get_scopes` - Get available scopes/permissions tree
99
+ - `qik_get_smartlist` - Execute smartlist queries
85
100
 
86
- ### Ask Claude to help with content:
87
- > "List all articles created this month"
101
+ ## 🎯 Usage Examples
88
102
 
89
- > "Create a new profile for John Smith with email john@example.com"
90
-
91
- > "Search for all content containing 'project update'"
92
-
93
- ### Get system information:
94
- > "Show me my current user session and permissions"
95
-
96
- > "What content types are available in my Qik instance?"
97
-
98
- ## 🔐 Configuration
99
-
100
- The server stores your configuration securely in `~/.qik-mcp/config.json` and automatically configures Claude's MCP settings.
101
-
102
- ### Manual Configuration
103
+ ### Discovering Content Types
104
+ ```javascript
105
+ // Get all available content types
106
+ const glossary = await qik_get_glossary();
103
107
 
104
- If automatic MCP configuration fails, you can manually add this to your Claude MCP settings:
108
+ // Get specific content type definition
109
+ const articleDef = await qik_get_content_definition({ type: "article" });
110
+ ```
105
111
 
106
- ```json
107
- {
108
- "mcpServers": {
109
- "qik": {
110
- "command": "npx",
111
- "args": ["qik-mcp-server", "run"]
112
- }
112
+ ### Creating Content
113
+ ```javascript
114
+ // The server automatically validates against your content type definition
115
+ const newArticle = await qik_create_content({
116
+ type: "article",
117
+ title: "My New Article",
118
+ data: {
119
+ body: "Article content here...",
120
+ author: "John Doe"
121
+ },
122
+ meta: {
123
+ scopes: ["public"],
124
+ security: "public"
113
125
  }
114
- }
126
+ });
115
127
  ```
116
128
 
117
- ### Environment Variables
118
-
119
- For advanced users, you can also configure via environment variables:
120
-
121
- ```bash
122
- export QIK_ACCESS_TOKEN="at-your-token-here"
123
- export QIK_API_URL="https://api.qik.dev" # Optional, defaults to https://api.qik.dev
129
+ ### Searching Content
130
+ ```javascript
131
+ // Search across all content types
132
+ const results = await qik_search_content({
133
+ query: "important announcement",
134
+ types: ["article", "event"],
135
+ limit: 10
136
+ });
137
+
138
+ // List specific content type with filters
139
+ const articles = await qik_list_content({
140
+ type: "article",
141
+ search: "announcement",
142
+ filter: {
143
+ operator: "and",
144
+ filters: [{
145
+ key: "meta.status",
146
+ comparator: "equal",
147
+ value: "active"
148
+ }]
149
+ },
150
+ sort: {
151
+ key: "meta.created",
152
+ direction: "desc",
153
+ type: "date"
154
+ }
155
+ });
124
156
  ```
125
157
 
126
- ## 🔍 Troubleshooting
127
-
128
- ### "Authentication failed"
129
- - Check that your access token is correct and starts with `at-`
130
- - Verify the token has the required permissions
131
- - Try running `qik-mcp-server update-token`
132
-
133
- ### "Server not configured"
134
- - Run `qik-mcp-server setup` to configure
135
- - Check `qik-mcp-server status` for current configuration
136
-
137
- ### "Tools not appearing in Claude"
138
- - Verify MCP configuration with `qik-mcp-server status`
139
- - Restart Claude/Cline
140
- - Check that the server name doesn't conflict with existing MCP servers
158
+ ## 🔍 Smart Features
141
159
 
142
- ### Connection Issues
143
- - Verify internet connection
144
- - Check if your organization has firewall restrictions
145
- - Try with a different API URL if using a custom Qik instance
160
+ ### Automatic Content Type Validation
161
+ The server automatically:
162
+ - Checks if content types exist before making API calls
163
+ - Validates required fields based on your content type definitions
164
+ - Suggests correct field names when invalid ones are used
165
+ - Provides helpful error messages with available options
146
166
 
147
- ## 🏗️ Development
167
+ ### Dynamic Schema Generation
168
+ - Tool schemas are generated based on your actual content types
169
+ - Enum values are populated from your glossary
170
+ - Field descriptions include reference types and constraints
171
+ - Required fields are automatically marked in schemas
148
172
 
149
- ### Building from Source
173
+ ### Intelligent Error Handling
174
+ - Context-aware error messages explain what went wrong and how to fix it
175
+ - Permission errors include information about required scopes
176
+ - Field validation errors specify exactly which fields are invalid and why
177
+ - Network errors are handled gracefully with retry suggestions
150
178
 
151
- ```bash
152
- git clone https://gitlab.com/qikdevelopers/qik-mcp-server.git
153
- cd qik-mcp-server
154
- npm install
155
- npm run build
156
- ```
179
+ ## 🔧 Configuration
157
180
 
158
- ### Running in Development
181
+ ### Environment Variables
182
+ - `QIK_ACCESS_TOKEN` - Your Qik API access token (required)
183
+ - `QIK_API_URL` - Qik API base URL (optional, defaults to https://api.qik.dev)
159
184
 
160
- ```bash
161
- npm run dev
162
- ```
185
+ ### Advanced Configuration
186
+ The server automatically caches glossary data for 5 minutes to improve performance while ensuring content type information stays current.
163
187
 
164
- ### Testing the Server
188
+ ## 🚨 Troubleshooting
165
189
 
190
+ ### Authentication Issues
166
191
  ```bash
167
- # Test the MCP server directly
168
- npm run test
192
+ # Check your token status
193
+ qik-mcp-server status
169
194
 
170
- # Use the MCP inspector
171
- npm run inspector
195
+ # Reconfigure if needed
196
+ qik-mcp-server setup
172
197
  ```
173
198
 
174
- ## 📚 API Reference
175
-
176
- ### Content Types
177
-
178
- The server automatically discovers your organization's content types via the `/glossary` endpoint. Common types include:
199
+ ### Common Issues
179
200
 
180
- - `article` - Articles and blog posts
181
- - `profile` - People and contacts
182
- - `event` - Events and meetings
183
- - `file` - Uploaded files
184
- - `image` - Images and media
185
- - Custom types defined by your organization
201
+ **"Content type 'xyz' not found"**
202
+ - The server will list all available content types in the error message
203
+ - Use `qik_get_glossary` to see all available types
186
204
 
187
- ### Filtering and Search
188
-
189
- Most list operations support advanced filtering using Qik's filter syntax:
190
-
191
- ```javascript
192
- // Example filter for articles created this month
193
- {
194
- "operator": "and",
195
- "filters": [{
196
- "key": "meta.created",
197
- "comparator": "datesamemonth",
198
- "value": "2024-01-01"
199
- }]
200
- }
201
- ```
205
+ **"Field validation errors"**
206
+ - The server provides specific information about which fields are invalid
207
+ - Use `qik_get_content_definition` to see field requirements for a content type
202
208
 
203
- ### Pagination
209
+ **"Access denied"**
210
+ - Check that your access token has the required permissions
211
+ - Verify you're accessing content within your permitted scopes
204
212
 
205
- List operations support pagination:
213
+ ## 📚 API Reference
206
214
 
207
- ```javascript
208
- {
209
- "page": {
210
- "size": 20, // Items per page (1-100)
211
- "index": 1 // Page number (1-based)
212
- }
213
- }
214
- ```
215
+ For detailed API documentation, visit: https://docs.qik.dev/api
215
216
 
216
217
  ## 🤝 Contributing
217
218
 
218
- We welcome contributions! Please see our [GitLab repository](https://gitlab.com/qikdevelopers/qik-mcp-server) for:
219
-
220
- - Issue reporting
221
- - Feature requests
222
- - Pull requests
223
- - Development guidelines
219
+ 1. Fork the repository
220
+ 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
221
+ 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
222
+ 4. Push to the branch (`git push origin feature/amazing-feature`)
223
+ 5. Open a Pull Request
224
224
 
225
225
  ## 📄 License
226
226
 
227
- MIT License - see LICENSE file for details.
227
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
228
228
 
229
229
  ## 🆘 Support
230
230
 
231
- - **Documentation**: [Qik Developer Docs](https://qikdevelopers.gitlab.io/sdk/docs/)
232
- - **Issues**: [GitLab Issues](https://gitlab.com/qikdevelopers/qik-mcp-server/-/issues)
231
+ - **Documentation**: https://docs.qik.dev
232
+ - **Issues**: https://gitlab.com/qikdevelopers/qik-mcp-server/-/issues
233
233
  - **Email**: developers@qik.dev
234
234
 
235
235
  ---
236
236
 
237
- Made with ❤️ by the Qik team
237
+ Built with ❤️ by the Qik team
package/build/src/index.d.ts CHANGED
@@ -1,27 +1,38 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * Qik Platform MCP Server
3
+ * Qik Platform MCP Server - Enhanced Version
4
4
  *
5
5
  * This MCP server provides comprehensive integration with the Qik platform,
6
6
  * enabling AI assistants to interact with Qik's content management system,
7
7
  * user management, forms, files, and more.
8
8
  *
9
- * Features:
10
- * - Content management (CRUD operations)
11
- * - Content type discovery via glossary
12
- * - User and profile management
13
- * - Form handling and submissions
14
- * - File upload and management
15
- * - Search and filtering capabilities
16
- * - Scope and permission management
9
+ * Key Features:
10
+ * - Glossary-driven architecture for dynamic content type discovery
11
+ * - Smart validation based on content type definitions
12
+ * - Context-aware error handling and suggestions
13
+ * - Dynamic tool schema generation
14
+ * - Comprehensive API coverage
15
+ * - Intelligent request building and field validation
17
16
  */
18
17
  export declare class QikMCPServer {
19
18
  private server;
20
19
  private axiosInstance;
21
20
  private glossary;
21
+ private userSession;
22
+ private lastGlossaryUpdate;
23
+ private readonly GLOSSARY_CACHE_TTL;
22
24
  constructor();
23
- private initializeGlossary;
25
+ private log;
26
+ private initializeServer;
27
+ private loadUserSession;
28
+ private loadGlossary;
24
29
  private formatError;
30
+ private getContentTypeInfo;
31
+ private validateContentType;
32
+ private validateFieldData;
33
+ private generateFieldSchema;
34
+ private generateFieldsSchema;
35
+ private mapFieldTypeToJsonSchema;
25
36
  private setupToolHandlers;
26
37
  private getUserSession;
27
38
  private getGlossary;
package/build/src/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;GAeG;AAwFH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAyC;;YAwC3C,kBAAkB;IAUhC,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,iBAAiB;YAmcX,cAAc;YAUd,WAAW;YAaX,oBAAoB;YAUpB,UAAU;YAkBV,WAAW;YAiBX,aAAa;YAgBb,aAAa;YAWb,aAAa;YAUb,YAAY;YAeZ,aAAa;YAmBb,OAAO;YAUP,UAAU;YAUV,UAAU;YA4BV,aAAa;YAgCb,SAAS;YAUT,YAAY;IAUpB,GAAG;CAKV"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;GAcG;AA2HH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAyC;IACzD,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,kBAAkB,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAiB;;IAwCpD,OAAO,CAAC,GAAG;YAQG,gBAAgB;YAYhB,eAAe;YAUf,YAAY;IA+B1B,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,iBAAiB;IAmDzB,OAAO,CAAC,mBAAmB;IAwB3B,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,wBAAwB;IAsBhC,OAAO,CAAC,iBAAiB;YAkeX,cAAc;YAad,WAAW;YAuBX,oBAAoB;YA+BpB,UAAU;YA6BV,WAAW;YAsCX,aAAa;YAoDb,aAAa;YAqBb,aAAa;YAoBb,YAAY;YAyBZ,aAAa;YA6Bb,OAAO;YAoBP,UAAU;YAoBV,UAAU;YAsCV,aAAa;YAiCb,SAAS;YAoBT,YAAY;IAoBpB,GAAG;CAKV"}