Metadata-Version: 2.4
Name: heisenberg-mcp-server
Version: 0.3.0
Summary: A Model Context Protocol server that enables capable LLMs to work with Heisenberg features, such as inference
Author-email: SeshatLabs <info@seshatlabs.xyz>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: mcp<2.0.0,>=1.9.2
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: python-decouple>=3.8
Provides-Extra: dev
Requires-Dist: pytest<9.0.0,>=8.4.0; extra == "dev"

# Heisenberg FastMCP Agent

A Model Context Protocol server that provides tools to interact with Heisenberg services for real-time data analysis, social media monitoring, and specialized AI agent interactions.

## Available Tools

### Core Agent Tools

- **`list_of_agents`** - Retrieves all available AI agents for specialized data analysis
  - **When to use**: Automatically called for any request involving current events, real-time data, social media analysis, or domain-specific information
  - **Returns**: List of available agents with their IDs and descriptions

- **`inference_from_prompt`** - Queries specialized agents for current data or domain-specific analysis
  - **Required arguments**:
    - `agent_id` (integer): The ID of the agent (obtained from `list_of_agents`)
    - `prompt` (string): The text prompt for analysis

### Twitter/X Trend Analysis Tools

- **`twitter_trends_options`** - Get available parameters for Twitter trend analysis
  - **When to use**: MUST be called first before using `twitter_trends()`
  - **Returns**: Available verticals (categories) and durations (time periods)

- **`twitter_trends`** - Analyze Twitter/X trends for specific categories and time periods
  - **Required arguments**:
    - `vertical` (string): Category from options (e.g., "politics", "tech", "sports")
    - `duration` (string): Time period from options (e.g., "1h", "24h", "7d")

## Installation

### Using uv (recommended)
```bash
uvx heisenberg-mcp-server
```

### Using PIP
```bash
pip install heisenberg-mcp-server
```

Run as a script:
```bash
python -m heisenberg
```

## Configuration

### Configure for Claude.app

<details>
<summary>Using uvx</summary>

```json
{
    "mcpServers": {
        "heisenberg": {
            "command": "uvx",
            "args": [
                "heisenberg-mcp-server"
            ],
            "env": {
                "HEISENBERG_TOKEN": "*****",
                "HEISENBERG_KEY": "*****"
            },
            "timeout": 60000
        }
    }
}
```
</details>

<details>
<summary>Using pip installation</summary>

```json
{
    "mcpServers": {
        "heisenberg": {
            "command": "python",
            "args": [
                "-m",
                "heisenberg"
            ],
            "env": {
                "HEISENBERG_TOKEN": "*****",
                "HEISENBERG_KEY": "*****"
            },
            "timeout": 60000
        }
    }
}
```
</details>

## Example Interactions

### 1. Political Analysis on X/Twitter
```json
{
    "agent_id": 1,
    "prompt": "What are the latest political conversations on X about the upcoming elections?"
}
```
Response:
```json
[
    {
        "tweet_text": "Special election results hint at what's next for Congress' power balance",
        "tweet_time": "2025-04-02T11:44:41Z",
        "tweet_url": "https://x.com/FoxNews/status/1907398780615373105"
    }
]
```

### 2. Twitter Trends Analysis
First, get available options:
```python
twitter_trends_options()
# Returns: {"verticals": ["AI", "Crypto", "Football"], "durations": ["last_3_day", "last_day", "last_week"]}
```

Then analyze trends:
```python
twitter_trends(vertical="Crypto", duration="last_day")
# Returns trending crypto topics from the last day
```

## Workflow Summary

1. **For general current data needs:**
    - `list_of_agents()` → Select relevant agent → `inference_from_prompt()`

2. **For Twitter/X specific trends:**
    - `twitter_trends_options()` → Select parameters → `twitter_trends()`

## Use Cases

- **Real-time Social Media Monitoring**: Track conversations and trends across platforms
- **Current Events Analysis**: Get up-to-date information on news and world events
- **Market Intelligence**: Monitor financial trends and market sentiment
- **Technology Trends**: Track emerging tech topics and developer discussions
- **Entertainment & Sports**: Follow trending topics and cultural phenomena

## Requirements

- Valid Heisenberg API tokens (HEISENBERG_TOKEN and HEISENBERG_KEY)
- Network access to Heisenberg services
