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

partiful_api_mcp/__init__.py

@@ -0,0 +1,28 @@
+"""Self-hosted API and MCP server for one app (see app.py). Personal use only, see LICENSE.
+
+From Python, without a server:
+
+    from partiful_api_mcp import call
+    events = call("list_events")["events"]
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+__version__ = "1.0.2"
+
+
+def call(tool: str, args: dict[str, Any] | None = None, **kwargs: Any) -> Any:
+    """Run one tool with the saved session and return its answer. Raises ToolError on failure."""
+    from partiful_api_mcp.runner import Runner
+
+    async def go() -> Any:
+        runner = Runner()
+        try:
+            return await runner.run(tool, {**(args or {}), **kwargs})
+        finally:
+            await runner.close()
+
+    return asyncio.run(go())

partiful_api_mcp/api.py

@@ -0,0 +1,213 @@
+"""The REST API and the MCP endpoint on one port.
+
+- `GET|POST|PUT|PATCH|DELETE <app.API_PREFIX>/<route>`: each tool at its route, the same paths as the
+  hosted API at cotlet.dev. Path parts and the query string are arguments; a JSON body adds the rest.
+- `POST <app.API_PREFIX>/tools/{name}`: any tool by name, the JSON body is its arguments.
+- `GET <app.API_PREFIX>/tools`: every tool with its schema. OpenAPI at `/docs` and `/openapi.json`.
+- `/mcp`: the MCP server over streamable HTTP.
+
+With <ENV>_MCP_TOKEN set, every request needs `Authorization: Bearer <token>`.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hmac
+import json
+import os
+import re
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+
+from partiful_api_mcp import __version__, app, mcp_server
+from partiful_api_mcp.core.errors import HTTP_STATUS, ErrorCode, ToolError
+from partiful_api_mcp.core.tools import ToolSpec
+from partiful_api_mcp.runner import Runner, description, tools
+
+PREFIX = app.API_PREFIX
+ASGI = Callable[[dict[str, Any], Callable[[], Awaitable[Any]], Callable[[Any], Awaitable[None]]], Awaitable[None]]
+
+
+def _error(code: ErrorCode, message: str) -> JSONResponse:
+    return JSONResponse({"error": code.value, "message": message}, status_code=HTTP_STATUS.get(code, 500))
+
+
+def _typed(value: str, schema: dict[str, Any]) -> Any:
+    kind = schema.get("type")
+    try:
+        if kind == "integer":
+            return int(value)
+        if kind == "number":
+            return float(value)
+    except ValueError:
+        return value
+    if kind == "boolean":
+        return value.lower() in ("1", "true", "yes", "on")
+    if kind == "array":
+        return [_typed(v, schema.get("items") or {}) for v in value.split(",") if v]
+    if kind == "object":
+        with contextlib.suppress(ValueError):
+            return json.loads(value)
+    return value
+
+
+def _route_order(spec: ToolSpec) -> list[int]:
+    """Literal segments before {placeholders}, so /groups/discover wins over /groups/{group}."""
+    path = (spec.route or "").split(" ", 1)[1]
+    return [1 if part.startswith("{") else 0 for part in path.strip("/").split("/")]
+
+
+def _tag(path: str) -> str:
+    """OpenAPI group: the part after /groups/{group}/ (posts, members ...), else the first part."""
+    parts = path.strip("/").split("/")
+    return parts[2] if parts[:2] == ["groups", "{group}"] and len(parts) > 2 else parts[0]
+
+
+def _openapi(spec: ToolSpec, method: str, path: str) -> dict[str, Any]:
+    props: dict[str, Any] = spec.input_schema.get("properties") or {}
+    required = set(spec.input_schema.get("required") or [])
+    in_path = set(re.findall(r"\{(\w+)\}", path))
+    parameters = [
+        {"name": name, "in": "path", "required": True, "schema": props.get(name, {"type": "string"})}
+        for name in in_path
+    ]
+    rest = {k: v for k, v in props.items() if k not in in_path}
+    extra: dict[str, Any] = {}
+    if method == "GET":
+        parameters += [
+            {"name": name, "in": "query", "required": name in required, "schema": schema}
+            for name, schema in rest.items()
+        ]
+    elif rest:
+        body = {"type": "object", "properties": rest, "required": sorted(required - in_path)}
+        extra["requestBody"] = {"required": bool(body["required"]), "content": {"application/json": {"schema": body}}}
+    if spec.example_response:
+        extra["responses"] = {
+            "200": {"description": "OK", "content": {"application/json": {"example": spec.example_response}}}
+        }
+    return {"parameters": parameters, **extra}
+
+
+async def _arguments(request: Request, spec: ToolSpec) -> dict[str, Any]:
+    props: dict[str, Any] = spec.input_schema.get("properties") or {}
+    args: dict[str, Any] = {}
+    if request.method != "GET":
+        raw = await request.body()
+        if raw.strip():
+            try:
+                body = json.loads(raw)
+            except ValueError:
+                raise ToolError("The body must be a JSON object.", ErrorCode.INVALID_INPUT) from None
+            if not isinstance(body, dict):
+                raise ToolError("The body must be a JSON object.", ErrorCode.INVALID_INPUT)
+            args.update(body)
+    for name in request.query_params:
+        values = request.query_params.getlist(name)
+        schema = props.get(name) or {}
+        args[name] = (
+            [_typed(v, schema.get("items") or {}) for v in values]
+            if schema.get("type") == "array" and len(values) > 1
+            else _typed(values[-1], schema)
+        )
+    for name, value in request.path_params.items():
+        args[name] = _typed(value, props.get(name) or {})
+    return args
+
+
+def create_app(runner: Runner) -> ASGI:
+    manager = StreamableHTTPSessionManager(app=mcp_server.build(runner), json_response=True, stateless=True)
+    token = os.environ.get(f"{app.ENV}_MCP_TOKEN", "").strip()
+
+    @contextlib.asynccontextmanager
+    async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+        async with manager.run():
+            yield
+        await runner.close()
+
+    api = FastAPI(
+        title=f"{app.NAME} API (self-hosted)",
+        version=__version__,
+        description=f"Your {app.NAME} account as a REST API, run on your machine with your Chrome's session.",
+        lifespan=lifespan,
+    )
+
+    async def call(spec: ToolSpec, args: dict[str, Any]) -> JSONResponse:
+        try:
+            result = await runner.run(spec.name, args)
+        except ToolError as exc:
+            return _error(exc.code, str(exc))
+        return JSONResponse(result)
+
+    def endpoint(spec: ToolSpec) -> Callable[[Request], Awaitable[JSONResponse]]:
+        async def handle(request: Request) -> JSONResponse:
+            try:
+                args = await _arguments(request, spec)
+            except ToolError as exc:
+                return _error(exc.code, str(exc))
+            return await call(spec, args)
+
+        return handle
+
+    @api.get(f"{PREFIX}/tools", summary="Every tool with its route and input schema")
+    async def list_tools() -> list[dict[str, Any]]:
+        return [
+            {
+                "name": spec.name,
+                "title": spec.title,
+                "access": spec.access,
+                "route": spec.route,
+                "description": description(spec),
+                "input_schema": spec.input_schema,
+                "example_response": spec.example_response,
+            }
+            for spec in tools(runner.read_only)
+        ]
+
+    @api.post(f"{PREFIX}/tools/{{name}}", summary="Call any tool by name; the JSON body is its arguments")
+    async def call_by_name(name: str, request: Request) -> JSONResponse:
+        raw = await request.body()
+        try:
+            args = json.loads(raw) if raw.strip() else {}
+        except ValueError:
+            return _error(ErrorCode.INVALID_INPUT, "The body must be a JSON object.")
+        if not isinstance(args, dict):
+            return _error(ErrorCode.INVALID_INPUT, "The body must be a JSON object.")
+        spec = next((s for s in tools() if s.name == name), None)
+        if spec is None:
+            return _error(ErrorCode.UNKNOWN_TOOL, f"No tool '{name}'. GET {PREFIX}/tools lists them.")
+        return await call(spec, args)
+
+    for spec in sorted(tools(runner.read_only), key=_route_order):
+        method, path = (spec.route or "").split(" ", 1)
+        api.add_api_route(
+            PREFIX + path,
+            endpoint(spec),
+            methods=[method],
+            name=spec.name,
+            operation_id=spec.name,
+            summary=spec.title,
+            description=description(spec),
+            tags=[_tag(path)],
+            openapi_extra=_openapi(spec, method, path),
+        )
+
+    async def asgi(
+        scope: dict[str, Any], receive: Callable[[], Awaitable[Any]], send: Callable[[Any], Awaitable[None]]
+    ) -> None:
+        if scope["type"] == "http" and token:
+            sent = dict(scope.get("headers") or []).get(b"authorization", b"").decode()
+            if not hmac.compare_digest(sent, f"Bearer {token}"):
+                await _error(ErrorCode.AUTH_REQUIRED, f"Send Authorization: Bearer <{app.ENV}_MCP_TOKEN>.")(
+                    scope, receive, send
+                )
+                return
+        if scope["type"] == "http" and (scope["path"] == "/mcp" or scope["path"].startswith("/mcp/")):
+            await manager.handle_request(scope, receive, send)
+            return
+        await api(scope, receive, send)
+
+    return asgi

partiful_api_mcp/app.py

@@ -0,0 +1,37 @@
+"""Everything the server knows about Partiful outside `partiful/`: names, domains and where the session lives.
+
+The rest of the package reads these values and never names the app itself.
+"""
+
+from __future__ import annotations
+
+NAME = "Partiful"
+SLUG = "partiful"
+# The command and the prefix of every environment variable (PARTIFUL_MCP_HOME, PARTIFUL_MCP_TOKEN ...).
+CLI = "partiful-mcp"
+ENV = "PARTIFUL"
+# Requests may reach only these hosts and their subdomains. Their cookies are read from Chrome.
+# securetoken.googleapis.com renews the sign-in token, firestore.googleapis.com holds guest lists and event edits.
+DOMAINS = ("partiful.com", "securetoken.googleapis.com", "firestore.googleapis.com")
+# Present only while signed in.
+SESSION_COOKIES = ("_partiful_session",)
+LOGIN_URL = "https://partiful.com/login"
+# A final URL with one of these means the app signed the session out.
+LOGGED_OUT_MARKERS = ("/login",)
+# The web app keeps the signed-in user (Firebase, with its refresh token) in this origin's IndexedDB.
+# `connect` reads these keys from a tab of the origin; without them the session is not signed in.
+STORAGE_ORIGIN = "https://partiful.com"
+STORAGE_PAGE = "https://partiful.com/events"
+STORAGE_KEYS = ("firebase:authUser:AIzaSyCky6PJ7cHRdBKk5X7gjuWERWaKWBHr4_k:[DEFAULT]",)
+# A 401 or 403 whose body has one of these asks for a fresh sign-in. Partiful has none.
+RELOGIN_MARKERS: tuple[str, ...] = ()
+# Paths of the app's sign-in, sign-out and the user's own record: tools may read them, never write to them.
+ACCOUNT_PATHS = (
+    r"^/api/(login|logout)$",
+    r"^/(sendAuthCode|sendAuthCodeTrusted|getLoginToken|setConsentMetadata)$",
+    r"^/(updateUser|deleteUser|deactivateUser|updateUserReference)$",
+)
+# REST routes live under this path, the same as on cotlet.dev.
+API_PREFIX = "/api/v1/partiful"
+# Prepended to the MCP server's instructions: where an agent starts.
+AGENT_START = "Start with list_events: its `event_id` values are what every other tool takes."

partiful_api_mcp/cli.py

@@ -0,0 +1,192 @@
+"""<cli>: connect your Chrome, then run the REST API and MCP server, or call one tool.
+
+<cli> connect          # read your session of the app from Chrome (remote debugging on)
+<cli> status           # which account the saved session is
+<cli> tools            # every tool, read or write
+<cli> call <tool> k=v  # one tool, arguments as JSON or key=value
+<cli> mcp              # MCP server over stdio, for Claude Code, Claude Desktop, Cursor
+<cli> serve            # REST API + MCP over HTTP on http://127.0.0.1:8787
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import ipaddress
+import json
+import os
+import sys
+from typing import Any
+from urllib.parse import urlsplit
+
+from partiful_api_mcp import __version__, app
+from partiful_api_mcp import session as sessions
+from partiful_api_mcp.core.errors import ToolError
+from partiful_api_mcp.runner import Runner, all_tools, tools
+
+
+def _connect(args: argparse.Namespace) -> None:
+    if not args.cdp:
+        print("Connecting to Chrome. Click Allow if Chrome asks about remote debugging.", file=sys.stderr)
+    session = sessions.from_chrome(args.cdp, args.profile_dir)
+    path = sessions.save(session)
+    who = asyncio.run(_whoami())
+    print(
+        f"Saved {len(session.cookies)} {app.NAME} cookies and {sum(map(len, session.local_storage.values()))} sign-in keys to {path}"
+    )
+    print(f"Signed in to {app.NAME} as {who}" if who else f"Saved, but {app.NAME} did not confirm the session.")
+
+
+async def _whoami() -> str | None:
+    from partiful_api_mcp.core.context import ToolContext
+    from partiful_api_mcp.partiful.auth import whoami
+
+    ctx = ToolContext(session=sessions.load())
+    try:
+        return await whoami(ctx)
+    except ToolError:
+        return None
+    finally:
+        await ctx.close()
+
+
+def _status(_: argparse.Namespace) -> None:
+    session = sessions.load()
+    if not session.signed_in:
+        sys.exit(f"No {app.NAME} session. Run: {app.CLI} connect")
+    who = asyncio.run(_whoami())
+    if not who:
+        sys.exit(f"{app.NAME} signed this session out. Sign in to {app.NAME} in Chrome, then run: {app.CLI} connect")
+    source = "your Chrome" if session.source == "auto" else f"Chrome at {urlsplit(session.source or '').netloc}"
+    print(f"Signed in to {app.NAME} as {who} (session from {source}, {sessions.session_path()})")
+
+
+def _tools(args: argparse.Namespace) -> None:
+    specs = tools(args.read_only)
+    if args.json:
+        rows = [{"name": s.name, "access": s.access, "route": s.route, "input_schema": s.input_schema} for s in specs]
+        print(json.dumps(rows, indent=2))
+        return
+    for spec in specs:
+        print(f"{spec.name:<30} {spec.access:<5} {spec.route:<62} {spec.description}")
+
+
+def _parse_args(tool: str, pairs: list[str]) -> dict[str, Any]:
+    """key=value pairs; a value is JSON unless the tool's schema wants a string (IDs like 148213977)."""
+    if len(pairs) == 1 and pairs[0].lstrip().startswith("{"):
+        return json.loads(pairs[0])
+    spec = all_tools().get(tool)
+    properties = spec.input_schema.get("properties", {}) if spec else {}
+    out: dict[str, Any] = {}
+    for pair in pairs:
+        key, sep, value = pair.partition("=")
+        if not sep:
+            sys.exit(f"Arguments are key=value or one JSON object, got {pair!r}")
+        if properties.get(key, {}).get("type") == "string":
+            out[key] = value
+            continue
+        try:
+            out[key] = json.loads(value)
+        except ValueError:
+            out[key] = value
+    return out
+
+
+def _call(args: argparse.Namespace) -> None:
+    runner = Runner(read_only=args.read_only)
+
+    async def go() -> Any:
+        try:
+            return await runner.run(args.tool, _parse_args(args.tool, args.arguments))
+        finally:
+            await runner.close()
+
+    try:
+        result = asyncio.run(go())
+    except ToolError as exc:
+        sys.exit(f"{exc.code}: {exc}")
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
+def _mcp(args: argparse.Namespace) -> None:
+    from partiful_api_mcp.mcp_server import run_stdio
+
+    asyncio.run(run_stdio(Runner(read_only=args.read_only)))
+
+
+def _serve(args: argparse.Namespace) -> None:
+    import uvicorn
+
+    from partiful_api_mcp.api import create_app
+
+    try:
+        loopback = ipaddress.ip_address(args.host).is_loopback
+    except ValueError:
+        loopback = args.host == "localhost"
+    if not loopback and not os.environ.get(f"{app.ENV}_MCP_TOKEN"):
+        sys.exit(
+            f"Listening beyond this machine needs {app.ENV}_MCP_TOKEN, or anyone on the network can use your {app.NAME} account."
+        )
+    print(
+        f"REST API  http://{args.host}:{args.port}{app.API_PREFIX}   docs http://{args.host}:{args.port}/docs",
+        file=sys.stderr,
+    )
+    print(f"MCP       http://{args.host}:{args.port}/mcp", file=sys.stderr)
+    uvicorn.run(create_app(Runner(read_only=args.read_only)), host=args.host, port=args.port, log_level="warning")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog=app.CLI,
+        description=(__doc__ or "").replace("<cli>", app.CLI),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("connect", help=f"read your {app.NAME} session from Chrome and save it")
+    p.add_argument(
+        "--cdp", help="DevTools address of a Chrome started with --remote-debugging-port, e.g. http://127.0.0.1:9222"
+    )
+    p.add_argument("--profile-dir", help="Chrome profile folder holding DevToolsActivePort, when not the default")
+    p.set_defaults(func=_connect)
+
+    p = sub.add_parser("status", help=f"check the saved session with {app.NAME}")
+    p.set_defaults(func=_status)
+
+    for name, func, text in (
+        ("tools", _tools, "list the tools"),
+        ("mcp", _mcp, "MCP server over stdio"),
+        ("serve", _serve, "REST API and MCP over HTTP"),
+    ):
+        p = sub.add_parser(name, help=text)
+        p.add_argument(
+            "--read-only",
+            action="store_true",
+            default=os.environ.get(f"{app.ENV}_MCP_READ_ONLY") == "1",
+            help="only tools that read",
+        )
+        p.set_defaults(func=func)
+        if name == "tools":
+            p.add_argument("--json", action="store_true", help="names, routes and input schemas as JSON")
+        if name == "serve":
+            p.add_argument("--host", default=os.environ.get(f"{app.ENV}_MCP_HOST", "127.0.0.1"))
+            p.add_argument("--port", type=int, default=int(os.environ.get(f"{app.ENV}_MCP_PORT", "8787")))
+
+    p = sub.add_parser("call", help="run one tool and print its JSON answer")
+    p.add_argument("tool")
+    p.add_argument("arguments", nargs="*", help="key=value pairs or one JSON object, e.g. status=going limit=10")
+    p.add_argument("--read-only", action="store_true")
+    p.set_defaults(func=_call)
+
+    args = parser.parse_args()
+    try:
+        args.func(args)
+    except ToolError as exc:
+        sys.exit(f"{exc.code}: {exc}")
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()

partiful_api_mcp/core/account_guard.py

@@ -0,0 +1,35 @@
+"""Tools never change your account in the app: password, email, sign-in, two-factor, profile.
+
+Checked on every request a tool makes, before it leaves. Reads stay allowed ("who am I" is a profile GET);
+any other method to an account path is refused. The common paths are matched for every app, `app.ACCOUNT_PATHS`
+adds the app's own.
+"""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urlsplit
+
+from partiful_api_mcp import app
+from partiful_api_mcp.core.errors import ErrorCode, ToolError
+
+_READS = frozenset({"GET", "HEAD", "OPTIONS"})
+_COMMON = re.compile(
+    r"passw|two[-_]?factor|2fa|(^|[/_-])(mfa|totp|otp)([/_-]|$)|recovery[-_]?code|"
+    r"(change|update|verify)[-_]?email|email[-_]?(change|update)|"
+    r"(delete|deactivate|close)[-_]?account|account[-_/](delete|deactivate|close)|"
+    r"(^|/)(log[-_]?out|sign[-_]?out|log[-_]?in|sign[-_]?in)([/?]|$)"
+)
+# Case-insensitive: the path is lowercased, the app's patterns keep its own spelling (getLoginToken).
+_APP = [re.compile(pattern, re.IGNORECASE) for pattern in app.ACCOUNT_PATHS]
+
+
+def check_account_write(method: str, url: str) -> None:
+    if method.upper() in _READS:
+        return
+    path = urlsplit(url).path.lower()
+    if _COMMON.search(path) or any(pattern.search(path) for pattern in _APP):
+        raise ToolError(
+            f"This server never changes your {app.NAME} account (password, email, sign-in, profile).",
+            ErrorCode.SCOPE_DENIED,
+        )