contractor-foreman-api-mcp 1.0.2__py3-none-any.whl

contractor_foreman_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 contractor_foreman_api_mcp import call
+    projects = call("list_projects")["projects"]
+"""
+
+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 contractor_foreman_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())

contractor_foreman_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 contractor_foreman_api_mcp import __version__, app, mcp_server
+from contractor_foreman_api_mcp.core.errors import HTTP_STATUS, ErrorCode, ToolError
+from contractor_foreman_api_mcp.core.tools import ToolSpec
+from contractor_foreman_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 /projects/archived would win over /projects/{project_id}."""
+    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}/ in group apps, else the first part (projects, invoices ...)."""
+    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

contractor_foreman_api_mcp/app.py

@@ -0,0 +1,41 @@
+"""Everything the server knows about Contractor Foreman outside `contractor_foreman/`: names, domains, cookies.
+
+The rest of the package reads these values and never names the app itself.
+"""
+
+from __future__ import annotations
+
+NAME = "Contractor Foreman"
+SLUG = "contractor-foreman"
+# The command and the prefix of every environment variable (CONTRACTOR_FOREMAN_AUTH_TOKEN, ..._MCP_TOKEN ...).
+CLI = "contractor-foreman-mcp"
+ENV = "CONTRACTOR_FOREMAN"
+# Requests may reach only these hosts and their subdomains. Their cookies are read from Chrome.
+DOMAINS = ("contractorforeman.net",)
+# Present together only while signed in (a signed-out visitor gets the first one too), with the domain a
+# pasted token sets each on.
+COOKIE_DOMAINS = {"_session__240322": "app.contractorforeman.net", "auth_data_session": ".contractorforeman.net"}
+SESSION_COOKIES = tuple(COOKIE_DOMAINS)
+LOGIN_URL = "https://app.contractorforeman.net/sign-in"
+# A final URL with one of these means the app signed the session out.
+LOGGED_OUT_MARKERS = ("/sign-in",)
+# Paths a tool may never change: account, company setup, billing. Reads (GET) stay allowed; every other
+# method to a match is refused before it leaves (core/context.py).
+ACCOUNT_PATHS = (
+    r"^/api/auth/",
+    r"^/api/settings/",
+    r"^/api/subscription",
+    r"^/api/stripe",
+    r"^/api/checkout-link",
+    r"^/api/common/submit-cancellation-request",
+    r"^/api/forgot-password",
+    r"^/api/directory/\d+/dir-reset-password",
+    r"^/api/remove-demo-data",
+    r"^/api/common/replicate-demo-data",
+)
+# A 401 or 403 whose body has one of these asks to sign in again: auth_expired. Contractor Foreman has none.
+RELOGIN_MARKERS: tuple[str, ...] = ()
+# REST routes live under this path, the same as on cotlet.dev.
+API_PREFIX = "/api/v1/contractor-foreman"
+# Prepended to the MCP server's instructions: where an agent starts.
+AGENT_START = "Start with list_projects: its `project_id` values are what most other tools take."

contractor_foreman_api_mcp/cli.py

@@ -0,0 +1,199 @@
+"""<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 getpass
+import ipaddress
+import json
+import os
+import sys
+from typing import Any
+from urllib.parse import urlsplit
+
+from contractor_foreman_api_mcp import __version__, app
+from contractor_foreman_api_mcp import session as sessions
+from contractor_foreman_api_mcp.core.errors import ToolError
+from contractor_foreman_api_mcp.runner import Runner, all_tools, tools
+
+
+def _connect(args: argparse.Namespace) -> None:
+    if args.token:
+        names = "; ".join(f"{name}=..." for name in app.SESSION_COOKIES)
+        token = getpass.getpass(f"Cookies as one line, {names} (input hidden): ")
+        session = sessions.from_token(token)
+    else:
+        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 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 contractor_foreman_api_mcp.contractor_foreman.auth import whoami
+    from contractor_foreman_api_mcp.core.context import ToolContext
+
+    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 = {"auto": "your Chrome", "token": "a pasted token", None: f"{app.ENV}_AUTH_TOKEN"}.get(
+        session.source, 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 1678164)."""
+    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 contractor_foreman_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 contractor_foreman_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.add_argument("--token", action="store_true", help="paste the session cookies by hand instead")
+    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. project_id=123 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()

contractor_foreman_api_mcp/contractor_foreman/auth.py

@@ -0,0 +1,23 @@
+"""Who is signed in: the panel's own app data (POST /api/get-app-data), for "Signed in as ..."."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from contractor_foreman_api_mcp.contractor_foreman.client import api
+from contractor_foreman_api_mcp.core.errors import AuthExpiredError
+
+if TYPE_CHECKING:
+    from contractor_foreman_api_mcp.core.context import ToolContext
+
+
+async def whoami(ctx: ToolContext) -> str | None:
+    """None only when Contractor Foreman says signed out; any other failure raises (detection tries again later)."""
+    try:
+        body = await api(ctx, "get-app-data")
+    except AuthExpiredError:
+        return None
+    me = ((body.get("data") or {}).get("user") or {}).get("data") or {}
+    name = me.get("display_name") or " ".join(p for p in (me.get("first_name"), me.get("last_name")) if p).strip()
+    email = me.get("email")
+    return f"{name} ({email})" if name and email else name or email or None

contractor_foreman_api_mcp/contractor_foreman/client.py

@@ -0,0 +1,30 @@
+"""Contractor Foreman panel requests, recorded 21.10.2026.
+
+The panel (app.contractorforeman.net, React Router) sends its API calls from a web worker as plain
+`fetch` to same-host `/api/...` paths: JSON bodies with `content-type: text/plain;charset=UTF-8`, no auth
+header, only the `_session__240322` cookie. A signed-out call still answers HTTP 200, with
+`{"statusCode": 401, "unauthorize": true}` in the body, so the core cannot see it: `api` turns it into
+`auth_expired`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from contractor_foreman_api_mcp.core.errors import AuthExpiredError
+
+if TYPE_CHECKING:
+    from contractor_foreman_api_mcp.core.context import ToolContext
+
+APP = "https://app.contractorforeman.net"
+_HEADERS = {"content-type": "text/plain;charset=UTF-8", "origin": APP, "referer": f"{APP}/"}
+
+
+async def api(ctx: ToolContext, path: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+    """POST one panel API call and return its JSON. Raises `auth_expired` when the app says signed out."""
+    response = await ctx.call("POST", f"{APP}/api/{path}", data=json.dumps(payload or {}), headers=_HEADERS)
+    body: dict[str, Any] = response.json()
+    if body.get("unauthorize") or body.get("statusCode") == 401:
+        raise AuthExpiredError("The app signed this account out. Reconnect it in the console.")
+    return body

contractor_foreman_api_mcp/contractor_foreman/tools/_change_orders.py

@@ -0,0 +1,111 @@
+"""Change order reads and item writes shared by the change order tools (recorded 21.10.2026).
+
+A change order (`type` co) or a change order request (`type` cor) belongs to a project. Its status is
+`billing_status`, an id from two lists: CHANGE_ORDER_STATUSES for co, REQUEST_STATUSES for cor.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from contractor_foreman_api_mcp.contractor_foreman.tools._finance_common import (
+    CHANGE_ORDER_STATUSES,
+    REQUEST_STATUSES,
+    call,
+    dollars,
+    iso,
+    item_in,
+    item_out,
+    key_of,
+    number,
+    plain,
+)
+from contractor_foreman_api_mcp.core.errors import ErrorCode, ToolError
+
+if TYPE_CHECKING:
+    from contractor_foreman_api_mcp.core.context import ToolContext
+
+STATUS_NAMES = sorted(set(CHANGE_ORDER_STATUSES) | set(REQUEST_STATUSES))
+
+
+def status_of(kind: str, value: Any) -> str | None:
+    return key_of(REQUEST_STATUSES if kind == "cor" else CHANGE_ORDER_STATUSES, value)
+
+
+def status_id(kind: str, status: str) -> int:
+    statuses = REQUEST_STATUSES if kind == "cor" else CHANGE_ORDER_STATUSES
+    if status not in statuses:
+        label = "a change order request" if kind == "cor" else "a change order"
+        raise ToolError(f"Status of {label} is one of: {', '.join(statuses)}.", ErrorCode.INVALID_INPUT)
+    return statuses[status]
+
+
+def row_out(row: dict[str, Any]) -> dict[str, Any]:
+    kind = row.get("type") or "co"
+    return {
+        "change_order_id": str(row.get("change_order_id")),
+        "number": row.get("prefix_company_order_id") or row.get("company_order_id"),
+        "title": row.get("subject"),
+        "kind": "request" if kind == "cor" else "change_order",
+        "status": status_of(kind, row.get("billing_status")),
+        "status_name": row.get("billing_status_name"),
+        "project_id": str(row["project_id"]) if number(row.get("project_id")) else None,
+        "project_name": row.get("project_name"),
+        "customer_name": plain(row.get("customer_name")),
+        "date": iso(row.get("order_date")),
+        "total": dollars(row.get("total")) or 0.0,
+    }
+
+
+async def detail(ctx: ToolContext, change_order_id: str) -> dict[str, Any]:
+    data = (await call(ctx, "change-orders/get-order-detail", {"change_order_id": int(change_order_id)})).get("data")
+    if not data:
+        raise ToolError("No such change order.", ErrorCode.INVALID_INPUT)
+    return data
+
+
+async def sections(ctx: ToolContext, change_order_id: str) -> list[dict[str, Any]]:
+    body = await call(ctx, "change-orders/get-items", {"change_order_id": int(change_order_id), "need_section": 1})
+    return body.get("data") or []
+
+
+def full_out(data: dict[str, Any], parts: list[dict[str, Any]]) -> dict[str, Any]:
+    items = [item_out(item) for part in parts for item in part.get("items") or []]
+    return {
+        **row_out(data),
+        "description": plain(data.get("notes")),
+        "customer_id": str(data["customer_id"]) if number(data.get("customer_id")) else None,
+        "estimate_id": str(data["estimate_id"]) if number(data.get("estimate_id")) else None,
+        "time_delay_days": data.get("day_delay") or None,
+        "items": items,
+        "sections": [{"section_id": str(part.get("section_id")), "name": part.get("section_name")} for part in parts],
+    }
+
+
+async def add_items(ctx: ToolContext, change_order_id: str, items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    parts = await sections(ctx, change_order_id)
+    if not parts:
+        raise ToolError("This change order has no section to add items to.", ErrorCode.TARGET_ERROR)
+    start = sum(len(part.get("items") or []) for part in parts)
+    section_id = parts[0]["section_id"]
+    payload = [item_in(item, section_id, start + i + 1, "order_item_no") for i, item in enumerate(items)]
+    saved = await call(ctx, "change-orders/add-items", {"change_order_id": int(change_order_id), "items": payload})
+    return [item_out(row) for row in saved.get("data") or []]
+
+
+async def customer_email(ctx: ToolContext, data: dict[str, Any]) -> str | None:
+    """The detail call has no customer email; the list row of the same change order has it."""
+    filters = {"status": "", "project": str(data.get("project_id") or "")}
+    for page in range(5):
+        body = await call(
+            ctx,
+            "change-orders/get-list",
+            {"page": page, "limit": 100, "type": data.get("type") or "co", "ignore_filter": 1, "filter": filters},
+        )
+        rows = (body.get("data") or {}).get("changeOrders") or []
+        for row in rows:
+            if str(row.get("change_order_id")) == str(data.get("change_order_id")):
+                return plain(row.get("email"))
+        if len(rows) < 100:
+            break
+    return None