@myna-sh/mcp 0.4.0 → 0.5.0

package/README.md

@@ -28,7 +28,7 @@ Configure your MCP client to run:
 }
 ```
 
-Use a narrowly scoped Myna API key and keep it out of source control.
+Use a narrowly scoped Myna API key and keep it out of source control. A key can also be confined to specific collections (`myna keys create --collections changelog`), which is worth doing for an agent with one job: the server then cannot reach content outside it, whatever it is asked to do.
 
 ## Streamable HTTP
 

package/dist/main.js

@@ -340,6 +340,12 @@ var ManagementClient = class {
     collections: (project, signal) => this.get(`/projects/${enc(project)}/collections`, void 0, signal),
     collection: (project, key, signal) => this.get(`/projects/${enc(project)}/collections/${enc(key)}`, void 0, signal),
     versions: (project, key, signal) => this.get(`/projects/${enc(project)}/collections/${enc(key)}/versions`, void 0, signal),
+    /** What is still untranslated in a collection, per project locale. */
+    translations: (project, key, signal) => this.get(
+      `/projects/${enc(project)}/collections/${enc(key)}/translations`,
+      void 0,
+      signal
+    ),
     diff: (project, collections) => this.mutate("POST", `/projects/${enc(project)}/schema/diff`, { collections }),
     push: (project, collections, opts = {}) => this.mutate("POST", `/projects/${enc(project)}/schema/push`, {
       collections,
@@ -358,7 +364,8 @@ var ManagementClient = class {
   entries = {
     list: (project, opts = {}) => this.page(`/projects/${enc(project)}/entries`, opts, {
       collection: opts.collection,
-      status: opts.status
+      status: opts.status,
+      q: opts.q
     }),
     create: (project, body) => this.mutate("POST", `/projects/${enc(project)}/entries`, body),
     get: (project, entry, signal) => this.get(`/projects/${enc(project)}/entries/${enc(entry)}`, void 0, signal),
@@ -438,7 +445,25 @@ var ManagementClient = class {
       void 0,
       signal
     ),
-    runChecks: (project, changeSet) => this.mutate("POST", `/projects/${enc(project)}/change-sets/${enc(changeSet)}/checks/run`)
+    runChecks: (project, changeSet) => this.mutate("POST", `/projects/${enc(project)}/change-sets/${enc(changeSet)}/checks/run`),
+    /** Report a verdict Myna cannot compute, against the current contents. */
+    reportCheck: (project, changeSet, name, body) => this.mutate(
+      "POST",
+      `/projects/${enc(project)}/change-sets/${enc(changeSet)}/checks/${enc(name)}`,
+      body
+    ),
+    /** Field-level before/after for everything this change set would change. */
+    diff: (project, changeSet, signal) => this.get(
+      `/projects/${enc(project)}/change-sets/${enc(changeSet)}/diff`,
+      void 0,
+      signal
+    )
+  };
+  // --- Declared external checks ---------------------------------------------
+  checks = {
+    list: (project, signal) => this.get(`/projects/${enc(project)}/checks`, void 0, signal),
+    declare: (project, body) => this.mutate("POST", `/projects/${enc(project)}/checks`, body),
+    remove: (project, name) => this.mutate("DELETE", `/projects/${enc(project)}/checks/${enc(name)}`)
   };
   // --- Previews -------------------------------------------------------------
   previews = {
@@ -452,7 +477,11 @@ var ManagementClient = class {
     completeUpload: (project, upload) => this.mutate("POST", `/projects/${enc(project)}/assets/uploads/${enc(upload)}/complete`).then(
       (r) => r.asset
     ),
-    list: (project, opts = {}) => this.page(`/projects/${enc(project)}/assets`, opts),
+    list: (project, opts = {}) => this.page(`/projects/${enc(project)}/assets`, opts, {
+      tag: opts.tag,
+      checksum: opts.checksum,
+      orphaned: opts.orphaned ? "true" : void 0
+    }),
     get: (project, asset, signal) => this.get(`/projects/${enc(project)}/assets/${enc(asset)}`, void 0, signal),
     usage: (project, asset, signal) => this.get(`/projects/${enc(project)}/assets/${enc(asset)}`, { usage: "true" }, signal),
     update: (project, asset, body) => this.mutate("PATCH", `/projects/${enc(project)}/assets/${enc(asset)}`, body),
@@ -704,7 +733,10 @@ function loadConfigFile(env) {
 import { z } from "zod";
 function ok(text, structured) {
   return {
-    content: [{ type: "text", text }],
+    content: [
+      { type: "text", text },
+      { type: "text", text: JSON.stringify(structured) }
+    ],
     structuredContent: structured
   };
 }
@@ -1273,6 +1305,387 @@ function registerTools(server, registry, options = { allowPathUploads: true }) {
       }
     }
   );
+  server.registerTool(
+    "myna_list_change_sets",
+    {
+      title: "List change sets",
+      description: "List change sets in a project, newest first, optionally filtered by status (open, ready, published, closed). Use this to find work already in progress before starting a new change set.",
+      inputSchema: {
+        ...projectArg,
+        status: z.enum(["open", "ready", "published", "closed"]).optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+        cursor: z.string().optional()
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const page = await client.changeSets.list(project, {
+          ...args.status ? { status: args.status } : {},
+          ...args.limit ? { limit: args.limit } : {},
+          ...args.cursor ? { cursor: args.cursor } : {}
+        });
+        return ok(`${page.data.length} change set(s).`, page);
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_diff_change_set",
+    {
+      title: "Diff a change set",
+      description: "Show what a change set would change, field by field: per item, the operation, the collection and slug, and every changed field with its before and after value. This is what a reviewer reads; use it to summarize your own work or to review someone else's.",
+      inputSchema: { ...projectArg, changeSet: z.string() },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const diff = await client.changeSets.diff(project, args.changeSet);
+        const fields = diff.items.reduce((n, i) => n + i.changes.length, 0);
+        return ok(`${diff.items.length} item(s), ${fields} changed field(s).`, diff);
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_update_change_set",
+    {
+      title: "Update a change set",
+      description: "Rename a change set, change its description, or mark it ready for review. Marking it ready signals that a human is needed and emits change_set.ready_for_review.",
+      inputSchema: {
+        ...projectArg,
+        changeSet: z.string(),
+        title: z.string().min(1).max(200).optional(),
+        description: z.string().max(2e3).optional(),
+        status: z.enum(["open", "ready"]).optional()
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const cs = await client.changeSets.update(project, args.changeSet, {
+          ...args.title ? { title: args.title } : {},
+          ...args.description ? { description: args.description } : {},
+          ...args.status ? { status: args.status } : {}
+        });
+        return ok(`Change set ${cs.id} is ${cs.status}.`, { changeSet: cs });
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_close_change_set",
+    {
+      title: "Close a change set",
+      description: "Abandon a change set without publishing it. The staged drafts and their revisions remain in history; the set simply stops being work in progress. Use this when a task is cancelled, so open sets do not accumulate. Requires confirm=true.",
+      inputSchema: { ...projectArg, changeSet: z.string(), confirm: z.literal(true).describe("Must be true.") },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const cs = await client.changeSets.close(project, args.changeSet);
+        return ok(`Closed ${cs.id}.`, { changeSet: cs });
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_request_change_set_review",
+    {
+      title: "Request review",
+      description: "Ask a specific person to review a change set. Pass their user id. Requires content:review scope.",
+      inputSchema: {
+        ...projectArg,
+        changeSet: z.string(),
+        reviewerId: z.string().describe("User id (usr_) to assign as reviewer.")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const reviews = await client.changeSets.requestReview(project, args.changeSet, {
+          reviewerType: "user",
+          reviewerId: args.reviewerId
+        });
+        return ok(`${reviews.length} reviewer(s) assigned.`, { reviews });
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_report_check_result",
+    {
+      title: "Report an external check result",
+      description: "Report the verdict of a check Myna cannot compute itself \u2014 a link check, a house-style review, an external build. The check must have been declared on the project first. The result is recorded against the change set's current contents, so later edits mark it stale. A failing required check blocks publish. Requires content:review scope.",
+      inputSchema: {
+        ...projectArg,
+        changeSet: z.string(),
+        name: z.string().describe("The declared check name, e.g. links."),
+        status: z.enum(["passed", "failed", "skipped"]),
+        details: z.array(
+          z.object({
+            resourceId: z.string().optional(),
+            path: z.string().optional(),
+            message: z.string()
+          })
+        ).optional().describe("What the check found; shown to the reviewer.")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const check = await client.changeSets.reportCheck(project, args.changeSet, args.name, {
+          status: args.status,
+          ...args.details ? { details: args.details } : {}
+        });
+        return ok(`Reported ${args.name}: ${check.status}.`, { check });
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_search_entries",
+    {
+      title: "Search entries",
+      description: 'Full-text search across every text field of an entry, matching either its draft or its published state. Use this to find the entry a human described in prose ("the pricing page", "the post about webhooks") instead of listing a collection and scanning it.',
+      inputSchema: {
+        ...projectArg,
+        query: z.string().min(1).describe("Words to search for. Supports quoted phrases and -exclusions."),
+        collection: z.string().optional().describe("Restrict to one collection."),
+        limit: z.number().int().min(1).max(100).optional()
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const page = await client.entries.list(project, {
+          q: args.query,
+          ...args.collection ? { collection: args.collection } : {},
+          limit: args.limit ?? 20
+        });
+        return ok(`${page.data.length} match(es) for "${args.query}".`, page);
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_unpublish_entry",
+    {
+      title: "Unpublish an entry",
+      description: "Stage the removal of an entry from published content. Like every write this is a draft operation: it takes effect when the change set is published. The entry and its history are kept. Requires confirm=true.",
+      inputSchema: {
+        ...projectArg,
+        entry: z.string(),
+        changeSet: z.string().optional(),
+        confirm: z.literal(true).describe("Must be true.")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const id = await resolveEntryId(client, project, args.entry);
+        const result = await client.entries.unpublish(project, id, args.changeSet);
+        return ok(`Unpublish staged on ${result.changeSetId}.`, result);
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_duplicate_entry",
+    {
+      title: "Duplicate an entry",
+      description: "Copy an entry into a new draft with a fresh slug. Useful as a starting point when a new entry should follow the shape of an existing one.",
+      inputSchema: { ...projectArg, entry: z.string(), changeSet: z.string().optional() },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const id = await resolveEntryId(client, project, args.entry);
+        const entry = await client.entries.duplicate(project, id, args.changeSet);
+        return ok(`Created ${entry.id} (${entry.slug ?? "no slug"}).`, { entry });
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_import_entries",
+    {
+      title: "Import entries",
+      description: "Create or update many entries in one collection in a single call, matched by slug: rows that already exist are updated, identical rows are skipped. Use dryRun=true first to see what would happen. Everything lands as drafts on one change set.",
+      inputSchema: {
+        ...projectArg,
+        collection: z.string(),
+        entries: z.array(z.object({ slug: z.string().optional(), data: z.record(z.string(), z.unknown()) })).min(1).max(500),
+        changeSet: z.string().optional(),
+        changeSummary: z.string().optional(),
+        dryRun: z.boolean().optional().describe("Report what would change without writing.")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const result = await client.entries.import(project, {
+          collection: args.collection,
+          entries: args.entries,
+          ...args.changeSet ? { changeSetId: args.changeSet } : {},
+          ...args.changeSummary ? { changeSummary: args.changeSummary } : {},
+          ...args.dryRun !== void 0 ? { dryRun: args.dryRun } : {}
+        });
+        const { created, updated, unchanged, invalid } = result.summary;
+        return ok(
+          `${args.dryRun ? "Would import" : "Imported"}: ${created} created, ${updated} updated, ${unchanged} unchanged, ${invalid} invalid.`,
+          result
+        );
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_reorder_entries",
+    {
+      title: "Reorder a collection",
+      description: "Set the editorial order of a collection. Unlike every other write, ordering is arrangement rather than content: it carries no revision, is not staged on a change set, and reaches readers immediately \u2014 which is why confirm=true is required. Never use it to change what an entry says.",
+      inputSchema: {
+        ...projectArg,
+        collection: z.string(),
+        order: z.array(z.string()).optional().describe("Entry ids in the intended order."),
+        move: z.object({ entry: z.string(), before: z.string().optional(), after: z.string().optional() }).optional().describe("Move one entry relative to another, instead of listing the whole order."),
+        confirm: z.literal(true).describe("Must be true: this is immediately visible to readers.")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        if (Boolean(args.order) === Boolean(args.move)) {
+          throw new Error("Provide exactly one of `order` or `move`.");
+        }
+        const { client, project } = registry.clientFor(args.project);
+        const result = await client.entries.reorder(project, args.collection, {
+          ...args.order ? { order: args.order } : {},
+          ...args.move ? { move: args.move } : {}
+        });
+        return ok(`Reordered with ${result.writes} write(s).`, result);
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_list_assets",
+    {
+      title: "List assets",
+      description: "List a project's assets, optionally filtered by tag or checksum. Check here before uploading: an asset that already exists should be referenced, not uploaded again.",
+      inputSchema: {
+        ...projectArg,
+        tag: z.string().optional(),
+        checksum: z.string().optional().describe("MD5 hex; finds an identical file already uploaded."),
+        limit: z.number().int().min(1).max(100).optional(),
+        cursor: z.string().optional()
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const page = await client.assets.list(project, {
+          ...args.tag ? { tag: args.tag } : {},
+          ...args.checksum ? { checksum: args.checksum } : {},
+          ...args.limit ? { limit: args.limit } : {},
+          ...args.cursor ? { cursor: args.cursor } : {}
+        });
+        return ok(`${page.data.length} asset(s).`, page);
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_get_asset",
+    {
+      title: "Get an asset",
+      description: "Fetch one asset: its delivery URL, content type, byte size, pixel dimensions, alt text, and tags.",
+      inputSchema: { ...projectArg, asset: z.string().describe("Asset id (ast_).") },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const asset = await client.assets.get(project, args.asset);
+        return ok(`${asset.displayFilename} (${asset.contentType}).`, { asset });
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_update_asset",
+    {
+      title: "Update asset metadata",
+      description: "Set an asset's alt text, caption, display filename, or tags. Alt text in particular is what the built-in alt-text check looks for, so filling it in here clears that check.",
+      inputSchema: {
+        ...projectArg,
+        asset: z.string(),
+        defaultAlt: z.string().optional(),
+        caption: z.string().optional(),
+        displayFilename: z.string().optional(),
+        tags: z.array(z.string()).optional()
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const asset = await client.assets.update(project, args.asset, {
+          ...args.defaultAlt !== void 0 ? { defaultAlt: args.defaultAlt } : {},
+          ...args.caption !== void 0 ? { caption: args.caption } : {},
+          ...args.displayFilename !== void 0 ? { displayFilename: args.displayFilename } : {},
+          ...args.tags !== void 0 ? { tags: args.tags } : {}
+        });
+        return ok(`Updated ${asset.id}.`, { asset });
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_translation_coverage",
+    {
+      title: "Translation coverage",
+      description: "Report what is still untranslated in a collection, per project locale: how complete each locale is, which fields are missing most often, and a worklist of entries to fix. Empty when the project has no locales or the collection has no localized fields.",
+      inputSchema: { ...projectArg, collection: z.string() },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const report = await client.schema.translations(project, args.collection);
+        const summary = report.coverage.map((c) => `${c.locale} ${c.percent}%`).join(", ");
+        return ok(summary || "No localized fields.", report);
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
 }
 
 // src/resources.ts
@@ -1286,7 +1699,7 @@ function registerResources(server, registry) {
     "myna://projects",
     { title: "Projects", description: "Projects in the default organization.", mimeType: "application/json" },
     async (uri) => {
-      const { client } = registry.clientFor();
+      const { client } = registry.clientForOrg();
       const org = registry.organizationFor();
       const projects = await client.projects.list(org);
       return json(uri.href, { organization: org, projects });
@@ -1347,7 +1760,7 @@ function registerResources(server, registry) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.4.0" : "0.0.0-dev";
+var VERSION = true ? "0.5.0" : "0.0.0-dev";
 
 // src/server.ts
 var SERVER_NAME = "myna";