the13f-mcp 0.1.1__tar.gz

the13f_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: the13f-mcp
+Version: 0.1.1
+Summary: Model Context Protocol server for the13f - institutional 13F intelligence in Claude Desktop, Cursor, and VS Code.
+Author-email: Pickel Fintech <tom@pickelfintech.com>
+License: MIT
+Project-URL: Homepage, https://the13f.com/developers/
+Project-URL: Documentation, https://the13f.com/developers/mcp.html
+Project-URL: Signup, https://the13f.com/developers/
+Project-URL: Source, https://gitlab.com/pickel-fintech/The13F
+Project-URL: Changelog, https://gitlab.com/pickel-fintech/The13F/-/blob/main/mcp_server/CHANGELOG.md
+Project-URL: Issues, https://gitlab.com/pickel-fintech/The13F/-/issues
+Keywords: 13f,sec,institutional,investment,mcp,claude,cursor,anthropic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+
+# the13f-mcp
+
+> Model Context Protocol server for [the13f](https://the13f.com). Brings
+> institutional 13F intelligence into Claude Desktop, Cursor, VS Code +
+> Continue, and any MCP-compatible host — no HTTP code required on your side.
+
+## Important limitations
+
+Research data only. Sourced from publicly disclosed SEC Form 13F filings,
+which lag quarter-end by up to 45 days. Past institutional positioning does
+not predict future performance. Nothing here constitutes investment advice.
+Every tool's response includes a `disclaimer` field; the host LLM should
+surface it alongside any analysis it produces.
+
+## Install
+
+```
+uvx the13f-mcp
+```
+
+Or `pip install the13f-mcp` if you prefer to manage Python environments
+yourself. Python 3.11+ required.
+
+## Get a free API key
+
+Free, no payment, no credit card:
+
+1. Visit <https://the13f.com/developers/>
+2. Enter your email and solve the Cloudflare Turnstile challenge
+3. Copy your `pf13f_` key — **shown once**
+4. Paste it into your MCP host's config as `THE13F_API_KEY` (see below)
+5. Restart the host
+
+Free tier: 100 read calls per day; quota rolls at UTC midnight. Signal and
+report tools arrive in later minor versions when paid tiers launch.
+
+## Configure your MCP host
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "the13f": {
+      "command": "uvx",
+      "args": ["the13f-mcp"],
+      "env": {
+        "THE13F_API_KEY": "pf13f_..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The13f tools should appear in the MCP tool list.
+
+### Cursor
+
+Settings → MCP → Add Server. Paste the same JSON block into the "Custom"
+field.
+
+### VS Code with Continue
+
+Settings → `experimental.modelContextProtocolServers` → add a `stdio`
+transport running `uvx the13f-mcp` with `THE13F_API_KEY` in env. The key
+reveal page at <https://the13f.com/developers/signup-success> shows a
+copy-paste-ready snippet with the key already filled in.
+
+## Available tools — v0.1.0 (Read tier, free)
+
+| Tool | What it does |
+|------|---------------|
+| `list_quarters` | All quarters with holdings data + the latest quarter |
+| `search_managers` | Autocomplete 13F filers by name |
+| `get_manager_holdings` | Full positions for a CIK + quarter |
+| `get_manager_holdings_bulk` | Up to 25 `(cik, quarter)` pairs in one call |
+| `list_all_managers` | Universe of 8,600+ filers with per-manager summary stats |
+| `find_similar_managers` | Match a portfolio against the universe |
+| `get_consensus_portfolio` | Most-widely-held securities per quarter |
+| `get_market_regime` | Institutional regime snapshot (IIOI composite, state, transition) |
+| `get_sector_flows` | Per-sector capital flows and risk posture |
+
+## Planned tools — later versions
+
+| Version | Tools | Requires |
+|---|---|---|
+| v0.2.0 | `get_security_signals`, `get_security_signals_bulk`, `get_portfolio_signals` | Standard tier subscription |
+| v0.3.0 | `generate_manager_report`, `generate_security_report`, `generate_sector_report`, `check_report_status`, `wait_and_download_report` | Standard tier + stored card; two-step confirm |
+
+The free-tier Read tools are enough to explore the data and build prompts
+against it. Signal and report tools deliberately wait on the paid-tier
+billing plumbing.
+
+## Example prompts
+
+> "Pull Berkshire Hathaway's top 20 positions as of Q4 2025 and summarize
+> what grew the most quarter-over-quarter."
+
+> "I own AAPL, MSFT, and NVDA equal-weight. Find the 5 institutional
+> managers whose portfolios most closely resemble mine."
+
+> "What sector did 13F filers most aggressively reduce last quarter? Show
+> me the top three managers leading the reduction."
+
+The MCP host's LLM picks the right tool, fills in arguments, surfaces the
+`disclaimer`, and returns the result as structured JSON.
+
+## Environment variables
+
+| Var | Default | What it controls |
+|---|---|---|
+| `THE13F_API_KEY` | (none) | Your `pf13f_` key. Without it, tools return a structured "free signup required" response with a link to the signup page. |
+| `THE13F_API_BASE_URL` | `https://api.the13f.com` | Override for local development against a running copy of the13f's gui_server. |
+| `THE13F_MCP_TIMEOUT` | `30` | Per-request HTTP timeout in seconds. Minimum 5. |
+
+## Source
+
+Published from this directory of <https://gitlab.com/pickel-fintech/The13F>.
+Tag pattern `sdk-mcp-vX.Y.Z` triggers a PyPI release via GitLab CI; see
+`docs/mcp_launch.plan.md` in the repo root for the extraction story and the
+release runbook.
+
+## Support
+
+tom@pickelfintech.com — quote the `request_id` field returned by any failing
+tool call for fastest triage.
+
+## License
+
+MIT. See [LICENSE](../LICENSE). The MCP server source is MIT-licensed; use
+of the the13f API itself is governed by the Terms of Service at
+<https://the13f.com/terms.html>.

the13f_mcp-0.1.1/README.md

@@ -0,0 +1,135 @@
+# the13f-mcp
+
+> Model Context Protocol server for [the13f](https://the13f.com). Brings
+> institutional 13F intelligence into Claude Desktop, Cursor, VS Code +
+> Continue, and any MCP-compatible host — no HTTP code required on your side.
+
+## Important limitations
+
+Research data only. Sourced from publicly disclosed SEC Form 13F filings,
+which lag quarter-end by up to 45 days. Past institutional positioning does
+not predict future performance. Nothing here constitutes investment advice.
+Every tool's response includes a `disclaimer` field; the host LLM should
+surface it alongside any analysis it produces.
+
+## Install
+
+```
+uvx the13f-mcp
+```
+
+Or `pip install the13f-mcp` if you prefer to manage Python environments
+yourself. Python 3.11+ required.
+
+## Get a free API key
+
+Free, no payment, no credit card:
+
+1. Visit <https://the13f.com/developers/>
+2. Enter your email and solve the Cloudflare Turnstile challenge
+3. Copy your `pf13f_` key — **shown once**
+4. Paste it into your MCP host's config as `THE13F_API_KEY` (see below)
+5. Restart the host
+
+Free tier: 100 read calls per day; quota rolls at UTC midnight. Signal and
+report tools arrive in later minor versions when paid tiers launch.
+
+## Configure your MCP host
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "the13f": {
+      "command": "uvx",
+      "args": ["the13f-mcp"],
+      "env": {
+        "THE13F_API_KEY": "pf13f_..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The13f tools should appear in the MCP tool list.
+
+### Cursor
+
+Settings → MCP → Add Server. Paste the same JSON block into the "Custom"
+field.
+
+### VS Code with Continue
+
+Settings → `experimental.modelContextProtocolServers` → add a `stdio`
+transport running `uvx the13f-mcp` with `THE13F_API_KEY` in env. The key
+reveal page at <https://the13f.com/developers/signup-success> shows a
+copy-paste-ready snippet with the key already filled in.
+
+## Available tools — v0.1.0 (Read tier, free)
+
+| Tool | What it does |
+|------|---------------|
+| `list_quarters` | All quarters with holdings data + the latest quarter |
+| `search_managers` | Autocomplete 13F filers by name |
+| `get_manager_holdings` | Full positions for a CIK + quarter |
+| `get_manager_holdings_bulk` | Up to 25 `(cik, quarter)` pairs in one call |
+| `list_all_managers` | Universe of 8,600+ filers with per-manager summary stats |
+| `find_similar_managers` | Match a portfolio against the universe |
+| `get_consensus_portfolio` | Most-widely-held securities per quarter |
+| `get_market_regime` | Institutional regime snapshot (IIOI composite, state, transition) |
+| `get_sector_flows` | Per-sector capital flows and risk posture |
+
+## Planned tools — later versions
+
+| Version | Tools | Requires |
+|---|---|---|
+| v0.2.0 | `get_security_signals`, `get_security_signals_bulk`, `get_portfolio_signals` | Standard tier subscription |
+| v0.3.0 | `generate_manager_report`, `generate_security_report`, `generate_sector_report`, `check_report_status`, `wait_and_download_report` | Standard tier + stored card; two-step confirm |
+
+The free-tier Read tools are enough to explore the data and build prompts
+against it. Signal and report tools deliberately wait on the paid-tier
+billing plumbing.
+
+## Example prompts
+
+> "Pull Berkshire Hathaway's top 20 positions as of Q4 2025 and summarize
+> what grew the most quarter-over-quarter."
+
+> "I own AAPL, MSFT, and NVDA equal-weight. Find the 5 institutional
+> managers whose portfolios most closely resemble mine."
+
+> "What sector did 13F filers most aggressively reduce last quarter? Show
+> me the top three managers leading the reduction."
+
+The MCP host's LLM picks the right tool, fills in arguments, surfaces the
+`disclaimer`, and returns the result as structured JSON.
+
+## Environment variables
+
+| Var | Default | What it controls |
+|---|---|---|
+| `THE13F_API_KEY` | (none) | Your `pf13f_` key. Without it, tools return a structured "free signup required" response with a link to the signup page. |
+| `THE13F_API_BASE_URL` | `https://api.the13f.com` | Override for local development against a running copy of the13f's gui_server. |
+| `THE13F_MCP_TIMEOUT` | `30` | Per-request HTTP timeout in seconds. Minimum 5. |
+
+## Source
+
+Published from this directory of <https://gitlab.com/pickel-fintech/The13F>.
+Tag pattern `sdk-mcp-vX.Y.Z` triggers a PyPI release via GitLab CI; see
+`docs/mcp_launch.plan.md` in the repo root for the extraction story and the
+release runbook.
+
+## Support
+
+tom@pickelfintech.com — quote the `request_id` field returned by any failing
+tool call for fastest triage.
+
+## License
+
+MIT. See [LICENSE](../LICENSE). The MCP server source is MIT-licensed; use
+of the the13f API itself is governed by the Terms of Service at
+<https://the13f.com/terms.html>.

the13f_mcp-0.1.1/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "the13f-mcp"
+version = "0.1.1"
+description = "Model Context Protocol server for the13f - institutional 13F intelligence in Claude Desktop, Cursor, and VS Code."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Pickel Fintech", email = "tom@pickelfintech.com" }]
+keywords = ["13f", "sec", "institutional", "investment", "mcp", "claude", "cursor", "anthropic"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "mcp>=1.0",
+    "httpx>=0.27",
+    "pydantic>=2.6",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.4",
+]
+
+[project.scripts]
+the13f-mcp = "the13f_mcp.server:main"
+
+[project.urls]
+Homepage = "https://the13f.com/developers/"
+Documentation = "https://the13f.com/developers/mcp.html"
+Signup = "https://the13f.com/developers/"
+Source = "https://gitlab.com/pickel-fintech/The13F"
+Changelog = "https://gitlab.com/pickel-fintech/The13F/-/blob/main/mcp_server/CHANGELOG.md"
+Issues = "https://gitlab.com/pickel-fintech/The13F/-/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

the13f_mcp-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

the13f_mcp-0.1.1/src/the13f_mcp/__init__.py

@@ -0,0 +1,24 @@
+"""the13f-mcp - Model Context Protocol server for the13f Platform.
+
+Exposes institutional 13F intelligence as MCP tools to Claude Desktop, Cursor,
+VS Code, Continue, and any MCP-compatible host. Read tools work for any signed-up
+user (free tier); signal tools and PDF report generation require Standard+
+subscription on platform.the13f.com.
+
+Install:
+    uvx the13f-mcp
+
+Configure in your MCP host (e.g. ~/Library/Application Support/Claude/claude_desktop_config.json):
+    {
+      "mcpServers": {
+        "the13f": {
+          "command": "uvx",
+          "args": ["the13f-mcp"],
+          "env": {"THE13F_API_KEY": "pf13f_..."}
+        }
+      }
+    }
+"""
+from ._version import __version__
+
+__all__ = ["__version__"]

the13f_mcp-0.1.1/src/the13f_mcp/_version.py

@@ -0,0 +1,2 @@
+"""Version constant. Own module to avoid circular imports."""
+__version__ = "0.1.1"

the13f_mcp-0.1.1/src/the13f_mcp/config.py

@@ -0,0 +1,39 @@
+"""Configuration loader for the MCP server.
+
+Reads three environment variables:
+
+    THE13F_API_KEY      - the user's pf13f_ key issued at
+                          https://the13f.com/developers/signup. Optional:
+                          read tools can surface a signup CTA on the first
+                          call when the key is absent. THIS IS THE
+                          CONVERSION GATE.
+
+    THE13F_API_BASE_URL - defaults to https://api.the13f.com. Override for
+                          local development (e.g. http://127.0.0.1:5053).
+
+    THE13F_MCP_TIMEOUT  - HTTP timeout in seconds. Default 30.
+"""
+from __future__ import annotations
+
+import os
+
+DEFAULT_BASE_URL = "https://api.the13f.com"
+DEFAULT_TIMEOUT_SECONDS = 30
+SIGNUP_URL = "https://the13f.com/developers/"
+
+
+def api_key() -> str | None:
+    raw = os.environ.get("THE13F_API_KEY", "").strip()
+    return raw or None
+
+
+def base_url() -> str:
+    return (os.environ.get("THE13F_API_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+
+def timeout_seconds() -> float:
+    raw = os.environ.get("THE13F_MCP_TIMEOUT", str(DEFAULT_TIMEOUT_SECONDS))
+    try:
+        return max(5.0, float(raw))
+    except ValueError:
+        return float(DEFAULT_TIMEOUT_SECONDS)

the13f_mcp-0.1.1/src/the13f_mcp/disclaimer.py

@@ -0,0 +1,31 @@
+"""Canonical research-only disclaimer text for the MCP server.
+
+Mirrors api_gateway/config/disclaimer.yml. Update both at the same time
+(or - better - have the MCP fetch it dynamically from the API at startup;
+that's a v0.2 enhancement).
+"""
+CANONICAL_TEXT = (
+    "Research data only. Sourced from publicly disclosed SEC Form 13F "
+    "filings, which lag quarter-end by up to 45 days and reflect long-only "
+    "equity positions of the filing manager. Past institutional positioning "
+    "does not predict future performance and nothing here constitutes "
+    "investment advice, a recommendation, or a solicitation. Do your own "
+    "analysis before making investment decisions."
+)
+
+SHORT_FORM = "Research data only - not investment advice."
+
+# Prefix for every tool description. The MCP host displays these to the LLM
+# as part of the tool catalog; the LLM should re-surface our framing.
+TOOL_DESCRIPTION_PREFIX = (
+    "Research data only. Returns disclosed institutional positions; "
+    "do not infer manager intent or future direction. "
+)
+
+
+def wrap(data: dict) -> dict:
+    """Add the disclaimer field to a tool result. Single helper for consistency."""
+    if not isinstance(data, dict):
+        data = {"data": data}
+    data.setdefault("disclaimer", CANONICAL_TEXT)
+    return data

the13f_mcp-0.1.1/src/the13f_mcp/http_client.py

@@ -0,0 +1,119 @@
+"""Shared HTTP client for the MCP server.
+
+Wraps httpx with the platform's auth header, sane timeouts, retry-on-429
+honoring Retry-After, and a small set of typed exceptions that the tool
+modules surface back to the MCP host.
+
+Importing this module is cheap; the httpx.Client is built lazily on first call.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from . import config
+
+_client: httpx.Client | None = None
+
+
+class The13FApiError(RuntimeError):
+    """Base exception for any non-2xx response or transport error."""
+
+    def __init__(self, message: str, status_code: int | None = None, body: dict | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body or {}
+        self.request_id = self.body.get("request_id")
+        self.docs_url = self.body.get("docs_url")
+        self.disclaimer = self.body.get("disclaimer")
+
+
+class FreeSignupRequiredError(The13FApiError):
+    """Raised when no THE13F_API_KEY is set; surfaces signup CTA to the user."""
+
+
+class TierUpgradeRequiredError(The13FApiError):
+    """403 - the user's tier doesn't unlock this feature."""
+
+
+class PaymentRequiredError(The13FApiError):
+    """402 - quota exhausted + no credits OR card declined OR no card on file."""
+
+
+def _client_lazy() -> httpx.Client:
+    global _client
+    if _client is None:
+        headers: dict[str, str] = {"User-Agent": _user_agent()}
+        api_key = config.api_key()
+        if api_key:
+            headers["X-API-Key"] = api_key
+        _client = httpx.Client(
+            base_url=config.base_url(),
+            timeout=config.timeout_seconds(),
+            headers=headers,
+        )
+    return _client
+
+
+def _user_agent() -> str:
+    from ._version import __version__
+    return f"the13f-mcp/{__version__} (python-mcp; +{config.SIGNUP_URL})"
+
+
+def request(method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+    """Perform one API call with retry on 429.
+
+    Returns the parsed JSON dict. Raises one of the typed exceptions on
+    non-2xx responses.
+    """
+    if not config.api_key():
+        raise FreeSignupRequiredError(
+            f"Free signup required. Visit {config.SIGNUP_URL}, complete the "
+            "free email signup (Cloudflare Turnstile), copy the issued "
+            "pf13f_ key, and set THE13F_API_KEY in your MCP host config "
+            "(Claude Desktop, Cursor, or VS Code + Continue). Then restart "
+            "the host.",
+            status_code=401,
+        )
+
+    client = _client_lazy()
+    attempts = 0
+    while True:
+        attempts += 1
+        try:
+            response = client.request(method, path, **kwargs)
+        except httpx.TimeoutException as timeout_err:
+            raise The13FApiError(f"Timed out talking to the13f Platform: {timeout_err}") from timeout_err
+        except httpx.HTTPError as transport_err:
+            raise The13FApiError(f"Transport error: {transport_err}") from transport_err
+
+        if response.status_code == 429 and attempts < 3:
+            retry_after = response.headers.get("Retry-After", "1")
+            try:
+                wait_s = float(retry_after)
+            except ValueError:
+                wait_s = 1.0
+            time.sleep(min(wait_s, 30.0))
+            continue
+        return _interpret(response)
+
+
+def _interpret(response: httpx.Response) -> dict[str, Any]:
+    """Parse the response. Raise typed exceptions for non-2xx."""
+    try:
+        body = response.json()
+    except ValueError:
+        body = {"error": response.text[:500]}
+    if 200 <= response.status_code < 300:
+        return body if isinstance(body, dict) else {"data": body}
+
+    message = body.get("error", f"HTTP {response.status_code}")
+    if response.status_code == 401:
+        raise FreeSignupRequiredError(message, status_code=401, body=body)
+    if response.status_code == 402:
+        raise PaymentRequiredError(message, status_code=402, body=body)
+    if response.status_code == 403:
+        raise TierUpgradeRequiredError(message, status_code=403, body=body)
+    raise The13FApiError(message, status_code=response.status_code, body=body)