substack-api-mcp 1.0.2__py3-none-any.whl

substack_api_mcp/core/context.py

@@ -0,0 +1,175 @@
+"""What a tool function gets besides its input: a ready HTTP client with your session of the app.
+
+Requests go out with curl_cffi, which copies Chrome's TLS and HTTP/2 fingerprint, so the app sees the same
+kind of client as your browser. Only the app's hosts (`app.DOMAINS`) are reachable, redirects included.
+"""
+
+from __future__ import annotations
+
+import json as jsonlib
+import time
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urljoin, urlsplit
+
+from curl_cffi.requests import AsyncSession, BrowserType
+
+from substack_api_mcp import app
+from substack_api_mcp.core.account_guard import check_account_write
+from substack_api_mcp.core.errors import AuthExpiredError, CaptchaRequiredError, ErrorCode, ToolError
+from substack_api_mcp.session import Session
+
+DOMAINS = app.DOMAINS
+_REDIRECTS = {301, 302, 303, 307, 308}
+_MAX_REDIRECTS = 10
+_TARGETS = {member.value for member in BrowserType}
+_CHALLENGE_MARKERS = ("cf-chl", "challenge-platform", "Just a moment...", "cf_chl_opt")
+_CAPTCHA_MARKERS = ("g-recaptcha", "h-captcha", "cf-turnstile")
+_LOGGED_OUT_MARKERS = app.LOGGED_OUT_MARKERS
+
+
+@dataclass(frozen=True)
+class HttpResponse:
+    status: int
+    url: str
+    headers: dict[str, str]
+    text: str
+
+    def json(self) -> Any:
+        try:
+            return jsonlib.loads(self.text)
+        except ValueError as exc:
+            raise ToolError(f"{app.NAME} answered with something that is not JSON.", ErrorCode.TARGET_ERROR) from exc
+
+
+def allowed_host(url: str) -> bool:
+    host = (urlsplit(url).hostname or "").lower()
+    return any(host == domain or host.endswith(f".{domain}") for domain in DOMAINS)
+
+
+def impersonate_target(chrome_major: int | None) -> str:
+    """The exact Chrome version when curl_cffi has it, otherwise its newest Chrome profile."""
+    target = f"chrome{chrome_major}"
+    return target if chrome_major and target in _TARGETS else "chrome"
+
+
+def _raise_for(response: HttpResponse) -> None:
+    final_url = response.url.lower()
+    if response.status == 401 or any(marker in final_url for marker in _LOGGED_OUT_MARKERS):
+        raise AuthExpiredError(
+            f"{app.NAME} signed this session out. Sign in to {app.NAME} in Chrome, then run: {app.CLI} connect"
+        )
+    if response.status == 429:
+        raise ToolError(f"{app.NAME} is rate limiting this account. Try again later.", ErrorCode.RATE_LIMITED)
+    head = response.text[:20000]
+    if response.status in (401, 403) and any(marker in head for marker in app.RELOGIN_MARKERS):
+        raise AuthExpiredError(
+            f"{app.NAME} asks you to sign in again before this action. Sign out and in again at "
+            f"{app.LOGIN_URL} in Chrome, then run: {app.CLI} connect"
+        )
+    if response.status in (200, 403) and any(marker in head for marker in _CAPTCHA_MARKERS):
+        raise CaptchaRequiredError(
+            f"{app.NAME} asks for a CAPTCHA. Open {app.DOMAINS[0]} in Chrome, finish it, then try again."
+        )
+    if response.status in (403, 503) and (
+        response.headers.get("cf-mitigated") == "challenge" or any(marker in head for marker in _CHALLENGE_MARKERS)
+    ):
+        raise ToolError(
+            f"{app.NAME} showed a bot check. Open {app.DOMAINS[0]} in Chrome once, then try again.",
+            ErrorCode.TARGET_BLOCKED,
+        )
+    if response.status == 403:
+        raise ToolError(f"{app.NAME} refused the request (403).", ErrorCode.TARGET_BLOCKED)
+
+
+@dataclass
+class ToolContext:
+    session: Session
+    timeout_s: float = 30.0
+    _cache: dict[str, tuple[float, str]] = field(default_factory=dict, repr=False)
+    _http: AsyncSession | None = field(default=None, repr=False)
+
+    def _client(self) -> AsyncSession:
+        if self._http is None:
+            headers = {"accept-language": self.session.locale or "en-US,en;q=0.9"}
+            target = impersonate_target(self.session.chrome_major)
+            # The browser's own user agent only when the TLS fingerprint matches its version.
+            if self.session.user_agent and target != "chrome":
+                headers["user-agent"] = self.session.user_agent
+            self._http = AsyncSession(impersonate=target, proxy=self.session.proxy or None, headers=headers)  # pyright: ignore[reportArgumentType] - target is a BrowserType value
+            for cookie in self.session.cookies:
+                self._http.cookies.set(
+                    cookie["name"], cookie["value"], domain=cookie["domain"], path=cookie.get("path", "/")
+                )
+        return self._http
+
+    async def call(self, method: str, url: str, **kwargs: Any) -> HttpResponse:
+        """One request to the app with your cookies. A signed-out answer raises auth_expired.
+
+        Writes to your account settings in the app are refused before they leave (account_guard).
+        """
+        if not allowed_host(url):
+            raise ToolError(f"Request outside {app.DOMAINS[0]}.", ErrorCode.INTERNAL_ERROR)
+        check_account_write(method, url)
+        client = self._client()
+        method = method.upper()
+        params, json, data, headers = (
+            kwargs.get("params"),
+            kwargs.get("json"),
+            kwargs.get("data"),
+            kwargs.get("headers"),
+        )
+        for _ in range(_MAX_REDIRECTS + 1):
+            try:
+                raw = await client.request(
+                    method,  # pyright: ignore[reportArgumentType] - an HTTP method name
+                    url,
+                    params=params,
+                    json=json,
+                    data=data,
+                    headers=headers,
+                    timeout=self.timeout_s,
+                    allow_redirects=False,
+                )
+            except Exception as exc:
+                raise ToolError(f"{app.NAME} did not answer: {type(exc).__name__}.", ErrorCode.TARGET_ERROR) from exc
+            location = raw.headers.get("location")
+            if raw.status_code not in _REDIRECTS or not location:
+                break
+            url = urljoin(str(raw.url), location)
+            if not allowed_host(url):
+                raise ToolError(f"{app.NAME} redirected outside {app.DOMAINS[0]}.", ErrorCode.TARGET_ERROR)
+            params = None
+            if raw.status_code == 303 or (raw.status_code in (301, 302) and method == "POST"):
+                method, json, data = "GET", None, None
+        else:
+            raise ToolError("Too many redirects.", ErrorCode.TARGET_ERROR)
+        response = HttpResponse(
+            status=raw.status_code,
+            url=str(raw.url),
+            headers={k.lower(): v or "" for k, v in raw.headers.items()},
+            text=raw.text,
+        )
+        _raise_for(response)
+        return response
+
+    async def get_json(self, url: str, **kwargs: Any) -> Any:
+        return (await self.call("GET", url, **kwargs)).json()
+
+    async def post_json(self, url: str, payload: Any, **kwargs: Any) -> Any:
+        return (await self.call("POST", url, json=payload, **kwargs)).json()
+
+    async def cache_get(self, key: str) -> str | None:
+        """Short-lived app data (a build id, a page token), kept in this process."""
+        entry = self._cache.get(key)
+        if entry is None or entry[0] < time.monotonic():
+            return None
+        return entry[1]
+
+    async def cache_set(self, key: str, value: str, ttl_s: int) -> None:
+        self._cache[key] = (time.monotonic() + ttl_s, value)
+
+    async def close(self) -> None:
+        if self._http is not None:
+            await self._http.close()
+            self._http = None

substack_api_mcp/core/errors.py

@@ -0,0 +1,78 @@
+"""Error codes a tool call can end with, and the exceptions tools raise to produce them.
+
+The REST API answers with the code in `error` and the HTTP status from `HTTP_STATUS`; the MCP server
+returns the same code and message as a tool error.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class ErrorCode(StrEnum):
+    # No session for this server yet, or the app signed it out: run `<cli> connect` again.
+    AUTH_REQUIRED = "auth_required"
+    AUTH_EXPIRED = "auth_expired"
+    CAPTCHA_REQUIRED = "captcha_required"
+    MFA_REQUIRED = "mfa_required"
+    # The tool changes something and the server runs with --read-only.
+    SCOPE_DENIED = "scope_denied"
+    # The account in the app lacks the role (not a group admin, not the author).
+    APP_PERMISSION_DENIED = "app_permission_denied"
+    TARGET_BLOCKED = "target_blocked"
+    UNKNOWN_TOOL = "unknown_tool"
+    INVALID_INPUT = "invalid_input"
+    NOT_BUILT = "not_built"
+    TARGET_ERROR = "target_error"
+    RATE_LIMITED = "rate_limited"
+    TIMEOUT = "timeout"
+    INTERNAL_ERROR = "internal_error"
+
+
+HTTP_STATUS: dict[ErrorCode, int] = {
+    ErrorCode.AUTH_REQUIRED: 401,
+    ErrorCode.AUTH_EXPIRED: 401,
+    ErrorCode.CAPTCHA_REQUIRED: 409,
+    ErrorCode.MFA_REQUIRED: 409,
+    ErrorCode.SCOPE_DENIED: 403,
+    ErrorCode.APP_PERMISSION_DENIED: 403,
+    ErrorCode.TARGET_BLOCKED: 403,
+    ErrorCode.UNKNOWN_TOOL: 404,
+    ErrorCode.INVALID_INPUT: 422,
+    ErrorCode.NOT_BUILT: 501,
+    ErrorCode.TARGET_ERROR: 502,
+    ErrorCode.RATE_LIMITED: 429,
+    ErrorCode.TIMEOUT: 504,
+    ErrorCode.INTERNAL_ERROR: 500,
+}
+
+
+class ToolError(Exception):
+    """Raised by a tool or the core; the REST API and the MCP server turn it into an error answer."""
+
+    code: ErrorCode = ErrorCode.TARGET_ERROR
+
+    def __init__(self, message: str, code: ErrorCode | None = None) -> None:
+        super().__init__(message)
+        if code is not None:
+            self.code = code
+
+
+class AuthExpiredError(ToolError):
+    code = ErrorCode.AUTH_EXPIRED
+
+
+class CaptchaRequiredError(ToolError):
+    code = ErrorCode.CAPTCHA_REQUIRED
+
+
+class MfaRequiredError(ToolError):
+    code = ErrorCode.MFA_REQUIRED
+
+
+class TargetBlockedError(ToolError):
+    code = ErrorCode.TARGET_BLOCKED
+
+
+class NotBuiltError(ToolError):
+    code = ErrorCode.NOT_BUILT

substack_api_mcp/core/helpers.py

@@ -0,0 +1,33 @@
+"""Input and answer helpers the tools share."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+
+
+def page_cursor(cursor: str | None) -> int:
+    """A page-number cursor: None is page 1, anything else must be a positive number we handed out."""
+    if not cursor:
+        return 1
+    if not cursor.isdigit() or int(cursor) < 1:
+        raise ToolError("cursor must be the next_cursor value from the previous call.", ErrorCode.INVALID_INPUT)
+    return int(cursor)
+
+
+def limit(args: dict[str, Any], default: int, maximum: int) -> int:
+    """`limit` from the input, clamped to 1..maximum."""
+    value = int(args.get("limit") or default)
+    return max(1, min(value, maximum))
+
+
+def json_field(value: Any) -> Any:
+    """Apps keep some metadata as JSON strings: the parsed value, None when it does not parse."""
+    if isinstance(value, str) and value[:1] in "{[":
+        try:
+            return json.loads(value)
+        except ValueError:
+            return None
+    return value

substack_api_mcp/core/tools.py

@@ -0,0 +1,106 @@
+"""A tool is one async function, declared with @tool next to its schemas.
+
+The declaration is the only source of a tool's shape: the REST API, the MCP server and the CLI are
+all built from it.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+ToolHandler = Callable[["ToolContext", dict[str, Any]], Awaitable[Any]]
+
+# The REST route under app.API_PREFIX, e.g. "POST /groups/{group}/posts".
+ROUTE = re.compile(r"^(GET|POST|PUT|PATCH|DELETE) (/(?:[a-z0-9-]+|\{[a-z][a-z0-9_]*\}))+$")
+
+# The hosted service asks the owner to approve each call that reaches other people. Here your MCP client
+# asks before each tool call instead, so those sentences are dropped from the published details.
+_HOSTED_CONFIRM = re.compile(
+    r"(,? ?so)?[,;]? ?[Bb]y default you confirm each [a-z]+[;,] ?(and )?you can switch that off for this tool\."
+)
+
+
+def _local_details(details: str | None) -> str | None:
+    if details is None:
+        return None
+    text = _HOSTED_CONFIRM.sub(".", details).replace("..", ".").replace(" through Cotlet", "")
+    return re.sub(r"\s+", " ", text).strip()
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    name: str
+    title: str
+    access: Literal["read", "write"]
+    description: str
+    input_schema: dict[str, Any]
+    handler: ToolHandler
+    route: str | None = None
+    details: str | None = None
+    # Reaches other people (messages, posts, emails): MCP clients should ask before each call.
+    confirm: bool = False
+    credits: int = 25
+    output_schema: dict[str, Any] | None = None
+    example_response: dict[str, Any] | None = None
+    needs_browser: bool = False
+    timeout_s: int | None = None
+    # Read-only check of the input against the app before a call that reaches people.
+    check: ToolHandler | None = None
+
+
+def check_route(name: str, route: str, input_schema: dict[str, Any]) -> None:
+    """A route is a method and a path whose {placeholders} are required arguments of the tool."""
+    if not ROUTE.match(route):
+        raise ValueError(f"{name}: route must look like 'POST /groups/{{group}}/posts', got {route!r}")
+    required = set(input_schema.get("required", []))
+    for param in re.findall(r"\{(\w+)\}", route):
+        if param not in required:
+            raise ValueError(f"{name}: route parameter {{{param}}} must be a required argument")
+
+
+def tool(
+    *,
+    name: str,
+    title: str,
+    access: Literal["read", "write"],
+    description: str,
+    input_schema: dict[str, Any],
+    route: str | None = None,
+    details: str | None = None,
+    confirm: bool = False,
+    credits: int = 25,  # noqa: A002 - kept for parity with the hosted declarations
+    output_schema: dict[str, Any] | None = None,
+    example_response: dict[str, Any] | None = None,
+    needs_browser: bool = False,
+    timeout_s: int | None = None,
+    check: ToolHandler | None = None,
+) -> Callable[[ToolHandler], ToolSpec]:
+    if route is not None:
+        check_route(name, route, input_schema)
+
+    def wrap(handler: ToolHandler) -> ToolSpec:
+        return ToolSpec(
+            name=name,
+            title=title,
+            access=access,
+            description=description,
+            input_schema=input_schema,
+            handler=handler,
+            route=route,
+            details=_local_details(details),
+            confirm=confirm,
+            credits=credits,
+            output_schema=output_schema,
+            example_response=example_response,
+            needs_browser=needs_browser,
+            timeout_s=timeout_s,
+            check=check,
+        )
+
+    return wrap

substack_api_mcp/mcp_context.py

@@ -0,0 +1,126 @@
+"""Prompts and resources of the MCP server: how to start a task, and the tool catalog as context."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+
+import mcp.types as types
+from mcp.server.lowlevel import Server
+from mcp.server.lowlevel.helper_types import ReadResourceContents
+from pydantic import AnyUrl
+
+from substack_api_mcp import app
+from substack_api_mcp.runner import Runner, description, tools
+
+GUIDE_URI = f"{app.SLUG}://guide"
+TOOLS_URI = f"{app.SLUG}://tools"
+
+SAFETY = (
+    "Tools marked write act under the user's name and can reach real people. "
+    "Before calling one, say exactly what it will send or change and wait for the user's OK."
+)
+
+
+def _guide(runner: Runner) -> str:
+    specs = tools(runner.read_only)
+    reads = sum(spec.access == "read" for spec in specs)
+    mode = "read only" if runner.read_only else "read and write"
+    return "\n\n".join(
+        [
+            f"# {app.NAME} tools",
+            f"These tools work in the user's own {app.NAME} account through the session of their Chrome "
+            f"({app.LOGIN_URL}). Mode: {mode}. {len(specs)} tools, {reads} read, {len(specs) - reads} write.",
+            f"Where to start: {app.AGENT_START}",
+            SAFETY,
+            "Lists page with next_cursor: pass it back to get the next page.",
+            f"The full catalog with each tool's access is in {TOOLS_URI}.",
+        ]
+    )
+
+
+def _catalog(runner: Runner) -> str:
+    return json.dumps(
+        [
+            {"name": spec.name, "title": spec.title, "access": spec.access, "description": description(spec)}
+            for spec in tools(runner.read_only)
+        ],
+        ensure_ascii=False,
+        indent=2,
+    )
+
+
+def _prompts() -> list[types.Prompt]:
+    return [
+        types.Prompt(
+            name="getting_started",
+            title=f"Get started with {app.NAME}",
+            description=f"Check the {app.NAME} session and show what the tools can do, without changing anything.",
+        ),
+        types.Prompt(
+            name="plan_task",
+            title=f"Plan a {app.NAME} task",
+            description=f"Turn a goal into {app.NAME} tool calls: reads first, every write shown before it runs.",
+            arguments=[
+                types.PromptArgument(name="task", description=f"What you want done in {app.NAME}", required=True)
+            ],
+        ),
+    ]
+
+
+def _prompt_text(name: str, arguments: dict[str, str] | None) -> str:
+    if name == "getting_started":
+        return (
+            f"Use the {app.NAME} tools. {app.AGENT_START} Tell me which account and data you can see, "
+            f"then list five things I can do with these tools. Read only: change nothing."
+        )
+    if name == "plan_task":
+        task = (arguments or {}).get("task", "").strip()
+        if not task:
+            raise ValueError("plan_task needs a task")
+        return (
+            f"I want to do this in {app.NAME}: {task}\n\n"
+            f"Read {TOOLS_URI}, pick the tools, and run the read tools you need first. {SAFETY}"
+        )
+    raise ValueError(f"unknown prompt: {name}")
+
+
+def register(server: Server, runner: Runner) -> None:
+    @server.list_prompts()
+    async def list_prompts() -> list[types.Prompt]:
+        return _prompts()
+
+    @server.get_prompt()
+    async def get_prompt(name: str, arguments: dict[str, str] | None) -> types.GetPromptResult:
+        text = _prompt_text(name, arguments)
+        return types.GetPromptResult(
+            description=next(prompt.description for prompt in _prompts() if prompt.name == name),
+            messages=[types.PromptMessage(role="user", content=types.TextContent(type="text", text=text))],
+        )
+
+    @server.list_resources()
+    async def list_resources() -> list[types.Resource]:
+        return [
+            types.Resource(
+                uri=AnyUrl(GUIDE_URI),
+                name="guide",
+                title=f"How to use the {app.NAME} tools",
+                description="Where to start, read and write rules, paging.",
+                mimeType="text/markdown",
+            ),
+            types.Resource(
+                uri=AnyUrl(TOOLS_URI),
+                name="tools",
+                title=f"{app.NAME} tool catalog",
+                description="Every tool with its access (read or write) and full description.",
+                mimeType="application/json",
+            ),
+        ]
+
+    @server.read_resource()
+    async def read_resource(uri: AnyUrl) -> Iterable[ReadResourceContents]:
+        if str(uri) == GUIDE_URI:
+            return [ReadResourceContents(content=_guide(runner), mime_type="text/markdown")]
+        if str(uri) == TOOLS_URI:
+            return [ReadResourceContents(content=_catalog(runner), mime_type="application/json")]
+        raise ValueError(f"unknown resource: {uri}")

substack_api_mcp/mcp_server.py

@@ -0,0 +1,67 @@
+"""The MCP server: one MCP tool per tool of the app, over stdio or streamable HTTP."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import mcp.types as types
+from mcp.server.lowlevel import Server
+
+from substack_api_mcp import __version__, app, mcp_context
+from substack_api_mcp.core.errors import ToolError
+from substack_api_mcp.runner import Runner, description, tools
+
+INSTRUCTIONS = (
+    f"{app.NAME} tools working in the user's own {app.NAME} account, through the session of their Chrome. "
+    f"{app.AGENT_START} "
+    "Tools that post, comment, message, invite or change settings act under the user's name and reach real "
+    "people: say what you will send and get the user's OK first. Lists page with next_cursor."
+)
+
+
+def _annotations(spec: Any) -> types.ToolAnnotations:
+    method = (spec.route or "GET").split(" ", 1)[0]
+    return types.ToolAnnotations(
+        title=spec.title,
+        readOnlyHint=spec.access == "read",
+        destructiveHint=spec.access == "write" and (method == "DELETE" or spec.confirm),
+        idempotentHint=method in ("GET", "PUT"),
+        openWorldHint=True,
+    )
+
+
+def build(runner: Runner) -> Server:
+    server: Server = Server(app.SLUG, version=__version__, instructions=INSTRUCTIONS)
+
+    @server.list_tools()
+    async def list_tools() -> list[types.Tool]:
+        return [
+            types.Tool(
+                name=spec.name,
+                title=spec.title,
+                description=description(spec),
+                inputSchema=spec.input_schema,
+                annotations=_annotations(spec),
+            )
+            for spec in tools(runner.read_only)
+        ]
+
+    @server.call_tool(validate_input=False)
+    async def call_tool(name: str, arguments: dict[str, Any]) -> list[types.TextContent]:
+        try:
+            result = await runner.run(name, arguments)
+        except ToolError as exc:
+            raise RuntimeError(f"{exc.code}: {exc}") from None
+        return [types.TextContent(type="text", text=json.dumps(result, ensure_ascii=False, indent=2))]
+
+    mcp_context.register(server, runner)
+    return server
+
+
+async def run_stdio(runner: Runner) -> None:
+    from mcp.server.stdio import stdio_server
+
+    server = build(runner)
+    async with stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())