Metadata-Version: 2.5
Name: HeronIntelligence-mcp
Version: 1.9.1
Summary: Heron Intelligence — MCP server for AI assistants
Project-URL: Homepage, https://www.heron-intelligence.com
Project-URL: Documentation, https://docs.heron-intelligence.com/overview/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 land on a Heron Intelligence consent page that names the application
   requesting access and asks for the Client ID and Client Secret issued to
   your seat. Get them from your account dashboard, or from your Heron
   administrator.
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. The server advertises the scopes `mcp:read` and `mcp:write`, and Claude
   requests both. Access to a given tool is decided by your own entitlements
   on the Heron Intelligence account behind the token.

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. Accepts a **list** of queries too, routed to the same batch path as `search_companies`, so resolving many names never needs a loop. |
| `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). An empty page carries a `coverage` block: whether the window was widened for you, or that no coverage exists at all — with a `next_step` toward commissioned research when it does not. |
| `list_data_providers` | Lists the exact `data_provider_names` values the transcript and people tools accept, with how each source is produced. No backend call, no quota — call it instead of guessing a source name. |
| `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 — alerts (saved monitoring rules)

| Tool | Purpose |
| --- | --- |
| `list_alerts` | Lists every alert the user can see (own + firm-shared + team-shared) with `visibility` and `is_owner` flags. |
| `get_recent_alerts` | Returns alert firings across all visible alerts in the last N days (default 7, max 90). |
| `get_alert_history` | Returns the firing history of a single alert, most recent first. |
| `list_analysis_categories` | Lists the catalog categories valid for `type=analysis` alerts. |
| `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 — alerts

| Tool | Purpose |
| --- | --- |
| `create_alert` | Creates a new alert (`notification` / `report` / `analysis`) with cadence- or threshold-based triggering. |
| `update_alert` | Partially updates an alert, including rename and scope replacement. |
| `pause_alert` | Pauses an active alert (stops firing without losing config). |
| `resume_alert` | Resumes a paused alert. |
| `delete_alert` | Soft-deletes an alert (requires `confirm=true`). |

The alert tools were called drops before the Portal renamed the module. Only
the alert names are listed in `tools/list`; a call that still uses an old name
(`list_drops`, `create_drop`, ...) is served by the alert tool and its response
carries `renamed_to` with the name to use.

### Access by plan

Heron Events Platinum firms (`firm_type = he_premium`) do not get the Research
Projects or Evasion tools: they are left out of `tools/list` and a call by name
returns `{"error": "tool_not_in_plan", ...}`. The caller's tier comes from the
API's `GET /api/v1/auth/caller`; when it cannot be read, nothing is restricted.

## 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 alerts 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 alert on that watchlist using the Executive Assessment category."*

## Documentation

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

## Privacy Policy

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

The policy covers what is collected, how it is used and stored, third-party
sharing, retention, and who to contact. What this MCP server itself handles:

- **Identity.** OAuth resolves the connecting user to their Heron Intelligence
  account; `whoami` returns that email. No other profile data is read.
- **Tool arguments and results.** Queries are forwarded to Heron
  Intelligence's own first-party API and the response is returned to the
  client. Nothing is proxied to a third party.
- **Operational records.** One structured access line per request (method,
  path, status, latency, request id, and the resolved account), with the
  credential redacted out of the path before the line is written. Each tool
  call also records a usage event to Heron Intelligence's own backend — tool
  name, the arguments it was called with, a short summary of the result,
  status and duration — used for quota enforcement and support.
- **Not collected.** Conversation content, chat history, memory, or user
  files. The server reads only the arguments a tool is called with.

## 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.
