mcp-edgar 0.1.0__tar.gz

mcp_edgar-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q

mcp_edgar-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

mcp_edgar-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+
+# Tooling / caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.cache/
+edgar_cache/
+uv.lock
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

mcp_edgar-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-21
+
+### Added
+- Initial release. 10 MCP tools over SEC EDGAR, FRED, Tradernet and OpenFIGI:
+  - `get_company_facts` — normalized fundamentals (revenue, EPS, margins, debt).
+  - `get_financial_statement` — income/balance/cashflow as structured JSON.
+  - `get_filings` — recent SEC filings with metadata and document URLs.
+  - `parse_filing_section` — extract a 10-K section (risk factors, MD&A) as clean text.
+  - `get_insider_trades` — structured Form 3/4/5 insider transactions.
+  - `get_macro_series` — FRED macro time series.
+  - `get_quote` — real-time L1 quote via the Tradernet WebSocket feed.
+  - `get_etf_holdings` — ETF/fund portfolio (NPORT-P) with AUM, NAV and asset/country mix.
+  - `get_holdings_analysis` — look-through sector breakdown and weighted net-margin/ROE.
+  - `get_index` — index snapshot (level via FRED, tracking ETF, holdings preview).
+- Holding resolution by CUSIP/ISIN (OpenFIGI) with name-match fallback.
+- Centralized HTTPS host-allowlist (SSRF defense), `defusedxml` XML parsing, secret redaction.
+
+[0.1.0]: https://github.com/birthday-tools/edgarmcp/releases/tag/v0.1.0

mcp_edgar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 birthday.tools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_edgar-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: mcp-edgar
+Version: 0.1.0
+Summary: MCP server for clean, normalized SEC EDGAR, FRED, ETF and index data
+Project-URL: Homepage, https://github.com/birthday-tools/edgarmcp
+Project-URL: Repository, https://github.com/birthday-tools/edgarmcp
+Project-URL: Issues, https://github.com/birthday-tools/edgarmcp/issues
+Project-URL: Changelog, https://github.com/birthday-tools/edgarmcp/blob/main/CHANGELOG.md
+Author-email: "birthday.tools" <info+sec@birthday.tools>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,edgar,etf,finance,fred,llm,mcp,model-context-protocol,sec
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.11
+Requires-Dist: defusedxml>=0.7
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: selectolax>=0.3.21
+Requires-Dist: websocket-client>=1.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# EdgarMCP
+
+[![PyPI](https://img.shields.io/pypi/v/mcp-edgar.svg)](https://pypi.org/project/mcp-edgar/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/birthday-tools/edgarmcp/actions/workflows/ci.yml/badge.svg)](https://github.com/birthday-tools/edgarmcp/actions/workflows/ci.yml)
+
+An MCP server that gives AI agents clean, normalized access to financial data:
+company fundamentals and insider trades from [SEC EDGAR](https://www.sec.gov/edgar),
+macro series from [FRED](https://fred.stlouisfed.org/), real-time quotes via the
+Tradernet WebSocket feed, ETF/fund holdings from SEC NPORT-P, look-through analytics,
+and index snapshots.
+
+Raw sources (XBRL, bulky filing HTML, ownership XML) are expensive and error-prone for
+agents — they burn tokens and trip up on parsing. EdgarMCP returns agent-ready JSON.
+
+## Installation
+
+```bash
+pip install mcp-edgar
+```
+
+This installs the `edgarmcp` console script (a stdio MCP server).
+
+## Quick start
+
+Add it to an MCP client. For Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "edgarmcp": {
+      "command": "edgarmcp",
+      "env": {
+        "FRED_API_KEY": "your-free-fred-key",
+        "OPENFIGI_API_KEY": "optional-openfigi-key"
+      }
+    }
+  }
+}
+```
+
+Both keys are optional: without `FRED_API_KEY` the FRED-backed tools degrade gracefully;
+without `OPENFIGI_API_KEY` holding resolution runs in anonymous mode.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `get_company_facts(ticker)` | Normalized fundamentals (revenue, EPS, margins, debt) |
+| `get_financial_statement(ticker, statement, period)` | Income/balance/cashflow as structured JSON |
+| `get_filings(ticker, form_type, limit)` | Recent SEC filings (10-K/10-Q/8-K) with metadata and document URLs |
+| `parse_filing_section(url, section)` | Extract a 10-K section (Risk Factors, MD&A) as clean text |
+| `get_insider_trades(ticker, limit)` | Form 3/4/5 insider transactions (who, role, buy/sell, volume) |
+| `get_macro_series(series_id, start, end)` | FRED macro series (rates, inflation, unemployment) with metadata |
+| `get_quote(ticker)` | Real-time L1 quote (last/bid/ask/volume) via the Tradernet WebSocket feed |
+| `get_etf_holdings(ticker, limit)` | ETF/fund holdings (top by weight) + AUM, NAV, asset/country mix from SEC NPORT-P |
+| `get_holdings_analysis(symbol, limit)` | Look-through of an ETF/index: sector breakdown + weighted net-margin/ROE with coverage |
+| `get_index(index)` | Index snapshot (S&P 500, NASDAQ-100, Dow, NASDAQ Composite): level from FRED, tracking ETF, holdings preview |
+
+## Configuration
+
+| Variable | Description | Default |
+|---|---|---|
+| `EDGAR_USER_AGENT` | User-Agent for SEC requests | `EdgarMCP/0.1 (contact: info+sec@birthday.tools)` |
+| `EDGAR_RATE_LIMIT` | Requests per second | `10` |
+| `EDGAR_CACHE_DIR` | File cache directory | `edgar_cache` |
+| `FRED_API_KEY` | Free FRED key for `get_macro_series` / index levels | — |
+| `OPENFIGI_API_KEY` | Optional OpenFIGI key for higher CUSIP/ISIN rate limit | — |
+
+Variables are read from the environment; locally you can put them in a `.env` file.
+
+## Architecture
+
+Three isolated layers: a platform-independent **data layer** (HTTP client with a host
+allowlist, ticker/name/CUSIP/ISIN resolution, XBRL normalizers, filing/ownership/NPORT-P
+parsers, FRED, the Tradernet WebSocket client, OpenFIGI identifier mapping, look-through
+and index analytics); a **cache layer** (aggressive caching of immutable filings and FIGI
+mappings; mutable FRED series are not cached); and a thin **MCP layer**. The data layer
+knows nothing about MCP and ports unchanged between a marketplace and self-hosting.
+
+## Security
+
+- Outbound requests are restricted to an HTTPS host allowlist (SSRF defense), centralized
+  across all sources (SEC, FRED, OpenFIGI).
+- Ownership and NPORT XML is parsed with `defusedxml` (XXE / billion-laughs defense).
+- Secrets (FRED / OpenFIGI keys) are redacted from error messages and never placed in URLs
+  or cache keys.
+- Real-time quotes come from Tradernet's public anonymous WebSocket feed
+  (`wss://wss.tradernet.com/`); a dedicated client with a hardcoded URL.
+- CUSIP/ISIN holding resolution goes through OpenFIGI (`api.openfigi.com`, allowlisted);
+  on failure it falls back to name matching.
+
+## Data licenses
+
+SEC EDGAR data is public domain, used with a descriptive `User-Agent` and the 10 req/s
+limit. FRED data is provided by the Federal Reserve Bank of St. Louis under its
+[terms of use](https://fred.stlouisfed.org/legal/). Real-time quotes come from Tradernet's
+public anonymous WebSocket feed. CUSIP/ISIN → ticker mapping uses
+[OpenFIGI](https://www.openfigi.com/) (Bloomberg; free tier, 25 req/min anonymous,
+250 req/min with a key).
+
+## License
+
+[MIT](LICENSE) © 2026 birthday.tools

mcp_edgar-0.1.0/README.md

@@ -0,0 +1,104 @@
+# EdgarMCP
+
+[![PyPI](https://img.shields.io/pypi/v/mcp-edgar.svg)](https://pypi.org/project/mcp-edgar/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/birthday-tools/edgarmcp/actions/workflows/ci.yml/badge.svg)](https://github.com/birthday-tools/edgarmcp/actions/workflows/ci.yml)
+
+An MCP server that gives AI agents clean, normalized access to financial data:
+company fundamentals and insider trades from [SEC EDGAR](https://www.sec.gov/edgar),
+macro series from [FRED](https://fred.stlouisfed.org/), real-time quotes via the
+Tradernet WebSocket feed, ETF/fund holdings from SEC NPORT-P, look-through analytics,
+and index snapshots.
+
+Raw sources (XBRL, bulky filing HTML, ownership XML) are expensive and error-prone for
+agents — they burn tokens and trip up on parsing. EdgarMCP returns agent-ready JSON.
+
+## Installation
+
+```bash
+pip install mcp-edgar
+```
+
+This installs the `edgarmcp` console script (a stdio MCP server).
+
+## Quick start
+
+Add it to an MCP client. For Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "edgarmcp": {
+      "command": "edgarmcp",
+      "env": {
+        "FRED_API_KEY": "your-free-fred-key",
+        "OPENFIGI_API_KEY": "optional-openfigi-key"
+      }
+    }
+  }
+}
+```
+
+Both keys are optional: without `FRED_API_KEY` the FRED-backed tools degrade gracefully;
+without `OPENFIGI_API_KEY` holding resolution runs in anonymous mode.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `get_company_facts(ticker)` | Normalized fundamentals (revenue, EPS, margins, debt) |
+| `get_financial_statement(ticker, statement, period)` | Income/balance/cashflow as structured JSON |
+| `get_filings(ticker, form_type, limit)` | Recent SEC filings (10-K/10-Q/8-K) with metadata and document URLs |
+| `parse_filing_section(url, section)` | Extract a 10-K section (Risk Factors, MD&A) as clean text |
+| `get_insider_trades(ticker, limit)` | Form 3/4/5 insider transactions (who, role, buy/sell, volume) |
+| `get_macro_series(series_id, start, end)` | FRED macro series (rates, inflation, unemployment) with metadata |
+| `get_quote(ticker)` | Real-time L1 quote (last/bid/ask/volume) via the Tradernet WebSocket feed |
+| `get_etf_holdings(ticker, limit)` | ETF/fund holdings (top by weight) + AUM, NAV, asset/country mix from SEC NPORT-P |
+| `get_holdings_analysis(symbol, limit)` | Look-through of an ETF/index: sector breakdown + weighted net-margin/ROE with coverage |
+| `get_index(index)` | Index snapshot (S&P 500, NASDAQ-100, Dow, NASDAQ Composite): level from FRED, tracking ETF, holdings preview |
+
+## Configuration
+
+| Variable | Description | Default |
+|---|---|---|
+| `EDGAR_USER_AGENT` | User-Agent for SEC requests | `EdgarMCP/0.1 (contact: info+sec@birthday.tools)` |
+| `EDGAR_RATE_LIMIT` | Requests per second | `10` |
+| `EDGAR_CACHE_DIR` | File cache directory | `edgar_cache` |
+| `FRED_API_KEY` | Free FRED key for `get_macro_series` / index levels | — |
+| `OPENFIGI_API_KEY` | Optional OpenFIGI key for higher CUSIP/ISIN rate limit | — |
+
+Variables are read from the environment; locally you can put them in a `.env` file.
+
+## Architecture
+
+Three isolated layers: a platform-independent **data layer** (HTTP client with a host
+allowlist, ticker/name/CUSIP/ISIN resolution, XBRL normalizers, filing/ownership/NPORT-P
+parsers, FRED, the Tradernet WebSocket client, OpenFIGI identifier mapping, look-through
+and index analytics); a **cache layer** (aggressive caching of immutable filings and FIGI
+mappings; mutable FRED series are not cached); and a thin **MCP layer**. The data layer
+knows nothing about MCP and ports unchanged between a marketplace and self-hosting.
+
+## Security
+
+- Outbound requests are restricted to an HTTPS host allowlist (SSRF defense), centralized
+  across all sources (SEC, FRED, OpenFIGI).
+- Ownership and NPORT XML is parsed with `defusedxml` (XXE / billion-laughs defense).
+- Secrets (FRED / OpenFIGI keys) are redacted from error messages and never placed in URLs
+  or cache keys.
+- Real-time quotes come from Tradernet's public anonymous WebSocket feed
+  (`wss://wss.tradernet.com/`); a dedicated client with a hardcoded URL.
+- CUSIP/ISIN holding resolution goes through OpenFIGI (`api.openfigi.com`, allowlisted);
+  on failure it falls back to name matching.
+
+## Data licenses
+
+SEC EDGAR data is public domain, used with a descriptive `User-Agent` and the 10 req/s
+limit. FRED data is provided by the Federal Reserve Bank of St. Louis under its
+[terms of use](https://fred.stlouisfed.org/legal/). Real-time quotes come from Tradernet's
+public anonymous WebSocket feed. CUSIP/ISIN → ticker mapping uses
+[OpenFIGI](https://www.openfigi.com/) (Bloomberg; free tier, 25 req/min anonymous,
+250 req/min with a key).
+
+## License
+
+[MIT](LICENSE) © 2026 birthday.tools

mcp_edgar-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "mcp-edgar"
+version = "0.1.0"
+description = "MCP server for clean, normalized SEC EDGAR, FRED, ETF and index data"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "birthday.tools", email = "info+sec@birthday.tools" }]
+keywords = ["mcp", "model-context-protocol", "sec", "edgar", "fred", "etf", "finance", "llm", "agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+    "mcp>=1.2.0",
+    "httpx>=0.27",
+    "selectolax>=0.3.21",
+    "defusedxml>=0.7",
+    "python-dotenv>=1.0",
+    "websocket-client>=1.6",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.5"]
+
+[project.scripts]
+edgarmcp = "edgarmcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/birthday-tools/edgarmcp"
+Repository = "https://github.com/birthday-tools/edgarmcp"
+Issues = "https://github.com/birthday-tools/edgarmcp/issues"
+Changelog = "https://github.com/birthday-tools/edgarmcp/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/edgarmcp"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

mcp_edgar-0.1.0/scripts/live_validate.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""Manual, network-gated end-to-end validation against live SEC EDGAR + FRED.
+
+NOT a unit test — it makes real HTTP calls. Run manually before shipping:
+
+    .venv/bin/python scripts/live_validate.py [TICKER] [FRED_SERIES]
+
+Defaults: TICKER=AAPL, FRED_SERIES=FEDFUNDS.
+Requires EDGAR_USER_AGENT (has a sane default) and, for the FRED tool,
+FRED_API_KEY in the environment or in edgar-mcp/.env.
+"""
+import sys
+
+from dotenv import load_dotenv
+
+from edgarmcp.cache import FileCache
+from edgarmcp.config import Settings
+from edgarmcp.deps import build_context
+from edgarmcp.http_client import EdgarClient
+from edgarmcp.server import build_tools
+
+
+def section(title: str) -> None:
+    print(f"\n{'=' * 70}\n{title}\n{'=' * 70}")
+
+
+def show(label: str, ok: bool, detail: str) -> None:
+    mark = "OK " if ok else "ERR"
+    print(f"[{mark}] {label}: {detail}")
+
+
+def main() -> int:
+    ticker = sys.argv[1] if len(sys.argv) > 1 else "AAPL"
+    series = sys.argv[2] if len(sys.argv) > 2 else "FEDFUNDS"
+
+    load_dotenv()
+    settings = Settings.from_env()
+    client = EdgarClient(
+        settings.user_agent,
+        FileCache(settings.cache_dir),
+        min_interval=1.0 / settings.rate_limit_per_sec if settings.rate_limit_per_sec else 0.0,
+        allowed_hosts=settings.allowed_hosts,
+    )
+    ctx = build_context(settings, client)
+    tools = build_tools(ctx)
+
+    failures = 0
+
+    section(f"SEC EDGAR tools — ticker {ticker}")
+
+    # get_company_facts
+    try:
+        f = tools["get_company_facts"](ticker)
+        metrics = f.get("metrics", {})
+        rev = metrics.get("revenue", {})
+        show("get_company_facts", bool(f.get("entity_name") and metrics),
+             f"{f.get('entity_name')} | {len(metrics)} metrics | revenue={rev.get('value')} ({rev.get('period')})")
+        if not metrics:
+            failures += 1
+    except Exception as e:
+        failures += 1
+        show("get_company_facts", False, f"{type(e).__name__}: {e}")
+
+    # get_financial_statement
+    try:
+        st = tools["get_financial_statement"](ticker, "income", "annual")
+        li = st.get("line_items", {})
+        show("get_financial_statement", bool(li),
+             f"income/annual | {len(li)} line items | revenue={li.get('revenue', {}).get('value')}")
+        if not li:
+            failures += 1
+    except Exception as e:
+        failures += 1
+        show("get_financial_statement", False, f"{type(e).__name__}: {e}")
+
+    # get_filings (10-K)
+    filing_url = None
+    try:
+        fl = tools["get_filings"](ticker, "10-K", 2)
+        if fl:
+            filing_url = fl[0]["url"]
+        show("get_filings", bool(fl),
+             f"{len(fl)} 10-K filings | latest={fl[0]['filing_date'] if fl else None} | url={filing_url}")
+        if not fl:
+            failures += 1
+    except Exception as e:
+        failures += 1
+        show("get_filings", False, f"{type(e).__name__}: {e}")
+
+    # parse_filing_section (uses the 10-K url from above)
+    if filing_url:
+        for sec_name in ("risk_factors", "mda"):
+            try:
+                text = tools["parse_filing_section"](filing_url, sec_name)
+                ok = len(text) > 200
+                preview = text[:160].replace("\n", " ")
+                show(f"parse_filing_section[{sec_name}]", ok, f"{len(text)} chars | {preview!r}")
+                if not ok:
+                    failures += 1
+            except Exception as e:
+                failures += 1
+                show(f"parse_filing_section[{sec_name}]", False, f"{type(e).__name__}: {e}")
+    else:
+        show("parse_filing_section", False, "skipped — no 10-K url")
+        failures += 1
+
+    # get_insider_trades
+    try:
+        it = tools["get_insider_trades"](ticker, 3)
+        if it:
+            e0 = it[0]
+            rep = (e0.get("reporters") or [{}])[0]
+            nd = e0.get("non_derivative") or []
+            summ = e0.get("summary", {})
+            detail = (f"{len(it)} filings | form={e0['form']} | reporter={rep.get('name')} "
+                      f"({rep.get('relationship')}) | {len(nd)} non-deriv | "
+                      f"summary={summ.get('action')} {summ.get('total_shares')}")
+        else:
+            detail = "0 insider filings returned"
+        show("get_insider_trades", bool(it), detail)
+        if not it:
+            failures += 1
+    except Exception as e:
+        failures += 1
+        show("get_insider_trades", False, f"{type(e).__name__}: {e}")
+
+    section(f"FRED tool — series {series}")
+    try:
+        ms = tools["get_macro_series"](series)
+        obs = ms.get("observations", [])
+        last = obs[-1] if obs else {}
+        show("get_macro_series", bool(obs),
+             f"{ms.get('title')} | {ms.get('units')} | {ms.get('frequency')} | "
+             f"{ms.get('count')} obs | last={last.get('date')}={last.get('value')}")
+        if not obs:
+            failures += 1
+    except Exception as e:
+        failures += 1
+        show("get_macro_series", False, f"{type(e).__name__}: {e}")
+
+    section(f"Tradernet tool — real-time quote {ticker}")
+    try:
+        q = tools["get_quote"](ticker)
+        ok = q.get("price") is not None
+        show("get_quote", ok,
+             f"{q.get('ticker')} | last={q.get('price')} | bid={q.get('bid')} ask={q.get('ask')} | "
+             f"vol={q.get('volume_day')} | t={q.get('last_trade_time')}")
+        if not ok:
+            failures += 1
+    except Exception as e:
+        failures += 1
+        show("get_quote", False, f"{type(e).__name__}: {e}")
+
+    section("ETF tool — holdings SPY")
+    try:
+        h = tools["get_etf_holdings"]("SPY", 3)
+        top = h.get("holdings", [])
+        ok = bool(top) and h.get("total_net_assets") is not None
+        names = ", ".join(x["name"] for x in top)
+        show("get_etf_holdings", ok,
+             f"{h.get('fund_name')} | {h.get('total_holdings')} holdings | "
+             f"netAssets={h.get('total_net_assets')} | top: {names}")
+        if not ok:
+            failures += 1
+    except Exception as e:
+        failures += 1
+        show("get_etf_holdings", False, f"{type(e).__name__}: {e}")
+
+    section("Look-through — get_holdings_analysis SP500")
+    try:
+        a = tools["get_holdings_analysis"]("SP500", 25)
+        cov = a.get("coverage", {})
+        secs = ", ".join(f"{b['sector']} {b['weight_pct']}%" for b in a.get("sector_breakdown", [])[:3])
+        ok = cov.get("matched", 0) > 0
+        res = cov.get("resolution", {})
+        show("get_holdings_analysis", ok,
+             f"{a.get('resolved_etf')} | matched {cov.get('matched')}/{cov.get('of')} "
+             f"({cov.get('matched_weight_pct')}%) via cusip={res.get('by_cusip')}/isin={res.get('by_isin')}/name={res.get('by_name')} | "
+             f"margin={a.get('weighted_net_margin')} roe={a.get('weighted_roe')} | top sectors: {secs}")
+        if not ok:
+            failures += 1
+    except Exception as e:
+        failures += 1
+        show("get_holdings_analysis", False, f"{type(e).__name__}: {e}")
+
+    section("Index — get_index S&P 500")
+    try:
+        ix = tools["get_index"]("S&P 500")
+        lvl = ix.get("level") or {}
+        top = ", ".join(f"{x['name']}({x['ticker']})" for x in ix.get("top_holdings", [])[:3])
+        ok = bool(ix.get("tracking_etf"))
+        show("get_index", ok,
+             f"{ix.get('index')} | level={lvl.get('value')} @ {lvl.get('date')} | etf={ix.get('tracking_etf')} | top: {top}")
+        if not ok:
+            failures += 1
+    except Exception as e:
+        failures += 1
+        show("get_index", False, f"{type(e).__name__}: {e}")
+
+    section("RESULT")
+    print(f"{'ALL TOOLS OK' if failures == 0 else f'{failures} CHECK(S) FAILED'}")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mcp_edgar-0.1.0/server.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
+  "name": "io.github.birthday-tools/edgarmcp",
+  "description": "Clean, normalized SEC EDGAR / FRED / ETF / index data for AI agents.",
+  "version": "0.1.0",
+  "status": "active",
+  "repository": {
+    "url": "https://github.com/birthday-tools/edgarmcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registry_type": "pypi",
+      "identifier": "mcp-edgar",
+      "version": "0.1.0",
+      "transport": { "type": "stdio" },
+      "environment_variables": [
+        { "name": "EDGAR_USER_AGENT", "description": "Override the SEC User-Agent contact string", "is_required": false },
+        { "name": "FRED_API_KEY", "description": "Free FRED API key for get_macro_series and index levels", "is_required": false, "is_secret": true },
+        { "name": "OPENFIGI_API_KEY", "description": "Optional OpenFIGI key for a higher CUSIP/ISIN rate limit", "is_required": false, "is_secret": true }
+      ]
+    }
+  ]
+}

mcp_edgar-0.1.0/src/edgarmcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"