actionlayer-mcp 0.1.0__tar.gz

actionlayer_mcp-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+env/
+*.egg
+
+# Env / secrets
+.env
+.env.local
+.env.*.local
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Cloudflare Pages / Vercel (legacy)
+.vercel/
+
+# Fly
+.fly/
+
+# Bun + Node (for site/)
+node_modules/
+.next/
+.vite/
+.cache/
+*.tsbuildinfo
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

actionlayer_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: actionlayer-mcp
+Version: 0.1.0
+Summary: MCP server for ActionLayer — give Claude Code and other MCP hosts access to ActionLayer's typed action catalog.
+Project-URL: Homepage, https://action-layer.dev
+Project-URL: Repository, https://github.com/grimjjow/actionlayer
+Author: ActionLayer
+License: MIT
+Keywords: actionlayer,agents,claude,claude-code,mcp,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=0.4.0
+Requires-Dist: httpx>=0.27.0
+Description-Content-Type: text/markdown
+
+# actionlayer-mcp
+
+MCP server for [ActionLayer](https://action-layer.dev) — give Claude Code (and any MCP host) access to ActionLayer's typed action catalog: 30+ actions across Gmail, Calendar, Drive, Slack, Notion, GitHub, Stripe, Linear, Resy, Partiful, USPS, and more.
+
+## Install
+
+Get an API key at https://action-layer.dev/join, then:
+
+```bash
+claude mcp add --scope user actionlayer "uvx" "actionlayer-mcp" \
+  --env ACTIONLAYER_API_KEY="ak_…" \
+  --env ACTIONLAYER_API_URL="https://api.action-layer.dev"
+```
+
+Restart Claude Code and try:
+
+```
+Summarize my 3 most recent unread emails.
+```
+
+## How it works
+
+This package is a thin shim. The actual execution lives on ActionLayer's
+service. The MCP server here exposes one tool — `actionlayer_invoke_action` —
+plus helpers to list the catalog, create jobs, and manage the cyborg loop.
+Auth is via your bearer API key; the server proxies calls and surfaces
+the typed response back to your agent host.
+
+## Usage from other MCP hosts
+
+```bash
+# stdio transport (default)
+actionlayer-mcp
+
+# also works with Cursor, Cody, Codex, etc. — any MCP host
+```
+
+Env vars:
+- `ACTIONLAYER_API_KEY` — required, your bearer key
+- `ACTIONLAYER_API_URL` — defaults to `https://api.action-layer.dev`
+
+## License
+
+MIT

actionlayer_mcp-0.1.0/README.md

@@ -0,0 +1,44 @@
+# actionlayer-mcp
+
+MCP server for [ActionLayer](https://action-layer.dev) — give Claude Code (and any MCP host) access to ActionLayer's typed action catalog: 30+ actions across Gmail, Calendar, Drive, Slack, Notion, GitHub, Stripe, Linear, Resy, Partiful, USPS, and more.
+
+## Install
+
+Get an API key at https://action-layer.dev/join, then:
+
+```bash
+claude mcp add --scope user actionlayer "uvx" "actionlayer-mcp" \
+  --env ACTIONLAYER_API_KEY="ak_…" \
+  --env ACTIONLAYER_API_URL="https://api.action-layer.dev"
+```
+
+Restart Claude Code and try:
+
+```
+Summarize my 3 most recent unread emails.
+```
+
+## How it works
+
+This package is a thin shim. The actual execution lives on ActionLayer's
+service. The MCP server here exposes one tool — `actionlayer_invoke_action` —
+plus helpers to list the catalog, create jobs, and manage the cyborg loop.
+Auth is via your bearer API key; the server proxies calls and surfaces
+the typed response back to your agent host.
+
+## Usage from other MCP hosts
+
+```bash
+# stdio transport (default)
+actionlayer-mcp
+
+# also works with Cursor, Cody, Codex, etc. — any MCP host
+```
+
+Env vars:
+- `ACTIONLAYER_API_KEY` — required, your bearer key
+- `ACTIONLAYER_API_URL` — defaults to `https://api.action-layer.dev`
+
+## License
+
+MIT

actionlayer_mcp-0.1.0/actionlayer_mcp/__init__.py

@@ -0,0 +1,17 @@
+"""ActionLayer MCP server.
+
+A thin Model Context Protocol shim that translates MCP tool calls into
+ActionLayer REST API calls. Runs on the user's machine (or wherever
+their agent host runs); reads ACTIONLAYER_API_KEY + ACTIONLAYER_API_URL
+from the environment.
+
+Distributed via PyPI as `actionlayer-mcp`. The console_scripts entry
+point lets agent hosts run it as `uvx actionlayer-mcp` or
+`pipx run actionlayer-mcp` with no clone needed.
+"""
+
+from actionlayer_mcp.client import ActionLayerClient, ApiError
+
+__version__ = "0.1.0"
+
+__all__ = ["ActionLayerClient", "ApiError", "__version__"]

actionlayer_mcp-0.1.0/actionlayer_mcp/client.py

@@ -0,0 +1,237 @@
+"""HTTP client wrapping the ActionLayer REST API.
+
+A small async wrapper kept separate from server.py so it's reusable
+(future SDK can import it). All network IO lives here; server.py is
+pure protocol translation.
+
+Auth: bearer token from ACTIONLAYER_API_KEY env var. Errors are mapped
+to ApiError with the upstream status + JSON detail string when present.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+from typing import Any, Optional
+
+import httpx
+
+DEFAULT_API_URL = "https://api.action-layer.dev"
+USER_AGENT = "actionlayer-mcp/0.1.0"
+DEFAULT_TIMEOUT = httpx.Timeout(connect=5.0, read=30.0, write=10.0, pool=5.0)
+
+
+class ApiError(RuntimeError):
+    """Raised when the ActionLayer API returns a non-2xx response."""
+
+    def __init__(self, status: int, detail: str):
+        super().__init__(f"ActionLayer API {status}: {detail}")
+        self.status = status
+        self.detail = detail
+
+
+class ActionLayerClient:
+    """Thin async wrapper. One instance per MCP server lifetime."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        api_url: Optional[str] = None,
+    ):
+        self.api_key = api_key or os.environ.get("ACTIONLAYER_API_KEY", "")
+        self.api_url = (
+            api_url
+            or os.environ.get("ACTIONLAYER_API_URL")
+            or DEFAULT_API_URL
+        ).rstrip("/")
+        if not self.api_key:
+            raise RuntimeError(
+                "ACTIONLAYER_API_KEY env var not set. Run "
+                "`actionlayer-mcp configure --api-key ak_...` to set it up."
+            )
+        self._client = httpx.AsyncClient(
+            base_url=self.api_url,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "User-Agent": USER_AGENT,
+            },
+            timeout=DEFAULT_TIMEOUT,
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    # --- Tasks --------------------------------------------------------
+
+    async def start_task(
+        self,
+        *,
+        goal: str,
+        max_budget_usd: Optional[float] = None,
+        webhook_url: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        # An auto-generated idempotency key gives the API a stable replay
+        # surface, but each call still gets a fresh ticket — true
+        # deduplication requires the agent to pass its own key, which is
+        # the right design (only the agent knows whether two same-arg
+        # calls are "retry" or "do it again").
+        key = idempotency_key or f"mcp-{uuid.uuid4()}"
+        body: dict[str, Any] = {"goal": goal}
+        if max_budget_usd is not None:
+            body["max_budget_usd"] = max_budget_usd
+        if webhook_url is not None:
+            body["webhook_url"] = webhook_url
+        return await self._post("/tasks", json=body, headers={"Idempotency-Key": key})
+
+    async def get_task(self, ticket_id: str) -> dict[str, Any]:
+        return await self._get(f"/tasks/{ticket_id}")
+
+    async def reply_task(
+        self,
+        ticket_id: str,
+        *,
+        message: Optional[str] = None,
+        field: Optional[str] = None,
+        value: Optional[str] = None,
+        sensitive: bool = False,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"sensitive": sensitive}
+        if message is not None:
+            body["message"] = message
+        if field is not None:
+            body["field"] = field
+        if value is not None:
+            body["value"] = value
+        return await self._post(f"/tasks/{ticket_id}/reply", json=body)
+
+    async def cancel_task(self, ticket_id: str) -> dict[str, Any]:
+        return await self._post(f"/tasks/{ticket_id}/cancel", json=None)
+
+    # --- Skills -------------------------------------------------------
+
+    async def list_skills(
+        self, *, source_format: Optional[str] = None
+    ) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {}
+        if source_format:
+            params["source_format"] = source_format
+        result = await self._get("/skills", params=params)
+        # /skills returns either a bare list or {"items": [...]} —
+        # accept either to stay forward-compatible.
+        if isinstance(result, dict) and "items" in result:
+            return result["items"]
+        return result  # type: ignore[return-value]
+
+    # --- Actions (P10) ------------------------------------------------
+
+    async def list_actions(
+        self,
+        *,
+        provider: Optional[str] = None,
+        category: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """GET /v1/actions — returns the full catalog response shape
+        ({count, actions, providers, categories}). The MCP server
+        decides what subset to surface to the agent host."""
+        params: dict[str, Any] = {}
+        if provider:
+            params["provider"] = provider
+        if category:
+            params["category"] = category
+        return await self._get("/v1/actions", params=params)
+
+    async def get_action(self, action_id: str) -> dict[str, Any]:
+        """GET /v1/actions/{id} — full ActionDefinition with the
+        input/output schemas."""
+        return await self._get(f"/v1/actions/{action_id}")
+
+    async def invoke_action(
+        self,
+        action_id: str,
+        *,
+        inputs: dict[str, Any],
+        executor: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """POST /v1/actions/{id} — synchronous typed dispatch.
+
+        Returns the ExecutionResult shape: action_id, executor_used,
+        outcome, output, error, blocked_reason, live_view_url,
+        cost_usd, payload. The caller (MCP server) reshapes for the
+        agent host.
+        """
+        body: dict[str, Any] = {"inputs": inputs}
+        if executor:
+            body["executor"] = executor
+        return await self._post(f"/v1/actions/{action_id}", json=body)
+
+    # --- Jobs (P6) ----------------------------------------------------
+
+    async def create_job(
+        self,
+        *,
+        goal: str,
+        budget_usd: Optional[float] = None,
+        deadline: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """POST /v1/jobs — kick off a multi-step planner-driven job.
+
+        `deadline` is ISO 8601 (e.g. '2026-05-15T19:00:00-07:00').
+        Returns the job in 'planning' state; caller polls get_job.
+        """
+        body: dict[str, Any] = {"goal": goal}
+        if budget_usd is not None:
+            body["budget_usd"] = budget_usd
+        if deadline is not None:
+            body["deadline"] = deadline
+        if webhook_url is not None:
+            body["webhook_url"] = webhook_url
+        return await self._post("/v1/jobs", json=body)
+
+    async def get_job(self, job_id: str) -> dict[str, Any]:
+        """GET /v1/jobs/{id} — returns the full Job + items array."""
+        return await self._get(f"/v1/jobs/{job_id}")
+
+    async def cancel_job(self, job_id: str) -> dict[str, Any]:
+        return await self._post(f"/v1/jobs/{job_id}/cancel", json=None)
+
+    async def resume_job(self, job_id: str) -> dict[str, Any]:
+        return await self._post(f"/v1/jobs/{job_id}/resume", json=None)
+
+    # --- Internals ----------------------------------------------------
+
+    async def _get(
+        self, path: str, *, params: Optional[dict[str, Any]] = None
+    ) -> Any:
+        resp = await self._client.get(path, params=params)
+        return _parse(resp)
+
+    async def _post(
+        self,
+        path: str,
+        *,
+        json: Optional[dict[str, Any]],
+        headers: Optional[dict[str, str]] = None,
+    ) -> dict[str, Any]:
+        resp = await self._client.post(path, json=json, headers=headers)
+        return _parse(resp)
+
+
+def _parse(resp: httpx.Response) -> Any:
+    if resp.is_success:
+        if not resp.content:
+            return {}
+        return resp.json()
+    detail: str
+    try:
+        body = resp.json()
+        detail = body.get("detail") if isinstance(body, dict) else str(body)
+        if not isinstance(detail, str):
+            detail = str(detail)
+    except Exception:
+        detail = resp.text or resp.reason_phrase
+    raise ApiError(resp.status_code, detail)
+
+

actionlayer_mcp-0.1.0/actionlayer_mcp/server.py

@@ -0,0 +1,602 @@
+"""ActionLayer MCP server — stdio JSON-RPC, 5 tools.
+
+Tools (locked surface — agents will see these names):
+
+    actionlayer_start_task   create a ticket
+    actionlayer_get_task     read state + recent transcript
+    actionlayer_reply        resume a blocked_on_user ticket
+    actionlayer_cancel       cancel a non-terminal ticket
+    actionlayer_list_skills  list user's skills
+
+When a ticket is blocked_on_user, the latest event payload contains the
+prompt the worker is waiting on. We surface that prompt in
+actionlayer_get_task's response with `next_action` set to the prompt
+string. Agent host then asks the human, who replies via
+actionlayer_reply. If `sensitive=true` is on the prompt, the tool's
+description tells the agent to ask the human directly and never echo
+the value to other tools — the value goes straight from the user into
+actionlayer_reply with sensitive=true.
+
+The server is intentionally small: ~250 lines. Anything more belongs in
+client.py or back in the API.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+from fastmcp import FastMCP
+
+from actionlayer_mcp.client import ActionLayerClient, ApiError
+
+mcp = FastMCP(
+    name="actionlayer",
+    instructions=(
+        "ActionLayer is the execution layer for AI agents — one API to "
+        "call any action, hit a REST API if there is one, drive a "
+        "browser if there isn't, fall back to a human operator if the "
+        "browser gets stuck.\n\n"
+        "TWO USAGE PATTERNS:\n\n"
+        "1. TYPED ACTIONS (preferred). Call actionlayer_list_actions to "
+        "see what's available. Each action has an id like 'gmail.send_email' "
+        "with a typed input_schema. Call actionlayer_invoke_action with "
+        "the id + inputs to dispatch synchronously and get the result "
+        "inline. Examples: send an email, summarize an inbox, find free "
+        "calendar slots, book a Resy table.\n\n"
+        "2. FREE-FORM GOALS (legacy + multi-step). Call "
+        "actionlayer_start_task with a natural-language goal — the "
+        "router picks the flow and the work runs asynchronously. Poll "
+        "actionlayer_get_task. For goals that need multiple actions in "
+        "sequence (e.g. 'find a slot then email the invite'), call "
+        "actionlayer_create_job — the planner decomposes the goal and "
+        "runs the steps with output piping between them.\n\n"
+        "BLOCKED-ON-USER PATTERN. If a ticket or job goes to "
+        "'blocked_on_user', the latest event has a prompt; ask the "
+        "human, then call actionlayer_reply with the answer. If the "
+        "prompt is marked sensitive (2FA, password), DO NOT echo the "
+        "value to any other tool — pass it directly to "
+        "actionlayer_reply with sensitive=true.\n\n"
+        "BLOCKED-ON-OPERATOR PATTERN. If a browser action gets stuck "
+        "(CAPTCHA, novel UI), the ticket goes 'blocked_on_operator' and "
+        "a human teammate picks it up via the Live View URL. You don't "
+        "need to do anything — just report the status to the user."
+    ),
+)
+
+
+# Global client — opened on first use, closed at process exit.
+_client: Optional[ActionLayerClient] = None
+
+
+def _get_client() -> ActionLayerClient:
+    global _client
+    if _client is None:
+        _client = ActionLayerClient()
+    return _client
+
+
+def _summarize_events(events: list[dict[str, Any]], limit: int = 5) -> list[dict[str, Any]]:
+    """Keep responses small — agents don't need the full transcript on every poll."""
+    if not events:
+        return []
+    return [
+        {
+            "type": e.get("type"),
+            "to_state": e.get("to_state"),
+            "created_at": e.get("created_at"),
+            "payload": e.get("payload"),
+        }
+        for e in events[-limit:]
+    ]
+
+
+def _next_action(ticket: dict[str, Any]) -> Optional[dict[str, Any]]:
+    """If the ticket is waiting on the user, surface the prompt + field.
+
+    Returns None when the ticket is not blocked. Otherwise, returns:
+        {
+          "kind": "block_on_user",
+          "prompt": "Two-factor code from your phone?",
+          "field": "sms_code",       (when present)
+          "sensitive": true|false,
+        }
+
+    Drives the agent's behavior — the description on actionlayer_reply
+    tells the agent to use field/sensitive verbatim from this object.
+    """
+    if ticket.get("state") != "blocked_on_user":
+        return None
+    events = ticket.get("events") or []
+    block_events = [e for e in events if e.get("type") == "block_on_user"]
+    if not block_events:
+        return {"kind": "block_on_user", "prompt": "Waiting for user input.", "sensitive": False}
+    payload = block_events[-1].get("payload") or {}
+    return {
+        "kind": "block_on_user",
+        "prompt": payload.get("prompt", "Waiting for user input."),
+        "field": payload.get("field"),
+        "sensitive": bool(payload.get("sensitive", False)),
+    }
+
+
+# --- Tools ------------------------------------------------------------
+
+
+@mcp.tool()
+async def actionlayer_start_task(
+    goal: str,
+    max_budget_usd: Optional[float] = None,
+    webhook_url: Optional[str] = None,
+    idempotency_key: Optional[str] = None,
+) -> dict[str, Any]:
+    """Start a new ActionLayer task.
+
+    Args:
+        goal: A natural-language description of what to do. Examples:
+            "Send Alex at alex@x.com an email to set up a 30-min call"
+            "Book a table for 2 at Liholiho, Friday 7pm"
+            "Hire someone to assemble an IKEA Malm dresser this Saturday"
+        max_budget_usd: Optional spend cap. The flow refuses to commit
+            money beyond this.
+        webhook_url: Optional URL ActionLayer POSTs ticket events to.
+        idempotency_key: Optional caller-supplied retry key. If you call
+            this tool twice with the same key within 24h, you get the
+            same ticket back — safe across timeouts and retries.
+
+    Returns the ticket as {ticket_id, state, ...}. State is initially
+    "queued"; poll actionlayer_get_task to watch it progress.
+    """
+    client = _get_client()
+    try:
+        ticket = await client.start_task(
+            goal=goal,
+            max_budget_usd=max_budget_usd,
+            webhook_url=webhook_url,
+            idempotency_key=idempotency_key,
+        )
+    except ApiError as e:
+        return {"error": str(e), "status": e.status}
+    return {
+        "ticket_id": ticket.get("id"),
+        "state": ticket.get("state"),
+        "goal": ticket.get("goal"),
+        "created_at": ticket.get("created_at"),
+    }
+
+
+@mcp.tool()
+async def actionlayer_get_task(ticket_id: str) -> dict[str, Any]:
+    """Read the current state of a ticket.
+
+    Poll this until `state` is one of: completed, failed, cancelled, or
+    blocked_on_user. If blocked_on_user, the response includes a
+    `next_action` object with the prompt the human needs to answer.
+
+    Returns:
+        ticket_id, state, goal, flow, result (when completed),
+        error (when failed), recent_events (last 5), next_action (when
+        blocked_on_user).
+    """
+    client = _get_client()
+    try:
+        ticket = await client.get_task(ticket_id)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "ticket_id": ticket_id}
+    return {
+        "ticket_id": ticket.get("id"),
+        "state": ticket.get("state"),
+        "goal": ticket.get("goal"),
+        "flow": ticket.get("flow"),
+        "result": ticket.get("result"),
+        "error": ticket.get("error"),
+        "created_at": ticket.get("created_at"),
+        "completed_at": ticket.get("completed_at"),
+        "recent_events": _summarize_events(ticket.get("events") or []),
+        "next_action": _next_action(ticket),
+    }
+
+
+@mcp.tool()
+async def actionlayer_reply(
+    ticket_id: str,
+    message: Optional[str] = None,
+    field: Optional[str] = None,
+    value: Optional[str] = None,
+    sensitive: bool = False,
+) -> dict[str, Any]:
+    """Resume a ticket that's waiting on the user.
+
+    Use this only when actionlayer_get_task returned state
+    "blocked_on_user". The `next_action` object on that response tells
+    you the field name and whether the value is sensitive — pass them
+    through verbatim.
+
+    SENSITIVE VALUES (passwords, 2FA codes, payment info): set
+    `sensitive=true`. Pass the value the user typed directly — DO NOT
+    echo it into other tool calls, agent thoughts, or messages. The API
+    encrypts it at rest, redacts it in logs, and purges it when the
+    ticket terminates.
+
+    Args:
+        ticket_id: The ticket waiting on the user.
+        message: Optional free-form note (non-secret). Lands on the
+            transcript as-is.
+        field: Machine-readable key from next_action.field.
+        value: The user's answer.
+        sensitive: True if value is a secret.
+    """
+    client = _get_client()
+    try:
+        ticket = await client.reply_task(
+            ticket_id,
+            message=message,
+            field=field,
+            value=value,
+            sensitive=sensitive,
+        )
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "ticket_id": ticket_id}
+    return {
+        "ticket_id": ticket.get("id"),
+        "state": ticket.get("state"),
+    }
+
+
+@mcp.tool()
+async def actionlayer_cancel(ticket_id: str) -> dict[str, Any]:
+    """Cancel a non-terminal ticket.
+
+    Idempotent on terminal states — calling cancel on a completed/
+    failed/already-cancelled ticket returns the ticket as-is.
+    """
+    client = _get_client()
+    try:
+        ticket = await client.cancel_task(ticket_id)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "ticket_id": ticket_id}
+    return {
+        "ticket_id": ticket.get("id"),
+        "state": ticket.get("state"),
+    }
+
+
+@mcp.tool()
+async def actionlayer_list_skills(
+    source_format: Optional[str] = None,
+) -> dict[str, Any]:
+    """List skills registered for this user.
+
+    Args:
+        source_format: Optional filter — "agentskills", "hermes",
+            "openclaw", "claude-code". Omit for all.
+
+    Returns {"skills": [{id, name, description, source_format, ...}, ...]}.
+    """
+    client = _get_client()
+    try:
+        skills = await client.list_skills(source_format=source_format)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "skills": []}
+    return {
+        "skills": [
+            {
+                "id": s.get("id"),
+                "name": s.get("name"),
+                "description": s.get("description"),
+                "source_format": s.get("source_format"),
+                "lifecycle": s.get("lifecycle"),
+            }
+            for s in skills
+        ]
+    }
+
+
+# --- Action catalog tools (P10) --------------------------------------
+#
+# These expose the typed action surface. Agents that prefer structured
+# tool-use (vs. natural-language goals) should call these.
+#
+# Note: we surface the catalog as ONE generic tool
+# (actionlayer_invoke_action) parameterized by action_id, rather than
+# emitting 22+ separate MCP tools (gmail_send_email, gmail_summarize_inbox,
+# ...). Build doc §16 calls this out — "one connector covers all 30+
+# actions". The single-tool model matches Composio's surface and keeps
+# the agent host's tool-discovery cost flat as we add actions.
+
+
+@mcp.tool()
+async def actionlayer_list_actions(
+    provider: Optional[str] = None,
+    category: Optional[str] = None,
+) -> dict[str, Any]:
+    """List available actions. Call this first to discover what's in
+    the catalog before invoking one.
+
+    Each entry has:
+        id          — '<provider>.<name>', e.g. 'gmail.send_email'
+        provider    — e.g. 'gmail', 'slack', 'resy'
+        category    — e.g. 'communication', 'scheduling', 'dining'
+        description — what the action does
+        executors   — ['api'] or ['browser']
+        auth        — what the user must connect (OAuth, PAT, etc.)
+        requires_confirmation — whether the action is gated behind a
+                      user-approval step (real-world bookings,
+                      payments)
+
+    Args:
+        provider: Filter by provider slug ('gmail', 'slack', etc.).
+        category: Filter by category ('communication', 'scheduling',
+            etc.).
+
+    Returns {"count": int, "actions": [...], "providers": [...],
+    "categories": [...]}. The providers + categories arrays let the
+    agent build a follow-up filter without a second list call.
+    """
+    client = _get_client()
+    try:
+        return await client.list_actions(provider=provider, category=category)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "count": 0, "actions": []}
+
+
+@mcp.tool()
+async def actionlayer_get_action(action_id: str) -> dict[str, Any]:
+    """Get the full definition of one action — including its
+    input_schema and output_schema (JSON Schema).
+
+    Use this to learn exactly which fields actionlayer_invoke_action
+    needs for a given action. The input_schema tells you which fields
+    are required, their types, and any constraints (enums, min/max).
+
+    Args:
+        action_id: e.g. 'gmail.send_email'.
+
+    Returns the full ActionDefinition object.
+    """
+    client = _get_client()
+    try:
+        return await client.get_action(action_id)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "action_id": action_id}
+
+
+@mcp.tool()
+async def actionlayer_invoke_action(
+    action_id: str,
+    inputs: dict[str, Any],
+    executor: Optional[str] = None,
+) -> dict[str, Any]:
+    """Invoke a single action synchronously with typed inputs.
+
+    The result returns inline (no polling — unlike start_task /
+    create_job). Use this for single-step calls where you already
+    know which action to run.
+
+    Args:
+        action_id: Action id from actionlayer_list_actions
+            (e.g. 'gmail.send_email').
+        inputs: Typed inputs matching the action's input_schema.
+            Required fields and types are visible via
+            actionlayer_get_action. Extra fields are rejected (422).
+        executor: Optional 'api' or 'browser'. When unset, the
+            dispatcher picks the action's preferred kind (usually
+            'api', with 'browser' as fallback for actions that have
+            both).
+
+    Returns:
+        outcome: 'succeeded' | 'blocked' | 'failed'
+        output: typed result matching the action's output_schema
+        error: error message if outcome != succeeded
+        blocked_reason: 'operator' | 'user' | 'auth_expired' |
+            'approval' when outcome == 'blocked'
+        live_view_url: Browserbase Live View URL when the action
+            escalated to operator (open in a browser to take over)
+        cost_usd: best-effort per-call cost
+
+    Common error responses:
+        404 — action_id not in the catalog
+        412 — auth not connected for this action's provider (the
+            human needs to OAuth-connect Google/Slack/etc., or paste
+            a GitHub PAT, before retrying)
+        422 — inputs failed input_schema validation
+    """
+    client = _get_client()
+    try:
+        return await client.invoke_action(
+            action_id, inputs=inputs, executor=executor
+        )
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "action_id": action_id}
+
+
+# --- Job tools (P10) -------------------------------------------------
+#
+# Jobs are for multi-step plans. Single actions stay on
+# actionlayer_invoke_action (sync). Jobs are async — caller polls
+# actionlayer_get_job until terminal.
+
+
+@mcp.tool()
+async def actionlayer_create_job(
+    goal: str,
+    budget_usd: Optional[float] = None,
+    deadline: Optional[str] = None,
+    webhook_url: Optional[str] = None,
+) -> dict[str, Any]:
+    """Create a multi-step job from a natural-language goal.
+
+    The planner (Claude Sonnet 4.6) decomposes the goal into N
+    ordered actions, possibly with output piping between them.
+    Examples:
+        "Find a 30-min slot next week, then email alex@x.com to
+         schedule it"
+        "Summarize my unread emails, then post the count to
+         Slack #general"
+
+    Returns the job in 'planning' state. Poll actionlayer_get_job
+    until state is one of: complete, partial, failed, cancelled,
+    blocked.
+
+    Use actionlayer_invoke_action for single-action goals — it's
+    sync and skips the planner round-trip.
+
+    Args:
+        goal: Natural-language description of the work.
+        budget_usd: Optional total spend cap.
+        deadline: Optional ISO 8601 deadline (e.g.
+            '2026-05-15T19:00:00-07:00'). Planner picks faster
+            actions when deadlines are tight.
+        webhook_url: HTTPS URL POSTed on terminal state. Optional.
+
+    Returns the Job row: {id, goal, state, plan, budget_usd, ...}.
+    """
+    client = _get_client()
+    body: dict[str, Any] = {"goal": goal}
+    if budget_usd is not None:
+        body["budget_usd"] = budget_usd
+    if deadline is not None:
+        body["deadline"] = deadline
+    if webhook_url is not None:
+        body["webhook_url"] = webhook_url
+    try:
+        return await client.create_job(
+            goal=goal,
+            budget_usd=budget_usd,
+            deadline=deadline,
+            webhook_url=webhook_url,
+        )
+    except ApiError as e:
+        return {"error": str(e), "status": e.status}
+
+
+@mcp.tool()
+async def actionlayer_get_job(job_id: str) -> dict[str, Any]:
+    """Read a job's current state + per-step items.
+
+    Terminal states: complete, partial, failed, cancelled. Non-terminal:
+    planning, executing, blocked.
+
+    `items` is the list of plan steps; each has its own state,
+    inputs, result, and (if blocked) the reason.
+
+    Returns the Job row with `items` populated.
+    """
+    client = _get_client()
+    try:
+        return await client.get_job(job_id)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "job_id": job_id}
+
+
+@mcp.tool()
+async def actionlayer_cancel_job(job_id: str) -> dict[str, Any]:
+    """Cancel an in-flight job. Idempotent on terminal states.
+
+    Note: cancellation is cooperative-on-fetch — if a job is
+    mid-step when this is called, the current step finishes before
+    the job transitions to cancelled.
+    """
+    client = _get_client()
+    try:
+        return await client.cancel_job(job_id)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "job_id": job_id}
+
+
+@mcp.tool()
+async def actionlayer_resume_job(job_id: str) -> dict[str, Any]:
+    """Resume a job that's in 'blocked' state.
+
+    Use after the operator or user has resolved the blocker
+    (e.g., the operator finished the CAPTCHA on the Live View URL,
+    or the user replied with a 2FA code via actionlayer_reply).
+    The worker re-evaluates the plan and continues from where it
+    paused.
+
+    Returns 409 if the job isn't in 'blocked' state.
+    """
+    client = _get_client()
+    try:
+        return await client.resume_job(job_id)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "job_id": job_id}
+
+
+# --- Configure subcommand --------------------------------------------
+
+
+def _configure(api_key: str, api_url: Optional[str]) -> None:
+    """Write a basic Claude Desktop / Claude Code MCP config snippet to stdout.
+
+    Doesn't auto-edit the user's config file — printing keeps the action
+    visible and lets the user paste into whichever host they use.
+    """
+    snippet = {
+        "mcpServers": {
+            "actionlayer": {
+                "command": "uvx",
+                "args": ["actionlayer-mcp"],
+                "env": {
+                    "ACTIONLAYER_API_KEY": api_key,
+                    **({"ACTIONLAYER_API_URL": api_url} if api_url else {}),
+                },
+            }
+        }
+    }
+    print("Add this to your MCP host config (Claude Desktop, Cursor, etc.):\n")
+    print(json.dumps(snippet, indent=2))
+    print()
+    home_hint = Path.home() / "Library/Application Support/Claude/claude_desktop_config.json"
+    if sys.platform == "darwin":
+        print(f"On macOS, Claude Desktop config lives at:\n    {home_hint}")
+
+
+# --- Entry point -----------------------------------------------------
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="actionlayer-mcp",
+        description="ActionLayer MCP server (Model Context Protocol).",
+    )
+    sub = parser.add_subparsers(dest="cmd")
+
+    cfg = sub.add_parser(
+        "configure",
+        help="Print MCP host config snippet for a given API key.",
+    )
+    cfg.add_argument("--api-key", required=True)
+    cfg.add_argument("--api-url", default=None)
+
+    args = parser.parse_args()
+
+    if args.cmd == "configure":
+        _configure(args.api_key, args.api_url)
+        return
+
+    # Default: run the MCP server over stdio. The host (Claude Code,
+    # Cursor, etc.) launches us with stdin/stdout connected and speaks
+    # MCP JSON-RPC. fastmcp.run() blocks until the host disconnects.
+    if not os.environ.get("ACTIONLAYER_API_KEY"):
+        print(
+            "ACTIONLAYER_API_KEY env var is not set. Either set it in your "
+            "MCP host config (recommended) or run "
+            "`actionlayer-mcp configure --api-key ak_...` for setup help.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    try:
+        asyncio.run(mcp.run_async())
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

actionlayer_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+# Standalone PyPI package for the ActionLayer MCP server.
+#
+# This pyproject lives SEPARATE from the main repo's pyproject.toml
+# because the main one ships the whole server (SQLAlchemy, Alembic,
+# browser-use, anthropic, ...) which would be ~600MB of deps for
+# teammates who just want to wire ActionLayer into Claude Code.
+#
+# This package contains only the MCP shim (fastmcp + httpx). Source is
+# kept in sync via the publish_mcp.sh script in this directory.
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "actionlayer-mcp"
+version = "0.1.0"
+description = "MCP server for ActionLayer — give Claude Code and other MCP hosts access to ActionLayer's typed action catalog."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "ActionLayer"}]
+keywords = ["mcp", "claude", "claude-code", "actionlayer", "agents", "tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+
+dependencies = [
+    # MCP server framework. Pin minimum to a version with stdio + sse
+    # transports we use.
+    "fastmcp>=0.4.0",
+    # HTTP client used to talk to the ActionLayer REST API. Async
+    # mode in the server, sync mode in scripts.
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://action-layer.dev"
+Repository = "https://github.com/grimjjow/actionlayer"
+
+[project.scripts]
+# The single entry point teammates install. `uvx actionlayer-mcp`
+# starts the stdio MCP server.
+actionlayer-mcp = "actionlayer_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["actionlayer_mcp"]