Data Planning

You can run the Data Planning Agent MCP server to transform vague business intents into structured, machine-readable Data PRPs through interactive conversations. It exposes both a local STDIO server for quick testing and an HTTP transport when you want to host it as a service for Cursor or other MCP clients. The server orchestrates AI-powered requirement gathering and outputs a standardized Data PRP document that downstream agents can consume.

How to use

Connect to the MCP server from your MCP client using the STDIO transport (the default) or the HTTP transport. You will initiate a planning session by providing an initial business intent, answer clarifying questions, and eventually generate a Data PRP markdown file that details the data requirements, metrics, dimensions, filters, and success criteria.

How to install

Prerequisites: Install Python 3.10 or higher and Poetry for dependency management. Obtain a Gemini API key to enable AI-powered conversations.

poetry install

# Create environment from template
cp .env.example .env

# Populate your Gemini API key and other settings in .env
# Example:
# GEMINI_API_KEY=your-gemini-api-key-here
# GEMINI_MODEL=gemini-2.5-pro
# OUTPUT_DIR=./output
# MCP_TRANSPORT=stdio
# LOG_LEVEL=INFO

Configuration

Environment variables control how the planning agent runs and how it stores outputs. The following variables appear in the configuration: GEMINI_API_KEY, GEMINI_MODEL, OUTPUT_DIR, CONTEXT_DIR, MCP_TRANSPORT, MCP_HOST, MCP_PORT, MAX_CONVERSATION_TURNS, and LOG_LEVEL.

# .env
GEMINI_API_KEY=your-gemini-api-key-here
GEMINI_MODEL=gemini-2.5-pro
OUTPUT_DIR=./output
MCP_TRANSPORT=stdio
LOG_LEVEL=INFO
# Optional (examples)
CONTEXT_DIR=./context
MCP_HOST=0.0.0.0
MCP_PORT=8080
MAX_CONVERSATION_TURNS=10

Usage with an MCP client

1. Start the server in STDIO mode for local development.

poetry run python -m data_planning_agent.mcp

Usage with Cursor

If you are integrating with Cursor, run the server with the HTTP transport by setting MCP_TRANSPORT to http in your environment, then configure Cursor to connect via the appropriate HTTP endpoint.

Data PRP output

The final Data PRP is generated as a Markdown document containing an executive summary, business context, data requirements (metrics, dimensions, filters), and success criteria. This document is saved to the configured OUTPUT_DIR and can be stored locally or in a GCS bucket if you specify a cloud path.

Organizational context

You can tailor the AI agent by loading organizational context files. These Markdown files provide company terminology, SOPs, governance policies, constraints, and preferred communication styles. Context is prepended to all AI prompts and is loaded automatically when the agent starts.

Notes on testing

Test interactions with the Interactive CLI to simulate a real planning session. The CLI guides you through entering an initial intent, answering clarifying questions, and generating the final PRP.

Troubleshooting

Common issues include missing Gemini API keys, session timeouts, GCS permission errors, or a Cursor connection problem. Ensure .env contains a valid GEMINI_API_KEY, adjust MAX_CONVERSATION_TURNS if needed, verify GCP credentials for GCS, and confirm MCP_TRANSPORT and connection settings when using Cursor.

Available tools

GeminiClient

Wraps Gemini API to conduct conversations with the user and guide requirement refinement.

StorageClient

Handles local and GCS I/O for saving outputs and loading context.

ConversationManager

Manages planning session state across prompts and questions.

PRPGenerator

Generates the final Data PRP markdown document from refined inputs.

MCPServer

Provides STDIO/API transports for MCP clients to interact with the agent.