signal8-mcp

# @signal8ai/mcp

MCP (Model Context Protocol) server for [Signal8](https://signal8.ai) -- AI-extracted SEC filing intelligence data.

Gives AI agents like Claude, Cursor, and other MCP-compatible tools direct access to:

- **Company fundamentals** (quotes, financials, earnings, float, executives, peers, news)
- **Dilution risk scoring** (0-100 Dilution Pressure Score with 5-dimension assessment)
- **SEC filing extractions** (warrants, convertibles, shelf registrations, and 10 more types)
- **Instrument lifecycle tracking** (warrants, convertibles, ATMs with XBRL reconciliation)
- **Intelligence** (counterparties, counsel, insiders, institutions, ROFR triggers, cluster buys)
- **Cross-company intelligence** (top AUM institutions, cross-company counsel & insider patterns)
- **Compliance monitoring** (Nasdaq/NYSE deficiency detection, listing classification)
- **Company screening** (dilution-aware filters with 30+ fields)
- **ETF analysis** (holdings, sectors, countries, performance, comparables)

## Installation

```bash
npm install -g @signal8ai/mcp
# or use npx (no install needed)
npx @signal8ai/mcp
```

## Setup

### 1. Get your API key

Sign up at [signal8.ai/mcp](https://signal8.ai/mcp) and create a key at [signal8.ai/settings/api-keys](https://signal8.ai/settings/api-keys) to get your API key.

### 2. Configure your MCP client

#### Claude Desktop

Add to your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "signal8": {
      "command": "npx",
      "args": ["-y", "@signal8ai/mcp"],
      "env": {
        "SIGNAL8_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}
```

#### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "signal8": {
      "command": "npx",
      "args": ["-y", "@signal8ai/mcp"],
      "env": {
        "SIGNAL8_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}
```

#### Other MCP Clients

Set the `SIGNAL8_API_KEY` environment variable and run:

```bash
SIGNAL8_API_KEY=sk_live_your_key_here npx @signal8ai/mcp
```

## Available Tools (86)

The server exposes **86 live tools** at runtime. The reference tables below are
a representative catalog grouped by domain; several documented tools and whole
categories (e.g. Extractions and Dilution) are currently disabled and are not
registered live, so individual section counts below may exceed what is actually
exposed.

### Companies (3 tools)

| Tool | Description | Credits |
|------|-------------|---------|
| `search_companies` | Search companies by name or ticker | 1 |
| `get_company_profile` | Full company profile (description, market cap, sector) | 1 |
| `get_company_bundle` | Consolidated data bundle in one call | 25 |

### Company Data (13 tools)

| Tool | Description | Credits |
|------|-------------|---------|
| `get_quote` | Real-time stock quote (price, change, volume) | 1 |
| `get_market_metrics` | Volume averages, volatility, SMAs, trend direction | 3 |
| `get_short_interest` | Short interest data and days-to-cover | 3 |
| `get_float` | Float composition, shares outstanding, ownership % | 3 |
| `get_financials` | Income statement, balance sheet, cash flow | 5 |
| `get_earnings` | Earnings history with EPS surprises | 3 |
| `get_executives` | Executive team roster and compensation | 1 |
| `get_peers` | Peer/comparable companies | 1 |
| `get_transcripts` | Earnings call transcripts | 3 |
| `get_news` | Latest company news headlines | 1 |
| `get_analyst_consensus` | Analyst ratings and price targets | 3 |
| `get_material_events` | Material corporate events (8-K filings) | 3 |
| `get_clinical_trials` | Clinical trial pipeline (biotech/pharma) | 3 |

### Market — Cross-Ticker (6 tools)

| Tool | Description | Credits |
|------|-------------|---------|
| `get_quotes_batch` | Batch real-time quotes for up to 200 tickers (POST) | max(1, ceil(N/10)) |
| `get_quotes_universe` | Quotes for an entire index universe (sp500/ndx/dji) | 5 |
| `get_index_snapshot` | Bulk ticker snapshots (price, day change, % change) | 1 |
| `get_sector_etf_snapshot` | Snapshot of the 11 SPDR sector ETFs with sector labels | 2 |
| `get_top_movers` | Top gainers / losers / most-active by volume (with optional `session` window) | 2 |
| `get_market_breadth` | Advance/decline, % above SMA50/200, 52-week high/low counts | 2 |

### Calendar (5 tools)

| Tool | Description | Credits |
|------|-------------|---------|
| `get_earnings_calendar` | Upcoming/recent earnings releases between two dates | 3 |
| `get_economic_calendar` | Macro/economic events (CPI, FOMC, jobs, GDP) by date and country | 3 |
| `get_filing_calendar` | 10-K / 10-Q SEC filing-deadline calendar by universe | 5 |
| `get_lockup_expirations` | Upcoming IPO/secondary lockup expirations | 5 |
| `get_recent_material_filings` | Recent material 8-K filings by index universe and item codes | 5 |

### Extractions (4 tools)

| Tool | Description | Credits |
|------|-------------|---------|
| `get_extractions` | AI-extracted SEC filing data (13 types) | 5 |
| `get_filing_extractions` | Extractions for a specific SEC filing | 5 |
| `get_extraction_dashboard` | Cross-company extraction analytics | 50 |
| `get_extraction_by_type` | Filter extractions by type (warrants, convertibles, etc.) | 5 |

### Dilution (5 tools)

| Tool | Description | Credits |
|------|-------------|---------|
| `get_dilution_risk` | Dilution Pressure Score (0-100) with 5-dimension assessment | 5 |
| `get_dilution_performance` | Post-dilution stock performance at +1d/+7d/+30d/+90d | 10 |
| `get_instruments` | Active warrants, convertibles, ATMs, shelf registrations | 5 |
| `get_instrument_detail` | Deep dive on a single instrument | 5 |
| `get_baby_shelf` | IB6 baby shelf remaining capacity | 10 |

### Intelligence — Per-Company (12 tools)

| Tool | Description | Credits |
|------|-------------|---------|
| `get_counterparties` | Entity-resolved counterparty relationships | 10 |
| `get_counsel` | Legal counsel engagements with role taxonomy | 10 |
| `get_insiders` | Insider trading discovery and patterns | 10 |
| `get_ownership` | Unified ownership (Form 4 + 13F + 13D/G) | 10 |
| `get_rofr_triggers` | ROFR exercise trigger detection | 10 |
| `get_institutions` | Institutional holders from 13F filings | 10 |
| `get_institution_detail` | Detailed info for a specific institution (by CIK) | 10 |
| `get_institution_holdings` | Full portfolio holdings for an institution | 10 |
| `get_banks` | Investment bank relationships from SEC filings | 10 |
| `get_legal_counsels` | Legal counsel relationships with partner names | 10 |
| `get_insider_transactions` | Detailed Form 4 transaction history | 5 |
| `get_insider_cluster_buys` | Cluster buying pattern detection (3+ insiders in 14 days) | 10 |

### Intelligence — Cross-Company (3 tools)

| Tool | Description | Credits |
|------|-------------|---------|
| `get_institution_top_aum` | Top institutional holders by AUM across all companies | 25 |
| `get_counsel_cross_company` | Law firm engagements across multiple companies | 25 |
| `get_insider_cross_company` | Insider trading patterns across multiple companies | 25 |

### Compliance (4 tools)

| Tool | Description | Credits |
|------|-------------|---------|
| `get_compliance` | Full compliance evaluation | 25 |
| `get_deficiencies` | Listing deficiency detection | 10 |
| `get_compliance_alerts` | Active compliance alerts | 5 |
| `get_listing_classification` | Exchange listing classification | 10 |

### Screener (2 tools)

| Tool | Description | Credits |
|------|-------------|---------|
| `get_screener_fields` | Discover available screening filters | 1 |
| `screen_companies` | Dilution-aware company screener | 25 |

### Events & ATM (2 tools)

| Tool | Description | Credits |
|------|-------------|---------|
| `get_events` | Unified corporate events | 5 |
| `get_atm_activity` | ATM program monitoring | 5 |

### ETF (1 tool)

| Tool | Description | Credits |
|------|-------------|---------|
| `get_etf_bundle` | Aggregated ETF data (profile, holdings, sectors, performance) | 25 |

## Market Intelligence — Tool Reference

Cross-ticker market and calendar tools that operate over the entire universe rather than a single company. The single-ticker `get_quote` tool is included here for completeness; the rest were added in the Market Intelligence rollout.

---

### `get_quote`

Real-time quote for a single ticker (price, change, volume, day range).

**Inputs:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| ticker | string | yes | Ticker symbol (e.g. `AAPL`) |

**Sample output (regular trading hours, 9:30am–4:00pm ET):**

```json
{
  "data": {
    "ticker": "AAPL",
    "currentPrice": 178.42,
    "change": 2.15,
    "changePercent": 1.22,
    "high": 179.10,
    "low": 176.80,
    "open": 177.05,
    "previousClose": 176.27,
    "preMarketPrice": null,
    "preMarketChangePercent": null,
    "afterHoursPrice": null,
    "afterHoursChangePercent": null,
    "timestamp": 1714492800
  }
}
```

**Sample output (extended hours — pre-market or after-hours):**

```json
{
  "data": {
    "ticker": "AAPL",
    "currentPrice": 178.42,
    "change": 2.15,
    "changePercent": 1.22,
    "high": 179.10,
    "low": 176.80,
    "open": 177.05,
    "previousClose": 176.27,
    "preMarketPrice": 179.05,
    "preMarketChangePercent": 0.35,
    "afterHoursPrice": 178.90,
    "afterHoursChangePercent": 0.27,
    "timestamp": 1714492800
  }
}
```

> **Extended-hours windows (US equities, ET):** pre-market 4:00am–9:30am, after-hours 4:00pm–8:00pm. Outside those windows `preMarketPrice`, `preMarketChangePercent`, `afterHoursPrice`, and `afterHoursChangePercent` are `null`. In practice only one pair is populated at a time depending on the current window — the second example shows both populated for illustration.

**Use case:** "What is AAPL trading at right now