{
  "markdown": "# Clappia MCP (Model Context Protocol)\n\nA Python-based MCP server that provides a comprehensive interface for interacting with the Clappia platform. This server enables programmatic management of Clappia applications, forms, submissions, and more.\n\nClappia is a no-code platform that allows businesses, operations teams, and non-developers to create custom apps—like inspection forms, approval workflows, field data collection tools, internal dashboards, and more—without writing a single line of code. It's used across industries for automating manual processes, digitizing paperwork, and improving operational efficiency. [Click here](https://www.clappia.com) to learn more.\n\n## Features\n\n-  **App Management**\n\n   -  Create new Clappia apps with customizable sections and fields\n\n   -  Retrieve detailed app definitions with field metadata\n\n-  **Submission Management**\n\n   -  Create new submissions with field data\n   -  Edit existing submissions with validation\n   -  Update submission status with optional comments\n   -  Manage submission owners with email-based assignments\n   -  Retrieve submissions with advanced filtering and pagination\n   -  Get submission aggregations for analytics with customizable dimensions\n\n-  **Field Management**\n   -  Add new fields with comprehensive configuration options\n   -  Update field properties including validation, display conditions, and layout\n   -  Configure field validations (number, email, URL, custom)\n   -  Set up conditional logic for field display and editability\n   -  Manage field layouts with responsive design options\n\n## Prerequisites\n\n-  Python 3.8 or higher\n-  uv python package manager\n-  Access to Clappia API Key and Workplace ID\n-  Claude for Desktop (or any other MCP Clients)\n\n## Installation\n\n\n1. **Set up Clappia API Access**:\n\n   -  Visit your Workplace in Clappia (https://<your_workplace>.clappia.com), you need to have Workplace Manager Access to this Workplace.\n   -  Visit Workplace Settings. Note your Workplace ID.\n   -  Visit Workplace Settings -> Preferences -> API Keys. Note your API Key, generate one if it is not yet generated.\n2. **Set up Claude for Desktop**:\n\n   -  Download Claude for Desktop for [macOS](https://claude.ai/download) or [Windows](https://claude.ai/download)\n   -  Install and launch Claude for Desktop\n   -  Open Claude menu → Settings → Developer → Edit Config\n   -  Add the following configuration to `claude_desktop_config.json`:\n      ```json\n      {\n         \"mcpServers\": {\n            \"clappia-mcp\": {\n               \"command\": \"uv\",\n               \"args\": [\n                  \"--directory\",\n                  \"/Users/<YOUR_DIECTORY>/Desktop/clappia-mcp\",\n                  \"run\",\n                  \"clappia-mcp.py\"\n               ],\n               \"env\": {\n                  \"CLAPPIA_API_KEY\": \"<ENTER_YOUR_WORKPLACE_API_KEY_HERE>\",\n                  \"CLAPPIA_WORKPLACE_ID\": \"<ENTER_YOUR_WORKPLACE_ID_HERE>\"\n               }\n            }\n         }\n      }\n      ```\n   -  Restart Claude for Desktop\n   -  Verify the MCP server is running by checking for the tools icon in the input box\n\n3. **Clone the repository**:\n\n   ```bash\n   git clone https://github.com/clappia-dev/clappia-mcp.git\n   cd clappia-mcp\n   ```\n\n4. **Set up Python Environment**:\n\n   ```bash\n   # Install uv if not already installed\n   curl -LsSf https://astral.sh/uv/install.sh | sh\n\n   # Install dependencies\n   uv sync\n   ```\n\n## Project Structure\n\n```\nclappia-mcp/\n├── clappia-mcp.py          # Main MCP server implementation\n├── tools/                  # Core functionality modules\n│   ├── add_field.py        # Field addition functionality\n│   ├── create_app.py       # App creation functionality\n│   ├── create_submission.py # Submission creation\n│   ├── edit_submission.py  # Submission editing\n│   ├── get_definition.py   # App definition retrieval\n│   ├── get_submissions.py  # Submission retrieval\n│   ├── get_submissions_aggregation.py # Analytics functionality\n│   ├── update_field.py     # Field update functionality\n│   ├── update_submission_owners.py # Owner management\n│   └── update_submission_status.py # Status management\n├── pyproject.toml         # Project metadata and dependencies\n├── uv.lock               # Dependency lock file (if using uv)\n└── .env                  # Environment variables\n```\n\n### Usage\n\n-  The server will automatically start when Claude Desktop launches\n-  Access tools through the Claude Desktop interface\n\n### Troubleshooting\n\n1. **Server Not Starting**:\n\n   -  Check Claude Desktop logs for errors\n   -  Verify Python environment is activated\n   -  Ensure all dependencies are installed\n   -  Check environment variables are set correctly\n\n2. **API Connection Issues**:\n\n   -  Verify API credentials in `claude_desktop_config.json` file\n   -  Check network connectivity\n   -  Review API rate limits\n\n3. **Tool Execution Failures**:\n   -  Check server logs for detailed error messages\n   -  Verify input parameters match API requirements\n   -  Ensure proper permissions for API operations\n\n### Example API Calls\n\n1. **Create a New Application**\n\n   ```python\n   from tools.create_app import create_app, Section, Field\n\n   result = create_app(\n       app_name=\"Employee Survey\",\n       requesting_user_email_address=\"user@company.com\",\n       sections=[\n           Section(\n               sectionName=\"Personal Information\",\n               fields=[\n                   Field(\n                       fieldType=\"singleLineText\",\n                       label=\"Full Name\",\n                       required=True\n                   )\n               ]\n           )\n       ]\n   )\n   ```\n\n2. **Add a Field to an Application**\n\n   ```python\n   from tools.add_field import add_field_to_app\n\n   result = add_field_to_app(\n       app_id=\"APP123\",\n       requesting_user_email_address=\"user@company.com\",\n       section_index=0,\n       field_index=1,\n       field_type=\"singleLineText\",\n       label=\"Employee ID\",\n       required=True,\n       validation=\"number\",\n       block_width_percentage_desktop=50,\n       block_width_percentage_mobile=100\n   )\n   ```\n\n3. **Update a Field**\n\n   ```python\n   from tools.update_field import update_field_in_app\n\n   result = update_field_in_app(\n       app_id=\"APP123\",\n       requesting_user_email_address=\"user@company.com\",\n       field_name=\"employeeName\",\n       label=\"Full Employee Name\",\n       required=True,\n       validation=\"none\",\n       display_condition=\"status == 'active'\"\n   )\n   ```\n\n4. **Create a Submission**\n\n   ```python\n   from tools.create_submission import create_app_submission\n\n   result = create_app_submission(\n       app_id=\"APP123\",\n       data={\"employeeName\": \"John Doe\", \"employeeId\": \"12345\"},\n       email=\"user@company.com\"\n   )\n   ```\n\n5. **Get Submissions with Filtering**\n\n   ```python\n   from tools.get_submissions import get_app_submissions, Filters, QueryGroup, Query, Condition\n\n   filters = Filters(queries=[\n       QueryGroup(queries=[\n           Query(\n               conditions=[\n                   Condition(\n                       operator=\"EQ\",\n                       filterKeyType=\"STANDARD\",\n                       key=\"status\",\n                       value=\"active\"\n                   )\n               ],\n               operator=\"AND\"\n           )\n       ])\n   ])\n\n   result = get_app_submissions(\n       app_id=\"APP123\",\n       requesting_user_email_address=\"user@company.com\",\n       page_size=10,\n       filters=filters\n   )\n   ```\n\n## API Documentation\n\n### Field Types\n\n-  **Text Fields**\n\n   -  `singleLineText`: Single line text input\n   -  `multiLineText`: Multi-line text input\n   -  `richTextEditor`: Rich text editor with formatting\n\n-  **Selector Fields**\n\n   -  `singleSelector`: Single choice selection\n   -  `multiSelector`: Multiple choice selection\n   -  `dropDown`: Dropdown selection\n\n-  **Date/Time Fields**\n\n   -  `dateSelector`: Date selection\n   -  `timeSelector`: Time selection\n   -  `dateTime`: Combined date and time selection\n\n-  **File Fields**\n\n   -  `file`: File upload with configurable types\n   -  `camera`: Direct camera capture\n   -  `signature`: Digital signature capture\n\n-  **Advanced Fields**\n   -  `calculationsAndLogic`: Formula-based calculations\n   -  `gpsLocation`: Location tracking\n   -  `codeScanner`: Barcode/QR code scanning\n   -  `nfcReader`: NFC tag reading\n   -  `liveTracking`: Real-time location tracking\n   -  `address`: Address input with validation\n\n### Validation Types\n\n-  `none`: No validation\n-  `number`: Numeric validation\n-  `email`: Email format validation\n-  `url`: URL format validation\n-  `custom`: Custom validation rules\n\n### Field Properties\n\n-  **Layout**\n\n   -  `block_width_percentage_desktop`: Width on desktop (25, 50, 75, 100)\n   -  `block_width_percentage_mobile`: Width on mobile (50, 100)\n   -  `number_of_cols`: Number of columns for selector fields\n\n-  **Behavior**\n\n   -  `required`: Whether field is mandatory\n   -  `is_editable`: Whether field can be edited\n   -  `hidden`: Whether field is hidden\n   -  `retain_values`: Whether to retain values when hidden\n\n-  **Conditions**\n\n   -  `display_condition`: Condition for field visibility\n   -  `editability_condition`: Condition for field editability\n\n-  **File Settings**\n   -  `allowed_file_types`: List of allowed file types\n   -  `max_file_allowed`: Maximum files allowed (1-10)\n   -  `image_quality`: Image quality (low, medium, high)\n   -  `file_name_prefix`: Prefix for uploaded files\n\n## Error Handling\n\nThe server implements comprehensive error handling for:\n\n-  Invalid API credentials\n-  Network connectivity issues\n-  Invalid input parameters\n-  API rate limiting\n-  Server errors\n\nAll errors are logged with appropriate context for debugging.\n\n## Security\n\n-  API keys are stored in environment variables\n-  All API calls are made over HTTPS\n-  Input validation is implemented for all parameters\n-  Rate limiting is supported\n-  Error messages are sanitized\n\n## Performance Considerations\n\n-  Connection pooling for API requests\n-  Efficient payload construction\n-  Proper resource cleanup\n-  Logging optimization\n-  Error handling optimization\n\n## Support\n\nFor support, please:\n\n1. Check the documentation\n2. Review existing issues\n3. Create a new issue if needed\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## API Integration\n\n### Clappia Public API\n\nThe MCP server integrates with Clappia's public API to provide the following capabilities:\n\n1. **Authentication**:\n\n   -  API key-based authentication\n   -  Secure credential management\n   -  Rate limiting support\n\n2. **Endpoints**:\n\n   -  Application management\n   -  Form submissions\n   -  Field operations\n   -  User management\n   -  Analytics and reporting\n\n3. **API Documentation**:\n\n   -  Visit [Clappia Developer Portal](https://developer.clappia.com/) for:\n      -  API reference\n      -  Authentication guide\n      -  Rate limits\n      -  Best practices\n      -  Example implementations\n\n4. **API Versioning**:\n   -  Current stable version: v1\n   -  Backward compatibility maintained\n   -  Deprecation notices provided\n",
  "bytes": 11092,
  "sha": "4a410c6d7004b32b5d8a31d6707e37d4549b3e8e4974806ecc8161b86a2bbf6f",
  "repo_slug": "clappia-dev/clappia-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_clappia_dev_clappia_mcp_c27bb696/readme"
}