MWPW-183572: MAS Studio — AI assistant, product catalog, release flow, OST monorepo integration

.github/workflows/deploy-mcp-runtime.yml

@@ -0,0 +1,64 @@
+name: Deploy MCP Runtime Actions
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'io/mcp-server/**'
+      - '.github/workflows/deploy-mcp-runtime.yml'
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: io/mcp-server/package-lock.json
+
+      - name: Install Adobe I/O CLI
+        run: npm install -g @adobe/aio-cli
+
+      - name: Configure Adobe I/O CLI
+        env:
+          AIO_RUNTIME_NAMESPACE: ${{ secrets.AIO_RUNTIME_NAMESPACE }}
+          AIO_RUNTIME_AUTH: ${{ secrets.AIO_RUNTIME_AUTH }}
+        run: |
+          aio config:set runtime.namespace $AIO_RUNTIME_NAMESPACE
+          aio config:set runtime.auth $AIO_RUNTIME_AUTH
+
+      - name: Install dependencies
+        working-directory: io/mcp-server
+        run: npm ci
+
+      - name: Deploy to Adobe I/O Runtime
+        working-directory: io/mcp-server
+        env:
+          AEM_BASE_URL: ${{ secrets.AEM_BASE_URL }}
+          STUDIO_BASE_URL: ${{ secrets.STUDIO_BASE_URL }}
+        run: aio app deploy --all
+
+      - name: Verify deployment
+        working-directory: io/mcp-server
+        run: aio runtime action list
+
+      - name: Deployment summary
+        run: |
+          echo "✅ MCP Runtime actions deployed successfully"
+          echo ""
+          echo "Deployed actions:"
+          echo "  - publish-card"
+          echo "  - unpublish-card"
+          echo "  - get-card"
+          echo "  - search-cards"
+          echo "  - delete-card"
+          echo "  - copy-card"
+          echo "  - update-card"

.gitignore

@@ -30,6 +30,7 @@ nala/.auth/
 .claude/
 .logs/
 .specify/
+.superpowers/
 .worktrees/
 .pids
 /specs/
@@ -56,3 +57,7 @@ web-components/commerce.json
 web-components/mas.json
 web-components/stats.json
 *.jsonl
+
+# MWPW-183572 workspace-local (not shipped with PR)
+io/knowledge/
+.claude

io/mcp-server/DEPLOYMENT.md

@@ -0,0 +1,141 @@
+# MCP Runtime Deployment Guide
+
+> **Note (MWPW-183572):** the Studio frontend has already been migrated
+> to call Runtime actions directly — see `studio/src/constants.js`
+> `MCP_SERVER_URL` and `getMCPServerURL()`. The post-deployment steps
+> below describe that historical migration; treat them as reference
+> material, not a current checklist. The retired Express bridge on
+> port 3001 has been removed.
+
+## Post-Deployment: Update Studio Frontend (historical)
+
+After deploying the Runtime actions, update the Studio frontend to use the Runtime URLs.
+
+### 1. Get Runtime Action URLs
+
+After deployment, get your action URLs:
+
+```bash
+aio runtime action get publish-card --url
+```
+
+The URL will look like:
+```
+https://adobeioruntime.net/api/v1/web/<namespace>/MerchAtScaleMCP/publish-card
+```
+
+### 2. Update Studio Constants
+
+Edit [`studio/src/constants.js`](../../studio/src/constants.js) line 150:
+
+**Before:**
+```javascript
+export const MCP_SERVER_URL = window.location.hostname === 'localhost' ? 'http://localhost:3001' : 'https://mas-mcp.adobe.com';
+```
+
+**After:**
+```javascript
+export const MCP_SERVER_URL = window.location.hostname === 'localhost'
+    ? 'http://localhost:3001'
+    : 'https://adobeioruntime.net/api/v1/web/<your-namespace>/MerchAtScaleMCP';
+```
+
+### 3. Update MCP Client
+
+The Studio MCP client ([`studio/src/services/mcp-client.js`](../../studio/src/services/mcp-client.js)) will need to use the Runtime action names instead of the `/tools/:toolName` pattern:
+
+**Current:**
+```javascript
+const response = await fetch(`${MCP_SERVER_URL}/tools/${toolName}`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(requestBody),
+});
+```
+
+**Update to:**
+```javascript
+const response = await fetch(`${MCP_SERVER_URL}/${toolName.replace('studio_', '')}`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(requestBody),
+});
+```
+
+This maps:
+- `studio_publish_card` → `publish-card`
+- `studio_search_cards` → `search-cards`
+- etc.
+
+### 4. Test the Integration
+
+1. Deploy the Runtime actions
+2. Update Studio constants with the Runtime URL
+3. Test each operation in Studio AI chat:
+   - "publish this card"
+   - "search for fries cards"
+   - "copy this card"
+   - etc.
+
+### 5. Environment-Specific URLs
+
+For different environments:
+
+**Development (localhost):**
+```javascript
+MCP_SERVER_URL = 'http://localhost:3001'
+```
+
+**Staging:**
+```javascript
+MCP_SERVER_URL = 'https://adobeioruntime.net/api/v1/web/stage-namespace/MerchAtScaleMCP'
+```
+
+**Production:**
+```javascript
+MCP_SERVER_URL = 'https://adobeioruntime.net/api/v1/web/prod-namespace/MerchAtScaleMCP'
+```
+
+## Rollback Plan
+
+If Runtime actions have issues, rollback to the Express server:
+
+1. Start the Express MCP server:
+   ```bash
+   cd mas-mcp-server
+   npm run http
+   ```
+
+2. Revert Studio constants to point to `https://mas-mcp.adobe.com`
+
+3. Investigate Runtime issues using action logs:
+   ```bash
+   aio runtime activation list
+   aio runtime activation logs <activation-id>
+   ```
+
+## Monitoring
+
+### Check Action Status
+```bash
+aio runtime action list
+```
+
+### View Recent Activations
+```bash
+aio runtime activation list --limit 10
+```
+
+### Get Action Logs
+```bash
+aio runtime activation logs <activation-id>
+```
+
+### Action Metrics
+View in Adobe I/O Console → Runtime → Actions → Select action → Metrics
+
+## Security
+
+Runtime actions use Adobe IMS authentication via the `require-adobe-auth: true` annotation. Users must be authenticated with Adobe IMS to call these actions.
+
+The Studio frontend passes the IMS access token in the `Authorization` header, which the Runtime action extracts from `__ow_headers.authorization`.

io/mcp-server/README.md

@@ -0,0 +1,131 @@
+# MAS MCP Server - Adobe I/O Runtime Actions
+
+Adobe I/O Runtime actions for MAS Studio MCP operations. These serverless functions provide AEM Content Fragment operations for Studio's AI chat.
+
+## Architecture
+
+This is the production deployment of the MAS MCP Server using Adobe I/O Runtime. It replaces the local Express HTTP server with serverless functions that auto-deploy on git push.
+
+### Actions
+
+- **publish-card**: Publish a card to production
+- **unpublish-card**: Unpublish a card from production
+- **get-card**: Get card details by ID
+- **search-cards**: Search for cards with filters
+- **delete-card**: Delete a card
+- **copy-card**: Copy/duplicate a card
+- **update-card**: Update card fields
+
+## Local Development
+
+### Prerequisites
+
+- Node.js 22+
+- Adobe I/O CLI: `npm install -g @adobe/aio-cli`
+- Adobe I/O Runtime credentials
+
+### Setup
+
+1. Install dependencies:
+   ```bash
+   cd io/mcp-server
+   npm install
+   ```
+
+2. Configure Adobe I/O CLI:
+   ```bash
+   aio config:set runtime.namespace <your-namespace>
+   aio config:set runtime.auth <your-auth-token>
+   ```
+
+3. Shared libraries (auth-manager, aem-client, studio-url-builder,
+   studio-operations) now live directly in `src/lib/`. The previous
+   copy-from-`mas-mcp-server` step is no longer required.
+
+### Deploy
+
+Deploy all actions:
+```bash
+aio app deploy --all
+```
+
+Deploy specific action:
+```bash
+aio app deploy -a publish-card
+```
+
+### Test
+
+List deployed actions:
+```bash
+aio runtime action list
+```
+
+Invoke action directly:
+```bash
+aio runtime action invoke publish-card --param id <card-id> --result
+```
+
+## Auto-Deployment
+
+The GitHub Actions workflow [`.github/workflows/deploy-mcp-runtime.yml`](../../.github/workflows/deploy-mcp-runtime.yml) automatically deploys actions when changes are pushed to `main` branch.
+
+### Required Secrets
+
+Configure these in GitHub repository settings:
+
+- `AIO_RUNTIME_NAMESPACE`: Adobe I/O Runtime namespace
+- `AIO_RUNTIME_AUTH`: Adobe I/O Runtime auth token
+- `AEM_BASE_URL`: AEM author URL (e.g., `https://author-p133911-e1313554.adobeaemcloud.com`)
+- `STUDIO_BASE_URL`: Studio base URL (e.g., `https://mas.adobe.com/studio.html`)
+
+## Runtime URLs
+
+After deployment, actions are available at:
+```
+https://adobeioruntime.net/api/v1/web/<namespace>/MerchAtScaleMCP/<action-name>
+```
+
+Example:
+```
+https://adobeioruntime.net/api/v1/web/prod-namespace/MerchAtScaleMCP/publish-card
+```
+
+## Local development
+
+Run `aio app dev` from this directory to start the Runtime actions
+locally. Studio's MCP client (`studio/src/services/mcp-client.js`)
+routes to your local dev server when the Studio URL includes
+`?mcp.server=<local-runtime-url>`.
+
+The former local Express bridge (`mas-mcp-server/src/http-server.js`)
+has been retired — it duplicated the Runtime actions over a separate
+port (3001) without giving anything the Runtime dev server doesn't
+already give. The stdio MCP entry in `mas-mcp-server/src/index.js`
+stays for Claude Code / Cursor clients.
+| **Scaling** | Single instance | Auto-scales |
+
+## Troubleshooting
+
+### View action logs
+```bash
+aio runtime activation list
+aio runtime activation logs <activation-id>
+```
+
+### Test authentication
+```bash
+curl -H "Authorization: Bearer <token>" \
+  https://adobeioruntime.net/api/v1/web/<namespace>/MerchAtScaleMCP/get-card?id=<card-id>
+```
+
+### Undeploy actions
+```bash
+aio app undeploy
+```
+
+## Related Documentation
+
+- [MAS MCP Server (Express)](../../mas-mcp-server/README.md)
+- [Adobe I/O Runtime Documentation](https://developer.adobe.com/runtime/docs/)
+- [Studio MCP Integration](../../MCP_INTEGRATION.md)