@cplace/mcp-server 2.1.0 → 2.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +6 -4
  2. package/dist/api.d.ts.map +1 -1
  3. package/dist/api.js +0 -1
  4. package/dist/api.js.map +1 -1
  5. package/dist/backend-capabilities.d.ts +1 -1
  6. package/dist/backend-capabilities.d.ts.map +1 -1
  7. package/dist/backend-capabilities.js +5 -2
  8. package/dist/backend-capabilities.js.map +1 -1
  9. package/dist/capability-gating.d.ts +4 -0
  10. package/dist/capability-gating.d.ts.map +1 -1
  11. package/dist/capability-gating.js +28 -9
  12. package/dist/capability-gating.js.map +1 -1
  13. package/dist/index.js +8 -2
  14. package/dist/index.js.map +1 -1
  15. package/dist/local-mode.d.ts +3 -0
  16. package/dist/local-mode.d.ts.map +1 -0
  17. package/dist/local-mode.js +8 -0
  18. package/dist/local-mode.js.map +1 -0
  19. package/dist/logger.d.ts +1 -0
  20. package/dist/logger.d.ts.map +1 -1
  21. package/dist/logger.js +5 -1
  22. package/dist/logger.js.map +1 -1
  23. package/dist/plugins/core/app-catalog/README.md +4 -1
  24. package/dist/plugins/core/app-catalog/cf.cplace.lowCodeWidgetBuilder/README.md +117 -0
  25. package/dist/plugins/core/app-catalog/cf.cplace.lowCodeWidgetRenderer/README.md +37 -0
  26. package/dist/plugins/core/app-catalog/cf.cplace.lowcode.ai/README.md +62 -9
  27. package/dist/plugins/core/widget-specifications/cf.cplace.workflow.widget/_meta.json +1 -1
  28. package/dist/plugins/resource-management/app-catalog/cf.cplace.resourceManagement/README.md +42 -30
  29. package/dist/plugins/resource-management/app-catalog/cf.cplace.resourceManagement.predefinedValueTypes/README.md +67 -0
  30. package/dist/tools/documents.d.ts.map +1 -1
  31. package/dist/tools/documents.js +77 -14
  32. package/dist/tools/documents.js.map +1 -1
  33. package/dist/tools/system.js +2 -2
  34. package/dist/tools/system.js.map +1 -1
  35. package/dist/utils/fileIO.d.ts +3 -0
  36. package/dist/utils/fileIO.d.ts.map +1 -1
  37. package/dist/utils/fileIO.js +14 -0
  38. package/dist/utils/fileIO.js.map +1 -1
  39. package/package.json +2 -2
@@ -0,0 +1,117 @@
1
+ # AI Widget Studio (cf.cplace.lowCodeWidgetBuilder)
2
+
3
+ ## Overview
4
+
5
+ AI Widget Studio builds custom widgets with HTML, CSS, JavaScript and a cplaceJS data script. Each widget is a
6
+ *Widget Definition* page in the workspace: its code lives in attributes, edited in a draft and published to the
7
+ live copy. The Studio's own widgets (code editor, preview, publish) are placed on the Widget Definition layouts.
8
+
9
+ Embedding a widget on another page needs the Embedded Widget, which comes from the separate
10
+ **AI Widget Studio Renderer** app (`cf.cplace.lowCodeWidgetRenderer`). A workspace that both defines and shows
11
+ widgets needs both apps; neither installs the other.
12
+
13
+ **Plugin:** `cf.cplace.lowCodeWidgetBuilder`
14
+
15
+ **Repository:** `cplace-lowcode-widget-builder`
16
+
17
+ ## Dependencies
18
+
19
+ - `cf.cplace.platform` (cplace Basis) — always pre-installed
20
+
21
+ No additional apps are auto-installed with this app.
22
+
23
+ ## Types Provided
24
+
25
+ Creating or editing a page of these types needs the client-JavaScript permission.
26
+
27
+ ### cf.cplace.lowCodeWidget.widgetDefinition (Widget Definition)
28
+
29
+ One custom widget: the live code, its draft, and the revision counter.
30
+
31
+ | Attribute | Internal Name | Type | Required | Description |
32
+ |-----------|---------------|------|----------|-------------|
33
+ | HTML Code | `cf.cplace.lowCodeWidget.htmlCode` | Text | No | Published HTML (read-only, written by publish) |
34
+ | CSS Code | `cf.cplace.lowCodeWidget.cssCode` | Text | No | Published CSS (read-only) |
35
+ | JavaScript Code | `cf.cplace.lowCodeWidget.jsCode` | Text | No | Published client JavaScript (read-only) |
36
+ | Widget Name | `cf.cplace.lowCodeWidget.widgetName` | Text | No | Display name of the widget |
37
+ | Description | `cf.cplace.lowCodeWidget.description` | Text | No | What the widget does |
38
+ | cplaceJS Script | `cf.cplace.lowCodeWidget.script` | Script | No | Published server-side data and action script (read-only) |
39
+ | Messages | `cf.cplace.lowCodeWidget.messages` | Text | No | Published localized messages as JSON (read-only) |
40
+ | Search | `cf.cplace.lowCodeWidget.search` | Search | No | Search the widget's data script can use |
41
+ | Draft HTML Code | `cf.cplace.lowCodeWidget.draftHtmlCode` | Text | No | Draft HTML, written by the code editor |
42
+ | Draft CSS Code | `cf.cplace.lowCodeWidget.draftCssCode` | Text | No | Draft CSS |
43
+ | Draft JavaScript Code | `cf.cplace.lowCodeWidget.draftJsCode` | Text | No | Draft client JavaScript |
44
+ | Draft cplaceJS Script | `cf.cplace.lowCodeWidget.draftScript` | Script | No | Draft data and action script |
45
+ | Draft Messages | `cf.cplace.lowCodeWidget.draftMessages` | Text | No | Draft localized messages |
46
+ | Revision Counter | `cf.cplace.lowCodeWidget.revisionCounter` | Number | No | Counter for revision version numbers (read-only) |
47
+
48
+ **Icon:** `cf-widget`
49
+
50
+ ---
51
+
52
+ ### cf.cplace.lowCodeWidget.asset (Widget Assets)
53
+
54
+ Files belonging to one widget definition, served to its client code.
55
+
56
+ | Attribute | Internal Name | Type | Required | Description |
57
+ |-----------|---------------|------|----------|-------------|
58
+ | Widget Definition | `cf.cplace.lowCodeWidget.widgetDefinition` | Reference (to Widget Definition, hierarchy) | Yes | The widget the assets belong to |
59
+ | Workspace-level Asset | `cf.cplace.lowCodeWidget.refWlAsset` | Document reference (multiple) | No | Shared assets from a Workspace-level Assets page |
60
+
61
+ **Icon:** `fa-file-code`
62
+
63
+ ---
64
+
65
+ ### cf.cplace.lowCodeWidget.wlAsset (Workspace-level Assets)
66
+
67
+ Files shared by several widgets of the workspace. The type has no attributes; the page's files are the assets.
68
+
69
+ **Icon:** `fa-file-code`
70
+
71
+ ---
72
+
73
+ ### cf.cplace.lowCodeWidget.revision (Revision)
74
+
75
+ One approved, restored or scanned state of a widget definition, with a snapshot of its code.
76
+
77
+ | Attribute | Internal Name | Type | Required | Description |
78
+ |-----------|---------------|------|----------|-------------|
79
+ | Widget Definition | `cf.cplace.lowCodeWidget.parentWidget` | Reference (to Widget Definition, hierarchy) | Yes | The widget the revision belongs to |
80
+ | Version | `cf.cplace.lowCodeWidget.versionNumber` | Number | No | Revision version number |
81
+ | Action | `cf.cplace.lowCodeWidget.action` | Enumeration | Yes | `approved`, `restored` or `scanned` |
82
+ | Performed By | `cf.cplace.lowCodeWidget.performedBy` | Person reference | Yes | Who performed the action |
83
+ | Performed At | `cf.cplace.lowCodeWidget.performedAt` | Date | Yes | When the action was performed |
84
+ | Security Scan Result | `cf.cplace.lowCodeWidget.securityScanResult` | Rich text | No | Result of the security scan |
85
+ | HTML Snapshot | `cf.cplace.lowCodeWidget.snapshotHtml` | Text | No | HTML frozen at approval |
86
+ | CSS Snapshot | `cf.cplace.lowCodeWidget.snapshotCss` | Text | No | CSS frozen at approval |
87
+ | JS Snapshot | `cf.cplace.lowCodeWidget.snapshotJs` | Text | No | Client JavaScript frozen at approval |
88
+ | Script Snapshot | `cf.cplace.lowCodeWidget.snapshotScript` | Text | No | cplaceJS script frozen at approval |
89
+ | Messages Snapshot | `cf.cplace.lowCodeWidget.snapshotMessages` | Text | No | Messages frozen at approval |
90
+
91
+ **Icon:** `fa-history`
92
+
93
+ ## Widgets Provided
94
+
95
+ | Widget | Widget Kind | Description | Use Case |
96
+ |--------|-------------|-------------|----------|
97
+ | Code Editor | `cf.cplace.lowCodeWidgetBuilder.codeEditor` | Edits one draft code attribute of a Widget Definition | Widget Definition draft layout |
98
+ | Preview | `cf.cplace.lowCodeWidgetBuilder.preview` | Renders the widget from its draft or live code | Widget Definition layouts |
99
+ | Publish | `cf.cplace.lowCodeWidgetBuilder.approveWidget` | Publishes the draft to the live code and records a Revision | Widget Definition draft layout |
100
+
101
+ The widget that shows a published widget on other pages, `cf.cplace.lowCodeWidgetBuilder.embeddedWidget`, belongs
102
+ to the AI Widget Studio Renderer app.
103
+
104
+ ## Usage Notes
105
+
106
+ - **Install with the Renderer.** A workspace that defines widgets and embeds them needs both
107
+ `cf.cplace.lowCodeWidgetBuilder` and `cf.cplace.lowCodeWidgetRenderer`. A workspace that only shows widgets
108
+ defined elsewhere needs the Renderer alone.
109
+ - **Draft and live.** Editors write the draft attributes; the Publish widget copies them to the live ones. The live
110
+ attributes are read-only.
111
+
112
+ ## Investigation Details
113
+
114
+ - **Source:** the `cplace-lowcode-widget-builder` source — `LowCodeWidgetBuilderApp.java` (qualified name, no
115
+ required apps), `LowCodeWidgetBuilderAppTypes.java` (types and attributes), `messages_en.properties` (labels),
116
+ `widgets/WidgetBuilderWidgetTypes.java` (widget kinds).
117
+ - **Live workspace investigation:** Not run.
@@ -0,0 +1,37 @@
1
+ # AI Widget Studio Renderer (cf.cplace.lowCodeWidgetRenderer)
2
+
3
+ ## Overview
4
+
5
+ Displays widgets built with AI Widget Studio, without the full builder (editor, preview, custom types). It holds
6
+ only the Embedded Widget, which renders a published Widget Definition on any page.
7
+
8
+ **Plugin:** `cf.cplace.lowCodeWidgetBuilder`
9
+
10
+ **Repository:** `cplace-lowcode-widget-builder`
11
+
12
+ ## Dependencies
13
+
14
+ - `cf.cplace.platform` (cplace Basis) — always pre-installed
15
+
16
+ No additional apps are auto-installed with this app. It does not install AI Widget Studio, and AI Widget
17
+ Studio does not install it.
18
+
19
+ ## Types Provided
20
+
21
+ **None** — this app provides no types. The Widget Definition type comes from AI Widget Studio.
22
+
23
+ ## Widgets Provided
24
+
25
+ | Widget | Widget Kind | Description | Use Case |
26
+ |--------|-------------|-------------|----------|
27
+ | Embedded Widget | `cf.cplace.lowCodeWidgetBuilder.embeddedWidget` | Renders a published Widget Definition on the page it is placed on | Every page that shows a custom widget |
28
+
29
+ ## Usage Notes
30
+
31
+ - A workspace that also defines widgets needs AI Widget Studio installed as well.
32
+
33
+ ## Investigation Details
34
+
35
+ - **Source:** the `cplace-lowcode-widget-builder` source — `LowCodeWidgetRendererApp.java` (qualified name, no
36
+ types, no required apps), `widgets/EmbeddedWidgetDefinition.java` (`getApp()`), `messages_en.properties` (title).
37
+ - **Live workspace investigation:** Not run.
@@ -14,22 +14,73 @@ widgets build on.
14
14
 
15
15
  ## Dependencies
16
16
 
17
- - `cf.cplace.platform` (cplace Basis) — always pre-installed
17
+ When this app is installed, the following apps are automatically installed:
18
18
 
19
- > Dependencies were not confirmed via a live workspace investigation; only the always-present platform base is listed.
19
+ | App | Qualified Name | Description |
20
+ |-----|----------------|-------------|
21
+ | Attribute Dependencies | `cf.cplace.attributeDependencies` | Required in the same workspace; hides tool-parameter fields by parameter type (`AiApp.getRequiredAppsInSameSpace`) |
22
+ | cplace Basis | `cf.cplace.platform` | Base platform (always installed) |
20
23
 
21
24
  ## Types Provided
22
25
 
23
- Not observed. This README was authored from existing in-repo widget specifications without a live-workspace
24
- investigation, so no type definitions were confirmed for this app. Citizen AI is used primarily through the widgets
25
- listed below. Run the standard investigation (see `INVESTIGATION-PROMPT.md`) to populate types if needed.
26
+ ### cf.cplace.lowcode.ai.assistantConfiguration (Citizen AI Assistant Configuration)
27
+
28
+ Configures one AI assistant: its instructions, model, tools and knowledge sources. The type keeps the
29
+ pre-rename prefix `cf.cplace.lowcode.ai`; attributes added later use `cf.cplace.citizenAi`.
30
+
31
+ | Attribute | Internal Name | Type | Required | Description |
32
+ |-----------|---------------|------|----------|-------------|
33
+ | Instructions | `cf.cplace.lowcode.ai.systemMessage` | Script (Markdown) | Yes | System message given to the model |
34
+ | Model | `cf.cplace.lowcode.ai.modelId` | Text (dynamic enumeration) | Yes | One of the chat models configured for the tenant |
35
+ | Temperature | `cf.cplace.lowcode.ai.temperature` | Number | Yes | Sampling temperature, with a default value |
36
+ | Seed | `cf.cplace.lowcode.ai.seed` | Number | No | Seed for reproducible answers |
37
+ | Max. Tokens | `cf.cplace.lowcode.ai.maxTokens` | Number | No | Upper bound for the answer length |
38
+ | Custom Tools | `cf.cplace.citizenAi.tools` | Reference (multiple, to Tool) | No | No-code tools the assistant may call |
39
+ | Platform Tools | `cf.cplace.citizenAi.platformTools` | Text (dynamic enumeration, multiple) | No | Built-in platform tools the assistant may call |
40
+ | Available in AI Companion | `cf.cplace.citizenAi.availableInAiCompanion` | Boolean | No | Offer the assistant in the AI Companion (default false) |
41
+ | Default in AI Companion | `cf.cplace.citizenAi.defaultInAiCompanion` | Boolean | No | Preselect the assistant in the AI Companion (default false) |
42
+ | Icon | `cf.cplace.citizenAi.companionIcon` | Icon | No | Icon shown in the AI Companion |
43
+ | Contextual Knowledge Sources | `cf.cplace.citizenAi.ragDataSources` | Text (dynamic enumeration, multiple) | No | Knowledge sources searched for context |
44
+
45
+ **Icon:** `fa-robot`
46
+
47
+ ---
48
+
49
+ ### cf.cplace.citizenAi.noCodeTool (Tool)
50
+
51
+ A scripted tool an assistant can call. Only users with Low-Code permission may create one or edit its script.
52
+
53
+ | Attribute | Internal Name | Type | Required | Description |
54
+ |-----------|---------------|------|----------|-------------|
55
+ | Tool Name | `cf.cplace.citizenAi.name` | Text | Yes | Name the model calls the tool by (`[a-zA-Z0-9-_]+`) |
56
+ | Description | `cf.cplace.citizenAi.description` | Long text | No | What the tool does, read by the model |
57
+ | Parameters | `cf.cplace.citizenAi.parameters` | Reference (multiple, to Tool Parameter) | No | The tool's parameters |
58
+ | Script | `cf.cplace.citizenAi.script` | Script | Yes | cplaceJS executed when the tool is called |
59
+
60
+ **Icon:** `fa-tools`
61
+
62
+ ---
63
+
64
+ ### cf.cplace.citizenAi.toolParameter (Tool Parameter)
65
+
66
+ One parameter of a Tool.
67
+
68
+ | Attribute | Internal Name | Type | Required | Description |
69
+ |-----------|---------------|------|----------|-------------|
70
+ | Parameter Name | `cf.cplace.citizenAi.name` | Text | Yes | Name of the parameter (`[a-zA-Z0-9-_]+`) |
71
+ | Description | `cf.cplace.citizenAi.description` | Long text | No | What the parameter means, read by the model |
72
+ | Type | `cf.cplace.citizenAi.type` | Enumeration | Yes | Parameter type |
73
+ | Required | `cf.cplace.citizenAi.required` | Boolean | No | Whether the model must pass it (default true) |
74
+ | Allowed Values | `cf.cplace.citizenAi.allowedValues` | Text (multiple) | No | Allowed values; hidden for Boolean parameters |
75
+
76
+ **Icon:** `fa-hashtag`
26
77
 
27
78
  ## Widgets Provided
28
79
 
29
80
  | Widget | Widget Kind | Description | Use Case |
30
81
  |--------|-------------|-------------|----------|
31
82
  | Ask Your Page | `cf.cplace.citizenAi.askYourPageWidget` | Zero-configuration, read-only AI assistant that understands the current page's attributes, relationships, and attached files and answers natural-language questions with links to related pages. Maintains per-user conversation history per page. | Exploring information-rich or highly-connected pages; documentation and knowledge Q&A; relationship navigation. |
32
- | Citizen AI Streaming Chat | *(widget kind not documented)* | The recommended AI chat widget for new use cases; replacement for the deprecated Chat Widget. Detail is not yet documented in this repo (no widget specification available). | New AI chat use cases — use in place of the deprecated Chat Widget. |
83
+ | Citizen AI Streaming Chat | `cf.cplace.citizenAi.streamingChatWidget` | The recommended AI chat widget for new use cases; replacement for the deprecated Chat Widget. Answers with the assistant configuration it is set to. | New AI chat use cases — use in place of the deprecated Chat Widget. |
33
84
  | Chat Widget (deprecated) | `cf.cplace.lowcode.ai.chatWidget` | **Deprecated** — use Citizen AI Streaming Chat instead. A script-based (CplaceJS `checkAccess()` / `call()`) chat interface supporting custom data sources, custom tools, configurable memory, and shared or per-user history. Will be removed in a future version. | Legacy custom AI assistants; new work should use Citizen AI Streaming Chat. |
34
85
 
35
86
  ## Use Cases
@@ -56,8 +107,10 @@ listed below. Run the standard investigation (see `INVESTIGATION-PROMPT.md`) to
56
107
 
57
108
  ## Investigation Details
58
109
 
59
- - **Source:** Authored from in-repo widget specifications
110
+ - **Source:** Widgets from the in-repo widget specifications
60
111
  (`src/plugins/core/widget-specifications/cf.cplace.lowcode.ai.chatWidget/`,
61
112
  `.../cf.cplace.citizenAi.askYourPageWidget/`) and `_catalog-data.json`.
62
- - **Live workspace investigation:** Not run. Types were not observed; the "Citizen AI Streaming Chat" widget has no
63
- widget specification in the repo yet and is documented by name/role only.
113
+ - **Types and dependencies:** from the `cplace-citizen-ai` source — `AiAppTypes.java` (types, attributes,
114
+ labels from `messages_en.properties`), `AiApp.java` (`getRequiredAppsInSameSpace`), and
115
+ `StreamingChatWidgetDefinition.java` (the Streaming Chat widget kind).
116
+ - **Live workspace investigation:** Not run.
@@ -5,5 +5,5 @@
5
5
  "detail-view",
6
6
  "workflow"
7
7
  ],
8
- "requiredApp": "cf.cplace.workflow"
8
+ "requiredApp": null
9
9
  }
@@ -21,51 +21,56 @@ The Resource Management app enables configuration and planning of resources acro
21
21
 
22
22
  ## Types Provided
23
23
 
24
- ### cf.cplace.resourceManagement.resourceTypeConfiguration
24
+ The attribute internal names carry the prefix `cf.cplace.resourceManagement.`; labels are the English ones
25
+ from `messages_en.properties`.
26
+
27
+ ### cf.cplace.resourceManagement.resourceTypeConfiguration (Resource Type Configuration)
25
28
 
26
29
  Configures which types in the workspace should be treated as **resources** (e.g., Person, Team, Machine).
27
30
 
28
- | Attribute | Type | Required | Description |
29
- |-----------|------|----------|-------------|
30
- | `cf.cplace.resourceManagement.type` | Type Reference | Yes | The type to be used as a resource |
31
- | `cf.cplace.resourceManagement.capacityAttribute` | Attribute Reference | No | Attribute defining the capacity of the resource |
32
- | `cf.cplace.resourceManagement.actualAttribute` | Attribute Reference | No | Attribute defining the actual/used value |
33
- | `cf.cplace.resourceManagement.responsibleAttribute` | Attribute Reference | No | Attribute defining responsible person(s) |
34
- | `cf.cplace.resourceManagement.userReferenceAttribute` | Attribute Reference | No | Attribute for displaying user profile picture |
35
- | `cf.cplace.resourceManagement.icon` | Text/Icon | No | Icon displayed in Resource Planner widget |
31
+ | Attribute | Internal Name | Type | Required | Description |
32
+ |-----------|---------------|------|----------|-------------|
33
+ | Resource Type | `cf.cplace.resourceManagement.type` | Text (type name, dynamic enumeration) | Yes | The type to be used as a resource |
34
+ | Capacity Attribute | `cf.cplace.resourceManagement.capacityAttribute` | Text (attribute name, dynamic enumeration) | No | Attribute defining the capacity of the resource |
35
+ | Actual Attribute | `cf.cplace.resourceManagement.actualAttribute` | Text (attribute name, dynamic enumeration) | No | Attribute defining the actual/used value |
36
+ | Responsible Attribute | `cf.cplace.resourceManagement.responsibleAttribute` | Text (attribute name, dynamic enumeration) | No | Attribute defining responsible person(s) |
37
+ | User Reference Attribute | `cf.cplace.resourceManagement.userReferenceAttribute` | Text (attribute name, dynamic enumeration) | No | Attribute for displaying user profile picture |
38
+ | Icon | `cf.cplace.resourceManagement.icon` | Icon | No | Icon displayed in Resource Planner widget |
36
39
 
37
- ### cf.cplace.resourceManagement.planningItemTypeConfiguration
40
+ ### cf.cplace.resourceManagement.planningItemTypeConfiguration (Planning Item Type Configuration)
38
41
 
39
42
  Configures which types in the workspace should be treated as **planning items** (e.g., Task, Project, Work Package).
40
43
 
41
- | Attribute | Type | Required | Description |
42
- |-----------|------|----------|-------------|
43
- | `cf.cplace.resourceManagement.type` | Type Reference | Yes | The type to be used as a planning item |
44
- | `cf.cplace.resourceManagement.demandAttribute` | Attribute Reference | No | Attribute defining the demand/need |
45
- | `cf.cplace.resourceManagement.actualAttribute` | Attribute Reference | No | Attribute defining the actual value |
46
- | `cf.cplace.resourceManagement.icon` | Text/Icon | No | Icon displayed in Resource Planner widget |
44
+ | Attribute | Internal Name | Type | Required | Description |
45
+ |-----------|---------------|------|----------|-------------|
46
+ | Planning Item Type | `cf.cplace.resourceManagement.type` | Text (type name, dynamic enumeration) | Yes | The type to be used as a planning item |
47
+ | Demand Attribute | `cf.cplace.resourceManagement.demandAttribute` | Text (attribute name, dynamic enumeration) | No | Attribute defining the demand/need |
48
+ | Actual Attribute | `cf.cplace.resourceManagement.actualAttribute` | Text (attribute name, dynamic enumeration) | No | Attribute defining the actual value |
49
+ | Icon | `cf.cplace.resourceManagement.icon` | Icon | No | Icon displayed in Resource Planner widget |
47
50
 
48
- ### cf.cplace.resourceManagement.valueTypeConfiguration
51
+ ### cf.cplace.resourceManagement.valueTypeConfiguration (Value Type Configuration)
49
52
 
50
53
  Configures which types represent **allocation values** that connect resources to planning items.
51
54
 
52
- | Attribute | Type | Required | Description |
53
- |-----------|------|----------|-------------|
54
- | `cf.cplace.resourceManagement.type` | Type Reference | Yes | The type to be used as a value type |
55
- | `cf.cplace.resourceManagement.resourceAttribute` | Attribute Reference | No | Attribute linking to the resource |
56
- | `cf.cplace.resourceManagement.planningItemAttribute` | Attribute Reference | No | Attribute linking to the planning item |
57
- | `cf.cplace.resourceManagement.icon` | Text/Icon | No | Icon displayed in Resource Management widgets |
55
+ | Attribute | Internal Name | Type | Required | Description |
56
+ |-----------|---------------|------|----------|-------------|
57
+ | Value Type | `cf.cplace.resourceManagement.type` | Text (type name, dynamic enumeration) | Yes | The type to be used as a value type |
58
+ | Attribute for Resource | `cf.cplace.resourceManagement.resourceAttribute` | Text (attribute name, dynamic enumeration) | No | Attribute linking to the resource |
59
+ | Attribute for Planning Item | `cf.cplace.resourceManagement.planningItemAttribute` | Text (attribute name, dynamic enumeration) | No | Attribute linking to the planning item |
60
+ | Requested Demand | `cf.cplace.resourceManagement.requestedDemandAttribute` | Time-bounded value mapping | No | Attribute holding the requested demand of the value type |
61
+ | Allocation | `cf.cplace.resourceManagement.allocationAttribute` | Time-bounded value mapping | No | Attribute holding the allocation of the value type |
62
+ | Icon | `cf.cplace.resourceManagement.icon` | Icon | No | Icon displayed in Resource Management widgets |
58
63
 
59
- ### cf.cplace.resourceManagement.tooltip
64
+ ### cf.cplace.resourceManagement.tooltip (Tooltip)
60
65
 
61
66
  Configures custom tooltips for the Resource Planner widget.
62
67
 
63
- | Attribute | Type | Required | Description |
64
- |-----------|------|----------|-------------|
65
- | `cf.cplace.resourceManagement.isActive` | Boolean | Yes | Whether this tooltip is active |
66
- | `cf.cplace.resourceManagement.isDefault` | Boolean | Yes | Whether this is the default tooltip for all types |
67
- | `cf.cplace.resourceManagement.referencedTypes` | Type Reference | No | Specific types this tooltip applies to (multi-value) |
68
- | `cf.cplace.resourceManagement.script` | Text/Script | No | cplaceJS script to generate custom tooltip content |
68
+ | Attribute | Internal Name | Type | Required | Description |
69
+ |-----------|---------------|------|----------|-------------|
70
+ | Activated | `cf.cplace.resourceManagement.isActive` | Boolean | No | Whether this tooltip is active (default false) |
71
+ | Default Tooltip | `cf.cplace.resourceManagement.isDefault` | Boolean | No | Whether this is the default tooltip for all types (default false) |
72
+ | Referenced Type | `cf.cplace.resourceManagement.referencedTypes` | Text (type names, dynamic enumeration, multiple) | No | Specific types this tooltip applies to |
73
+ | Script | `cf.cplace.resourceManagement.script` | Script | No | cplaceJS script to generate custom tooltip content |
69
74
 
70
75
  ## Widgets Provided
71
76
 
@@ -105,6 +110,13 @@ The Resource Planner widget provides:
105
110
  |-----|---------|
106
111
  | `cf.cplace.resourceManagement.resourceManagementChart` | Additional chart visualizations for resource data |
107
112
  | `cf.cplace.projectPlanning.app.basic.basicScheduleManagement` | Schedule, Task, Milestone types that can be used as planning items |
113
+ | `cf.cplace.resourceManagement.predefinedValueTypes` | Optional companion: adds the value types "Resource Request" and "Resource Answer" and their Value Type Configurations |
114
+
115
+ ### Optional Companion: Predefined Value Types
116
+
117
+ `cf.cplace.resourceManagement.predefinedValueTypes` (Value Types "Resource Request" and "Resource Answer") is a
118
+ separate app that requires this one. Install it when the solution plans with requests and answers instead of
119
+ defining its own value type; it brings the two types and configures them as value types.
108
120
 
109
121
  ### Prerequisites
110
122
 
@@ -0,0 +1,67 @@
1
+ # Value Types "Resource Request" and "Resource Answer" (cf.cplace.resourceManagement.predefinedValueTypes)
2
+
3
+ ## Overview
4
+
5
+ Adds the value types "Resource Request" and "Resource Answer" to the workspace. On install it also creates a
6
+ Value Type Configuration for each: the request's allocation is mapped as the *Requested Demand*, the answer's as
7
+ the *Allocation*. It is the optional companion of Resource Management for solutions that plan with requests and
8
+ answers rather than with a value type of their own.
9
+
10
+ **Plugin:** `cf.cplace.resourceManagement`
11
+
12
+ **Repository:** `cplace-resource-management`
13
+
14
+ ## Dependencies
15
+
16
+ When this app is installed, the following apps are automatically installed:
17
+
18
+ | App | Qualified Name | Description |
19
+ |-----|----------------|-------------|
20
+ | Resource Management | `cf.cplace.resourceManagement` | Required in the same workspace (`PredefinedValueTypesApp.getRequiredAppsInSameSpace`) |
21
+ | cplace Basis | `cf.cplace.platform` | Base platform (always installed) |
22
+
23
+ ## Types Provided
24
+
25
+ Both types share the value-type attributes of Resource Management (prefix `cf.cplace.resourceManagement.`).
26
+
27
+ ### cf.cplace.resourceManagement.request (Resource Request)
28
+
29
+ A demand for a resource on a planning item over time.
30
+
31
+ | Attribute | Internal Name | Type | Required | Description |
32
+ |-----------|---------------|------|----------|-------------|
33
+ | Resource | `cf.cplace.resourceManagement.resource` | Reference (any type) | No | The requested resource |
34
+ | Planning Item | `cf.cplace.resourceManagement.planningItem` | Reference (any type) | No | The planning item the demand is for |
35
+ | Requested Demand | `cf.cplace.resourceManagement.values` | Time-bounded values (multiple) | No | The demand per period |
36
+ | Resource Answer(s) | `cf.cplace.resourceManagement.answer` | Reference (multiple, to Resource Answer) | No | The answers to this request |
37
+ | Note | `cf.cplace.resourceManagement.note` | Long text | No | Free-text note |
38
+ | Time Range - Start | `cf.cplace.resourceManagement.startDate` | Date | No | Start of the values (read-only, derived) |
39
+ | Time Range - End | `cf.cplace.resourceManagement.endDate` | Date | No | End of the values (read-only, derived) |
40
+
41
+ ---
42
+
43
+ ### cf.cplace.resourceManagement.answer (Resource Answer)
44
+
45
+ The allocation granted in answer to a Resource Request.
46
+
47
+ | Attribute | Internal Name | Type | Required | Description |
48
+ |-----------|---------------|------|----------|-------------|
49
+ | Resource | `cf.cplace.resourceManagement.resource` | Reference (any type) | No | The allocated resource |
50
+ | Planning Item | `cf.cplace.resourceManagement.planningItem` | Reference (any type) | No | The planning item the allocation is for |
51
+ | Allocation | `cf.cplace.resourceManagement.values` | Time-bounded values (multiple) | No | The allocation per period |
52
+ | Resource Request | `cf.cplace.resourceManagement.originalRequest` | Reference (to Resource Request) | Yes | The request this answers |
53
+ | Note | `cf.cplace.resourceManagement.note` | Long text | No | Free-text note |
54
+ | Time Range - Start | `cf.cplace.resourceManagement.startDate` | Date | No | Start of the values (read-only, derived) |
55
+ | Time Range - End | `cf.cplace.resourceManagement.endDate` | Date | No | End of the values (read-only, derived) |
56
+
57
+ ## Widgets Provided
58
+
59
+ None. The Resource Planner widget comes from Resource Management.
60
+
61
+ ## Investigation Details
62
+
63
+ - **Source:** the `cplace-resource-management` source — `PredefinedValueTypesApp.java` (required app, types,
64
+ install hook), `types/RequestType.java`, `types/AnswerType.java`, `types/MixinTypes.java` (attributes),
65
+ `messages_en.properties` (labels). The qualified name follows the platform's `App.computeQualifiedName`
66
+ (package plus class name without `App`).
67
+ - **Live workspace investigation:** Not run.
@@ -1 +1 @@
1
- {"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/tools/documents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAsB5C,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAMjF;AAGD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyF5B,CAAC;AAEX,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,QAyS/E"}
1
+ {"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/tools/documents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AA4B5C,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAMjF;AAGD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4G5B,CAAC;AAEX,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,QAwW/E"}
@@ -3,9 +3,12 @@ import { debugLogWithTag } from '../logger.js';
3
3
  import { checkResponseSize } from '../utils.js';
4
4
  import { MAX_UPLOAD_BYTES } from '../types.js';
5
5
  import { validateAbsolutePath, writeFileCreatingParents, validateUploadFile, readFileForUpload, defaultFileName, } from '../utils/fileIO.js';
6
+ import { isLocalMode } from '../local-mode.js';
7
+ import { ifLocalFiles, ifNoLocalFiles, localFilesOnly } from '../capability-gating.js';
6
8
  const TOOL_GET_DOCUMENT = 'cplace_get_document';
7
9
  const TOOL_DOWNLOAD_DOCUMENT = 'cplace_download_document';
8
10
  const TOOL_UPLOAD_DOCUMENT = 'cplace_upload_document';
11
+ const HOSTED_DOWNLOAD_HINT = 'Open url in a browser while signed in to cplace to download the file. This hosted MCP server cannot save files to your disk; the local cplace MCP server (stdio) can.';
9
12
  export function formatDocumentContentError(prefix, error) {
10
13
  const message = error instanceof Error ? error.message : String(error);
11
14
  if (message.includes('(Status: 404)')) {
@@ -34,36 +37,41 @@ export const DOCUMENT_TOOL_DEFINITIONS = {
34
37
  annotations: { title: 'Get Document' },
35
38
  },
36
39
  [TOOL_DOWNLOAD_DOCUMENT]: {
37
- description: 'Download the binary file content of a document to a local file. Complements cplace_get_document, which returns extracted text only — use this tool to get the actual file (office documents, images, css/js assets, etc.). ' +
38
- 'Document UIDs are found in the documents array of page responses. ' +
39
- 'targetPath must be an absolute local path; missing parent directories are created and an existing file is overwritten silently.',
40
+ description: 'Get the file of a document. Complements cplace_get_document, which returns extracted text only — use this tool for the actual file (office documents, images, css/js assets, etc.). Document UIDs are found in the documents array of page responses. ' +
41
+ ifLocalFiles('The file is written to targetPath, an absolute local path; missing parent directories are created and an existing file is overwritten silently.') +
42
+ ifNoLocalFiles("Returns the document's cplace URL (url): the user opens it in a browser, signed in to cplace, to download the file. This hosted server cannot save files to the user's disk; that needs the local cplace MCP server (stdio). For the document's text, use cplace_get_document."),
40
43
  inputSchema: {
41
44
  documentUID: z
42
45
  .string()
43
46
  .describe("The unique identifier of the document (e.g., 'document/abc123'). Found in the documents array of page responses. (parameter name is `documentUID`, NOT `uid`)"),
44
- targetPath: z
47
+ targetPath: localFilesOnly(z
45
48
  .string()
46
- .describe("Absolute local file path to write the downloaded file to (e.g., '/tmp/report.pptx'). Parent directories are created if missing; an existing file is overwritten silently. Relative paths are rejected."),
49
+ .describe("Absolute local file path to write the downloaded file to (e.g., '/tmp/report.pptx'). Parent directories are created if missing; an existing file is overwritten silently. Relative paths are rejected.")),
47
50
  },
48
51
  annotations: { title: 'Download Document' },
49
52
  },
50
53
  [TOOL_UPLOAD_DOCUMENT]: {
51
- description: 'Upload a file as a page attachment. Provide the file bytes in exactly one of two ways: filePath (an absolute path the MCP server reads from its own filesystem — only works when the server shares your filesystem, i.e. local/stdio mode) or content (base64-encoded bytes, for when the server does not share your filesystem, e.g. a hosted server or an agent-generated file). ' +
54
+ description: ifLocalFiles('Upload a file as a page attachment. Provide the file bytes in exactly one of two ways: filePath (an absolute local path the MCP server reads) or content (base64-encoded bytes, e.g. for an agent-generated file). ') +
55
+ ifNoLocalFiles('Upload a file as a page attachment. Provide the file bytes as content (base64-encoded). ') +
52
56
  'Exactly one of pageUID (create mode) or documentUID (replace mode) must be provided. ' +
53
57
  'Create mode attaches the file as a new document on the page; if the page already has a document with the same file name, a new version of that document is written instead of creating a duplicate (platform behavior). ' +
54
58
  'Replace mode writes the file as a new version of an existing document — the document UID, name, and URL stay stable, so use this to update css/js assets referenced by widgets. ' +
55
- 'fileName applies to create mode only: it is required when content is used and defaults to the basename of filePath when filePath is used. ' +
59
+ 'fileName applies to create mode only: it is required when content is used' +
60
+ ifLocalFiles(' and defaults to the basename of filePath when filePath is used') +
61
+ '. ' +
56
62
  'When content is used its decoded size must not exceed 64 KB. ' +
57
63
  'Note: the fulltext of a freshly uploaded document becomes available asynchronously (~30s, Tika extraction).',
58
64
  inputSchema: {
59
- filePath: z
65
+ filePath: localFilesOnly(z
60
66
  .string()
61
67
  .optional()
62
- .describe("Absolute local file path of the file to upload (e.g., '/tmp/report.pptx'), read from the MCP server's own filesystem. Only usable when the server shares your filesystem (local/stdio mode). Relative paths are rejected. Provide exactly one of filePath or content."),
68
+ .describe("Absolute local file path of the file to upload (e.g., '/tmp/report.pptx'). Relative paths are rejected. Provide exactly one of filePath or content.")),
63
69
  content: z
64
70
  .string()
65
71
  .optional()
66
- .describe('Base64-encoded file bytes to upload directly, for when the MCP server does not share your filesystem (hosted/remote mode) or the file was generated in the agent context. Provide exactly one of filePath or content. When content is used, fileName is required. Decoded size must not exceed 64 KB (~87 KB of base64).'),
72
+ .describe('Base64-encoded file bytes to upload directly.' +
73
+ ifLocalFiles(' Provide exactly one of filePath or content.') +
74
+ ' When content is used, fileName is required. Decoded size must not exceed 64 KB (~87 KB of base64).'),
67
75
  pageUID: z
68
76
  .string()
69
77
  .optional()
@@ -75,7 +83,9 @@ export const DOCUMENT_TOOL_DEFINITIONS = {
75
83
  fileName: z
76
84
  .string()
77
85
  .optional()
78
- .describe('File name for the new document in create mode. Required when content is used (there is no path to derive a name from); defaults to the basename of filePath when filePath is used. Ignored in replace mode — the existing document keeps its name.'),
86
+ .describe('File name for the new document in create mode. Required when content is used (there is no path to derive a name from)' +
87
+ ifLocalFiles('; defaults to the basename of filePath when filePath is used') +
88
+ '. Ignored in replace mode — the existing document keeps its name.'),
79
89
  },
80
90
  annotations: { title: 'Upload Document' },
81
91
  },
@@ -133,7 +143,58 @@ export function registerDocumentTools(server, client) {
133
143
  }
134
144
  });
135
145
  server.registerTool(TOOL_DOWNLOAD_DOCUMENT, DOCUMENT_TOOL_DEFINITIONS[TOOL_DOWNLOAD_DOCUMENT], async ({ documentUID, targetPath }) => {
136
- debugLogWithTag('DOCUMENTS', `Downloading document: ${documentUID} to ${targetPath}`);
146
+ debugLogWithTag('DOCUMENTS', `Downloading document: ${documentUID}${targetPath === undefined ? '' : ` to ${targetPath}`}`);
147
+ if (!isLocalMode()) {
148
+ try {
149
+ const document = await client.makeApiRequest('json/document', 'GET', { documentUID });
150
+ if (typeof document?.url !== 'string' || document.url === '') {
151
+ return {
152
+ content: [
153
+ {
154
+ type: 'text',
155
+ text: `Error: cplace returned no URL for document ${documentUID}.`,
156
+ },
157
+ ],
158
+ isError: true,
159
+ };
160
+ }
161
+ const result = {
162
+ documentUID,
163
+ fileName: document.name,
164
+ mimeType: document.mimeType,
165
+ fileSize: document.fileSize,
166
+ url: document.url,
167
+ download: HOSTED_DOWNLOAD_HINT,
168
+ };
169
+ const sizeCheck = checkResponseSize(result);
170
+ if (sizeCheck.tooLarge) {
171
+ return {
172
+ content: [
173
+ {
174
+ type: 'text',
175
+ text: `Response too large (${sizeCheck.actualSize} characters, max: 45000).`,
176
+ },
177
+ ],
178
+ isError: true,
179
+ };
180
+ }
181
+ return {
182
+ content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
183
+ };
184
+ }
185
+ catch (error) {
186
+ debugLogWithTag('DOCUMENTS', `Error getting document link: ${error instanceof Error ? error.message : String(error)}`);
187
+ return {
188
+ content: [
189
+ {
190
+ type: 'text',
191
+ text: `Error retrieving document: ${error instanceof Error ? error.message : String(error)}`,
192
+ },
193
+ ],
194
+ isError: true,
195
+ };
196
+ }
197
+ }
137
198
  const pathError = validateAbsolutePath(targetPath, 'targetPath');
138
199
  if (pathError) {
139
200
  return {
@@ -196,7 +257,9 @@ export function registerDocumentTools(server, client) {
196
257
  content: [
197
258
  {
198
259
  type: 'text',
199
- text: 'Error: Exactly one of filePath (an absolute path the server reads from its own filesystem) or content (base64-encoded file bytes) must be provided.',
260
+ text: isLocalMode()
261
+ ? 'Error: Exactly one of filePath (an absolute path the server reads from its own filesystem) or content (base64-encoded file bytes) must be provided.'
262
+ : 'Error: content (base64-encoded file bytes) must be provided.',
200
263
  },
201
264
  ],
202
265
  isError: true,
@@ -246,7 +309,7 @@ export function registerDocumentTools(server, client) {
246
309
  content: [
247
310
  {
248
311
  type: 'text',
249
- text: `Error: decoded content is ${contentBuffer.byteLength} bytes, which exceeds the ${MAX_UPLOAD_BYTES}-byte (64 KB) limit for base64 content uploads. Base64 encoding inflates size by ~33%, and the whole tool call must fit the MCP client message limit. For larger files, use filePath when the server shares your filesystem.`,
312
+ text: `Error: decoded content is ${contentBuffer.byteLength} bytes, which exceeds the ${MAX_UPLOAD_BYTES}-byte (64 KB) limit for base64 content uploads. Base64 encoding inflates size by ~33%, and the whole tool call must fit the MCP client message limit. ${isLocalMode() ? 'For larger files, use filePath.' : 'For larger files, upload them in cplace directly, or use the local cplace MCP server (stdio), which reads files from disk.'}`,
250
313
  },
251
314
  ],
252
315
  isError: true,