@ampless/mcp-server 1.0.0-alpha.24 → 1.0.0-alpha.26

package/README.ja.md

@@ -68,6 +68,9 @@ import type { ToolDefinition, ToolContext, ResolvedSite } from '@ampless/mcp-ser
 | `update_post` | editor | 既存の投稿のフィールドをパッチ更新 |
 | `delete_post` | editor | 投稿を削除しタグインデックスをクリーンアップ |
 | `upload_media` | editor | Base64 エンコードされたバイト列を S3 にアップロードし Media レコードを作成 |
+| `list_media` | reader | メディア一覧を取得。`mimeType`（前方一致）/ `prefix` / `createdAfter` / `createdBefore` フィルターとページネーション対応 |
+| `search_media` | reader | ファイル名 / `src` / `mimeType` への部分一致でメディアを検索 |
+| `delete_media` | editor | メディアファイルを削除（S3 オブジェクト + Media 行）。`mediaId` または `src` で指定。`dryRun: true` で削除せずにプレビュー |
 | `get_schema` | reader | CMS コンテンツスキーマを返す |
 | `upload_static_bundle` | editor | ビルド済み静的バンドルを S3 にアップロード |
 | `list_static_files` | reader | 静的バンドルファイルを一覧表示 |

package/README.md

@@ -68,6 +68,9 @@ import type { ToolDefinition, ToolContext, ResolvedSite } from '@ampless/mcp-ser
 | `update_post` | editor | Patch fields on an existing post |
 | `delete_post` | editor | Delete a post and clean up its tag index |
 | `upload_media` | editor | Upload base64-encoded bytes to S3 and create a Media record |
+| `list_media` | reader | List media with optional `mimeType` (prefix) / `prefix` / `createdAfter` / `createdBefore` filters + pagination |
+| `search_media` | reader | Search media by substring across filename / `src` / `mimeType` |
+| `delete_media` | editor | Delete a media file (S3 object + Media row). Pass `mediaId` or `src`; `dryRun: true` previews without deleting |
 | `get_schema` | reader | Return the CMS content schema |
 | `upload_static_bundle` | editor | Upload a pre-built static bundle to S3 |
 | `list_static_files` | reader | List static bundle files |

package/dist/index.d.ts

@@ -68,6 +68,14 @@ interface StorageClient {
      * a few hundred entries per bundle in practice.
      */
     listObjects(prefix: string): Promise<StorageObject[]>;
+    /**
+     * Build the public URL for an object `key`, in the same format
+     * `putObject` returns (`https://{bucket}.s3.{region}.amazonaws.com/{key}`).
+     * Pure string formatting — no S3 round-trip. `list_media` /
+     * `search_media` use this to surface a `url` alongside each Media row
+     * without re-deriving the bucket/region in the tool layer.
+     */
+    publicUrl(key: string): string;
 }
 interface ToolContext {
     graphql: GraphqlClient;

package/dist/index.js

@@ -353,6 +353,276 @@ async function uploadMedia(graphql, storage, args) {
   return { media: data.createMedia, url: putResult.url };
 }
 
+// src/tools/media-mapping.ts
+var MEDIA_FIELDS = (
+  /* GraphQL */
+  `
+  fragment MediaFields on Media {
+    mediaId
+    src
+    mimeType
+    size
+    createdAt
+    updatedAt
+  }
+`
+);
+function toMediaResult(row, storage) {
+  return {
+    mediaId: row.mediaId,
+    src: row.src,
+    url: storage.publicUrl(row.src),
+    mimeType: row.mimeType,
+    size: row.size,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt
+  };
+}
+
+// src/tools/list-media.ts
+var QUERY2 = (
+  /* GraphQL */
+  `
+  ${MEDIA_FIELDS}
+  query ListMedia($filter: ModelMediaFilterInput, $limit: Int, $nextToken: String) {
+    listMedia(filter: $filter, limit: $limit, nextToken: $nextToken) {
+      items {
+        ...MediaFields
+      }
+      nextToken
+    }
+  }
+`
+);
+var listMediaSchema = {
+  type: "object",
+  properties: {
+    limit: {
+      type: "integer",
+      minimum: 1,
+      maximum: 100,
+      description: "Max results (default 20)"
+    },
+    nextToken: { type: "string", description: "Pagination cursor from a previous call" },
+    mimeType: {
+      type: "string",
+      description: 'Filter by MIME type prefix (beginsWith): "image/" matches all images, "image/png" matches PNG only.'
+    },
+    prefix: {
+      type: "string",
+      description: 'Filter by S3 key prefix (beginsWith) on `src`, e.g. "public/media/2024/" to find files from a given year.'
+    },
+    createdAfter: {
+      type: "string",
+      description: "ISO 8601 timestamp; only return media created at or after this."
+    },
+    createdBefore: {
+      type: "string",
+      description: "ISO 8601 timestamp; only return media created at or before this."
+    }
+  }
+};
+function buildMediaFilter(args) {
+  const conditions = [];
+  if (args.mimeType) conditions.push({ mimeType: { beginsWith: args.mimeType } });
+  if (args.prefix) conditions.push({ src: { beginsWith: args.prefix } });
+  if (args.createdAfter && args.createdBefore) {
+    conditions.push({ createdAt: { between: [args.createdAfter, args.createdBefore] } });
+  } else if (args.createdAfter) {
+    conditions.push({ createdAt: { ge: args.createdAfter } });
+  } else if (args.createdBefore) {
+    conditions.push({ createdAt: { le: args.createdBefore } });
+  }
+  if (conditions.length === 0) return void 0;
+  if (conditions.length === 1) return conditions[0];
+  return { and: conditions };
+}
+async function listMedia(graphql, storage, args = {}) {
+  const filter = buildMediaFilter(args);
+  const data = await graphql.query(QUERY2, {
+    filter,
+    limit: args.limit ?? 20,
+    nextToken: args.nextToken
+  });
+  return {
+    media: data.listMedia.items.map((row) => toMediaResult(row, storage)),
+    nextToken: data.listMedia.nextToken
+  };
+}
+
+// src/tools/search-media.ts
+var QUERY3 = (
+  /* GraphQL */
+  `
+  ${MEDIA_FIELDS}
+  query SearchMedia($filter: ModelMediaFilterInput, $limit: Int, $nextToken: String) {
+    listMedia(filter: $filter, limit: $limit, nextToken: $nextToken) {
+      items {
+        ...MediaFields
+      }
+      nextToken
+    }
+  }
+`
+);
+var MAX_PAGES = 20;
+var searchMediaSchema = {
+  type: "object",
+  required: ["query"],
+  properties: {
+    query: {
+      type: "string",
+      description: 'Substring matched (case-sensitive `contains`) against `src` (which includes the filename) and `mimeType`. e.g. "logo", ".png", "image/png".'
+    },
+    limit: {
+      type: "integer",
+      minimum: 1,
+      maximum: 100,
+      description: "Target number of matches to collect before stopping (default 20). A soft target \u2014 the last page may push the result slightly past it."
+    },
+    nextToken: { type: "string", description: "Pagination cursor from a previous call" }
+  }
+};
+async function searchMedia(graphql, storage, args) {
+  if (!args.query) {
+    throw new Error("search_media: `query` is required");
+  }
+  const limit = args.limit ?? 20;
+  const filter = {
+    or: [{ src: { contains: args.query } }, { mimeType: { contains: args.query } }]
+  };
+  const media = [];
+  let token = args.nextToken ?? null;
+  let pages = 0;
+  do {
+    const data = await graphql.query(QUERY3, {
+      filter,
+      limit,
+      nextToken: token ?? void 0
+    });
+    pages += 1;
+    for (const row of data.listMedia.items) {
+      media.push(toMediaResult(row, storage));
+    }
+    token = data.listMedia.nextToken;
+  } while (media.length < limit && token && pages < MAX_PAGES);
+  const truncated = media.length < limit && token !== null && pages >= MAX_PAGES;
+  return {
+    media,
+    nextToken: token,
+    ...truncated ? { truncated: true } : {}
+  };
+}
+
+// src/tools/delete-media.ts
+var GET_BY_ID2 = (
+  /* GraphQL */
+  `
+  query GetMedia($mediaId: ID!) {
+    getMedia(mediaId: $mediaId) {
+      mediaId
+      src
+    }
+  }
+`
+);
+var GET_BY_SRC = (
+  /* GraphQL */
+  `
+  query GetMediaBySrc($src: String!) {
+    getMediaBySrc(src: $src) {
+      mediaId
+      src
+    }
+  }
+`
+);
+var DELETE = (
+  /* GraphQL */
+  `
+  mutation DeleteMedia($input: DeleteMediaInput!) {
+    deleteMedia(input: $input) {
+      mediaId
+    }
+  }
+`
+);
+var deleteMediaSchema = {
+  type: "object",
+  properties: {
+    mediaId: {
+      type: "string",
+      description: "Media row primary key (e.g. 'media-1714400000000-abc123' as returned by `upload_media`). Provide either `mediaId` or `src`; mediaId is the direct path."
+    },
+    src: {
+      type: "string",
+      description: "Full S3 key including `public/` (e.g. 'public/media/2026/05/1714400000000-photo.jpg'). Use when you only have the public URL \u2014 strip `/api/media/` and prepend `public/`. Provide either `mediaId` or `src`."
+    },
+    dryRun: {
+      type: "boolean",
+      description: "When true, resolve the target but delete nothing (no S3 delete, no row delete). Returns `{ deleted: false, dryRun: true, ... }` previewing what would be removed. Use it to confirm before the real delete."
+    }
+  }
+};
+async function deleteMedia(graphql, storage, args) {
+  if (!args.mediaId && !args.src) {
+    throw new Error("delete_media: provide `mediaId` or `src`");
+  }
+  const dryRun = args.dryRun === true;
+  let mediaId;
+  let src;
+  if (args.mediaId) {
+    const data = await graphql.query(GET_BY_ID2, { mediaId: args.mediaId });
+    if (data.getMedia) {
+      mediaId = data.getMedia.mediaId;
+      src = data.getMedia.src;
+    }
+  } else {
+    const data = await graphql.query(GET_BY_SRC, { src: args.src });
+    if (data.getMediaBySrc) {
+      mediaId = data.getMediaBySrc.mediaId;
+      src = data.getMediaBySrc.src;
+    }
+  }
+  if (!mediaId) {
+    if (args.src) {
+      if (dryRun) {
+        return {
+          deleted: false,
+          dryRun: true,
+          reason: "dry run \u2014 media row not found; would attempt S3 object delete",
+          src: args.src
+        };
+      }
+      await storage.deleteObject(args.src);
+      return {
+        deleted: false,
+        reason: "media row not found; S3 object delete attempted (idempotent)",
+        src: args.src
+      };
+    }
+    return {
+      deleted: false,
+      ...dryRun ? { dryRun: true } : {},
+      reason: dryRun ? "dry run \u2014 media row not found for mediaId; nothing to delete" : "media row not found for mediaId"
+    };
+  }
+  if (dryRun) {
+    return {
+      deleted: false,
+      dryRun: true,
+      reason: "dry run \u2014 nothing deleted",
+      mediaId,
+      src
+    };
+  }
+  await storage.deleteObject(src);
+  await graphql.query(DELETE, {
+    input: { mediaId }
+  });
+  return { deleted: true, mediaId, src };
+}
+
 // src/tools/get-schema.ts
 var getSchemaSchema = {
   type: "object",
@@ -1309,6 +1579,29 @@ var tools = [
     inputSchema: uploadMediaSchema,
     handler: (args, ctx) => uploadMedia(ctx.graphql, ctx.storage(), args)
   },
+  {
+    name: "list_media",
+    description: 'List media files in the CMS. Optional filters: `mimeType` (prefix match \u2014 "image/" matches all images, "image/png" only PNG), `prefix` (S3 key prefix on `src`, e.g. "public/media/2024/"), `createdAfter` / `createdBefore` (ISO 8601 date range). Returns up to `limit` rows (default 20) \u2014 each `{ mediaId, src, url, mimeType, size, createdAt, updatedAt }` \u2014 plus a `nextToken` cursor. Note: filters apply after the page read, so a page may return fewer than `limit` rows while a `nextToken` remains \u2014 follow the cursor. Use this to find media to delete without remembering `upload_media` responses.',
+    inputSchema: listMediaSchema,
+    handler: (args, ctx) => listMedia(ctx.graphql, ctx.storage(), args)
+  },
+  {
+    name: "search_media",
+    description: 'Search media by substring (case-sensitive `contains`) across `src` (which includes the filename) and `mimeType`. Pass `query` (e.g. "logo", ".png", "image/png"). Walks DynamoDB pages internally until it collects at least `limit` matches (default 20), exhausts the table, or hits its page cap \u2014 so `limit` is a soft target and the result may run slightly past it. Returns the same row shape as `list_media` plus `nextToken`; `truncated: true` means the page cap was hit with more to scan (pass `nextToken` back to continue).',
+    inputSchema: searchMediaSchema,
+    handler: (args, ctx) => searchMedia(ctx.graphql, ctx.storage(), args)
+  },
+  {
+    name: "delete_media",
+    description: "Delete a media file: removes the S3 object and the Media row. Pass `mediaId` (from `upload_media`'s response, or `list_media` / `search_media`) or `src` (full S3 key like `public/media/2026/05/...`). When only `src` is given, looks up the Media row via `getMediaBySrc`. S3 delete runs first, then the DDB row delete \u2014 both are idempotent so re-running converges on missing-key cases. Pass `dryRun: true` to preview what would be deleted without touching anything (returns `{ deleted: false, dryRun: true, ... }`). Returns `{ deleted: false }` instead of throwing when no Media row matches; if `src` was supplied directly the S3 object is still removed (use this to sweep orphan files).",
+    inputSchema: deleteMediaSchema,
+    handler: (args, ctx) => deleteMedia(
+      ctx.graphql,
+      ctx.storage(),
+      args
+    ),
+    destructive: true
+  },
   {
     name: "get_schema",
     description: "Returns the CMS content schema (Post/Page/Media field shapes, format enum, notes). Useful as the first call to understand what fields are available.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/mcp-server",
-  "version": "1.0.0-alpha.24",
+  "version": "1.0.0-alpha.26",
   "description": "MCP tool registry shared by @ampless/backend mcp-handler Lambda. Installed transitively via @ampless/admin / @ampless/backend; no direct install needed.",
   "publishConfig": {
     "access": "public"