Metadata-Version: 2.4
Name: HeronIntelligence-mcp
Version: 1.2.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
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 Blue Heron (human) vs Heron AI (automated) provenance
handling.

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

| 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. |
| `get_company_overview` | Returns transcript counts, date range, and breakdown of available coverage for a company. |
| `get_recent_transcripts` | Lists transcript metadata with pagination and filters (due-diligence type, sentiment, call quality, free text). |
| `get_transcript_content` | Returns the verbatim Q&A content of a specific transcript. |
| `get_project_status` | Returns the current step, completed fields, and last artifact for a research project. |

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

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

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