@extenshi/mcp 0.13.0 → 0.14.0

package/dist/tools.js

@@ -52,10 +52,13 @@ import { amoCreateAllowed, PublishSetupError, publishArtifact, storeCredentialsF
 import { checkPublishAccess } from './publish-access.js';
 import { ScanError, scanArtifact } from './scan.js';
 import { describeStoreConstraints, validateSearchFilters } from './search-filters.js';
+import { canCaptureSessionTelemetry } from './session-telemetry.js';
 import { DEFAULT_MARKET_TOP_N, MARKET_FACETS, MAX_MARKET_TOP_N, shapeExtension, shapeMarketOverview, shapeReviews, shapeSearch, shapeSecurity, shapeStoreRiskBatch, } from './shape.js';
 import { captureError, captureEvent, classifyError } from './telemetry.js';
 import { renderExtensionTemplates } from './templates.js';
+import { registerUninstallFormTools } from './uninstall-form-tools.js';
 import { renderCatalogPayload } from './untrusted.js';
+import { knownUpdate } from './update-check.js';
 import { renderWelcomeWorkflow } from './welcome-workflow.js';
 // ── Public links (shared by tool bodies + server instructions) ──────────────
 export const KEY_PAGE = 'https://dojo.extenshi.io/api-keys';
@@ -76,6 +79,12 @@ export const MISSING_KEY_MESSAGE = "This tool needs an Extenshi API key, and you
     'config (or run `extenshi login`).\n\n' +
     'Tip: the `search_docs` tool is free and needs no key — use it any time to ' +
     'look up product docs and CLI commands.';
+/**
+ * The remote connector's counterpart of MISSING_KEY_MESSAGE. It signs in over
+ * OAuth, so a rejected request means the sign-in lapsed — there is no key to find.
+ */
+export const RECONNECT_MESSAGE = 'The Extenshi sign-in for this connection is missing, has expired or was revoked. ' +
+    'Reconnect the Extenshi connector in your MCP client and sign in again; no API key is needed.';
 /**
  * Max extensions `get_risk_by_store_ids` accepts per call.
  *
@@ -88,35 +97,35 @@ 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 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; 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 its _locales messages (messagesByLocale) 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}.`;
+/**
+ * Shown to the model at `initialize`. It states what the tools return and what
+ * the account can do — not how to work — and is kept short: directory review
+ * reads this block in full, and a cut-off copy hides the end of it. The length
+ * is pinned by a test.
+ */
+export const SERVER_INSTRUCTIONS = "Extenshi covers browser-extension development and operations: catalog and security data on other people's extensions, " +
+    "and the signed-in developer's own projects, hosted pages, Pay applications and privacy policy. " +
+    'get_development_guide (free) returns the end-to-end workflow, the tools on this connection, the service directory and documentation links; ' +
+    'search_docs (free) returns current product documentation and exact CLI flags. ' +
+    'get_credit_balance reports the remaining read, scan, icon and inventory credits; get_risk_by_store_ids covers up to 40 store IDs for one read, and get_security costs three reads. ' +
+    "list_my_projects returns the developer's own projects (create_project adds one); get_project_state returns a project's configuration, including integration.file " +
+    '(the content for integration.path that links a repository to the project) and integration.unwired. ' +
+    'get_decisions lists the owner decisions (AMO add-on id, license, seller identity, pricing); propose_decision proposes a value and the owner decides it in Dojo. ' +
+    'Pay applications are independent of projects (list_pay_apps, create_pay_app, get_pay_readiness) and need the pay.read / pay.write scopes; ' +
+    'agreement acceptance and KYC take place in the browser, and only the publishable SDK key and the public verification key belong in extension code. ' +
+    'Hosted privacy-policy tools need a Pro project: publish_privacy_policy puts a policy on the live public page, update_privacy_policy_with_ai returns a proposal only. ' +
+    'Registered tools are not proof of account entitlements or a completed release.';
 /** Match initialize instructions to the same capabilities used for registration. */
-export function getServerInstructions(capabilities) {
+export function getServerInstructions(capabilities, auth = 'api-key') {
     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."));
+            ? ` This connection exposes ${local.join(' and ')} for local artifacts; they need valid credentials and publishing access.`
+            : ' This connection has no local artifact scan or store-publishing tool; the local stdio server and the CLI provide those stages.') +
+        (auth === 'api-key' ? ` API keys for the local package: ${KEY_PAGE}.` : ''));
 }
 // ── Internal helpers (ported from index.ts, now deps-parametrized) ───────────
 /**
@@ -221,26 +230,15 @@ export function isExpectedError(err, kind = classifyError(err)) {
     return err instanceof UserError && err.cause === undefined;
 }
 /**
- * Attribution for a tool call, lifted from the session the surface supplies.
- *
- * Local stdio has no session at all, so both fields come back undefined and
- * captureEvent falls back to the per-install anonymous id — unchanged behaviour.
- * The hosted connector authenticates every request, so it supplies both: the
- * account id becomes the PostHog distinct_id, and the connection id threads one
- * client's calls together (see tools/extenshi-mcp-server/src/identity.ts, which
- * mints it per `authenticate()` — i.e. per connection, NOT per cached token).
- *
- * Read defensively: `session` is FastMCP's opaque auth record, and a surface
- * that carries neither field must degrade to the local behaviour rather than
- * throw inside instrumentation.
+ * Account identity comes from validated auth; connection identity comes from
+ * FastMCP's server-owned transport, not the auth object refreshed on each POST.
+ * Local stdio keeps captureEvent's anonymous per-install identity.
  */
-function attribution(session) {
-    if (!session || typeof session !== 'object')
-        return {};
-    const s = session;
+function attribution(session, sessionId) {
+    const s = session && typeof session === 'object' ? session : {};
     return {
         userId: typeof s.userId === 'string' && s.userId ? s.userId : undefined,
-        sessionId: typeof s.sessionId === 'string' && s.sessionId ? s.sessionId : undefined,
+        sessionId: typeof sessionId === 'string' && sessionId ? sessionId : undefined,
     };
 }
 /**
@@ -279,15 +277,16 @@ function instrument(tool) {
         execute: async (args, context) => {
             // The hosted connector lets a user decline analytics on the consent
             // screen; honour it for every event, including error reports.
-            if (context.session?.telemetry === false)
+            if (!canCaptureSessionTelemetry(context.session))
                 return original(args, context);
             const startedAt = Date.now();
-            const { userId, sessionId } = attribution(context.session);
+            const { userId, sessionId } = attribution(context.session, context.sessionId);
             const props = { tool: name, ...(sessionId ? { mcp_session_id: sessionId } : {}) };
             captureEvent('mcp_tool_called', props, userId);
             try {
                 const result = await original(args, context);
-                captureEvent('mcp_tool_succeeded', { ...props, duration_ms: Date.now() - startedAt }, userId);
+                if (canCaptureSessionTelemetry(context.session))
+                    captureEvent('mcp_tool_succeeded', { ...props, duration_ms: Date.now() - startedAt }, userId);
                 return result;
             }
             catch (err) {
@@ -297,12 +296,14 @@ function instrument(tool) {
                 const kind = classifyError(err);
                 // The failure count is always tracked, so we keep visibility into
                 // how often callers hit each condition (incl. the billing gate).
-                captureEvent('mcp_tool_failed', { ...props, error_kind: kind, duration_ms: Date.now() - startedAt }, userId);
-                // …but only genuine faults are shipped as exceptions. Expected
-                // user-facing conditions (a quota gate, a bad key, a message we
-                // authored) are not bugs and must not open error-tracking issues.
-                if (!isExpectedError(err, kind))
-                    captureError(err, { tool: name });
+                if (canCaptureSessionTelemetry(context.session)) {
+                    captureEvent('mcp_tool_failed', { ...props, error_kind: kind, duration_ms: Date.now() - startedAt }, userId);
+                    // …but only genuine faults are shipped as exceptions. Expected
+                    // user-facing conditions (a quota gate, a bad key, a message we
+                    // authored) are not bugs and must not open error-tracking issues.
+                    if (!isExpectedError(err, kind))
+                        captureError(err, { tool: name }, userId);
+                }
                 throw err;
             }
         },
@@ -504,7 +505,8 @@ const TOOL_ANNOTATIONS = {
     publish_privacy_policy: {
         title: 'Publish a hosted privacy policy',
         readOnlyHint: false,
-        destructiveHint: false,
+        // Overwrites the live public policy page, so a client treats it like any other overwrite.
+        destructiveHint: true,
         openWorldHint: true,
     },
     update_privacy_policy_with_ai: {
@@ -909,7 +911,8 @@ const LANDING_FORM_SHAPE = {
 export function registerTools(server, deps) {
     const registeredTools = [];
     const caps = deps.capabilities;
-    const missingKeyMessage = deps.missingKeyMessage ?? MISSING_KEY_MESSAGE;
+    const oauth = deps.auth === 'oauth';
+    const missingKeyMessage = deps.missingKeyMessage ?? (oauth ? RECONNECT_MESSAGE : MISSING_KEY_MESSAGE);
     // Generic so each tool's Zod `parameters` infers its own `args` type (a
     // non-generic wrapper would collapse Params to `never`).
     function add(tool) {
@@ -967,7 +970,9 @@ export function registerTools(server, deps) {
                                         : status === 404
                                             ? 'Pay application or resource not found. Check the appId with list_pay_apps.'
                                             : status === 401
-                                                ? 'Pay authentication failed. Reconnect or configure a developer API key with explicit Pay permissions.'
+                                                ? oauth
+                                                    ? `Pay authentication failed. Reconnect the Extenshi connector and grant the ${mutation ? 'pay.write' : 'pay.read'} permission when asked.`
+                                                    : '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);
@@ -1031,11 +1036,16 @@ export function registerTools(server, deps) {
             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; ' +
+                'formats: amo.addonId {GUID} or name@domain; license an AMO license slug (below); 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.',
+                'targetBrowsers an array of chrome/firefox/edge; targetLocales an array of locale codes. License: AMO ' +
+                'accepts exactly these case-sensitive slugs: all-rights-reserved, MIT, Apache-2.0, MPL-2.0, GPL-3.0-only, ' +
+                'ISC, BSD-2-Clause, GPL-2.0-only, LGPL-2.1-only, LGPL-3.0-only, AGPL-3.0-only, Unlicense. Another SPDX ' +
+                'id (BSD-3-Clause, GPL-3.0-or-later) is accepted, but AMO then needs it as customLicense (name + text) ' +
+                "in the listing. npm's UNLICENSED in package.json means proprietary, so propose all-rights-reserved; " +
+                'Unlicense is a public-domain dedication. A misspelled slug (mit, GPL-3.0, UNLICENSED) is refused. ' +
+                'Idempotent per idempotencyKey. Requires project.write.',
             annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: false, openWorldHint: true },
             parameters: proposeDecisionSchema,
             execute: async (args, context) => {
@@ -1062,7 +1072,8 @@ export function registerTools(server, deps) {
                     "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'.",
+                    "record source 'platform'. `warnings` lists what does not block but needs action before upload, such as a " +
+                    'decided license that is not an AMO slug and needs customLicense in the AMO listing.',
                 'getReleaseReadiness',
             ],
         ];
@@ -1094,7 +1105,7 @@ export function registerTools(server, deps) {
             });
         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; credentials and secrets are not included. Auth failures are recoverable with `extenshi login --recover` (CLI) or a reissued API key from dojo.extenshi.io/api-keys.',
+            description: 'Verify authentication, granted scopes, supported workspace contracts and actual write permissions (incl. hosted.write, evidence uploads and, for a projectId, CI ingest configuration) and the Pay scopes a key carries. Includes credit balances, the registered tools and, on the local server, `client` {version, latestVersion, updateAvailable}; credentials and secrets are not included. A failed sign-in returns an error that says how to sign in again.',
             annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
             parameters: z.object({}),
             execute: async (_args, context) => {
@@ -1104,7 +1115,13 @@ export function registerTools(server, deps) {
                         client.connectionDiagnostics(),
                         client.getApiCallerBalance(),
                     ]);
-                    return JSON.stringify({ connection, balance, registeredTools: registeredTools.map((t) => t.name) });
+                    const update = knownUpdate();
+                    return JSON.stringify({
+                        connection,
+                        balance,
+                        registeredTools: registeredTools.map((t) => t.name),
+                        ...(update ? { client: update } : {}),
+                    });
                 }
                 catch (err) {
                     return readError(err, missingKeyMessage);
@@ -1524,7 +1541,7 @@ export function registerTools(server, deps) {
                 'Built-in text (buttons, reasons, footers) is translated by Extenshi into en, es, pt-BR, fr, de, ' +
                 'it, ru, ja, ko, zh-CN and ar and is not listed. A page is shown in the user’s browser language ' +
                 'when the project offers it, otherwise in defaultLocale; an untranslated or outdated field shows ' +
-                'its original. Requires project.read.',
+                'its original. Uninstall survey text itself is changed with update_uninstall_form. Requires project.read.',
             parameters: z.object({ projectId: z.string().uuid() }),
             execute: async (args, context) => {
                 try {
@@ -1550,6 +1567,7 @@ export function registerTools(server, deps) {
                 publicCode: z.string().max(40).describe('The page code, from get_page_translations.'),
                 locale: z.string().max(35).describe('BCP 47 tag or the _locales spelling (de, pt-BR, pt_BR).'),
                 translations: z.record(z.string().max(80), z.string().max(2000)),
+                proposedBy: z.string().max(120).optional().describe('Your agent/tool name, shown to the owner.'),
             }),
             execute: async (args, context) => {
                 try {
@@ -1621,6 +1639,8 @@ export function registerTools(server, deps) {
         });
         // get_license_terms_questionnaire / draft_license_terms (project.read, read-only).
         registerLicenseTermsTools(add, bff, (err) => readError(err, missingKeyMessage));
+        // list/get/update/preview_uninstall_form + find_brand_mentions (project.read / hosted.write).
+        registerUninstallFormTools(add, bff, (err) => readError(err, missingKeyMessage));
         // A local filesystem exists only where local artifacts do (stdio).
         const localFiles = caps.has('scan');
         add({
@@ -2043,7 +2063,7 @@ export function registerTools(server, deps) {
         add({
             name: 'get_credit_balance',
             description: 'Report your remaining Extenshi credits — for checking whether a large request fits the ' +
-                'balance before running it. Returns every credit pool for your API key: `read` (spent one-per-call by ' +
+                'balance before running it. Returns every credit pool of the signed-in Extenshi account: `read` (spent one-per-call by ' +
                 'search_extensions / get_extension / get_reviews / market_overview / get_risk_by_store_ids — the ' +
                 'last one covers up to 40 extensions for that single credit; get_security costs 3) and ' +
                 '`scan` (spent by scan_extension), plus `icon` and `inventory`. Each pool reports `remaining` — the ' +
@@ -2071,7 +2091,7 @@ export function registerTools(server, deps) {
         // data about other people's extensions, never for your own work.
         add({
             name: 'list_my_projects',
-            description: "List the extension projects owned by this API key — the developer's own workspaces on " +
+            description: "List the extension projects owned by the signed-in Extenshi account — the developer's own workspaces on " +
                 'extenshi.io. Returns id, name, status, target browsers, the bound GitHub repo (if any) and ' +
                 'the claimed store listing (if any). Applies when the developer refers to "my extension" or ' +
                 '"my project": the returned id is what get_project_state takes. FREE — reading your own ' +