filingexplorer-mcp 0.1.0__py3-none-any.whl

filingexplorer_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for the FilingExplorer API."""
+
+__version__ = "0.1.0"

filingexplorer_mcp/__main__.py

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

filingexplorer_mcp/client.py

@@ -0,0 +1,174 @@
+"""Thin async HTTP client for the FilingExplorer API."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+from mcp.server.fastmcp.exceptions import ToolError
+
+from filingexplorer_mcp import __version__
+
+DEFAULT_BASE_URL = "https://api.filingexplorer.com"
+TOKEN_ENV = "FILING_EXPLORER_API_TOKEN"
+BASE_URL_ENV = "FILING_EXPLORER_API_URL"
+TIMEOUT_ENV = "FILING_EXPLORER_TIMEOUT"
+
+
+class ApiError(ToolError):
+    """An error response from the API, rendered as a readable tool error."""
+
+    def __init__(self, status: int, message: str):
+        self.status = status
+        super().__init__(message)
+
+
+def segment(value: str) -> str:
+    """Percent-encode one path segment (list names may contain spaces or slashes)."""
+    return quote(str(value), safe="")
+
+
+def _base_url() -> str:
+    return os.environ.get(BASE_URL_ENV, DEFAULT_BASE_URL).rstrip("/")
+
+
+def _token() -> str:
+    token = os.environ.get(TOKEN_ENV, "").strip()
+    if not token:
+        raise ApiError(
+            401,
+            f"No API token configured. Set the {TOKEN_ENV} environment variable "
+            "to your FilingExplorer API token.",
+        )
+    return token
+
+
+def _timeout() -> float:
+    try:
+        return float(os.environ.get(TIMEOUT_ENV, "60"))
+    except ValueError:
+        return 60.0
+
+
+def clean_params(params: dict[str, Any] | None) -> list[tuple[str, str]]:
+    """Drop unset values, render booleans as true/false, expand lists."""
+    out: list[tuple[str, str]] = []
+    for key, value in (params or {}).items():
+        if value is None or value == "" or value == []:
+            continue
+        if isinstance(value, (list, tuple)):
+            out.extend((key, str(v)) for v in value)
+        elif isinstance(value, bool):
+            out.append((key, "true" if value else "false"))
+        else:
+            out.append((key, str(value)))
+    return out
+
+
+def _error_detail(response: httpx.Response) -> tuple[str, Any]:
+    try:
+        body = response.json()
+    except ValueError:
+        text = response.text.strip()
+        return (text[:300] if text and "<html" not in text.lower() else ""), None
+    if isinstance(body, dict):
+        err = body.get("error", body.get("errors", body))
+        if isinstance(err, str):
+            return err, None
+        if isinstance(err, dict):
+            message = str(err.get("message") or err.get("code") or "")
+            hint = err.get("hint")
+            if hint:
+                message = f"{message} ({hint})" if message else str(hint)
+            return message, err.get("details")
+        if isinstance(err, list):
+            return "; ".join(str(e) for e in err), None
+    return "", None
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    status = response.status_code
+    if status < 400:
+        return
+    message, details = _error_detail(response)
+    suffix = f": {message}" if message else ""
+    if status == 400:
+        text = f"Invalid request (400){suffix}"
+    elif status == 401:
+        text = (
+            "Authentication failed (401): the API token is missing, invalid or expired. "
+            f"Check {TOKEN_ENV}."
+        )
+    elif status == 402:
+        text = f"This request needs a paid FilingExplorer plan (402){suffix}"
+    elif status == 403:
+        text = f"Not permitted for this account (403){suffix}"
+    elif status == 404:
+        text = f"Not found (404){suffix}"
+    elif status == 409:
+        text = f"Ambiguous identifier (409){suffix}"
+        matches = details.get("matches") if isinstance(details, dict) else None
+        if matches:
+            options = []
+            for m in matches[:10]:
+                if isinstance(m, dict):
+                    parts = [str(m[k]) for k in ("symbol", "exchange", "cusip", "name") if m.get(k)]
+                    options.append(" / ".join(parts))
+            text += ". Candidates: " + "; ".join(options) + ". Retry with a more specific value."
+    elif status == 413:
+        text = f"Document too large to extract (413){suffix}"
+    elif status == 422:
+        text = f"Validation failed (422){suffix}"
+        if isinstance(details, dict) and details:
+            text += " " + "; ".join(
+                f"{k} {', '.join(map(str, v)) if isinstance(v, list) else v}"
+                for k, v in details.items()
+            )
+    elif status == 429:
+        retry = response.headers.get("Retry-After")
+        wait = f" Retry after {retry} seconds." if retry else " Wait a moment and retry."
+        text = f"Rate limited by the FilingExplorer API (429).{wait}"
+    elif status >= 500:
+        text = f"FilingExplorer API error ({status}){suffix}. Try again later."
+    else:
+        text = f"Request failed ({status}){suffix}"
+    raise ApiError(status, text)
+
+
+async def request(
+    method: str,
+    path: str,
+    *,
+    params: dict[str, Any] | None = None,
+    body: dict[str, Any] | None = None,
+    text: bool = False,
+) -> Any:
+    """Call the API and return parsed JSON (or text when ``text`` is true).
+
+    Returns ``None`` for 204 responses.
+    """
+    headers = {
+        "Authorization": f"Bearer {_token()}",
+        "Accept": "text/plain" if text else "application/json",
+        "User-Agent": f"filingexplorer-mcp/{__version__}",
+    }
+    try:
+        async with httpx.AsyncClient(base_url=_base_url(), timeout=_timeout()) as client:
+            response = await client.request(
+                method, path, params=clean_params(params), json=body, headers=headers
+            )
+    except httpx.TimeoutException as exc:
+        raise ApiError(504, "The FilingExplorer API did not respond in time. Try again.") from exc
+    except httpx.HTTPError as exc:
+        raise ApiError(503, f"Could not reach the FilingExplorer API: {exc}") from exc
+    _raise_for_status(response)
+    if response.status_code == 204 or not response.content:
+        return None
+    if text:
+        return response.text
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise ApiError(502, "The FilingExplorer API returned an unreadable response.") from exc

filingexplorer_mcp/formatting.py

@@ -0,0 +1,129 @@
+"""Render API payloads as compact, YAML-like text.
+
+The goal is a format that is cheap in tokens and easy for a model to read:
+null and empty mapping values are dropped, short scalar lists stay on one line,
+and multi-line strings use a literal block. Inside a list a null stays as
+``null``: lists are often aligned to periods, and dropping an item would shift
+every later value onto the wrong period.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+_PLAIN = re.compile(r"^[A-Za-z0-9_./()%$@+\-][^:#\n]*$")
+_RESERVED = {"true", "false", "null", "yes", "no", "on", "off", "~"}
+_INLINE_LIST_MAX = 120
+
+
+def _is_empty(value: Any) -> bool:
+    if isinstance(value, list):
+        return all(item is None for item in value)
+    return value is None or value == "" or value == {}
+
+
+def _scalar(value: Any) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        return repr(value) if value != int(value) or abs(value) >= 1e16 else str(int(value))
+    text = str(value)
+    if (
+        _PLAIN.match(text)
+        and text == text.strip()
+        and text.lower() not in _RESERVED
+        and not text.endswith(":")
+    ):
+        return text
+    return json.dumps(text, ensure_ascii=False)
+
+
+def _is_scalar(value: Any) -> bool:
+    return not isinstance(value, (dict, list))
+
+
+def _lines(value: Any, indent: int) -> list[str]:
+    pad = "  " * indent
+    out: list[str] = []
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if _is_empty(item):
+                continue
+            out.extend(_keyed(str(key), item, indent))
+    elif isinstance(value, list):
+        for item in value:
+            if isinstance(item, dict):
+                body = _lines(item, indent + 1)
+                if not body:
+                    continue
+                first = body[0].lstrip()
+                out.append(f"{pad}- {first}")
+                out.extend(body[1:])
+            elif isinstance(item, list):
+                out.append(f"{pad}-")
+                out.extend(_lines(item, indent + 1))
+            else:
+                out.extend(_block_or_line(f"{pad}- ", item, indent + 1))
+    else:
+        out.extend(_block_or_line(pad, value, indent))
+    return out
+
+
+def _block_or_line(prefix: str, value: Any, indent: int) -> list[str]:
+    if isinstance(value, str) and "\n" in value:
+        pad = "  " * indent
+        return [f"{prefix}|"] + [f"{pad}{line}" if line else "" for line in value.split("\n")]
+    return [f"{prefix}{_scalar(value)}"]
+
+
+def _keyed(key: str, item: Any, indent: int) -> list[str]:
+    pad = "  " * indent
+    label = _scalar(key)
+    if isinstance(item, list) and all(_is_scalar(v) for v in item):
+        rendered = ", ".join(_scalar(v) for v in item)
+        if len(rendered) <= _INLINE_LIST_MAX and not any(
+            isinstance(v, str) and "\n" in v for v in item
+        ):
+            return [f"{pad}{label}: [{rendered}]"]
+    if isinstance(item, (dict, list)):
+        body = _lines(item, indent + 1)
+        return [f"{pad}{label}:"] + body if body else []
+    return _block_or_line(f"{pad}{label}: ", item, indent + 1)
+
+
+def to_text(value: Any) -> str:
+    """Render ``value`` as compact YAML-like text."""
+    if _is_empty(value):
+        return "(no data)"
+    return "\n".join(_lines(value, 0))
+
+
+def page_note(total: int | None, offset: int, returned: int, has_more: bool | None) -> str:
+    """One-line pagination footer, or an empty string when everything was returned."""
+    more = has_more if has_more is not None else (total is not None and offset + returned < total)
+    if not more:
+        return ""
+    total_part = f" of {total}" if total is not None else ""
+    return (
+        f"\n\n[showing {offset + 1}-{offset + returned}{total_part}; "
+        f"call again with offset={offset + returned} for more]"
+    )
+
+
+def slice_text(text: str, offset: int, max_chars: int) -> str:
+    """Return one window of a long text with a header describing the window."""
+    total = len(text)
+    offset = max(0, offset)
+    chunk = text[offset : offset + max_chars]
+    end = offset + len(chunk)
+    if offset == 0 and end >= total:
+        return chunk
+    note = f"[characters {offset}-{end} of {total}"
+    note += f"; call again with offset={end} for more]" if end < total else "; end of text]"
+    return f"{note}\n\n{chunk}"