44reports-mcp 1.4.0 → 1.5.0

package/dist/api-client.d.ts

@@ -262,6 +262,34 @@ export declare class ApiClient {
     }): Promise<{
         files: PulledFile[];
     }>;
+    findAssets(slug: string, options?: {
+        query?: string;
+        asset_type?: string;
+        surfaces?: string[];
+        orientation?: string | null;
+        background?: string | null;
+        color_mode?: string | null;
+        platform?: string | null;
+        locale?: string | null;
+        include_drafts?: boolean;
+        limit?: number;
+        ttl?: number;
+    }): Promise<{
+        query: string | null;
+        filters: Record<string, unknown>;
+        total_inventory: number;
+        matched: number;
+        results: Array<{
+            path: string;
+            score: number;
+            matched_terms: string[];
+            content_type: string;
+            size: number;
+            entry: Record<string, unknown>;
+            url: string;
+            expires_at: string;
+        }>;
+    }>;
     addBacklogEntry(data: {
         content: string;
         product_slug?: string;

package/dist/api-client.js

@@ -172,6 +172,30 @@ export class ApiClient {
             body: JSON.stringify(options ?? {}),
         });
     }
+    async findAssets(slug, options = {}) {
+        const params = new URLSearchParams();
+        if (options.query)
+            params.set('q', options.query);
+        if (options.asset_type)
+            params.set('asset_type', options.asset_type);
+        if (options.surfaces?.length)
+            params.set('surfaces', options.surfaces.join(','));
+        // For variant fields, undefined = no filter; null = require null on the entry; string = exact match.
+        for (const k of ['orientation', 'background', 'color_mode', 'platform', 'locale']) {
+            const v = options[k];
+            if (v === null)
+                params.set(k, '');
+            else if (typeof v === 'string')
+                params.set(k, v);
+        }
+        if (options.include_drafts === false)
+            params.set('include_drafts', 'false');
+        if (options.limit !== undefined)
+            params.set('limit', String(options.limit));
+        if (options.ttl !== undefined)
+            params.set('ttl', String(options.ttl));
+        return this.request(withQuery(`/api/products/${slug}/find-assets`, params));
+    }
     // --- Agent Backlog ---
     async addBacklogEntry(data) {
         return this.request('/api/backlog', {

package/dist/index.js

@@ -8,7 +8,7 @@ import { deployReportSchema, updateReportSchema, createDeployTool, createUpdateT
 import { listReportsSchema, getReportSchema, deleteReportSchema, createListTool, createGetTool, createDeleteTool, } from './tools/reports.js';
 import { pullContextSchema, createPullTool, } from './tools/pull.js';
 import { manageFoldersSchema, createManageFoldersTool, } from './tools/folders.js';
-import { listProductsSchema, getProductSchema, readProductFileSchema, updateProductKnowledgeSchema, uploadProductFilesSchema, pullProductFilesSchema, createProductSchema, deleteProductSchema, deleteProductFileSchema, getProductHealthSchema, getProductIndexSchema, createListProductsTool, createGetProductTool, createReadProductFileTool, createUpdateProductKnowledgeTool, createUploadProductFilesTool, createPullProductFilesTool, createGetProductHealthTool, createGetProductIndexTool, createCreateProductTool, createDeleteProductTool, createDeleteProductFileTool, } from './tools/products.js';
+import { listProductsSchema, getProductSchema, readProductFileSchema, updateProductKnowledgeSchema, uploadProductFilesSchema, pullProductFilesSchema, createProductSchema, deleteProductSchema, deleteProductFileSchema, getProductHealthSchema, getProductIndexSchema, createListProductsTool, createGetProductTool, createReadProductFileTool, createUpdateProductKnowledgeTool, createUploadProductFilesTool, createPullProductFilesTool, createGetProductHealthTool, createGetProductIndexTool, createCreateProductTool, createDeleteProductTool, createDeleteProductFileTool, createFindAssetsTool, findAssetsSchema, } from './tools/products.js';
 import { createUploadProductDirectoryTool, uploadProductDirectorySchema, UPLOAD_DIRECTORY_DESCRIPTION, } from './tools/upload-directory.js';
 import { addToBacklogSchema, listBacklogSchema, processBacklogSchema, createAddToBacklogTool, createListBacklogTool, createProcessBacklogTool, } from './tools/backlog.js';
 import { DOMAIN_VALUES } from './tools/domains.js';
@@ -342,6 +342,40 @@ const toolDefinitions = [
         schema: deleteProductFileSchema,
         handler: createDeleteProductFileTool(client),
     },
+    {
+        name: 'find_assets',
+        description: 'Search a product\'s asset inventory by free-text query and structured filters. Returns ranked entries with descriptions, taxonomy fields, and short-lived signed download URLs.\n\n' +
+            'Prefer this over scanning binary_files from get_product when you know what kind of asset you want — agents reading 30+ paths and guessing from filenames is the failure mode this tool exists to fix.\n\n' +
+            'Examples:\n' +
+            '  • { slug: "clara", query: "horizontal logo for landing page", asset_type: "logo", surfaces: ["landing"], background: "transparent" }\n' +
+            '  • { slug: "clara", asset_type: "app-icon", platform: "ios" }  — pure filter query, no text\n' +
+            '  • { slug: "clara", query: "device mockup with hand holding phone" }  — semantic, no filters\n\n' +
+            'Empty string for orientation/background/color_mode/platform/locale means "the entry has this variant set to null". Drafts (auto-described, unverified) are included by default; pass include_drafts=false to exclude them.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                slug: prop('string', 'Product slug'),
+                query: prop('string', 'Free-text query against description, usage, file path, asset_type, and surfaces.'),
+                asset_type: prop('string', 'Restrict to one asset_type.', {
+                    enum: ['logo', 'app-icon', 'screenshot-ui', 'screenshot-marketing', 'mockup', 'photo-lifestyle', 'photo-product', 'illustration', 'color-swatch', 'typography-sample', 'brand-guide-page', 'video', 'animation', 'document', 'other'],
+                }),
+                surfaces: prop('array', 'ANY-of match against the entry\'s surfaces array.', {
+                    items: { type: 'string', enum: ['ad-creative', 'app-store', 'landing', 'email', 'social-organic', 'brand-guide', 'internal-doc'] },
+                }),
+                orientation: prop('string', 'Variant filter.', { enum: ['horizontal', 'vertical', 'square'] }),
+                background: prop('string', 'Variant filter.', { enum: ['transparent', 'solid-light', 'solid-dark', 'photographic'] }),
+                color_mode: prop('string', 'Variant filter.', { enum: ['light', 'dark', 'neutral'] }),
+                platform: prop('string', 'Variant filter.', { enum: ['ios', 'android', 'web'] }),
+                locale: prop('string', 'Filter by exact locale string (BCP-47, e.g. "en-US").'),
+                include_drafts: prop('boolean', 'Include auto-described draft entries (default true).'),
+                limit: prop('number', 'Maximum number of results. Default 20, max 100.'),
+                ttl: prop('number', 'Lifetime in seconds for the signed download URLs (default 600, max 3600).'),
+            },
+            required: ['slug'],
+        },
+        schema: findAssetsSchema,
+        handler: createFindAssetsTool(client),
+    },
     {
         name: 'add_to_backlog',
         description: 'Add an unstructured observation to the agent backlog for later processing. Low-friction way for any agent to contribute signals — competitor insights, user feedback, research findings, or any data that should eventually enrich product knowledge. Only content is required; everything else is optional.\n\nIf you know which product this relates to, pass product_slug. Otherwise, omit it — the backlog processor will auto-route it to the right product (or reject it as noise).',

package/dist/tools/products.d.ts

@@ -142,6 +142,46 @@ export declare const deleteProductFileSchema: z.ZodObject<{
     slug: string;
     filepath: string;
 }>;
+export declare const findAssetsSchema: z.ZodObject<{
+    slug: z.ZodString;
+    query: z.ZodOptional<z.ZodString>;
+    asset_type: z.ZodOptional<z.ZodEnum<["logo", "app-icon", "screenshot-ui", "screenshot-marketing", "mockup", "photo-lifestyle", "photo-product", "illustration", "color-swatch", "typography-sample", "brand-guide-page", "video", "animation", "document", "other"]>>;
+    surfaces: z.ZodOptional<z.ZodArray<z.ZodEnum<["ad-creative", "app-store", "landing", "email", "social-organic", "brand-guide", "internal-doc"]>, "many">>;
+    orientation: z.ZodOptional<z.ZodEnum<["horizontal", "vertical", "square"]>>;
+    background: z.ZodOptional<z.ZodEnum<["transparent", "solid-light", "solid-dark", "photographic"]>>;
+    color_mode: z.ZodOptional<z.ZodEnum<["light", "dark", "neutral"]>>;
+    platform: z.ZodOptional<z.ZodEnum<["ios", "android", "web"]>>;
+    locale: z.ZodOptional<z.ZodString>;
+    include_drafts: z.ZodOptional<z.ZodBoolean>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    ttl: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    slug: string;
+    limit?: number | undefined;
+    ttl?: number | undefined;
+    asset_type?: "logo" | "app-icon" | "screenshot-ui" | "screenshot-marketing" | "mockup" | "photo-lifestyle" | "photo-product" | "illustration" | "color-swatch" | "typography-sample" | "brand-guide-page" | "video" | "animation" | "document" | "other" | undefined;
+    surfaces?: ("app-store" | "ad-creative" | "landing" | "email" | "social-organic" | "brand-guide" | "internal-doc")[] | undefined;
+    orientation?: "horizontal" | "vertical" | "square" | undefined;
+    background?: "transparent" | "solid-light" | "solid-dark" | "photographic" | undefined;
+    color_mode?: "light" | "dark" | "neutral" | undefined;
+    platform?: "ios" | "android" | "web" | undefined;
+    locale?: string | undefined;
+    include_drafts?: boolean | undefined;
+    query?: string | undefined;
+}, {
+    slug: string;
+    limit?: number | undefined;
+    ttl?: number | undefined;
+    asset_type?: "logo" | "app-icon" | "screenshot-ui" | "screenshot-marketing" | "mockup" | "photo-lifestyle" | "photo-product" | "illustration" | "color-swatch" | "typography-sample" | "brand-guide-page" | "video" | "animation" | "document" | "other" | undefined;
+    surfaces?: ("app-store" | "ad-creative" | "landing" | "email" | "social-organic" | "brand-guide" | "internal-doc")[] | undefined;
+    orientation?: "horizontal" | "vertical" | "square" | undefined;
+    background?: "transparent" | "solid-light" | "solid-dark" | "photographic" | undefined;
+    color_mode?: "light" | "dark" | "neutral" | undefined;
+    platform?: "ios" | "android" | "web" | undefined;
+    locale?: string | undefined;
+    include_drafts?: boolean | undefined;
+    query?: string | undefined;
+}>;
 export declare function createListProductsTool(client: ApiClient): (input: z.infer<typeof listProductsSchema>) => Promise<{
     products: Array<{
         id: string;
@@ -251,3 +291,19 @@ export declare function createDeleteProductTool(client: ApiClient): (input: z.in
 export declare function createDeleteProductFileTool(client: ApiClient): (input: z.infer<typeof deleteProductFileSchema>) => Promise<{
     success: boolean;
 }>;
+export declare function createFindAssetsTool(client: ApiClient): (input: z.infer<typeof findAssetsSchema>) => Promise<{
+    query: string | null;
+    filters: Record<string, unknown>;
+    total_inventory: number;
+    matched: number;
+    results: Array<{
+        path: string;
+        score: number;
+        matched_terms: string[];
+        content_type: string;
+        size: number;
+        entry: Record<string, unknown>;
+        url: string;
+        expires_at: string;
+    }>;
+}>;

package/dist/tools/products.js

@@ -77,6 +77,31 @@ export const deleteProductFileSchema = z.object({
     slug: z.string().describe('Product slug'),
     filepath: z.string().describe('File path within the product to delete (e.g., "docs/copy/old-brief.md", "brand-assets/old-logo.png")'),
 });
+const ASSET_TYPE_VALUES = [
+    'logo', 'app-icon', 'screenshot-ui', 'screenshot-marketing', 'mockup',
+    'photo-lifestyle', 'photo-product', 'illustration', 'color-swatch',
+    'typography-sample', 'brand-guide-page', 'video', 'animation', 'document', 'other',
+];
+const SURFACE_VALUES = [
+    'ad-creative', 'app-store', 'landing', 'email', 'social-organic', 'brand-guide', 'internal-doc',
+];
+export const findAssetsSchema = z.object({
+    slug: z.string().describe('Product slug'),
+    query: z
+        .string()
+        .optional()
+        .describe('Free-text query — matched against asset description, usage notes, file path, asset_type, and surfaces. Use this for "what" you want ("phone illustration", "horizontal wordmark", "iOS launch icon"). Combine with structured filters for "where" the asset belongs.'),
+    asset_type: z.enum(ASSET_TYPE_VALUES).optional().describe('Restrict to one asset_type.'),
+    surfaces: z.array(z.enum(SURFACE_VALUES)).optional().describe('ANY-of match against the entry\'s surfaces array. e.g. ["ad-creative","landing"] returns assets used on either.'),
+    orientation: z.enum(['horizontal', 'vertical', 'square']).optional().describe('Filter by orientation variant.'),
+    background: z.enum(['transparent', 'solid-light', 'solid-dark', 'photographic']).optional().describe('Filter by background variant.'),
+    color_mode: z.enum(['light', 'dark', 'neutral']).optional().describe('Filter by color_mode variant.'),
+    platform: z.enum(['ios', 'android', 'web']).optional().describe('Filter by platform variant.'),
+    locale: z.string().optional().describe('Filter by exact locale string (BCP-47, e.g. "en-US").'),
+    include_drafts: z.boolean().optional().describe('Include auto-described draft entries (unverified by a curator). Default true. Drafts are real entries with descriptions; the flag is a confidence marker.'),
+    limit: z.number().int().positive().max(100).optional().describe('Maximum number of results. Default 20, max 100.'),
+    ttl: z.number().int().positive().max(3600).optional().describe('Lifetime in seconds for the signed download URLs returned with each result. Default 600, max 3600.'),
+});
 // --- Tool factories ---
 export function createListProductsTool(client) {
     return async (input) => {
@@ -193,3 +218,20 @@ export function createDeleteProductFileTool(client) {
         return client.deleteProductFile(input.slug, input.filepath);
     };
 }
+export function createFindAssetsTool(client) {
+    return async (input) => {
+        return client.findAssets(input.slug, {
+            query: input.query,
+            asset_type: input.asset_type,
+            surfaces: input.surfaces,
+            orientation: input.orientation,
+            background: input.background,
+            color_mode: input.color_mode,
+            platform: input.platform,
+            locale: input.locale,
+            include_drafts: input.include_drafts,
+            limit: input.limit,
+            ttl: input.ttl,
+        });
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "44reports-mcp",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "description": "MCP server for deploying and pulling context files (code, docs, data) to/from 44reports",
   "main": "dist/index.js",