Skip to content

Commit d8fec8f

Browse files
author
Dev Agent Amelia
committed
v0.3.0: MCP annotations, structured outputs, HTTP transport, doctor CLI, tool registry, docs
- Refactor: Map-based O(1) tool routing (tool-registry.ts) replacing if-chain - Feature: MCP annotations on all 50 tools (readOnlyHint, destructiveHint, etc.) - Feature: Structured outputs {summary, data, suggestions} on all handlers - Feature: Global SERVER_INSTRUCTIONS in capabilities handshake - Feature: HTTP/SSE transport (--transport http --port 3001) - Feature: Doctor CLI for pre-flight diagnostics (npx mcp-dataverse doctor) - Docs: Getting started, multi-client setup, 5 use-case guides - Add: AutoParc project (spec + setup script for Dataverse automotive fleet DB) - Tests: All 412 tests updated and passing
1 parent 1847930 commit d8fec8f

65 files changed

Lines changed: 4507 additions & 874 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎autoparc/autoparc-spec.md‎

Lines changed: 329 additions & 0 deletions
Large diffs are not rendered by default.

‎autoparc/setup-autoparc.ts‎

Lines changed: 896 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/getting-started.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Getting Started
2+
3+
Quick start guide for MCP Dataverse — an MCP server exposing 50 AI-callable tools for Microsoft Dataverse.
4+
5+
## Prerequisites
6+
7+
- **Node.js 20+**
8+
- A **Dataverse environment** with a licensed user account (e.g. `https://yourorg.crm.dynamics.com`)
9+
- An MCP-compatible client (VS Code + Copilot, Claude Desktop, Cursor, etc.)
10+
11+
## Installation
12+
13+
### Recommended — Interactive CLI
14+
15+
```bash
16+
npx mcp-dataverse install
17+
```
18+
19+
The wizard will:
20+
21+
1. Ask for your Dataverse environment URL
22+
2. Save configuration to `~/.mcp-dataverse/config.json`
23+
3. Register the server in VS Code via `code --add-mcp`
24+
4. Authenticate with your Microsoft account (device code flow)
25+
26+
### Manual Configuration
27+
28+
Create `~/.mcp-dataverse/config.json`:
29+
30+
```json
31+
{
32+
"environmentUrl": "https://yourorg.crm.dynamics.com",
33+
"requestTimeoutMs": 30000,
34+
"maxRetries": 3
35+
}
36+
```
37+
38+
See [multi-client-setup.md](multi-client-setup.md) for client-specific configuration.
39+
40+
## Configuration Options
41+
42+
| Option | Type | Default | Description |
43+
| ------------------ | ------ | ------- | --------------------------------------------------------- |
44+
| `environmentUrl` | string | — | Your Dataverse org URL (must be `https://*.dynamics.com`) |
45+
| `requestTimeoutMs` | number | `30000` | HTTP request timeout in milliseconds |
46+
| `maxRetries` | number | `3` | Retry count on transient errors (0–10) |
47+
48+
## Environment Variables
49+
50+
All config values can be set via environment variables (useful for MCP client `env` blocks):
51+
52+
| Variable | Maps to |
53+
| -------------------- | ----------------------------------- |
54+
| `DATAVERSE_ENV_URL` | `environmentUrl` |
55+
| `REQUEST_TIMEOUT_MS` | `requestTimeoutMs` |
56+
| `MAX_RETRIES` | `maxRetries` |
57+
| `MCP_CONFIG_PATH` | Path to a custom `config.json` file |
58+
59+
**Priority**: environment variables > `MCP_CONFIG_PATH` > `~/.mcp-dataverse/config.json` > `./config.json`.
60+
61+
## Authentication
62+
63+
MCP Dataverse uses **Microsoft device code flow** (MSAL Public Client) — no Azure AD app registration or PAT required.
64+
65+
### First connection
66+
67+
Authentication triggers on the **first tool call** after the server starts:
68+
69+
1. Open the VS Code **Output** panel → select **MCP**
70+
2. A sign-in prompt appears with a device code (auto-copied to clipboard)
71+
3. Open `https://microsoft.com/devicelogin`, paste the code, sign in with your work account
72+
4. The Output panel confirms: `Authenticated ✓`
73+
74+
> The code expires after **5 minutes**. If it times out, retry the tool call for a new code.
75+
76+
### Subsequent launches
77+
78+
Tokens are cached encrypted (AES-256-GCM) in `~/.mcp-dataverse/`. Renewal is fully silent — no prompt needed until the refresh token expires (~90 days of inactivity).
79+
80+
To force re-authentication:
81+
82+
```bash
83+
npx mcp-dataverse-auth https://yourorg.crm.dynamics.com
84+
```
85+
86+
## Running the Server
87+
88+
### Stdio transport (default)
89+
90+
Used by VS Code, Claude Desktop, Cursor, and most MCP clients:
91+
92+
```bash
93+
npx mcp-dataverse
94+
```
95+
96+
### HTTP transport
97+
98+
For clients that connect over HTTP (or for shared/remote access):
99+
100+
```bash
101+
npx mcp-dataverse --transport http --port 3001
102+
```
103+
104+
The MCP endpoint is available at `http://localhost:3001/mcp`.
105+
106+
## Diagnostics
107+
108+
Run the built-in health check to verify your configuration and connectivity:
109+
110+
```bash
111+
npx mcp-dataverse doctor
112+
```
113+
114+
This checks:
115+
116+
- Configuration file validity
117+
- Dataverse environment reachability
118+
- Authentication token status
119+
- API connectivity (WhoAmI)
120+
121+
## Next Steps
122+
123+
- [Multi-client setup](multi-client-setup.md) — configure VS Code, Claude Desktop, Cursor, and more
124+
- [Querying data](use-cases/querying-data.md) — OData, FetchXML, search
125+
- [Inspecting schema](use-cases/inspecting-schema.md) — tables, columns, relationships
126+
- [Managing records](use-cases/managing-records.md) — CRUD, batch, associations
127+
- [Solutions & customizations](use-cases/solutions-and-customizations.md)
128+
- [Delta sync](use-cases/delta-sync.md) — change tracking for incremental sync

‎docs/multi-client-setup.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# Multi-Client Setup
2+
3+
Configuration examples for running MCP Dataverse with different MCP clients.
4+
5+
All examples use `npx -y mcp-dataverse` to auto-install and run the server. Set `DATAVERSE_ENV_URL` in the `env` block or use `MCP_CONFIG_PATH` to point to a config file.
6+
7+
> See [getting-started.md](getting-started.md) for prerequisites and authentication details.
8+
9+
---
10+
11+
## VS Code (Copilot Chat)
12+
13+
Create `.vscode/mcp.json` in your workspace (or use **Ctrl+Shift+P** → **MCP: Open User Configuration** for global):
14+
15+
```json
16+
{
17+
"servers": {
18+
"mcp-dataverse": {
19+
"type": "stdio",
20+
"command": "npx",
21+
"args": ["-y", "mcp-dataverse"],
22+
"env": {
23+
"DATAVERSE_ENV_URL": "https://yourorg.crm.dynamics.com"
24+
}
25+
}
26+
}
27+
}
28+
```
29+
30+
> Requires VS Code 1.99+ with GitHub Copilot (Agent mode).
31+
32+
---
33+
34+
## Claude Desktop
35+
36+
Edit the Claude Desktop configuration:
37+
38+
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
39+
- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
40+
41+
```json
42+
{
43+
"mcpServers": {
44+
"mcp-dataverse": {
45+
"command": "npx",
46+
"args": ["-y", "mcp-dataverse"],
47+
"env": {
48+
"DATAVERSE_ENV_URL": "https://yourorg.crm.dynamics.com"
49+
}
50+
}
51+
}
52+
}
53+
```
54+
55+
---
56+
57+
## Claude Code CLI
58+
59+
```bash
60+
claude mcp add mcp-dataverse -- npx -y mcp-dataverse
61+
```
62+
63+
Set the environment variable before launching:
64+
65+
```bash
66+
export DATAVERSE_ENV_URL=https://yourorg.crm.dynamics.com
67+
```
68+
69+
---
70+
71+
## Cursor
72+
73+
Create `.cursor/mcp.json` in your workspace:
74+
75+
```json
76+
{
77+
"mcpServers": {
78+
"mcp-dataverse": {
79+
"command": "npx",
80+
"args": ["-y", "mcp-dataverse"],
81+
"env": {
82+
"DATAVERSE_ENV_URL": "https://yourorg.crm.dynamics.com"
83+
}
84+
}
85+
}
86+
}
87+
```
88+
89+
---
90+
91+
## Windsurf
92+
93+
Create or edit `~/.windsurf/mcp.json`:
94+
95+
```json
96+
{
97+
"mcpServers": {
98+
"mcp-dataverse": {
99+
"command": "npx",
100+
"args": ["-y", "mcp-dataverse"],
101+
"env": {
102+
"DATAVERSE_ENV_URL": "https://yourorg.crm.dynamics.com"
103+
}
104+
}
105+
}
106+
}
107+
```
108+
109+
---
110+
111+
## Gemini CLI
112+
113+
Edit `~/.gemini/settings.json`:
114+
115+
```json
116+
{
117+
"mcpServers": {
118+
"mcp-dataverse": {
119+
"command": "npx",
120+
"args": ["-y", "mcp-dataverse"],
121+
"env": {
122+
"DATAVERSE_ENV_URL": "https://yourorg.crm.dynamics.com"
123+
}
124+
}
125+
}
126+
}
127+
```
128+
129+
---
130+
131+
## HTTP Transport (any client)
132+
133+
For clients that support HTTP-based MCP connections, or for remote/shared access:
134+
135+
```bash
136+
npx mcp-dataverse --transport http --port 3001
137+
```
138+
139+
Then connect your client to:
140+
141+
```
142+
http://localhost:3001/mcp
143+
```
144+
145+
This is useful when:
146+
147+
- The client doesn't support stdio (e.g. web-based tools)
148+
- You want a single server instance shared across multiple clients
149+
- You need remote access to Dataverse tools
150+
151+
---
152+
153+
## Additional Configuration
154+
155+
### Using a config file instead of env vars
156+
157+
If you prefer a config file over environment variables, point `MCP_CONFIG_PATH` to it:
158+
159+
```json
160+
{
161+
"servers": {
162+
"mcp-dataverse": {
163+
"type": "stdio",
164+
"command": "npx",
165+
"args": ["-y", "mcp-dataverse"],
166+
"env": {
167+
"MCP_CONFIG_PATH": "/path/to/.mcp-dataverse/config.json"
168+
}
169+
}
170+
}
171+
}
172+
```
173+
174+
### Overriding timeout and retries
175+
176+
Pass `REQUEST_TIMEOUT_MS` and `MAX_RETRIES` in the `env` block:
177+
178+
```json
179+
{
180+
"env": {
181+
"DATAVERSE_ENV_URL": "https://yourorg.crm.dynamics.com",
182+
"REQUEST_TIMEOUT_MS": "60000",
183+
"MAX_RETRIES": "5"
184+
}
185+
}
186+
```
187+
188+
---
189+
190+
## Troubleshooting
191+
192+
| Symptom | Fix |
193+
| --------------------------------- | ------------------------------------------------------------------ |
194+
| Server not appearing in client | Restart the client after editing config |
195+
| Authentication prompt not showing | Check the Output panel (VS Code) or terminal for the device code |
196+
| `Invalid configuration` error | Verify `DATAVERSE_ENV_URL` is a valid `https://*.dynamics.com` URL |
197+
| Timeout errors | Increase `REQUEST_TIMEOUT_MS` |
198+
199+
Run `npx mcp-dataverse doctor` to diagnose connectivity issues. See [getting-started.md](getting-started.md#diagnostics).

0 commit comments

Comments
 (0)