assemblix-mcp 0.1.0__tar.gz

assemblix_mcp-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+
+# Tooling / test caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# SDD controller scratch (git-ignored working files)
+.superpowers/

assemblix_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the Assemblix authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

assemblix_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: assemblix-mcp
+Version: 0.1.0
+Summary: MCP server for Assemblix — author, run & inspect workflows over a project API key
+Project-URL: Homepage, https://github.com/nmamizerov/assemblix-aitools
+Project-URL: Repository, https://github.com/nmamizerov/assemblix-aitools
+Project-URL: Issues, https://github.com/nmamizerov/assemblix-aitools/issues
+Author-email: nmamizerov <nmamizerov@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,assemblix,llm,mcp,model-context-protocol,workflows
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=3
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# assemblix-mcp
+
+MCP server for [Assemblix](https://app.assmblx.com). Author, run & inspect your
+project's workflows from any MCP client using a single project API key (`sk_...`).
+`projectId` is never needed — the key defines the project.
+
+Get your `sk_` key from the project's **API keys** page in the Assemblix UI.
+
+## Install
+
+### Hosted (easiest — nothing to install)
+
+```
+claude mcp add --transport http assemblix https://mcp.assmblx.com \
+  --header "Authorization: Bearer sk_your_key"
+```
+
+### Local via uvx (privacy / self-host)
+
+```
+claude mcp add assemblix \
+  --env ASSEMBLIX_API_KEY=sk_your_key \
+  --env ASSEMBLIX_API_URL=https://app.assmblx.com \
+  -- uvx assemblix-mcp
+```
+
+### Claude Desktop / Cursor (JSON config)
+
+```json
+{
+  "mcpServers": {
+    "assemblix": {
+      "command": "uvx",
+      "args": ["assemblix-mcp"],
+      "env": {
+        "ASSEMBLIX_API_KEY": "sk_your_key",
+        "ASSEMBLIX_API_URL": "https://app.assmblx.com"
+      }
+    }
+  }
+}
+```
+
+For the hosted server, use your client's "add custom connector → URL + header" flow.
+
+## Configuration
+
+| Env var | Default | Notes |
+| --- | --- | --- |
+| `ASSEMBLIX_API_URL` | `https://app.assmblx.com` | Base URL of your Assemblix instance |
+| `ASSEMBLIX_API_KEY` | — | Project `sk_` key. Required for stdio; for hosted HTTP the `Authorization` header is used instead |
+| `ASSEMBLIX_MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
+| `ASSEMBLIX_MCP_HOST` / `ASSEMBLIX_MCP_PORT` | `0.0.0.0` / `8000` | HTTP transport bind |
+
+## Tools
+
+**Authoring:** `list_node_types`, `list_workflows`, `get_workflow`, `create_workflow`,
+`update_workflow`, `publish_workflow`
+**Run & inspect:** `run_workflow`, `run_workflow_and_wait`, `get_execution`,
+`list_executions`, `get_execution_detail`, `list_in_flight`
+
+**Resources:** `assemblix://examples/minimal`, `assemblix://examples/branching`
+(example workflow JSON). **Prompt:** `author_workflow` (authoring guide).
+
+Lifecycle: `create_workflow → update_workflow(nodes, edges) → publish_workflow →
+run_workflow`. Runs always execute the **published** snapshot. AGENT nodes need a
+provider credential configured in the Assemblix UI.
+
+All tools operate on the single project your API key is scoped to; `projectId` is
+never a parameter.

assemblix_mcp-0.1.0/README.md

@@ -0,0 +1,70 @@
+# assemblix-mcp
+
+MCP server for [Assemblix](https://app.assmblx.com). Author, run & inspect your
+project's workflows from any MCP client using a single project API key (`sk_...`).
+`projectId` is never needed — the key defines the project.
+
+Get your `sk_` key from the project's **API keys** page in the Assemblix UI.
+
+## Install
+
+### Hosted (easiest — nothing to install)
+
+```
+claude mcp add --transport http assemblix https://mcp.assmblx.com \
+  --header "Authorization: Bearer sk_your_key"
+```
+
+### Local via uvx (privacy / self-host)
+
+```
+claude mcp add assemblix \
+  --env ASSEMBLIX_API_KEY=sk_your_key \
+  --env ASSEMBLIX_API_URL=https://app.assmblx.com \
+  -- uvx assemblix-mcp
+```
+
+### Claude Desktop / Cursor (JSON config)
+
+```json
+{
+  "mcpServers": {
+    "assemblix": {
+      "command": "uvx",
+      "args": ["assemblix-mcp"],
+      "env": {
+        "ASSEMBLIX_API_KEY": "sk_your_key",
+        "ASSEMBLIX_API_URL": "https://app.assmblx.com"
+      }
+    }
+  }
+}
+```
+
+For the hosted server, use your client's "add custom connector → URL + header" flow.
+
+## Configuration
+
+| Env var | Default | Notes |
+| --- | --- | --- |
+| `ASSEMBLIX_API_URL` | `https://app.assmblx.com` | Base URL of your Assemblix instance |
+| `ASSEMBLIX_API_KEY` | — | Project `sk_` key. Required for stdio; for hosted HTTP the `Authorization` header is used instead |
+| `ASSEMBLIX_MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
+| `ASSEMBLIX_MCP_HOST` / `ASSEMBLIX_MCP_PORT` | `0.0.0.0` / `8000` | HTTP transport bind |
+
+## Tools
+
+**Authoring:** `list_node_types`, `list_workflows`, `get_workflow`, `create_workflow`,
+`update_workflow`, `publish_workflow`
+**Run & inspect:** `run_workflow`, `run_workflow_and_wait`, `get_execution`,
+`list_executions`, `get_execution_detail`, `list_in_flight`
+
+**Resources:** `assemblix://examples/minimal`, `assemblix://examples/branching`
+(example workflow JSON). **Prompt:** `author_workflow` (authoring guide).
+
+Lifecycle: `create_workflow → update_workflow(nodes, edges) → publish_workflow →
+run_workflow`. Runs always execute the **published** snapshot. AGENT nodes need a
+provider credential configured in the Assemblix UI.
+
+All tools operate on the single project your API key is scoped to; `projectId` is
+never a parameter.

assemblix_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "assemblix-mcp"
+version = "0.1.0"
+description = "MCP server for Assemblix — author, run & inspect workflows over a project API key"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "nmamizerov", email = "nmamizerov@gmail.com" }]
+keywords = ["assemblix", "mcp", "model-context-protocol", "workflows", "llm", "ai-agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "fastmcp>=3",
+    "httpx>=0.27",
+    "pydantic>=2",
+]
+
+[project.urls]
+Homepage = "https://github.com/nmamizerov/assemblix-aitools"
+Repository = "https://github.com/nmamizerov/assemblix-aitools"
+Issues = "https://github.com/nmamizerov/assemblix-aitools/issues"
+
+[project.scripts]
+assemblix-mcp = "assemblix_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/assemblix_mcp"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["uv.lock"]
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "respx>=0.21"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

assemblix_mcp-0.1.0/src/assemblix_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Assemblix MCP server package."""
+
+__version__ = "0.1.0"

assemblix_mcp-0.1.0/src/assemblix_mcp/client.py

@@ -0,0 +1,192 @@
+"""Thin async HTTP client over the Assemblix REST API.
+
+Wire contract: query params are snake_case; request bodies are camelCase;
+responses are camelCase. ``project_id`` is injected only where the endpoint
+expects it (workflows list query + create body). Id-addressed and key-scoped
+endpoints do not need it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class AssemblixAPIError(Exception):
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"{status_code}: {detail}")
+
+
+class AssemblixClient:
+    def __init__(self, base_url: str, api_key: str, project_id: str) -> None:
+        self._base = base_url.rstrip("/")
+        self._project_id = project_id
+        self._headers = {"Authorization": f"Bearer {api_key}"}
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict | None = None,
+        json: dict | None = None,
+    ) -> Any:
+        async with httpx.AsyncClient(base_url=self._base, headers=self._headers) as http:
+            resp = await http.request(method, path, params=params, json=json)
+        if resp.status_code >= 400:
+            raise AssemblixAPIError(resp.status_code, _extract_detail(resp))
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+    # --- nodes ---
+    async def list_node_types(self) -> Any:
+        return await self._request("GET", "/api/nodes")
+
+    # --- workflows ---
+    async def list_workflows(
+        self,
+        is_active: bool | None = None,
+        is_published: bool | None = None,
+        is_template: bool | None = None,
+    ) -> Any:
+        params = _clean(
+            {
+                "project_id": self._project_id,
+                "is_active": is_active,
+                "is_published": is_published,
+                "is_template": is_template,
+            }
+        )
+        return await self._request("GET", "/api/workflows/", params=params)
+
+    async def get_workflow(self, workflow_id: str) -> Any:
+        return await self._request("GET", f"/api/workflows/{workflow_id}")
+
+    async def create_workflow(
+        self,
+        name: str | None = None,
+        description: str | None = None,
+        nodes: list | None = None,
+        edges: list | None = None,
+        state: list | None = None,
+    ) -> Any:
+        body = _clean(
+            {
+                "projectId": self._project_id,
+                "name": name,
+                "description": description,
+                "nodes": nodes,
+                "edges": edges,
+                "state": state,
+            }
+        )
+        return await self._request("POST", "/api/workflows/", json=body)
+
+    async def update_workflow(
+        self,
+        workflow_id: str,
+        name: str | None = None,
+        description: str | None = None,
+        nodes: list | None = None,
+        edges: list | None = None,
+        state: list | None = None,
+    ) -> Any:
+        body = _clean(
+            {
+                "name": name,
+                "description": description,
+                "nodes": nodes,
+                "edges": edges,
+                "state": state,
+            }
+        )
+        return await self._request("PATCH", f"/api/workflows/{workflow_id}", json=body)
+
+    async def publish_workflow(self, workflow_id: str) -> Any:
+        return await self._request("POST", f"/api/workflows/{workflow_id}/publish")
+
+    # --- execution ---
+    async def execute_workflow(
+        self,
+        workflow_id: str,
+        input: dict,
+        task: bool = False,
+        state: dict | None = None,
+        project_state: dict | None = None,
+        client_id: str | None = None,
+        metadata: dict | None = None,
+    ) -> Any:
+        body = _clean(
+            {
+                "input": input,
+                "task": task,
+                "state": state,
+                "projectState": project_state,
+                "clientId": client_id,
+                "metadata": metadata,
+            }
+        )
+        return await self._request(
+            "POST", f"/api/workflows/{workflow_id}/execute", json=body
+        )
+
+    async def get_task_result(self, execution_id: str) -> Any:
+        return await self._request("GET", f"/api/executions/task/{execution_id}")
+
+    async def list_executions(
+        self,
+        workflow_id: str | None = None,
+        status: str | None = None,
+        date_from: str | None = None,
+        date_to: str | None = None,
+        page: int = 1,
+        limit: int = 50,
+    ) -> Any:
+        params = _clean(
+            {
+                "project_id": self._project_id,
+                "workflow_id": workflow_id,
+                "status": status,
+                "date_from": date_from,
+                "date_to": date_to,
+                "page": page,
+                "limit": limit,
+            }
+        )
+        return await self._request("GET", "/api/executions/", params=params)
+
+    async def get_execution_detail(self, execution_id: str) -> Any:
+        return await self._request("GET", f"/api/executions/{execution_id}")
+
+    async def list_in_flight(self) -> Any:
+        return await self._request("GET", "/api/executions/in-flight")
+
+
+async def fetch_project_id(base_url: str, api_key: str) -> str:
+    """Resolve the key's project via the whoami endpoint."""
+    async with httpx.AsyncClient(
+        base_url=base_url.rstrip("/"),
+        headers={"Authorization": f"Bearer {api_key}"},
+    ) as http:
+        resp = await http.get("/api/api-keys/whoami")
+    if resp.status_code >= 400:
+        raise AssemblixAPIError(resp.status_code, _extract_detail(resp))
+    return str(resp.json()["projectId"])
+
+
+def _clean(d: dict) -> dict:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _extract_detail(resp: httpx.Response) -> str:
+    try:
+        body = resp.json()
+        if isinstance(body, dict) and "detail" in body:
+            return str(body["detail"])
+    except Exception:
+        pass
+    return resp.text or resp.reason_phrase

assemblix_mcp-0.1.0/src/assemblix_mcp/config.py

@@ -0,0 +1,38 @@
+"""Configuration and per-request API key resolution."""
+
+from __future__ import annotations
+
+import os
+
+from pydantic import BaseModel
+
+
+class Settings(BaseModel):
+    api_url: str
+    api_key: str | None
+    transport: str
+    host: str
+    port: int
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        return cls(
+            api_url=os.environ.get("ASSEMBLIX_API_URL", "https://app.assmblx.com"),
+            api_key=os.environ.get("ASSEMBLIX_API_KEY"),
+            transport=os.environ.get("ASSEMBLIX_MCP_TRANSPORT", "stdio"),
+            host=os.environ.get("ASSEMBLIX_MCP_HOST", "0.0.0.0"),
+            port=int(os.environ.get("ASSEMBLIX_MCP_PORT", "8000")),
+        )
+
+
+def resolve_api_key(settings: Settings, header_value: str | None) -> str:
+    """Return the bearer token, preferring an incoming Authorization header."""
+    if header_value:
+        token = header_value.removeprefix("Bearer ").strip()
+        if token:
+            return token
+    if settings.api_key:
+        return settings.api_key
+    raise ValueError(
+        "No API key: set ASSEMBLIX_API_KEY or send an Authorization: Bearer header."
+    )

assemblix_mcp-0.1.0/src/assemblix_mcp/resources/__init__.py

@@ -0,0 +1,50 @@
+"""Bundled example workflows + authoring prompt registered on the MCP server."""
+
+from __future__ import annotations
+
+from importlib import resources
+
+from fastmcp import FastMCP
+
+_EXAMPLES = resources.files("assemblix_mcp.resources") / "examples"
+
+
+def _load(name: str) -> str:
+    return (_EXAMPLES / name).read_text(encoding="utf-8")
+
+
+def register_resources(mcp: FastMCP) -> None:
+    @mcp.resource("assemblix://examples/minimal")
+    def minimal_example() -> str:
+        """A runnable START -> AGENT -> END workflow (create -> update ->
+        publish -> run). Shows the START node shape, which is not in
+        list_node_types."""
+        return _load("minimal.json")
+
+    @mcp.resource("assemblix://examples/branching")
+    def branching_example() -> str:
+        """A START -> CONDITION -> two AGENT branches -> END workflow. Shows how
+        condition branch edges use sourceHandle 'source_<conditionId>_<index>'."""
+        return _load("branching.json")
+
+    @mcp.prompt
+    def author_workflow() -> str:
+        """Guidance for authoring an Assemblix workflow via these tools."""
+        return (
+            "To author and run an Assemblix workflow:\n"
+            "1. Call list_node_types to see AGENT/CONDITION/HTTP_REQUEST/"
+            "SET_VARIABLE/DELAY/END config schemas. START is implicit and NOT "
+            "listed — copy its shape from the example resources.\n"
+            "2. Read assemblix://examples/minimal (and /branching) for the exact "
+            "node/edge JSON shape: node = {id, type, position:{x,y}, config}, "
+            "edge = {id, source, target, sourceHandle?}. CONDITION branch edges "
+            "use sourceHandle 'source_<conditionNodeId>_<index>'.\n"
+            "3. create_workflow -> update_workflow(nodes, edges, state) -> "
+            "publish_workflow. Runs always execute the PUBLISHED snapshot, so "
+            "publish after every change you want to run.\n"
+            "4. run_workflow (async, poll get_execution) or run_workflow_and_wait. "
+            "input usually is {\"message\": \"...\"}.\n"
+            "5. Inspect with get_execution_detail / list_executions. AGENT nodes "
+            "need a provider credential configured in the Assemblix UI; if missing, "
+            "the run fails with a clear error."
+        )

assemblix_mcp-0.1.0/src/assemblix_mcp/resources/examples/branching.json

@@ -0,0 +1,63 @@
+{
+  "name": "Branching agent",
+  "description": "START -> CONDITION -> two AGENT branches -> END. The condition routes by index; branch edges use sourceHandle source_<conditionId>_<index>.",
+  "nodes": [
+    {
+      "id": "start-1",
+      "type": "start",
+      "position": { "x": 0, "y": 0 },
+      "config": { "firstPhrase": null, "acceptVoice": false }
+    },
+    {
+      "id": "cond-1",
+      "type": "condition",
+      "position": { "x": 320, "y": 0 },
+      "config": {
+        "conditions": [
+          { "name": "mentions bug", "expression": "input.message.contains('bug')" },
+          { "name": "default", "expression": "true" }
+        ]
+      }
+    },
+    {
+      "id": "agent-bug",
+      "type": "agent",
+      "position": { "x": 640, "y": -120 },
+      "config": {
+        "name": "Bug helper",
+        "provider": "openai",
+        "model": "gpt-4o-mini",
+        "instructions": [
+          { "role": "system", "content": "The user reported a bug. Ask one clarifying question." }
+        ]
+      }
+    },
+    {
+      "id": "agent-default",
+      "type": "agent",
+      "position": { "x": 640, "y": 120 },
+      "config": {
+        "name": "General helper",
+        "provider": "openai",
+        "model": "gpt-4o-mini",
+        "instructions": [
+          { "role": "system", "content": "Answer the user's message helpfully." }
+        ]
+      }
+    },
+    {
+      "id": "end-1",
+      "type": "end",
+      "position": { "x": 960, "y": 0 },
+      "config": { "name": "Done", "outputMode": "last_agent" }
+    }
+  ],
+  "edges": [
+    { "id": "e1", "source": "start-1", "target": "cond-1" },
+    { "id": "e2", "source": "cond-1", "target": "agent-bug", "sourceHandle": "source_cond-1_0" },
+    { "id": "e3", "source": "cond-1", "target": "agent-default", "sourceHandle": "source_cond-1_1" },
+    { "id": "e4", "source": "agent-bug", "target": "end-1" },
+    { "id": "e5", "source": "agent-default", "target": "end-1" }
+  ],
+  "state": []
+}

assemblix_mcp-0.1.0/src/assemblix_mcp/resources/examples/minimal.json

@@ -0,0 +1,36 @@
+{
+  "name": "Minimal chat agent",
+  "description": "START -> AGENT -> END. Replies to input.message with an LLM.",
+  "nodes": [
+    {
+      "id": "start-1",
+      "type": "start",
+      "position": { "x": 0, "y": 0 },
+      "config": { "firstPhrase": null, "acceptVoice": false }
+    },
+    {
+      "id": "agent-1",
+      "type": "agent",
+      "position": { "x": 320, "y": 0 },
+      "config": {
+        "name": "Assistant",
+        "provider": "openai",
+        "model": "gpt-4o-mini",
+        "instructions": [
+          { "role": "system", "content": "You are a helpful assistant. Answer the user's message." }
+        ]
+      }
+    },
+    {
+      "id": "end-1",
+      "type": "end",
+      "position": { "x": 640, "y": 0 },
+      "config": { "name": "Done", "outputMode": "last_agent" }
+    }
+  ],
+  "edges": [
+    { "id": "e1", "source": "start-1", "target": "agent-1" },
+    { "id": "e2", "source": "agent-1", "target": "end-1" }
+  ],
+  "state": []
+}

assemblix_mcp-0.1.0/src/assemblix_mcp/server.py

@@ -0,0 +1,42 @@
+"""FastMCP server assembly and entry point."""
+
+from __future__ import annotations
+
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import get_http_headers
+
+from assemblix_mcp.client import AssemblixClient, fetch_project_id
+from assemblix_mcp.config import Settings, resolve_api_key
+from assemblix_mcp.resources import register_resources
+from assemblix_mcp.tools.executions import register_execution_tools
+from assemblix_mcp.tools.workflows import register_workflow_tools
+
+
+def build_server(settings: Settings) -> FastMCP:
+    mcp = FastMCP("assemblix")
+
+    async def get_client() -> AssemblixClient:
+        headers = get_http_headers(include={"authorization"}) or {}
+        api_key = resolve_api_key(settings, headers.get("authorization"))
+        project_id = await fetch_project_id(settings.api_url, api_key)
+        return AssemblixClient(
+            base_url=settings.api_url, api_key=api_key, project_id=project_id
+        )
+
+    register_workflow_tools(mcp, get_client)
+    register_execution_tools(mcp, get_client)
+    register_resources(mcp)
+    return mcp
+
+
+def main() -> None:
+    settings = Settings.from_env()
+    mcp = build_server(settings)
+    if settings.transport == "http":
+        mcp.run(transport="http", host=settings.host, port=settings.port)
+    else:
+        mcp.run()
+
+
+if __name__ == "__main__":
+    main()

assemblix_mcp-0.1.0/src/assemblix_mcp/tools/__init__.py

@@ -0,0 +1 @@
+"""MCP tool registration."""

assemblix_mcp-0.1.0/src/assemblix_mcp/tools/executions.py

@@ -0,0 +1,115 @@
+"""Run & inspect tools. project_id is implicit in the API key."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+from fastmcp import FastMCP
+
+from assemblix_mcp.tools.workflows import GetClient
+
+_PENDING = {"running", "queued", "pending"}
+
+
+def _is_terminal(payload: Any) -> bool:
+    status = str((payload or {}).get("status", "")).lower()
+    return status not in _PENDING
+
+
+def register_execution_tools(mcp: FastMCP, get_client: GetClient) -> None:
+    @mcp.tool
+    async def run_workflow(
+        workflow_id: str,
+        input: dict,
+        state: dict | None = None,
+        project_state: dict | None = None,
+        client_id: str | None = None,
+        metadata: dict | None = None,
+    ) -> Any:
+        """Start the published workflow asynchronously. Returns immediately with
+        an executionId; poll it with get_execution. `input` typically holds a
+        'message' field. Publish the workflow first."""
+        client = await get_client()
+        return await client.execute_workflow(
+            workflow_id,
+            input=input,
+            task=True,
+            state=state,
+            project_state=project_state,
+            client_id=client_id,
+            metadata=metadata,
+        )
+
+    @mcp.tool
+    async def run_workflow_and_wait(
+        workflow_id: str,
+        input: dict,
+        state: dict | None = None,
+        project_state: dict | None = None,
+        timeout_seconds: float = 120.0,
+        poll_interval: float = 2.0,
+    ) -> Any:
+        """Start the published workflow and poll until it finishes or the timeout
+        elapses. Returns the final result — including an error payload on failure
+        (does not raise). On timeout returns the last status with timedOut=true."""
+        client = await get_client()
+        started = await client.execute_workflow(
+            workflow_id,
+            input=input,
+            task=True,
+            state=state,
+            project_state=project_state,
+        )
+        if _is_terminal(started):
+            return started
+        execution_id = str(started["executionId"])
+        deadline = time.monotonic() + timeout_seconds
+        while time.monotonic() < deadline:
+            await asyncio.sleep(poll_interval)
+            result = await client.get_task_result(execution_id)
+            if _is_terminal(result):
+                return result
+        return {"executionId": execution_id, "status": "running", "timedOut": True}
+
+    @mcp.tool
+    async def get_execution(execution_id: str) -> Any:
+        """Get the status/result of one run (poll after run_workflow). Returns
+        status 'running' while in progress, else the completed or error payload."""
+        client = await get_client()
+        return await client.get_task_result(execution_id)
+
+    @mcp.tool
+    async def list_executions(
+        workflow_id: str | None = None,
+        status: str | None = None,
+        date_from: str | None = None,
+        date_to: str | None = None,
+        page: int = 1,
+        limit: int = 50,
+    ) -> Any:
+        """List the project's run history (paginated). status is one of QUEUED,
+        RUNNING, COMPLETED, ERROR, FAILED. Dates are ISO 8601."""
+        client = await get_client()
+        return await client.list_executions(
+            workflow_id=workflow_id,
+            status=status,
+            date_from=date_from,
+            date_to=date_to,
+            page=page,
+            limit=limit,
+        )
+
+    @mcp.tool
+    async def get_execution_detail(execution_id: str) -> Any:
+        """Get step-level detail for a run (node inputs/outputs, errors, timing) —
+        use this to diagnose why a run failed."""
+        client = await get_client()
+        return await client.get_execution_detail(execution_id)
+
+    @mcp.tool
+    async def list_in_flight() -> list:
+        """List runs currently QUEUED or RUNNING in the project."""
+        client = await get_client()
+        return await client.list_in_flight()

assemblix_mcp-0.1.0/src/assemblix_mcp/tools/workflows.py

@@ -0,0 +1,76 @@
+"""Workflow authoring tools. project_id is implicit in the API key."""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable
+
+from fastmcp import FastMCP
+
+from assemblix_mcp.client import AssemblixClient
+
+GetClient = Callable[[], Awaitable[AssemblixClient]]
+
+
+def register_workflow_tools(mcp: FastMCP, get_client: GetClient) -> None:
+    @mcp.tool
+    async def list_node_types() -> list:
+        """List available node types with their config schemas, for building a
+        workflow graph. Note: START is implicit and not listed here — see the
+        example workflows (resources) for its shape and the create->update->
+        publish->run lifecycle."""
+        client = await get_client()
+        return await client.list_node_types()
+
+    @mcp.tool
+    async def list_workflows(
+        is_active: bool | None = None,
+        is_published: bool | None = None,
+        is_template: bool | None = None,
+    ) -> list:
+        """List the project's workflows (optionally filtered by status)."""
+        client = await get_client()
+        return await client.list_workflows(
+            is_active=is_active, is_published=is_published, is_template=is_template
+        )
+
+    @mcp.tool
+    async def get_workflow(workflow_id: str) -> Any:
+        """Get a workflow by id, including its nodes, edges and state."""
+        client = await get_client()
+        return await client.get_workflow(workflow_id)
+
+    @mcp.tool
+    async def create_workflow(name: str, description: str | None = None) -> Any:
+        """Create a new draft workflow in the project. Add nodes/edges with
+        update_workflow, then publish_workflow before running."""
+        client = await get_client()
+        return await client.create_workflow(name=name, description=description)
+
+    @mcp.tool
+    async def update_workflow(
+        workflow_id: str,
+        name: str | None = None,
+        description: str | None = None,
+        nodes: list | None = None,
+        edges: list | None = None,
+        state: list | None = None,
+    ) -> Any:
+        """Replace a draft workflow's fields. nodes/edges/state fully replace the
+        existing graph when provided; omit to leave unchanged."""
+        client = await get_client()
+        return await client.update_workflow(
+            workflow_id,
+            name=name,
+            description=description,
+            nodes=nodes,
+            edges=edges,
+            state=state,
+        )
+
+    @mcp.tool
+    async def publish_workflow(workflow_id: str) -> Any:
+        """Publish the draft as the runnable snapshot. run_workflow always
+        executes the published version, so publish after every edit you want to
+        run."""
+        client = await get_client()
+        return await client.publish_workflow(workflow_id)

assemblix_mcp-0.1.0/tests/test_client_executions.py

@@ -0,0 +1,49 @@
+import httpx
+import respx
+
+from assemblix_mcp.client import AssemblixClient
+
+
+def _client():
+    return AssemblixClient(base_url="http://api.test", api_key="sk_k", project_id="p1")
+
+
+@respx.mock
+async def test_execute_workflow_task_mode_body():
+    route = respx.post("http://api.test/api/workflows/w1/execute").mock(
+        return_value=httpx.Response(200, json={"executionId": "e1", "status": "running"})
+    )
+    result = await _client().execute_workflow("w1", input={"message": "hi"}, task=True)
+    assert result["executionId"] == "e1"
+    body = route.calls.last.request.content
+    assert b'"input"' in body
+    assert b'"task"' in body
+    assert b"project_id" not in body and b"projectId" not in body
+
+
+@respx.mock
+async def test_get_task_result():
+    respx.get("http://api.test/api/executions/task/e1").mock(
+        return_value=httpx.Response(200, json={"executionId": "e1", "status": "completed"})
+    )
+    result = await _client().get_task_result("e1")
+    assert result["status"] == "completed"
+
+
+@respx.mock
+async def test_list_executions_snake_query():
+    route = respx.get("http://api.test/api/executions/").mock(
+        return_value=httpx.Response(200, json={"data": [], "total": 0, "page": 1, "limit": 50})
+    )
+    await _client().list_executions(workflow_id="w1")
+    params = route.calls.last.request.url.params
+    assert params["project_id"] == "p1"
+    assert params["workflow_id"] == "w1"
+
+
+@respx.mock
+async def test_list_in_flight():
+    respx.get("http://api.test/api/executions/in-flight").mock(
+        return_value=httpx.Response(200, json=[{"id": "e1", "status": "RUNNING"}])
+    )
+    assert await _client().list_in_flight() == [{"id": "e1", "status": "RUNNING"}]

assemblix_mcp-0.1.0/tests/test_client_workflows.py

@@ -0,0 +1,54 @@
+import httpx
+import respx
+
+from assemblix_mcp.client import AssemblixAPIError, AssemblixClient, fetch_project_id
+
+
+def _client():
+    return AssemblixClient(base_url="http://api.test", api_key="sk_k", project_id="p1")
+
+
+@respx.mock
+async def test_list_workflows_sends_bearer_and_snake_project():
+    route = respx.get("http://api.test/api/workflows/").mock(
+        return_value=httpx.Response(200, json=[{"id": "w1"}])
+    )
+    result = await _client().list_workflows(is_active=True)
+    assert result == [{"id": "w1"}]
+    sent = route.calls.last.request
+    assert sent.headers["authorization"] == "Bearer sk_k"
+    assert sent.url.params["project_id"] == "p1"
+    assert sent.url.params["is_active"] == "true"
+
+
+@respx.mock
+async def test_create_workflow_posts_camel_body():
+    route = respx.post("http://api.test/api/workflows/").mock(
+        return_value=httpx.Response(201, json={"id": "w2", "name": "New"})
+    )
+    result = await _client().create_workflow(name="New")
+    assert result["id"] == "w2"
+    body = route.calls.last.request.content
+    assert b'"projectId"' in body
+    assert b'"name"' in body
+
+
+@respx.mock
+async def test_error_response_raises_with_detail():
+    respx.get("http://api.test/api/workflows/w9").mock(
+        return_value=httpx.Response(403, json={"detail": "nope"})
+    )
+    try:
+        await _client().get_workflow("w9")
+        assert False, "expected error"
+    except AssemblixAPIError as e:
+        assert e.status_code == 403
+        assert "nope" in e.detail
+
+
+@respx.mock
+async def test_fetch_project_id():
+    respx.get("http://api.test/api/api-keys/whoami").mock(
+        return_value=httpx.Response(200, json={"projectId": "p-42"})
+    )
+    assert await fetch_project_id("http://api.test", "sk_k") == "p-42"

assemblix_mcp-0.1.0/tests/test_config.py

@@ -0,0 +1,22 @@
+import pytest
+
+from assemblix_mcp.config import Settings, resolve_api_key
+
+
+def _settings(**over):
+    base = dict(api_url="http://x", api_key="sk_env", transport="stdio", host="h", port=1)
+    base.update(over)
+    return Settings(**base)
+
+
+def test_resolve_prefers_header():
+    assert resolve_api_key(_settings(), "Bearer sk_header") == "sk_header"
+
+
+def test_resolve_falls_back_to_env():
+    assert resolve_api_key(_settings(), None) == "sk_env"
+
+
+def test_resolve_raises_without_any_key():
+    with pytest.raises(ValueError):
+        resolve_api_key(_settings(api_key=None), None)

assemblix_mcp-0.1.0/tests/test_execution_tools.py

@@ -0,0 +1,81 @@
+import httpx
+import respx
+from fastmcp import Client as MCPClient
+from fastmcp import FastMCP
+
+from assemblix_mcp.client import AssemblixClient
+from assemblix_mcp.tools.executions import register_execution_tools
+
+
+def _server():
+    mcp = FastMCP("test")
+
+    async def get_client():
+        return AssemblixClient(base_url="http://api.test", api_key="sk_k", project_id="p1")
+
+    register_execution_tools(mcp, get_client)
+    return mcp
+
+
+@respx.mock
+async def test_run_workflow_returns_execution_id():
+    respx.post("http://api.test/api/workflows/w1/execute").mock(
+        return_value=httpx.Response(200, json={"executionId": "e1", "status": "running"})
+    )
+    async with MCPClient(_server()) as c:
+        result = await c.call_tool("run_workflow", {"workflow_id": "w1", "input": {"message": "hi"}})
+    assert result.data["executionId"] == "e1"
+
+
+@respx.mock
+async def test_run_and_wait_polls_until_completed():
+    respx.post("http://api.test/api/workflows/w1/execute").mock(
+        return_value=httpx.Response(200, json={"executionId": "e1", "status": "running"})
+    )
+    respx.get("http://api.test/api/executions/task/e1").mock(
+        side_effect=[
+            httpx.Response(200, json={"executionId": "e1", "status": "running"}),
+            httpx.Response(200, json={"executionId": "e1", "status": "completed", "output": {"a": 1}}),
+        ]
+    )
+    async with MCPClient(_server()) as c:
+        result = await c.call_tool(
+            "run_workflow_and_wait",
+            {"workflow_id": "w1", "input": {"message": "hi"}, "poll_interval": 0, "timeout_seconds": 5},
+        )
+    assert result.data["status"] == "completed"
+    assert result.data["output"] == {"a": 1}
+
+
+@respx.mock
+async def test_run_and_wait_returns_error_payload_without_raising():
+    respx.post("http://api.test/api/workflows/w1/execute").mock(
+        return_value=httpx.Response(200, json={"executionId": "e1", "status": "running"})
+    )
+    respx.get("http://api.test/api/executions/task/e1").mock(
+        return_value=httpx.Response(200, json={"executionId": "e1", "status": "failed", "error": "no credential"})
+    )
+    async with MCPClient(_server()) as c:
+        result = await c.call_tool(
+            "run_workflow_and_wait",
+            {"workflow_id": "w1", "input": {"message": "hi"}, "poll_interval": 0, "timeout_seconds": 5},
+        )
+    assert result.data["status"] == "failed"
+    assert result.data["error"] == "no credential"
+
+
+@respx.mock
+async def test_run_and_wait_times_out_when_never_terminal():
+    respx.post("http://api.test/api/workflows/w1/execute").mock(
+        return_value=httpx.Response(200, json={"executionId": "e1", "status": "running"})
+    )
+    respx.get("http://api.test/api/executions/task/e1").mock(
+        return_value=httpx.Response(200, json={"executionId": "e1", "status": "running"})
+    )
+    async with MCPClient(_server()) as c:
+        result = await c.call_tool(
+            "run_workflow_and_wait",
+            {"workflow_id": "w1", "input": {"message": "hi"}, "poll_interval": 0, "timeout_seconds": 0.05},
+        )
+    assert result.data["timedOut"] is True
+    assert result.data["status"] == "running"

assemblix_mcp-0.1.0/tests/test_resources.py

@@ -0,0 +1,39 @@
+import json
+
+from fastmcp import Client as MCPClient
+from fastmcp import FastMCP
+
+from assemblix_mcp.resources import register_resources
+
+
+def _server():
+    mcp = FastMCP("test")
+    register_resources(mcp)
+    return mcp
+
+
+async def test_minimal_example_is_valid_runnable_shape():
+    async with MCPClient(_server()) as c:
+        contents = await c.read_resource("assemblix://examples/minimal")
+    data = json.loads(contents[0].text)
+    types = [n["type"] for n in data["nodes"]]
+    assert types == ["start", "agent", "end"]
+    # edges wire start->agent->end
+    pairs = {(e["source"], e["target"]) for e in data["edges"]}
+    assert ("start-1", "agent-1") in pairs
+    assert ("agent-1", "end-1") in pairs
+
+
+async def test_branching_example_uses_condition_handles():
+    async with MCPClient(_server()) as c:
+        contents = await c.read_resource("assemblix://examples/branching")
+    data = json.loads(contents[0].text)
+    handles = {e.get("sourceHandle") for e in data["edges"]}
+    assert "source_cond-1_0" in handles
+    assert "source_cond-1_1" in handles
+
+
+async def test_author_prompt_registered():
+    async with MCPClient(_server()) as c:
+        prompts = await c.list_prompts()
+    assert any(p.name == "author_workflow" for p in prompts)

assemblix_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,71 @@
+import asyncio
+from unittest.mock import patch
+
+import httpx
+import respx
+from fastmcp import Client as MCPClient
+from starlette.datastructures import Headers
+
+from assemblix_mcp.config import Settings
+from assemblix_mcp.server import build_server
+
+
+class _FakeRequest:
+    """Stand-in for starlette Request; only .headers is read by get_http_headers."""
+
+    def __init__(self, headers: dict[str, str]) -> None:
+        self.headers = Headers(headers)
+        self.scope: dict[str, object] = {}
+
+
+@respx.mock
+async def test_get_client_reads_authorization_header_over_http():
+    """Regression test: hosted HTTP transport must forward the caller's bearer
+    token to the API. fastmcp's get_http_headers() excludes "authorization" by
+    default, so build_server's get_client() must pass include={"authorization"}
+    to opt it back in. No ASSEMBLIX_API_KEY is set, so if the header is not
+    read, resolve_api_key raises and this test fails.
+    """
+    settings = Settings(
+        api_url="http://api.test", api_key=None, transport="http", host="h", port=1
+    )
+    mcp = build_server(settings)
+
+    route = respx.get("http://api.test/api/workflows/").mock(
+        return_value=httpx.Response(200, json=[])
+    )
+
+    async def _fake_fetch_project_id(api_url, api_key):
+        return "p1"
+
+    fake_request = _FakeRequest(
+        {"Authorization": "Bearer sk_from_header", "X-Benign": "yes"}
+    )
+
+    with (
+        patch("fastmcp.server.dependencies.get_http_request", return_value=fake_request),
+        patch("assemblix_mcp.server.fetch_project_id", _fake_fetch_project_id),
+    ):
+        async with MCPClient(mcp) as c:
+            result = await c.call_tool("list_workflows", {})
+
+    assert result.data == []
+    sent_auth = route.calls.last.request.headers["authorization"]
+    assert sent_auth == "Bearer sk_from_header"
+
+
+def test_build_server_registers_all_tools():
+    settings = Settings(
+        api_url="http://api.test", api_key="sk_k", transport="stdio", host="h", port=1
+    )
+    mcp = build_server(settings)
+    names = {tool.name for tool in asyncio.run(mcp.list_tools())}
+    assert {
+        "list_node_types",
+        "create_workflow",
+        "publish_workflow",
+        "run_workflow",
+        "run_workflow_and_wait",
+        "get_execution",
+        "list_executions",
+    } <= names

assemblix_mcp-0.1.0/tests/test_workflow_tools.py

@@ -0,0 +1,42 @@
+import httpx
+import respx
+from fastmcp import Client as MCPClient
+from fastmcp import FastMCP
+
+from assemblix_mcp.client import AssemblixClient
+from assemblix_mcp.tools.workflows import register_workflow_tools
+
+
+def _server():
+    mcp = FastMCP("test")
+
+    async def get_client():
+        return AssemblixClient(base_url="http://api.test", api_key="sk_k", project_id="p1")
+
+    register_workflow_tools(mcp, get_client)
+    return mcp
+
+
+@respx.mock
+async def test_list_node_types_tool():
+    respx.get("http://api.test/api/nodes").mock(
+        return_value=httpx.Response(200, json=[{"type": "agent"}])
+    )
+    async with MCPClient(_server()) as c:
+        result = await c.call_tool("list_node_types", {})
+    assert result.data == [{"type": "agent"}]
+
+
+@respx.mock
+async def test_create_then_publish():
+    respx.post("http://api.test/api/workflows/").mock(
+        return_value=httpx.Response(201, json={"id": "w2", "name": "New"})
+    )
+    respx.post("http://api.test/api/workflows/w2/publish").mock(
+        return_value=httpx.Response(200, json={"id": "w2", "isPublished": True})
+    )
+    async with MCPClient(_server()) as c:
+        created = await c.call_tool("create_workflow", {"name": "New"})
+        published = await c.call_tool("publish_workflow", {"workflow_id": "w2"})
+    assert created.data["id"] == "w2"
+    assert published.data["isPublished"] is True