v0.3.7: docs site, 23 bug fixes, schema roadmap

Documentation:
- GitHub Pages site (Jekyll + Just the Docs dark theme)
- New pages: Getting Started, Roadmap, Community, Capabilities, 5 Use-Case guides
- Roadmap v0.4 expanded: HTTP transport + schema consistency reinforcement
- Upcoming auth methods documented (Azure AD, Managed Identity)
- CHANGELOG backfilled v0.2.0 through v0.3.7

Bug fixes (sessions 1-8, 23 fixes):
- BUG-021: HasNotes as plain boolean, BooleanManagedProperty handling
- BUG-022/023: Idempotent RBAC (role assign/remove with pre-check)
- BUG-024: FetchXML entity set resolution
- ETag-based optimistic concurrency for updates
- Guardrails: confirm param on all destructive operations
- Structured JSON errors with actionable suggestions
- 482/482 tests passing

Author: Dev Agent Amelia

.env.example

@@ -1,15 +1,20 @@
 # MCP Dataverse Configuration
 # Set these environment variables (or use config.json for local dev)
 
+# Required: your Dataverse / Power Platform environment URL
 DATAVERSE_ENV_URL=https://yourorg.crm.dynamics.com
-AUTH_MODE=pac
-PAC_PROFILE_NAME=default
 
-# MSAL client credentials (required if AUTH_MODE=msal)
-TENANT_ID=
-CLIENT_ID=
-CLIENT_SECRET=
+# Optional: path to a config.json file (overrides DATAVERSE_ENV_URL)
+# MCP_CONFIG_PATH=/home/you/.mcp-dataverse/config.json
 
 # Tuning (optional)
 # REQUEST_TIMEOUT_MS=30000
 # MAX_RETRIES=3
+
+# ── Authentication ────────────────────────────────────────────────────────────
+# No credentials are required here.
+# Authentication uses the Microsoft Device Code Flow (MSAL):
+#   1. Run: npx mcp-dataverse install   (or npx mcp-dataverse-auth)
+#   2. Open the URL shown in the terminal and enter the displayed code
+#   3. Sign in with your Microsoft / Power Platform account
+# The token is cached in ~/.mcp-dataverse/msal-cache.json and reused silently.

.github/workflows/pages.yml

@@ -0,0 +1,50 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'docs/**'
+      - 'CAPABILITIES.md'
+      - 'CHANGELOG.md'
+      - 'assets/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Build with Jekyll
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./docs
+          destination: ./_site
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -9,6 +9,7 @@ config.json
 .DS_Store
 coverage/
 
+
 # Test artifacts
 test-output.txt
 *.local
@@ -24,6 +25,7 @@ scripts/
 mcp-template/
 autoparc/
 assets/
+debug/
 !assets/logo.webp
 
 # Private planning & internal artifacts (security/privacy)
@@ -35,6 +37,7 @@ refine.md
 refinev2.md
 refinev3.md
 PUBLISHING.md
+ROADMAP-PERSONAL.md
 
 # Internal IDE/workflow configs
 .vscode/mcp.json

CAPABILITIES.md

@@ -1,16 +1,16 @@
 # MCP Dataverse Server — Complete Capabilities Reference
 
-> **Version**: 0.3.2 | **API Version**: Dataverse Web API v9.2 | **Transport**: stdio · HTTP/SSE
+> **Version**: 0.3.6 | **API Version**: Dataverse Web API v9.2 | **Transport**: stdio · HTTP/SSE
 
-54 tools across 23 categories for full Dataverse lifecycle: schema, CRUD, FetchXML, solutions, plugins, audit, files, users, teams, environment variables, and more.
+63 tools across 24 categories for full Dataverse lifecycle: schema, CRUD, FetchXML, solutions, plugins, audit, files, users, teams, RBAC, environment variables, workflows, and more.
 
 ---
 
 ## Table of Contents
 
 - [Quick Start](#quick-start)
 - [Architecture Overview](#architecture-overview)
-- [Tool Reference (54 tools)](#tool-reference-54-tools)
+- [Tool Reference (63 tools)](#tool-reference-63-tools)
   - [1. Auth (1)](#1-auth-1-tool)
   - [2. Metadata (8)](#2-metadata-8-tools)
   - [3. Query (3)](#3-query-3-tools)
@@ -91,7 +91,7 @@ Server communicates over **stdio** (MCP SDK `StdioServerTransport`). Connect fro
 
 ```mermaid
 graph LR
-    MCP["MCP Dataverse Server<br/><i>54 tools · 23 categories</i>"]
+    MCP["MCP Dataverse Server<br/><i>63 tools · 24 categories</i>"]
 
     MCP --> AUTH["🔑 Auth (1)"]
     MCP --> META["📋 Metadata (8)"]
@@ -122,7 +122,7 @@ All tool handlers validate inputs with **Zod** before calling the `DataverseAdva
 
 ---
 
-## Tool Reference (50 tools)
+## Tool Reference (63 tools)
 
 ### 1. Auth (1 tool)
 
@@ -1012,7 +1012,7 @@ Dataverse error bodies are formatted as `Dataverse error <code>: <message>`. Tim
 | Limitation                              | Details                                                                                                            |
 | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
 | **UUID required for get/update/delete** | Alternate-key retrieval via `dataverse_get` is not supported; use `dataverse_upsert` or `dataverse_query` instead. |
-| **No ETag conditional update**          | `dataverse_update` sends `If-Match: *`. ETag-based optimistic concurrency is not exposed.                          |
+| **ETag conditional update**             | `dataverse_update` supports optional `etag` parameter for optimistic concurrency (`If-Match: <etag>`). When omitted, sends `If-Match: *`. |
 
 ### Authentication
 
@@ -1036,4 +1036,4 @@ Dataverse error bodies are formatted as `Dataverse error <code>: <message>`. Tim
 
 ---
 
-_This document reflects the MCP Dataverse server codebase as of v0.2.0 — 50 tools across 22 categories._
+_This document reflects the MCP Dataverse server codebase as of v0.3.6 — 63 tools across 24 categories._

CHANGELOG.md

@@ -5,7 +5,112 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) — [Semantic V
 
 ---
 
-## [0.2.0] — Unreleased
+## [0.3.7] — 2026-03-02
+
+### Added
+
+- **GitHub Pages documentation site** — full Jekyll + Just the Docs theme at `codeurali.github.io/mcp-dataverse`
+- New doc pages: Getting Started, Roadmap, Community, Capabilities, 5 Use-Case guides
+- **Roadmap v0.4** expanded with schema consistency reinforcement (parameter naming, `errorCategory`, preflight checks)
+- **Upcoming auth methods** documented — Azure AD (Client Credentials) and Managed Identity planned, architecture confirmed ready
+
+### Changed
+
+- CAPABILITIES.md updated to 63 tools, version alignment, ETag fix documented
+- README.md refreshed with new docs site URLs and community links
+- CHANGELOG backfilled with all versions from v0.2.0 through v0.3.6
+
+---
+
+## [0.3.6] — 2026-03-02
+
+### Fixed
+
+- **BUG-021 final fix** — `dataverse_update_entity`: `HasNotes` now sent as plain `boolean` (was incorrectly wrapped in `{ Value: bool }` — Dataverse expects `Edm.Boolean`, not `BooleanManagedProperty`)
+- `dataverse_update_entity`: graceful error handling for `0x80060888` — returns structured JSON with actionable suggestions (e.g. enable org-level audit) instead of raw exception
+- `IsAuditEnabled` / `ChangeTrackingEnabled` both return clear guidance when the operation is blocked at org level
+
+---
+
+## [0.3.5] — 2026-03-01
+
+### Fixed
+
+- **BUG-021** — `dataverse_update_entity`: `IsAuditEnabled` wrapped as `BooleanManagedProperty` (`{ Value: bool }`); `@odata.type: "#Microsoft.Dynamics.CRM.EntityMetadata"` added to PATCH body
+- **BUG-022** — `dataverse_assign_role_to_user`: idempotence now functional — pre-check via `$expand=systemuserroles_association` before `associate`; returns `"already_assigned"` if role already present
+- **BUG-023** — `dataverse_remove_role_from_user`: idempotence now functional — pre-check before `disassociate`; returns `"not_assigned"` if role absent
+
+---
+
+## [0.3.4] — 2026-03-01
+
+### Added
+
+- `dataverse_list_connection_references` — list Connection References in the environment (active/inactive count, connector details)
+
+---
+
+## [0.3.3] — 2026-03-01
+
+### Added
+
+- `dataverse_list_roles` — list Dataverse security roles with optional `nameContains` filter
+- `dataverse_assign_role_to_user` — assign a security role to a user (`confirm: true` required)
+- `dataverse_remove_role_from_user` — remove a security role from a user (`confirm: true` required)
+
+---
+
+## [0.3.2] — 2026-03-01
+
+### Added
+
+- `dataverse_update_entity` — modify entity metadata flags (HasNotes, ChangeTracking, Audit) with `confirm: true` required; auto-publishes by default
+- `dataverse_create_environment_variable` — create an environment variable definition + value in Dataverse (`confirm: true` required)
+- **Write guardrails** — `checkWriteGuardrails` on destructive tools surfaces `[WARN] DESTRUCTIVE_OP` in `data.warnings[]`
+
+---
+
+## [0.3.1] — 2026-03-01
+
+### Fixed
+
+- **BUG-018** — `dataverse_query`: `count=true` now shows total in summary (`"N records returned from X (total in dataset: Y)"`)
+- **BUG-019** — `dataverse_get`: `expand` parameter now properly forwarded to `getRecord` (was silently ignored)
+- **BUG-020** — `formattedValues: true` parameter added to `dataverse_query`, `dataverse_get`, `dataverse_execute_fetchxml`, `dataverse_retrieve_multiple_with_paging` — transmits `Prefer: odata.include-annotations` header; picklist fields return `{ value, label }` objects
+
+### Added
+
+- **Query guardrails** — `checkQueryGuardrails` surfaces warnings in response: `[WARN] NO_SELECT`, `[INFO] NO_FILTER`, `[WARN] LARGE_RESULT_SET`
+
+---
+
+## [0.3.0] — 2026-03-01
+
+### Added
+
+- `dataverse_list_workflows` — **reimplemented**: queries the real Dataverse `workflows` entity (Cloud Flows, Business Rules, Classic Workflows); supports `category`, `nameContains`, `top` parameters
+- `dataverse_get_workflow` — **reimplemented**: retrieves a Dataverse Process by GUID with enriched `categoryLabel` / `stateLabel`
+- `dataverse_list_guides` — new tool replacing old `list_workflows` behavior (lists 10 built-in MCP operational guides)
+- `dataverse_get_guide` — new tool replacing old `get_workflow` behavior (returns step-by-step MCP guide by name)
+
+### Fixed
+
+- **BUG-013** — `dataverse_get_attribute_option_set`: summary showed "0 options" — handler used `Options` (PascalCase) but client returns `options` (camelCase)
+- **BUG-014** — `dataverse_list_dependencies`: summary showed "1 dependencies" — fallback wrapped entire result object; now reads `count` directly
+- **BUG-015** — `dataverse_retrieve_multiple_with_paging`: summary showed "X records across 1 pages" — used `result.pages` instead of `result.pageCount`
+- `dataverse_publish_customizations`: added 120 s timeout for `PublishAllXml` / `PublishXml` (previously timed out on large solutions)
+- `dataverse_list_users`: removed `.refine()` — all parameters now truly optional
+- `dataverse_batch_execute`: summary now correctly shows `"2/2 operations succeeded"` instead of `"0/N"`
+- `dataverse_solution_components`: summary count now accurate
+- `dataverse_create_annotation`: actionable error message when `HasNotes=false` (instructions to enable Notes in Power Apps maker portal)
+
+### Improved
+
+- Enriched error messages across 6 tools: `get_environment_variable`, `set_workflow_state`, `execute_action`, `execute_bound_action`, `execute_bound_function`, `change_detection`
+
+---
+
+## [0.2.0] — 2026-02-28
 
 ### Added
 

README.md

@@ -6,15 +6,15 @@
 
 **The most complete MCP server for Microsoft Dataverse.**
 
-54 tools · 4 resources · 10 guided workflows · Zero config auth
+63 tools · 4 resources · 10 guided workflows · Zero config auth
 
 [![npm](https://img.shields.io/npm/v/mcp-dataverse)](https://www.npmjs.com/package/mcp-dataverse)
 [![npm downloads](https://img.shields.io/npm/dm/mcp-dataverse)](https://www.npmjs.com/package/mcp-dataverse)
 [![Node 20+](https://img.shields.io/badge/Node.js-20%2B-green)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue)](https://www.typescriptlang.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
 
-**[→ Full Documentation](https://codeurali.github.io/mcp-dataverse-docs)**
+**[→ Full Documentation](https://codeurali.github.io/mcp-dataverse)**
 
 </div>
 
@@ -41,7 +41,7 @@ npx mcp-dataverse install
 
 The interactive wizard configures your environment, registers the server in VS Code, and authenticates your Microsoft account in under 2 minutes.
 
-> Requires Node.js 20+. For other clients (Claude, Cursor, Windsurf…) see [Multi-Client Setup](https://codeurali.github.io/mcp-dataverse-docs/multi-client-setup).
+> Requires Node.js 20+. For other clients (Claude, Cursor, Windsurf…) see [Multi-Client Setup](https://codeurali.github.io/mcp-dataverse/multi-client-setup).
 
 ---
 
@@ -59,33 +59,52 @@ Re-authenticate after ~90 days of inactivity: `npx mcp-dataverse-auth`
 
 ## Capabilities
 
-| Category | Count | Description |
-|----------|-------|-------------|
-| **Metadata** | 8 | Tables, schema, relationships, option sets, entity keys |
-| **Query** | 3 | OData, FetchXML, paginated retrieval |
-| **CRUD** | 6 | Get, create, update, delete, upsert, assign |
-| **Actions & Functions** | 6 | Bound/unbound Dataverse actions and functions |
-| **Batch** | 1 | Up to 1000 operations atomically |
-| **Solutions** | 3 | List solutions, components, publish customizations |
-| **Search** | 1 | Full-text Relevance Search |
-| **Users & Teams** | 3 | Users, roles, teams |
-| **Files** | 2 | Upload/download file and image columns |
-| **+ more** | … | Audit, trace logs, delta tracking, impersonation, annotations… |
-| **Assistance** | 4 | Tool router, workflow guide |
-
-[→ Full Capabilities Reference](https://codeurali.github.io/mcp-dataverse-docs/capabilities)
+| Category                | Count | Description                                                    |
+| ----------------------- | ----- | -------------------------------------------------------------- |
+| **Metadata**            | 8     | Tables, schema, relationships, option sets, entity keys        |
+| **Query**               | 3     | OData, FetchXML, paginated retrieval                           |
+| **CRUD**                | 6     | Get, create, update, delete, upsert, assign                    |
+| **Actions & Functions** | 6     | Bound/unbound Dataverse actions and functions                  |
+| **Batch**               | 1     | Up to 1000 operations atomically                               |
+| **Solutions**           | 3     | List solutions, components, publish customizations             |
+| **Search**              | 1     | Full-text Relevance Search                                     |
+| **Users & Teams**       | 3     | Users, roles, teams                                            |
+| **Files**               | 2     | Upload/download file and image columns                         |
+| **+ more**              | …     | Audit, trace logs, delta tracking, impersonation, annotations… |
+| **Assistance**          | 4     | Tool router, workflow guide                                    |
+
+[→ Full Capabilities Reference](https://codeurali.github.io/mcp-dataverse/capabilities)
 
 ---
 
 ## Troubleshooting
 
-| Symptom | Fix |
-|---------|-----|
-| No sign-in prompt | Open **View → Output → MCP** — the device code is displayed there |
-| `No MSAL accounts found` | Run `npx mcp-dataverse-auth` then restart the server |
-| `Authentication timed out` | 5-minute window expired — restart MCP for a new code |
-| Server not appearing in Agent mode | Run `npx mcp-dataverse install` or `npx mcp-dataverse doctor` |
-| HTTP errors | Run `npx mcp-dataverse doctor` to diagnose config and connectivity |
+| Symptom                            | Fix                                                                |
+| ---------------------------------- | ------------------------------------------------------------------ |
+| No sign-in prompt                  | Open **View → Output → MCP** — the device code is displayed there  |
+| `No MSAL accounts found`           | Run `npx mcp-dataverse-auth` then restart the server               |
+| `Authentication timed out`         | 5-minute window expired — restart MCP for a new code               |
+| Server not appearing in Agent mode | Run `npx mcp-dataverse install` or `npx mcp-dataverse doctor`      |
+| HTTP errors                        | Run `npx mcp-dataverse doctor` to diagnose config and connectivity |
+
+---
+
+## Battle-Tested
+
+All 63 tools tested on a real Dataverse production environment across 8 live sessions — **55 ✅ · 9 ⚠️ · 1 ❌ (env-specific)**. [Details & test results →](https://codeurali.github.io/mcp-dataverse/community)
+
+---
+
+## Roadmap
+
+| Version | Feature | Status |
+| ------- | ------- | ------ |
+| **v0.4** | Streamable HTTP transport | 🟢 90% done |
+| **v0.5** | MCP Resources — browsable schema | 🟡 40% done |
+| **v0.6** | MCP Prompts — workflow templates | 🔴 Planned |
+| **v1.0** | On-Behalf-Of auth (OBO) | 🔴 Planned |
+
+[→ Full Roadmap](https://codeurali.github.io/mcp-dataverse/roadmap)
 
 ---
 

dist/dataverse/dataverse-client-advanced.d.ts

@@ -43,5 +43,11 @@ export declare class DataverseAdvancedClient extends DataverseBatchClient {
         published: boolean;
         message: string;
     }>;
+    listDataverseWorkflows(params: {
+        category?: number;
+        top?: number;
+        nameContains?: string;
+    }): Promise<Record<string, unknown>[]>;
+    getDataverseWorkflow(workflowId: string): Promise<Record<string, unknown>>;
 }
 //# sourceMappingURL=dataverse-client-advanced.d.ts.map