@cplace/test-mcp-server

v1.0.0

Published

a month ago

MCP server that provides Claude Desktop with tools to interact with cplace APIs

0High
0Medium
0Low

mcp model-context-protocol cplace api claude

@cplace/mcp-server

An MCP (Model Context Protocol) server that provides Claude Desktop and Claude Code with tools to interact with cplace APIs. This server exposes cplace functionality through a comprehensive set of MCP tools for workspace management, page operations, search capabilities, layout management, type definitions, automation scripts, and version history tracking.

The server supports a profile-based tool loading system to optimize LLM context usage by only loading the tools you need.

Installation & Setup

Claude Desktop Installation

Basic Setup

By default, only the core tools are loaded. Add this entry to your Claude Desktop MCP server configuration file:

Option 1: Separate credentials (traditional)

{
  "mcpServers": {
    "cplace": {
      "command": "npx",
      "args": ["--ignore-existing", "-y", "@cplace/test-mcp-server@latest"],
      "env": {
        "CPLACE_URL": "https://your-cplace-instance.com/your-tenant",
        "API_TOKEN": "your-api-token"
      }
    }
  }
}

Option 2: URL-embedded credentials

{
  "mcpServers": {
    "cplace": {
      "command": "npx",
      "args": ["--ignore-existing", "-y", "@cplace/test-mcp-server@latest"],
      "env": {
        "CPLACE_URL": "https://[email protected]/your-tenant"
      }
    }
  }
}

Claude Code Installation

All tools (default):

Option 1: Separate credentials

claude mcp add cplace \
  --env CPLACE_URL=https://your-cplace-instance.com/your-tenant \
  --env API_TOKEN=your-api-token \
  -- npx --ignore-existing -y @cplace/test-mcp-server@latest

Option 2: URL-embedded credentials

claude mcp add cplace \
  --env CPLACE_URL=https://[email protected]/your-tenant \
  -- npx --ignore-existing -y @cplace/test-mcp-server@latest

Verify the installation:

claude mcp list

Installing a Specific Version

By default, npx installs the latest version of the MCP server. To install a specific version, add the version number to the package name:

Claude Desktop

{
  "mcpServers": {
    "cplace": {
      "command": "npx",
      "args": ["--ignore-existing", "-y", "@cplace/[email protected]"],
      "env": {
        "CPLACE_URL": "https://your-cplace-instance.com/your-tenant",
        "API_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Code

claude mcp add cplace \
  --env CPLACE_URL=https://your-cplace-instance.com/your-tenant \
  --env API_TOKEN=your-api-token \
  -- npx --ignore-existing -y @cplace/[email protected]

Note: Replace 0.1.15 with your desired version number. You can find available versions on npm.

Authentication Notes

The installation examples above show two authentication approaches:

Separate credentials: Traditional CPLACE_URL + API_TOKEN approach
URL-embedded credentials: Token embedded in the URL like https://[email protected]/tenant

Priority: If both API_TOKEN and URL-embedded credentials are provided, API_TOKEN takes precedence. This ensures backwards compatibility and allows secure credential override.

cplace Requirements

The cplace-citizen-ai repository must be part of the deployment. These plugins must be activated:

cf.cplace.citizenAi
cf.cplace.apiToken - required for authentication

Additional Configuration Properties

The following configuration properties must be set for API Token authentication to work:

cplace.plugins.cf.cplace.apiToken.enable=true - Hidden property that actually enables API Token authentication (not documented in ops configuration reference, see issue #750)
cplace.plugins.cf.cplace.apiToken.headerName=X-Cplace-Api-Token - HTTP header name for the API token (default value, should not be changed)

Usage

Obtain an API Token for your cplace system (see cplace documentation)
- Navigate to your user profile in cplace
- Click on "Action" -> "View my API Tokens"
- Create a new API Token
- Copy the token value
Configure your credentials (see Installation section above)
If Claude Desktop is running, close it
Add the MCP server configuration to Claude Desktop
Open Claude Desktop - the cplace tools should now be available

Version Compatibility

The MCP server and cplace backend must be synchronized to work correctly. Version mismatches can occur when either component is upgraded independently.

Checking Version Compatibility

Ask Claude to check version compatibility:

Check the version compatibility between the MCP server and the cplace backend

Claude will internally use the cplace_check_version_compatibility tool to perform the check.

Understanding the Results

Claude will report one of these outcomes:

✅ Compatible

Your MCP server package version matches what the backend expects. Everything is working correctly, and no action is needed.

⚠️ Version Mismatch

The versions don't match. There are two possible scenarios:

Scenario 1: MCP Server Newer Than Backend

⚠️ Version Mismatch Detected

Your MCP server package is newer than what the cplace backend currently supports:

- Your MCP server package version: 1.0.5
- Backend expects version: 1.0.2

What This Means: The cplace backend hasn't been upgraded yet to support features in your MCP server package version. This could lead to unexpected behavior or errors when using certain tools.

Resolution Options:

Option A: Downgrade MCP Server (Recommended for Local Installations)

If you're using a local MCP server installation, you can downgrade to match the backend version. Follow the instructions in the Installing a Specific Version section above to install version 1.0.2 (the version your backend expects).

Example for Claude Desktop:

{
  "mcpServers": {
    "cplace": {
      "command": "npx",
      "args": ["--ignore-existing", "-y", "@cplace/[email protected]"],
      "env": {
        "CPLACE_URL": "https://your-cplace-instance.com/your-tenant",
        "API_TOKEN": "your-api-token"
      }
    }
  }
}

After updating the configuration, close and reopen Claude Desktop, then run the version check again to confirm compatibility.

Option B: Upgrade Backend

Contact your cplace administrator to upgrade the backend deployment to the latest version.

Scenario 2: Backend Newer Than MCP Server

⚠️ Version Mismatch Detected

Your cplace backend has been upgraded and now expects a newer package version:

- Your MCP server package version: 1.0.2
- Backend expects version: 1.0.5

What This Means: The backend has been upgraded with new features that require a newer MCP server package version.

Resolution:

The MCP server will automatically upgrade to the latest version on the next restart when using @latest. If you're using a version-pinned installation (e.g., @1.0.2), update your configuration to either specify the new version or use @latest to always fetch the newest version:

Example for Claude Desktop (auto-upgrade to latest):

{
  "mcpServers": {
    "cplace": {
      "command": "npx",
      "args": ["--ignore-existing", "-y", "@cplace/test-mcp-server@latest"],
      "env": {
        "CPLACE_URL": "https://your-cplace-instance.com/your-tenant",
        "API_TOKEN": "your-api-token"
      }
    }
  }
}

Close and reopen Claude Desktop to apply the changes, then run the version check again to confirm compatibility.

Changing the cplace System

To change CPLACE_URL or API_TOKEN, update the values in the Claude Desktop configuration, then close & reopen Claude Desktop.

Profile System

The MCP server uses a profile-based tool loading system to optimize LLM context usage. By default, only the core profile is loaded if no profiles are specified, providing essential operations while keeping context usage low. You can load additional tool groups by specifying profiles via CLI arguments or by using the cplace_manage_profiles tool.

Available Tool Profiles

| Profile | Description | Tool Count | |---------|-------------|------------| | core | Essential operations | 18 tools | | workspace-admin | Workspace creation and app management | 3 tools | | history | Version history | 4 tools | | layouts | Widget and layout management | 21 tools | | types-write | Type and attribute management | 2 tools | | low-code | Validators, change listeners, workflows | 11 tools | | ppt-export | PowerPoint export | 2 tools | | csv-export | CSV export functionality | 1 tool | | schedule | Schedule analysis | 1 tool |

Token Usage by Profile

The visualization below shows the LLM context token usage for each profile. Loading multiple profiles increases the total context consumed:

┌─────────────────────────────────────────────────────────────────┐
│ LAYOUTS          20.8k ████████████████████████████████████████ │
│ CORE             17.4k ██████████████████████████████████       │
│ LOW_CODE         10.3k ████████████████                         │
│ PPT_EXPORT        5.2k ████████                                 │
│ TYPES_WRITE       3.4k █████                                    │
│ HISTORY           2.8k ████                                     │
│ WORKSPACE_ADMIN   2.3k ███                                      │
│ CSV_EXPORT        2.2k ███                                      │
│ SCHEDULE          860  █                                        │
└─────────────────────────────────────────────────────────────────┘
Total: ~65.3k tokens across all profiles

Note: The core profile is always loaded automatically. When you specify additional profiles, their token counts are added to the core profile's usage.

Profile Usage Examples

# Default - core functionality only
npx --ignore-existing -y @cplace/test-mcp-server@latest

# Dashboard development (core + layouts)
npx --ignore-existing -y @cplace/test-mcp-server@latest --profiles=layouts

# Type development (core + types-write + low-code)
npx --ignore-existing -y @cplace/test-mcp-server@latest --profiles=types-write+low-code

# Load all available profiles
npx --ignore-existing -y @cplace/test-mcp-server@latest --profiles=all

Dynamic Profile Management

You can ask Claude to manage profiles at runtime using natural language. Claude will use the cplace_manage_profiles tool to handle your requests:

Example messages:

"What profiles are currently active?"
"Show me all available profiles"
"Switch to the layouts and types-write profiles"

Note: Profile changes are saved to ~/.cplace-mcp-profiles.json but require a server reconnect to take effect. The MCP server loads tools once at startup and cannot dynamically register/unregister tools during runtime.

To reconnect in Claude Code: Use the /mcp command, then select the cplace MCP server and click Reconnect. To reconnect in Claude Desktop: Close and reopen the application.

Profile Resolution Priority

The server uses a three-tier priority system to determine which profiles are active at startup:

Stored Preferences (Highest Priority): Profiles saved via cplace_manage_profiles tool, stored in ~/.cplace-mcp-profiles.json. These are path-specific (keyed by working directory), user-specific (API token hash), and tenant-specific (URL).
CLI Argument (Medium Priority): The --profiles= argument in your MCP server configuration. Used when no stored preference exists for the current directory/user/tenant combination.
Code Default (Lowest Priority): Falls back to the "core" profile only when neither stored preferences nor CLI arguments are provided.

Special Rules:

The "core" profile is always included automatically, regardless of configuration
Profile preferences are directory-specific: /project-a can have different profiles than /project-b for the same user
The cplace_manage_profiles tool is always available

Available Profiles and Tools

Core (Always Loaded)

Essential operations including workspace navigation, page CRUD operations, search, users, and references.

Workspace Management:

cplace_list_workspaces - Get all workspaces with essential properties
cplace_get_workspace_details - Get comprehensive details about a specific workspace including all metadata, permissions, type definitions, styling, and configuration
cplace_list_types - List all types available in a workspace
cplace_get_type_datamodel - Get the datamodel of a type including its attributes, constraints, and permissions

Page Operations:

cplace_get_by_uid - Get entity (page or person) by UID with full details
cplace_manage_page - Create or update a page with attributes and content
cplace_delete_page - Permanently delete a single page (leaf pages only)
cplace_delete_page_with_children - Permanently delete a page and optionally all its children
cplace_copy_page - Copy a page with optional children to a new location

Search:

cplace_search_pages - Search pages of a type in cplace with advanced filtering
cplace_search_pages_fulltext - Make a fulltext search across all pages in cplace
cplace_list_pages_of_type - List all pages of a specific type in a workspace

Users & References:

cplace_get_person_by_name - Get details about a person by searching for their name
cplace_get_current_user - Get information about the currently logged-in user
cplace_get_incoming_references - Get incoming references for pages or types

Utilities:

cplace_get_icon_names - Get all available icon names in the cplace system (FontAwesome, cplace custom, HUI utility icons)
cplace_check_version_compatibility - Check version compatibility between the MCP server and the cplace backend API

Profile Management:

cplace_manage_profiles - Dynamically manage active profiles

Workspace Admin (Profile: workspace-admin)

Workspace creation and app management.

cplace_create_workspace - Create a new workspace with specified configuration including name, permissions, and apps
cplace_list_workspace_apps - Get comprehensive information about applications within a workspace, including installed apps, available apps for installation, dependency information, and compatibility status
cplace_install_workspace_app - Install a specific application into a workspace, including automatic dependency resolution

Layouts (Profile: layouts)

Widget and dashboard layout management, plus richstring widget operations.

cplace_list_widget_definitions - Get a list of all available widget definitions with their metadata
cplace_get_widget_definition - Get detailed information about a specific widget definition including its configuration schema
cplace_get_widget_details - Get detailed configuration for a specific widget within a page layout
cplace_add_widget_to_layout - Add a new widget to a page layout at a specific position
cplace_remove_widget_from_layout - Remove an existing widget from a page layout
cplace_update_widget_in_layout - Modify widget configuration or display properties
cplace_move_widget_in_layout - Relocate a widget to a different position in the layout
cplace_get_embedded_layout - Get the widget layout structure of an embedded widget within a container widget
cplace_add_widget_to_embedded_layout - Add a new widget to an embedded layout within a container widget
cplace_remove_widget_from_embedded_layout - Remove an existing widget from an embedded layout within a container widget
cplace_get_type_layout - Get widget layout structure of a specific type definition (default or alternative layout)
cplace_list_type_alternative_layouts - List all available layouts for a type with usage statistics (default + alternatives)
cplace_create_type_alternative_layout - Create a new alternative layout for a specific type definition
cplace_layout_get_overview - Get layout structure for page or type (unified interface)
cplace_layout_add_widget - Add widget to page or type layout (unified interface)
cplace_layout_remove_widget - Remove widget from page or type layout (unified interface)
cplace_layout_add_row - Add row structure to page or type layout (unified interface)
cplace_layout_get_widget_details - Get detailed widget configuration from page or type layout (unified interface)
cplace_layout_update_widget - Update widget configuration or collapse state in page or type layout (unified interface)
cplace_layout_move_widget - Move widget to different position in page or type layout (unified interface)
cplace_layout_compact - Remove empty rows from page or type layout (unified interface)
cplace_richstring_extract_widgets - Extract all embedded widgets from a richstring attribute value
cplace_richstring_insert_widget - Insert a widget into a richstring attribute at a specific position
cplace_richstring_update_widget - Update an existing widget configuration within a richstring attribute
cplace_richstring_delete_widget - Delete a widget from a richstring attribute

Type and Attribute Definition (Profile: types-write)

Type and attribute creation and updates.

cplace_manage_type_definition - Create or update type definitions in a workspace with comprehensive configuration options
cplace_manage_attribute_definition - Create or update attribute definitions within existing type definitions

Low-Code (Profile: low-code)

Validators, change listeners, workflow state machines, workflow scripts, and script logging.

cplace_get_validator_by_attribute - Get JavaScript validator script and metadata for a specific attribute
cplace_manage_validator - Create or update JavaScript validators for attribute definitions
cplace_get_change_listeners_by_type - Get all JavaScript automation scripts (change listeners) for a type
cplace_manage_change_listener - Create or update JavaScript automation scripts that execute when specified attributes change
cplace_manage_workflow_state - Create or update workflow states for type definitions with comprehensive configuration
cplace_delete_workflow_state - Delete a workflow state from a type definition
cplace_manage_workflow_transition - Create or update workflow transitions between states with validation and JavaScript actions
cplace_delete_workflow_transition - Delete a workflow transition from a type definition
cplace_get_workflow_script - Get the JavaScript script associated with a workflow state or transition
cplace_manage_workflow_script - Create or update JavaScript scripts for workflow states or transitions
cplace_get_script_logs - Retrieve filtered and paginated script execution logs for debugging and monitoring low-code scripts

PPT Export (Profile: ppt-export)

PowerPoint export profiles.

cplace_create_ppt_export_profile - Create PowerPoint Export Profiles with comprehensive configuration for page layout, timeline settings, task classes, and visual formatting
cplace_partial_update_ppt_export_profile - Update existing PowerPoint Export Profiles using path-based granular updates

History (Profile: history)

Version history and change tracking.

cplace_get_page_changesets - Get all changesets (modification records) for a specific page within an optional time range
cplace_get_page_state_at_timestamp - Reconstruct and return the complete state of a page as it was at a specific point in time
cplace_get_page_diff - Compare page states between two timestamps and return the differences
cplace_get_page_changesets_summary - Get a summary of recent changes for a page (convenience tool for last 7 days by default)

CSV Export (Profile: csv-export)

CSV export functionality for search results.

cplace_search_pages_csv - Export search results to CSV format

Schedule (Profile: schedule)

Schedule analysis and cross-schedule dependencies.

cplace_get_schedule_links - Get schedule dependencies and links between work packages

Development

For development setup, contribution guidelines, and extending the server, see DEVELOPMENT.md.