dataverse-mcp 0.1.0__tar.gz

dataverse_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan James
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dataverse_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: dataverse-mcp
+Version: 0.1.0
+Summary: A read-only MCP server for querying Microsoft Dataverse environments during development
+Author: Ryan James
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ryanmichaeljames/dataverse-mcp
+Project-URL: Repository, https://github.com/ryanmichaeljames/dataverse-mcp
+Project-URL: Issues, https://github.com/ryanmichaeljames/dataverse-mcp/issues
+Project-URL: Changelog, https://github.com/ryanmichaeljames/dataverse-mcp/blob/main/CHANGELOG.md
+Keywords: mcp,model-context-protocol,dataverse,power-platform,copilot,llm
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: azure-identity>=1.25.3
+Requires-Dist: httpx<1.0,>=0.20.0
+Requires-Dist: mcp[cli]>=1.27.0
+Requires-Dist: powerplatform-dataverse-client>=0.1.0b7
+Dynamic: license-file
+
+# Dataverse MCP Server
+
+An [MCP](https://modelcontextprotocol.io/) server for interacting with Microsoft Dataverse environments. Built with [FastMCP](https://github.com/modelcontextprotocol/python-sdk) and the official [PowerPlatform-Dataverse-Client](https://pypi.org/project/PowerPlatform-Dataverse-Client/) Python SDK.
+
+## Features
+
+- **Solution inspection** — list solutions, get solution details, browse solution components
+- **Table querying** — flexible OData-style queries against any Dataverse table
+- **Schema exploration** — list tables, inspect table metadata (primary key, name attribute)
+- **Agent-friendly** — rich tool descriptions designed for AI agent discoverability
+- **Secure** — Pydantic v2 input validation, GUID format enforcement, OData injection prevention
+
+## Prerequisites
+
+- [uv](https://docs.astral.sh/uv/) — install from [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/)
+- Access to a Microsoft Dataverse environment
+- Azure CLI (`az login`) or a registered app for authentication
+
+## Installation
+
+No install required — run directly from PyPI using `uvx`:
+
+```bash
+uvx dataverse-mcp
+```
+
+`uvx` downloads and runs the package in an isolated environment. No cloning, no virtual env setup.
+
+## Configuration
+
+Copy the example environment file and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DATAVERSE_URL` | Yes | — | Your Dataverse org URL (e.g., `https://yourorg.crm.dynamics.com`) |
+| `DATAVERSE_AUTH_TYPE` | No | `azure_cli` | Auth method: `interactive`, `client_secret`, or `azure_cli` |
+| `AZURE_TENANT_ID` | For `client_secret` | — | Azure AD tenant ID |
+| `AZURE_CLIENT_ID` | For `client_secret` | — | App registration client ID |
+| `AZURE_CLIENT_SECRET` | For `client_secret` | — | App registration client secret |
+
+### Authentication Methods
+
+- **`azure_cli`** (default) — Uses your existing `az login` session. Best for local development.
+- **`interactive`** — Opens a browser window for interactive sign-in.
+- **`client_secret`** — Uses a service principal. Requires `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, and `AZURE_CLIENT_SECRET`.
+
+## Usage
+
+This server communicates over stdio and works with any MCP-compatible client.
+
+### VS Code
+
+Add the server to your VS Code MCP configuration (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "dataverse-mcp": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["dataverse-mcp"],
+      "env": {
+        "DATAVERSE_URL": "https://yourorg.crm.dynamics.com",
+        "DATAVERSE_AUTH_TYPE": "azure_cli"
+      }
+    }
+  }
+}
+```
+
+To connect to multiple environments, add one entry per environment with a unique key:
+
+```json
+{
+  "servers": {
+    "dataverse-mcp-dev": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["dataverse-mcp"],
+      "env": {
+        "DATAVERSE_URL": "https://yourorg-dev.crm.dynamics.com",
+        "DATAVERSE_AUTH_TYPE": "azure_cli"
+      }
+    },
+    "dataverse-mcp-test": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["dataverse-mcp"],
+      "env": {
+        "DATAVERSE_URL": "https://yourorg-test.crm.dynamics.com",
+        "DATAVERSE_AUTH_TYPE": "azure_cli"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `dataverse_list_solutions` | List solutions with optional OData filter, select, and top |
+| `dataverse_get_solution` | Get a single solution by unique name or GUID |
+| `dataverse_list_solution_components` | List components in a solution with optional type filter |
+| `dataverse_query_table` | Query records from any table with filter, select, orderby, expand, top |
+| `dataverse_get_record` | Get a single record by table name and GUID |
+| `dataverse_list_tables` | List available tables/entities with optional filter |
+| `dataverse_get_table_metadata` | Get schema details for a specific table |
+
+## Project Structure
+
+```
+src/dataverse_mcp/
+├── __init__.py          # Package init
+├── _app.py              # FastMCP instance (avoids circular imports)
+├── server.py            # Entry point, logging setup, tool registration
+├── client.py            # DataverseClient wrapper (auth, lifecycle)
+├── models.py            # Pydantic v2 input models for all tools
+└── tools/
+    ├── __init__.py      # Tools package init
+    ├── solutions.py     # Solution query tools
+    ├── tables.py        # Table record query tools
+    └── metadata.py      # Table/column metadata tools
+```
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/ryanmichaeljames/dataverse-mcp.git
+cd dataverse-mcp
+
+# Install dependencies
+uv sync
+
+# Run the MCP inspector for testing
+uv run mcp dev src/dataverse_mcp/server.py
+
+# Compile check all modules
+uv run python -m py_compile src/dataverse_mcp/server.py
+```
+
+## License
+
+MIT

dataverse_mcp-0.1.0/README.md

@@ -0,0 +1,149 @@
+# Dataverse MCP Server
+
+An [MCP](https://modelcontextprotocol.io/) server for interacting with Microsoft Dataverse environments. Built with [FastMCP](https://github.com/modelcontextprotocol/python-sdk) and the official [PowerPlatform-Dataverse-Client](https://pypi.org/project/PowerPlatform-Dataverse-Client/) Python SDK.
+
+## Features
+
+- **Solution inspection** — list solutions, get solution details, browse solution components
+- **Table querying** — flexible OData-style queries against any Dataverse table
+- **Schema exploration** — list tables, inspect table metadata (primary key, name attribute)
+- **Agent-friendly** — rich tool descriptions designed for AI agent discoverability
+- **Secure** — Pydantic v2 input validation, GUID format enforcement, OData injection prevention
+
+## Prerequisites
+
+- [uv](https://docs.astral.sh/uv/) — install from [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/)
+- Access to a Microsoft Dataverse environment
+- Azure CLI (`az login`) or a registered app for authentication
+
+## Installation
+
+No install required — run directly from PyPI using `uvx`:
+
+```bash
+uvx dataverse-mcp
+```
+
+`uvx` downloads and runs the package in an isolated environment. No cloning, no virtual env setup.
+
+## Configuration
+
+Copy the example environment file and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DATAVERSE_URL` | Yes | — | Your Dataverse org URL (e.g., `https://yourorg.crm.dynamics.com`) |
+| `DATAVERSE_AUTH_TYPE` | No | `azure_cli` | Auth method: `interactive`, `client_secret`, or `azure_cli` |
+| `AZURE_TENANT_ID` | For `client_secret` | — | Azure AD tenant ID |
+| `AZURE_CLIENT_ID` | For `client_secret` | — | App registration client ID |
+| `AZURE_CLIENT_SECRET` | For `client_secret` | — | App registration client secret |
+
+### Authentication Methods
+
+- **`azure_cli`** (default) — Uses your existing `az login` session. Best for local development.
+- **`interactive`** — Opens a browser window for interactive sign-in.
+- **`client_secret`** — Uses a service principal. Requires `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, and `AZURE_CLIENT_SECRET`.
+
+## Usage
+
+This server communicates over stdio and works with any MCP-compatible client.
+
+### VS Code
+
+Add the server to your VS Code MCP configuration (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "dataverse-mcp": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["dataverse-mcp"],
+      "env": {
+        "DATAVERSE_URL": "https://yourorg.crm.dynamics.com",
+        "DATAVERSE_AUTH_TYPE": "azure_cli"
+      }
+    }
+  }
+}
+```
+
+To connect to multiple environments, add one entry per environment with a unique key:
+
+```json
+{
+  "servers": {
+    "dataverse-mcp-dev": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["dataverse-mcp"],
+      "env": {
+        "DATAVERSE_URL": "https://yourorg-dev.crm.dynamics.com",
+        "DATAVERSE_AUTH_TYPE": "azure_cli"
+      }
+    },
+    "dataverse-mcp-test": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["dataverse-mcp"],
+      "env": {
+        "DATAVERSE_URL": "https://yourorg-test.crm.dynamics.com",
+        "DATAVERSE_AUTH_TYPE": "azure_cli"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `dataverse_list_solutions` | List solutions with optional OData filter, select, and top |
+| `dataverse_get_solution` | Get a single solution by unique name or GUID |
+| `dataverse_list_solution_components` | List components in a solution with optional type filter |
+| `dataverse_query_table` | Query records from any table with filter, select, orderby, expand, top |
+| `dataverse_get_record` | Get a single record by table name and GUID |
+| `dataverse_list_tables` | List available tables/entities with optional filter |
+| `dataverse_get_table_metadata` | Get schema details for a specific table |
+
+## Project Structure
+
+```
+src/dataverse_mcp/
+├── __init__.py          # Package init
+├── _app.py              # FastMCP instance (avoids circular imports)
+├── server.py            # Entry point, logging setup, tool registration
+├── client.py            # DataverseClient wrapper (auth, lifecycle)
+├── models.py            # Pydantic v2 input models for all tools
+└── tools/
+    ├── __init__.py      # Tools package init
+    ├── solutions.py     # Solution query tools
+    ├── tables.py        # Table record query tools
+    └── metadata.py      # Table/column metadata tools
+```
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/ryanmichaeljames/dataverse-mcp.git
+cd dataverse-mcp
+
+# Install dependencies
+uv sync
+
+# Run the MCP inspector for testing
+uv run mcp dev src/dataverse_mcp/server.py
+
+# Compile check all modules
+uv run python -m py_compile src/dataverse_mcp/server.py
+```
+
+## License
+
+MIT

dataverse_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "dataverse-mcp"
+version = "0.1.0"
+description = "A read-only MCP server for querying Microsoft Dataverse environments during development"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    {name = "Ryan James"},
+]
+license = "MIT"
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "dataverse",
+    "power-platform",
+    "copilot",
+    "llm",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "azure-identity>=1.25.3",
+    "httpx>=0.20.0,<1.0",
+    "mcp[cli]>=1.27.0",
+    "powerplatform-dataverse-client>=0.1.0b7",
+]
+
+[project.urls]
+Homepage = "https://github.com/ryanmichaeljames/dataverse-mcp"
+Repository = "https://github.com/ryanmichaeljames/dataverse-mcp"
+Issues = "https://github.com/ryanmichaeljames/dataverse-mcp/issues"
+Changelog = "https://github.com/ryanmichaeljames/dataverse-mcp/blob/main/CHANGELOG.md"
+
+[project.scripts]
+dataverse-mcp = "dataverse_mcp.server:main"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[dependency-groups]
+dev = [
+    "build>=1.0",
+    "twine>=5.0",
+]

dataverse_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dataverse_mcp-0.1.0/src/dataverse_mcp/__init__.py

@@ -0,0 +1 @@
+"""Dataverse MCP Server — read-only MCP tools for querying Microsoft Dataverse."""

dataverse_mcp-0.1.0/src/dataverse_mcp/_app.py

@@ -0,0 +1,22 @@
+"""FastMCP application instance.
+
+This module exists to avoid circular imports between server.py and tool
+modules.  Tool modules import ``mcp`` from here; server.py imports ``mcp``
+from here and registers tool modules.
+"""
+
+from mcp.server.fastmcp import FastMCP
+
+from dataverse_mcp.client import dataverse_lifespan
+
+mcp = FastMCP(
+    "dataverse_mcp",
+    instructions=(
+        "Dataverse MCP server for interacting with Microsoft Dataverse "
+        "environments. Use dataverse_list_solutions to discover solutions, "
+        "dataverse_query_table to search records, and "
+        "dataverse_list_tables / dataverse_get_table_metadata for schema "
+        "exploration."
+    ),
+    lifespan=dataverse_lifespan,
+)

dataverse_mcp-0.1.0/src/dataverse_mcp/client.py

@@ -0,0 +1,101 @@
+"""DataverseClient wrapper with authentication factory and lifecycle management."""
+
+import logging
+import os
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+from azure.identity import (
+    AzureCliCredential,
+    ClientSecretCredential,
+    InteractiveBrowserCredential,
+)
+from PowerPlatform.Dataverse.client import DataverseClient
+
+logger = logging.getLogger(__name__)
+
+SUPPORTED_AUTH_TYPES = ("interactive", "client_secret", "azure_cli")
+
+
+def _build_credential(auth_type: str):
+    """Build an Azure TokenCredential based on the configured auth type.
+
+    Args:
+        auth_type: One of 'interactive', 'client_secret', or 'azure_cli'.
+
+    Returns:
+        A TokenCredential instance for authenticating with Dataverse.
+
+    Raises:
+        ValueError: If the auth type is not supported or required env vars are missing.
+    """
+    if auth_type == "interactive":
+        logger.info("Using InteractiveBrowserCredential for authentication")
+        return InteractiveBrowserCredential()
+
+    if auth_type == "client_secret":
+        tenant_id = os.environ.get("AZURE_TENANT_ID")
+        client_id = os.environ.get("AZURE_CLIENT_ID")
+        client_secret = os.environ.get("AZURE_CLIENT_SECRET")
+        if not all([tenant_id, client_id, client_secret]):
+            raise ValueError(
+                "client_secret auth requires AZURE_TENANT_ID, "
+                "AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET environment variables"
+            )
+        logger.info("Using ClientSecretCredential for authentication")
+        return ClientSecretCredential(
+            tenant_id=tenant_id,
+            client_id=client_id,
+            client_secret=client_secret,
+        )
+
+    if auth_type == "azure_cli":
+        logger.info("Using AzureCliCredential for authentication")
+        return AzureCliCredential()
+
+    raise ValueError(
+        f"Unsupported DATAVERSE_AUTH_TYPE: '{auth_type}'. "
+        f"Supported values: {', '.join(SUPPORTED_AUTH_TYPES)}"
+    )
+
+
+@dataclass
+class AppContext:
+    """Application context holding the initialized DataverseClient."""
+
+    client: DataverseClient
+
+
+@asynccontextmanager
+async def dataverse_lifespan(server) -> AsyncIterator[AppContext]:
+    """FastMCP lifespan that initializes and cleans up the DataverseClient.
+
+    Reads configuration from environment variables:
+    - DATAVERSE_URL: The Dataverse organization URL (required)
+    - DATAVERSE_AUTH_TYPE: Authentication method (default: 'azure_cli')
+
+    Yields:
+        AppContext containing the initialized DataverseClient.
+    """
+    dataverse_url = os.environ.get("DATAVERSE_URL")
+    if not dataverse_url:
+        raise ValueError(
+            "DATAVERSE_URL environment variable is required "
+            "(e.g., 'https://yourorg.crm.dynamics.com')"
+        )
+
+    auth_type = os.environ.get("DATAVERSE_AUTH_TYPE", "azure_cli").lower().strip()
+    logger.info(
+        "Initializing DataverseClient for %s (auth: %s)", dataverse_url, auth_type
+    )
+
+    credential = _build_credential(auth_type)
+    client = DataverseClient(dataverse_url, credential)
+
+    try:
+        logger.info("DataverseClient initialized successfully")
+        yield AppContext(client=client)
+    finally:
+        logger.info("Shutting down DataverseClient")
+        client.close()