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.

🚀 Key Features

Glossary-Driven Architecture

• 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
• Dynamic Tool Schema Generation: Tool schemas are generated based on your actual content types, not static definitions
• Context-Aware Error Handling: Provides specific, helpful error messages based on your content structure

Enhanced API Integration

• Comprehensive Coverage: Supports all major Qik API endpoints including content management, profiles, forms, files, and more
• Intelligent Request Building: Auto-validates field types, required fields, and constraints
• Proper Error Context: Explains permission issues and suggests fixes based on the specific operation
• Rate Limit Handling: Gracefully handles API rate limits and provides appropriate feedback

Advanced Content Management

• Field-Level Validation: Validates data types, required fields, and constraints before API calls
• Reference Validation: Understands and validates content references between different types
• Scope and Permission Awareness: Respects content scopes and user permissions
• Batch Operations: Supports efficient bulk operations where available

📦 Quick Start

Just run:

npx @qikdev/mcp setup

This interactive setup will:

1. Prompt you for your Qik API access token
2. Validate your token against the Qik API
3. Automatically configure Claude Desktop to use the MCP server

That's it! Restart Claude Desktop and you're ready to go.

🔧 Getting Your Access Token

1. Log in to your Qik dashboard at https://app.qik.dev
2. Navigate to Settings → API Access
3. Generate a new access token
4. Copy the token and paste it when prompted during setup

📋 CLI Commands

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

🛠️ Available Tools

Authentication & Session

• qik_get_user_session - Get current user session information

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

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

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

// 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

// 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

// 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

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

🔧 Configuration

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)

Advanced Configuration

The server automatically caches glossary data for 5 minutes to improve performance while ensuring content type information stays current.

🚨 Troubleshooting

Authentication Issues

# Check your token status
npx @qikdev/mcp status

# Reconfigure if needed
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

"Access denied"

• Check that your access token has the required permissions
• Verify you're accessing content within your permitted scopes

📚 API Reference

For detailed API documentation, visit: https://docs.qik.dev/api

🤝 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 file for details.

🆘 Support

• Documentation: https://docs.qik.dev
• Issues: https://gitlab.com/qikdevelopers/qik-mcp-server/-/issues
• Email: [email protected]

Built with ❤️ by the Qik team