@cplace/mcp-server 1.3.14

package/dist/utils.js

@@ -0,0 +1,375 @@
+import { MAX_STRING_LENGTH, TRUNCATION_SUFFIX, MAX_RESPONSE_SIZE } from './types.js';
+import { setProperty } from 'dot-prop';
+export function transformMultiplicityToBoolean(attributes) {
+    if (!attributes || !Array.isArray(attributes)) {
+        return attributes;
+    }
+    return attributes.map((attr) => {
+        const transformed = { ...attr };
+        if (attr.multiplicity) {
+            transformed.required = attr.multiplicity === 'exactlyOne' || attr.multiplicity === 'atLeastOne';
+            transformed.multiple = attr.multiplicity === 'arbitrary' || attr.multiplicity === 'atLeastOne';
+            delete transformed.multiplicity;
+        }
+        return transformed;
+    });
+}
+export function filterTypeDefinitionResponse(typeDefinition, options) {
+    if (!typeDefinition) {
+        return typeDefinition;
+    }
+    const { responseFormat, includeScripts, attributeNames } = options;
+    let result;
+    if (responseFormat === 'schema') {
+        result = {
+            internalName: typeDefinition.internalName,
+            workspaceId: typeDefinition.workspaceId,
+            localizedNames: typeDefinition.localizedNames,
+            attributesCount: typeDefinition.attributesCount,
+            attributes: (typeDefinition.attributes || []).map((attr) => ({
+                name: attr.name,
+                localizedName: attr.localizedName,
+                multiplicity: attr.multiplicity,
+                constraint: attr.constraint ? {
+                    attributeType: attr.constraint.attributeType
+                } : undefined
+            }))
+        };
+    }
+    else if (responseFormat === 'minimal') {
+        result = {
+            internalName: typeDefinition.internalName,
+            workspaceId: typeDefinition.workspaceId,
+            localizedNames: typeDefinition.localizedNames,
+            localizedPlural: typeDefinition.localizedPlural,
+            description: typeDefinition.description,
+            iconName: typeDefinition.iconName,
+            showInExplorer: typeDefinition.showInExplorer,
+            showInGlobalSearch: typeDefinition.showInGlobalSearch,
+            namesAreUnique: typeDefinition.namesAreUnique,
+            permissions: typeDefinition.permissions,
+            attributesCount: typeDefinition.attributesCount,
+            attributes: (typeDefinition.attributes || []).map((attr) => ({
+                name: attr.name,
+                localizedName: attr.localizedName,
+                localizedShortName: attr.localizedShortName,
+                shortHelp: attr.shortHelp,
+                multiplicity: attr.multiplicity,
+                constraint: attr.constraint ? filterMinimalConstraint(attr.constraint) : undefined
+            }))
+        };
+    }
+    else {
+        result = JSON.parse(JSON.stringify(typeDefinition));
+        if (!includeScripts) {
+            if (result.attributes) {
+                result.attributes = result.attributes.map((attr) => {
+                    const filtered = { ...attr };
+                    delete filtered.lowCodeValidator;
+                    delete filtered.lowCodeEnumProvider;
+                    return filtered;
+                });
+            }
+            delete result.advanced;
+        }
+    }
+    if (attributeNames && attributeNames.length > 0 && result.attributes) {
+        const attributeSet = new Set(attributeNames);
+        result.attributes = result.attributes.filter((attr) => attributeSet.has(attr.name));
+        result.attributesCount = result.attributes.length;
+    }
+    return result;
+}
+function filterMinimalConstraint(constraint) {
+    const minimal = {
+        attributeType: constraint.attributeType
+    };
+    switch (constraint.attributeType) {
+        case 'number':
+            if (constraint.precision !== undefined)
+                minimal.precision = constraint.precision;
+            if (constraint.suffix)
+                minimal.suffix = constraint.suffix;
+            break;
+        case 'date':
+            if (constraint.specificity)
+                minimal.specificity = constraint.specificity;
+            if (constraint.withTime !== undefined)
+                minimal.withTime = constraint.withTime;
+            break;
+        case 'reference':
+            if (constraint.targetTypeNames)
+                minimal.targetTypeNames = constraint.targetTypeNames;
+            if (constraint.targetEntityKind)
+                minimal.targetEntityKind = constraint.targetEntityKind;
+            if (constraint.sameWorkspace !== undefined)
+                minimal.sameWorkspace = constraint.sameWorkspace;
+            break;
+        case 'textEnumeration':
+        case 'numberEnumeration':
+            if (constraint.element)
+                minimal.element = constraint.element;
+            break;
+        case 'dynamicEnumeration':
+            if (constraint.providerSimpleName)
+                minimal.providerSimpleName = constraint.providerSimpleName;
+            break;
+        case 'string':
+            if (constraint.pattern)
+                minimal.pattern = constraint.pattern;
+            break;
+    }
+    return minimal;
+}
+export function truncateValue(value) {
+    if (typeof value === 'string') {
+        if (value.length > MAX_STRING_LENGTH) {
+            return {
+                value: value.substring(0, MAX_STRING_LENGTH) + TRUNCATION_SUFFIX,
+                wasTruncated: true
+            };
+        }
+        return { value, wasTruncated: false };
+    }
+    else if (typeof value === 'object' && value !== null) {
+        if ('markup' in value && 'filteredText' in value) {
+            const truncated = { ...value };
+            let wasTruncated = false;
+            if (typeof value.markup === 'string' && value.markup.length > MAX_STRING_LENGTH) {
+                truncated.markup = value.markup.substring(0, MAX_STRING_LENGTH) + TRUNCATION_SUFFIX;
+                wasTruncated = true;
+            }
+            if (typeof value.filteredText === 'string' && value.filteredText.length > MAX_STRING_LENGTH) {
+                truncated.filteredText = value.filteredText.substring(0, MAX_STRING_LENGTH) + TRUNCATION_SUFFIX;
+                wasTruncated = true;
+            }
+            return { value: truncated, wasTruncated };
+        }
+        return { value, wasTruncated: false };
+    }
+    else if (Array.isArray(value)) {
+        let arrayWasTruncated = false;
+        const truncatedArray = value.map(item => {
+            const result = truncateValue(item);
+            if (result.wasTruncated) {
+                arrayWasTruncated = true;
+            }
+            return result.value;
+        });
+        return { value: truncatedArray, wasTruncated: arrayWasTruncated };
+    }
+    else {
+        return { value, wasTruncated: false };
+    }
+}
+export function truncateAttributeValues(attributes, truncate) {
+    if (!truncate || !attributes) {
+        return { attributes, truncatedAttributeNames: [] };
+    }
+    const truncatedAttributes = {};
+    const truncatedAttributeNames = [];
+    for (const [key, value] of Object.entries(attributes)) {
+        const result = truncateValue(value);
+        truncatedAttributes[key] = result.value;
+        if (result.wasTruncated) {
+            truncatedAttributeNames.push(key);
+        }
+    }
+    return { attributes: truncatedAttributes, truncatedAttributeNames };
+}
+export function filterSearchResult(resultItem, options) {
+    const { minimal, includeAttributes, includeMetadata, attributeFields, truncateLargeValues } = options;
+    if (minimal) {
+        return {
+            uid: resultItem.uid,
+            name: resultItem.name,
+            url: resultItem.url,
+            type: {
+                internalName: resultItem.type.internalName
+            },
+            workspace: {
+                name: resultItem.workspace.name
+            }
+        };
+    }
+    const filtered = {
+        uid: resultItem.uid,
+        name: resultItem.name,
+        url: resultItem.url,
+        type: {
+            internalName: resultItem.type.internalName
+        },
+        workspace: {
+            name: resultItem.workspace.name
+        }
+    };
+    if (includeAttributes && resultItem.attributes) {
+        let truncationResult;
+        if (attributeFields && attributeFields.length > 0) {
+            const filteredAttrs = {};
+            for (const field of attributeFields) {
+                if (field in resultItem.attributes) {
+                    filteredAttrs[field] = resultItem.attributes[field];
+                }
+            }
+            truncationResult = truncateAttributeValues(filteredAttrs, truncateLargeValues || false);
+        }
+        else {
+            truncationResult = truncateAttributeValues(resultItem.attributes, truncateLargeValues || false);
+        }
+        filtered.attributes = truncationResult.attributes;
+        if (truncationResult.truncatedAttributeNames.length > 0) {
+            filtered.truncatedAttributes = {
+                names: truncationResult.truncatedAttributeNames,
+                note: `Content truncated at ${MAX_STRING_LENGTH} characters. Use cplace_get_by_id({ entityType: "page", id: '${resultItem.uid}' }) to get full attribute values.`
+            };
+        }
+    }
+    if (includeMetadata) {
+        if (resultItem.parent) {
+            filtered.parent = {
+                uid: resultItem.parent.uid,
+                name: resultItem.parent.name,
+                type: resultItem.parent.type.internalName
+            };
+        }
+        if (resultItem.creator) {
+            filtered.creator = {
+                uid: resultItem.creator.uid,
+                name: resultItem.creator.name
+            };
+        }
+        if (resultItem.modifier) {
+            filtered.modifier = {
+                uid: resultItem.modifier.uid,
+                name: resultItem.modifier.name
+            };
+        }
+        if (resultItem.children && resultItem.children.length > 0) {
+            filtered.children = resultItem.children.map(child => ({
+                uid: child.uid,
+                name: child.name,
+                type: child.type.internalName
+            }));
+        }
+    }
+    return filtered;
+}
+export function checkResponseSize(response) {
+    const responseJson = JSON.stringify(response, null, 2);
+    const actualSize = responseJson.length;
+    if (actualSize > MAX_RESPONSE_SIZE) {
+        return {
+            tooLarge: true,
+            actualSize,
+            suggestion: `Response too large (${actualSize} characters, max allowed: ${MAX_RESPONSE_SIZE}). Try: reduce result count (limit parameter), use responseFormat='minimal', or use specific attributes parameter to get fewer fields.`
+        };
+    }
+    return { tooLarge: false, actualSize, suggestion: '' };
+}
+export function truncateStringForCsv(value) {
+    if (typeof value !== 'string') {
+        return value;
+    }
+    if (value.length > MAX_STRING_LENGTH) {
+        return value.substring(0, MAX_STRING_LENGTH) + TRUNCATION_SUFFIX;
+    }
+    return value;
+}
+export function truncateDocumentSummaries(documents) {
+    if (!documents || !Array.isArray(documents)) {
+        return documents;
+    }
+    const DOCUMENT_SUMMARY_LENGTH = 500;
+    return documents.map(doc => {
+        if (!doc || typeof doc !== 'object') {
+            return doc;
+        }
+        if (!doc.summary || typeof doc.summary !== 'string') {
+            return doc;
+        }
+        const originalLength = doc.summary.length;
+        if (originalLength <= DOCUMENT_SUMMARY_LENGTH) {
+            return doc;
+        }
+        return {
+            ...doc,
+            summary: doc.summary.substring(0, DOCUMENT_SUMMARY_LENGTH) + TRUNCATION_SUFFIX,
+            summaryLength: originalLength,
+            summaryShortened: true
+        };
+    });
+}
+export function flattenAttributeValue(value, prefix = '') {
+    if (value === null || value === undefined) {
+        return { [prefix]: '' };
+    }
+    else if (typeof value === 'object' && !Array.isArray(value)) {
+        const flattened = {};
+        if ('id' in value && 'name' in value) {
+            flattened[`${prefix}_id`] = value.uid || '';
+            const nameValue = value.name || '';
+            flattened[`${prefix}_name`] = truncateStringForCsv(nameValue);
+        }
+        else {
+            for (const [key, val] of Object.entries(value)) {
+                const nestedKey = prefix ? `${prefix}_${key}` : key;
+                Object.assign(flattened, flattenAttributeValue(val, nestedKey));
+            }
+        }
+        return flattened;
+    }
+    else if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return { [prefix]: '' };
+        }
+        if (value.every(item => typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean')) {
+            const truncatedItems = value.map(item => {
+                if (typeof item === 'string') {
+                    return truncateStringForCsv(item);
+                }
+                else {
+                    return String(item);
+                }
+            });
+            const joinedValue = truncatedItems.join('|');
+            return { [prefix]: truncateStringForCsv(joinedValue) };
+        }
+        else {
+            const jsonValue = JSON.stringify(value);
+            return { [prefix]: truncateStringForCsv(jsonValue) };
+        }
+    }
+    else {
+        if (typeof value === 'string') {
+            return { [prefix]: truncateStringForCsv(value) };
+        }
+        else {
+            return { [prefix]: String(value) };
+        }
+    }
+}
+export function extractAllAttributeKeys(results) {
+    const allKeys = new Set();
+    for (const result of results) {
+        const attributes = result.attributes || {};
+        for (const [key, value] of Object.entries(attributes)) {
+            const flattened = flattenAttributeValue(value, key);
+            for (const flatKey of Object.keys(flattened)) {
+                allKeys.add(flatKey);
+            }
+        }
+    }
+    return Array.from(allKeys).sort();
+}
+export function applyPathUpdates(target, updates) {
+    if (!target || typeof target !== 'object') {
+        return target;
+    }
+    const result = JSON.parse(JSON.stringify(target));
+    for (const update of updates) {
+        setProperty(result, update.path, update.value);
+    }
+    return result;
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/dist/widget-specifications/CLAUDE.md

@@ -0,0 +1,288 @@
+# Widget Specifications Guidelines
+
+This directory contains supplementary documentation for widgets that help AI correctly discover, understand, and configure widgets. These specifications follow a two-level progressive disclosure architecture.
+
+## Two-Level Architecture
+
+Each level serves a distinct purpose in the AI-assisted workflow:
+
+| Level | Purpose | Question Answered | Files |
+|-------|---------|-------------------|-------|
+| **1** | Discovery | "What widgets exist?" | `_meta.json`, `_summary.md` |
+| **2** | Definition | "How does this widget work and how do I configure it?" | `_summary.md`, `_overview.md`, `_implementation.md`, `{attribute}.md` |
+
+Level 2 (`cplace_get_widget_definition`) provides configurable depth via boolean flags:
+- **Baseline** (always): `summary` from `_summary.md`
+- **With `includeOverview: true`**: Adds `overview` from `_overview.md`
+- **With `includeDetails: true`**: Adds `implementation` from `_implementation.md` and attribute specifications
+
+**Information should not be duplicated across levels.**
+
+## File Structure
+
+```
+widget-specifications/{widgetKind}/
+├── _meta.json           → Level 1: Tag metadata
+├── _summary.md          → Level 1: Brief description
+├── _overview.md         → Level 2: Conceptual documentation
+├── _implementation.md   → With includeDetails: Widget-level implementation hints
+└── {attribute}.md       → With includeDetails: Attribute-specific configuration
+```
+
+- Directory name = exact widget kind (e.g., `cf.platform.embeddedSearchAsTable`)
+- Attribute file name = attribute short name (e.g., `search.md`, not the full attribute name)
+
+## Tool Response Mapping
+
+| Tool | Level | Returns |
+|------|-------|---------|
+| `cplace_list_widget_definitions` | 1 | API metadata + `summary` from `_summary.md`, filtered by `tags` |
+| `cplace_get_widget_definition` | 2 | Configurable via flags - see below |
+
+### `cplace_get_widget_definition` Response Depth
+
+| Flags | Returns |
+|-------|---------|
+| (none) | `widgetKind`, `localizedName`, `summary` |
+| `includeOverview: true` | Above + `overview` |
+| `includeDetails: true` | Above + `implementation`, `attributesCount`, `attributes` with per-attribute `specification` |
+| Both flags | All fields |
+
+---
+
+## Level 1: Discovery Files
+
+### `_meta.json`
+
+Tag metadata and app dependency information used for filtering widgets during discovery.
+
+```json
+{
+  "tags": ["table", "searchable", "filterable", "sortable", "selectable", "navigation"],
+  "requiredApp": "cf.cplace.cboard.main"
+}
+```
+
+**Fields:**
+- `tags`: Array of tags for categorization (see `tag-registry.json`)
+- `requiredApp`: App required for this widget to be available:
+  - `null`: Platform widget, always available
+  - `"cf.cplace.appName"`: Requires specific app to be installed
+  - Missing/undefined: Not yet documented
+
+Tags are organized by dimension (data type, display format, interaction, purpose, technical). See `tag-registry.json` for the complete list.
+
+### `_summary.md`
+
+Brief description for scanning during widget discovery. **Maximum 1-2 sentences.**
+
+**Content guidelines**:
+- What the widget displays/does (one sentence)
+- Primary use case (optional, one sentence)
+
+**Example**:
+```markdown
+Displays pages matching a search query in a sortable, filterable table format. Use for listing collections of data with support for master-detail interactions.
+```
+
+**Do NOT include**:
+- Configuration details
+- Attribute descriptions
+- Implementation workflows
+
+---
+
+## Level 2: Understanding Files
+
+### `_overview.md`
+
+Rich conceptual documentation for understanding the widget's purpose, patterns, and design considerations.
+
+**Content guidelines**:
+- When to use this widget (use cases)
+- Operating modes and their purposes
+- Design considerations and trade-offs
+- Connection patterns with other widgets
+- Common pitfalls to avoid
+- Alternative widgets to consider
+- Related patterns
+
+**Example structure**:
+```markdown
+# Widget Name
+
+**Technical ID**: `cf.platform.widgetKind`
+
+## Overview
+What this widget does and when to use it...
+
+## Operating Modes
+### Standalone Mode
+Description...
+
+### Master Mode
+Description...
+
+## Design Considerations
+### When to Use This Pattern
+Guidance...
+
+## Common Pitfalls
+- Pitfall 1...
+- Pitfall 2...
+
+## Related Patterns
+- Pattern name - brief description
+```
+
+**Do NOT include**:
+- Attribute configuration details
+- JSON format specifications
+- Step-by-step configuration workflows
+
+---
+
+## Implementation Files (with includeDetails)
+
+### `_implementation.md`
+
+Widget-level implementation hints and configuration guidance.
+
+**Content guidelines**:
+- Configuration modes and which attributes they activate
+- Attribute dependencies and conditional requirements
+- Typical configuration workflow/order
+- Technical gotchas
+
+**Example**:
+```markdown
+**Configuration Modes**:
+- `search`: Query pages via embedded search (most common)
+  - Requires: `search` attribute with cplaceJson from `cplace_search_pages`
+- `connectedTable`: Display data from another table widget
+  - Requires: `connectedTableWidgetId` pointing to the source widget
+
+**Typical Configuration Workflow**:
+1. Configure either `search` or `connectedTableWidgetId`
+2. Define visible columns via `columns` attribute
+3. Optionally configure sorting, filtering, and grouping
+```
+
+**Do NOT include**:
+- Conceptual explanations (belongs in `_overview.md`)
+- Use case descriptions (belongs in `_overview.md`)
+- Detailed attribute schemas (returned by API)
+
+### `{attribute}.md`
+
+Attribute-specific configuration documentation. Only create when the attribute requires information not available from the API response.
+
+---
+
+## Core Principle: Don't Duplicate
+
+The `cplace_get_widget_definition` MCP tool already provides:
+- Attribute names and localized names
+- Constraint types (boolean, string, textEnumeration, dynamicEnumeration, search, etc.)
+- Required/optional status
+- Enumeration values (for textEnumeration constraints)
+- Multiplicity (single/multiple)
+
+**Widget specifications should ONLY document information that the MCP tool CANNOT provide.**
+
+## When to Create Attribute Specifications
+
+Create a specification file for an attribute when:
+
+1. **Complex Value Construction** - The value requires a specific workflow to construct correctly
+   - Example: `search` attribute needs JSON from `cplace_search_pages` response
+
+2. **Non-Obvious Valid Values** - The constraint type doesn't reveal what values are actually valid
+   - Example: `dataSource` is a string but only accepts `search`, `connectedTable`, `selection`
+
+3. **Conditional Requirements** - Other attributes become required based on this attribute's value
+   - Example: When `dataSource=search`, the `search` attribute becomes required
+
+4. **JSON Format Documentation** - The attribute accepts structured JSON but the schema isn't obvious
+   - Example: `columns`, `multiSortColumns`, `filters` all need JSON format examples
+
+5. **Common Mistakes** - Users/AI frequently misuse this attribute
+   - Example: Manually constructing search JSON instead of using cplaceJson
+
+6. **Semantic Clarification** - The attribute name is misleading
+   - Example: `dataSource` sounds like it expects a type reference, but it's a mode selector
+
+## When NOT to Create Attribute Specifications
+
+Do NOT create specifications for:
+
+- Simple boolean flags with obvious semantics (e.g., `showTableHeader`, `hideNames`)
+- Attributes where the constraint fully describes valid values (e.g., `textEnumeration` with all values listed)
+- Basic string/number attributes with obvious purpose (e.g., `title`, `height`)
+- Attributes where the localized name makes the purpose clear
+
+## Attribute Specification Format
+
+Keep specifications **brief and actionable**:
+
+```markdown
+**Warning**: [One-line warning about common mistakes, if applicable]
+
+**Valid Values**: [If constraint doesn't reveal valid values]
+- `value1`: Description
+- `value2`: Description
+
+**Correct Usage**: [Brief description of correct workflow]
+
+**Workflow**: [If complex multi-step process required]
+1. Step one
+2. Step two
+3. Step three
+
+**JSON Format**: [If attribute accepts structured JSON]
+```json
+{
+  "example": "structure"
+}
+```
+
+**Note**: [Additional context, relationships to other attributes]
+```
+
+Not all sections are required. Only include what's necessary for the specific attribute.
+
+---
+
+## Examples
+
+### Good Attribute Specification (search.md)
+```markdown
+**Warning**: Do not manually construct search JSON!
+
+**Correct Usage**: Use the cplaceJson field from cplace_search_pages response
+
+**Workflow**:
+1. Call cplace_search_pages with your desired filter
+2. Take the cplaceJson field from the response
+3. Use that value for the search configuration
+```
+
+### Good Attribute Specification (dataSource.md)
+```markdown
+**Warning**: This is a mode selector, NOT a type reference!
+
+**Valid Values**:
+- `search`: Widget queries data via embedded search (use search attribute)
+- `connectedTable`: Widget uses data from a connected table widget (use tableWidgetId)
+- `selection`: Widget uses explicitly selected pages (use selection attribute)
+
+**Note**: The "required" constraints on tableWidgetId and selection are conditional - only the attribute matching your dataSource choice is actually required.
+```
+
+### Bad Specification (don't create this)
+```markdown
+**Type**: Boolean
+**Required**: Yes
+**Description**: Controls whether the table header is shown.
+```
+This duplicates information already in the MCP tool response.