ZURAVFX/zura-premiere-reels

Develop Premiere Pro MCP

Make focused, evidence-backed changes to this TypeScript MCP server. Preserve unrelated worktree changes and distinguish automated verification from behavior proven in a live Premiere Pro host.

Orient to the repository

1. Read AGENTS.md first, then README.md, SECURITY.md, CONTRIBUTING.md, and RESEARCH.md only as needed for the task. Treat current source and release metadata as authoritative over dated snapshots.
2. Inspect git status before editing. Do not stage, rewrite, or remove unrelated work.
3. Trace the relevant path before changing it:
   • src/server.ts assembles the MCP surface.
   • src/tools/ contains tool schemas and handlers.
   • src/bridge/ implements host communication.
   • cep-plugin/ is the broad production bridge.
   • uxp-plugin/ is capability-aware and supports only its declared Premiere APIs.
4. Use Node.js 24 for development when available; preserve the package's Node 20.19+ runtime floor. Install deterministically with npm ci when dependencies are missing.

Implement safely

• Reuse nearby helpers and module patterns before adding abstractions or dependencies.
• Keep tool schemas, descriptions, registrations, structured results, authority profiles, tests, documentation, generated catalogs, and reported counts synchronized.
• Generate ExtendScript as ECMAScript 3: use var, traditional functions and loops, and avoid arrows, let, const, template literals, and other modern runtime syntax.
• Escape every user-controlled string with existing helpers before embedding it in a generated script. Never interpolate raw paths, names, expressions, or prompts.
• Keep raw scripting disabled unless the explicit unsafe-script capability is enabled.
• Prefer documented Premiere APIs. Label QE DOM behavior experimental.
• Verify mutation postconditions. Do not treat a host API return value alone as proof of success, and do not silently fall back from failed UXP work to CEP or QE.
• Premiere metadata is several documented surfaces, not one blob: Project-panel column JSON (getProjectColumnsMetadata), Premiere-private project metadata XML, file/clip XMP, panel-layout/schema XML, plus adjacent color-label, interpretation, marker, and transcript tools. Documented ppro.Metadata.* methods are already mapped. Do not wrap undocumented QE metadata, dump unbounded packets, or treat premiere://project/metadata as XMP. Field-level inspect/update is bounded (uxp.XMPMeta / AdobeXMPScript, 256 fields, sensitive EXIF omitted by default, field readback). CEP still accepts a complete XML payload plus updatedFields. Adobe exposes no field-level schema enumerator. Keep C2PA as beta until a stable host pin exists. When adding metadata behavior, update src/workflows/agent-instructions.ts, the workflow catalog prompt, and both edit-premiere-project skill copies together.
• Preserve private-directory ownership checks, authentication, size limits, secret handling, and telemetry privacy. Never collect prompts, arguments, results, tokens, IP addresses, project paths, media names, or person profiles.

Test proportionally

1. Add or update tests for behavior, failure paths, validation, escaping, authorization, registration, and metadata affected by the change.
2. Run the narrowest relevant tests while iterating.
3. Run npm run check before completion. Run npm run test:coverage when changing coverage-sensitive behavior.
4. Inspect the final diff and status so generated output or unrelated files are not included accidentally.
5. Treat build, unit tests, mocks, and CI as package evidence only. Require a supported Premiere host and the applicable running CEP or UXP bridge for live-host claims.

Handle releases and compatibility claims

• Follow docs/release-conventions.md: GitHub release titles equal their Git tags, exactly v<SemVer> (for example, v1.19.0 or v1.20.0-rc.1). Put summaries in release bodies; omit v in package and manifest versions. Preserve the README ### Latest release: heading and existing changelog heading format.
• Use scripts/normalize-release-names.mjs to preview title drift, --check to fail on drift, and --apply for authorized repairs with GitHub readback. Historical cleanup edits display titles only; never retag or republish existing versions. A naming task does not authorize a new publication.
• Search all version-bearing package, lock, manifest, marketplace, MCP configuration, updater, and installation files when changing a version.
• After an npm release is verified, update the README ### Latest release: heading, README install commands, both plugin .mcp.json pins, and both edit-premiere-project skill pins together; tests/release-metadata.test.ts and tests/codex-plugin.test.ts guard them.
• The website lives in leancoderkavy/premiere-pro-mcp-site and syncs published npm facts automatically. Do not edit site facts from this repository.
• Verify the exact commit, checks, registry artifact, release assets, deployment health, and host state separately when the task includes those outcomes.
• Never claim a commit, push, merge, publication, deployment, or live Premiere result without direct evidence from that layer.
• Report what changed, exact checks run, failures or skipped checks, and whether live CEP or UXP verification was performed.