feat: add MCP server support for CDF data models

[ks93]

Summary

Adds MCP (Model Context Protocol) server support to pygen, enabling LLMs to interact with CDF data models through dynamically generated tools.

Features

• Zero-config UX: Launch MCP server directly from a data model ID with interactive OAuth login
• Dynamic tool generation: Automatically creates MCP tools based on generated SDK methods
• Full parameter introspection: Exposes all SDK filter parameters with types and descriptions from docstrings
• Correct required/optional handling: Required parameters (like aggregate in aggregate tools) are properly enforced
• View filtering: Use --views to include only specific views (reduces tool count)
• Operation filtering: Use --operations to enable only specific operations (list, search, etc.)

Supported Operations

Operation	Description
list	List/filter items with full filter support
retrieve	Retrieve single item by external_id
search	Full-text search with filters
aggregate	Count, sum, avg, min, max with optional group_by
histogram	Generate histograms for numeric properties
delete	Delete items (opt-in via --write flag)
graphql_query	Execute GraphQL queries (opt-in via --graphql flag)

Type Support

• Datetime: Accepts ISO 8601 strings, converts to datetime.datetime
• Direct relations: Accepts {"space": str, "externalId": str} objects
• List of direct relations: Accepts arrays of node reference objects
• All primitive types: str, int, float, bool

CLI Usage

# Basic usage
pygen mcp-serve "space/dataModel/version" --cluster greenfield --project myproject

# With optional features
pygen mcp-serve "space/dataModel/version" --cluster greenfield --project myproject --graphql --write

# Filter to specific views (reduces tool count for clients with limits)
pygen mcp-serve "space/dataModel/version" -c greenfield -p myproject --views Asset,Equipment

# Enable only specific operations
pygen mcp-serve "space/dataModel/version" -c greenfield -p myproject --ops list,search

Installation

# Install pygen globally with MCP support
uv tool install "cognite-pygen[cli,mcp]" --with pandas

# Or install from local development repo (editable)
uv tool install -e "/path/to/pygen[cli,mcp]" --with pandas --force

Cursor IDE Setup

Example Cursor MCP config (~/.cursor/mcp.json):

{
  "mcpServers": {
    "cognite": {
      "command": "pygen",
      "args": ["mcp-serve", "space/dataModel/version", "-c", "greenfield", "-p", "myproject", "--org", "myorg"]
    }
  }
}

Claude Desktop Setup

Example Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "cognite": {
      "command": "/Users/yourname/.local/bin/pygen",
      "args": [
        "mcp-serve",
        "sp_enterprise_process_industry/RigsbergProcessIndustries@v1",
        "-c", "greenfield",
        "-p", "eos-greenfield",
        "--org", "cog-ai",
        "--views", "RigsbergAsset,RigsbergFile,RigsbergMaintenanceOrder",
        "--ops", "list,search"
      ]
    }
  }
}

Note: Claude Desktop requires the full path to pygen since ~/.local/bin is not in its PATH.

Authentication

Uses interactive OAuth 2.0 Authorization Code Flow with PKCE (same as @cognite/dune):

• Opens browser for Entra ID login
• Local HTTPS callback server with self-signed certificate
• No .env files or client secrets required

Test Plan

• List tools expose all SDK filter parameters
• Search tools work with query and filters
• Aggregate tools work with count, group_by
• Histogram tools work with numeric properties
• Datetime filters accept ISO 8601 strings
• Direct relation filters accept object/array format
• Parameter descriptions extracted from SDK docstrings
• Required parameters (e.g., aggregate) are properly enforced, optional params have defaults
• --views flag filters to specified view external IDs
• --operations flag enables only specified operations

Bump

• Major
• Minor
• Patch
• Skip

Changelog

Added

• MCP (Model Context Protocol) server support for pygen-generated SDKs
• New CLI command pygen mcp-serve to launch MCP server from a data model ID
• Dynamic tool generation for list, retrieve, search, aggregate, and histogram operations
• Full parameter introspection with types and descriptions from SDK docstrings
• Interactive OAuth 2.0 authentication with PKCE flow
• Optional --graphql and --write flags for GraphQL queries and delete operations
• --views flag to filter which views are exposed as MCP tools
• --operations flag to control which operations are enabled (list, retrieve, search, aggregate, histogram)

Fixed

• Required parameters (like aggregate) are now properly enforced in MCP tool schemas

[gemini-code-assist]

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

[github-actions]

☂️ Python Coverage

current status: ✅

Overall Coverage

Lines	Covered	Coverage	Threshold	Status
5376	3654	68%	60%	🟢

New Files

File	Coverage	Status
cognite/pygen/_auth.py	38%	🟢
cognite/pygen/_mcp.py	10%	🟢
TOTAL	24%	🟢

Modified Files

File	Coverage	Status
cognite/pygen/cli.py	0%	🟢
TOTAL	0%	🟢

updated for commit: afde35a by action🐍