Metadata-Version: 2.4
Name: supernova-connector
Version: 1.0.0
Summary: MCP stdio connector for the Supernova tool marketplace (supernova.cool)
Author-email: Data Genius LLC <support@agenticharness.cloud>
License: MIT
Project-URL: Homepage, https://supernova.cool
Project-URL: Documentation, https://supernova.cool/docs
Project-URL: Repository, https://github.com/datagenuis/supernova-connector
Keywords: mcp,supernova,agent,tools,marketplace
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Supernova MCP Connector

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Supernova** is a hosted MCP tool marketplace at [supernova.cool](https://supernova.cool). Publish REST APIs as paid MCP tools, discover and call them with metering, auth, and real-time analytics.

This package provides a Python stdio MCP connector that gives Claude Desktop, Cursor, and other MCP-compatible clients access to the Supernova tool registry.

## Installation

```bash
pip install supernova-connector
```

## MCP Configuration (Claude Desktop / Cursor)

### Option 1: Hosted MCP URL (Recommended)

```json
{
  "mcpServers": {
    "supernova": {
      "url": "https://supernova.cool/api/v1/mcp/",
      "headers": {
        "X-Supernova-Key": "YOUR_API_KEY"
      }
    }
  }
}
```

### Option 2: stdio Connector

```json
{
  "mcpServers": {
    "supernova": {
      "command": "supernova-connector",
      "env": {
        "SUPERNOVA_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

## Python SDK Usage

```python
from supernova_connector import SupernovaClient, Swarm

# Discover tools by intent
results = SupernovaClient.discover("fetch a URL and extract the title")
print(results)

# Execute a tool
result = SupernovaClient.execute(
    tool_id="core-001",
    payload={"query": "https://news.ycombinator.com"}
)
print(result)

# Get a Swarm WebSocket connection string
swarm = Swarm(agent_id="my-agent-id")
print("WebSocket URL:", swarm.get_connection_string())
```

## Available Tools

The connector exposes three MCP tools:

| Tool | Description |
|------|-------------|
| `discover_tools` | Search the Supernova registry using natural language |
| `execute_tool` | Execute any tool by its ID |
| `connect_to_swarm` | Get a WebSocket URL for real-time agent messaging |

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SUPERNOVA_API_KEY` | `anonymous` | Your API key from the [portal](https://supernova.cool/portal) |
| `SUPERNOVA_API_BASE` | `https://supernova.cool/api/v1` | API base URL |
| `SUPERNOVA_WS_BASE` | `wss://supernova.cool/api/v1/swarm/stream` | WebSocket base URL |

## Pricing

- Free tier: 1,000 NOVA credits on signup (1 NOVA ≈ $0.001 USD)
- Tool calls cost 0.5–1.0 NOVA each
- Credit packs available from $10–$250 via Stripe

## Documentation

- [Supernova Docs](https://supernova.cool/docs)
- [API Reference](https://supernova.cool/docs#api-reference)
- [Security](https://supernova.cool/security)

## License

MIT — operated by [Data Genius LLC](https://supernova.cool/contact)
