fcp-slides 0.1.0__tar.gz

fcp_slides-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check for local path references
+        run: |
+          if grep -v '^\s*#' pyproject.toml | grep -q 'path\s*='; then
+            echo "::error::pyproject.toml contains uncommented local path references that break CI installs"
+            exit 1
+          fi
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --extra dev
+      - run: uv run pytest

fcp_slides-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,22 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: uv sync --extra dev
+      - run: uv run pytest
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

fcp_slides-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.DS_Store
+.pytest_cache/
+.ruff_cache/

fcp_slides-0.1.0/CLAUDE.md

@@ -0,0 +1,45 @@
+# fcp-slides
+
+## Project Overview
+MCP server that lets LLMs create and edit PowerPoint presentations through a semantic verb DSL.
+Uses python-pptx as the native library (Tier 2 architecture).
+
+## Architecture
+- `src/fcp_slides/model/` — Thin wrapper around python-pptx Presentation, slide/shape index, shape refs
+- `src/fcp_slides/server/` — Verb handlers (ops_*.py), queries, verb registry, resolvers
+- `src/fcp_slides/lib/` — Unit conversion, color palette, shape types, layout names, chart types
+- `src/fcp_slides/adapter.py` — FcpDomainAdapter bridging fcp-core to python-pptx
+- `src/fcp_slides/main.py` — Server entry point
+
+## Key Patterns
+- Each `ops_*.py` exports a `HANDLERS` dict mapping verb names to handler functions
+- The adapter merges all HANDLERS at import time for dispatch
+- `queries.py` exports `QUERY_HANDLERS` for query dispatch
+- Undo/redo: byte snapshots via `prs.save(BytesIO)` / `Presentation(BytesIO)`
+- Batch atomicity: pre-batch snapshot, rollback on any op failure
+- Positions/sizes use EMU internally, lib/units.py converts from `2in`/`5cm`
+- Shapes and slides referenced by labels (auto-assigned or user-specified)
+
+## python-pptx Gotchas
+- Slide removal requires XML manipulation (`_sldIdLst`)
+- Slide copy is partial — uses XML deepcopy
+- Slide hide/unhide via XML attribute (`show="0"`)
+- Chart data is set at creation; modifications use `chart.replace_data()`
+- Positions use EMUs (914400/inch)
+
+## Commands
+- `uv run pytest` — Run tests (70 tests)
+- `uv run python -c "from fcp_slides.main import main"` — Verify import
+
+## Verb Categories
+| Category | Verbs |
+|----------|-------|
+| Slides | slide (add/remove/rename/copy/move/hide/unhide/activate) |
+| Shapes | shape (add/remove/move/resize/duplicate), textbox, connector |
+| Text | text (set/append/clear), placeholder (set), bullet |
+| Tables | table (add/set/style/row/header/merge/remove) |
+| Charts | chart (add/data/series/axis/remove) |
+| Images | image (add/placeholder/remove) |
+| Layout | align, distribute, z-order |
+| Style | style (fill/outline/shadow/rotation), text-style (font/size/color/bold) |
+| Meta | notes (set/append/clear), deck (widescreen/standard/size) |

fcp_slides-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Scott Meyer
+
+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.

fcp_slides-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: fcp-slides
+Version: 0.1.0
+Summary: Presentation File Context Protocol — semantic slide operations for LLMs
+License-File: LICENSE
+Requires-Python: <3.14,>=3.11
+Requires-Dist: fastmcp>=3.0
+Requires-Dist: fcp-core>=0.1.14
+Requires-Dist: python-pptx>=1.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'

fcp_slides-0.1.0/README.md

@@ -0,0 +1,99 @@
+# fcp-slides
+
+MCP server for semantic presentation operations.
+
+## What It Does
+
+fcp-slides lets LLMs create and edit PowerPoint presentations by describing slide intent -- layouts, shapes, tables, charts, text styling -- and renders it into standard `.pptx` files. Instead of writing python-pptx code, the LLM works with operations like `slide add layout:title`, `placeholder set title "Q4 Report"`, and `table add 5 4 label:metrics`. Built on the [FCP](https://github.com/aetherwing-io/fcp) framework, powered by python-pptx for serialization.
+
+## Quick Example
+
+```
+slides_session('new "Q4 Review"')
+
+slides([
+  'slide add layout:title',
+  'placeholder set title "Q4 Business Review"',
+  'placeholder set subtitle "Prepared by Finance Team"',
+  'slide add layout:blank',
+  'table add 5 4 label:metrics x:1in y:1.5in w:8in h:4in',
+  'table header metrics "Region" "Revenue" "Costs" "Margin"',
+  'table set metrics 2 1 "North"',
+  'table set metrics 2 2 "$1.25M"',
+  'chart add bar label:revenue title:"Revenue by Region" x:1in y:1.5in w:8in h:4.5in',
+  'notes set "Discuss regional performance trends"',
+])
+
+slides_session('save as:./q4_review.pptx')
+```
+
+### Available MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `slides(ops)` | Batch mutations -- slides, shapes, text, tables, charts, images, styling |
+| `slides_query(q)` | Inspect the presentation -- slides, shapes, placeholders, layout info |
+| `slides_session(action)` | Lifecycle -- new, open, save, checkpoint, undo, redo |
+| `slides_help()` | Full reference card |
+
+## Installation
+
+Requires Python >= 3.11.
+
+```bash
+pip install fcp-slides
+```
+
+### MCP Client Configuration
+
+```json
+{
+  "mcpServers": {
+    "slides": {
+      "command": "uv",
+      "args": ["run", "python", "-m", "fcp_slides"]
+    }
+  }
+}
+```
+
+## Architecture
+
+3-layer architecture:
+
+```
+MCP Server (Intent Layer)
+  Parses op strings, dispatches to verb handlers
+        |
+Semantic Model
+  Thin wrapper around python-pptx Presentation
+  Slide/shape index, shape refs, undo/redo via byte snapshots
+        |
+Serialization (python-pptx)
+  Semantic model -> .pptx binary output
+```
+
+Key features:
+
+- **Slide layouts** -- Title, blank, content, section header, and custom layouts
+- **Shapes** -- Rectangles, ellipses, arrows, textboxes, connectors
+- **Tables** -- Create, populate, style with headers and merged cells
+- **Charts** -- Bar, line, pie, scatter, area, doughnut, and more
+- **Images** -- Add from file or set as slide background
+- **Text styling** -- Font, size, color, bold, italic, alignment, spacing
+- **Layout ops** -- Align, distribute, z-order for shape arrangement
+- **Undo/redo** -- Full presentation snapshots with event sourcing
+- **Keynote-compatible** -- Standard PPTX output opens in Keynote, Google Slides, LibreOffice
+
+## Development
+
+```bash
+uv sync
+uv run pytest       # 70 tests
+uv run ruff check   # linting
+uv run pyright      # type checking
+```
+
+## License
+
+MIT

fcp_slides-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "fcp-slides"
+version = "0.1.0"
+description = "Presentation File Context Protocol — semantic slide operations for LLMs"
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    "fcp-core>=0.1.14",
+    "fastmcp>=3.0",
+    "python-pptx>=1.0",
+]
+
+# [tool.uv.sources]
+# For local development, uncomment below:
+# fcp-core = { path = "../fcp-core/python", editable = true }
+
+[project.scripts]
+fcp-slides = "fcp_slides.main:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.4",
+    "pyright>=1.1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fcp_slides"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+src = ["src"]

fcp_slides-0.1.0/src/fcp_slides/__main__.py

@@ -0,0 +1,3 @@
+from fcp_slides.main import main
+
+main()

fcp_slides-0.1.0/src/fcp_slides/adapter.py

@@ -0,0 +1,149 @@
+"""SlidesAdapter — FcpDomainAdapter implementation for python-pptx presentations.
+
+Bridges fcp-core to python-pptx via SlidesModel (thin wrapper for in-place
+undo/redo). Handles batch atomicity and snapshot-based undo/redo.
+"""
+
+from __future__ import annotations
+
+from pptx import Presentation
+
+from fcp_core import EventLog, OpResult, ParsedOp
+
+from fcp_slides.lib.units import format_length
+from fcp_slides.model.index import SlideIndex
+from fcp_slides.model.snapshot import SlidesModel, SnapshotEvent
+from fcp_slides.server.queries import dispatch_query
+from fcp_slides.server.resolvers import SlidesOpContext
+
+# Import all handler dicts
+from fcp_slides.server.ops_slides import HANDLERS as SLIDES_HANDLERS
+from fcp_slides.server.ops_shapes import HANDLERS as SHAPES_HANDLERS
+from fcp_slides.server.ops_text import HANDLERS as TEXT_HANDLERS
+from fcp_slides.server.ops_tables import HANDLERS as TABLES_HANDLERS
+from fcp_slides.server.ops_charts import HANDLERS as CHARTS_HANDLERS
+from fcp_slides.server.ops_images import HANDLERS as IMAGES_HANDLERS
+from fcp_slides.server.ops_layout import HANDLERS as LAYOUT_HANDLERS
+from fcp_slides.server.ops_style import HANDLERS as STYLE_HANDLERS
+from fcp_slides.server.ops_notes import HANDLERS as NOTES_HANDLERS
+
+# Max snapshot events in undo history
+MAX_EVENTS = 15
+
+
+class SlidesAdapter:
+    """FcpDomainAdapter[SlidesModel, SnapshotEvent] for presentation operations."""
+
+    def __init__(self) -> None:
+        self.index = SlideIndex()
+
+        # Merge all verb handlers
+        self._handlers: dict[str, callable] = {}
+        for h in (
+            SLIDES_HANDLERS, SHAPES_HANDLERS, TEXT_HANDLERS,
+            TABLES_HANDLERS, CHARTS_HANDLERS, IMAGES_HANDLERS,
+            LAYOUT_HANDLERS, STYLE_HANDLERS, NOTES_HANDLERS,
+        ):
+            self._handlers.update(h)
+
+    # -- FcpDomainAdapter protocol --
+
+    def create_empty(self, title: str, params: dict[str, str]) -> SlidesModel:
+        """Create a new empty presentation."""
+        prs = Presentation()
+        model = SlidesModel(title=title, prs=prs)
+        self.index.clear()
+        return model
+
+    def serialize(self, model: SlidesModel, path: str) -> None:
+        """Save presentation to file."""
+        model.prs.save(path)
+        model.file_path = path
+
+    def deserialize(self, path: str) -> SlidesModel:
+        """Load presentation from file."""
+        prs = Presentation(path)
+        # Extract title from path
+        title = path.rsplit("/", 1)[-1]
+        model = SlidesModel(title=title, prs=prs)
+        model.file_path = path
+        self.index.rebuild(model)
+        return model
+
+    def rebuild_indices(self, model: SlidesModel) -> None:
+        """Rebuild index after undo/redo."""
+        self.index.rebuild(model)
+
+    def get_digest(self, model: SlidesModel) -> str:
+        """Return a compact state fingerprint."""
+        prs = model.prs
+        slide_count = len(prs.slides)
+        shape_count = sum(len(list(s.shapes)) for s in prs.slides)
+        active = self.index.active_slide + 1
+        size = ""
+        if prs.slide_width and prs.slide_height:
+            size = f", Size: {format_length(prs.slide_width)}x{format_length(prs.slide_height)}"
+        return f"Active: slide {active}, Slides: {slide_count}, Shapes: {shape_count}{size}"
+
+    def dispatch_op(
+        self, op: ParsedOp, model: SlidesModel, log: EventLog
+    ) -> OpResult:
+        """Execute a parsed operation on the model."""
+        handler = self._handlers.get(op.verb)
+        if handler is None:
+            from fcp_core import suggest
+            s = suggest(op.verb, list(self._handlers.keys()))
+            msg = f"Unknown verb: {op.verb!r}"
+            if s:
+                msg += f"\n  try: {s}"
+            return OpResult(success=False, message=msg)
+
+        # Take pre-op snapshot
+        before = model.snapshot()
+
+        # Build context
+        ctx = SlidesOpContext(
+            prs=model.prs,
+            index=self.index,
+            model=model,
+        )
+
+        # Dispatch
+        try:
+            result = handler(op, ctx)
+        except NotImplementedError as exc:
+            return OpResult(success=False, message=str(exc))
+        except (ValueError, KeyError, TypeError, AttributeError) as exc:
+            return OpResult(success=False, message=f"Error: {exc}")
+
+        if not result.success:
+            return result
+
+        # Log snapshot for undo
+        after = model.snapshot()
+        log.append(SnapshotEvent(before=before, after=after, summary=op.raw))
+
+        return result
+
+    def take_snapshot(self, model: SlidesModel) -> bytes:
+        """Return byte snapshot for batch rollback."""
+        return model.snapshot()
+
+    def restore_snapshot(self, model: SlidesModel, snapshot: bytes) -> None:
+        """Restore model from snapshot and rebuild indices."""
+        model.restore(snapshot)
+        self.rebuild_indices(model)
+
+    def dispatch_query(self, query: str, model: SlidesModel) -> str:
+        """Execute a query against the model."""
+        return dispatch_query(query, model, self.index)
+
+    def reverse_event(self, event: SnapshotEvent, model: SlidesModel) -> None:
+        """Undo — restore from before-snapshot."""
+        model.restore(event.before)
+        self.index.rebuild(model)
+
+    def replay_event(self, event: SnapshotEvent, model: SlidesModel) -> None:
+        """Redo — restore from after-snapshot."""
+        model.restore(event.after)
+        self.index.rebuild(model)

fcp_slides-0.1.0/src/fcp_slides/lib/chart_types.py

@@ -0,0 +1,40 @@
+"""Chart type mapping for presentation charts.
+
+Maps friendly names to python-pptx chart type constants.
+"""
+
+from __future__ import annotations
+
+from pptx.enum.chart import XL_CHART_TYPE
+
+# Friendly name → XL_CHART_TYPE constant
+CHART_TYPES: dict[str, int] = {
+    "column": XL_CHART_TYPE.COLUMN_CLUSTERED,
+    "column-stacked": XL_CHART_TYPE.COLUMN_STACKED,
+    "column-100": XL_CHART_TYPE.COLUMN_STACKED_100,
+    "bar": XL_CHART_TYPE.BAR_CLUSTERED,
+    "bar-stacked": XL_CHART_TYPE.BAR_STACKED,
+    "bar-100": XL_CHART_TYPE.BAR_STACKED_100,
+    "line": XL_CHART_TYPE.LINE,
+    "line-markers": XL_CHART_TYPE.LINE_MARKERS,
+    "line-stacked": XL_CHART_TYPE.LINE_STACKED,
+    "pie": XL_CHART_TYPE.PIE,
+    "pie-exploded": XL_CHART_TYPE.PIE_EXPLODED,
+    "doughnut": XL_CHART_TYPE.DOUGHNUT,
+    "area": XL_CHART_TYPE.AREA,
+    "area-stacked": XL_CHART_TYPE.AREA_STACKED,
+    "scatter": XL_CHART_TYPE.XY_SCATTER,
+    "scatter-lines": XL_CHART_TYPE.XY_SCATTER_LINES,
+    "radar": XL_CHART_TYPE.RADAR,
+    "radar-filled": XL_CHART_TYPE.RADAR_FILLED,
+}
+
+
+def resolve_chart_type(name: str) -> int | None:
+    """Resolve a friendly chart type name to XL_CHART_TYPE constant."""
+    return CHART_TYPES.get(name.lower())
+
+
+def list_chart_types() -> list[str]:
+    """Return sorted list of available chart type names."""
+    return sorted(CHART_TYPES.keys())

fcp_slides-0.1.0/src/fcp_slides/lib/colors.py

@@ -0,0 +1,57 @@
+"""Named color palette and hex parsing for presentation formatting."""
+
+from __future__ import annotations
+
+from pptx.util import Pt
+from pptx.dml.color import RGBColor
+
+# Standard Office/PowerPoint color palette
+NAMED_COLORS: dict[str, str] = {
+    "blue": "4472C4",
+    "orange": "ED7D31",
+    "gray": "A5A5A5",
+    "gold": "FFC000",
+    "lt-blue": "5B9BD5",
+    "green": "70AD47",
+    "red": "FF0000",
+    "dk-green": "00B050",
+    "white": "FFFFFF",
+    "black": "000000",
+    "yellow": "FFFF00",
+    "purple": "7030A0",
+    "teal": "00B0F0",
+    "dk-blue": "002060",
+    "dk-red": "C00000",
+    "lt-gray": "D9D9D9",
+    "dk-gray": "404040",
+}
+
+
+def parse_color(color_str: str) -> str:
+    """Parse a color string to a 6-char hex value (no #).
+
+    Accepts:
+      - Named colors: "blue", "red"
+      - Hex with #: "#4472C4"
+      - Hex without #: "4472C4"
+      - 3-char shorthand: "F0F" → "FF00FF"
+    """
+    name = color_str.lower().strip()
+    if name in NAMED_COLORS:
+        return NAMED_COLORS[name]
+
+    hex_str = color_str.lstrip("#").strip()
+
+    if len(hex_str) == 6 and all(c in "0123456789ABCDEFabcdef" for c in hex_str):
+        return hex_str.upper()
+
+    if len(hex_str) == 3 and all(c in "0123456789ABCDEFabcdef" for c in hex_str):
+        return "".join(c + c for c in hex_str).upper()
+
+    raise ValueError(f"Invalid color: {color_str!r}")
+
+
+def to_rgb(color_str: str) -> RGBColor:
+    """Parse a color string directly to an RGBColor object."""
+    hex_str = parse_color(color_str)
+    return RGBColor.from_string(hex_str)

fcp_slides-0.1.0/src/fcp_slides/lib/layout_names.py

@@ -0,0 +1,72 @@
+"""Slide layout name resolution.
+
+Maps friendly names to slide layout indices in standard PowerPoint templates.
+Falls back to fuzzy matching against the actual layout names in the presentation.
+"""
+
+from __future__ import annotations
+
+from difflib import SequenceMatcher
+
+# Friendly name → common layout name in standard templates
+LAYOUT_ALIASES: dict[str, str] = {
+    "title": "Title Slide",
+    "title-slide": "Title Slide",
+    "title-content": "Title and Content",
+    "section": "Section Header",
+    "section-header": "Section Header",
+    "two-content": "Two Content",
+    "comparison": "Comparison",
+    "title-only": "Title Only",
+    "blank": "Blank",
+    "content-caption": "Content with Caption",
+    "picture-caption": "Picture with Caption",
+}
+
+
+def resolve_layout(name: str, prs) -> "SlideLayout | None":
+    """Resolve a layout name to a SlideLayout object.
+
+    Tries in order:
+      1. Friendly alias (e.g., "title" → "Title Slide")
+      2. Exact match against actual layout names
+      3. Case-insensitive match
+      4. Fuzzy match (>0.6 similarity)
+
+    Returns None if no match found.
+    """
+    # Try alias first
+    alias = LAYOUT_ALIASES.get(name.lower())
+    target = alias or name
+
+    layouts = prs.slide_layouts
+
+    # Exact match
+    for layout in layouts:
+        if layout.name == target:
+            return layout
+
+    # Case-insensitive match
+    target_lower = target.lower()
+    for layout in layouts:
+        if layout.name.lower() == target_lower:
+            return layout
+
+    # Fuzzy match
+    best_match = None
+    best_score = 0.0
+    for layout in layouts:
+        score = SequenceMatcher(None, target_lower, layout.name.lower()).ratio()
+        if score > best_score:
+            best_score = score
+            best_match = layout
+
+    if best_match and best_score > 0.6:
+        return best_match
+
+    return None
+
+
+def list_layouts(prs) -> list[str]:
+    """Return list of available layout names in the presentation."""
+    return [layout.name for layout in prs.slide_layouts]