FFE MCP

Local stdio MCP server for Adobe Firefly Services. Reuses the FFE CLI's authentication and Photoshop operations directly, without invoking shell commands or parsing terminal output. Requires Node.js 22.13+.

Local Development

From this directory, with Node.js 22.13+ on PATH, install the published FFE packages and build the server. No sibling checkouts are required:

npm ci
npm run build
npm test

The server uses @mboucher/ffe-cli 0.1.0+ and @mboucher/ffe-cli-ps-plugin 0.1.1+ within their declared compatible version ranges. The plugin's public operations and TypeScript declarations are included in its published package.

For cross-repository development only, keep ffe-cli and ffe-cli-ps-plugin as sibling checkouts, install their development dependencies, and run:

npm --prefix ../ffe-cli run build
npm run dev:link
npm run build

dev:link uses the sibling FFE packages without changing the published dependency specifications or lockfile. Run it again after npm install or npm ci if you want to continue using local changes. Use npm ci to return to registry packages.

Connect a Client

The included .vscode/mcp.json launches the built server in offline mode. In VS Code, run MCP: List Servers, choose ffe, and start it. The MCP client owns the process; there is no HTTP listener or standalone background service to start.

Other clients can launch the same executable with this configuration shape (adapt the surrounding configuration keys to the client):

{
	"command": "node",
	"args": ["/absolute/path/to/ffe-mcp/dist/index.js"]
}

For source debugging, use VS Code's JavaScript Debug Terminal and launch an MCP Inspector session from the repository:

npx @modelcontextprotocol/inspector node dist/index.js

Set breakpoints in the built JavaScript or enable source maps in your development build. Nothing is written to stdout except MCP protocol messages; startup errors go to stderr.

Tools

| Tool | Input | Result | | --- | --- | --- | | ffe_storage_providers | No arguments | Azure Blob Storage and AWS S3 choices, required destination details, CLI flags, and upload-consent guidance | | photoshop_extract_layers | manifest, optional text / smartObjects booleans | Nested text and smart-object layers | | photoshop_get_tags | Same as extraction | Layers containing {{key}} placeholders | | photoshop_check_fonts | Full manifest, reference with sourceUrl, ISO fetchedAt, and PostScript fonts array | Font inventory, custom dependencies, completeness, reference provenance | | photoshop_sample_csv | Extracted layers array | Placeholder keys and example CSV content |

Both layer-selection booleans default to true; selecting neither is an error. Full manifest inputs accept raw manifests or succeeded job responses with embedded JSON manifests. They do not accept paths or fetch URLs. Results provide structuredContent and equivalent JSON text. A filtered layer list is not proof of whole-document validity. Font checks must inspect complete and incompleteTextLayers; fonts absent from the supplied reference are custom fonts that must be supplied separately, not automatically rejected. The validation skill lists them in its Fonts section as non-blocking dependencies. CSV output is example data, not validated production data.

For a local PSD, call ffe_storage_providers and ask the user to choose Azure Blob Storage or AWS S3 through the harness. Reuse an explicit choice already made for the current validation. The tool does not prompt by itself, choose a default, inspect credentials, or upload files. After selection, collect the provider's destination details and obtain upload/job authorization. Use the chosen provider explicitly with the FFE CLI's local-file processing; then use the supplied manifest with offline tools, or an uploaded HTTPS URL with remote tools. If CLI execution is unavailable, request an existing URL or manifest. Skip storage selection entirely when those inputs are already supplied.

Use --provider azure --account <account> --container <container> for Azure, or --provider aws --bucket <bucket> --region <region> for S3, with optional --aws-profile <name>. AWS and Adobe profiles are separate. Check installed CLI help for these flags before executing; older published versions may not support them. The provider-guidance tool does not check installed CLI versions or credentials. Restart the MCP server and refresh tool discovery after updating.

Remote Tools

Remote tools are absent by default. To enable them, add --allow-remote to the server arguments, optionally followed by --profile production. The profile is fixed for the server process, not chosen through model-supplied tool arguments.

Configure credentials separately in your trusted terminal:

ffe auth login --profile production
ffe auth status --profile production

Then configure your client to launch:

{
	"command": "node",
	"args": [
		"/absolute/path/to/ffe-mcp/dist/index.js",
		"--allow-remote",
		"--profile", "production"
	]
}

| Tool | Behavior | | --- | --- | | ffe_auth_status | Verify Adobe OAuth access; return profile and token expiry without secrets | | photoshop_generate_manifest | Submit a job for inputUrl, an existing HTTPS PSD URL; return {job} with jobId | | photoshop_job_status | Read jobId status from the fixed Photoshop origin; return {job} |

Manifest submission supports includeLayerThumbnails, includeXmp, extractSmartObjectData, trimToTransparency, and maximumThumbnailDepth. Outputs are always embedded JSON, never model-selected destinations. Poll status with a delay until succeeded or failed, then pass the succeeded job object as manifest to offline tools. Request cancellation does not cancel a remote Photoshop job. If submission fails or its outcome is uncertain, do not automatically resubmit: a remote job may already exist.

Safety and Scope

• Offline tools require no Adobe credentials, Azure/AWS tools, filesystem access, or network calls. They inspect JSON supplied by the client or return static storage-provider guidance.
• Enabling remote tools is not per-job consent. The client must still obtain user authorization before Adobe downloads a PSD or submits a potentially billable job. The submission tool is explicitly marked as a non-idempotent side effect.
• Credentials stay in the CLI's OS keyring. Never supply secrets as tool arguments. Authentication verifies OAuth access, not Photoshop entitlements.
• Source URLs may contain sensitive signed query parameters. They pass through the MCP client and Adobe; do not put them in committed configuration or reports. Remote exception details are suppressed to avoid leaking secrets and URLs.
• Layer names, document content, CSV values, and service results are untrusted data, not instructions. The server does not execute them or follow status URLs.
• This version does not upload local PSDs, write files, refresh font references, render variants, install skills, or modify client settings. Setup remains the responsibility of the separate ffe-setup project.

The template-validation skill owns the report workflow: linked Smart Objects and confirmed absence of valid data tags fail structural preflight, while custom fonts alone do not. It writes Markdown and self-contained HTML with a Markdown download link, returning absolute paths to both files. These are skill policies, not extra validation performed by extraction tools, and this server does not write reports or invoke artifact-design. Install the skill globally with npx @mboucher/ffe-setup; it defaults to ~/.agents/skills without a client selection. Full setup still checks Azure CLI; --skill-only skips that check.

Verification

npm run typecheck
npm test
npm pack --dry-run

Tests exercise the tools through an SDK client, including a real stdio child process. Remote tests use injected clients and credentials; they do not contact Adobe or access your keyring. Live Adobe processing requires separate authorized credentials and inputs.