sec-engine 0.1.0__tar.gz

sec_engine-0.1.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls -la /Users/taika/Documents/Github/Python/sec-engine/.git*)"
+    ]
+  }
+}

sec_engine-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env

sec_engine-0.1.0/CLAUDE.md

@@ -0,0 +1,32 @@
+# CLAUDE.md
+
+## Project
+
+sec-engine is an MCP server that exposes SEC EDGAR financial data to LLMs. It runs over stdio and provides 6 tools for company lookup, filing navigation, XBRL metrics, and narrative text extraction.
+
+## Structure
+
+```
+sec_engine/
+  server.py   — FastMCP server, defines all 6 tools
+  edgar.py    — SEC EDGAR API client (async httpx, rate-limited)
+  __main__.py — CLI entry point
+  __init__.py
+```
+
+## Build & Run
+
+```bash
+uv pip install -e .    # install in dev mode
+sec-engine             # run the MCP server (stdio)
+```
+
+Build system is hatchling. Dependencies: mcp, httpx, beautifulsoup4, lxml.
+
+## Key Details
+
+- Python >= 3.11 required
+- SEC API has a 10 req/sec rate limit; EdgarClient handles this
+- SEC requires a descriptive User-Agent header (configurable via `SEC_EDGAR_USER_AGENT` env var)
+- No tests yet
+- No auth needed — all SEC APIs are public

sec_engine-0.1.0/Dockerfile

@@ -0,0 +1,8 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY pyproject.toml .
+COPY sec_engine/ sec_engine/
+RUN pip install --no-cache-dir .
+
+ENTRYPOINT ["sec-engine"]

sec_engine-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 taika-st
+
+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.

sec_engine-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: sec-engine
+Version: 0.1.0
+Summary: LLM-optimized SEC EDGAR MCP server
+Author-email: taika-st <taika-st@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: lxml>=5.0.0
+Requires-Dist: mcp>=1.0.0

sec_engine-0.1.0/README.md

@@ -0,0 +1,83 @@
+# sec-engine
+
+LLM-optimized SEC EDGAR MCP server. Provides six tools that wrap the SEC's public JSON APIs for financial data extraction and analysis — no authentication required.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `resolve` | Ticker/CIK to company identity (name, SIC, exchanges, fiscal year end) |
+| `filings` | List SEC filings with form type and date filtering |
+| `snapshot` | Latest key metrics (~20) + full XBRL concept index |
+| `concept_history` | Time series for one XBRL metric across all filings |
+| `cross_company` | Compare one metric across ALL filers for peer/sector screening |
+| `filing_section` | Extract narrative text from 10-K/10-Q sections (MD&A, Risk Factors, etc.) |
+
+## Installation
+
+```bash
+pip install sec-engine
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install sec-engine
+```
+
+## Usage
+
+### Claude Desktop
+
+Add to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "sec-engine": {
+      "command": "sec-engine"
+    }
+  }
+}
+```
+
+### Docker Compose
+
+Edit `SEC_EDGAR_USER_AGENT` in `compose.yml` with your name and email, then:
+
+```bash
+docker compose up --build
+```
+
+### Docker
+
+```bash
+docker build -t sec-engine .
+docker run -i sec-engine
+```
+
+### Direct
+
+```bash
+sec-engine
+```
+
+The server communicates over stdio using the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `SEC_EDGAR_USER_AGENT` | `SEC-Engine/0.1 (sec-engine-mcp)` | User-Agent string sent to SEC.gov (SEC requires a descriptive UA) |
+
+## Requirements
+
+- Python >= 3.11
+
+## Disclaimer
+
+This software retrieves publicly available data from the SEC EDGAR system. It is provided as-is for informational purposes only and does not constitute financial, legal, or investment advice. The authors are not responsible for how you use this data or any consequences arising from its use. You are solely responsible for complying with all applicable SEC policies, regulations, and terms of service.
+
+## License
+
+MIT

sec_engine-0.1.0/compose.yml

@@ -0,0 +1,6 @@
+services:
+  sec-engine:
+    build: .
+    stdin_open: true
+    environment:
+      - SEC_EDGAR_USER_AGENT=YourName your-email@example.com

sec_engine-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "sec-engine"
+version = "0.1.0"
+description = "LLM-optimized SEC EDGAR MCP server"
+license = "MIT"
+authors = [
+    { name = "taika-st", email = "taika-st@users.noreply.github.com" },
+]
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+    "beautifulsoup4>=4.12.0",
+    "lxml>=5.0.0",
+]
+
+[project.scripts]
+sec-engine = "sec_engine.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

sec_engine-0.1.0/sec_engine/__init__.py

@@ -0,0 +1 @@
+"""SEC Engine - LLM-optimized SEC EDGAR MCP server."""

sec_engine-0.1.0/sec_engine/__main__.py

@@ -0,0 +1,4 @@
+from sec_engine.server import main
+
+if __name__ == "__main__":
+    main()

sec_engine-0.1.0/sec_engine/edgar.py

@@ -0,0 +1,265 @@
+"""SEC EDGAR public API client.
+
+Thin wrapper around data.sec.gov JSON APIs. No auth required — just a User-Agent string.
+Rate limited to 10 req/sec per SEC policy.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from typing import Any
+
+import httpx
+
+SEC_DATA = "https://data.sec.gov"
+SEC_WWW = "https://www.sec.gov"
+TICKERS_URL = f"{SEC_WWW}/files/company_tickers.json"
+
+# Key us-gaap concepts for the snapshot tool
+KEY_CONCEPTS = [
+    "Revenues",
+    "RevenueFromContractWithCustomerExcludingAssessedTax",
+    "NetIncomeLoss",
+    "OperatingIncomeLoss",
+    "GrossProfit",
+    "CostOfGoodsAndServicesSold",
+    "Assets",
+    "AssetsCurrent",
+    "Liabilities",
+    "LiabilitiesCurrent",
+    "StockholdersEquity",
+    "CashAndCashEquivalentsAtCarryingValue",
+    "EarningsPerShareBasic",
+    "EarningsPerShareDiluted",
+    "CommonStockSharesOutstanding",
+    "LongTermDebt",
+    "LongTermDebtNoncurrent",
+    "NetCashProvidedByOperatingActivities",
+    "PaymentsOfDividends",
+    "ResearchAndDevelopmentExpense",
+]
+
+# Section aliases for filing_section tool
+SECTION_ALIASES: dict[str, str] = {
+    "business": "1",
+    "risk factors": "1A",
+    "risk": "1A",
+    "cybersecurity": "1C",
+    "properties": "2",
+    "legal": "3",
+    "legal proceedings": "3",
+    "mda": "7",
+    "md&a": "7",
+    "management discussion": "7",
+    "management's discussion": "7",
+    "market risk": "7A",
+    "quantitative": "7A",
+    "financial statements": "8",
+    "controls": "9A",
+    "controls and procedures": "9A",
+}
+
+# Regex for Item headers in SEC filings
+ITEM_HEADER = re.compile(
+    r"^[\s]*(?:ITEM|Item)\s+(\d+[A-Ca-c]?)[\.\s:]+[-\u2014\u2013]?\s*(.+?)$",
+    re.MULTILINE,
+)
+
+
+class EdgarClient:
+    """Async client for SEC EDGAR public APIs."""
+
+    def __init__(self, user_agent: str):
+        self.user_agent = user_agent
+        self._headers = {
+            "User-Agent": user_agent,
+            "Accept-Encoding": "gzip, deflate",
+        }
+        self._semaphore = asyncio.Semaphore(10)
+        self._ticker_map: dict[str, int] | None = None
+        self._http: httpx.AsyncClient | None = None
+
+    def _client(self) -> httpx.AsyncClient:
+        if self._http is None or self._http.is_closed:
+            self._http = httpx.AsyncClient(
+                headers=self._headers,
+                timeout=30.0,
+                follow_redirects=True,
+            )
+        return self._http
+
+    async def _get(self, url: str) -> httpx.Response:
+        async with self._semaphore:
+            r = await self._client().get(url)
+            r.raise_for_status()
+            return r
+
+    async def _json(self, url: str) -> dict:
+        return (await self._get(url)).json()
+
+    async def _text(self, url: str) -> str:
+        return (await self._get(url)).text
+
+    # ── Identity ──────────────────────────────────────────────────────
+
+    async def _load_tickers(self) -> dict[str, int]:
+        if self._ticker_map is None:
+            raw = await self._json(TICKERS_URL)
+            self._ticker_map = {
+                v["ticker"].upper(): int(v["cik_str"]) for v in raw.values()
+            }
+        return self._ticker_map
+
+    async def resolve_cik(self, identifier: str) -> int:
+        """Ticker or CIK string -> integer CIK."""
+        clean = identifier.strip().upper()
+        try:
+            return int(clean)
+        except ValueError:
+            tmap = await self._load_tickers()
+            if clean in tmap:
+                return tmap[clean]
+            raise ValueError(f"Unknown ticker: {identifier}")
+
+    @staticmethod
+    def pad_cik(cik: int) -> str:
+        return str(cik).zfill(10)
+
+    # ── SEC Data APIs ─────────────────────────────────────────────────
+
+    async def submissions(self, cik: int) -> dict:
+        """Filing history and company metadata."""
+        return await self._json(
+            f"{SEC_DATA}/submissions/CIK{self.pad_cik(cik)}.json"
+        )
+
+    async def company_facts(self, cik: int) -> dict:
+        """All XBRL financial facts for a company."""
+        return await self._json(
+            f"{SEC_DATA}/api/xbrl/companyfacts/CIK{self.pad_cik(cik)}.json"
+        )
+
+    async def company_concept(
+        self, cik: int, concept: str, taxonomy: str = "us-gaap"
+    ) -> dict:
+        """Time series for one XBRL concept."""
+        return await self._json(
+            f"{SEC_DATA}/api/xbrl/companyconcept/"
+            f"CIK{self.pad_cik(cik)}/{taxonomy}/{concept}.json"
+        )
+
+    async def frames(
+        self,
+        concept: str,
+        period: str,
+        currency: str = "USD",
+        taxonomy: str = "us-gaap",
+    ) -> dict:
+        """One concept across all companies for a period."""
+        return await self._json(
+            f"{SEC_DATA}/api/xbrl/frames/{taxonomy}/{concept}/{currency}/{period}.json"
+        )
+
+    async def filing_document(
+        self, cik: int, accession: str, filename: str
+    ) -> str:
+        """Fetch a specific document from a filing archive."""
+        acc_clean = accession.replace("-", "")
+        url = f"{SEC_WWW}/Archives/edgar/data/{cik}/{acc_clean}/{filename}"
+        return await self._text(url)
+
+    # ── Helpers ────────────────────────────────────────────────────────
+
+    async def find_primary_doc(self, cik: int, accession: str) -> str | None:
+        """Look up the primary document filename from submissions."""
+        subs = await self.submissions(cik)
+        recent = subs.get("filings", {}).get("recent", {})
+        accs = recent.get("accessionNumber", [])
+        docs = recent.get("primaryDocument", [])
+        for i, acc in enumerate(accs):
+            if acc == accession and i < len(docs):
+                return docs[i]
+        return None
+
+    def extract_snapshot(self, facts: dict) -> dict[str, Any]:
+        """Extract key financial metrics from companyfacts."""
+        us_gaap = facts.get("facts", {}).get("us-gaap", {})
+        metrics: dict[str, Any] = {}
+        for concept in KEY_CONCEPTS:
+            if concept not in us_gaap:
+                continue
+            units = us_gaap[concept].get("units", {})
+            for unit_name, datapoints in units.items():
+                if not datapoints:
+                    continue
+                latest = max(datapoints, key=lambda d: d.get("end", ""))
+                metrics[concept] = {
+                    "value": latest["val"],
+                    "end": latest.get("end"),
+                    "fiscal_year": latest.get("fy"),
+                    "period": latest.get("fp"),
+                    "form": latest.get("form"),
+                    "filed": latest.get("filed"),
+                    "unit": unit_name,
+                    "label": us_gaap[concept].get("label", concept),
+                }
+                break  # first unit type only
+        return metrics
+
+    def extract_concept_index(self, facts: dict) -> dict[str, Any]:
+        """Build a compact index of all available concepts."""
+        result: dict[str, Any] = {}
+        for taxonomy, concepts in facts.get("facts", {}).items():
+            names = sorted(concepts.keys())
+            result[taxonomy] = {
+                "count": len(names),
+                "concepts": names,
+            }
+        return result
+
+    def parse_filing_sections(self, html: str) -> dict[str, dict[str, str]]:
+        """Parse 10-K/10-Q HTML into sections by Item number."""
+        import warnings
+        from bs4 import BeautifulSoup, XMLParsedAsHTMLWarning
+
+        warnings.filterwarnings("ignore", category=XMLParsedAsHTMLWarning)
+        soup = BeautifulSoup(html, "lxml")
+        for tag in soup(["script", "style"]):
+            tag.decompose()
+
+        text = soup.get_text(separator="\n")
+        text = text.replace("\xa0", " ")
+        text = re.sub(r"\n{3,}", "\n\n", text)
+
+        matches = list(ITEM_HEADER.finditer(text))
+        if not matches:
+            return {}
+
+        sections: dict[str, dict[str, str]] = {}
+        for i, m in enumerate(matches):
+            item_num = m.group(1).upper()
+            title = m.group(2).strip()
+            start = m.end()
+            end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+            content = text[start:end].strip()
+
+            # Skip ToC entries — real sections have substantial content
+            if len(content) < 500:
+                continue
+
+            # Keep longest version (handles ToC reference + actual content)
+            if item_num not in sections or len(content) > len(
+                sections[item_num]["content"]
+            ):
+                sections[item_num] = {"title": title, "content": content}
+
+        return sections
+
+    @staticmethod
+    def resolve_section_key(section: str) -> str:
+        """Resolve section name/alias to Item number."""
+        clean = section.strip().lower()
+        if clean in SECTION_ALIASES:
+            return SECTION_ALIASES[clean]
+        return section.strip().upper()