Metadata-Version: 2.4
Name: provenance-mcp
Version: 1.1.0
Summary: MCP server for the Provenance platform — connect AI agents to your provenance data
Project-URL: Homepage, https://www.stdiolabs.dev
Project-URL: Repository, https://github.com/stdiolabs/provenance-mcp
Project-URL: Documentation, https://provenance.dev/docs/ecosystem/mcp
Project-URL: Issues, https://github.com/stdiolabs/provenance-mcp/issues
Author-email: STDIO Labs <hello@stdiolabs.dev>
License: MIT License
        
        Copyright (c) 2025 STDIO Labs
        
        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.
License-File: LICENSE
Keywords: agents,ai,audit,mcp,model-context-protocol,provenance,tracking
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://www.stdiolabs.dev/images/stdio-logo-white-font.png" alt="STDIO Labs" height="32" />
</p>

<h1 align="center">Provenance MCP Server</h1>

<p align="center">
  <a href="https://modelcontextprotocol.io">Model Context Protocol</a> server for the <a href="https://provenance.dev">Provenance</a> platform — connect AI agents to your provenance data.
</p>

<p align="center">
  <a href="https://pypi.org/project/provenance-mcp/"><img src="https://img.shields.io/pypi/v/provenance-mcp" alt="PyPI version" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
  <a href="https://www.python.org"><img src="https://img.shields.io/badge/python-%3E%3D3.10-blue" alt="Python Version" /></a>
</p>

---

## Installation

```bash
pip install provenance-mcp
```

## Quick Start

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "provenance": {
      "command": "provenance-mcp",
      "env": {
        "PROVENANCE_API_URL": "https://your-api.provenance.dev/api",
        "PROVENANCE_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Amazon Q Developer

Add to your Amazon Q MCP config:

```json
{
  "mcpServers": {
    "provenance": {
      "command": "provenance-mcp",
      "env": {
        "PROVENANCE_API_URL": "https://your-api.provenance.dev/api",
        "PROVENANCE_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Cursor / Windsurf / Other MCP Clients

Same pattern — set the command to `provenance-mcp` and provide the env vars.

## Authentication

### API Key (default)

```bash
provenance-mcp
```

Set `PROVENANCE_API_KEY` in your environment or MCP client config.

### OAuth2 (client credentials)

```bash
provenance-mcp-oauth
```

Set `PROVENANCE_CLIENT_ID` and `PROVENANCE_CLIENT_SECRET`. Tokens auto-refresh on expiry.

## Environment Variables

| Variable                   | Required | Default                                    | Description                |
| -------------------------- | -------- | ------------------------------------------ | -------------------------- |
| `PROVENANCE_API_URL`       | Yes      | `http://localhost:4000/api`                | Provenance API base URL    |
| `PROVENANCE_API_KEY`       | Yes\*    | —                                          | API key for authentication |
| `PROVENANCE_CLIENT_ID`     | Yes\*\*  | —                                          | OAuth2 client ID           |
| `PROVENANCE_CLIENT_SECRET` | Yes\*\*  | —                                          | OAuth2 client secret       |
| `PROVENANCE_PLATFORM_URL`  | No       | `https://provenance-platform.onrender.com` | Platform URL (OAuth mode)  |

\* Required for `provenance-mcp`
\*\* Required for `provenance-mcp-oauth`

## Available Tools

The server exposes 80+ tools covering the full Provenance API:

### Core

- **query_interactions** — Search interactions by resource, action, origin, time range, spanId, parentSpanId
- **create_interaction** — Record a new provenance event (accepts optional `spanId` and `parentSpanId` for span hierarchy)
- **search_activity** — Advanced multi-filter search
- **get_trace** — Get full interaction history for a resource

### Configuration

- **get/create/update/delete_resource_type** — Manage resource types
- **get/create/update/delete_action** — Manage actions
- **get/create/update/delete_origin** — Manage origins

### Analytics

- **query_analytics** — Run analytics queries with metrics, dimensions, filters
- **get_home_dashboard** — Get dashboard summary data
- **get/create/update/delete_dashboard** — Manage dashboards
- **get/create/update/delete_widget** — Manage dashboard widgets
- **get_widget_data** — Get rendered widget data

### Notifications

- **get/create/update/delete_subscriber** — Manage notification subscribers
- **get/create/update/delete_subscription** — Manage event subscriptions
- **pause/resume_subscription** — Control subscription state
- **get_queue_stats** / **process_queue** — Monitor notification queue

### Alerting

- **get/create/update/delete_interaction_alert** — Manage alerts
- **get_alert_states** / **evaluate_alerts** — Monitor alert status
- **get/create/update/delete_interaction_metric** — Manage metrics
- **calculate_metric** — Calculate metric values

### Inbound Webhooks

- **get/create/update/delete_inbound_source** — Manage webhook sources
- **get/create/update/delete_inbound_mapping** — Manage payload mappings
- **test_inbound_mapping** — Test mappings against sample payloads

### Secrets

- **get/create/update/delete_secret** — Manage secrets
- **test_secret** — Verify secret resolution
- **get/create/update/delete_secret_provider** — Manage provider connections

### Adapters

- **get_adapters** / **get_adapter** — Browse notification adapters
- **publish_adapter** — Publish custom adapters
- **get/create/update/delete_adapter_setting** — Manage adapter config

## Development

```bash
git clone https://github.com/stdiolabs/provenance-mcp.git
cd provenance-mcp
pip install -e .

# Run locally
PROVENANCE_API_KEY=your-key provenance-mcp
```

## Related Projects

- [Provenance API](https://github.com/stdiolabs/provenance) — Backend REST API
- [Provenance UI](https://github.com/stdiolabs/provenance-ui) — Web dashboard
- [Provenance CLI](https://github.com/stdiolabs/provenance-cli) — Command-line interface
- [Provenance SDK](https://github.com/stdiolabs/provenance-sdk) — Node.js SDK

## License

MIT — [STDIO Labs](https://www.stdiolabs.dev)
