mcp-dataverse 0.5.0 → 0.7.5

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 (13) hide show
  1. package/CAPABILITIES.md +270 -171
  2. package/README.md +33 -29
  3. package/dist/chunk-6KQIRQNP.js +35 -0
  4. package/dist/chunk-IA4YDPXM.js +35 -0
  5. package/dist/dataverse-client-advanced-54FU3FKK.js +1 -0
  6. package/dist/dataverse-client-advanced-CON7DMNS.js +1 -0
  7. package/dist/doctor.js +1 -1
  8. package/dist/http-server.js +6 -6
  9. package/dist/server.js +151 -15
  10. package/package.json +2 -2
  11. package/server.json +3 -3
  12. package/dist/chunk-FSM3J3WD.js +0 -35
  13. 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.5 | **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
+ 79 tools across 27 categories for full Dataverse lifecycle: schema, CRUD, FetchXML, solutions, plugins, audit, files, users, teams, RBAC, attribute management, environment variables, workflows, schema write, record access, 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 (79 tools)](#tool-reference-79-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,8 @@
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)
39
41
  - [Error Handling & Retry Behavior](#error-handling--retry-behavior)
40
42
  - [Security](#security)
41
43
  - [Limitations & Known Constraints](#limitations--known-constraints)
@@ -46,11 +48,11 @@
46
48
 
47
49
  ### Prerequisites
48
50
 
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 |
51
+ | Requirement | Details |
52
+ | ------------------------- | ------------------------------------------------ |
53
+ | **Node.js** | v20+ |
54
+ | **Dataverse Environment** | Active URL (`https://<org>.crm<N>.dynamics.com`) |
55
+ | **Authentication** | Device code flow (interactive) via MSAL |
54
56
 
55
57
  ### Installation & Configuration
56
58
 
@@ -68,11 +70,11 @@ Create `config.json` (see `config.example.json`):
68
70
  }
69
71
  ```
70
72
 
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`) |
73
+ | Field | Type | Description |
74
+ | ------------------ | -------- | ------------------------------------------------------- |
75
+ | `environmentUrl` | `string` | Dataverse environment URL (**required**, must be HTTPS) |
76
+ | `requestTimeoutMs` | `number` | HTTP timeout ms (default: `30000`) |
77
+ | `maxRetries` | `number` | Max retry attempts 0–10 (default: `3`) |
76
78
 
77
79
  Env vars override config: `DATAVERSE_ENV_URL`, `REQUEST_TIMEOUT_MS`, `MAX_RETRIES`.
78
80
 
@@ -95,7 +97,7 @@ Server communicates over **stdio** (MCP SDK `StdioServerTransport`). Connect fro
95
97
 
96
98
  ```mermaid
97
99
  graph LR
98
- MCP["MCP Dataverse Server<br/><i>73 tools · 25 categories</i>"]
100
+ MCP["MCP Dataverse Server<br/><i>79 tools · 27 categories</i>"]
99
101
 
100
102
  MCP --> AUTH["🔑 Auth (1)"]
101
103
  MCP --> META["📋 Metadata (9)"]
@@ -122,13 +124,15 @@ graph LR
122
124
  MCP --> WF["⚙️ Workflows (4)"]
123
125
  MCP --> ASSIST["🤖 Assistance (2)"]
124
126
  MCP --> ATTR["🏗️ Attributes (4)"]
127
+ MCP --> SCHEMA["📐 Schema write (2)"]
128
+ MCP --> ACCESS["🔐 Record Access (4)"]
125
129
  ```
126
130
 
127
131
  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
132
 
129
133
  ---
130
134
 
131
- ## Tool Reference (73 tools)
135
+ ## Tool Reference (79 tools)
132
136
 
133
137
  ### 1. Auth (1 tool)
134
138
 
@@ -225,6 +229,35 @@ Returns all labels and integer values for a table-specific Picklist, Status, or
225
229
 
226
230
  ---
227
231
 
232
+ #### `dataverse_resolve_entity_name`
233
+
234
+ 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`).
235
+
236
+ | Parameter | Type | Req | Notes |
237
+ | --------- | -------- | --- | ----------------------------------------------------- |
238
+ | `name` | `string` | ✓ | Entity name to resolve — logicalName or entitySetName |
239
+
240
+ > "What is the entitySetName for the 'account' entity?"
241
+
242
+ ---
243
+
244
+ #### `dataverse_update_entity`
245
+
246
+ 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.
247
+
248
+ | Parameter | Type | Req | Notes |
249
+ | ----------------------- | --------- | --- | -------------------------------------------------------------------- |
250
+ | `entityLogicalName` | `string` | ✓ | Logical name of the entity to update (e.g. `account`, `new_mytable`) |
251
+ | `confirm` | `boolean` | ✓ | Must be `true` — confirms intentional schema modification |
252
+ | `hasNotes` | `boolean` | – | Enable or disable Notes/Attachments for this entity |
253
+ | `changeTrackingEnabled` | `boolean` | – | Enable or disable change tracking (required for delta sync) |
254
+ | `isAuditEnabled` | `boolean` | – | Enable or disable auditing on this entity |
255
+ | `autoPublish` | `boolean` | – | Publish automatically after update (default: `false`) |
256
+
257
+ > "Enable notes/attachments on the 'new_myentity' table."
258
+
259
+ ---
260
+
228
261
  ### 3. Query (3 tools)
229
262
 
230
263
  #### `dataverse_query`
@@ -409,6 +442,39 @@ Removes an existing association. `relatedId` / `relatedEntitySetName` required f
409
442
 
410
443
  ---
411
444
 
445
+ #### `dataverse_associate_bulk`
446
+
447
+ 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.
448
+
449
+ | Parameter | Type | Req | Notes |
450
+ | ---------------------- | --------------- | --- | ------------------------------------- |
451
+ | `entitySetName` | `string` | ✓ | Source entity set name |
452
+ | `id` | `string (UUID)` | ✓ | Source record GUID |
453
+ | `relationshipName` | `string` | ✓ | Relationship schema name |
454
+ | `relatedEntitySetName` | `string` | ✓ | Related entity set name |
455
+ | `relatedIds` | `string[]` | ✓ | GUIDs of records to associate (1–200) |
456
+
457
+ > "Associate accounts a1b2, a3b4, and a5b6 with campaign record c1d2e3"
458
+
459
+ ---
460
+
461
+ #### `dataverse_query_associations`
462
+
463
+ 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`.
464
+
465
+ | Parameter | Type | Req | Notes |
466
+ | -------------------- | --------------- | --- | ----------------------------------------------------------- |
467
+ | `entitySetName` | `string` | ✓ | Source entity set name, e.g. `roles` |
468
+ | `id` | `string (UUID)` | ✓ | Source record GUID |
469
+ | `navigationProperty` | `string` | ✓ | Navigation property name, e.g. `roleprivileges_association` |
470
+ | `select` | `string` | – | Comma-separated columns to return on related records |
471
+ | `top` | `number` | – | Max records to return (default 50, max 1000) |
472
+ | `filter` | `string` | – | OData `$filter` expression applied to related records |
473
+
474
+ > "Check which privileges are linked to role r1a2b3c4 via the roleprivileges_association nav property"
475
+
476
+ ---
477
+
412
478
  ### 6. Actions & Functions (6 tools)
413
479
 
414
480
  #### `dataverse_execute_action`
@@ -537,43 +603,6 @@ Delta-query for incremental sync. Pass `deltaToken: null` for initial snapshot;
537
603
 
538
604
  ### 9. Solutions (2 tools)
539
605
 
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
606
  #### `dataverse_publish_customizations`
578
607
 
579
608
  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 +617,22 @@ Publishes unpublished customizations. Omit `components` to publish all (equivale
588
617
 
589
618
  ---
590
619
 
620
+ #### `dataverse_create_sitemap`
621
+
622
+ 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.
623
+
624
+ | Parameter | Type | Req | Notes |
625
+ | --------------------- | -------- | --- | ------------------------------------------------------------ |
626
+ | `sitemapName` | `string` | ✓ | Display name of the sitemap |
627
+ | `appModuleUniqueName` | `string` | — | Unique name of the model-driven app to link this sitemap to |
628
+ | `areas` | `array` | ✓ | One or more navigation areas (each with `title`, `groups[]`) |
629
+
630
+ Each area contains **groups**, each group contains **subareas** with optional `entityLogicalName`, `url`, `title`, and `id`.
631
+
632
+ > "Create a sitemap with a 'Sales' area containing an 'Accounts' subarea for entity 'account'"
633
+
634
+ ---
635
+
591
636
  ### 10. Impersonation (1 tool)
592
637
 
593
638
  #### `dataverse_impersonate`
@@ -672,6 +717,19 @@ Activates or deactivates a classic Dataverse workflow (statecode/statuscode upda
672
717
 
673
718
  ---
674
719
 
720
+ #### `dataverse_list_connection_references`
721
+
722
+ Lists connection references used in solutions (Power Automate connectors).
723
+
724
+ | Parameter | Type | Req | Notes |
725
+ | ------------ | -------- | --- | ------------------------------- |
726
+ | `top` | `number` | — | Default `50`, max `200` |
727
+ | `nameFilter` | `string` | — | Substring match on display name |
728
+
729
+ > "List all SharePoint connection references in my environment"
730
+
731
+ ---
732
+
675
733
  ### 12. Environment (4 tools)
676
734
 
677
735
  #### `dataverse_get_environment_variable`
@@ -713,20 +771,32 @@ Sets or updates an environment variable's current value (creates or updates the
713
771
 
714
772
  Creates a new Dataverse environment variable definition and sets its initial value. Use when the variable does not yet exist.
715
773
 
716
- | Parameter | Type | Req | Notes |
717
- | -------------- | ---------------------------------------- | --- | ------------------------------------------------------- |
774
+ | Parameter | Type | Req | Notes |
775
+ | -------------- | ---------------------------------------- | --- | --------------------------------------------------------- |
718
776
  | `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 |
777
+ | `displayName` | `string` | ✓ | Human-readable label |
778
+ | `type` | `"String"\|"Integer"\|"Boolean"\|"JSON"` | ✓ | Variable data type |
779
+ | `value` | `string` | ✓ | Initial value |
780
+ | `description` | `string` | — | Optional description |
781
+ | `defaultValue` | `string` | — | Optional default value |
782
+ | `confirm` | `true` | ✓ | Explicit confirmation required |
725
783
 
726
784
  > "Create environment variable new_MaxRetries of type Integer with value 3"
727
785
 
728
786
  ---
729
787
 
788
+ #### `dataverse_environment_capabilities`
789
+
790
+ 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.
791
+
792
+ | Parameter | Type | Req | Notes |
793
+ | --------- | ---- | --- | ---------------------- |
794
+ | _(none)_ | | | No parameters required |
795
+
796
+ > "Give me an overview of this Dataverse environment"
797
+
798
+ ---
799
+
730
800
  ### 13. Trace (2 tools)
731
801
 
732
802
  #### `dataverse_get_plugin_trace_logs`
@@ -935,7 +1005,7 @@ Lists saved (system) and optionally personal views for a Dataverse table, includ
935
1005
 
936
1006
  #### `dataverse_upload_file_column`
937
1007
 
938
- Uploads a file to a Dataverse **file-type column** on a record. File content must be base64-encoded.
1008
+ Uploads a file to a Dataverse **file or image column** on a record. File content must be base64-encoded.
939
1009
 
940
1010
  | Parameter | Type | Req | Notes |
941
1011
  | --------------- | --------------- | --- | ------------------------------------------------------- |
@@ -961,7 +1031,7 @@ Uploads a file to a Dataverse **file-type column** on a record. File content mus
961
1031
 
962
1032
  #### `dataverse_download_file_column`
963
1033
 
964
- Downloads a file from a Dataverse file-type column. Returns the file as a base64-encoded string with its name and size.
1034
+ Downloads a file from a Dataverse file or image column. Returns the file as a base64-encoded string with its name and size.
965
1035
 
966
1036
  | Parameter | Type | Req | Notes |
967
1037
  | --------------- | --------------- | --- | ------------------------ |
@@ -1000,11 +1070,11 @@ Lists business units in the environment with name, ID, parent BU ID, disabled st
1000
1070
 
1001
1071
  Lists Dataverse teams (owner teams and access teams) within one or all business units.
1002
1072
 
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 |
1073
+ | Parameter | Type | Req | Notes |
1074
+ | ---------------- | -------------------------- | --- | --------------------------------- |
1075
+ | `top` | `number` | — | Default `50`, max `200` |
1076
+ | `teamType` | `"Owner"\|"Access"\|"AAD"` | — | Filter by team type; omit for all |
1077
+ | `businessUnitId` | `string (UUID)` | — | Filter by business unit |
1008
1078
 
1009
1079
  > "List all owner teams in the environment"
1010
1080
 
@@ -1036,10 +1106,10 @@ Lists security roles in the environment, optionally filtered by name.
1036
1106
 
1037
1107
  Assigns a security role to a system user (idempotent — returns `"already_assigned"` if the role is already assigned).
1038
1108
 
1039
- | Parameter | Type | Req | Notes |
1040
- | --------- | --------------- | --- | ----------------- |
1041
- | `userId` | `string (UUID)` | ✓ | System user GUID |
1042
- | `roleId` | `string (UUID)` | ✓ | Security role ID |
1109
+ | Parameter | Type | Req | Notes |
1110
+ | --------- | --------------- | --- | ---------------- |
1111
+ | `userId` | `string (UUID)` | ✓ | System user GUID |
1112
+ | `roleId` | `string (UUID)` | ✓ | Security role ID |
1043
1113
 
1044
1114
  > "Assign role r1s2t3u4 to user u1v2w3x4"
1045
1115
 
@@ -1072,17 +1142,59 @@ Assigns a security role to a Dataverse team. All team members inherit the role p
1072
1142
 
1073
1143
  ---
1074
1144
 
1145
+ #### `dataverse_get_role_privileges`
1146
+
1147
+ 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.
1148
+
1149
+ | Parameter | Type | Req | Notes |
1150
+ | --------- | --------------- | --- | ------------------------- |
1151
+ | `roleId` | `string (UUID)` | ✓ | GUID of the security role |
1152
+
1153
+ > "What privileges does role r1s2t3u4 currently have?"
1154
+
1155
+ ---
1156
+
1157
+ #### `dataverse_add_role_privileges`
1158
+
1159
+ 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.
1160
+
1161
+ | Parameter | Type | Req | Notes |
1162
+ | ----------------------------- | --------------- | --- | ---------------------------------------------------------------- |
1163
+ | `roleId` | `string (UUID)` | ✓ | GUID of the security role |
1164
+ | `privileges` | `array` | ✓ | Array of `{ privilegeId, depth, businessUnitId? }` entries (1–N) |
1165
+ | `privileges[].privilegeId` | `string (UUID)` | ✓ | GUID — query `privileges` entity to find by name or entity |
1166
+ | `privileges[].depth` | `string` | ✓ | `None`, `Basic`, `Local`, `Deep`, or `Global` |
1167
+ | `privileges[].businessUnitId` | `string (UUID)` | — | Defaults to root BU if omitted |
1168
+
1169
+ > "Add prvReadAccount with Global depth to role r1s2t3u4"
1170
+
1171
+ ---
1172
+
1173
+ #### `dataverse_replace_role_privileges`
1174
+
1175
+ 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.
1176
+
1177
+ | Parameter | Type | Req | Notes |
1178
+ | ------------ | --------------- | --- | ----------------------------------------------------------------- |
1179
+ | `roleId` | `string (UUID)` | ✓ | GUID of the security role |
1180
+ | `privileges` | `array` | ✓ | Complete new privilege set (same schema as `add_role_privileges`) |
1181
+ | `confirm` | `true` | ✓ | Required — replaces all existing privileges on the role |
1182
+
1183
+ > "Replace all privileges on role r1s2t3u4 with a custom set"
1184
+
1185
+ ---
1186
+
1075
1187
  ### 23. Workflows (4 tools)
1076
1188
 
1077
1189
  #### `dataverse_list_workflows`
1078
1190
 
1079
1191
  Lists classic Dataverse workflows and modern cloud flows registered in the environment.
1080
1192
 
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 |
1193
+ | Parameter | Type | Req | Notes |
1194
+ | ------------ | --------- | --- | ------------------------------------------------- |
1195
+ | `top` | `number` | — | Default `50`, max `200` |
1196
+ | `activeOnly` | `boolean` | — | Return only activated workflows (default `false`) |
1197
+ | `nameFilter` | `string` | — | Substring match on workflow name |
1086
1198
 
1087
1199
  > "List all active workflows on the account table"
1088
1200
 
@@ -1100,27 +1212,12 @@ Retrieves a single workflow definition by ID, including its trigger, steps, and
1100
1212
 
1101
1213
  ---
1102
1214
 
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
1215
  #### `dataverse_list_guides`
1119
1216
 
1120
1217
  Lists available built-in guides that walk through common multi-step Dataverse tasks.
1121
1218
 
1122
- | Parameter | Type | Req | Notes |
1123
- | --------- | ---- | --- | ----- |
1219
+ | Parameter | Type | Req | Notes |
1220
+ | --------- | ---- | --- | ------------- |
1124
1221
  | — | — | — | No parameters |
1125
1222
 
1126
1223
  > "What guides are available in this MCP server?"
@@ -1131,24 +1228,26 @@ Lists available built-in guides that walk through common multi-step Dataverse ta
1131
1228
 
1132
1229
  Retrieves the full step-by-step content for a specific guide by name.
1133
1230
 
1134
- | Parameter | Type | Req | Notes |
1135
- | ----------- | -------- | --- | ------------------- |
1231
+ | Parameter | Type | Req | Notes |
1232
+ | ----------- | -------- | --- | ----------------------------- |
1136
1233
  | `guideName` | `string` | ✓ | Guide name from `list_guides` |
1137
1234
 
1138
1235
  > "Show me the steps for the entity-audit guide"
1139
1236
 
1140
1237
  ---
1141
1238
 
1142
- #### `dataverse_list_connection_references`
1239
+ ### 24. Assistance (2 tools)
1143
1240
 
1144
- Lists connection references used in solutions (Power Automate connectors).
1241
+ #### `dataverse_suggest_tools`
1242
+
1243
+ 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.
1145
1244
 
1146
- | Parameter | Type | Req | Notes |
1147
- | -------------- | -------- | --- | -------------------------------- |
1148
- | `top` | `number` | — | Default `50`, max `200` |
1149
- | `nameFilter` | `string` | — | Substring match on display name |
1245
+ | Parameter | Type | Req | Notes |
1246
+ | --------- | -------- | --- | ---------------------------------------- |
1247
+ | `task` | `string` | ✓ | Natural-language description of the task |
1248
+ | `top` | `number` | — | Max results (default `5`) |
1150
1249
 
1151
- > "List all SharePoint connection references in my environment"
1250
+ > "Which tool should I use to create a new lookup column?"
1152
1251
 
1153
1252
  ---
1154
1253
 
@@ -1172,24 +1271,24 @@ Attribute tools manage **column-level schema** in Dataverse tables. All write op
1172
1271
 
1173
1272
  Creates a new column on an existing Dataverse table. Supports 11 attribute types with type-specific parameters.
1174
1273
 
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` |
1274
+ | Parameter | Type | Req | Notes |
1275
+ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --- | -------------------------------------------------------- |
1276
+ | `entityLogicalName` | `string` | ✓ | Target table (e.g. `"account"`) |
1277
+ | `schemaName` | `string` | ✓ | Must include publisher prefix (e.g. `"new_CustomField"`) |
1278
+ | `attributeType` | `"String"\|"Memo"\|"Integer"\|"Decimal"\|"Money"\|"DateTime"\|"Boolean"\|"Picklist"\|"MultiSelectPicklist"\|"AutoNumber"\|"Image"` | ✓ | Column type |
1279
+ | `displayName` | `string` | ✓ | Human-readable label |
1280
+ | `description` | `string` | — | Column description |
1281
+ | `requiredLevel` | `"None"\|"ApplicationRequired"\|"Recommended"` | — | Requirement level (default `"None"`) |
1282
+ | `maxLength` | `number` | — | String/Memo max chars |
1283
+ | `minValue`/`maxValue` | `number` | — | Integer/Decimal range bounds |
1284
+ | `precision` | `number` | — | Decimal/Money decimal places |
1285
+ | `dateTimeFormat` | `"DateOnly"\|"DateAndTime"` | — | DateTime display format |
1286
+ | `defaultBooleanValue` | `boolean` | — | Default for Boolean columns |
1287
+ | `picklistOptions` | `{value: number, label: string}[]` | — | Option values for Picklist/MultiSelectPicklist |
1288
+ | `autoNumberFormat` | `string` | — | Format string for AutoNumber, e.g. `"INV-{SEQNUM:5}"` |
1289
+ | `languageCode` | `number` | — | Label language code (default `1033` = English) |
1290
+ | `autoPublish` | `boolean` | — | Publish after create (default `true`) |
1291
+ | `confirm` | `true` | ✓ | Must be `true` |
1193
1292
 
1194
1293
  > "Add a text column 'new_ExternalId' to the account table with max 100 characters"
1195
1294
 
@@ -1209,18 +1308,18 @@ Creates a new column on an existing Dataverse table. Supports 11 attribute types
1209
1308
 
1210
1309
  Updates properties of an existing column. Only columns with `IsCustomizable = true` can be modified.
1211
1310
 
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` |
1311
+ | Parameter | Type | Req | Notes |
1312
+ | ---------------------- | ---------------------------------------------- | --- | ------------------------------------------ |
1313
+ | `entityLogicalName` | `string` | ✓ | Table containing the column |
1314
+ | `attributeLogicalName` | `string` | ✓ | Column logical name (e.g. `"new_myfield"`) |
1315
+ | `displayName` | `string` | — | New display label |
1316
+ | `description` | `string` | — | New description |
1317
+ | `requiredLevel` | `"None"\|"ApplicationRequired"\|"Recommended"` | — | New requirement level |
1318
+ | `maxLength` | `number` | — | Increase only (cannot decrease) |
1319
+ | `isSearchable` | `boolean` | — | Include in Quick Find views |
1320
+ | `languageCode` | `number` | — | Default `1033` |
1321
+ | `autoPublish` | `boolean` | — | Default `true` |
1322
+ | `confirm` | `true` | ✓ | Must be `true` |
1224
1323
 
1225
1324
  > "Update new_externalid on account to be required"
1226
1325
 
@@ -1230,12 +1329,12 @@ Updates properties of an existing column. Only columns with `IsCustomizable = tr
1230
1329
 
1231
1330
  ⚠️ **DESTRUCTIVE** — permanently deletes a custom column and all its data from all records.
1232
1331
 
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` |
1332
+ | Parameter | Type | Req | Notes |
1333
+ | ---------------------- | --------- | --- | --------------------------------------------- |
1334
+ | `entityLogicalName` | `string` | ✓ | Table containing the column |
1335
+ | `attributeLogicalName` | `string` | ✓ | Column logical name (must be a custom column) |
1336
+ | `autoPublish` | `boolean` | — | Publish after delete (default `true`) |
1337
+ | `confirm` | `true` | ✓ | Must be `true` |
1239
1338
 
1240
1339
  > "Delete the column new_externalid from account"
1241
1340
 
@@ -1245,17 +1344,17 @@ Updates properties of an existing column. Only columns with `IsCustomizable = tr
1245
1344
 
1246
1345
  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
1346
 
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` |
1347
+ | Parameter | Type | Req | Notes |
1348
+ | ------------------- | ---------------------------------------------- | --- | ----------------------------------------------------------- |
1349
+ | `entityLogicalName` | `string` | ✓ | Table that will contain the lookup column (the "many" side) |
1350
+ | `schemaName` | `string` | ✓ | Must include publisher prefix (e.g. `"new_ParentAccount"`) |
1351
+ | `displayName` | `string` | ✓ | Human-readable label |
1352
+ | `referencedEntity` | `string` | ✓ | Table being looked up (the "one" side, e.g. `"account"`) |
1353
+ | `description` | `string` | — | Column description |
1354
+ | `requiredLevel` | `"None"\|"ApplicationRequired"\|"Recommended"` | — | Default `"None"` |
1355
+ | `languageCode` | `number` | — | Default `1033` |
1356
+ | `autoPublish` | `boolean` | — | Default `true` |
1357
+ | `confirm` | `true` | ✓ | Must be `true` |
1259
1358
 
1260
1359
  > "Add a lookup to 'account' on the contact table called new_PrimaryAccount"
1261
1360
 
@@ -1289,26 +1388,26 @@ Dataverse error bodies are formatted as `Dataverse error <code>: <message>`. Tim
1289
1388
 
1290
1389
  Certain tools include an `errorCategory` field in the error text when the failure has a well-known cause:
1291
1390
 
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` |
1391
+ | `errorCategory` | Meaning | Example |
1392
+ | ----------------- | -------------------------------------------------------- | ---------------------------------------------------- |
1393
+ | `ENV_LIMITATION` | Feature not enabled or unavailable in this environment | `dataverse_search` when Relevance Search is disabled |
1394
+ | `PERMISSIONS` | Operation denied due to insufficient privileges | Restricted table or action |
1395
+ | `SCHEMA_MISMATCH` | Supplied data conflicts with the table's metadata schema | Wrong attribute type in `dataverse_create_attribute` |
1297
1396
 
1298
1397
  ---
1299
1398
 
1300
1399
  ## Security
1301
1400
 
1302
- | Mode | Flow | Use Case |
1303
- | ----------------- | ------------------------------------------------- | ---------------------- |
1304
- | **Device Code** | MSAL Public Client → device code + silent refresh | Local dev, interactive |
1401
+ | Mode | Flow | Use Case |
1402
+ | --------------- | ------------------------------------------------- | ---------------------- |
1403
+ | **Device Code** | MSAL Public Client → device code + silent refresh | Local dev, interactive |
1305
1404
 
1306
1405
  - `clientSecret` is never logged or returned in tool responses.
1307
1406
  - Token cache is encrypted (AES-256-GCM) at `~/.mcp-dataverse/` and should not be shared.
1308
1407
  - OData path segments use `esc()` (single-quote doubling) to prevent OData injection.
1309
1408
  - `columnName` in file tools is validated against `/^[a-zA-Z0-9_]+$/` to prevent path traversal.
1310
1409
  - `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).
1410
+ - `.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
1411
 
1313
1412
  ---
1314
1413
 
@@ -1316,12 +1415,12 @@ Certain tools include an `errorCategory` field in the error text when the failur
1316
1415
 
1317
1416
  ### General
1318
1417
 
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. |
1418
+ | Limitation | Details |
1419
+ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
1420
+ | **Transport** | stdio (default) and HTTP/SSE. stdio: spawned as child process. HTTP: run as standalone service on configurable port. |
1421
+ | **Single environment** | One Dataverse environment per server instance. Restart to switch. |
1422
+ | **No streaming** | Responses are complete JSON. Very large result sets may exceed AI model context limits. |
1423
+ | **No real-time subscriptions** | Use `dataverse_change_detection` for polling-based incremental sync. |
1325
1424
 
1326
1425
  ### Query
1327
1426
 
@@ -1333,16 +1432,16 @@ Certain tools include an `errorCategory` field in the error text when the failur
1333
1432
 
1334
1433
  ### CRUD
1335
1434
 
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. |
1435
+ | Limitation | Details |
1436
+ | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
1437
+ | **UUID required for get/update/delete** | Alternate-key retrieval via `dataverse_get` is not supported; use `dataverse_upsert` or `dataverse_query` instead. |
1339
1438
  | **ETag conditional update** | `dataverse_update` supports optional `etag` parameter for optimistic concurrency (`If-Match: <etag>`). When omitted, sends `If-Match: *`. |
1340
1439
 
1341
1440
  ### Authentication
1342
1441
 
1343
- | Limitation | Details |
1344
- | ----------------------- | ---------------------------------------------------------------- |
1345
- | **Token expiry** | If the refresh token expires (~90 days), re-run `npm run auth:setup`. |
1442
+ | Limitation | Details |
1443
+ | ---------------- | --------------------------------------------------------------------- |
1444
+ | **Token expiry** | If the refresh token expires (~90 days), re-run `npm run auth:setup`. |
1346
1445
 
1347
1446
  ### Dependencies & Solutions
1348
1447
 
@@ -1360,4 +1459,4 @@ Certain tools include an `errorCategory` field in the error text when the failur
1360
1459
 
1361
1460
  ---
1362
1461
 
1363
- _This document reflects the MCP Dataverse server codebase as of v0.4.6 — 73 tools across 25 categories._
1462
+ _This document reflects the MCP Dataverse server codebase as of v0.5.0 — 73 tools across 25 categories._