@extenshi/mcp 0.5.2 → 0.7.0

package/dist/tools.js

@@ -13,7 +13,7 @@
  * passes deps that read `context.session` (the validated OAuth identity).
  *
  * Capability gating: the remote connector deliberately exposes a SUBSET — the
- * read/research/docs tools only. `scan_extension` and `publish_extension` need
+ * catalog/project/policy/guidance tools. `scan_extension` and `publish_extension` need
  * the caller's LOCAL filesystem and LOCAL store credentials, which a hosted
  * server has no access to (and must never store) — so they are registered only
  * when the corresponding capability is present (stdio enables all four).
@@ -22,18 +22,24 @@
  *   capability → tools
  *   ─────────────────────────────────────────────────────────────
  *   'read'    → search_extensions, get_extension, get_reviews,
- *               get_security, get_risk_by_store_ids, market_overview
- *   'docs'    → search_docs, list_extension_templates, generate_icon_workflow,
- *               generate_welcome_page_workflow        (free; no key)
+ *               get_security, get_risk_by_store_ids, market_overview,
+ *               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)
  *   '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 { UserError } from 'fastmcp';
 import { z } from 'zod';
+import { buildDevelopmentGuide } from './development-guide.js';
 import { DocsError, getDocsIndex, searchDocs } from './docs.js';
 import { renderIconWorkflow } from './icon-workflow.js';
+import { renderLocalizeWorkflow } from './localize-workflow.js';
+import { PAY_OPERATIONS, paySchemas } from './pay.js';
 import { PublishSetupError, publishArtifact, readStoreCredentials, validateStoreCredentials, } from './publish.js';
 import { checkPublishAccess } from './publish-access.js';
 import { ScanError, scanArtifact } from './scan.js';
@@ -70,33 +76,33 @@ export const MISSING_KEY_MESSAGE = "This tool needs an Extenshi API key, and you
  */
 export const MAX_BATCH_EXTENSIONS = 40;
 export const SERVER_NAME = 'extenshi';
-export const SERVER_INSTRUCTIONS = 'Extenshi catalog tools for extension developers: search the cross-store catalog, ' +
-    'inspect an extension and its security findings, find competitors, read market stats, ' +
-    'run a pre-publish security scan, and publish to the stores. Use search_docs (free, no ' +
-    'key) to consult the live product documentation and the @extenshi/cli command reference — ' +
-    'prefer quoting exact CLI commands and flags from the docs over guessing. Use ' +
-    'generate_icon_workflow (free, no key) when the developer needs an extension icon — it ' +
-    'returns the local agent-draws-SVG → CLI browser-panel preview → export workflow. Use ' +
-    'generate_welcome_page_workflow (free, no key) when the developer needs the page shown right ' +
-    'after install — it returns which illustrations to produce for the chosen goal, how to mark ' +
-    'up where to click, and the block JSON to hand back. Call ' +
-    'get_credit_balance (free — it never spends a credit) to check remaining read/scan credits ' +
-    'before a large batch instead of guessing whether it is safe. When the developer is BUILDING ' +
-    'an extension: call list_extension_templates (free, no key) for the four shapes and the ' +
-    'permissions each one requires before writing a manifest, and — when they mention "my ' +
-    'extension" or "my project" — list_my_projects then get_project_state (both free) to read the ' +
-    'types, manifest and hosted URLs they already configured on extenshi.io instead of asking them ' +
-    'to repeat it. Re-read get_project_state after they change something on the site, and write its ' +
-    '`integration.file` verbatim rather than hand-assembling the same values — that is what keeps the ' +
-    'site and the extension in sync. ' +
-    'In get_extension / get_reviews / ' +
-    'get_security you can identify an extension either by its numeric catalog id or by its store id ' +
-    '(the id in the store URL; add the store for a Chrome/Edge id). To check a LIST of installed ' +
-    `extensions by store id, use get_risk_by_store_ids — up to ${MAX_BATCH_EXTENSIONS} per call for one ` +
-    'read credit total, instead of 3 credits per extension via get_security. The catalog and ' +
-    `scan tools require an Extenshi API key (${KEY_PAGE}). Every account gets a one-time free ` +
-    'allowance — 10 reads and 3 scans; beyond it, buy prepaid credit packs (scans ' +
-    `and reads, never expire) at ${BILLING_PAGE}.`;
+export const SERVER_INSTRUCTIONS = 'Extenshi helps develop and operate browser extensions. Start extension-development tasks with ' +
+    'get_development_guide (free): it lists every tool on this connection, the service directory, ' +
+    'account/local prerequisites, documentation links, GitHub repository guidance and the ordered ' +
+    '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, ' +
+    '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 ' +
+    'for one read; get_security costs three reads for detailed findings. Hosted policy tools require ' +
+    'Pro; publish_privacy_policy changes the live policy, while update_privacy_policy_with_ai returns ' +
+    "a proposal to review. Respect the author's authorization for publication and repository writes. " +
+    'Tool registration is not proof of account entitlements or a completed release. Verify hosted ' +
+    'URLs, built artifacts, store status and optional purchases before reporting completion. ' +
+    `API keys: ${KEY_PAGE}. Credits: ${BILLING_PAGE}.`;
+/** Match initialize instructions to the same capabilities used for registration. */
+export function getServerInstructions(capabilities) {
+    const local = [
+        capabilities.has('scan') ? 'scan_extension' : null,
+        capabilities.has('publish') ? 'publish_extension' : null,
+    ].filter(Boolean);
+    return (SERVER_INSTRUCTIONS +
+        (local.length
+            ? ` This connection exposes ${local.join(' and ')} for local artifacts; check credentials and access before use.`
+            : " This connection has no local artifact scan or store-publishing tool. Use the local stdio server or CLI on the developer's machine for those stages; hosted privacy-policy publishing is a separate capability."));
+}
 // ── Internal helpers (ported from index.ts, now deps-parametrized) ───────────
 /**
  * A `UserError` that keeps the error it renders as `cause`.
@@ -344,7 +350,7 @@ async function resolveOptionalExtensionId(client, args) {
  * Anthropic Connectors Directory — its submission portal auto-syncs tools and
  * refuses to submit any tool missing a `title` or a read/write hint. Kept as a
  * name→annotation map (not inline per tool) so the read/write split is auditable
- * in one place. Every remote-exposed tool is read-only; scan uploads an artifact
+ * in one place. Hosted policy publication writes a public page; scan uploads an artifact
  * (not read-only, not destructive); publish writes to public stores (destructive).
  */
 const TOOL_ANNOTATIONS = {
@@ -390,6 +396,12 @@ const TOOL_ANNOTATIONS = {
         idempotentHint: true,
         openWorldHint: true,
     },
+    get_development_guide: {
+        title: 'Extension development services and workflow',
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     search_docs: {
         title: 'Search Extenshi documentation',
         readOnlyHint: true,
@@ -420,6 +432,36 @@ const TOOL_ANNOTATIONS = {
         idempotentHint: true,
         openWorldHint: true,
     },
+    list_privacy_policy_versions: {
+        title: 'List hosted privacy policy versions',
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    get_privacy_policy_version: {
+        title: 'Read a privacy policy version',
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    publish_privacy_policy: {
+        title: 'Publish a hosted privacy policy',
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
+    update_privacy_policy_with_ai: {
+        title: 'Update a privacy policy with AI',
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
+    localize_workflow: {
+        title: 'Local extension localization workflow',
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     generate_icon_workflow: {
         title: 'Icon design workflow guide',
         readOnlyHint: true,
@@ -444,12 +486,38 @@ const TOOL_ANNOTATIONS = {
         destructiveHint: true,
         openWorldHint: true,
     },
+    create_ci_ingest_secret: {
+        title: 'Create or rotate the CI evidence ingest secret',
+        readOnlyHint: false,
+        destructiveHint: true,
+        openWorldHint: true,
+    },
+    upsert_hosted_page: {
+        title: 'Register a hosted page URL',
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
+    verify_hosted_artifact: {
+        title: 'Verify a hosted page matches its record',
+        readOnlyHint: false,
+        idempotentHint: true,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
+    list_hosted_pages: {
+        title: 'List hosted page registrations',
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 };
 /**
- * Register the Extenshi tools on a FastMCP server. Idempotent per server.
+ * Register the Extenshi tools once on a FastMCP server.
  * Only the tools whose capability is present in `deps.capabilities` are added.
  */
 export function registerTools(server, deps) {
+    const registeredTools = [];
     const caps = deps.capabilities;
     const missingKeyMessage = deps.missingKeyMessage ?? MISSING_KEY_MESSAGE;
     // Generic so each tool's Zod `parameters` infers its own `args` type (a
@@ -457,8 +525,13 @@ export function registerTools(server, deps) {
     function add(tool) {
         // Attach the directory-required annotations (title + read/write hint) from
         // the central map; an explicit `tool.annotations` (none today) still wins.
-        const annotations = { ...TOOL_ANNOTATIONS[tool.name], ...tool.annotations };
+        const annotations = {
+            ...TOOL_ANNOTATIONS[tool.name],
+            ...tool.annotations,
+            title: tool.annotations?.title ?? TOOL_ANNOTATIONS[tool.name]?.title ?? tool.name.replaceAll('_', ' '),
+        };
         server.addTool(instrument({ ...tool, annotations }));
+        registeredTools.push({ name: tool.name, description: tool.description ?? '', annotations });
     }
     // Per-call helpers bound to the injected deps.
     const bff = (ctx) => deps.getBff(ctx);
@@ -469,6 +542,212 @@ export function registerTools(server, deps) {
     };
     // ── Read tools (free; key/identity required) ───────────────────────────────
     if (caps.has('read')) {
+        for (const [method, name, , , mutation, description] of PAY_OPERATIONS) {
+            add({
+                name,
+                description: `${description} Requires ${mutation ? 'pay.write' : 'pay.read'} permission. Never put developer API keys or Stripe secrets in extension code.`,
+                parameters: paySchemas[method],
+                annotations: {
+                    readOnlyHint: !mutation,
+                    destructiveHint: mutation,
+                    idempotentHint: !['createPayApp', 'connectPaySeller', 'rotatePayKey'].includes(method),
+                    openWorldHint: true,
+                },
+                execute: async (args, context) => {
+                    try {
+                        const invoke = bff(context)[method];
+                        return JSON.stringify(await invoke(args));
+                    }
+                    catch (err) {
+                        if (err instanceof UserError && /^MCP_SCOPE_REQUIRED:pay\.(read|write)\./.test(err.message))
+                            throw err;
+                        const status = err?.data?.httpStatus;
+                        const message = status === 403
+                            ? 'Pay access denied. Grant pay.read/pay.write explicitly and verify application ownership.'
+                            : status === 412
+                                ? 'Pay prerequisites are incomplete. Read get_pay_readiness; the author completes legal acceptance and Stripe KYC in the browser.'
+                                : status === 401
+                                    ? 'Pay authentication failed. Reconnect or configure a developer API key with explicit Pay permissions.'
+                                    : 'Pay request failed. Check authentication, application readiness and backend support before retrying a mutation.';
+                        // Provider failures may contain customer data or credentials; never echo them.
+                        throw userErrorFrom(message, err);
+                    }
+                },
+            });
+        }
+        add({
+            name: 'import_manifest',
+            description: 'Import an existing manifest.json into the Dojo manifest editor and project labels. Pass parsed JSON and optional default-locale messages. Source import fills supported fields and preserves all other JSON; built imports remain separate observations. Default dryRun=true returns changes and expectedStateHash; apply with dryRun=false and that hash. Never infers data collection, prices, or publication. Requires project.write.',
+            parameters: importManifestSchema,
+            annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: true, openWorldHint: true },
+            execute: async (args, context) => {
+                try {
+                    return JSON.stringify(await bff(context).importManifest(args));
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
+        const reads = [
+            [
+                'get_project_workspace',
+                'Read revisioned source/built manifests, repository metadata, scope and release snapshot. These are observations, separate from scaffold drafts.',
+                'getProjectWorkspace',
+            ],
+            [
+                'get_release_readiness',
+                'Explain readiness for the recorded browser and artifact by locale. Local or agent reports never become CI attestations. Stale evidence does not pass. Requires a Pro project.',
+                'getReleaseReadiness',
+            ],
+        ];
+        for (const [name, description, method] of reads)
+            add({
+                name,
+                description,
+                annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+                parameters: z.object({
+                    projectId: z.string().uuid(),
+                    browser: z
+                        .enum(['chrome', 'firefox', 'edge'])
+                        .optional()
+                        .describe('Release status: select a browser from release history.'),
+                    artifactDigest: z
+                        .string()
+                        .regex(/^[a-f0-9]{64}$/)
+                        .optional()
+                        .describe('Release status: select the exact artifact from history.'),
+                }),
+                execute: async (args, context) => {
+                    try {
+                        return JSON.stringify(await bff(context)[method](args));
+                    }
+                    catch (err) {
+                        return readError(err, missingKeyMessage);
+                    }
+                },
+            });
+        add({
+            name: 'connection_diagnostics',
+            description: 'Verify authentication, granted scopes, supported workspace contracts and actual write permissions (incl. hosted.write, evidence uploads and, for a projectId, CI ingest configuration). Includes credit balances; never returns credentials or secrets. On auth failures run `extenshi login --recover` (CLI) or reissue the API key from dojo.extenshi.io/api-keys.',
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+            parameters: z.object({}),
+            execute: async (_args, context) => {
+                try {
+                    const client = bff(context);
+                    const [connection, balance] = await Promise.all([
+                        client.connectionDiagnostics(),
+                        client.getApiCallerBalance(),
+                    ]);
+                    return JSON.stringify({ connection, balance, registeredTools: registeredTools.map((t) => t.name) });
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
+        for (const [name, method, dryRun] of [
+            ['diff_project_state', 'diffProjectWorkspace', true],
+            ['apply_project_patch', 'patchProjectWorkspace', false],
+        ])
+            add({
+                name,
+                description: dryRun
+                    ? 'Preview a three-way metadata diff against a server-held base revision. No writes.'
+                    : 'Apply a typed project metadata patch with expectedRevision and idempotencyKey. Preserve source and built manifests separately, including unknown keys. Missing fields never delete; tombstones explicitly delete. No source upload or scaffold overwrite. Requires project.write OAuth scope.',
+                annotations: {
+                    readOnlyHint: dryRun,
+                    idempotentHint: true,
+                    destructiveHint: !dryRun,
+                    openWorldHint: true,
+                },
+                parameters: workspacePatchSchema,
+                execute: async (args, context) => {
+                    try {
+                        return JSON.stringify(await bff(context)[method](args));
+                    }
+                    catch (err) {
+                        return readError(err, missingKeyMessage);
+                    }
+                },
+            });
+        add({
+            name: 'create_ci_ingest_secret',
+            description: 'Create or rotate the per-project secret the extenshi-evidence-action uses to POST CI evidence (POST /projects/:id/evidence/ingest). The secret is displayed ONCE — put it into the repository GitHub Actions secret EXTENSHI_EVIDENCE_SECRET. Creating again invalidates the previous secret. Requires project.write.',
+            annotations: { readOnlyHint: false, idempotentHint: false, destructiveHint: true, openWorldHint: true },
+            parameters: z.object({ projectId: z.string().uuid() }),
+            execute: async (args, context) => {
+                try {
+                    return JSON.stringify(await bff(context).createCiIngestSecret(args));
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
+        add({
+            name: 'upsert_hosted_page',
+            description: "Register the project's homepage or support page URL (HTTPS only, must be publicly reachable; the server hashes the body). The registered homepage URL feeds HOMEPAGE_URL when the integration config file is regenerated. Requires hosted.write.",
+            annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: false, openWorldHint: true },
+            parameters: z.object({
+                projectId: z.string().uuid(),
+                kind: z.enum(['homepage', 'support']),
+                url: z.string().url().max(2000),
+            }),
+            execute: async (args, context) => {
+                try {
+                    return JSON.stringify(await bff(context).upsertHostedPage(args));
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
+        add({
+            name: 'verify_hosted_artifact',
+            description: "Verify a hosted page actually serves what its record says: re-fetches and compares content. kind=homepage|support compares against the registered body hash (verified | changed | unreachable); kind=privacy checks the published policy version's HTML is what the public page really serves. Requires hosted.write.",
+            annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: false, openWorldHint: true },
+            parameters: z.object({
+                projectId: z.string().uuid(),
+                kind: z.enum(['homepage', 'support', 'privacy']),
+            }),
+            execute: async (args, context) => {
+                try {
+                    return JSON.stringify(await bff(context).verifyHostedArtifact(args));
+                }
+                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.',
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+            parameters: z.object({ projectId: z.string().uuid() }),
+            execute: async (args, context) => {
+                try {
+                    return JSON.stringify(await bff(context).listHostedPages(args));
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
+        add({
+            name: 'record_project_evidence',
+            description: 'Record test/scan/listing/privacy/payment evidence metadata bound to a browser, artifact hash and input hash. Source is local or agent, never CI — CI evidence is written by the verified ingest endpoint only. Attachment files upload via the CLI (extenshi evidence push --attach); this tool records metadata only. Requires evidence.write OAuth scope.',
+            annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: false, openWorldHint: true },
+            parameters: agentEvidenceSchema,
+            execute: async (args, context) => {
+                try {
+                    return JSON.stringify(await bff(context).recordProjectEvidence(args));
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
         add({
             name: 'search_extensions',
             description: 'Search the cross-store extension catalog (Chrome, Firefox, Edge) with hybrid relevance. ' +
@@ -840,7 +1119,7 @@ export function registerTools(server, deps) {
                 'browser, the files that type needs, live hosted URLs (uninstall survey), and an index of ' +
                 'every saved tool state with its size. Use it before writing code so the manifest you ship ' +
                 'matches what the developer configured on the site — and re-read it after they change ' +
-                'something rather than assuming. It also returns the integration contract: write ' +
+                'something rather than assuming. The additive workspace envelope holds revisioned local observations separately from these scaffold drafts. It also returns the integration contract: review local changes before writing ' +
                 '`integration.file` to `integration.path` VERBATIM to wire the extension to this project — ' +
                 "those bytes carry a fingerprint extenshi.io uses to tell the developer's edits from its " +
                 'own, so an equivalent file you assemble yourself makes the site stop managing every value ' +
@@ -875,7 +1154,7 @@ export function registerTools(server, deps) {
                 "content-script files that project's types need, placeholder icons, and " +
                 'src/extenshi.config.js. Write the files VERBATIM — the config carries a fingerprint ' +
                 "that lets extenshi.io keep recognising the repository as this project's, and rebuilding " +
-                'it by hand makes the site stop managing those values. Prefer this over writing a manifest ' +
+                'it by hand makes the site stop managing those values. Use this for a NEW extension; never overwrite an existing repository. Prefer this over writing a manifest ' +
                 'yourself: it is the same set the site commits, so what you write and what the site ' +
                 "expects cannot disagree. One browser per call (default: the project's first target). " +
                 'FREE — never spends a credit.',
@@ -899,9 +1178,103 @@ export function registerTools(server, deps) {
                 }
             },
         });
+        add({
+            name: 'list_privacy_policy_versions',
+            description: "List hosted privacy-policy versions for one of the developer's Pro projects: version number, " +
+                'kind (generated / edited / ai_updated / reverted), and which one is live. The public URL is ' +
+                'in get_project_state hostedArtifacts.privacyPolicy. Pro only — a free project returns ' +
+                'PROJECT_PREMIUM_REQUIRED. Does not spend a credit.',
+            parameters: z.object({
+                projectId: z.string().describe('Project id from list_my_projects.'),
+            }),
+            execute: async (args, context) => {
+                try {
+                    return JSON.stringify(await bff(context).listPrivacyPolicyVersions(args), null, 2);
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
+        add({
+            name: 'get_privacy_policy_version',
+            description: 'Read the markdown (and HTML) of one hosted privacy-policy version. Use list_privacy_policy_versions ' +
+                'first. Pro only. Does not spend a credit.',
+            parameters: z.object({
+                projectId: z.string().describe('Project id from list_my_projects.'),
+                versionNumber: z
+                    .number()
+                    .int()
+                    .positive()
+                    .describe('Version number from list_privacy_policy_versions.'),
+            }),
+            execute: async (args, context) => {
+                try {
+                    return JSON.stringify(await bff(context).getPrivacyPolicyVersion(args), null, 2);
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
+        add({
+            name: 'publish_privacy_policy',
+            description: 'Publish a hosted privacy policy for a Pro project. Omit bodyMarkdown to generate version 1 from ' +
+                'the saved form and manifest (always the first version). Pass bodyMarkdown to publish an edited ' +
+                '(or AI-updated) draft — that goes live at the same public URL. After a successful publish, ' +
+                're-read get_project_state so PRIVACY_POLICY_URL in integration.file is the hosted URL. ' +
+                'Show the author the URL before telling them it is live. Pro only.',
+            parameters: z.object({
+                projectId: z.string().describe('Project id from list_my_projects.'),
+                bodyMarkdown: z
+                    .string()
+                    .optional()
+                    .describe('Full policy markdown. Omit to generate from current form + manifest.'),
+                kind: z
+                    .enum(['generated', 'edited', 'ai_updated', 'reverted'])
+                    .optional()
+                    .describe('How this version was produced. Default: generated if no markdown, edited if markdown is set.'),
+            }),
+            execute: async (args, context) => {
+                try {
+                    return JSON.stringify(await bff(context).publishPrivacyPolicy(args), null, 2);
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
+        add({
+            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. Does NOT go live — show proposedMarkdown to the ' +
+                'author, then call publish_privacy_policy with that markdown (kind ai_updated). 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);
+                }
+                catch (err) {
+                    return readError(err, missingKeyMessage);
+                }
+            },
+        });
     }
     // ── Documentation (free; no API key required) ──────────────────────────────
     if (caps.has('docs')) {
+        add({
+            name: 'get_development_guide',
+            description: 'Start here when developing an extension: get 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.',
+            parameters: z.object({}),
+            execute: async () => JSON.stringify(buildDevelopmentGuide(registeredTools), null, 2),
+        });
         add({
             name: 'search_docs',
             description: 'Search the official Extenshi documentation (docs.extenshi.io) — product guides plus the ' +
@@ -938,6 +1311,16 @@ export function registerTools(server, deps) {
                 }
             },
         });
+        add({
+            name: 'localize_workflow',
+            description: 'Get the FREE local browser-extension localization workflow: prepare missing or stale ' +
+                '_locales messages, translate with your own coding agent, apply validated translations ' +
+                'and check placeholders, protected terms and listing risks. Returns commands and the ' +
+                'JSON handoff contract. Static guidance only: no API key, network or Extenshi credits; ' +
+                'translation uses your agent provider. Includes release availability and human review gates.',
+            parameters: z.object({}),
+            execute: async () => renderLocalizeWorkflow(),
+        });
         add({
             name: 'generate_icon_workflow',
             description: 'Get the recommended FREE local workflow for creating a browser-extension icon: the ' +