@extenshi/mcp 0.8.0 → 0.10.0

package/dist/tools.js

@@ -26,22 +26,26 @@
  *               list_my_projects, get_project_state, get_project_scaffold,
  *               list/get/publish/update privacy policy (hosted; Pro)
  *   'docs'    → get_development_guide, search_docs, list_extension_templates, generate_icon_workflow,
- *               generate_welcome_page_workflow, localize_workflow (free; no key)
+ *               generate_welcome_page_workflow, generate_landing_page, localize_workflow (free; no key)
  *   'scan'    → scan_extension             (local artifact; stdio only)
  *   'publish' → publish_extension          (local creds; stdio only)
  *
  * stdout is the MCP protocol channel for stdio — nothing here may write to it.
  */
-import { agentEvidenceSchema, importManifestSchema, workspacePatchSchema } from '@extenshi/contracts';
+import { agentCreateProjectSchema, agentEvidenceSchema, importManifestSchema, proposeDecisionSchema, workspacePatchSchema, } from '@extenshi/contracts';
 import { UserError } from 'fastmcp';
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { buildDevelopmentGuide, GUIDE_SECTIONS } from './development-guide.js';
 import { DEFAULT_EXCERPT_CHARS, DocsError, getDocsIndex, MAX_EXCERPT_CHARS, MIN_EXCERPT_CHARS, searchDocs, } from './docs.js';
 import { renderIconWorkflow } from './icon-workflow.js';
+import { LANDING_LIMITS } from './landing-page.js';
+import { hostedLandingNextSteps, landingFormFromArgs, renderGenerateLandingPage } from './landing-workflow.js';
 import { renderLocalizeWorkflow } from './localize-workflow.js';
 import { PAY_OPERATIONS, paySchemas } from './pay.js';
-import { PublishSetupError, publishArtifact, readStoreCredentials, validateStoreCredentials, } from './publish.js';
+import { describePrivacyAiUpdate } from './privacy-ai-outcome.js';
+import { checkInlineImage, PROJECT_MEDIA_MAX_BYTES, PROJECT_MEDIA_MIME_TYPES, ProjectMediaInputError, readWorkspaceImage, } from './project-media.js';
+import { amoCreateAllowed, PublishSetupError, publishArtifact, storeCredentialsFor, validateStoreCredentials, } from './publish.js';
 import { checkPublishAccess } from './publish-access.js';
 import { ScanError, scanArtifact } from './scan.js';
 import { describeStoreConstraints, validateSearchFilters } from './search-filters.js';
@@ -87,7 +91,10 @@ export const SERVER_INSTRUCTIONS = 'Extenshi helps develop and operate browser e
     'plan from scope and research through code, assets, privacy, CI, store release and maintenance. ' +
     'Keep a checklist covering the whole requested lifecycle. For standalone Pay, start with list_pay_apps; create_pay_app needs no development project or repository. Request explicit pay.read/pay.write scopes, use get_pay_readiness, and leave agreement acceptance and KYC to the author in the browser. Only the publishable SDK key and public verification key belong in extension code. Use search_docs (free) for current ' +
     'product details and exact CLI flags. With identity, call list_my_projects then get_project_state ' +
-    'to reuse the existing project and repository. Use list_extension_templates before the manifest, ' +
+    'to reuse the existing project and repository; for a new extension, create_project makes one (idempotent). ' +
+    'Read get_decisions early: the AMO add-on id, license, seller identity and pricing are owner decisions — ' +
+    'propose defaults with propose_decision; the owner decides them in Dojo, and release readiness blocks on them. ' +
+    'Use list_extension_templates before the manifest, ' +
     'and get_project_scaffold for a new project. Preserve existing source. For an existing extension, read get_project_workspace then preview and apply import_manifest to fill Dojo from its real manifest and default-locale messages before configuring services. Review the integration diff and preserve local edits; write integration.file ' +
     'verbatim to integration.path, check integration.unwired and re-read state after cabinet edits. ' +
     'Check get_credit_balance before metered work. get_risk_by_store_ids covers up to 40 store IDs ' +
@@ -441,6 +448,26 @@ const TOOL_ANNOTATIONS = {
         idempotentHint: true,
         openWorldHint: false,
     },
+    create_project: {
+        title: 'Create an extension project',
+        readOnlyHint: false,
+        idempotentHint: true,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
+    get_decisions: {
+        title: 'Read owner decisions',
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    propose_decision: {
+        title: 'Propose an owner decision',
+        readOnlyHint: false,
+        idempotentHint: true,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
     list_my_projects: {
         title: 'List my extension projects',
         readOnlyHint: true,
@@ -501,6 +528,12 @@ const TOOL_ANNOTATIONS = {
         idempotentHint: true,
         openWorldHint: false,
     },
+    generate_landing_page: {
+        title: 'Generate a static landing page',
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     scan_extension: {
         title: 'Scan an extension package',
         readOnlyHint: false,
@@ -538,6 +571,34 @@ const TOOL_ANNOTATIONS = {
         idempotentHint: true,
         openWorldHint: true,
     },
+    publish_landing_page: {
+        title: 'Publish a landing page on extenshi.io',
+        readOnlyHint: false,
+        idempotentHint: false,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
+    get_landing_page: {
+        title: 'Read the hosted landing page',
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    unpublish_landing_page: {
+        title: 'Unpublish the hosted landing page',
+        readOnlyHint: false,
+        idempotentHint: true,
+        destructiveHint: true,
+        openWorldHint: true,
+    },
+    upload_project_media: {
+        title: 'Upload a public image for hosted pages',
+        readOnlyHint: false,
+        // Content-addressed: the same bytes always return the same URL.
+        idempotentHint: true,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
     remove_hosted_page: {
         title: 'Remove a hosted page registration',
         readOnlyHint: false,
@@ -545,6 +606,86 @@ const TOOL_ANNOTATIONS = {
         openWorldHint: true,
     },
 };
+/**
+ * LandingForm fields shared by generate_landing_page (offline HTML) and
+ * publish_landing_page (hosted on page.extenshi.io). Limits match the builder
+ * and the BFF, so a form valid for one is valid for the other.
+ */
+const LANDING_FORM_SHAPE = {
+    extensionName: z.string().min(1).max(LANDING_LIMITS.extensionName).describe('Extension display name.'),
+    tagline: z.string().max(LANDING_LIMITS.tagline).optional().describe('One-line promise under the name.'),
+    description: z
+        .string()
+        .max(LANDING_LIMITS.description)
+        .optional()
+        .describe('Short paragraph on what the extension does; also the meta description.'),
+    accentColor: z
+        .string()
+        .max(9)
+        .optional()
+        .describe('Hex accent colour for the primary button and monogram (default #5e5ce6).'),
+    theme: z.enum(['light', 'dark']).optional().describe('Page colour scheme (default dark).'),
+    chromeUrl: z
+        .string()
+        .max(LANDING_LIMITS.url)
+        .optional()
+        .describe('Chrome Web Store listing URL. Empty or omitted hides the Chrome button.'),
+    firefoxUrl: z
+        .string()
+        .max(LANDING_LIMITS.url)
+        .optional()
+        .describe('Firefox Add-ons listing URL. Empty or omitted hides the Firefox button.'),
+    edgeUrl: z
+        .string()
+        .max(LANDING_LIMITS.url)
+        .optional()
+        .describe('Edge Add-ons listing URL. Empty or omitted hides the Edge button.'),
+    privacyPolicyUrl: z
+        .string()
+        .max(LANDING_LIMITS.url)
+        .optional()
+        .describe('Privacy policy URL for the footer (for example the hosted privacy.extenshi.io page).'),
+    supportUrl: z
+        .string()
+        .max(LANDING_LIMITS.url)
+        .optional()
+        .describe('Support link for the footer: an http(s) URL, or a single mailto: address (optionally ' +
+        '?subject= with a percent-encoded value).'),
+    homepageUrl: z
+        .string()
+        .max(LANDING_LIMITS.url)
+        .optional()
+        .describe('Public https URL the page will be served from: canonical link, og:url, JSON-LD url, and the ' +
+        'base for relative screenshot paths in og:image.'),
+    features: z
+        .array(z.object({
+        title: z.string().max(LANDING_LIMITS.featureTitle),
+        description: z.string().max(LANDING_LIMITS.featureDescription).optional(),
+    }))
+        .max(LANDING_LIMITS.features)
+        .optional()
+        .describe('Feature cards; entries with an empty title are skipped.'),
+    screenshots: z
+        .array(z.object({
+        url: z.string().max(LANDING_LIMITS.url),
+        alt: z.string().max(LANDING_LIMITS.screenshotAlt).optional(),
+    }))
+        .max(LANDING_LIMITS.screenshots)
+        .optional()
+        .describe('Screenshots as https URLs (for example store screenshots from get_extension) or paths ' +
+        'relative to index.html, each with alt text.'),
+    logoSvg: z
+        .string()
+        .max(LANDING_LIMITS.logoSvgBytes)
+        .optional()
+        .describe('Inline SVG logo source. Refused (monogram shown, reason in warnings) if it contains ' +
+        'scripts, event handlers, foreignObject, animation, entity references or non-fragment hrefs.'),
+    logoUrl: z
+        .string()
+        .max(LANDING_LIMITS.logoUrl)
+        .optional()
+        .describe('Logo image as an https URL, a relative path, or a data:image/(png|jpeg|gif|webp);base64 URL.'),
+};
 /**
  * Register the Extenshi tools once on a FastMCP server.
  * Only the tools whose capability is present in `deps.capabilities` are added.
@@ -633,6 +774,63 @@ export function registerTools(server, deps) {
                 }
             },
         });
+        add({
+            name: 'create_project',
+            description: 'Create a new extension project (a Dojo workspace) owned by this identity, through the same service ' +
+                'the Dojo project wizard uses, with the same ownership and limits. Returns JSON {projectId, dojoUrl, ' +
+                'project, pendingDecisions, nextSteps}: the next steps cover binding the repository and the starter ' +
+                'files. Idempotent: a repeated request with the same idempotencyKey returns the project it already ' +
+                'created (replayed: true); the same key with different input is rejected. Requires project.write.',
+            parameters: agentCreateProjectSchema,
+            execute: async (args, context) => {
+                try {
+                    return JSON.stringify(await bff(context).createProject(args), null, 2);
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
+        add({
+            name: 'get_decisions',
+            description: 'Owner decisions for one project: the AMO add-on id, license, seller public name, support contact ' +
+                'and terms, pricing, target browsers and target locales. Each entry reports its status (undecided, ' +
+                'proposed or decided), the value, a suggested default where one is derivable (a stable {GUID} add-on ' +
+                'id or the id already in the Firefox manifest, the project browsers), who proposed or decided it and ' +
+                'when, and which releases it blocks (blocksBrowsers, blocksPayment). `pending` lists the keys the ' +
+                'owner has not decided. FREE.',
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+            parameters: z.object({ projectId: z.string().uuid().describe('Project id from list_my_projects.') }),
+            execute: async (args, context) => {
+                try {
+                    return JSON.stringify(await bff(context).getDecisions(args), null, 2);
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
+        add({
+            name: 'propose_decision',
+            description: 'Propose a value for one owner decision. The proposal is stored with its rationale, proposer and ' +
+                'time; the owner accepts or edits it on the Dojo project page, which is the only place a decision ' +
+                'becomes decided. A key the owner already decided is refused (DECISION_ALREADY_DECIDED). Value ' +
+                'formats: amo.addonId {GUID} or name@domain; license an SPDX id such as MIT, or all-rights-reserved; ' +
+                'seller.publicName text; seller.supportContact an email or HTTPS URL; seller.terms an HTTPS URL; ' +
+                'pricing {model: free|paid|donations, trialDays?, plans?: subscription|lifetime|one_time}; ' +
+                'targetBrowsers an array of chrome/firefox/edge; targetLocales an array of locale codes. Idempotent ' +
+                'per idempotencyKey. Requires project.write.',
+            annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: false, openWorldHint: true },
+            parameters: proposeDecisionSchema,
+            execute: async (args, context) => {
+                try {
+                    return JSON.stringify(await bff(context).proposeDecision(args), null, 2);
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
         const reads = [
             [
                 'get_project_workspace',
@@ -644,7 +842,11 @@ export function registerTools(server, deps) {
                 'Explain readiness for the recorded browser and artifact by locale. Local or agent reports are not treated as CI attestations. Stale evidence does not pass. Requires a Pro project. ' +
                     'Readiness is measured against the release recorded in the workspace: until apply_project_patch sets patch.release ' +
                     '(browser, version, artifactDigest, manifestDigest, locales, paymentRequired, and commit or dirtyTreeDigest) it reports ' +
-                    'RELEASE_NOT_RECORDED; after that, evidence counts only when it matches that release artifactDigest.',
+                    'RELEASE_NOT_RECORDED; after that, evidence counts only when it matches that release artifactDigest. ' +
+                    "When the project has a linked Pay application, the payment check also carries `platform`: what Extenshi's own " +
+                    'payment ledger proves (checkout, license, installation activation, recovery, refund). A live-mode purchase through ' +
+                    "those stages passes the check with source 'platform'; test-mode purchases are listed without passing it. Clients cannot " +
+                    "record source 'platform'.",
                 'getReleaseReadiness',
             ],
         ];
@@ -784,6 +986,136 @@ export function registerTools(server, deps) {
                 }
             },
         });
+        add({
+            name: 'publish_landing_page',
+            description: "Publish the project's landing page (homepage) on Extenshi hosting — the same page " +
+                'generate_landing_page returns, rendered server-side from the form (no caller HTML is stored) and ' +
+                'served at page.extenshi.io/{code}, or https://{custom-domain}/landing when the project has an ' +
+                'active custom domain. The code is permanent: republishing creates a new version at the same URL. ' +
+                'By default the URL is also registered as the project homepage, which feeds HOMEPAGE_URL. Hosted ' +
+                'images are limited to store screenshot URLs (from get_extension) and images uploaded in the Dojo ' +
+                'Page generator or with upload_project_media (use its url for local screenshots or a logo); the logo ' +
+                'may also be an inline SVG or a raster data: URL. Returns JSON {url, publicCode, ' +
+                'versionNumber, contentHash, bytes, warnings, homepage, nextSteps}. Requires hosted.write. ' +
+                `API reference: ${HOSTED_PAGES_DOCS}`,
+            parameters: z.object({
+                projectId: z.string().uuid(),
+                registerAsHomepage: z
+                    .boolean()
+                    .optional()
+                    .describe('Register the URL as the project homepage (default true). False keeps an existing homepage.'),
+                ...LANDING_FORM_SHAPE,
+            }),
+            execute: async (args, context) => {
+                const { projectId, registerAsHomepage, ...fields } = args;
+                try {
+                    const result = (await bff(context).publishLandingPage({
+                        projectId,
+                        registerAsHomepage,
+                        form: landingFormFromArgs(fields),
+                    }));
+                    return JSON.stringify({ ...result, nextSteps: hostedLandingNextSteps(result) });
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
+        add({
+            name: 'get_landing_page',
+            description: "The project's hosted landing page: public code, live version, publish state, URL (null when " +
+                'unpublished) and the form the live version was rendered from.',
+            parameters: z.object({ projectId: z.string().uuid() }),
+            execute: async (args, context) => {
+                try {
+                    return JSON.stringify(await bff(context).getLandingPage(args));
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
+        add({
+            name: 'unpublish_landing_page',
+            description: 'Take the hosted landing page offline (it answers 404). The public code and version history are ' +
+                'kept, so publishing again restores the same URL. A homepage registration that points at this ' +
+                `page is removed with it. Requires hosted.write. API reference: ${HOSTED_PAGES_DOCS}`,
+            parameters: z.object({ projectId: z.string().uuid() }),
+            execute: async (args, context) => {
+                try {
+                    return JSON.stringify(await bff(context).unpublishLandingPage(args));
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
+        // A local filesystem exists only where local artifacts do (stdio).
+        const localFiles = caps.has('scan');
+        add({
+            name: 'upload_project_media',
+            description: "Upload a logo or screenshot (PNG, JPEG or WebP, up to 2 MB) to the project's PUBLIC media store — " +
+                'the same store the Dojo Page generator uploads into — and get a stable https URL that ' +
+                'publish_landing_page accepts as screenshots[].url or logoUrl. The server checks the file by content ' +
+                '(magic bytes), strips EXIF/XMP/text metadata and anything after the image end marker, bounds the ' +
+                'dimensions (16–4096 px) and enforces a per-project quota (100 files / 50 MB, Dojo uploads included); ' +
+                'identical bytes return the same URL without using quota. SVG is refused: rasterize it first ' +
+                '(CLI: extenshi icon store-assets) or pass an inline logo as logoSvg. ' +
+                (localFiles
+                    ? 'Pass filePath (a file inside the workspace) or dataBase64 + mime. '
+                    : 'Pass dataBase64 + mime (this connection has no access to local files). ') +
+                'Store screenshots come from the CLI: extenshi screenshots. Returns JSON {url, sha256, mime, bytes, ' +
+                'width, height, strippedBytes, deduplicated, quota}. Requires hosted.write. ' +
+                `CLI: extenshi media upload <file> --project <id>. API reference: ${HOSTED_PAGES_DOCS}`,
+            parameters: z.object({
+                projectId: z.string().uuid(),
+                filePath: z
+                    .string()
+                    .min(1)
+                    .max(4096)
+                    .optional()
+                    .describe('Image file inside the workspace (local stdio server only).'),
+                dataBase64: z
+                    .string()
+                    .min(1)
+                    .max(Math.ceil(PROJECT_MEDIA_MAX_BYTES / 3) * 4 + 16)
+                    .optional()
+                    .describe('The raw image, base64-encoded (no data: prefix). Use with mime.'),
+                mime: z.enum(PROJECT_MEDIA_MIME_TYPES).optional().describe('Required with dataBase64.'),
+            }),
+            execute: async (args, context) => {
+                let payload;
+                try {
+                    if (args.filePath && args.dataBase64)
+                        throw new ProjectMediaInputError('Pass filePath OR dataBase64, not both.');
+                    if (args.filePath) {
+                        if (!localFiles)
+                            throw new ProjectMediaInputError('filePath works only with the local stdio server; send dataBase64 + mime instead.');
+                        const read = await readWorkspaceImage(args.filePath);
+                        payload = { mime: read.mime, dataBase64: read.dataBase64 };
+                    }
+                    else if (args.dataBase64) {
+                        if (!args.mime)
+                            throw new ProjectMediaInputError('mime is required with dataBase64.');
+                        checkInlineImage(args.dataBase64, args.mime);
+                        payload = { mime: args.mime, dataBase64: args.dataBase64 };
+                    }
+                    else
+                        throw new ProjectMediaInputError('Pass filePath or dataBase64 + mime.');
+                }
+                catch (err) {
+                    if (err instanceof ProjectMediaInputError)
+                        throw new UserError(err.message);
+                    throw err;
+                }
+                try {
+                    return JSON.stringify(await bff(context).uploadProjectMedia({ projectId: args.projectId, ...payload }));
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
         add({
             name: 'list_hosted_pages',
             description: 'List the project registered hosted pages (homepage/support) with their verification status, content hash and last check time.',
@@ -1320,14 +1652,17 @@ export function registerTools(server, deps) {
             name: 'update_privacy_policy_with_ai',
             description: "Propose an updated privacy policy that keeps the author's custom wording and adds sections " +
                 'required by new permissions or data practices. Returns proposedMarkdown only; nothing goes ' +
-                'live. Publishing it is a separate step (publish_privacy_policy, kind ai_updated). Requires a ' +
-                'policy that is already published. Pro only.',
+                'live. aiStep states whether the AI step ran (ran | did_not_run | discarded | not_needed) and ' +
+                'notice says why; unless aiStep is ran, proposedMarkdown is a deterministic section merge, not an ' +
+                'AI draft. conflictHeadings and missingCategories list what still needs a manual edit. Publishing ' +
+                'is a separate step (publish_privacy_policy with the returned kind). Requires a policy that is ' +
+                'already published. Pro only.',
             parameters: z.object({
                 projectId: z.string().describe('Project id from list_my_projects.'),
             }),
             execute: async (args, context) => {
                 try {
-                    return JSON.stringify(await bff(context).updatePrivacyPolicyWithAi(args), null, 2);
+                    return JSON.stringify(describePrivacyAiUpdate(await bff(context).updatePrivacyPolicyWithAi(args)), null, 2);
                 }
                 catch (err) {
                     return readError(err, missingKeyMessage);
@@ -1342,13 +1677,14 @@ export function registerTools(server, deps) {
             description: 'For extension-development tasks: returns the complete tool inventory for THIS connection, ' +
                 'the Extenshi service directory with access requirements and docs links, GitHub/code placement ' +
                 'guidance, and the ordered workflow from idea and repository through implementation, assets, ' +
-                'privacy, tests/CI, store submission and maintenance. Distinguishes MCP tools from cabinet, ' +
-                'CLI and external steps. Free; no key, account lookup or network request.',
+                'privacy, tests/CI, store submission and maintenance, plus store media: the scenes.json format for ' +
+                'CLI screenshots (per-locale store screenshots) and listing artwork sizes per store. Distinguishes ' +
+                'MCP tools from cabinet, CLI and external steps. Free; no key, account lookup or network request.',
             parameters: z.object({
                 sections: z
                     .array(z.enum(['all', ...GUIDE_SECTIONS]))
                     .optional()
-                    .describe('Full guide sections to include: tools, localActions, services, repository, workflow, handoff, or all. ' +
+                    .describe('Full guide sections to include: tools, localActions, services, repository, workflow, handoff, storeMedia, or all. ' +
                     'Omitted: a compact overview with tool names, workflow stages and a table of contents.'),
             }),
             execute: async (args) => JSON.stringify(buildDevelopmentGuide(registeredTools, args?.sections), null, 2),
@@ -1479,6 +1815,21 @@ export function registerTools(server, deps) {
                 accentColor: args.accent_color,
             }),
         });
+        add({
+            name: 'generate_landing_page',
+            description: 'Generate a static landing page (homepage) for a browser extension as one self-contained HTML ' +
+                'file: no JavaScript, escaped text, http(s)-only links (the support link may also be a mailto: ' +
+                'address), and store buttons only for the store ' +
+                'URLs given. Same generator as the cabinet Page generator, so a saved `page-generator` form ' +
+                'from get_project_state maps field for field. Optional logo (inline SVG, validated and embedded ' +
+                'as an image, or an image URL), screenshots and the canonical homepage URL for Open Graph and ' +
+                'JSON-LD. Returns JSON {html, bytes, warnings, nextSteps}: warnings list input that was dropped ' +
+                'or clamped; nextSteps cover hosting the file on HTTPS and registering the URL with ' +
+                'upsert_hosted_page, which feeds HOMEPAGE_URL. Extenshi does not host the page. Static content: ' +
+                'no API key, no network, no credits.',
+            parameters: z.object(LANDING_FORM_SHAPE),
+            execute: async (args) => JSON.stringify(renderGenerateLandingPage(args)),
+        });
         add({
             name: 'list_extension_templates',
             description: 'The kinds of browser extension you can build, with the permissions each one REQUIRES: ' +
@@ -1541,7 +1892,12 @@ export function registerTools(server, deps) {
                             }
                         },
                     });
-                    return renderCatalogPayload(shapeExtension(report));
+                    // The scan report goes out as-is (defanged + labelled as data: finding
+                    // text quotes the artifact's own code). It used to be passed through
+                    // shapeExtension — the catalog-DETAIL shaper — whose field list has
+                    // none of the report's keys, so every scan came back as
+                    // {"snapshots": []} after the credit was spent.
+                    return renderCatalogPayload(report);
                 }
                 catch (err) {
                     // Keep the ScanError as `cause`: scanErrorMessage() renders 402/429
@@ -1564,8 +1920,12 @@ export function registerTools(server, deps) {
                 'CHROME_REFRESH_TOKEN, FIREFOX_ADDON_GUID/FIREFOX_JWT_ISSUER/FIREFOX_JWT_SECRET, ' +
                 'EDGE_PRODUCT_ID/EDGE_CLIENT_ID/EDGE_CLIENT_SECRET/EDGE_TENANT_ID). The upload itself is local, but ' +
                 'publishing is in an active testing phase: a quick Extenshi access check runs first (it identifies your ' +
-                'account by EXTENSHI_API_KEY). Edge submissions are polled to a terminal status. The artifact is ' +
-                'not security-scanned by this tool (scanning is scan_extension).',
+                'account by EXTENSHI_API_KEY). Edge submissions are polled to a terminal status. For Firefox, ' +
+                'listing_path turns the upload into a listed AMO submission with metadata: first-time add-on creation ' +
+                '(gated by allow_new_addon or the project decision), per-locale name/summary/description, categories, ' +
+                'license, homepage, support email and URL, privacy policy, release and reviewer notes, reviewer source ' +
+                '(source_path) and previews (screenshots_dir); the result lists each step. The artifact is not ' +
+                'security-scanned by this tool (scanning is scan_extension).',
             parameters: z.object({
                 artifact_path: z
                     .string()
@@ -1579,6 +1939,42 @@ export function registerTools(server, deps) {
                     .optional()
                     .describe('Separate Firefox artifact (.xpi); defaults to artifact_path.'),
                 release_notes: z.string().optional().describe('Release notes for stores that accept them.'),
+                listing_path: z
+                    .string()
+                    .optional()
+                    .describe('Firefox: AMO listing file (JSON with per-locale fields, or the AMO.md that generate-listing --store ' +
+                    'firefox writes, placeholders filled). Makes the Firefox submission a listed one with metadata: ' +
+                    'the add-on is created on first submission (see allow_new_addon) or its listing is edited, then ' +
+                    'privacy policy, release notes, reviewer notes, source and previews are applied.'),
+                source_path: z
+                    .string()
+                    .optional()
+                    .describe('Firefox: reviewer source archive (.zip/.tar.gz/.tgz/.tar.bz2) for the new version.'),
+                screenshots_dir: z
+                    .string()
+                    .optional()
+                    .describe('Firefox: AMO previews in file-name order: a directory of .png/.jpg/.gif files, or the extenshi ' +
+                    'screenshots output directory (its firefox/<locale>/ set, default locale first).'),
+                allow_new_addon: z
+                    .boolean()
+                    .optional()
+                    .describe('Firefox: permits creating a NEW AMO add-on, whose id becomes permanent. With project_id the ' +
+                    "project's decided amo.addonId governs creation instead."),
+                addon_id: z
+                    .string()
+                    .max(255)
+                    .optional()
+                    .describe('Firefox: the AMO add-on id ({GUID} or name@domain), stated explicitly. Needed with allow_new_addon ' +
+                    'when there is no project_id; fills FIREFOX_ADDON_GUID when the environment has none.'),
+                replace_screenshots: z
+                    .boolean()
+                    .optional()
+                    .describe('Firefox: replaces the previews of an existing AMO add-on with screenshots_dir.'),
+                project_id: z
+                    .string()
+                    .uuid()
+                    .optional()
+                    .describe('Dojo project id. Its owner-decided amo.addonId gates first-time AMO creation and has to equal FIREFOX_ADDON_GUID.'),
                 extension_id: z
                     .number()
                     .optional()
@@ -1598,7 +1994,7 @@ export function registerTools(server, deps) {
                     // preflight evaluates the `publish-access` PostHog flag for this developer
                     // / extension. Fails open on any transport error — only a definitive
                     // server "no" blocks here (see checkPublishAccess).
-                    const creds = readStoreCredentials();
+                    const creds = storeCredentialsFor(args.addon_id);
                     const storeIds = {};
                     if (creds.chrome)
                         storeIds.chrome = creds.chrome.appId;
@@ -1616,12 +2012,37 @@ export function registerTools(server, deps) {
                         throw new UserError(access.message ??
                             "Publishing is in an active testing phase and isn't available for your account yet.");
                     }
+                    let firefoxListing;
+                    if (args.listing_path || args.source_path || args.screenshots_dir) {
+                        if (!args.listing_path)
+                            throw new UserError('source_path and screenshots_dir need listing_path, the AMO listing they belong to.');
+                        let decision = null;
+                        if (args.project_id) {
+                            const view = (await bff(context).getDecisions({ projectId: args.project_id }));
+                            decision = view.decisions?.find((d) => d.key === 'amo.addonId') ?? null;
+                        }
+                        firefoxListing = {
+                            listingPath: args.listing_path,
+                            sourcePath: args.source_path,
+                            screenshotsDir: args.screenshots_dir,
+                            replaceScreenshots: args.replace_screenshots,
+                            allowCreate: amoCreateAllowed({
+                                addonGuid: creds.firefox?.addonGuid ?? '',
+                                allowNewAddon: args.allow_new_addon,
+                                addonId: args.addon_id,
+                                projectId: args.project_id,
+                                decision,
+                            }),
+                        };
+                    }
                     void context.reportProgress({ progress: 0, total: 1 });
                     const result = await publishArtifact({
                         artifactPath: args.artifact_path,
                         stores: args.stores,
                         firefoxArtifactPath: args.firefox_artifact_path,
                         releaseNotes: args.release_notes,
+                        addonId: args.addon_id,
+                        firefoxListing,
                     });
                     void context.reportProgress({ progress: 1, total: 1 });
                     return JSON.stringify(result, null, 2);