Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions gatsby-config.js
Original file line number Diff line number Diff line change
Expand Up @@ -601,6 +601,10 @@ module.exports = {
},
],
},
{
title: "Dev MCP Server",
path: "guides/getting_started/local_development/mcp_server.md",
},
{
title: "Local Development",
path: "guides/getting_started/local_development/dev_tooling.md",
Expand All @@ -609,10 +613,7 @@ module.exports = {
title: "Development tools",
path: "guides/getting_started/local_development/dev_tooling.md",
},
{
title: "Adobe Express Add-on MCP Server (Beta)",
path: "guides/getting_started/local_development/mcp_server.md",
},

{
title: "Browser debugging",
path: "guides/getting_started/local_development/browser.md",
Expand Down
6 changes: 6 additions & 0 deletions src/pages/guides/getting_started/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,12 @@ contributors:

# Changelog

## 2026-01-09

### Updated

- **[Adobe Express Developer MCP Server](./local_development/mcp_server.md) is now generally available**. The MCP server (formerly known as Adobe Express Add-on MCP Server Beta) has been renamed and is now released as a stable, production-ready version. Learn how to set up and use it for an enhanced development workflow in compatible editors like Cursor.

## 2025-12-28

### Added
Expand Down
176 changes: 88 additions & 88 deletions src/pages/guides/getting_started/local_development/mcp_server.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,15 @@ keywords:
- Code Generation
- TypeScript Definitions
- IDE
title: Adobe Express Add-on MCP Server (Beta)
title: Adobe Express Developer MCP Server
description: Learn how to set up and use the Adobe Express Add-on MCP Server for enhanced development workflow in compatible editors like Cursor.
contributors:
- https://github.com/hollyschinsky
---

# Adobe Express Add-on MCP Server (Beta)
# Adobe Express Developer MCP Server

**Status: Public Beta** Get Adobe Express Add-ons documentation and TypeScript definitions directly in your AI-assisted IDE through the Model Context Protocol (MCP). Build faster with grounded answers and accurate code suggestions.
Get Adobe Express Add-ons documentation and TypeScript definitions directly in your AI-assisted IDE through the Model Context Protocol (MCP). Build faster with grounded answers and accurate code suggestions.

## TL;DR - Quick Setup

Expand Down Expand Up @@ -57,15 +57,15 @@ If you are already familiar with the concepts of Model Context Protocol (MCP) an

<InlineAlert variant="info" slots="header, text1"/>

💬 **Feedback requested:**
💬 **Feedback requested:**

We're actively collecting input to improve accuracy and coverage. Have feedback? Please join our [Adobe Express Add-on Developers Discord](https://discord.com/invite/nc3QDyFeb4) for real-time chat with the team and community and share your thoughts!<br/>

## What it does

> "*Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools."* — [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro)<br/>
> "_Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools."_ — [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro)<br/>

The **Adobe Express Add-on MCP Server (Beta)** acts as a bridge between your LLM (AI assistant) and Adobe Express add-on developer resources. It requires an MCP-compatible IDE with an LLM of your choice to provide accurate, context-aware answers for coding, debugging, and building full-fledged add-ons, quickly.
The **Adobe Express Developer MCP Server** acts as a bridge between your LLM (AI assistant) and Adobe Express add-on developer resources. It requires an MCP-compatible IDE with an LLM of your choice to provide accurate, context-aware answers for coding, debugging, and building full-fledged add-ons, quickly.

The MCP Server communicates directly with your LLM to enhance its responses by connecting your IDE to the Adobe Express Add-on ecosystem, providing capabilities to ask questions and generate code with:

Expand Down Expand Up @@ -154,12 +154,12 @@ Add this to your workspace in `~/.vscode/mcp.json`:
<!-- <div className="container">
<div className="text-column">
<h3>Verify with Tool calls</h3>
<p>The LLM will automatically invoke tools based on your prompts.Here is an example of Cursor making calls to the Adobe Express Add-on MCP Server (Beta) tools to retrieve the developer documentation and type definitions. The expanded tool calls reveal the results of either the documentation source that matched the query, or the typescript definitions for the specific API in the parameters.</p>
<p>The LLM will automatically invoke tools based on your prompts.Here is an example of Cursor making calls to the Adobe Express Developer MCP Server tools to retrieve the developer documentation and type definitions. The expanded tool calls reveal the results of either the documentation source that matched the query, or the typescript definitions for the specific API in the parameters.</p>
</div> -->

#### Verify with Tool calls

The LLM will automatically invoke tools based on your prompts. Here is an example of Cursor making calls to the Adobe Express Add-on MCP Server (Beta) tools to retrieve the developer documentation and type definitions based on the query. The expanded tool calls reveal the results of either the documentation source that matched the query, or the typescript definitions for the specific API in the parameters.
The LLM will automatically invoke tools based on your prompts. Here is an example of Cursor making calls to the Adobe Express Developer MCP Server tools to retrieve the developer documentation and type definitions based on the query. The expanded tool calls reveal the results of either the documentation source that matched the query, or the typescript definitions for the specific API in the parameters.

<div className="container">
<div className="image-column">
Expand All @@ -172,10 +172,10 @@ The LLM will automatically invoke tools based on your prompts. Here is an exampl

<InlineNestedAlert header="true" variant="success" iconPosition="right">

**Tips:**
**Tips:**

- Ask the LLM to "*list MCP tools*".
- If you have multiple MCP servers, say: "*Use the MCP server named Adobe Express Add-on*".
- Ask the LLM to "_list MCP tools_".
- If you have multiple MCP servers, say: "_Use the MCP server named Adobe Express Add-on_".

</InlineNestedAlert>

Expand All @@ -187,27 +187,27 @@ The **Adobe Express Add-on MCP Server** excels at both helping with answering qu

#### Documentation & Learning

- "*How do I create and style text in Adobe Express*?"
- "*What are the steps for implementing drag-and-drop functionality*?"
- "*How does the Document API work for manipulating elements*?"
- "*Show me examples of using the color picker component*?"
- "_How do I create and style text in Adobe Express_?"
- "_What are the steps for implementing drag-and-drop functionality_?"
- "_How does the Document API work for manipulating elements_?"
- "_Show me examples of using the color picker component_?"

#### Code Generation & Implementation

- "*Implement a color picker in my add-on*"
- "*Generate code to create a text element with custom styling*"
- "*Build a drag-and-drop interface for uploading images*"
- "*Create a button that adds a rectangle to the canvas*"
- "*Write TypeScript code to handle user text input and apply it to the document*"
- "*Implement an image import feature with file validation*"
- "*Show me a sample code snippet for using a modal dialog*"
- "_Implement a color picker in my add-on_"
- "_Generate code to create a text element with custom styling_"
- "_Build a drag-and-drop interface for uploading images_"
- "_Create a button that adds a rectangle to the canvas_"
- "_Write TypeScript code to handle user text input and apply it to the document_"
- "_Implement an image import feature with file validation_"
- "_Show me a sample code snippet for using a modal dialog_"

#### Debugging & Troubleshooting

- "*Why isn't my add-on loading in Adobe Express?*"
- "*Why isn't my text element appearing on the canvas?*"
- "*Debug this error when trying to add an image to the document (error message: ...)*"
- "*How do I debug an issue in my `code.js` file?*"
- "_Why isn't my add-on loading in Adobe Express?_"
- "_Why isn't my text element appearing on the canvas?_"
- "_Debug this error when trying to add an image to the document (error message: ...)_"
- "_How do I debug an issue in my `code.js` file?_"

## Best Practices for Effective Use

Expand All @@ -227,28 +227,28 @@ The **Adobe Express Add-on MCP Server** excels at both helping with answering qu

**Example of a well-structured prompt:**

> "*I'm building an Adobe Express add-on using JavaScript/TypeScript and React with a UI based on Spectrum Web Components using the Express theme. My user interface needs a text field, a button, a modal dialog and a color picker. Please generate the code and show me how to set it up using the Adobe Add-on CLI.*"
> "_I'm building an Adobe Express add-on using JavaScript/TypeScript and React with a UI based on Spectrum Web Components using the Express theme. My user interface needs a text field, a button, a modal dialog and a color picker. Please generate the code and show me how to set it up using the Adobe Add-on CLI._"

**Key elements to include:**

- **Programming languages**: JavaScript, TypeScript
- **Framework**: React
- **UI components**: Spectrum Web Components with Express theme using [swc-react](https://opensource.adobe.com/spectrum-web-components/using-swc-react/)
- **Specific components needed**: Modal dialog, color picker, buttons, etc.
- **Build tools**: Adobe Add-on CLI for setup and development
- **Programming languages**: JavaScript, TypeScript
- **Framework**: React
- **UI components**: Spectrum Web Components with Express theme using [swc-react](https://opensource.adobe.com/spectrum-web-components/using-swc-react/)
- **Specific components needed**: Modal dialog, color picker, buttons, etc.
- **Build tools**: Adobe Add-on CLI for setup and development

### 2. Craft Effective Prompts

- **Be Specific**: "*Add a stroke to a rectangle*" vs "*Style shapes*"
- **Include Context**: "*I'm building a text editor add-on*" helps narrow results
- **Use Technical Terms**: "*text styling*" vs "*make it look good*"
- **Ask for Examples**: "*Show me code examples for text manipulation*"
- **Request Code Generation**: "*Generate TypeScript code to...*" or "*Implement a feature that...*"
- **Be Specific**: "_Add a stroke to a rectangle_" vs "_Style shapes_"
- **Include Context**: "_I'm building a text editor add-on_" helps narrow results
- **Use Technical Terms**: "_text styling_" vs "_make it look good_"
- **Ask for Examples**: "_Show me code examples for text manipulation_"
- **Request Code Generation**: "_Generate TypeScript code to..._" or "_Implement a feature that..._"

### 3. Manage Your Sessions

- **Keep Sessions Focused**: Start new conversations for different features or topics
- **Be Explicit**: Tell the agent "*For Adobe Express Add-ons questions, prefer the Adobe Express Add-on MCP tools and cite sources.*"
- **Be Explicit**: Tell the agent "_For Adobe Express Add-ons questions, prefer the Adobe Express Add-on MCP tools and cite sources._"
- **Provide Context**: Mention what you're building and your current progress
- **Iterate Gradually**: Build features step-by-step rather than asking for complete applications
- **Avoid Getting Stuck in Debugging Loops**:
Expand All @@ -271,15 +271,15 @@ Custom rules can help guide your LLM's responses, but they require careful desig

- Rules that focus on "never do X" or "cannot do Y" can backfire
- LLMs may over-prioritize avoiding the restriction and neglect coding fundamentals
- Instead of "*Never use inline styles*," try "*Prefer CSS classes and external stylesheets for maintainability*"
- Instead of "_Never use inline styles_," try "_Prefer CSS classes and external stylesheets for maintainability_"

#### 4.1 Example Rules for Cursor

Here are some example rules that have proven helpful for Adobe Express add-on development in Cursor. Feel free to adapt them for your own use:

```text
- Use adobe-express-add-on MCP server for questions about Express Add-ons, Express API, CLI, and SDK before web search.
- Add-ons are bundled and served in the browser as an iFrame.
- Add-ons are bundled and served in the browser as an iFrame.
- Both the Add-on UI and "Express document sandbox" are isolated and must communicate through a proxy layer.
- The term "document" most often refers to terminology related to Express Add-ons since the regular browser DOM isn't available in the sandboxed environment.
```
Expand All @@ -292,93 +292,93 @@ Consider using the following tips in your prompts/rules for LLM guidance when us

<InlineNestedAlert header="true" variant="success" iconPosition="right">

**🤖 LLM Guidance:**
**🤖 LLM Guidance:**

- **CRITICAL:** All `@spectrum-web-components/*` packages MUST use identical versions
- **REQUIRED theme imports:**
- **CRITICAL:** All `@spectrum-web-components/*` packages MUST use identical versions
- **REQUIRED theme imports:**

`import '@spectrum-web-components/theme/express/theme-light.js';`
`import '@spectrum-web-components/theme/express/scale-medium.js';`
`import '@spectrum-web-components/theme/sp-theme.js';`
`import '@spectrum-web-components/theme/express/theme-light.js';`
`import '@spectrum-web-components/theme/express/scale-medium.js';`
`import '@spectrum-web-components/theme/sp-theme.js';`

- Wrap app with: `<sp-theme system="express" scale="medium" color="light">`
- **ALWAYS** check `package.json` for version consistency across **ALL** `@spectrum-web-components/*` packages
- **Use Related References:**
- Wrap app with: `<sp-theme system="express" scale="medium" color="light">`
- **ALWAYS** check `package.json` for version consistency across **ALL** `@spectrum-web-components/*` packages
- **Use Related References:**

- [Spectrum Web Components Documentation](https://opensource.adobe.com/spectrum-web-components/index.html)
- [Using Spectrum Web Components in a basic JavaScript add-on](https://developer.adobe.com/express/add-ons/docs/guides/learn/how_to/tutorials/spectrum-workshop/part1)
- [Adobe Express Add-on UI Implementation Guide](https://developer.adobe.com/express/add-ons/docs/guides/build/design/implementation_guide/)

- [Spectrum Web Components Documentation](https://opensource.adobe.com/spectrum-web-components/index.html)
- [Using Spectrum Web Components in a basic JavaScript add-on](https://developer.adobe.com/express/add-ons/docs/guides/learn/how_to/tutorials/spectrum-workshop/part1)
- [Adobe Express Add-on UI Implementation Guide](https://developer.adobe.com/express/add-ons/docs/guides/build/design/implementation_guide/)

</InlineNestedAlert>

#### Using [swc-react: React Wrappers for SWC](https://opensource.adobe.com/spectrum-web-components/using-swc-react/) (only for add-ons using React)

<InlineNestedAlert header="true" variant="success" iconPosition="right">

**🤖 LLM Guidance:**
**🤖 LLM Guidance:**

- **MANDATORY:** Use `@swc-react/*` components (NOT React Spectrum)
- **CRITICAL:** All `@swc-react/*` packages MUST use identical versions
- **REQUIRED theme setup:**

- **MANDATORY:** Use `@swc-react/*` components (NOT React Spectrum)
- **CRITICAL:** All `@swc-react/*` packages MUST use identical versions
- **REQUIRED theme setup:**
`import '@spectrum-web-components/theme/express/theme-light.js';`
`import '@spectrum-web-components/theme/express/scale-medium.js';`
`import { Theme } from '@swc-react/theme';`

`import '@spectrum-web-components/theme/express/theme-light.js';`
`import '@spectrum-web-components/theme/express/scale-medium.js';`
`import { Theme } from '@swc-react/theme';`

- Wrap app with: `<Theme system="express" scale="medium" color="light">`
- **ALWAYS** check `package.json` for version consistency across **ALL** `@swc-react/*` packages
- **Use Related References:**
- Wrap app with: `<Theme system="express" scale="medium" color="light">`
- **ALWAYS** check `package.json` for version consistency across **ALL** `@swc-react/*` packages
- **Use Related References:**

- [Using swc-react](https://opensource.adobe.com/spectrum-web-components/using-swc-react/)
- [Using Spectrum Web Components in a React-based add-on with swc-react](https://developer.adobe.com/express/add-ons/docs/guides/learn/how_to/tutorials/spectrum-workshop/part2)
- [Adobe Express Add-on UI Implementation Guide](https://developer.adobe.com/express/add-ons/docs/guides/build/design/implementation_guide/)
- [React Synthetic Events Issue](https://github.com/facebook/react/issues/19846)
- [Using swc-react](https://opensource.adobe.com/spectrum-web-components/using-swc-react/)
- [Using Spectrum Web Components in a React-based add-on with swc-react](https://developer.adobe.com/express/add-ons/docs/guides/learn/how_to/tutorials/spectrum-workshop/part2)
- [Adobe Express Add-on UI Implementation Guide](https://developer.adobe.com/express/add-ons/docs/guides/build/design/implementation_guide/)
- [React Synthetic Events Issue](https://github.com/facebook/react/issues/19846)

</InlineNestedAlert>

## Troubleshooting

<InlineNestedAlert header="true" variant="neutral" iconPosition="right">

**Server Won't Start**
**Server Won't Start**

- ✅ Check Node.js version: `node --version` (needs 18+)
- ✅ Verify MCP config JSON syntax and file location
- ✅ Ensure firewall allows `npx` downloads
- ✅ Restart your IDE after configuration changes
- ✅ Check for MCP server status indicators
- ✅ Check Node.js version: `node --version` (needs 18+)
- ✅ Verify MCP config JSON syntax and file location
- ✅ Ensure firewall allows `npx` downloads
- ✅ Restart your IDE after configuration changes
- ✅ Check for MCP server status indicators

</InlineNestedAlert>

<InlineNestedAlert header="true" variant="neutral" iconPosition="right">

**No Documentation Results**
**No Documentation Results**

- ✅ Use specific technical terms ("text styling" vs "make it pretty")
- ✅ Try adding "Adobe Express Add-ons" for an additional context cue
- ✅ Try broader queries first, then narrow down
- ✅ Ask the agent to "use available tools" explicitly
- ✅ Include context about what you're building
- ✅ Use specific technical terms ("text styling" vs "make it pretty")
- ✅ Try adding "Adobe Express Add-ons" for an additional context cue
- ✅ Try broader queries first, then narrow down
- ✅ Ask the agent to "use available tools" explicitly
- ✅ Include context about what you're building

</InlineNestedAlert>

<InlineNestedAlert header="true" variant="neutral" iconPosition="right">

**Poor Code Generation**
**Poor Code Generation**

- ✅ Be specific about what you want to implement
- ✅ Mention the programming language and frameworks (TypeScript/JavaScript, React)
- ✅ Provide context about your add-on's purpose
- ✅ Ask for complete, working examples
- ✅ Be specific about what you want to implement
- ✅ Mention the programming language and frameworks (TypeScript/JavaScript, React)
- ✅ Provide context about your add-on's purpose
- ✅ Ask for complete, working examples

</InlineNestedAlert>

<InlineNestedAlert header="true" variant="neutral" iconPosition="right">

**Missing Type Definitions**
**Missing Type Definitions**

- ✅ Specify the correct API surface (`iframe-ui`, `express-document-sdk`, `add-on-sdk-document-sandbox`)
- ✅ Ask for specific types rather than general requests
- ✅ Specify the correct API surface (`iframe-ui`, `express-document-sdk`, `add-on-sdk-document-sandbox`)
- ✅ Ask for specific types rather than general requests

</InlineNestedAlert>

Expand Down
Loading