Metadata-Version: 2.4
Name: HeronIntelligence-mcp
Version: 1.7.0
Summary: Heron Intelligence — MCP server for AI assistants
Project-URL: Homepage, https://www.heron-intelligence.com
Project-URL: Documentation, https://docs.heron-intelligence.com/mcp
Project-URL: Repository, https://github.com/Heron-Intelligence/heron-intelligence-mcp
Project-URL: Issues, https://github.com/Heron-Intelligence/heron-intelligence-mcp/issues
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,due-diligence,earnings,finance,heron,heron-intelligence,mcp,private-equity,transcripts
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: sentry-sdk>=2.43.0
Provides-Extra: http
Requires-Dist: fastapi>=0.115.0; extra == 'http'
Requires-Dist: starlette>=0.40.0; extra == 'http'
Requires-Dist: uvicorn>=0.29.0; extra == 'http'
Description-Content-Type: text/markdown

# Heron Intelligence MCP

Connect Heron Intelligence — curated earnings call transcripts, management
interviews, and a guided custom-research intake flow — directly to Claude or
any [Model Context Protocol](https://modelcontextprotocol.io)-compatible AI
client.

## Highlights

- **Remote HTTPS transport** — one URL, zero install for browser clients.
- **OAuth 2.1** — Dynamic Client Registration (RFC 7591) with PKCE S256.
- **Subsidiary & legacy-name resolution** — search by ticker, name, or
  description; the server auto-maps spinoffs and rebrands to their current
  parent so coverage is never missed.
- **MCP tool annotations** — read-only tools auto-approve in supporting
  clients; write tools always require explicit user confirmation.

## Server

```
https://mcp.heron-intelligence.com/mcp
```

## Skill (recommended — install first)

The repo ships a Claude Code Skill in [`skills/heron-intelligence/`](./skills/heron-intelligence/)
that primes the model to use these tools automatically — without the user
having to type "use Heron MCP to…". It also encodes formatting rules and the
canonical provenance handling: Blue Heron (human-conducted), Heron AI
(AI-conducted), and licensed third-party feeds such as Paragon — each named
explicitly so the origin of every transcript stays visible to the user.

Install once per machine (org-wide):

```bash
cp -r skills/heron-intelligence ~/.claude/skills/
```

Restart Claude Code; verify with `/list-skills`. See
[`skills/heron-intelligence/INSTALL.md`](./skills/heron-intelligence/INSTALL.md)
for project-level install and team distribution.

## Quickstart

### Claude.ai (recommended)

1. Open Claude.ai → **Settings → Connectors**.
2. Click **Add custom connector**.
3. Enter the server URL above.
4. Click **Authorize** and sign in to Heron Intelligence.
5. Approve the requested scopes (`mcp:read`, `mcp:write`).
6. Start a new chat and ask Claude to use Heron Intelligence.

### Claude Desktop

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "heron": {
      "command": "uvx",
      "args": ["--from", "HeronIntelligence-mcp", "heronintelligence-mcp"],
      "env": { "HERON_API_KEY": "hk-xxxx" }
    }
  }
}
```

Restart Claude Desktop.

### Claude Code

```bash
claude mcp add heron \
  --command uvx \
  --args "--from HeronIntelligence-mcp heronintelligence-mcp" \
  -e HERON_API_KEY=hk-xxxx \
  -s user
```

### Cursor / Windsurf

```json
{
  "mcpServers": {
    "heron": {
      "command": "uvx",
      "args": ["--from", "HeronIntelligence-mcp", "heronintelligence-mcp"],
      "env": { "HERON_API_KEY": "hk-xxxx" }
    }
  }
}
```

## Authentication

The remote MCP server uses **OAuth 2.1** with PKCE (S256) and **Dynamic Client
Registration** (RFC 7591). Connecting from Claude.ai:

1. Claude registers itself silently as an OAuth client.
2. You are redirected to Heron Intelligence to sign in.
3. After consent, Claude receives a short-lived access token plus a refresh
   token. The refresh token is single-use and rotates on every refresh.
4. Scopes `mcp:read` and `mcp:write` map to read-only and write tools.

For local **stdio** mode (Claude Desktop / Claude Code / Cursor / Windsurf),
authenticate with a static API key via `HERON_API_KEY`. Request a key from
your Heron Intelligence account dashboard.

## Available tools

### Read-only — research

| Tool | Purpose |
| --- | --- |
| `whoami` | Returns the email of the user authenticated on the current MCP session. |
| `search_company` | Resolves a ticker, name, or description to a Heron Intelligence company id; auto-resolves subsidiaries and legacy names. |
| `search_companies` | Resolves MANY tickers/names/descriptions to company ids in one call; returns a deduped `resolved_ids` array. Preferred first step for watchlists, peer sets, or "compare X, Y, Z". |
| `search_people` | Semantic search over interviewed people (executives, channel contacts, former employees). Scope to one company with `company_id`, or to specific sources with `data_provider_names`; each person carries their provider attribution. |
| `get_company_overview` | Returns transcript counts, date range, and breakdown of available coverage for a company. |
| `get_companies_overview` | Coverage overview for many company ids in one call — batch coverage audit across a watchlist/peer set. |
| `get_recent_transcripts` | Lists transcript metadata with pagination and filters (due-diligence type, sentiment, call quality, free text). |
| `get_transcript_content` | Returns transcript content, with optional payload selectors (`summary_only`, `limit_qa`, `max_qa_answer_chars`, `qa_ids`) to trim the response before the caller reads it. |
| `get_project_status` | Returns the current step, completed fields, and last artifact for a research project. |

### Read-only — watchlists

| Tool | Purpose |
| --- | --- |
| `list_watchlists` | Lists every watchlist the user can see (own, firm-level, shared). |
| `get_watchlist` | Returns the companies in a watchlist, looked up by exact name (case-insensitive). |

### Read-only — drops (saved monitoring rules)

| Tool | Purpose |
| --- | --- |
| `list_drops` | Lists every drop the user can see (own + firm-shared + team-shared) with `visibility` and `is_owner` flags. |
| `get_recent_drops` | Returns drop firings across all visible drops in the last N days (default 7, max 90). |
| `get_drop_history` | Returns the firing history of a single drop, most recent first. |
| `list_analysis_categories` | Lists the catalog categories valid for `type=analysis` drops. |
| `list_report_templates` | Lists the report templates available to the user (user-own + system). |

### Write — custom research projects

| Tool | Purpose |
| --- | --- |
| `start_research_project` | Creates a new research project record. |
| `define_research_brief` | Step 1 — refines the Research Brief artifact one user turn at a time. |
| `prepopulate_research_configuration` | Step 1 → Step 2 helper that pre-fills configuration fields from the brief. |
| `configure_research_project` | Step 2 — fills the project's canonical configuration fields. |
| `generate_research_questions` | Step 3 — generates and curates the project's topics and questions. |
| `submit_research_project` | Step 4 — submits the project to a Heron Intelligence representative. |

### Write — watchlists

| Tool | Purpose |
| --- | --- |
| `create_watchlist` | Creates a new watchlist, optionally pre-populated with tickers or company names. |
| `rename_watchlist` | Renames an existing watchlist. |
| `add_to_watchlist` | Adds companies (by ticker or name) to an existing watchlist. |
| `remove_from_watchlist` | Removes companies from a watchlist. |
| `delete_watchlist` | Permanently deletes a watchlist (requires `confirm=true`). |

### Write — drops

| Tool | Purpose |
| --- | --- |
| `create_drop` | Creates a new drop (`notification` / `report` / `analysis`) with cadence- or threshold-based triggering. |
| `update_drop` | Partially updates a drop, including rename and scope replacement. |
| `pause_drop` | Pauses an active drop (stops firing without losing config). |
| `resume_drop` | Resumes a paused drop. |
| `delete_drop` | Soft-deletes a drop (requires `confirm=true`). |

## Example prompts

> *"How much research coverage does Heron Intelligence have on Amazon?"*

> *"Find Heron Intelligence's research coverage for Facebook and show me what's available under their current corporate entity."*

> *"Show me only the management due diligence transcripts available for Amazon from the last two quarters."*

> *"Set up a weekly digest of new Energy-sector transcripts that mention margin compression."*

> *"What drops do I have set up? Show me the ones that fired this week."*

> *"Add MSFT and NVDA to my Tech watchlist, then create an analysis drop on that watchlist using the Executive Assessment category."*

## Documentation

Full documentation: <https://docs.heron-intelligence.com/mcp>

## Privacy

<https://www.heron-intelligence.com/privacy-policy>

## Support

- Email: [support@heron-intelligence.com](mailto:support@heron-intelligence.com)
- Issues: <https://github.com/Heron-Intelligence/heron-intelligence-mcp/issues>

## License

Released under the Apache License 2.0 — see [LICENSE](./LICENSE). Use of the
hosted Heron Intelligence service requires an active account.
