penpot-api-mcp 0.1.1__tar.gz

penpot_api_mcp-0.1.1/.crackerjack/uv/cache/.gitignore

@@ -0,0 +1 @@
+*

penpot_api_mcp-0.1.1/.crackerjack/uv/cache/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

penpot_api_mcp-0.1.1/.envrc

@@ -0,0 +1 @@
+layout uv

penpot_api_mcp-0.1.1/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+.env
+*.egg-info/
+dist/
+build/
+htmlcov/
+.coverage
+coverage.xml
+*.log
+*.err
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+uv.lock

penpot_api_mcp-0.1.1/.mcp.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "crackerjack": {
+      "env": {
+        "BASH_DEFAULT_TIMEOUT_MS": "300000",
+        "BASH_MAX_TIMEOUT_MS": "1800000",
+        "MCP_TIMEOUT": "60000",
+        "MCP_TOOL_TIMEOUT": "1800000"
+      },
+      "type": "http",
+      "url": "http://localhost:8676/mcp"
+    },
+    "session-buddy": {
+      "type": "http",
+      "url": "http://localhost:8678/mcp"
+    }
+  }
+}

penpot_api_mcp-0.1.1/AGENTS.md

@@ -0,0 +1,42 @@
+# AGENTS.md
+
+Bootstrap reference for AI agents and tools working with `penpot-api-mcp`.
+
+## What This Is
+
+MCP server (Python 3.13, FastMCP, port 3051) wrapping the Penpot REST API. Headless — no browser required. Complements the official TypeScript `@penpot/mcp` (which needs a browser plugin for live canvas manipulation).
+
+## Quick Commands
+
+```bash
+uv sync                                        # Install deps
+uv run pytest                                  # Tests
+uv run crackerjack                             # Quality gates
+uv run python -m penpot_api_mcp start --force  # Start HTTP server
+```
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `penpot_api_mcp/utils/transit.py` | Transit+JSON encode/decode — Penpot's wire format |
+| `penpot_api_mcp/clients/penpot_client.py` | Core API client with auth and RPC |
+| `penpot_api_mcp/config/settings.py` | `PENPOT_*` env var configuration |
+| `penpot_api_mcp/tools/` | FastMCP tool registrations (6 tools) |
+| `settings/penpot_api_mcp.yaml` | YAML config (Oneiric-compatible) |
+| `~/Library/LaunchAgents/com.mcp.penpot-api.plist` | launchctl service definition |
+
+## MCP Tools
+
+`list_projects` · `get_project_files` · `get_file` · `get_object_tree` · `search_objects` · `export_object`
+
+## Auth
+
+Set `PENPOT_ACCESS_TOKEN` (preferred) or `PENPOT_EMAIL` + `PENPOT_PASSWORD`. Never use password-auth session cookie values as Bearer tokens.
+
+## Critical Invariants
+
+1. All `_rpc()` calls use `transit=True` — Penpot speaks Transit+JSON
+1. `encode()` / `decode()` are the only correct way to build/parse Penpot payloads
+1. After password login, session is cookie-jar only — `self._api_token` stays empty
+1. FastMCP lifespan via constructor `lifespan=` param, not `_mcp_server.lifespan` patch

penpot_api_mcp-0.1.1/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2026-05-18
+
+### Added
+
+- Initial implementation of penpot-api-mcp
+
+### Internal
+
+- Add LICENSE, README, CLAUDE.md, AGENTS.md, .gitignore

penpot_api_mcp-0.1.1/CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+Guidance for Claude Code working with `penpot-api-mcp`. Start with `AGENTS.md` for a shorter bootstrap.
+
+## Ecosystem Context
+
+Part of the **Bodai Ecosystem**:
+
+| Component | Role | Port |
+|-----------|------|------|
+| Mahavishnu | Orchestrator | 8680 |
+| Akosha | Seer | 8682 |
+| Dhara | Curator | 8683 |
+| Session-Buddy | Builder | 8678 |
+| Crackerjack | Inspector | 8676 |
+| **penpot-api-mcp** | Penpot REST API | 3051 |
+
+## Project Overview
+
+FastMCP MCP server wrapping the Penpot REST API. Provides headless (no-browser) read and export access for design automation workflows. Complements the official `@penpot/mcp` (TypeScript, browser plugin required).
+
+**Tech stack:** Python 3.13, FastMCP, httpx, Pydantic, mcp-common, Oneiric
+
+## Common Commands
+
+```bash
+uv sync                              # Install/sync all dependencies
+uv run python -m penpot_api_mcp      # Run (stdio mode)
+uv run python -m penpot_api_mcp start --force  # Run (HTTP mode)
+
+uv run pytest                        # Run tests
+uv run crackerjack                   # Full quality suite
+uv run ruff check --fix              # Lint
+uv run mypy .                        # Type check
+```
+
+## Architecture
+
+### Key Design Decisions
+
+**Transit+JSON**: Penpot's RPC API uses Transit+JSON (Clojure serialization). All encoding/decoding is centralized in `penpot_api_mcp/utils/transit.py`. Never manually construct `~:key` or `~uUUID` payloads elsewhere — use `encode()` / `decode()`.
+
+**Auth separation**: Two auth paths must stay separate:
+
+- API token (`PENPOT_ACCESS_TOKEN`): stored in `self._api_token`, sent as `Authorization: Token` header
+- Password auth: session cookie only, stored in the httpx cookie jar, never converted to a Bearer token
+
+**Consistent transit**: All `_rpc()` calls use `transit=True` (default). The `transit=False` path exists only for edge cases where the server doesn't speak Transit. Do not add new `transit=False` calls without verifying the server response format.
+
+**FastMCP lifespan**: Use the `lifespan=` constructor parameter — never monkey-patch `app._mcp_server.lifespan`.
+
+### Module Layout
+
+```
+penpot_api_mcp/
+├── utils/transit.py      # encode() / decode() for Transit+JSON
+├── config/settings.py    # PenpotSettings (PENPOT_* env vars)
+├── clients/
+│   ├── base_client.py    # httpx.AsyncClient lifecycle + cookie persistence
+│   └── penpot_client.py  # Typed Penpot RPC wrapper
+├── models/               # Pydantic: Project, File, Object, ObjectTree
+├── tools/                # FastMCP @app.tool() registrations
+├── server.py             # create_app() factory
+└── __main__.py           # Oneiric MCPServerCLIFactory entrypoint
+```
+
+## Coding Standards
+
+- Python 3.13+, strict typing, 88-char lines (Ruff)
+- `from __future__ import annotations` in every module
+- Pydantic models for all API response shapes
+- `httpx` (async) — never `requests`
+- Tests in `tests/`, mirrors package layout
+
+## Security
+
+- Credentials only via environment variables — never hardcoded
+- Path: `PENPOT_ACCESS_TOKEN` > `PENPOT_EMAIL` + `PENPOT_PASSWORD`
+- No secrets in logs — use structured logging with redaction

penpot_api_mcp-0.1.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Les Leslie
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

penpot_api_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: penpot-api-mcp
+Version: 0.1.1
+Summary: MCP server wrapping the Penpot REST API for headless design automation
+Author-email: Les Leslie <les@wedgwoodwebworks.com>
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: automation,design,mcp,model-context-protocol,penpot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Requires-Dist: fastmcp>=2.12.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp-common>=0.15.0
+Requires-Dist: oneiric>=0.3.6
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: structlog>=25.0.0
+Requires-Dist: uvicorn>=0.30.0
+Description-Content-Type: text/markdown
+
+# penpot-api-mcp
+
+MCP server wrapping the [Penpot](https://penpot.app) REST API for headless design automation. Provides read, search, and export access to Penpot projects, files, and design objects — without requiring a browser session.
+
+Part of the **Bodai Ecosystem** alongside Mahavishnu, Akosha, Dhara, Session-Buddy, and Crackerjack.
+
+## Why this exists
+
+The official `@penpot/mcp` (TypeScript) requires a live browser plugin to operate — it is the right tool for interactive canvas manipulation. This server targets the complementary use case: background automation, asset export pipelines, and AI-driven design queries that run without a browser.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `list_projects` | List all projects for the authenticated user |
+| `get_project_files` | List design files in a project |
+| `get_file` | Fetch the full content of a design file |
+| `get_object_tree` | Return the design object hierarchy for a file |
+| `search_objects` | Search objects by name or type |
+| `export_object` | Export a design object as PNG/SVG (base64-encoded) |
+
+## Setup
+
+```bash
+uv sync
+cp .env.example .env   # fill in credentials
+```
+
+## Configuration
+
+Environment variables (prefix `PENPOT_`):
+
+| Variable | Description | Default |
+|---|---|---|
+| `PENPOT_ACCESS_TOKEN` | API access token (preferred) | — |
+| `PENPOT_EMAIL` | Email for password auth (fallback) | — |
+| `PENPOT_PASSWORD` | Password for password auth (fallback) | — |
+| `PENPOT_BASE_URL` | API base URL for self-hosted instances | `https://design.penpot.app/api` |
+
+Either `PENPOT_ACCESS_TOKEN` or `PENPOT_EMAIL` + `PENPOT_PASSWORD` must be set.
+
+## Running
+
+```bash
+# HTTP mode (default — Claude Code compatible)
+uv run python -m penpot_api_mcp start --force
+
+# stdio mode
+uv run python -m penpot_api_mcp
+```
+
+Server listens on `http://localhost:3051/mcp`.
+
+## MCP configuration
+
+```json
+{
+  "mcpServers": {
+    "penpot-api": {
+      "type": "http",
+      "url": "http://localhost:3051/mcp"
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+uv run pytest                          # Run tests
+uv run crackerjack                     # Full quality suite (ruff + mypy + pytest + bandit)
+uv run ruff check --fix                # Lint
+uv run mypy .                          # Type check
+```
+
+## Architecture
+
+```
+penpot_api_mcp/
+├── utils/transit.py      # Transit+JSON encode/decode (Penpot's wire format)
+├── config/settings.py    # Pydantic settings (PENPOT_* env vars)
+├── clients/              # httpx async client with dual auth
+├── models/               # Pydantic models: Project, File, Object, ObjectTree
+├── tools/                # FastMCP tool registrations
+├── server.py             # FastMCP app + health endpoints
+└── __main__.py           # MCPServerCLIFactory entrypoint (Oneiric)
+```
+
+### Transit+JSON
+
+Penpot's RPC layer uses [Transit+JSON](https://github.com/cognitect/transit-format) — a Clojure serialization format where map keys are `~:keyword` and UUIDs are `~uUUID`. The `utils/transit.py` module handles encode/decode at the API boundary, keeping all Python models clean.
+
+### Authentication
+
+Two modes are supported:
+
+- **API token** (`PENPOT_ACCESS_TOKEN`): sent as `Authorization: Token <token>` header
+- **Email + password**: authenticates via `/rpc/command/login-with-password`, then relies on the httpx cookie jar (`auth-token` cookie) for all subsequent requests
+
+## License
+
+BSD 3-Clause. See [LICENSE](LICENSE).

penpot_api_mcp-0.1.1/README.md

@@ -0,0 +1,102 @@
+# penpot-api-mcp
+
+MCP server wrapping the [Penpot](https://penpot.app) REST API for headless design automation. Provides read, search, and export access to Penpot projects, files, and design objects — without requiring a browser session.
+
+Part of the **Bodai Ecosystem** alongside Mahavishnu, Akosha, Dhara, Session-Buddy, and Crackerjack.
+
+## Why this exists
+
+The official `@penpot/mcp` (TypeScript) requires a live browser plugin to operate — it is the right tool for interactive canvas manipulation. This server targets the complementary use case: background automation, asset export pipelines, and AI-driven design queries that run without a browser.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `list_projects` | List all projects for the authenticated user |
+| `get_project_files` | List design files in a project |
+| `get_file` | Fetch the full content of a design file |
+| `get_object_tree` | Return the design object hierarchy for a file |
+| `search_objects` | Search objects by name or type |
+| `export_object` | Export a design object as PNG/SVG (base64-encoded) |
+
+## Setup
+
+```bash
+uv sync
+cp .env.example .env   # fill in credentials
+```
+
+## Configuration
+
+Environment variables (prefix `PENPOT_`):
+
+| Variable | Description | Default |
+|---|---|---|
+| `PENPOT_ACCESS_TOKEN` | API access token (preferred) | — |
+| `PENPOT_EMAIL` | Email for password auth (fallback) | — |
+| `PENPOT_PASSWORD` | Password for password auth (fallback) | — |
+| `PENPOT_BASE_URL` | API base URL for self-hosted instances | `https://design.penpot.app/api` |
+
+Either `PENPOT_ACCESS_TOKEN` or `PENPOT_EMAIL` + `PENPOT_PASSWORD` must be set.
+
+## Running
+
+```bash
+# HTTP mode (default — Claude Code compatible)
+uv run python -m penpot_api_mcp start --force
+
+# stdio mode
+uv run python -m penpot_api_mcp
+```
+
+Server listens on `http://localhost:3051/mcp`.
+
+## MCP configuration
+
+```json
+{
+  "mcpServers": {
+    "penpot-api": {
+      "type": "http",
+      "url": "http://localhost:3051/mcp"
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+uv run pytest                          # Run tests
+uv run crackerjack                     # Full quality suite (ruff + mypy + pytest + bandit)
+uv run ruff check --fix                # Lint
+uv run mypy .                          # Type check
+```
+
+## Architecture
+
+```
+penpot_api_mcp/
+├── utils/transit.py      # Transit+JSON encode/decode (Penpot's wire format)
+├── config/settings.py    # Pydantic settings (PENPOT_* env vars)
+├── clients/              # httpx async client with dual auth
+├── models/               # Pydantic models: Project, File, Object, ObjectTree
+├── tools/                # FastMCP tool registrations
+├── server.py             # FastMCP app + health endpoints
+└── __main__.py           # MCPServerCLIFactory entrypoint (Oneiric)
+```
+
+### Transit+JSON
+
+Penpot's RPC layer uses [Transit+JSON](https://github.com/cognitect/transit-format) — a Clojure serialization format where map keys are `~:keyword` and UUIDs are `~uUUID`. The `utils/transit.py` module handles encode/decode at the API boundary, keeping all Python models clean.
+
+### Authentication
+
+Two modes are supported:
+
+- **API token** (`PENPOT_ACCESS_TOKEN`): sent as `Authorization: Token <token>` header
+- **Email + password**: authenticates via `/rpc/command/login-with-password`, then relies on the httpx cookie jar (`auth-token` cookie) for all subsequent requests
+
+## License
+
+BSD 3-Clause. See [LICENSE](LICENSE).

penpot_api_mcp-0.1.1/penpot_api_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""penpot-api-mcp — MCP server wrapping the Penpot REST API."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

penpot_api_mcp-0.1.1/penpot_api_mcp/__main__.py

@@ -0,0 +1,94 @@
+"""Oneiric CLI entry point for penpot-api-mcp."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mcp_common.cli import MCPServerCLIFactory
+from mcp_common.server import BaseOneiricServerMixin, create_runtime_components
+from oneiric.core.config import OneiricMCPConfig
+from oneiric.runtime.mcp_health import HealthStatus
+
+from penpot_api_mcp.config import get_settings
+from penpot_api_mcp.server import create_app
+
+OneiricMCPConfigType = (
+    OneiricMCPConfig if not TYPE_CHECKING else "TypedOneiricMCPConfig"
+)
+
+
+class PenpotApiConfig(OneiricMCPConfig):  # type: ignore[misc]
+    http_port: int = 3051
+    http_host: str = "127.0.0.1"
+    enable_http_transport: bool = True
+
+    class Config:
+        env_prefix = "PENPOT_MCP_"
+        env_file = ".env"
+
+
+class PenpotApiMCPServer(BaseOneiricServerMixin):
+    def __init__(self, config: PenpotApiConfig) -> None:
+        self.config = config  # type: ignore[assignment]
+        self.app = create_app()
+        self.runtime = create_runtime_components(
+            server_name="penpot-api-mcp",
+            cache_dir=config.cache_dir or ".oneiric_cache",
+        )
+
+    @property
+    def snapshot_manager(self) -> object:
+        return self.runtime.snapshot_manager
+
+    @property
+    def cache_manager(self) -> object:
+        return self.runtime.cache_manager
+
+    @property
+    def health_monitor(self) -> object:
+        return self.runtime.health_monitor
+
+    async def startup(self) -> None:
+        _ = get_settings()
+        await self.runtime.initialize()
+        await self._create_startup_snapshot(
+            custom_components={"penpot-api": {"status": "initialized"}}
+        )
+
+    async def shutdown(self) -> None:
+        await self._create_shutdown_snapshot()
+        await self.runtime.cleanup()
+
+    async def health_check(self) -> object:
+        base = await self._build_health_components()
+        settings = get_settings()
+        base.append(
+            self.runtime.health_monitor.create_component_health(
+                name="penpot-api",
+                status=HealthStatus.HEALTHY
+                if settings.is_configured
+                else HealthStatus.UNHEALTHY,
+                details={
+                    "configured": settings.is_configured,
+                    "auth_method": "token" if settings.has_token_auth else "password",
+                },
+            )
+        )
+        return self.runtime.health_monitor.create_health_response(base)
+
+    def get_app(self) -> object:
+        return self.app.http_app
+
+
+def main() -> None:
+    cli_factory = MCPServerCLIFactory.create_server_cli(
+        server_class=PenpotApiMCPServer,
+        config_class=PenpotApiConfig,
+        name="penpot-api-mcp",
+        _description="Penpot API MCP Server — headless design automation via REST API",
+    )
+    cli_factory.create_app()()
+
+
+if __name__ == "__main__":
+    main()

penpot_api_mcp-0.1.1/penpot_api_mcp/clients/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from penpot_api_mcp.clients.penpot_client import PenpotClient
+
+__all__ = ["PenpotClient"]

penpot_api_mcp-0.1.1/penpot_api_mcp/clients/base_client.py

@@ -0,0 +1,61 @@
+"""Base async HTTP client with httpx."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+from penpot_api_mcp.config.settings import PenpotSettings
+
+logger = logging.getLogger(__name__)
+
+_TRANSIT_HEADERS = {
+    "Content-Type": "application/transit+json",
+    "Accept": "application/transit+json",
+}
+_JSON_HEADERS = {
+    "Content-Type": "application/json",
+    "Accept": "application/json",
+}
+
+
+class BaseHTTPClient:
+    def __init__(self, settings: PenpotSettings) -> None:
+        self._settings = settings
+        self._base_url = str(settings.base_url).rstrip("/")
+        self._client: httpx.AsyncClient | None = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            # Carry over any cookies from a closed client so session auth
+            # survives a transport error + reconnect.
+            prior_cookies = dict(self._client.cookies) if self._client else {}
+            self._client = httpx.AsyncClient(
+                base_url=self._base_url,
+                timeout=self._settings.request_timeout,
+                limits=httpx.Limits(max_connections=self._settings.max_connections),
+                cookies=prior_cookies,
+            )
+        return self._client
+
+    async def close(self) -> None:
+        if self._client and not self._client.is_closed:
+            await self._client.aclose()
+
+    async def _post(
+        self,
+        path: str,
+        body: dict[str, Any],
+        *,
+        transit: bool = True,
+        extra_headers: dict[str, str] | None = None,
+    ) -> Any:
+        client = await self._get_client()
+        headers = dict(_TRANSIT_HEADERS if transit else _JSON_HEADERS)
+        if extra_headers:
+            headers.update(extra_headers)
+        response = await client.post(path, json=body, headers=headers)
+        response.raise_for_status()
+        return response.json()