@qikdev/mcp

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

📦 Installation

npm install -g @qikdev/mcp

🔧 Setup

Quick Setup

qik-mcp-server setup

This will guide you through:

• Entering your Qik API access token
• Configuring your API URL (defaults to https://api.qik.dev)
• Automatically adding the server to your MCP configuration

Manual Setup

• Get your Qik API Access Token:

  • Log in to your Qik dashboard at https://app.qik.dev
  • Navigate to Settings → API Access
  • Generate a new access token

• Configure Environment Variables:

  export QIK_ACCESS_TOKEN="your_access_token_here"
  export QIK_API_URL="https://api.qik.dev"  # Optional, defaults to this
  

• Add to MCP Configuration: Add this to your MCP settings file:

  {
    "mcpServers": {
      "qik": {
        "command": "npx",
        "args": ["@qikdev/mcp", "run"],
        "env": {
          "NODE_ENV": "production"
        }
      }
    }
  }
  

🛠️ 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
qik-mcp-server status

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

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• 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: [e-mail]

Built with ❤️ by the Qik team