marqeta-diva-mcp 0.2.0__py3-none-any.whl

marqeta_diva_mcp-0.2.0.dist-info/METADATA

@@ -0,0 +1,515 @@
+Metadata-Version: 2.4
+Name: marqeta-diva-mcp
+Version: 0.2.0
+Summary: MCP server for Marqeta DiVA API - Data insights, Visualization, and Analytics
+Project-URL: Homepage, https://github.com/zvika-finally/marqeta-diva-mcp
+Project-URL: Repository, https://github.com/zvika-finally/marqeta-diva-mcp
+Project-URL: Issues, https://github.com/zvika-finally/marqeta-diva-mcp/issues
+Project-URL: Documentation, https://github.com/zvika-finally/marqeta-diva-mcp#readme
+Author-email: Zvika Badalov <zvika.badalov@finally.com>
+License: MIT
+License-File: LICENSE
+Keywords: analytics,api,diva,fintech,marqeta,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: all
+Requires-Dist: black>=23.0.0; extra == 'all'
+Requires-Dist: chromadb>=0.4.22; extra == 'all'
+Requires-Dist: pytest>=7.0.0; extra == 'all'
+Requires-Dist: ruff>=0.1.0; extra == 'all'
+Requires-Dist: sentence-transformers>=2.3.1; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: rag
+Requires-Dist: chromadb>=0.4.22; extra == 'rag'
+Requires-Dist: sentence-transformers>=2.3.1; extra == 'rag'
+Description-Content-Type: text/markdown
+
+# Marqeta DiVA API MCP Server
+
+[![PyPI version](https://badge.fury.io/py/marqeta-diva-mcp.svg)](https://badge.fury.io/py/marqeta-diva-mcp)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Model Context Protocol (MCP) server that provides programmatic access to the Marqeta DiVA (Data insights, Visualization, and Analytics) API. This server enables AI assistants and applications to retrieve aggregated production data from the Marqeta platform for reporting, analytics, and data-driven business decisions.
+
+> **Note:** This is an unofficial community project and is not officially supported by Marqeta.
+
+## Features
+
+### Core Features (Always Available)
+- **Transaction Data**: Access authorizations, settlements, clearings, declines, and loads
+- **Financial Data**: Retrieve program balances, settlement balances, and activity balances
+- **Card & User Data**: Get card and user details with flexible filtering
+- **Chargeback Data**: Access chargeback status and detailed information
+- **Metadata Tools**: Discover available views and retrieve schema definitions
+- **Export Tools**: Export data to JSON or CSV files
+- **Rate Limiting**: Built-in rate limiting to comply with API limits (300 requests per 5 minutes)
+- **Error Handling**: Comprehensive error handling with meaningful messages
+- **Flexible Querying**: Support for filtering, sorting, field selection, date ranges, and more
+
+### Optional RAG Features (Requires `[rag]` extras)
+- **Local Storage**: Store complete transaction data in SQLite (bypasses MCP token limits)
+- **Semantic Search**: Natural language queries on transaction data using AI embeddings
+- **Vector Store**: ChromaDB integration for similarity-based transaction search
+- **Offline Analysis**: Query local data without API calls or token limits
+
+## Prerequisites
+
+- Python 3.10 or higher
+- [uv](https://docs.astral.sh/uv/) package manager (for running with `uvx`)
+- Marqeta DiVA API credentials (Application Token, Access Token, and Program Name)
+
+## Installation
+
+### Option 1: Run with uvx (Recommended)
+
+No installation needed! `uvx` will automatically handle dependencies when you run the server.
+
+**For basic features only:**
+```bash
+uvx marqeta-diva-mcp
+```
+
+**For RAG features (local storage + semantic search):**
+```bash
+uvx --with marqeta-diva-mcp[rag] marqeta-diva-mcp
+```
+
+### Option 2: Traditional Installation
+
+**Basic installation (core features only):**
+```bash
+pip install marqeta-diva-mcp
+```
+
+**With RAG features (recommended for advanced analytics):**
+```bash
+pip install marqeta-diva-mcp[rag]
+```
+
+**From source:**
+```bash
+cd marqeta-diva-mcp
+pip install -e .              # Basic features
+pip install -e ".[rag]"       # With RAG features
+```
+
+## Configuration
+
+1. Copy the example environment file:
+
+```bash
+cp .env.example .env
+```
+
+2. Edit `.env` and add your Marqeta DiVA API credentials:
+
+```env
+# Required: Marqeta DiVA API credentials
+MARQETA_APP_TOKEN=your_application_token_here
+MARQETA_ACCESS_TOKEN=your_access_token_here
+MARQETA_PROGRAM=your_program_name_here
+
+# Optional: Enable local storage and RAG features
+# Requires: pip install marqeta-diva-mcp[rag]
+# ENABLE_LOCAL_STORAGE=true
+```
+
+**How to obtain credentials:**
+- Contact your Marqeta representative, OR
+- Generate via Marqeta Dashboard (Reports section)
+
+**Enabling RAG Features:**
+
+To use local storage, semantic search, and other RAG features:
+
+1. Install RAG dependencies: `pip install marqeta-diva-mcp[rag]`
+2. Set environment variable: `ENABLE_LOCAL_STORAGE=true`
+3. Restart the MCP server
+
+When enabled, you'll see this message in the logs:
+```
+[MCP Server] Local storage and RAG features ENABLED
+```
+
+When disabled (default):
+```
+[MCP Server] Local storage and RAG features DISABLED (set ENABLE_LOCAL_STORAGE=true to enable)
+```
+
+## Usage
+
+### Running the Server Locally
+
+#### With uvx (Recommended)
+
+```bash
+cd marqeta-diva-mcp
+uvx marqeta-diva-mcp
+```
+
+#### With Python
+
+```bash
+cd marqeta-diva-mcp
+python -m marqeta_diva_mcp.server
+```
+
+### Adding to Claude Desktop
+
+Add this configuration to your Claude Desktop config file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+
+#### Using uvx (Recommended)
+
+**Basic configuration (core features only):**
+```json
+{
+  "mcpServers": {
+    "marqeta-diva": {
+      "command": "uvx",
+      "args": ["marqeta-diva-mcp"],
+      "env": {
+        "MARQETA_APP_TOKEN": "your_application_token",
+        "MARQETA_ACCESS_TOKEN": "your_access_token",
+        "MARQETA_PROGRAM": "your_program_name"
+      }
+    }
+  }
+}
+```
+
+**With RAG features (local storage + semantic search):**
+```json
+{
+  "mcpServers": {
+    "marqeta-diva": {
+      "command": "uvx",
+      "args": ["--with", "marqeta-diva-mcp[rag]", "marqeta-diva-mcp"],
+      "env": {
+        "MARQETA_APP_TOKEN": "your_application_token",
+        "MARQETA_ACCESS_TOKEN": "your_access_token",
+        "MARQETA_PROGRAM": "your_program_name",
+        "ENABLE_LOCAL_STORAGE": "true"
+      }
+    }
+  }
+}
+```
+
+#### Using Python
+
+**Basic configuration (core features only):**
+```json
+{
+  "mcpServers": {
+    "marqeta-diva": {
+      "command": "python",
+      "args": ["-m", "marqeta_diva_mcp.server"],
+      "cwd": "/path/to/marqeta-diva-mcp",
+      "env": {
+        "MARQETA_APP_TOKEN": "your_application_token",
+        "MARQETA_ACCESS_TOKEN": "your_access_token",
+        "MARQETA_PROGRAM": "your_program_name"
+      }
+    }
+  }
+}
+```
+
+**With RAG features (requires `pip install -e ".[rag]"` first):**
+```json
+{
+  "mcpServers": {
+    "marqeta-diva": {
+      "command": "python",
+      "args": ["-m", "marqeta_diva_mcp.server"],
+      "cwd": "/path/to/marqeta-diva-mcp",
+      "env": {
+        "MARQETA_APP_TOKEN": "your_application_token",
+        "MARQETA_ACCESS_TOKEN": "your_access_token",
+        "MARQETA_PROGRAM": "your_program_name",
+        "ENABLE_LOCAL_STORAGE": "true"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Transaction Tools
+
+#### `get_authorizations`
+Get authorization transaction data with amounts, counts, acting users/cards, and merchant information.
+
+**Parameters:**
+- `aggregation` (string): `detail`, `day`, `week`, or `month` (default: `detail`)
+- `start_date` (string): Start date in ISO format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)
+- `end_date` (string): End date in ISO format
+- `fields` (array): Specific fields to return
+- `filters` (object): Additional filters (e.g., `{"transaction_amount": ">100"}`)
+- `sort_by` (string): Field to sort by (prefix with `-` for descending)
+- `count` (integer): Maximum records to return (up to 10,000)
+- `program` (string): Override default program name
+
+**Example:**
+```json
+{
+  "aggregation": "day",
+  "start_date": "2024-01-01",
+  "end_date": "2024-01-31",
+  "filters": {"transaction_amount": ">1000"},
+  "sort_by": "-request_amount",
+  "count": 100
+}
+```
+
+#### `get_settlements`
+Get settlement transaction data including status, post dates, purchase amounts, and network information.
+
+**Parameters:** Same as `get_authorizations`
+
+#### `get_clearings`
+Get accounting-level line items for transaction lifecycle. Ideal for reconciliation.
+
+**Parameters:** Same as `get_authorizations`
+
+#### `get_declines`
+Get declined transaction data with tokens, decline reasons, merchant info, and amounts.
+
+**Parameters:** Same as `get_authorizations`
+
+#### `get_loads`
+Get load transaction data including amounts and transaction details.
+
+**Parameters:** Same as `get_authorizations`
+
+### Financial Tools
+
+#### `get_program_balances`
+Get program-level balance data including beginning/ending bank balances and amounts to send/receive.
+
+**Parameters:**
+- `start_date`, `end_date`, `fields`, `filters`, `sort_by`, `count`, `program`
+
+#### `get_program_balances_settlement`
+Get settlement-based program balance data and fund transfers.
+
+**Parameters:** Same as `get_program_balances`
+
+#### `get_activity_balances`
+Get cardholder-level balance data, expandable by network.
+
+**Parameters:**
+- All standard parameters plus:
+- `expand` (string): Field to expand for more detail (e.g., network data)
+
+### Card & User Tools
+
+#### `get_cards`
+Get card detail data including user tokens, card state, active status, and UAI.
+
+**Parameters:**
+- `fields`, `filters`, `sort_by`, `count`, `program`
+
+**Example filters:**
+```json
+{
+  "filters": {
+    "state": "ACTIVE",
+    "user_token": "abc123"
+  }
+}
+```
+
+#### `get_users`
+Get user detail data including tokens, UAI, and number of physical/virtual cards.
+
+**Parameters:** Same as `get_cards`
+
+### Chargeback Tools
+
+#### `get_chargebacks_status`
+Get chargeback status data including state, tokens, and provisional credit status.
+
+**Parameters:**
+- `start_date`, `end_date`, `fields`, `filters`, `sort_by`, `count`, `program`
+
+#### `get_chargebacks_detail`
+Get detailed chargeback information with transaction dates and types.
+
+**Parameters:** Same as `get_chargebacks_status`
+
+### Metadata Tools
+
+#### `list_available_views`
+Get a list of all available DiVA API view endpoints with metadata.
+
+**Parameters:** None
+
+#### `get_view_schema`
+Get the schema definition for any view endpoint with field names, types, and descriptions.
+
+**Parameters:**
+- `view_name` (string, required): Name of the view (e.g., `authorizations`, `settlements`, `cards`)
+- `aggregation` (string): Aggregation level if applicable (default: `detail`)
+
+## Query Filtering
+
+The DiVA API supports powerful filtering operators:
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `~` | Like (wildcard) | `{"company": "Mar~eta"}` |
+| `..` | Range | `{"date": "2023-10-01..2023-10-03"}` |
+| `<`, `<=` | Less than | `{"amount": "<=100"}` |
+| `>`, `>=` | Greater than | `{"date": ">=2023-04-01"}` |
+| `=` | Equal/In list | `{"amount": "0"}` or `{"country": "United States,Mexico"}` |
+| `=!` | Not equal/Not in | `{"amount": "=!0"}` |
+
+**Example:**
+```json
+{
+  "filters": {
+    "transaction_amount": ">1000",
+    "post_date": "2023-02-01..2023-02-28",
+    "state": "COMPLETION"
+  }
+}
+```
+
+## Rate Limits
+
+- **Maximum:** 300 requests per 5-minute interval (≈1 per second)
+- **Enforcement:** Built-in rate limiter automatically throttles requests
+- **Error Code:** HTTP 429 if limit exceeded
+
+## Data Synchronization
+
+Report data is synchronized **3 times daily**. See Marqeta documentation for specific refresh timelines.
+
+## Error Handling
+
+The server handles all common DiVA API errors:
+
+| Code | Description |
+|------|-------------|
+| 400 | Bad Request - Malformed query or filter |
+| 403 | Forbidden - Unauthorized access to field, filter, or program |
+| 404 | Not Found - Malformed URL or endpoint doesn't exist |
+| 429 | Rate limit exceeded |
+
+## Example Usage with Claude
+
+Once configured in Claude Desktop, you can use natural language queries:
+
+**Example queries:**
+- "Get all authorization transactions from last week with amounts over $1000"
+- "Show me the settlement data for January 2024"
+- "List all active cards for user token abc123"
+- "What are the available views in the DiVA API?"
+- "Get the schema for the settlements view"
+- "Show me chargeback status for the last 30 days"
+- "Get program balances for February 2024"
+
+## API Documentation
+
+For complete DiVA API documentation, visit:
+https://www.marqeta.com/docs/diva-api/introduction/
+
+## Troubleshooting
+
+### Missing Credentials Error
+```
+Error: Missing required environment variables: MARQETA_APP_TOKEN, MARQETA_ACCESS_TOKEN, MARQETA_PROGRAM
+```
+**Solution:** Ensure your `.env` file exists and contains all three required variables.
+
+### Authentication Error (403)
+```
+Error 403: Forbidden - Unauthorized access
+```
+**Solution:** Verify your Application Token and Access Token are correct. Check that you have access to the specified program.
+
+### Rate Limit Error (429)
+```
+Error 429: Rate limit exceeded - Maximum 300 requests per 5 minutes
+```
+**Solution:** The built-in rate limiter should prevent this, but if you see it, wait a few minutes before making more requests.
+
+## Development
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Formatting
+
+```bash
+black src/
+ruff check src/
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/zvika-finally/marqeta-diva-mcp.git
+cd marqeta-diva-mcp
+
+# Install with development dependencies
+pip install -e ".[dev,rag]"
+
+# Run tests
+python test_fixes_unit.py
+
+# Format code
+black src/
+ruff check src/
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+**Zvika Badalov** - [zvika.badalov@finally.com](mailto:zvika.badalov@finally.com)
+
+## Acknowledgments
+
+- Built with [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
+- Powered by [Marqeta's DiVA API](https://www.marqeta.com/docs/diva-api/)
+
+## Support
+
+- **Issues:** [GitHub Issues](https://github.com/zvika-finally/marqeta-diva-mcp/issues)
+- **Marqeta API Questions:** Contact your Marqeta representative or refer to the [official Marqeta documentation](https://www.marqeta.com/docs/diva-api/introduction/)
+
+## Disclaimer
+
+This is an unofficial community project and is not officially endorsed or supported by Marqeta, Inc. Use at your own risk.

marqeta_diva_mcp-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+marqeta_diva_mcp/__init__.py,sha256=CcNeajXZ20SqiZY_XJHvPoN7GEJKmo7Vo4HYZexgHBA,58
+marqeta_diva_mcp/__main__.py,sha256=kXVU3ep8u6O2QBRWo2QR03DGQisp3MzS5CTqNnBdQh0,125
+marqeta_diva_mcp/client.py,sha256=_1z-si-zvQg4F6o7cfc6wI2kpjK7s0wQuwA5s38yzAA,16957
+marqeta_diva_mcp/embeddings.py,sha256=6BTSdsmhowH5vF5MHe7jDz2l-__RvjlE02H1zgRmx5I,4357
+marqeta_diva_mcp/local_storage.py,sha256=-tHRXa7WcNsTvVlZ1QCqtkULVBSHEmbPi6NVqu9ME2E,11414
+marqeta_diva_mcp/rag_tools.py,sha256=DYMOGzwhXIIgAuhm78ZNuyxrO2IZ5JzHi5L0QIWAl_w,11944
+marqeta_diva_mcp/server.py,sha256=L2zpH7qEeWvhGPiRsV1Sp_NK1jiEPCxY8y-dHVaP4zU,40249
+marqeta_diva_mcp/vector_store.py,sha256=LWbjY_i10W-PI92ApE5zCvdQBOrBBYXDdStYawbk5zE,9753
+marqeta_diva_mcp-0.2.0.dist-info/METADATA,sha256=5_FkB8tZqwUsqQUdyJO3-CU9vhXvgC7jFGugZjZ9c_w,15285
+marqeta_diva_mcp-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+marqeta_diva_mcp-0.2.0.dist-info/entry_points.txt,sha256=McJosMo_ymnQhLuOpJ3l62qM7z9U_ssW3Ugn-Y8HZJ4,66
+marqeta_diva_mcp-0.2.0.dist-info/licenses/LICENSE,sha256=bxGQUnY1nbevspSFL72pJrNvPwdFFExKHEKnQ665kfs,1070
+marqeta_diva_mcp-0.2.0.dist-info/RECORD,,

marqeta_diva_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

marqeta_diva_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+marqeta-diva-mcp = marqeta_diva_mcp.server:main

marqeta_diva_mcp-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zvika Badalov
+
+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.