@extenshi/mcp 0.5.1 → 0.6.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,8 +22,10 @@
  *   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,
+ *               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        (free; no key)
  *   'scan'    → scan_extension             (local artifact; stdio only)
  *   'publish' → publish_extension          (local creds; stdio only)
@@ -32,8 +34,10 @@
  */
 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 { evidenceSchema, importManifestSchema, workspacePatchSchema } from './project-workspace.js';
 import { PublishSetupError, publishArtifact, readStoreCredentials, validateStoreCredentials, } from './publish.js';
 import { checkPublishAccess } from './publish-access.js';
 import { ScanError, scanArtifact } from './scan.js';
@@ -70,33 +74,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. 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`.
@@ -200,10 +204,36 @@ export function isExpectedError(err, kind = classifyError(err)) {
     return err instanceof UserError && err.cause === undefined;
 }
 /**
- * Wrap a tool definition so every call emits anonymous telemetry: which tool
- * ran, how long it took, and how it failed (coarse error_kind + sanitized
- * exception). The generic preserves the Zod-inferred `args` type — `parameters`
- * fixes Params, so the inner execute stays as strongly typed as before.
+ * 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.
+ */
+function attribution(session) {
+    if (!session || typeof session !== 'object')
+        return {};
+    const s = session;
+    return {
+        userId: typeof s.userId === 'string' && s.userId ? s.userId : undefined,
+        sessionId: typeof s.sessionId === 'string' && s.sessionId ? s.sessionId : undefined,
+    };
+}
+/**
+ * Wrap a tool definition so every call is reported: which tool ran, how long it
+ * took, and how it failed (coarse error_kind + sanitized exception). On the
+ * hosted connector the report also carries WHO — the authenticated account id —
+ * and which connection it belonged to; on local stdio it stays anonymous. Never
+ * the arguments, never the result. The generic preserves the Zod-inferred
+ * `args` type — `parameters` fixes Params, so the inner execute stays as
+ * strongly typed as before.
  * Fail-soft: telemetry never alters the tool's result or its thrown error.
  */
 function instrument(tool) {
@@ -213,10 +243,12 @@ function instrument(tool) {
         ...tool,
         execute: async (args, context) => {
             const startedAt = Date.now();
-            captureEvent('mcp_tool_called', { tool: name });
+            const { userId, sessionId } = attribution(context.session);
+            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', { tool: name, duration_ms: Date.now() - startedAt });
+                captureEvent('mcp_tool_succeeded', { ...props, duration_ms: Date.now() - startedAt }, userId);
                 return result;
             }
             catch (err) {
@@ -226,7 +258,7 @@ 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', { tool: name, error_kind: kind, duration_ms: Date.now() - startedAt });
+                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.
@@ -316,7 +348,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 = {
@@ -362,6 +394,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,
@@ -392,6 +430,30 @@ 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,
+    },
     generate_icon_workflow: {
         title: 'Icon design workflow guide',
         readOnlyHint: true,
@@ -418,10 +480,11 @@ const TOOL_ANNOTATIONS = {
     },
 };
 /**
- * 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
@@ -429,8 +492,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);
@@ -441,6 +509,116 @@ export function registerTools(server, deps) {
     };
     // ── Read tools (free; key/identity required) ───────────────────────────────
     if (caps.has('read')) {
+        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. Includes credit balances; never returns credentials. On OAuth invalid_grant reconnect the client and serialize refresh in its credential store.',
+            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: '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. No logs, screenshots or credentials uploaded. Requires evidence.write OAuth scope.',
+            annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: false, openWorldHint: true },
+            parameters: evidenceSchema,
+            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. ' +
@@ -812,7 +990,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 ' +
@@ -847,7 +1025,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.',
@@ -871,9 +1049,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 ' +