ai-assisted-insights-agent

The AI-Assisted Insights Agent is an MCP agent that translates natural language questions into accurate, explainable, and reproducible data insights. It provides an accessible natural language interface for querying a data lake or warehouse, generating SQL via trusted metric definitions, and returning explainability context such as the underlying query, data quality signals, and assumptions. The agent is designed to work with a semantic metric layer to ensure consistent business logic and governance across queries, making it easier for analysts and stakeholders to collaborate without losing transparency.

Within MCP, you can access the agent's capabilities through a set of tools exposed by the server. Key tools include ask_question to pose questions in natural language, generate_query to produce SQL for a specific metric and time window, validate_query to check SQL correctness, explain_result to get interpretation and context for results, and suggest_followups to surface relevant follow-up questions. There are also utilities to save and manage query templates, compare metrics, and check data quality. These tools enable a reproducible workflow where every insight is tied to its underlying query and metric definitions, with an audit trail for validation and governance. You can integrate the agent with your existing data sources and semantic layers to maintain consistent business logic across analyses.

Prerequisites:

• Python 3.10 or higher
• pip (or uv as an alternative package manager)

Option 1: Install from Source

# Clone the repository
git clone https://github.com/jkelleman/ai-assisted-insights-agent.git
cd ai-assisted-insights-agent

# Install with pip in editable mode
pip install -e .

# Or install with uv (recommended for some environments)
uv pip install -e .

Option 2: Install as Package

pip install git+https://github.com/jkelleman/ai-assisted-insights-agent.git

Verify Installation

# Test the CLI (if provided by the package)
python -m insights_agent.cli

# Run tests (if available)
pytest 05_tests/

Starting the MCP Server (example)

python -m insights_agent.server

Prerequisites recap if you hit issues:

• Ensure Python 3.10+ is active in your environment
• Ensure dependencies can be installed (build tools, network access)
• If using uv, ensure you have uv installed in your environment
• Confirm you are in the project root or have the package installed in your environment

Tips and common considerations:

• Configuration is driven by a config.yaml that defines metrics and glossary terms. Customize metrics and table references to match your data sources.
• The MCP server exposes several tools for interaction; integrate with your data catalog and semantic layer to maintain consistent metrics across queries.
• When deploying in production, consider pinning dependencies and using a virtual environment to avoid conflicts.
• If you integrate with Claude or other desktop clients, you can point them to the MCP server with the appropriate command and working directory as shown in the README examples.
• Common issues include Python environment mismatches, missing dependencies, and incorrect metric references in config.yaml. Validate config.yaml against your data sources and metric definitions before starting the server.
• For debugging, run the server in a verbose or debug mode if supported by the package, and consult the query templates and history resources to diagnose problems with queries or data quality signals.