dataverse-mcp 0.1.0__py3-none-any.whl

dataverse_mcp/__init__.py

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

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/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()

dataverse_mcp/models.py

@@ -0,0 +1,252 @@
+"""Pydantic input models for all Dataverse MCP tools."""
+
+import re
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+_GUID_PATTERN = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+
+
+# ---------------------------------------------------------------------------
+# Solution tools
+# ---------------------------------------------------------------------------
+
+
+class ListSolutionsInput(BaseModel):
+    """Input for listing solutions in the Dataverse environment."""
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    filter: str | None = Field(
+        default=None,
+        description=(
+            "OData $filter expression to narrow results. Use lowercase logical "
+            "names (e.g., \"ismanaged eq true\", \"uniquename eq 'MyApp'\")"
+        ),
+    )
+    select: list[str] | None = Field(
+        default=None,
+        description=(
+            "Columns to return. Defaults to solutionid, uniquename, "
+            "friendlyname, version, ismanaged, installedon, modifiedon"
+        ),
+    )
+    top: int = Field(
+        default=50,
+        description="Maximum number of solutions to return",
+        ge=1,
+        le=5000,
+    )
+
+
+class GetSolutionInput(BaseModel):
+    """Input for retrieving a single solution by unique name or ID."""
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    solution_unique_name: str | None = Field(
+        default=None,
+        description=(
+            "The unique name of the solution (e.g., 'MyCustomApp'). "
+            "Provide either this or solution_id, not both."
+        ),
+    )
+    solution_id: str | None = Field(
+        default=None,
+        description=(
+            "The GUID of the solution (e.g., 'a1b2c3d4-...'). "
+            "Provide either this or solution_unique_name, not both."
+        ),
+    )
+    select: list[str] | None = Field(
+        default=None,
+        description="Columns to return. Defaults to all standard solution columns.",
+    )
+
+    @field_validator("solution_id")
+    @classmethod
+    def validate_solution_guid(cls, v: str | None) -> str | None:
+        if v is not None and not _GUID_PATTERN.match(v):
+            raise ValueError(f"Invalid GUID format: '{v}'")
+        return v
+
+    @model_validator(mode="after")
+    def check_identifier_provided(self) -> "GetSolutionInput":
+        if not self.solution_unique_name and not self.solution_id:
+            raise ValueError(
+                "Either solution_unique_name or solution_id must be provided"
+            )
+        if self.solution_unique_name and self.solution_id:
+            raise ValueError(
+                "Provide either solution_unique_name or solution_id, not both"
+            )
+        return self
+
+
+class ListSolutionComponentsInput(BaseModel):
+    """Input for listing components within a specific solution."""
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    solution_id: str = Field(
+        ...,
+        description="The GUID of the solution whose components to list",
+        min_length=1,
+    )
+
+    @field_validator("solution_id")
+    @classmethod
+    def validate_solution_guid(cls, v: str) -> str:
+        if not _GUID_PATTERN.match(v):
+            raise ValueError(f"Invalid GUID format: '{v}'")
+        return v
+
+    component_type: int | None = Field(
+        default=None,
+        description=(
+            "Filter by component type code. Common values: "
+            "1=Entity, 2=Attribute, 3=Relationship, 9=OptionSet, "
+            "10=EntityRelationship, 26=View, 29=Workflow, 60=SystemForm, "
+            "61=WebResource, 300=CanvasApp, 371=Connector"
+        ),
+    )
+    top: int = Field(
+        default=50,
+        description="Maximum number of components to return",
+        ge=1,
+        le=5000,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Table query tools
+# ---------------------------------------------------------------------------
+
+
+class QueryTableInput(BaseModel):
+    """Input for querying records from any Dataverse table."""
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    table_name: str = Field(
+        ...,
+        description=(
+            "Logical name of the table to query (e.g., 'account', 'contact', "
+            "'new_customtable'). Use lowercase logical names."
+        ),
+        min_length=1,
+    )
+    select: list[str] | None = Field(
+        default=None,
+        description=(
+            "Columns to return. Omit to return default columns. "
+            "Always specify this to reduce payload size "
+            "(e.g., ['name', 'accountid', 'telephone1'])"
+        ),
+    )
+    filter: str | None = Field(
+        default=None,
+        description=(
+            "OData $filter expression. Use lowercase logical names. "
+            "Examples: \"statecode eq 0\", "
+            "\"name eq 'Contoso'\" , "
+            "\"createdon gt 2024-01-01\""
+        ),
+    )
+    orderby: list[str] | None = Field(
+        default=None,
+        description=(
+            "Sort order. Each entry is 'column_name asc' or 'column_name desc' "
+            "(e.g., ['name asc', 'createdon desc'])"
+        ),
+    )
+    top: int = Field(
+        default=50,
+        description="Maximum number of records to return",
+        ge=1,
+        le=5000,
+    )
+    expand: list[str] | None = Field(
+        default=None,
+        description=(
+            "Navigation properties to expand (case-sensitive!). "
+            "Example: ['primarycontactid']"
+        ),
+    )
+
+
+class GetRecordInput(BaseModel):
+    """Input for retrieving a single record by its ID."""
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    table_name: str = Field(
+        ...,
+        description="Logical name of the table (e.g., 'account', 'contact')",
+        min_length=1,
+    )
+    record_id: str = Field(
+        ...,
+        description="The GUID of the record to retrieve",
+        min_length=1,
+    )
+
+    @field_validator("record_id")
+    @classmethod
+    def validate_record_guid(cls, v: str) -> str:
+        if not _GUID_PATTERN.match(v):
+            raise ValueError(f"Invalid GUID format: '{v}'")
+        return v
+
+    select: list[str] | None = Field(
+        default=None,
+        description=(
+            "Columns to return. Omit to return default columns. "
+            "Specify to reduce payload (e.g., ['name', 'telephone1'])"
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Metadata tools
+# ---------------------------------------------------------------------------
+
+
+class ListTablesInput(BaseModel):
+    """Input for listing available tables/entities in the environment."""
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    filter: str | None = Field(
+        default=None,
+        description=(
+            "OData $filter for table metadata. "
+            "Examples: \"IsCustomEntity eq true\", "
+            "\"IsManaged eq false\""
+        ),
+    )
+    select: list[str] | None = Field(
+        default=None,
+        description=(
+            "Metadata properties to return. "
+            "Defaults to LogicalName, SchemaName, DisplayName, "
+            "IsCustomEntity, IsManaged"
+        ),
+    )
+
+
+class GetTableMetadataInput(BaseModel):
+    """Input for retrieving detailed metadata for a specific table."""
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    table_name: str = Field(
+        ...,
+        description=(
+            "Logical name of the table (e.g., 'account', 'contact', "
+            "'new_customtable'). Use lowercase logical names."
+        ),
+        min_length=1,
+    )

dataverse_mcp/server.py

@@ -0,0 +1,27 @@
+"""FastMCP server for Dataverse MCP tools."""
+
+import logging
+import sys
+
+# Configure logging to stderr (stdout reserved for stdio transport)
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    stream=sys.stderr,
+)
+
+from dataverse_mcp._app import mcp  # noqa: E402
+
+# Import tool modules to trigger @mcp.tool() registration
+import dataverse_mcp.tools.solutions  # noqa: E402, F401
+import dataverse_mcp.tools.tables  # noqa: E402, F401
+import dataverse_mcp.tools.metadata  # noqa: E402, F401
+
+
+def main():
+    """Entry point for the Dataverse MCP server."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

dataverse_mcp/tools/__init__.py

@@ -0,0 +1 @@
+"""Dataverse MCP tool modules."""

dataverse_mcp/tools/metadata.py

@@ -0,0 +1,147 @@
+"""Table and column metadata tools for the Dataverse MCP server."""
+
+import asyncio
+import json
+import logging
+
+from mcp.server.fastmcp import Context
+from PowerPlatform.Dataverse.core.errors import DataverseError, HttpError
+
+from dataverse_mcp._app import mcp
+from dataverse_mcp.client import AppContext
+from dataverse_mcp.models import GetTableMetadataInput, ListTablesInput
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_TABLE_SELECT = [
+    "LogicalName",
+    "SchemaName",
+    "DisplayName",
+    "EntitySetName",
+    "IsCustomEntity",
+    "IsManaged",
+]
+
+
+def _get_client(ctx: Context):
+    """Extract the DataverseClient from the FastMCP lifespan context."""
+    app_ctx: AppContext = ctx.request_context.lifespan_context
+    return app_ctx.client
+
+
+@mcp.tool(
+    name="dataverse_list_tables",
+    annotations={
+        "title": "List Tables",
+        "readOnlyHint": True,
+        "destructiveHint": False,
+        "idempotentHint": True,
+        "openWorldHint": True,
+    },
+)
+async def dataverse_list_tables(params: ListTablesInput, ctx: Context) -> str:
+    """List available tables (entities) in the Dataverse environment.
+
+    Returns table metadata including logical name, schema name, and display
+    name. By default returns all non-private tables. Use filter to narrow
+    results (e.g., "IsCustomEntity eq true" for custom tables only).
+
+    Use this tool to discover which tables exist before querying them with
+    dataverse_query_table or inspecting their schema with
+    dataverse_get_table_metadata.
+    """
+    client = _get_client(ctx)
+    select = params.select or _DEFAULT_TABLE_SELECT
+
+    try:
+
+        def _query():
+            return client.tables.list(
+                filter=params.filter,
+                select=select,
+            )
+
+        tables = await asyncio.to_thread(_query)
+        return json.dumps({
+            "tables": tables,
+            "count": len(tables),
+        })
+    except HttpError as e:
+        logger.error("Dataverse HTTP error: %s (status=%d)", e.message, e.status_code)
+        return json.dumps({
+            "error": True,
+            "message": f"Dataverse returned HTTP {e.status_code}: {e.message}",
+            "is_transient": e.is_transient,
+        })
+    except DataverseError as e:
+        logger.error("Dataverse error: %s", e.message)
+        return json.dumps({"error": True, "message": str(e)})
+    except Exception as e:
+        logger.exception("Unexpected error in dataverse_list_tables")
+        return json.dumps({
+            "error": True,
+            "message": f"Unexpected error: {type(e).__name__}: {e}",
+        })
+
+
+@mcp.tool(
+    name="dataverse_get_table_metadata",
+    annotations={
+        "title": "Get Table Metadata",
+        "readOnlyHint": True,
+        "destructiveHint": False,
+        "idempotentHint": True,
+        "openWorldHint": True,
+    },
+)
+async def dataverse_get_table_metadata(
+    params: GetTableMetadataInput, ctx: Context
+) -> str:
+    """Get detailed metadata for a specific Dataverse table.
+
+    Returns the table's schema name, logical name, entity set name,
+    primary key attribute, and primary name attribute. Use this to
+    understand a table's structure before querying it with
+    dataverse_query_table.
+    """
+    client = _get_client(ctx)
+
+    try:
+
+        def _query():
+            return client.tables.get(params.table_name)
+
+        info = await asyncio.to_thread(_query)
+
+        if info is None:
+            return json.dumps({
+                "error": True,
+                "message": f"Table not found: '{params.table_name}'",
+            })
+
+        return json.dumps({
+            "table": {
+                "logical_name": info.logical_name,
+                "schema_name": info.schema_name,
+                "entity_set_name": info.entity_set_name,
+                "metadata_id": info.metadata_id,
+                "primary_id_attribute": info.primary_id_attribute,
+                "primary_name_attribute": info.primary_name_attribute,
+            },
+        })
+    except HttpError as e:
+        logger.error("Dataverse HTTP error: %s (status=%d)", e.message, e.status_code)
+        return json.dumps({
+            "error": True,
+            "message": f"Dataverse returned HTTP {e.status_code}: {e.message}",
+            "is_transient": e.is_transient,
+        })
+    except DataverseError as e:
+        logger.error("Dataverse error: %s", e.message)
+        return json.dumps({"error": True, "message": str(e)})
+    except Exception as e:
+        logger.exception("Unexpected error in dataverse_get_table_metadata")
+        return json.dumps({
+            "error": True,
+            "message": f"Unexpected error: {type(e).__name__}: {e}",
+        })

dataverse_mcp/tools/solutions.py

@@ -0,0 +1,293 @@
+"""Solution-related tools for the Dataverse MCP server."""
+
+import asyncio
+import json
+import logging
+
+from mcp.server.fastmcp import Context
+from PowerPlatform.Dataverse.core.errors import DataverseError, HttpError
+
+from dataverse_mcp.client import AppContext
+from dataverse_mcp.models import (
+    GetSolutionInput,
+    ListSolutionComponentsInput,
+    ListSolutionsInput,
+)
+from dataverse_mcp._app import mcp
+
+logger = logging.getLogger(__name__)
+
+# Solution component type code → display name
+# https://learn.microsoft.com/en-us/power-apps/developer/data-platform/reference/entities/solutioncomponent
+COMPONENT_TYPE_NAMES: dict[int, str] = {
+    1: "Entity",
+    2: "Attribute",
+    3: "Relationship",
+    9: "Option Set",
+    10: "Entity Relationship",
+    20: "Security Role",
+    26: "Saved Query",
+    29: "Workflow",
+    59: "Saved Query Visualization",
+    60: "System Form",
+    61: "Web Resource",
+    62: "Site Map",
+    63: "Connection Role",
+    66: "Custom Control",
+    70: "Field Security Profile",
+    90: "Plugin Type",
+    91: "Plugin Assembly",
+    92: "SDK Message Processing Step",
+    300: "Canvas App",
+    371: "Connector",
+    372: "Environment Variable Definition",
+    373: "Environment Variable Value",
+    380: "AI Project Type",
+    381: "AI Project",
+    382: "AI Configuration",
+}
+
+_DEFAULT_SOLUTION_SELECT = [
+    "solutionid",
+    "uniquename",
+    "friendlyname",
+    "version",
+    "ismanaged",
+    "installedon",
+    "modifiedon",
+    "description",
+]
+
+_DEFAULT_COMPONENT_SELECT = [
+    "solutioncomponentid",
+    "componenttype",
+    "objectid",
+    "rootcomponentbehavior",
+]
+
+
+def _get_client(ctx: Context):
+    """Extract the DataverseClient from the FastMCP lifespan context."""
+    app_ctx: AppContext = ctx.request_context.lifespan_context
+    return app_ctx.client
+
+
+def _flatten_records(pages, limit: int) -> list[dict]:
+    """Flatten paginated Record results into a list of dicts, up to limit."""
+    records = []
+    for page in pages:
+        for record in page:
+            records.append(dict(record))
+            if len(records) >= limit:
+                return records
+    return records
+
+
+def _enrich_component_type(record: dict) -> dict:
+    """Add component_type_name to a solution component record."""
+    comp_type = record.get("componenttype")
+    if comp_type is not None:
+        record["componenttype_name"] = COMPONENT_TYPE_NAMES.get(
+            comp_type, f"Unknown ({comp_type})"
+        )
+    return record
+
+
+@mcp.tool(
+    name="dataverse_list_solutions",
+    annotations={
+        "title": "List Solutions",
+        "readOnlyHint": True,
+        "destructiveHint": False,
+        "idempotentHint": True,
+        "openWorldHint": True,
+    },
+)
+async def dataverse_list_solutions(params: ListSolutionsInput, ctx: Context) -> str:
+    """List solutions in the connected Dataverse environment.
+
+    Returns solutions with their unique name, friendly name, version, and
+    managed status. Use the optional filter parameter to narrow results
+    (e.g., "ismanaged eq false" for unmanaged solutions only).
+
+    Use this tool to discover which solutions exist before drilling into
+    specific solution details or components.
+    """
+    client = _get_client(ctx)
+    select = params.select or _DEFAULT_SOLUTION_SELECT
+    top = params.top
+
+    try:
+
+        def _query():
+            pages = client.records.get(
+                "solution",
+                select=select,
+                filter=params.filter,
+                top=top,
+            )
+            return _flatten_records(pages, top)
+
+        records = await asyncio.to_thread(_query)
+        return json.dumps({
+            "records": records,
+            "count": len(records),
+            "has_more": len(records) >= top,
+        })
+    except HttpError as e:
+        logger.error("Dataverse HTTP error: %s (status=%d)", e.message, e.status_code)
+        return json.dumps({
+            "error": True,
+            "message": f"Dataverse returned HTTP {e.status_code}: {e.message}",
+            "is_transient": e.is_transient,
+        })
+    except DataverseError as e:
+        logger.error("Dataverse error: %s", e.message)
+        return json.dumps({"error": True, "message": str(e)})
+    except Exception as e:
+        logger.exception("Unexpected error in dataverse_list_solutions")
+        return json.dumps({
+            "error": True,
+            "message": f"Unexpected error: {type(e).__name__}: {e}",
+        })
+
+
+@mcp.tool(
+    name="dataverse_get_solution",
+    annotations={
+        "title": "Get Solution",
+        "readOnlyHint": True,
+        "destructiveHint": False,
+        "idempotentHint": True,
+        "openWorldHint": True,
+    },
+)
+async def dataverse_get_solution(params: GetSolutionInput, ctx: Context) -> str:
+    """Retrieve a single solution by its unique name or ID.
+
+    Provide either solution_unique_name or solution_id (not both).
+    Returns full solution details including version, publisher, and
+    managed status.
+
+    Use this after dataverse_list_solutions to get full details for
+    a specific solution.
+    """
+    client = _get_client(ctx)
+    select = params.select or _DEFAULT_SOLUTION_SELECT
+
+    try:
+
+        def _query():
+            if params.solution_id:
+                return dict(
+                    client.records.get(
+                        "solution",
+                        record_id=params.solution_id,
+                        select=select,
+                    )
+                )
+            # Query by unique name — escape single quotes for OData safety
+            escaped_name = params.solution_unique_name.replace("'", "''")
+            odata_filter = f"uniquename eq '{escaped_name}'"
+            pages = client.records.get(
+                "solution",
+                select=select,
+                filter=odata_filter,
+                top=1,
+            )
+            results = _flatten_records(pages, 1)
+            return results[0] if results else None
+
+        record = await asyncio.to_thread(_query)
+
+        if record is None:
+            identifier = params.solution_unique_name or params.solution_id
+            return json.dumps({
+                "error": True,
+                "message": f"Solution not found: '{identifier}'",
+            })
+
+        return json.dumps({"record": record})
+    except HttpError as e:
+        logger.error("Dataverse HTTP error: %s (status=%d)", e.message, e.status_code)
+        return json.dumps({
+            "error": True,
+            "message": f"Dataverse returned HTTP {e.status_code}: {e.message}",
+            "is_transient": e.is_transient,
+        })
+    except DataverseError as e:
+        logger.error("Dataverse error: %s", e.message)
+        return json.dumps({"error": True, "message": str(e)})
+    except Exception as e:
+        logger.exception("Unexpected error in dataverse_get_solution")
+        return json.dumps({
+            "error": True,
+            "message": f"Unexpected error: {type(e).__name__}: {e}",
+        })
+
+
+@mcp.tool(
+    name="dataverse_list_solution_components",
+    annotations={
+        "title": "List Solution Components",
+        "readOnlyHint": True,
+        "destructiveHint": False,
+        "idempotentHint": True,
+        "openWorldHint": True,
+    },
+)
+async def dataverse_list_solution_components(
+    params: ListSolutionComponentsInput, ctx: Context
+) -> str:
+    """List components within a specific solution.
+
+    Returns the components (entities, web resources, workflows, etc.)
+    that belong to the specified solution. Each component includes both
+    the integer type code and a human-readable type name.
+
+    Use component_type to filter by a specific type (e.g., 1 for Entity,
+    61 for Web Resource, 300 for Canvas App). Use dataverse_get_solution
+    first to find the solution_id.
+    """
+    client = _get_client(ctx)
+    top = params.top
+
+    # solution_id is already GUID-validated by Pydantic
+    odata_filter = f"_solutionid_value eq '{params.solution_id}'"
+    if params.component_type is not None:
+        odata_filter += f" and componenttype eq {params.component_type}"
+
+    try:
+
+        def _query():
+            pages = client.records.get(
+                "solutioncomponent",
+                select=_DEFAULT_COMPONENT_SELECT,
+                filter=odata_filter,
+                top=top,
+            )
+            records = _flatten_records(pages, top)
+            return [_enrich_component_type(r) for r in records]
+
+        records = await asyncio.to_thread(_query)
+        return json.dumps({
+            "records": records,
+            "count": len(records),
+            "has_more": len(records) >= top,
+        })
+    except HttpError as e:
+        logger.error("Dataverse HTTP error: %s (status=%d)", e.message, e.status_code)
+        return json.dumps({
+            "error": True,
+            "message": f"Dataverse returned HTTP {e.status_code}: {e.message}",
+            "is_transient": e.is_transient,
+        })
+    except DataverseError as e:
+        logger.error("Dataverse error: %s", e.message)
+        return json.dumps({"error": True, "message": str(e)})
+    except Exception as e:
+        logger.exception("Unexpected error in dataverse_list_solution_components")
+        return json.dumps({
+            "error": True,
+            "message": f"Unexpected error: {type(e).__name__}: {e}",
+        })

dataverse_mcp/tools/tables.py

@@ -0,0 +1,141 @@
+"""Table query tools for the Dataverse MCP server."""
+
+import asyncio
+import json
+import logging
+
+from mcp.server.fastmcp import Context
+from PowerPlatform.Dataverse.core.errors import DataverseError, HttpError
+
+from dataverse_mcp._app import mcp
+from dataverse_mcp.client import AppContext
+from dataverse_mcp.models import GetRecordInput, QueryTableInput
+
+logger = logging.getLogger(__name__)
+
+
+def _get_client(ctx: Context):
+    """Extract the DataverseClient from the FastMCP lifespan context."""
+    app_ctx: AppContext = ctx.request_context.lifespan_context
+    return app_ctx.client
+
+
+def _flatten_records(pages, limit: int) -> list[dict]:
+    """Flatten paginated Record results into a list of dicts, up to limit."""
+    records = []
+    for page in pages:
+        for record in page:
+            records.append(dict(record))
+            if len(records) >= limit:
+                return records
+    return records
+
+
+@mcp.tool(
+    name="dataverse_query_table",
+    annotations={
+        "title": "Query Table",
+        "readOnlyHint": True,
+        "destructiveHint": False,
+        "idempotentHint": True,
+        "openWorldHint": True,
+    },
+)
+async def dataverse_query_table(params: QueryTableInput, ctx: Context) -> str:
+    """Query records from any Dataverse table.
+
+    Returns matching records from the specified table. Supports OData-style
+    filtering, column selection, sorting, and navigation property expansion.
+
+    Always specify select to limit returned columns and reduce payload size.
+    Default top is 50 to prevent overwhelming context — increase if needed.
+
+    Use dataverse_list_tables or dataverse_get_table_metadata first to
+    discover available tables and their column names.
+    """
+    client = _get_client(ctx)
+    top = params.top
+
+    try:
+
+        def _query():
+            pages = client.records.get(
+                params.table_name,
+                select=params.select,
+                filter=params.filter,
+                orderby=params.orderby,
+                top=top,
+                expand=params.expand,
+            )
+            return _flatten_records(pages, top)
+
+        records = await asyncio.to_thread(_query)
+        return json.dumps({
+            "records": records,
+            "count": len(records),
+            "has_more": len(records) >= top,
+        })
+    except HttpError as e:
+        logger.error("Dataverse HTTP error: %s (status=%d)", e.message, e.status_code)
+        return json.dumps({
+            "error": True,
+            "message": f"Dataverse returned HTTP {e.status_code}: {e.message}",
+            "is_transient": e.is_transient,
+        })
+    except DataverseError as e:
+        logger.error("Dataverse error: %s", e.message)
+        return json.dumps({"error": True, "message": str(e)})
+    except Exception as e:
+        logger.exception("Unexpected error in dataverse_query_table")
+        return json.dumps({
+            "error": True,
+            "message": f"Unexpected error: {type(e).__name__}: {e}",
+        })
+
+
+@mcp.tool(
+    name="dataverse_get_record",
+    annotations={
+        "title": "Get Record",
+        "readOnlyHint": True,
+        "destructiveHint": False,
+        "idempotentHint": True,
+        "openWorldHint": True,
+    },
+)
+async def dataverse_get_record(params: GetRecordInput, ctx: Context) -> str:
+    """Retrieve a single record by its ID from any Dataverse table.
+
+    Returns the full record (or selected columns) for the given table
+    and record GUID. Use dataverse_query_table first to find record IDs.
+    """
+    client = _get_client(ctx)
+
+    try:
+
+        def _query():
+            record = client.records.get(
+                params.table_name,
+                record_id=params.record_id,
+                select=params.select,
+            )
+            return dict(record)
+
+        record = await asyncio.to_thread(_query)
+        return json.dumps({"record": record})
+    except HttpError as e:
+        logger.error("Dataverse HTTP error: %s (status=%d)", e.message, e.status_code)
+        return json.dumps({
+            "error": True,
+            "message": f"Dataverse returned HTTP {e.status_code}: {e.message}",
+            "is_transient": e.is_transient,
+        })
+    except DataverseError as e:
+        logger.error("Dataverse error: %s", e.message)
+        return json.dumps({"error": True, "message": str(e)})
+    except Exception as e:
+        logger.exception("Unexpected error in dataverse_get_record")
+        return json.dumps({
+            "error": True,
+            "message": f"Unexpected error: {type(e).__name__}: {e}",
+        })

dataverse_mcp-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+dataverse_mcp/__init__.py,sha256=8VxXY19tOjLshtSnDs1sv4saYA-SKYq9rl7r1rtLK94,85
+dataverse_mcp/_app.py,sha256=UkBt4dNLU1ERWVGLTl-Iz6UyTcJLjymdKGlDJUDUyyg,718
+dataverse_mcp/client.py,sha256=xHcKH4yn20kt4Qnt6-T5C5gfcYq3BDGI-QZHCXV5ZqY,3334
+dataverse_mcp/models.py,sha256=wsdJjvKGIq229aRZN-vMM43vE5ZrCQS_iFdWQmSGBOE,7777
+dataverse_mcp/server.py,sha256=2Unth7sSlOEkanv3eSGmOlmIYgRQ1qVQAkpd7p6A3WM,675
+dataverse_mcp/tools/__init__.py,sha256=MIYqOIDPe12iOP2h_RFgTHiuuaEE3bQW_sdGDCYmBuE,34
+dataverse_mcp/tools/metadata.py,sha256=W7_kuO4hXvLFroT6bGzCINXUxU205R3Hd7zbVO9mDZs,4699
+dataverse_mcp/tools/solutions.py,sha256=4ElxrWl8kU4a4d9WE11R2hwB7l1f0d_0c5kEs9FPFiQ,9347
+dataverse_mcp/tools/tables.py,sha256=ijvNs-qRl5j9l7g5b1LAMRyA_N3ikKPe7wkEq3vnfS4,4586
+dataverse_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=hpGGbtLk_YVW3uWKzc3Fb2_EZvEbkgcNDUD_RSa4Wsw,1067
+dataverse_mcp-0.1.0.dist-info/METADATA,sha256=ni4B6cJ55bKnjjacFafClzAR37W3st6TqqfGHVtmTxA,6243
+dataverse_mcp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+dataverse_mcp-0.1.0.dist-info/entry_points.txt,sha256=rV1Uph_G75ODMtkGBq86B-msdjASIrrUUWVlxnEFllE,60
+dataverse_mcp-0.1.0.dist-info/top_level.txt,sha256=fxIeN_8EzsfcxzaCvJGobSsEWAv9N9FXCxGrVp_xuOU,14
+dataverse_mcp-0.1.0.dist-info/RECORD,,

dataverse_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dataverse_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dataverse-mcp = dataverse_mcp.server:main

dataverse_mcp-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+dataverse_mcp