mograph-mcp 0.5.0__tar.gz

mograph_mcp-0.5.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Victor Aragon
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mograph_mcp-0.5.0/NOTICE

@@ -0,0 +1,20 @@
+mograph-mcp
+Copyright 2026 Victor Aragon
+
+Licensed under the Apache License, Version 2.0. See LICENSE.
+
+------------------------------------------------------------------------------
+
+This project is not affiliated with, endorsed by, or sponsored by Adobe Inc.
+
+"Adobe", "Adobe Illustrator", "Adobe After Effects", "ExtendScript" and "CEP"
+are trademarks or registered trademarks of Adobe Inc. They are used here only
+to describe what this software interoperates with, which is the "reasonable and
+customary use in describing the origin of the Work" that section 6 of the
+License allows. No trademark rights are granted by that license.
+
+This project ships no Adobe code. It talks to Illustrator and After Effects
+through the scripting interfaces Adobe publishes for that purpose (COM /
+`do javascript` for Illustrator, a CEP panel for After Effects), and requires a
+separate, valid installation of those applications, obtained from Adobe under
+Adobe's own terms.

mograph_mcp-0.5.0/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: mograph-mcp
+Version: 0.5.0
+Summary: MCP server to control Adobe Illustrator and After Effects, including an Illustrator-to-After-Effects transfer that keeps bezier curves, strokes and gradients.
+Author: Victor Aragon
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://gitlab.com/vic-lab/mograph-mcp
+Project-URL: Repository, https://gitlab.com/vic-lab/mograph-mcp
+Project-URL: Issues, https://gitlab.com/vic-lab/mograph-mcp/issues
+Project-URL: Changelog, https://gitlab.com/vic-lab/mograph-mcp/blob/main/CHANGELOG.md
+Keywords: mcp,model-context-protocol,illustrator,after-effects,adobe,extendscript,motion-graphics,animation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: mcp<3,>=2
+Requires-Dist: pywin32>=306; platform_system == "Windows"
+Requires-Dist: websockets>=12.0
+Requires-Dist: pillow>=10.0
+Requires-Dist: typing_extensions>=4.6; python_version < "3.12"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# mograph
+
+An MCP server that drives **Adobe Illustrator** and **Adobe After Effects**, and
+moves artwork between them.
+
+The interesting part is not that it can draw a rectangle. It is
+**`ai_to_ae_push`**: it takes what you have selected in Illustrator and rebuilds
+it in an After Effects comp as editable shape layers — real bezier curves,
+strokes, gradients, the group hierarchy recreated as parented nulls — and then
+`ai_to_ae_verify` renders both sides and tells you how far apart they are, with
+a number instead of an opinion.
+
+It was built against a real 52-artboard storyboard, and most of what is in here
+exists because that file broke something.
+
+> **Not affiliated with Adobe.** "Adobe", "Illustrator" and "After Effects" are
+> trademarks of Adobe Inc. This is an independent project that automates
+> applications you already own, using Adobe's own scripting interfaces.
+
+**Protocol:** implements MCP revision **2026-07-28**, on the official Python SDK
+2.x (`mcp>=2,<3`). Transport is stdio only — this drives desktop applications, so
+it is bound to one machine by design.
+
+## Status
+
+| | Windows | macOS |
+|---|---|---|
+| Illustrator (`ai_*`) | ✅ tested end to end (COM) | ⚠️ implemented, **never run** (osascript) |
+| After Effects (`ae_*`) | ✅ tested (CEP + WebSocket) | ⚠️ should work — CEP is cross-platform — but untested |
+| Illustrator → After Effects (`ai_to_ae_*`) | ✅ tested against a real client file | ⚠️ untested |
+| Unit tests | ✅ | ✅ (no Adobe needed, run anywhere) |
+
+macOS is written and unverified. That is not a soft "should be fine": nobody has
+run it. The known risks are itemised in [`AGENTS.md`](AGENTS.md).
+
+---
+
+## Install
+
+Requires Python 3.10+ and the Adobe applications you intend to drive.
+
+```bash
+pip install mograph-mcp
+```
+
+Then point your MCP client at the `mograph-mcp` command. For Claude Code:
+
+```bash
+claude mcp add mograph -- mograph-mcp
+```
+
+There are registration scripts for Codex CLI, Claude Desktop and ZCode in
+`scripts/`, and `mograph-mcp doctor` reports what this machine can and cannot
+do without changing anything.
+
+Illustrator needs nothing else — it is driven over COM on Windows and
+`osascript` on macOS. After Effects needs the panel below.
+
+## After Effects: the panel
+
+After Effects has no COM interface, so this talks to it through a small CEP
+extension that runs inside the application and connects back to the server over
+a local WebSocket.
+
+```bash
+mograph-mcp install-panel
+```
+
+Then restart After Effects and open **Window → Extensions → mograph bridge**. It
+should say *"Connected and authenticated"*.
+
+> ### Read this before installing the panel
+>
+> `install-panel` copies the panel in place, which Adobe treats as unsigned, so
+> it enables `PlayerDebugMode`. That setting tells CEP to load unsigned
+> extensions — **all** of them, not just this one — and it stays on after the
+> panel is removed. It is a defence in your Adobe installation being lowered.
+>
+> A **signed `.zxp`** avoids it: build one with `python scripts/sign_panel.py`
+> and install it with ZXPInstaller or ExManCmd. See [`docs/panel.md`](docs/panel.md).
+> If neither trade is acceptable, skip the panel entirely: everything on the
+> Illustrator side works without it.
+
+Details, the manual install, and what each disconnect code means are in
+[`docs/panel.md`](docs/panel.md).
+
+---
+
+## What it can do
+
+The authoritative list is what the server returns from `tools/list`. A
+hand-written inventory rots — this README once claimed 33 tools. By family:
+
+**Illustrator (`ai_*`, 57 tools).** Documents, layers and items; export.
+Inspection and triage of a delivered file (`ai_inspect_document`,
+`ai_audit_for_animation`, `ai_audit_structure`). **Grouping derived from
+geometry** for when the file's hierarchy does not match what the eye reads as one
+thing (`ai_cluster_items` + `ai_apply_clusters`). Naming that survives the trip
+(`ai_auto_name_items`, `ai_propagate_names`). Reading frames and comparing them
+(`ai_frame_tree`, `ai_diff_frames`, `ai_track_frames`). Layout and reframing.
+
+**After Effects (`ae_*`, 51 tools).** Projects, comps, layers; effects and
+expressions; keyframes, easing and interpolation. **`ae_animate`** writes
+entrances and exits with anticipation, overshoot and settle — the parts that are
+not in a storyboard and are what makes an interpolation stop looking dead.
+**`ae_stagger`** orders layers by where they *actually* are in the comp, walking
+the parent chain. Anchors and parenting, render queue, headless `aerender`.
+
+**Between them (`ai_to_ae_*`, 2 tools).** `ai_to_ae_push` and `ai_to_ae_verify`,
+described at the top. The coordinate maths — the Y flip, artboard-to-comp
+scaling, bezier handles to tangents, gradient endpoints — lives in `mapping.py`
+as pure functions with unit tests, so it is verifiable without either
+application.
+
+### Renders come back as images
+
+`ai_see_document`, `ae_see_frame` and `ai_contact_sheet` return the PNG inline,
+not just a path on disk. A path only works if the client happens to have
+filesystem access and happens to think of reading it, and the protocol promises
+neither — which is a poor foundation for the tool that everything else is
+verified with.
+
+They are downscaled to `max_dim=1024` on the long side by default; the file path
+is still in the reply, and `max_dim=0` restores the old path-only behaviour.
+
+### The long notes are a resource, not a tax
+
+Several tools carry substantial field notes — the traps, why each default is
+what it is, what broke last time. Those are the most valuable thing here and
+they used to be paid for, in tokens, at the start of every session whether or not
+you ever called the tool.
+
+Now `tools/list` carries what a tool does and when to use it, and the rest is
+served on demand:
+
+- `docs://guia` — which tools have extended notes
+- `docs://tools/<name>` — the full notes for one
+
+Nothing was deleted; there is one copy of each docstring and a test fails if a
+paragraph goes missing.
+
+---
+
+## Choosing what gets exposed
+
+The full set is ~20,000 tokens of `tools/list`, paid at connect time before the
+first question. A session that will only touch one application does not need the
+other half:
+
+```bash
+MOGRAPH_TOOLS=ai            # Illustrator only  -> 57 tools, ~9,000 tokens
+MOGRAPH_TOOLS=ae            # After Effects only
+MOGRAPH_TOOLS=ai,symbiosis  # Illustrator plus the transfer
+MOGRAPH_TOOLS=all           # everything (default)
+```
+
+An invalid name is a startup error rather than an empty server: exposing zero
+tools looks exactly like a broken installation.
+
+Every tool ships `annotations` and a readable title, so a client can auto-approve
+the reads and ask only about the mutations. Without that, all of them look
+equally dangerous and people approve everything without reading.
+
+Failures arrive as protocol errors (`isError`), not as successful calls with
+`ok: false` buried in the body.
+
+---
+
+## Security
+
+Short version: **local only, the bridge is authenticated, and two tools can run
+arbitrary code.** The full threat model — including why a web page you visit was
+the attacker that mattered — is in [`SECURITY.md`](SECURITY.md).
+
+| Variable | Default | What it does |
+|---|---|---|
+| `MOGRAPH_ALLOW_RAW_SCRIPT` | `1` | `0` drops `ai_run_script` and `ae_run_script` |
+| `MOGRAPH_PORT_TAKEOVER` | `0` | `1` kills whatever holds the bridge port |
+| `MOGRAPH_BRIDGE_AUTH` | `1` | `0` accepts an unauthenticated panel — **unsafe** |
+| `MOGRAPH_WS_PORT` | `9123` | Bridge port; must match the panel |
+| `MOGRAPH_AI_APPNAME` | `Adobe Illustrator` | macOS only, if the app name does not match |
+
+---
+
+## Development
+
+```bash
+python -m pytest tests/ -q        # no Adobe required
+python -m ruff check .
+```
+
+With both applications open and the panel connected:
+
+```bash
+python scripts/smoke_fidelity_ai.py   # Illustrator only, does not touch the bridge port
+python scripts/smoke_fidelity_ae.py   # round trip, reads bezier + stroke back out of AE
+python scripts/smoke_gradient.py      # gradient round trip
+```
+
+`dev_reload` swaps the backend code in place without restarting the client,
+which covers most of the debugging loop. It cannot add or rename a tool — the
+list is handed to the client once, at connect time.
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md), [`AGENTS.md`](AGENTS.md) for the
+accumulated field notes, and [`ROADMAP.md`](ROADMAP.md) for known work.
+
+---
+
+## Troubleshooting
+
+**The AE tools say no panel is connected.** Open After Effects and the `mograph
+bridge` panel. If the panel says `code 4401`, After Effects is still running the
+old `main.js` from memory — restart it. `4409` means another server already has a
+panel. `mograph-mcp doctor` names which panels are installed, which port each one
+dials, and whether a session token is present; [`docs/panel.md`](docs/panel.md)
+covers the rest.
+
+**The bridge port is busy.** The error names the PID holding it. Stop that
+process, or set `MOGRAPH_PORT_TAKEOVER=1` to have it killed.
+
+**Illustrator does not connect.** On Windows COM launches it. On macOS, if you
+have several versions installed and it picks the wrong one, set
+`MOGRAPH_AI_APPNAME="Adobe Illustrator 2026"`. A macOS error `-1743` is the
+Automation permission prompt: approve it in System Settings → Privacy & Security
+→ Automation.
+
+**Shapes land in the wrong place after a push.** The mapping scales the artboard
+onto the comp. If their aspect ratios differ, it distorts — use a comp the same
+size as the artboard.
+
+**A gradient lost a colour.** Only the first and last stop survive: After
+Effects will not let scripting touch a shape layer's multi-stop gradient. The
+geometry is not the problem -- that transfers exactly. Check `degraded` in the
+push reply, which names each flattened layer and the colours it dropped, and
+rasterize in Illustrator if the middle colours carry the design.
+
+---
+
+## Known limitations
+
+- **Gradients keep their geometry and lose their middle stops.** Measured
+  against the applications: a two-stop gradient, linear or radial, arrives with
+  a mean channel error of 0.2/255 -- the angle, extent and centre are exact. A
+  three-stop one arrives at 19.8/255, because only the first and last colours
+  survive. After Effects does not expose a shape layer's multi-stop gradient to
+  scripting at all (`Colors` reports `NO_VALUE` and refuses both get and set),
+  so this is a limit of the host. The push reports every gradient it flattened
+  and names the colours it dropped. Patterns, brushes and mesh objects are
+  skipped with a warning.
+- **After Effects' first launch** takes 20–40s; the bridge waits 60s
+  (`MOGRAPH_EVAL_TIMEOUT`).
+- **One panel at a time**, by design — a second connection is refused rather
+  than silently displacing the first.
+- **No live feedback.** Nothing reacts to events in the applications; every
+  exchange starts from a tool call.
+- **macOS is untested.** See the table at the top.
+
+---
+
+## Licence
+
+[Apache-2.0](LICENSE). "Adobe", "Illustrator" and "After Effects" are
+trademarks of Adobe Inc.; this project is not affiliated with them and ships no
+Adobe code. See [`NOTICE`](NOTICE).