marqeta-diva-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Marqeta DiVA MCP Server - A Model Context Protocol (MCP) server providing programmatic access to Marqeta's DiVA (Data insights, Visualization, and Analytics) API. The server enables AI assistants to retrieve aggregated production data for reporting, analytics, and data-driven business decisions.

Key Technologies:

• Python 3.10+ with uv package manager
• MCP (Model Context Protocol) for AI assistant integration
• httpx for HTTP client
• SQLite for local transaction storage (optional, requires [rag] extras)
• ChromaDB for vector embeddings (optional, requires [rag] extras)
• sentence-transformers for semantic search (optional, requires [rag] extras)

Common Commands

Development Setup

# Install basic dependencies
pip install -e .

# Install with RAG features (optional)
pip install -e ".[rag]"

# Run the server locally
uvx marqeta-diva-mcp
# OR
python -m marqeta_diva_mcp.server

Enabling Optional Features

RAG Features (local storage + semantic search):

# 1. Install dependencies
pip install marqeta-diva-mcp[rag]

# 2. Enable in environment
export ENABLE_LOCAL_STORAGE=true

# 3. Verify in logs
# You should see: "[MCP Server] Local storage and RAG features ENABLED"

Testing

# Run specific test files
python test_rag.py              # Test RAG/semantic search features
python test_pagination.py       # Test pagination and large datasets
python test_date_filtering.py   # Test date filtering
python test_fixes.py           # Integration tests for key fixes
python test_fixes_unit.py      # Unit tests

Code Quality

# Format code
black src/

# Lint code
ruff check src/

Environment Configuration

Required environment variables in .env:

MARQETA_APP_TOKEN=your_application_token
MARQETA_ACCESS_TOKEN=your_access_token
MARQETA_PROGRAM=your_program_name

# Optional: Enable RAG features
ENABLE_LOCAL_STORAGE=true  # Default: false