mcp-dataverse 0.5.0 → 0.7.6

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 (15) hide show
  1. package/CAPABILITIES.md +326 -171
  2. package/README.md +41 -29
  3. package/assets/demo-thumbnail.jpg +0 -0
  4. package/assets/demo.mp4 +0 -0
  5. package/dist/chunk-6KQIRQNP.js +35 -0
  6. package/dist/chunk-IA4YDPXM.js +35 -0
  7. package/dist/dataverse-client-advanced-54FU3FKK.js +1 -0
  8. package/dist/dataverse-client-advanced-CON7DMNS.js +1 -0
  9. package/dist/doctor.js +1 -1
  10. package/dist/http-server.js +6 -6
  11. package/dist/server.js +174 -15
  12. package/package.json +2 -2
  13. package/server.json +3 -3
  14. package/dist/chunk-FSM3J3WD.js +0 -35
  15. package/dist/dataverse-client-advanced-EASNSX3M.js +0 -1
package/CAPABILITIES.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # MCP Dataverse Server — Complete Capabilities Reference
2
2
 
3
- > **Version**: 0.4.6 | **API Version**: Dataverse Web API v9.2 | **Transport**: stdio · HTTP/SSE
3
+ > **Version**: 0.7.6 | **API Version**: Dataverse Web API v9.2 | **Transport**: stdio · HTTP/SSE
4
4
 
5
- 73 tools across 25 categories for full Dataverse lifecycle: schema, CRUD, FetchXML, solutions, plugins, audit, files, users, teams, RBAC, attribute management, environment variables, workflows, and more.
5
+ 81 tools across 28 categories for full Dataverse lifecycle: schema, CRUD, FetchXML, solutions, plugins, audit, files, users, teams, RBAC, attribute management, environment variables, workflows, schema write, record access, web resources, and more.
6
6
 
7
7
  ---
8
8
 
@@ -10,7 +10,7 @@
10
10
 
11
11
  - [Quick Start](#quick-start)
12
12
  - [Architecture Overview](#architecture-overview)
13
- - [Tool Reference (73 tools)](#tool-reference-73-tools)
13
+ - [Tool Reference (81 tools)](#tool-reference-81-tools)
14
14
  - [1. Auth (1)](#1-auth-1-tool)
15
15
  - [2. Metadata (9)](#2-metadata-9-tools)
16
16
  - [3. Query (3)](#3-query-3-tools)
@@ -36,6 +36,9 @@
36
36
  - [23. Workflows (4)](#23-workflows-4-tools)
37
37
  - [24. Assistance (2)](#24-assistance-2-tools)
38
38
  - [25. Attributes (4)](#25-attributes-4-tools)
39
+ - [26. Schema (write) (2)](#26-schema-write-2-tools)
40
+ - [27. Record Access (4)](#27-record-access-4-tools)
41
+ - [28. Web Resources & Table Icons (2)](#28-web-resources--table-icons-2-tools)
39
42
  - [Error Handling & Retry Behavior](#error-handling--retry-behavior)
40
43
  - [Security](#security)
41
44
  - [Limitations & Known Constraints](#limitations--known-constraints)
@@ -46,11 +49,11 @@
46
49
 
47
50
  ### Prerequisites
48
51
 
49
- | Requirement | Details |
50
- | ------------------------- | ------------------------------------------------------------- |
51
- | **Node.js** | v20+ |
52
- | **Dataverse Environment** | Active URL (`https://<org>.crm<N>.dynamics.com`) |
53
- | **Authentication** | Device code flow (interactive) via MSAL |
52
+ | Requirement | Details |
53
+ | ------------------------- | ------------------------------------------------ |
54
+ | **Node.js** | v20+ |
55
+ | **Dataverse Environment** | Active URL (`https://<org>.crm<N>.dynamics.com`) |
56
+ | **Authentication** | Device code flow (interactive) via MSAL |
54
57
 
55
58
  ### Installation & Configuration
56
59
 
@@ -68,11 +71,11 @@ Create `config.json` (see `config.example.json`):
68
71
  }
69
72
  ```
70
73
 
71
- | Field | Type | Description |
72
- | ---------------------------------------- | --------------- | ------------------------------------------------------- |
73
- | `environmentUrl` | `string` | Dataverse environment URL (**required**, must be HTTPS) |
74
- | `requestTimeoutMs` | `number` | HTTP timeout ms (default: `30000`) |
75
- | `maxRetries` | `number` | Max retry attempts 0–10 (default: `3`) |
74
+ | Field | Type | Description |
75
+ | ------------------ | -------- | ------------------------------------------------------- |
76
+ | `environmentUrl` | `string` | Dataverse environment URL (**required**, must be HTTPS) |
77
+ | `requestTimeoutMs` | `number` | HTTP timeout ms (default: `30000`) |
78
+ | `maxRetries` | `number` | Max retry attempts 0–10 (default: `3`) |
76
79
 
77
80
  Env vars override config: `DATAVERSE_ENV_URL`, `REQUEST_TIMEOUT_MS`, `MAX_RETRIES`.
78
81
 
@@ -95,7 +98,7 @@ Server communicates over **stdio** (MCP SDK `StdioServerTransport`). Connect fro
95
98
 
96
99
  ```mermaid
97
100
  graph LR
98
- MCP["MCP Dataverse Server<br/><i>73 tools · 25 categories</i>"]
101
+ MCP["MCP Dataverse Server<br/><i>79 tools · 27 categories</i>"]
99
102
 
100
103
  MCP --> AUTH["🔑 Auth (1)"]
101
104
  MCP --> META["📋 Metadata (9)"]
@@ -122,13 +125,15 @@ graph LR
122
125
  MCP --> WF["⚙️ Workflows (4)"]
123
126
  MCP --> ASSIST["🤖 Assistance (2)"]
124
127
  MCP --> ATTR["🏗️ Attributes (4)"]
128
+ MCP --> SCHEMA["📐 Schema write (2)"]
129
+ MCP --> ACCESS["🔐 Record Access (4)"]
125
130
  ```
126
131
 
127
132
  All tool handlers validate inputs with **Zod** before calling the `DataverseAdvancedClient`. Auth tokens are cached and refreshed proactively; transient errors (429, 503, 504) are retried with exponential backoff.
128
133
 
129
134
  ---
130
135
 
131
- ## Tool Reference (73 tools)
136
+ ## Tool Reference (79 tools)
132
137
 
133
138
  ### 1. Auth (1 tool)
134
139
 
@@ -225,6 +230,35 @@ Returns all labels and integer values for a table-specific Picklist, Status, or
225
230
 
226
231
  ---
227
232
 
233
+ #### `dataverse_resolve_entity_name`
234
+
235
+ Resolves entity names bidirectionally: input a `logicalName` (e.g. `account`) or `entitySetName` (e.g. `accounts`) and get both representations plus metadata. Essential for avoiding 404/0x80060888 errors caused by using `logicalName` in OData URLs (which require `entitySetName`).
236
+
237
+ | Parameter | Type | Req | Notes |
238
+ | --------- | -------- | --- | ----------------------------------------------------- |
239
+ | `name` | `string` | ✓ | Entity name to resolve — logicalName or entitySetName |
240
+
241
+ > "What is the entitySetName for the 'account' entity?"
242
+
243
+ ---
244
+
245
+ #### `dataverse_update_entity`
246
+
247
+ Updates configuration flags on an existing Dataverse entity definition — enables or disables Notes (`HasNotes`), Change Tracking, and Audit. Requires System Customizer or System Administrator privileges.
248
+
249
+ | Parameter | Type | Req | Notes |
250
+ | ----------------------- | --------- | --- | -------------------------------------------------------------------- |
251
+ | `entityLogicalName` | `string` | ✓ | Logical name of the entity to update (e.g. `account`, `new_mytable`) |
252
+ | `confirm` | `boolean` | ✓ | Must be `true` — confirms intentional schema modification |
253
+ | `hasNotes` | `boolean` | – | Enable or disable Notes/Attachments for this entity |
254
+ | `changeTrackingEnabled` | `boolean` | – | Enable or disable change tracking (required for delta sync) |
255
+ | `isAuditEnabled` | `boolean` | – | Enable or disable auditing on this entity |
256
+ | `autoPublish` | `boolean` | – | Publish automatically after update (default: `false`) |
257
+
258
+ > "Enable notes/attachments on the 'new_myentity' table."
259
+
260
+ ---
261
+
228
262
  ### 3. Query (3 tools)
229
263
 
230
264
  #### `dataverse_query`
@@ -409,6 +443,39 @@ Removes an existing association. `relatedId` / `relatedEntitySetName` required f
409
443
 
410
444
  ---
411
445
 
446
+ #### `dataverse_associate_bulk`
447
+
448
+ Associates one source record with multiple related records at once via a named relationship, executing all associations in parallel. Unlike `dataverse_associate` (one pair at a time), this accepts an array of related IDs. Uses Promise.allSettled semantics — individual failures are reported per item without aborting the others.
449
+
450
+ | Parameter | Type | Req | Notes |
451
+ | ---------------------- | --------------- | --- | ------------------------------------- |
452
+ | `entitySetName` | `string` | ✓ | Source entity set name |
453
+ | `id` | `string (UUID)` | ✓ | Source record GUID |
454
+ | `relationshipName` | `string` | ✓ | Relationship schema name |
455
+ | `relatedEntitySetName` | `string` | ✓ | Related entity set name |
456
+ | `relatedIds` | `string[]` | ✓ | GUIDs of records to associate (1–200) |
457
+
458
+ > "Associate accounts a1b2, a3b4, and a5b6 with campaign record c1d2e3"
459
+
460
+ ---
461
+
462
+ #### `dataverse_query_associations`
463
+
464
+ Reads existing N:N associations for a record by querying through a navigation property. Returns the related records — use to verify what is already linked before calling `dataverse_associate` or `dataverse_disassociate`.
465
+
466
+ | Parameter | Type | Req | Notes |
467
+ | -------------------- | --------------- | --- | ----------------------------------------------------------- |
468
+ | `entitySetName` | `string` | ✓ | Source entity set name, e.g. `roles` |
469
+ | `id` | `string (UUID)` | ✓ | Source record GUID |
470
+ | `navigationProperty` | `string` | ✓ | Navigation property name, e.g. `roleprivileges_association` |
471
+ | `select` | `string` | – | Comma-separated columns to return on related records |
472
+ | `top` | `number` | – | Max records to return (default 50, max 1000) |
473
+ | `filter` | `string` | – | OData `$filter` expression applied to related records |
474
+
475
+ > "Check which privileges are linked to role r1a2b3c4 via the roleprivileges_association nav property"
476
+
477
+ ---
478
+
412
479
  ### 6. Actions & Functions (6 tools)
413
480
 
414
481
  #### `dataverse_execute_action`
@@ -537,43 +604,6 @@ Delta-query for incremental sync. Pass `deltaToken: null` for initial snapshot;
537
604
 
538
605
  ### 9. Solutions (2 tools)
539
606
 
540
- #### `dataverse_list_solutions`
541
-
542
- Lists solutions in the environment. By default returns only **unmanaged** solutions.
543
-
544
- | Parameter | Type | Req | Notes |
545
- | ---------------- | --------- | --- | ------------------------------------------- |
546
- | `includeManaged` | `boolean` | — | Include managed solutions (default `false`) |
547
- | `nameFilter` | `string` | — | Contains-match on unique name |
548
- | `top` | `number` | — | Default `50`, max `200` |
549
-
550
- > "List all unmanaged solutions in my environment"
551
-
552
- ```json
553
- {
554
- "solutions": [
555
- { "uniqueName": "MySolution", "version": "1.0.0.0", "isManaged": false }
556
- ],
557
- "count": 1
558
- }
559
- ```
560
-
561
- ---
562
-
563
- #### `dataverse_solution_components`
564
-
565
- Lists all components in a named solution. Use the **unique** solution name, not the display name.
566
-
567
- | Parameter | Type | Req | Notes |
568
- | --------------- | -------- | --- | ---------------------------------------------------------------------------- |
569
- | `solutionName` | `string` | ✓ | Unique solution name |
570
- | `componentType` | `number` | — | Type code filter (1=Entity, 29=Workflow, 90=PluginAssembly, 97=WebResource…) |
571
- | `top` | `number` | — | Default `200`, max `5000` |
572
-
573
- > "List all entities in the 'MySolution' solution"
574
-
575
- ---
576
-
577
607
  #### `dataverse_publish_customizations`
578
608
 
579
609
  Publishes unpublished customizations. Omit `components` to publish all (equivalent to "Publish All" in maker portal). **Can take 30–120 s in large environments.**
@@ -588,6 +618,22 @@ Publishes unpublished customizations. Omit `components` to publish all (equivale
588
618
 
589
619
  ---
590
620
 
621
+ #### `dataverse_create_sitemap`
622
+
623
+ Creates a model-driven app sitemap (navigation structure) by generating valid sitemap XML and posting it to the Dataverse `sitemaps` entity set. Optionally links the sitemap to an existing model-driven app module.
624
+
625
+ | Parameter | Type | Req | Notes |
626
+ | --------------------- | -------- | --- | ------------------------------------------------------------ |
627
+ | `sitemapName` | `string` | ✓ | Display name of the sitemap |
628
+ | `appModuleUniqueName` | `string` | — | Unique name of the model-driven app to link this sitemap to |
629
+ | `areas` | `array` | ✓ | One or more navigation areas (each with `title`, `groups[]`) |
630
+
631
+ Each area contains **groups**, each group contains **subareas** with optional `entityLogicalName`, `url`, `title`, and `id`.
632
+
633
+ > "Create a sitemap with a 'Sales' area containing an 'Accounts' subarea for entity 'account'"
634
+
635
+ ---
636
+
591
637
  ### 10. Impersonation (1 tool)
592
638
 
593
639
  #### `dataverse_impersonate`
@@ -672,6 +718,19 @@ Activates or deactivates a classic Dataverse workflow (statecode/statuscode upda
672
718
 
673
719
  ---
674
720
 
721
+ #### `dataverse_list_connection_references`
722
+
723
+ Lists connection references used in solutions (Power Automate connectors).
724
+
725
+ | Parameter | Type | Req | Notes |
726
+ | ------------ | -------- | --- | ------------------------------- |
727
+ | `top` | `number` | — | Default `50`, max `200` |
728
+ | `nameFilter` | `string` | — | Substring match on display name |
729
+
730
+ > "List all SharePoint connection references in my environment"
731
+
732
+ ---
733
+
675
734
  ### 12. Environment (4 tools)
676
735
 
677
736
  #### `dataverse_get_environment_variable`
@@ -713,20 +772,32 @@ Sets or updates an environment variable's current value (creates or updates the
713
772
 
714
773
  Creates a new Dataverse environment variable definition and sets its initial value. Use when the variable does not yet exist.
715
774
 
716
- | Parameter | Type | Req | Notes |
717
- | -------------- | ---------------------------------------- | --- | ------------------------------------------------------- |
775
+ | Parameter | Type | Req | Notes |
776
+ | -------------- | ---------------------------------------- | --- | --------------------------------------------------------- |
718
777
  | `schemaName` | `string` | ✓ | Schema name (publisher prefix required, e.g. `new_MyVar`) |
719
- | `displayName` | `string` | ✓ | Human-readable label |
720
- | `type` | `"String"\|"Integer"\|"Boolean"\|"JSON"` | ✓ | Variable data type |
721
- | `value` | `string` | ✓ | Initial value |
722
- | `description` | `string` | — | Optional description |
723
- | `defaultValue` | `string` | — | Optional default value |
724
- | `confirm` | `true` | ✓ | Explicit confirmation required |
778
+ | `displayName` | `string` | ✓ | Human-readable label |
779
+ | `type` | `"String"\|"Integer"\|"Boolean"\|"JSON"` | ✓ | Variable data type |
780
+ | `value` | `string` | ✓ | Initial value |
781
+ | `description` | `string` | — | Optional description |
782
+ | `defaultValue` | `string` | — | Optional default value |
783
+ | `confirm` | `true` | ✓ | Explicit confirmation required |
725
784
 
726
785
  > "Create environment variable new_MaxRetries of type Integer with value 3"
727
786
 
728
787
  ---
729
788
 
789
+ #### `dataverse_environment_capabilities`
790
+
791
+ Returns a comprehensive snapshot of the Dataverse environment: identity (WhoAmI), organization settings (name, version, language, audit config), unmanaged solution count, and environment variable count. Use at the start of a session to orient yourself to the environment and its configuration.
792
+
793
+ | Parameter | Type | Req | Notes |
794
+ | --------- | ---- | --- | ---------------------- |
795
+ | _(none)_ | | | No parameters required |
796
+
797
+ > "Give me an overview of this Dataverse environment"
798
+
799
+ ---
800
+
730
801
  ### 13. Trace (2 tools)
731
802
 
732
803
  #### `dataverse_get_plugin_trace_logs`
@@ -935,7 +1006,7 @@ Lists saved (system) and optionally personal views for a Dataverse table, includ
935
1006
 
936
1007
  #### `dataverse_upload_file_column`
937
1008
 
938
- Uploads a file to a Dataverse **file-type column** on a record. File content must be base64-encoded.
1009
+ Uploads a file to a Dataverse **file or image column** on a record. File content must be base64-encoded.
939
1010
 
940
1011
  | Parameter | Type | Req | Notes |
941
1012
  | --------------- | --------------- | --- | ------------------------------------------------------- |
@@ -961,7 +1032,7 @@ Uploads a file to a Dataverse **file-type column** on a record. File content mus
961
1032
 
962
1033
  #### `dataverse_download_file_column`
963
1034
 
964
- Downloads a file from a Dataverse file-type column. Returns the file as a base64-encoded string with its name and size.
1035
+ Downloads a file from a Dataverse file or image column. Returns the file as a base64-encoded string with its name and size.
965
1036
 
966
1037
  | Parameter | Type | Req | Notes |
967
1038
  | --------------- | --------------- | --- | ------------------------ |
@@ -1000,11 +1071,11 @@ Lists business units in the environment with name, ID, parent BU ID, disabled st
1000
1071
 
1001
1072
  Lists Dataverse teams (owner teams and access teams) within one or all business units.
1002
1073
 
1003
- | Parameter | Type | Req | Notes |
1004
- | ---------------- | ------------------------- | --- | ---------------------------------------------- |
1005
- | `top` | `number` | — | Default `50`, max `200` |
1006
- | `teamType` | `"Owner"\|"Access"\|"AAD"` | — | Filter by team type; omit for all |
1007
- | `businessUnitId` | `string (UUID)` | — | Filter by business unit |
1074
+ | Parameter | Type | Req | Notes |
1075
+ | ---------------- | -------------------------- | --- | --------------------------------- |
1076
+ | `top` | `number` | — | Default `50`, max `200` |
1077
+ | `teamType` | `"Owner"\|"Access"\|"AAD"` | — | Filter by team type; omit for all |
1078
+ | `businessUnitId` | `string (UUID)` | — | Filter by business unit |
1008
1079
 
1009
1080
  > "List all owner teams in the environment"
1010
1081
 
@@ -1036,10 +1107,10 @@ Lists security roles in the environment, optionally filtered by name.
1036
1107
 
1037
1108
  Assigns a security role to a system user (idempotent — returns `"already_assigned"` if the role is already assigned).
1038
1109
 
1039
- | Parameter | Type | Req | Notes |
1040
- | --------- | --------------- | --- | ----------------- |
1041
- | `userId` | `string (UUID)` | ✓ | System user GUID |
1042
- | `roleId` | `string (UUID)` | ✓ | Security role ID |
1110
+ | Parameter | Type | Req | Notes |
1111
+ | --------- | --------------- | --- | ---------------- |
1112
+ | `userId` | `string (UUID)` | ✓ | System user GUID |
1113
+ | `roleId` | `string (UUID)` | ✓ | Security role ID |
1043
1114
 
1044
1115
  > "Assign role r1s2t3u4 to user u1v2w3x4"
1045
1116
 
@@ -1072,17 +1143,59 @@ Assigns a security role to a Dataverse team. All team members inherit the role p
1072
1143
 
1073
1144
  ---
1074
1145
 
1146
+ #### `dataverse_get_role_privileges`
1147
+
1148
+ Retrieves all privileges assigned to a security role with their depth levels (None/Basic/Local/Deep/Global). Use to audit a role's current permissions before modifying them, or to verify depth assignments.
1149
+
1150
+ | Parameter | Type | Req | Notes |
1151
+ | --------- | --------------- | --- | ------------------------- |
1152
+ | `roleId` | `string (UUID)` | ✓ | GUID of the security role |
1153
+
1154
+ > "What privileges does role r1s2t3u4 currently have?"
1155
+
1156
+ ---
1157
+
1158
+ #### `dataverse_add_role_privileges`
1159
+
1160
+ Adds one or more privileges to a security role with specified depth levels. Supports all depths: None, Basic (user-level), Local (BU-level), Deep (parent-BU), Global (org-level). For org-owned entities only Global is valid.
1161
+
1162
+ | Parameter | Type | Req | Notes |
1163
+ | ----------------------------- | --------------- | --- | ---------------------------------------------------------------- |
1164
+ | `roleId` | `string (UUID)` | ✓ | GUID of the security role |
1165
+ | `privileges` | `array` | ✓ | Array of `{ privilegeId, depth, businessUnitId? }` entries (1–N) |
1166
+ | `privileges[].privilegeId` | `string (UUID)` | ✓ | GUID — query `privileges` entity to find by name or entity |
1167
+ | `privileges[].depth` | `string` | ✓ | `None`, `Basic`, `Local`, `Deep`, or `Global` |
1168
+ | `privileges[].businessUnitId` | `string (UUID)` | — | Defaults to root BU if omitted |
1169
+
1170
+ > "Add prvReadAccount with Global depth to role r1s2t3u4"
1171
+
1172
+ ---
1173
+
1174
+ #### `dataverse_replace_role_privileges`
1175
+
1176
+ Atomically replaces **all** privileges on a security role using the `ReplacePrivilegesRole` action. The existing privilege set is completely overwritten. Use `dataverse_add_role_privileges` instead if only additive changes are needed.
1177
+
1178
+ | Parameter | Type | Req | Notes |
1179
+ | ------------ | --------------- | --- | ----------------------------------------------------------------- |
1180
+ | `roleId` | `string (UUID)` | ✓ | GUID of the security role |
1181
+ | `privileges` | `array` | ✓ | Complete new privilege set (same schema as `add_role_privileges`) |
1182
+ | `confirm` | `true` | ✓ | Required — replaces all existing privileges on the role |
1183
+
1184
+ > "Replace all privileges on role r1s2t3u4 with a custom set"
1185
+
1186
+ ---
1187
+
1075
1188
  ### 23. Workflows (4 tools)
1076
1189
 
1077
1190
  #### `dataverse_list_workflows`
1078
1191
 
1079
1192
  Lists classic Dataverse workflows and modern cloud flows registered in the environment.
1080
1193
 
1081
- | Parameter | Type | Req | Notes |
1082
- | ------------- | --------- | --- | -------------------------------------------- |
1083
- | `top` | `number` | — | Default `50`, max `200` |
1084
- | `activeOnly` | `boolean` | — | Return only activated workflows (default `false`) |
1085
- | `nameFilter` | `string` | — | Substring match on workflow name |
1194
+ | Parameter | Type | Req | Notes |
1195
+ | ------------ | --------- | --- | ------------------------------------------------- |
1196
+ | `top` | `number` | — | Default `50`, max `200` |
1197
+ | `activeOnly` | `boolean` | — | Return only activated workflows (default `false`) |
1198
+ | `nameFilter` | `string` | — | Substring match on workflow name |
1086
1199
 
1087
1200
  > "List all active workflows on the account table"
1088
1201
 
@@ -1100,27 +1213,12 @@ Retrieves a single workflow definition by ID, including its trigger, steps, and
1100
1213
 
1101
1214
  ---
1102
1215
 
1103
- ### 24. Assistance (2 tools)
1104
-
1105
- #### `dataverse_suggest_tools`
1106
-
1107
- Returns a ranked list of MCP tools relevant to a natural-language task description. Use this when unsure which tool to call — it uses tag-based matching to surface the right tools.
1108
-
1109
- | Parameter | Type | Req | Notes |
1110
- | ------------- | -------- | --- | ---------------------------------- |
1111
- | `task` | `string` | ✓ | Natural-language description of the task |
1112
- | `top` | `number` | — | Max results (default `5`) |
1113
-
1114
- > "Which tool should I use to create a new lookup column?"
1115
-
1116
- ---
1117
-
1118
1216
  #### `dataverse_list_guides`
1119
1217
 
1120
1218
  Lists available built-in guides that walk through common multi-step Dataverse tasks.
1121
1219
 
1122
- | Parameter | Type | Req | Notes |
1123
- | --------- | ---- | --- | ----- |
1220
+ | Parameter | Type | Req | Notes |
1221
+ | --------- | ---- | --- | ------------- |
1124
1222
  | — | — | — | No parameters |
1125
1223
 
1126
1224
  > "What guides are available in this MCP server?"
@@ -1131,24 +1229,26 @@ Lists available built-in guides that walk through common multi-step Dataverse ta
1131
1229
 
1132
1230
  Retrieves the full step-by-step content for a specific guide by name.
1133
1231
 
1134
- | Parameter | Type | Req | Notes |
1135
- | ----------- | -------- | --- | ------------------- |
1232
+ | Parameter | Type | Req | Notes |
1233
+ | ----------- | -------- | --- | ----------------------------- |
1136
1234
  | `guideName` | `string` | ✓ | Guide name from `list_guides` |
1137
1235
 
1138
1236
  > "Show me the steps for the entity-audit guide"
1139
1237
 
1140
1238
  ---
1141
1239
 
1142
- #### `dataverse_list_connection_references`
1240
+ ### 24. Assistance (2 tools)
1143
1241
 
1144
- Lists connection references used in solutions (Power Automate connectors).
1242
+ #### `dataverse_suggest_tools`
1145
1243
 
1146
- | Parameter | Type | Req | Notes |
1147
- | -------------- | -------- | --- | -------------------------------- |
1148
- | `top` | `number` | — | Default `50`, max `200` |
1149
- | `nameFilter` | `string` | — | Substring match on display name |
1244
+ Returns a ranked list of MCP tools relevant to a natural-language task description. Use this when unsure which tool to call — it uses tag-based matching to surface the right tools.
1150
1245
 
1151
- > "List all SharePoint connection references in my environment"
1246
+ | Parameter | Type | Req | Notes |
1247
+ | --------- | -------- | --- | ---------------------------------------- |
1248
+ | `task` | `string` | ✓ | Natural-language description of the task |
1249
+ | `top` | `number` | — | Max results (default `5`) |
1250
+
1251
+ > "Which tool should I use to create a new lookup column?"
1152
1252
 
1153
1253
  ---
1154
1254
 
@@ -1172,24 +1272,24 @@ Attribute tools manage **column-level schema** in Dataverse tables. All write op
1172
1272
 
1173
1273
  Creates a new column on an existing Dataverse table. Supports 11 attribute types with type-specific parameters.
1174
1274
 
1175
- | Parameter | Type | Req | Notes |
1176
- | -------------------- | ---------------------------------------------------------------------------------------------------------------- | --- | --------------------------------------------------------------- |
1177
- | `entityLogicalName` | `string` | ✓ | Target table (e.g. `"account"`) |
1178
- | `schemaName` | `string` | ✓ | Must include publisher prefix (e.g. `"new_CustomField"`) |
1179
- | `attributeType` | `"String"\|"Memo"\|"Integer"\|"Decimal"\|"Money"\|"DateTime"\|"Boolean"\|"Picklist"\|"MultiSelectPicklist"\|"AutoNumber"\|"Image"` | ✓ | Column type |
1180
- | `displayName` | `string` | ✓ | Human-readable label |
1181
- | `description` | `string` | — | Column description |
1182
- | `requiredLevel` | `"None"\|"ApplicationRequired"\|"Recommended"` | — | Requirement level (default `"None"`) |
1183
- | `maxLength` | `number` | — | String/Memo max chars |
1184
- | `minValue`/`maxValue`| `number` | — | Integer/Decimal range bounds |
1185
- | `precision` | `number` | — | Decimal/Money decimal places |
1186
- | `dateTimeFormat` | `"DateOnly"\|"DateAndTime"` | — | DateTime display format |
1187
- | `defaultBooleanValue`| `boolean` | — | Default for Boolean columns |
1188
- | `picklistOptions` | `{value: number, label: string}[]` | — | Option values for Picklist/MultiSelectPicklist |
1189
- | `autoNumberFormat` | `string` | — | Format string for AutoNumber, e.g. `"INV-{SEQNUM:5}"` |
1190
- | `languageCode` | `number` | — | Label language code (default `1033` = English) |
1191
- | `autoPublish` | `boolean` | — | Publish after create (default `true`) |
1192
- | `confirm` | `true` | ✓ | Must be `true` |
1275
+ | Parameter | Type | Req | Notes |
1276
+ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --- | -------------------------------------------------------- |
1277
+ | `entityLogicalName` | `string` | ✓ | Target table (e.g. `"account"`) |
1278
+ | `schemaName` | `string` | ✓ | Must include publisher prefix (e.g. `"new_CustomField"`) |
1279
+ | `attributeType` | `"String"\|"Memo"\|"Integer"\|"Decimal"\|"Money"\|"DateTime"\|"Boolean"\|"Picklist"\|"MultiSelectPicklist"\|"AutoNumber"\|"Image"` | ✓ | Column type |
1280
+ | `displayName` | `string` | ✓ | Human-readable label |
1281
+ | `description` | `string` | — | Column description |
1282
+ | `requiredLevel` | `"None"\|"ApplicationRequired"\|"Recommended"` | — | Requirement level (default `"None"`) |
1283
+ | `maxLength` | `number` | — | String/Memo max chars |
1284
+ | `minValue`/`maxValue` | `number` | — | Integer/Decimal range bounds |
1285
+ | `precision` | `number` | — | Decimal/Money decimal places |
1286
+ | `dateTimeFormat` | `"DateOnly"\|"DateAndTime"` | — | DateTime display format |
1287
+ | `defaultBooleanValue` | `boolean` | — | Default for Boolean columns |
1288
+ | `picklistOptions` | `{value: number, label: string}[]` | — | Option values for Picklist/MultiSelectPicklist |
1289
+ | `autoNumberFormat` | `string` | — | Format string for AutoNumber, e.g. `"INV-{SEQNUM:5}"` |
1290
+ | `languageCode` | `number` | — | Label language code (default `1033` = English) |
1291
+ | `autoPublish` | `boolean` | — | Publish after create (default `true`) |
1292
+ | `confirm` | `true` | ✓ | Must be `true` |
1193
1293
 
1194
1294
  > "Add a text column 'new_ExternalId' to the account table with max 100 characters"
1195
1295
 
@@ -1209,18 +1309,18 @@ Creates a new column on an existing Dataverse table. Supports 11 attribute types
1209
1309
 
1210
1310
  Updates properties of an existing column. Only columns with `IsCustomizable = true` can be modified.
1211
1311
 
1212
- | Parameter | Type | Req | Notes |
1213
- | --------------------- | ----------------------------------------------- | --- | ------------------------------------------- |
1214
- | `entityLogicalName` | `string` | ✓ | Table containing the column |
1215
- | `attributeLogicalName`| `string` | ✓ | Column logical name (e.g. `"new_myfield"`) |
1216
- | `displayName` | `string` | — | New display label |
1217
- | `description` | `string` | — | New description |
1218
- | `requiredLevel` | `"None"\|"ApplicationRequired"\|"Recommended"` | — | New requirement level |
1219
- | `maxLength` | `number` | — | Increase only (cannot decrease) |
1220
- | `isSearchable` | `boolean` | — | Include in Quick Find views |
1221
- | `languageCode` | `number` | — | Default `1033` |
1222
- | `autoPublish` | `boolean` | — | Default `true` |
1223
- | `confirm` | `true` | ✓ | Must be `true` |
1312
+ | Parameter | Type | Req | Notes |
1313
+ | ---------------------- | ---------------------------------------------- | --- | ------------------------------------------ |
1314
+ | `entityLogicalName` | `string` | ✓ | Table containing the column |
1315
+ | `attributeLogicalName` | `string` | ✓ | Column logical name (e.g. `"new_myfield"`) |
1316
+ | `displayName` | `string` | — | New display label |
1317
+ | `description` | `string` | — | New description |
1318
+ | `requiredLevel` | `"None"\|"ApplicationRequired"\|"Recommended"` | — | New requirement level |
1319
+ | `maxLength` | `number` | — | Increase only (cannot decrease) |
1320
+ | `isSearchable` | `boolean` | — | Include in Quick Find views |
1321
+ | `languageCode` | `number` | — | Default `1033` |
1322
+ | `autoPublish` | `boolean` | — | Default `true` |
1323
+ | `confirm` | `true` | ✓ | Must be `true` |
1224
1324
 
1225
1325
  > "Update new_externalid on account to be required"
1226
1326
 
@@ -1230,12 +1330,12 @@ Updates properties of an existing column. Only columns with `IsCustomizable = tr
1230
1330
 
1231
1331
  ⚠️ **DESTRUCTIVE** — permanently deletes a custom column and all its data from all records.
1232
1332
 
1233
- | Parameter | Type | Req | Notes |
1234
- | --------------------- | -------- | --- | ------------------------------------------------ |
1235
- | `entityLogicalName` | `string` | ✓ | Table containing the column |
1236
- | `attributeLogicalName`| `string` | ✓ | Column logical name (must be a custom column) |
1237
- | `autoPublish` | `boolean`| — | Publish after delete (default `true`) |
1238
- | `confirm` | `true` | ✓ | Must be `true` |
1333
+ | Parameter | Type | Req | Notes |
1334
+ | ---------------------- | --------- | --- | --------------------------------------------- |
1335
+ | `entityLogicalName` | `string` | ✓ | Table containing the column |
1336
+ | `attributeLogicalName` | `string` | ✓ | Column logical name (must be a custom column) |
1337
+ | `autoPublish` | `boolean` | — | Publish after delete (default `true`) |
1338
+ | `confirm` | `true` | ✓ | Must be `true` |
1239
1339
 
1240
1340
  > "Delete the column new_externalid from account"
1241
1341
 
@@ -1245,17 +1345,17 @@ Updates properties of an existing column. Only columns with `IsCustomizable = tr
1245
1345
 
1246
1346
  Creates a lookup (N:1) column on a table, simultaneously defining a 1:N relationship between two tables. This is the correct way to add a foreign-key-style reference to another table.
1247
1347
 
1248
- | Parameter | Type | Req | Notes |
1249
- | --------------------- | -------- | --- | --------------------------------------------------------------------------- |
1250
- | `entityLogicalName` | `string` | ✓ | Table that will contain the lookup column (the "many" side) |
1251
- | `schemaName` | `string` | ✓ | Must include publisher prefix (e.g. `"new_ParentAccount"`) |
1252
- | `displayName` | `string` | ✓ | Human-readable label |
1253
- | `referencedEntity` | `string` | ✓ | Table being looked up (the "one" side, e.g. `"account"`) |
1254
- | `description` | `string` | — | Column description |
1255
- | `requiredLevel` | `"None"\|"ApplicationRequired"\|"Recommended"` | — | Default `"None"` |
1256
- | `languageCode` | `number` | — | Default `1033` |
1257
- | `autoPublish` | `boolean`| — | Default `true` |
1258
- | `confirm` | `true` | ✓ | Must be `true` |
1348
+ | Parameter | Type | Req | Notes |
1349
+ | ------------------- | ---------------------------------------------- | --- | ----------------------------------------------------------- |
1350
+ | `entityLogicalName` | `string` | ✓ | Table that will contain the lookup column (the "many" side) |
1351
+ | `schemaName` | `string` | ✓ | Must include publisher prefix (e.g. `"new_ParentAccount"`) |
1352
+ | `displayName` | `string` | ✓ | Human-readable label |
1353
+ | `referencedEntity` | `string` | ✓ | Table being looked up (the "one" side, e.g. `"account"`) |
1354
+ | `description` | `string` | — | Column description |
1355
+ | `requiredLevel` | `"None"\|"ApplicationRequired"\|"Recommended"` | — | Default `"None"` |
1356
+ | `languageCode` | `number` | — | Default `1033` |
1357
+ | `autoPublish` | `boolean` | — | Default `true` |
1358
+ | `confirm` | `true` | ✓ | Must be `true` |
1259
1359
 
1260
1360
  > "Add a lookup to 'account' on the contact table called new_PrimaryAccount"
1261
1361
 
@@ -1271,6 +1371,61 @@ Creates a lookup (N:1) column on a table, simultaneously defining a 1:N relation
1271
1371
 
1272
1372
  ---
1273
1373
 
1374
+ ### 28. Web Resources & Table Icons (2 tools)
1375
+
1376
+ Web resource tools manage custom files (SVG, PNG, JPG, GIF, ICO) in Dataverse, which are prerequisite for setting table (entity) icons in model-driven apps.
1377
+
1378
+ > **Workflow**: `dataverse_create_web_resource` → `dataverse_set_table_icon` → `dataverse_publish_customizations`
1379
+
1380
+ ---
1381
+
1382
+ #### `dataverse_create_web_resource`
1383
+
1384
+ Creates a web resource file in Dataverse — required before assigning icons to tables. Supports SVG (type 11, preferred for `IconVectorName`), PNG, JPG, GIF, and ICO formats. Provide the base64-encoded file content.
1385
+
1386
+ | Parameter | Type | Req | Notes |
1387
+ | ----------------- | ----------------------------------------- | --- | ---------------------------------------------------------------------------------- |
1388
+ | `name` | `string` | ✓ | Unique name with publisher prefix (e.g. `"plng_stage_icon.svg"`) |
1389
+ | `displayName` | `string` | ✓ | Human-friendly label |
1390
+ | `webResourceType` | `"SVG"\|"PNG"\|"JPG"\|"GIF"\|"ICO"` | ✓ | Use `"SVG"` for `IconVectorName` table icons |
1391
+ | `contentBase64` | `string` | ✓ | Base64-encoded file content |
1392
+ | `description` | `string` | — | Optional description |
1393
+
1394
+ ```json
1395
+ {
1396
+ "webResourceId": "00000000-0000-0000-0000-000000000000",
1397
+ "name": "plng_stage_icon.svg",
1398
+ "displayName": "Stage Icon",
1399
+ "webResourceType": "SVG",
1400
+ "typeCode": 11
1401
+ }
1402
+ ```
1403
+
1404
+ ---
1405
+
1406
+ #### `dataverse_set_table_icon`
1407
+
1408
+ Sets, changes, or removes the icon for a model-driven app table. Supports modern SVG vector icons (`iconVectorName`, preferred) and legacy PNG icons (`iconLargeName`, `iconMediumName`). The web resource must exist in Dataverse before calling this tool. Pass an empty string `""` to remove an icon.
1409
+
1410
+ | Parameter | Type | Req | Notes |
1411
+ | -------------------- | --------- | --- | ----------------------------------------------------------------------------- |
1412
+ | `entityLogicalName` | `string` | ✓ | Table logical name (e.g. `"plng_stage"`) |
1413
+ | `iconVectorName` | `string` | — | SVG web resource name (e.g. `"plng_stage_icon.svg"`). `""` to remove. |
1414
+ | `iconLargeName` | `string` | — | Legacy 32x32 image web resource. `""` to remove. |
1415
+ | `iconMediumName` | `string` | — | Legacy 16x16 image web resource. `""` to remove. |
1416
+ | `autoPublish` | `boolean` | — | Publish after update (default `false`) |
1417
+ | `confirm` | `true` | ✓ | Must be `true` |
1418
+
1419
+ ```json
1420
+ {
1421
+ "entityLogicalName": "plng_stage",
1422
+ "changes": { "IconVectorName": "plng_stage_icon.svg" },
1423
+ "published": false
1424
+ }
1425
+ ```
1426
+
1427
+ ---
1428
+
1274
1429
  ## Error Handling & Retry Behavior
1275
1430
 
1276
1431
  All tool handlers return `{ isError: true, content: [{ type: "text", text: "Error: ..." }] }` on failure. Zod input validation runs before any network call.
@@ -1289,26 +1444,26 @@ Dataverse error bodies are formatted as `Dataverse error <code>: <message>`. Tim
1289
1444
 
1290
1445
  Certain tools include an `errorCategory` field in the error text when the failure has a well-known cause:
1291
1446
 
1292
- | `errorCategory` | Meaning | Example |
1293
- | ----------------- | ------------------------------------------------------------ | --------------------------------------------------------- |
1294
- | `ENV_LIMITATION` | Feature not enabled or unavailable in this environment | `dataverse_search` when Relevance Search is disabled |
1295
- | `PERMISSIONS` | Operation denied due to insufficient privileges | Restricted table or action |
1296
- | `SCHEMA_MISMATCH` | Supplied data conflicts with the table's metadata schema | Wrong attribute type in `dataverse_create_attribute` |
1447
+ | `errorCategory` | Meaning | Example |
1448
+ | ----------------- | -------------------------------------------------------- | ---------------------------------------------------- |
1449
+ | `ENV_LIMITATION` | Feature not enabled or unavailable in this environment | `dataverse_search` when Relevance Search is disabled |
1450
+ | `PERMISSIONS` | Operation denied due to insufficient privileges | Restricted table or action |
1451
+ | `SCHEMA_MISMATCH` | Supplied data conflicts with the table's metadata schema | Wrong attribute type in `dataverse_create_attribute` |
1297
1452
 
1298
1453
  ---
1299
1454
 
1300
1455
  ## Security
1301
1456
 
1302
- | Mode | Flow | Use Case |
1303
- | ----------------- | ------------------------------------------------- | ---------------------- |
1304
- | **Device Code** | MSAL Public Client → device code + silent refresh | Local dev, interactive |
1457
+ | Mode | Flow | Use Case |
1458
+ | --------------- | ------------------------------------------------- | ---------------------- |
1459
+ | **Device Code** | MSAL Public Client → device code + silent refresh | Local dev, interactive |
1305
1460
 
1306
1461
  - `clientSecret` is never logged or returned in tool responses.
1307
1462
  - Token cache is encrypted (AES-256-GCM) at `~/.mcp-dataverse/` and should not be shared.
1308
1463
  - OData path segments use `esc()` (single-quote doubling) to prevent OData injection.
1309
1464
  - `columnName` in file tools is validated against `/^[a-zA-Z0-9_]+$/` to prevent path traversal.
1310
1465
  - `MSCRMCallerId` for impersonation is set per-call and cleaned up in a `finally` block regardless of outcome.
1311
- - `.msal-cache.json` should be in `.gitignore`. No HTTP endpoints are exposed (stdio only).
1466
+ - `.msal-cache.json` should be in `.gitignore`. When running in HTTP mode, ensure the server is not exposed on a public network without proper auth.
1312
1467
 
1313
1468
  ---
1314
1469
 
@@ -1316,12 +1471,12 @@ Certain tools include an `errorCategory` field in the error text when the failur
1316
1471
 
1317
1472
  ### General
1318
1473
 
1319
- | Limitation | Details |
1320
- | ------------------------------ | --------------------------------------------------------------------------------------- |
1321
- | **Transport** | stdio only. Server must be spawned as a child process by the MCP host. |
1322
- | **Single environment** | One Dataverse environment per server instance. Restart to switch. |
1323
- | **No streaming** | Responses are complete JSON. Very large result sets may exceed AI model context limits. |
1324
- | **No real-time subscriptions** | Use `dataverse_change_detection` for polling-based incremental sync. |
1474
+ | Limitation | Details |
1475
+ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
1476
+ | **Transport** | stdio (default) and HTTP/SSE. stdio: spawned as child process. HTTP: run as standalone service on configurable port. |
1477
+ | **Single environment** | One Dataverse environment per server instance. Restart to switch. |
1478
+ | **No streaming** | Responses are complete JSON. Very large result sets may exceed AI model context limits. |
1479
+ | **No real-time subscriptions** | Use `dataverse_change_detection` for polling-based incremental sync. |
1325
1480
 
1326
1481
  ### Query
1327
1482
 
@@ -1333,16 +1488,16 @@ Certain tools include an `errorCategory` field in the error text when the failur
1333
1488
 
1334
1489
  ### CRUD
1335
1490
 
1336
- | Limitation | Details |
1337
- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
1338
- | **UUID required for get/update/delete** | Alternate-key retrieval via `dataverse_get` is not supported; use `dataverse_upsert` or `dataverse_query` instead. |
1491
+ | Limitation | Details |
1492
+ | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
1493
+ | **UUID required for get/update/delete** | Alternate-key retrieval via `dataverse_get` is not supported; use `dataverse_upsert` or `dataverse_query` instead. |
1339
1494
  | **ETag conditional update** | `dataverse_update` supports optional `etag` parameter for optimistic concurrency (`If-Match: <etag>`). When omitted, sends `If-Match: *`. |
1340
1495
 
1341
1496
  ### Authentication
1342
1497
 
1343
- | Limitation | Details |
1344
- | ----------------------- | ---------------------------------------------------------------- |
1345
- | **Token expiry** | If the refresh token expires (~90 days), re-run `npm run auth:setup`. |
1498
+ | Limitation | Details |
1499
+ | ---------------- | --------------------------------------------------------------------- |
1500
+ | **Token expiry** | If the refresh token expires (~90 days), re-run `npm run auth:setup`. |
1346
1501
 
1347
1502
  ### Dependencies & Solutions
1348
1503
 
@@ -1360,4 +1515,4 @@ Certain tools include an `errorCategory` field in the error text when the failur
1360
1515
 
1361
1516
  ---
1362
1517
 
1363
- _This document reflects the MCP Dataverse server codebase as of v0.4.6 — 73 tools across 25 categories._
1518
+ _This document reflects the MCP Dataverse server codebase as of v0.5.0 — 73 tools across 25 categories._