@qikdev/mcp 6.10.3 → 6.12.0

package/README.md

@@ -1,14 +1,19 @@
 # Qik MCP Server
 
-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.
+A Model Context Protocol (MCP) server for the Qik platform, enabling AI assistants to interact with Qik's content management system, user management, forms, files, and more.
 
 ## Install
 
 ### One-Click Install (Claude Desktop)
 
-Download the [`qik.mcpb`](https://api.qik.dev/file/69a624516644ea20ba482e2e/qik.mcpb) file and open it. Claude Desktop will prompt you to install the extension and enter your Qik API access token. That's it.
+1. Download the [`qik.mcpb`](https://api.qik.dev/file/69a624516644ea20ba482e2e/qik.mcpb) file and open it
+2. Claude Desktop will prompt you to install the extension
+3. Enter your Qik API access token and a server name when prompted
+4. **Restart Claude Desktop** — the server won't appear until you quit and reopen the app
 
-### CLI Install (Developers)
+> **Multiple organisations:** You can install the extension multiple times with different access tokens and server names (e.g. `qik-acme`, `qik-contoso`) to connect to multiple Qik organisations at once.
+
+### CLI Install
 
 ```bash
 npx @qikdev/mcp setup
@@ -19,192 +24,152 @@ Setup will ask you to choose how to authenticate:
 1. **Login with email and password** — enter your Qik credentials (supports MFA). The server stores a refresh token and automatically keeps your session alive.
 2. **Enter an access token** — paste a static token generated in the Qik dashboard.
 
-Then it automatically configures Claude Desktop. Restart Claude Desktop and you're ready to go.
+You'll then choose a server name (defaults to `qik-{orgname}`) and the CLI will configure Claude Desktop automatically.
 
-## Key Features
+**Important: Restart Claude Desktop after setup.** The server won't be available until you quit and reopen the app.
 
-- **Dynamic Content Type Discovery**: Automatically discovers and understands all content types defined in your Qik instance
-- **Smart Validation**: Validates requests against actual content type definitions before making API calls
-- **Comprehensive Coverage**: 48 tools covering content management, profiles, workflows, campaigns, interface building, and more
-- **Automatic Token Refresh**: Sessions stay alive — tokens are refreshed automatically before they expire
-- **Intelligent Error Handling**: Context-aware error messages with suggested fixes
+> **Multiple organisations:** Run `npx @qikdev/mcp setup` again to add another organisation. Each one gets its own server name and config file.
 
-## 📋 CLI Commands
+## CLI Commands
 
 ```bash
-npx @qikdev/mcp setup        # Initial setup (interactive)
-npx @qikdev/mcp status       # Check configuration status
-npx @qikdev/mcp update-token # Update your access token
-npx @qikdev/mcp install      # Add to Claude Desktop config
-npx @qikdev/mcp remove       # Remove from Claude Desktop config
+npx @qikdev/mcp setup        # Set up a new instance (can run multiple times)
+npx @qikdev/mcp status       # Show all configured instances and their status
+npx @qikdev/mcp update-token # Update the access token for an instance
+npx @qikdev/mcp update       # Update to the latest version
+npx @qikdev/mcp remove       # Remove an instance
+npx @qikdev/mcp install      # Show installation guide
 ```
 
-## 🛠️ Available Tools
+When you have multiple instances configured, commands like `update-token` and `remove` will prompt you to choose which instance to manage.
 
-### Authentication & Session
-- `qik_get_user_session` - Get current user session information
+## Available Tools
 
-### Content Type Discovery
-- `qik_get_glossary` - Get all available content types and their definitions
-- `qik_get_content_definition` - Get detailed definition for a specific content type
+### Discovery
+- `get_glossary` — List all content types and their definitions
+- `get_content_type_details` — Get detailed schema for a content type
+- `search_content_types` — Search content types by keyword
+- `get_filter_comparators` — Get available filter operators
+- `get_entity_relationships` — Get relationship types between entities
 
 ### Content Management
-- `qik_get_content` - Get content item by ID or slug
-- `qik_list_content` - List content items with filtering and search
-- `qik_create_content` - Create new content item with validation
-- `qik_update_content` - Update existing content item (partial or full replace)
-- `qik_delete_content` - Delete content item
-
-### Profile Management
-- `qik_list_profiles` - Search and list profiles/people
-- `qik_create_profile` - Create new profile/person
-
-### Form Management
-- `qik_get_form` - Get form definition
-- `qik_submit_form` - Submit form data
+- `create_content` — Create a new content item with validation
+- `list_content` — Query and filter content with sorting and pagination
+- `get_content` — Get a single content item by ID
+- `update_content` — Update an existing content item
+- `delete_content` — Soft-delete a content item
+- `restore_content` — Restore a deleted content item
+- `global_search` — Search across all content types
+- `count_content` — Count content matching filters
 
 ### File Management
-- `qik_upload_file` - Upload files to Qik (supports base64 encoding)
-
-### Search & Discovery
-- `qik_search_content` - Global content search across all types
-- `qik_get_scopes` - Get available scopes/permissions tree
-- `qik_get_smartlist` - Execute smartlist queries
-
-## 🎯 Usage Examples
-
-### Discovering Content Types
-```javascript
-// Get all available content types
-const glossary = await qik_get_glossary();
-
-// Get specific content type definition
-const articleDef = await qik_get_content_definition({ type: "article" });
-```
-
-### Creating Content
-```javascript
-// The server automatically validates against your content type definition
-const newArticle = await qik_create_content({
-  type: "article",
-  title: "My New Article",
-  data: {
-    body: "Article content here...",
-    author: "John Doe"
-  },
-  meta: {
-    scopes: ["public"],
-    security: "public"
-  }
-});
-```
-
-### Searching Content
-```javascript
-// Search across all content types
-const results = await qik_search_content({
-  query: "important announcement",
-  types: ["article", "event"],
-  limit: 10
-});
-
-// List specific content type with filters
-const articles = await qik_list_content({
-  type: "article",
-  search: "announcement",
-  filter: {
-    operator: "and",
-    filters: [{
-      key: "meta.status",
-      comparator: "equal",
-      value: "active"
-    }]
-  },
-  sort: {
-    key: "meta.created",
-    direction: "desc",
-    type: "date"
-  }
-});
-```
-
-## 🔍 Smart Features
-
-### Automatic Content Type Validation
-The server automatically:
-- Checks if content types exist before making API calls
-- Validates required fields based on your content type definitions
-- Suggests correct field names when invalid ones are used
-- Provides helpful error messages with available options
+- `upload_file` — Upload a file from a local path or URL
+- `check_file_exists` — Check for duplicates before uploading
+- `replace_file` — Replace the file on an existing content item
+
+### Profiles & Relationships
+- `get_user_session` — Get current user session and permissions
+- `get_profile_timeline` — Get activity timeline for a profile
+- `get_profile_relationships` — List relationships for a profile
+- `create_relationship` — Create a relationship between profiles
+- `delete_relationship` — Remove a relationship
+- `create_profile_with_relationship` — Create a profile and link it in one step
+- `get_profile_groups` — Get groups a profile belongs to
+- `get_profile_access` — Get access permissions for a profile
+- `get_profile_blockout` — Get blockout dates for a profile
+- `create_profile_blockout` — Create a blockout period
+
+### Definitions
+- `get_definition_schema` — Get the field schema for a definition
+- `search_similar_definitions` — Find similar definition types
+- `create_definition` — Create a new content type definition
+- `update_definition` — Update an existing definition
+- `list_definitions` — List all definitions
+
+### Campaigns & Communication
+- `get_campaign_recipients` — Get recipient list for a campaign
+- `get_campaign_analytics` — Get campaign performance data
+- `send_campaign` — Send a campaign
+- `send_test_campaign` — Send a test campaign
+- `send_bulk_sms` — Send bulk SMS messages
+
+### Scopes
+- `get_scope_tree` — Get the full scope hierarchy
+- `get_actionable_scopes` — Get scopes the user can act on
+- `add_profile_to_scope` — Add a profile to a scope
+- `remove_profile_from_scope` — Remove a profile from a scope
+
+### Smart Lists & Duplicates
+- `run_smartlist` — Execute a smart list query
+- `export_smartlist` — Export smart list results
+- `detect_duplicates` — Find potential duplicate records
+- `mark_distinct` — Mark records as not duplicates
+- `preview_merge` — Preview a merge of duplicate records
+- `start_merge` — Execute a merge
+- `get_merge_progress` — Check merge progress
+
+### Check-in
+- `create_checkin` — Check in a profile to an event
+- `checkout` — Check out a profile
+
+### Forms
+- `list_forms` — List available forms
+
+### Workflows
+- `list_workflows` — List workflows
+- `get_workflow` — Get workflow details
+- `create_workflow` — Create a new workflow
+- `update_workflow` — Update an existing workflow
+
+### Interface Builder
+- `list_interface_components` — List available components
+- `get_interface_component_details` — Get component schema
+- `create_interface` — Create a new interface
+- `get_interface` — Get interface details
+- `publish_interface` — Publish an interface
+- `add_interface_route` / `update_interface_route` / `remove_interface_route` — Manage routes
+- `add_interface_section` / `update_interface_section` / `remove_interface_section` — Manage sections
+- `set_interface_custom_component` / `set_interface_service` / `set_interface_menu` / `set_interface_styles` / `set_interface_layout` — Configure interface settings
+
+## Configuration
 
-### Dynamic Schema Generation
-- Tool schemas are generated based on your actual content types
-- Enum values are populated from your glossary
-- Field descriptions include reference types and constraints
-- Required fields are automatically marked in schemas
-
-### Intelligent Error Handling
-- Context-aware error messages explain what went wrong and how to fix it
-- Permission errors include information about required scopes
-- Field validation errors specify exactly which fields are invalid and why
-- Network errors are handled gracefully with retry suggestions
+### Environment Variables
 
-## 🔧 Configuration
+- `QIK_ACCESS_TOKEN` — Your Qik API access token (required)
+- `QIK_API_URL` — Qik API base URL (defaults to `https://api.qik.dev`)
+- `QIK_INSTANCE` — Instance name for multi-org setups (set automatically by setup)
 
-### Environment Variables
-- `QIK_ACCESS_TOKEN` - Your Qik API access token (required)
-- `QIK_API_URL` - Qik API base URL (optional, defaults to https://api.qik.dev)
+## Troubleshooting
 
-### Advanced Configuration
-The server automatically caches glossary data for 5 minutes to improve performance while ensuring content type information stays current.
+### Server not showing up in Claude Desktop
 
-## 🚨 Troubleshooting
+**Restart Claude Desktop.** After installing or running setup, you must quit and reopen Claude Desktop for the server to appear.
 
 ### Authentication Issues
+
 ```bash
 # Check your token status
 npx @qikdev/mcp status
 
-# Reconfigure if needed
+# Update your token
+npx @qikdev/mcp update-token
+
+# Reconfigure from scratch
 npx @qikdev/mcp setup
 ```
 
-### Common Issues
-
-**"Content type 'xyz' not found"**
-- The server will list all available content types in the error message
-- Use `qik_get_glossary` to see all available types
-
-**"Field validation errors"**
-- The server provides specific information about which fields are invalid
-- Use `qik_get_content_definition` to see field requirements for a content type
+### Common Errors
 
-**"Access denied"**
-- Check that your access token has the required permissions
-- Verify you're accessing content within your permitted scopes
+- **"Content type not found"** — Use `get_glossary` to see available types
+- **"Field validation errors"** — Use `get_content_type_details` to see required fields
+- **"Access denied"** — Check that your token has the required permissions
 
-## 📚 API Reference
+## License
 
-For detailed API documentation, visit: https://docs.qik.dev/api
+MIT — see [LICENSE](LICENSE) for details.
 
-## 🤝 Contributing
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 🆘 Support
+## Support
 
 - **Documentation**: https://docs.qik.dev
 - **Issues**: https://gitlab.com/qikdevelopers/qik-mcp-server/-/issues
 - **Email**: developers@qik.dev
-
----
-
-Built with ❤️ by the Qik team