compono-mcp 0.1.0__tar.gz

compono_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: compono-mcp
+Version: 0.1.0
+Summary: MCP server exposing compono's render_deck/validate as MCP tools.
+Author: Shaik-Hamzah123
+Author-email: Shaik-Hamzah123 <hamzah.shaik2003@gmail.com>
+License-Expression: MIT
+Requires-Dist: compono>=0.1.0
+Requires-Dist: fastmcp>=4.0.3
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# compono-mcp
+
+MCP server wrapper exposing [`compono`](https://pypi.org/project/compono/)'s
+`render_deck`/`validate` as MCP tools, for any MCP-compatible client (not just
+Claude Code).
+
+## Install
+
+```bash
+pip install compono-mcp
+# or
+uv add compono-mcp
+```
+
+## Usage
+
+Add to your MCP client config (Claude Desktop / Claude Code style):
+
+```json
+{ "mcpServers": { "compono": { "command": "compono-mcp" } } }
+```
+
+Exposes:
+- **`validate(spec)`** — schema + layout + overflow checks, no file write.
+- **`render_deck(spec, output_path)`** — writes a real `.pptx` file.
+- **resource `compono://reference`** — the full agent-facing reference doc
+  (quickstart, primitive catalog, worked examples, error shape), for MCP
+  clients that don't have Claude Code's skill system.
+
+See the [main compono README](https://github.com/Shaik-Hamzah123/compono) for
+the primitive schema and worked examples — `spec` here is the identical JSON
+shape `compono.render_deck`/`validate` accept directly.

compono_mcp-0.1.0/README.md

@@ -0,0 +1,32 @@
+# compono-mcp
+
+MCP server wrapper exposing [`compono`](https://pypi.org/project/compono/)'s
+`render_deck`/`validate` as MCP tools, for any MCP-compatible client (not just
+Claude Code).
+
+## Install
+
+```bash
+pip install compono-mcp
+# or
+uv add compono-mcp
+```
+
+## Usage
+
+Add to your MCP client config (Claude Desktop / Claude Code style):
+
+```json
+{ "mcpServers": { "compono": { "command": "compono-mcp" } } }
+```
+
+Exposes:
+- **`validate(spec)`** — schema + layout + overflow checks, no file write.
+- **`render_deck(spec, output_path)`** — writes a real `.pptx` file.
+- **resource `compono://reference`** — the full agent-facing reference doc
+  (quickstart, primitive catalog, worked examples, error shape), for MCP
+  clients that don't have Claude Code's skill system.
+
+See the [main compono README](https://github.com/Shaik-Hamzah123/compono) for
+the primitive schema and worked examples — `spec` here is the identical JSON
+shape `compono.render_deck`/`validate` accept directly.

compono_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "compono-mcp"
+version = "0.1.0"
+description = "MCP server exposing compono's render_deck/validate as MCP tools."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Shaik-Hamzah123", email = "hamzah.shaik2003@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "compono>=0.1.0",
+    "fastmcp>=4.0.3",
+]
+
+[project.scripts]
+compono-mcp = "compono_mcp.server:main"
+
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+compono = { workspace = true }

compono_mcp-0.1.0/src/compono_mcp/__init__.py

@@ -0,0 +1 @@
+"""compono-mcp — MCP server exposing compono's render_deck/validate as MCP tools."""

compono_mcp-0.1.0/src/compono_mcp/reference.md

@@ -0,0 +1,212 @@
+<!--
+  Served verbatim as the `compono://reference` MCP resource (see server.py).
+  Kept in sync with the repo root skills/compono/SKILL.md and README.md —
+  same convention already used between those two files. Update all three
+  together when the API surface changes.
+-->
+
+# compono
+
+**Agent-oriented, code-based PPTX generation — "Manim, but for PowerPoint."**
+
+compono lets you describe a slide deck as data — headers, bullet text,
+stats, tables, charts, images, process sequences, shapes — and get back a
+real, editable `.pptx` file. You never write raw `x`/`y`/`w`/`h`
+coordinates: a constraint-based layout resolver computes every position
+from a small set of typed primitives.
+
+Every rendered element is a genuine, editable native shape (`p:sp`, `p:pic`,
+`p:graphicFrame`) — never a flattened image or embedded video. Opening the
+result in PowerPoint and dragging a box around works; it's a real object,
+not a picture of one.
+
+You are receiving this document through the `compono-mcp` MCP server's
+`compono://reference` resource — use its `validate`/`render_deck` tools as
+described below.
+
+## Quickstart
+
+```python
+from compono import render_deck
+
+spec = {
+    "slides": [
+        {
+            "header": {"title": "Q3 Results", "subtitle": "Engineering team"},
+            "body": [
+                {
+                    "primitive": "text",
+                    "mode": "bullets",
+                    "content": [
+                        "Shipped the new layout resolver",
+                        "Cut render time by 40%",
+                        "Zero overflow bugs in production",
+                    ],
+                    "emphasis_indices": [1],
+                }
+            ],
+        }
+    ]
+}
+
+report = render_deck(spec, "deck.pptx")
+print(report.pptx_path, report.warnings)
+```
+
+Through this MCP server, call the `validate` and `render_deck` tools with
+the identical `spec` shape instead of importing Python directly.
+
+## Core concepts
+
+- **One entry point, two verbs.** `render_deck(spec, output_path)` and
+  `validate(spec)` are the only two functions you need. `validate` is cheap
+  — no pptx write, millisecond-scale — so iterate on a spec before paying
+  render cost.
+- **A spec is plain data.** A raw `dict`/JSON (what tool-calling naturally
+  produces) is all you need — pass it straight to `render_deck`/`validate`.
+- **You never write coordinates.** Every primitive claims space in a slide;
+  the resolver (a CSS-flexbox-style directional box model) computes real
+  EMU positions. `grid` is the one primitive that does true 2D
+  row/column math.
+- **Errors are fixes, not diagnoses.** Every validation/render failure is
+  `{slide, primitive, field, error, detail, fix}` — see
+  [Error shape](#error-shape) below. Act on `fix`, don't just retry blindly.
+- **render_deck returns a report, not just a file** —
+  `{pptx_path, manifest, warnings, actual_layout}` — reason about what
+  happened without reopening the file.
+
+## Tools (via this MCP server)
+
+| Tool | Input | Output | Notes |
+|---|---|---|---|
+| `validate` | `spec: object` | `{valid, errors, warnings}` | No file write. Never errors out on malformed input — `valid: false` with structured errors instead. |
+| `render_deck` | `spec: object, output_path: string` | `{pptx_path, manifest, warnings}` on success, or `{valid: false, errors}` on failure | Writes a real `.pptx` at `output_path` on the machine running this server. |
+
+A `spec` (a `Deck`) is `{template?: str, slides: [Slide, ...]}`. A `Slide` is
+`{header?: Header, body: [primitive, ...], notes?: str}`. `body` (and
+`grid.items`) accept any primitive, keyed by its `"primitive"` field.
+
+**Prefer `validate` before `render_deck` when iterating** — it's cheap and
+gives you the same structured errors without writing a file.
+
+### Error shape
+
+```json
+{
+  "slide": 3,
+  "primitive": "grid.items[1]",
+  "field": "content",
+  "error": "overflow",
+  "detail": "Text is ~14pt too tall for the box at font size 18pt (6 lines).",
+  "fix": "Shorten the text, reduce bullet/line count, or split into two slides."
+}
+```
+
+## Primitive catalog
+
+Every primitive accepts an optional `id` (needed if another primitive
+references it, e.g. a connector) and an optional `notes` (speaker notes).
+There is no separate "title slide" / "content slide" / "thank-you slide"
+taxonomy — a slide is just `{header?, body: [...]}`, and genre/density/tone
+decisions (what kind of slide this is, how much goes on it) are yours to
+make by composing primitives, not a schema type to pick.
+
+| Primitive | Key fields | Purpose |
+|---|---|---|
+| `header` | `title`, `subtitle?`, `eyebrow?`, `align` | Slide title region. |
+| `text` | `mode` (paragraph/bullets), `content`, `columns?`, `emphasis_indices?` | Prose or bullet list. |
+| `image` | `src?`, `placeholder`, `caption?`, `fit` (cover/contain) | A real picture, or a first-class placeholder — see below. |
+| `stat` | `value`, `label`, `trend?` | A headline number with a label. |
+| `grid` | `items`, `columns`, `direction`, `align`, `justify` | The one primitive with true 2D layout. Items can be any primitive, including nested grids. |
+| `table` | `headers`, `rows`, `emphasis_row?`, `emphasis_col?` | Renders as a real OOXML table (`p:graphicFrame`), not an image. |
+| `sequence` | `steps` (`{label, description?}`), `orientation` | A row/column of connected step boxes — process/timeline diagrams. |
+| `chart` | `chart_type` (bar/line/pie), `categories`, `series` | A real, editable native chart with live data — not a picture of a chart. |
+| `shape` | `kind` (rect/rounded_rect/oval/line/arrow/connector), `fill`, `border`, `connects?`, `text?` | Freeform shape, optionally with text inside, or a connector between two other primitives by `id`. |
+
+### Image placeholders
+
+Set `"placeholder": true` (with an optional `caption`) instead of `src` when
+you don't have a real image yet. It renders as an intentional design
+element — dashed border, centered caption — and `render_deck`'s response
+gets one manifest entry per placeholder:
+`{slide, primitive, rect: {x, y, w, h}, caption}`. A later pass (image
+search/generation/human upload) can fill each reserved rect directly from
+the manifest EMU rect — no re-layout needed, and you don't need
+image-generation capability just to build the deck.
+
+## Worked examples
+
+### 1. Title slide
+
+```json
+{
+  "slides": [
+    { "header": { "title": "2026 Roadmap", "subtitle": "Platform team", "eyebrow": "Q1 Kickoff" } }
+  ]
+}
+```
+
+### 2. Two-column comparison with a connector
+
+```json
+{
+  "slides": [{
+    "header": { "title": "Before vs. After" },
+    "body": [
+      {
+        "primitive": "grid",
+        "columns": 2,
+        "items": [
+          { "id": "before", "primitive": "shape", "kind": "rounded_rect", "fill": "#EF4444",
+            "text": { "content": "Manual layout" } },
+          { "id": "after", "primitive": "shape", "kind": "rounded_rect", "fill": "#10B981",
+            "text": { "content": "Resolver-computed layout" } }
+        ]
+      },
+      { "primitive": "shape", "kind": "connector", "connects": { "from_id": "before", "to_id": "after" } }
+    ]
+  }]
+}
+```
+
+### 3. Stat + table + chart dashboard
+
+```json
+{
+  "slides": [{
+    "header": { "title": "Q3 Metrics" },
+    "body": [
+      { "primitive": "stat", "value": "42%", "label": "YoY growth", "trend": "+12% vs Q2" },
+      { "primitive": "table", "headers": ["Quarter", "Revenue"], "rows": [["Q1", "10"], ["Q2", "14"]] },
+      { "primitive": "chart", "chart_type": "bar", "categories": ["Q1", "Q2"],
+        "series": [{ "name": "Revenue", "values": [10, 14] }] }
+    ]
+  }]
+}
+```
+
+### 4. Process sequence
+
+```json
+{
+  "slides": [{
+    "header": { "title": "Our Process" },
+    "body": [{
+      "primitive": "sequence",
+      "orientation": "horizontal",
+      "steps": [
+        { "label": "Discover", "description": "Understand the problem" },
+        { "label": "Design", "description": "Sketch options" },
+        { "label": "Ship", "description": "Release to users" }
+      ]
+    }]
+  }]
+}
+```
+
+## Fonts and overflow validation
+
+Overflow checking reads real glyph advance widths via `fonttools` — no
+rendering required. As of this release, no font is bundled yet; validation
+falls back to a system font if one is found, and is skipped — not faked —
+with a warning if none is available.

compono_mcp-0.1.0/src/compono_mcp/server.py

@@ -0,0 +1,72 @@
+"""MCP server exposing compono's render_deck/validate as MCP tools.
+
+Every tool here is a thin proxy — no reimplemented logic. `spec` parameters
+are typed as plain `dict`, not the `Deck` pydantic model, so malformed input
+reaches compono.validate/render_deck itself and comes back as compono's own
+structured {slide, primitive, field, error, detail, fix} shape, never MCP's
+generic schema-rejection error (this is deliberate — see the project plan).
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+from typing import Any
+
+from fastmcp import FastMCP
+
+from compono import DeckValidationError, render_deck, validate
+
+mcp = FastMCP("compono")
+
+
+@mcp.tool()
+def validate_deck(spec: dict[str, Any]) -> dict[str, Any]:
+    """Validate a compono deck spec: schema + layout + text-overflow checks, no file write.
+
+    Cheap (millisecond-scale) — prefer this before render_deck when iterating.
+    Never raises: malformed input comes back as {valid: false, errors: [...]},
+    each error shaped {slide, primitive, field, error, detail, fix}.
+    """
+    report = validate(spec)
+    return {"valid": report.valid, "errors": report.errors, "warnings": report.warnings}
+
+
+@mcp.tool()
+def render_deck_tool(spec: dict[str, Any], output_path: str) -> dict[str, Any]:
+    """Render a compono deck spec to a real, editable .pptx file at output_path.
+
+    On success: {pptx_path, manifest, warnings}. On any validation/layout/
+    overflow error: {valid: false, errors: [...]} in the same shape as
+    validate_deck — nothing is written to output_path in that case.
+    """
+    try:
+        report = render_deck(spec, output_path)
+    except DeckValidationError as exc:
+        return {"valid": False, "errors": exc.errors}
+
+    return {
+        "pptx_path": str(report.pptx_path),
+        "manifest": report.manifest,
+        "warnings": report.warnings,
+    }
+
+
+@mcp.resource("compono://reference")
+def reference() -> str:
+    """The full agent-facing compono reference: quickstart, primitive catalog,
+    worked examples, and error shape — for MCP clients without Claude Code's
+    skill system.
+    """
+    return (
+        importlib.resources.files("compono_mcp")
+        .joinpath("reference.md")
+        .read_text(encoding="utf-8")
+    )
+
+
+def main() -> None:
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()