44reports-mcp 1.0.8 → 1.1.0

package/dist/api-client.d.ts

@@ -52,6 +52,7 @@ export interface Folder {
     name: string;
     description: string | null;
     allowed_domains: string[];
+    allowed_emails: string[];
     created_at: string;
     updated_at: string;
 }
@@ -92,7 +93,8 @@ export declare class ApiClient {
         name: string;
         slug?: string;
         description?: string;
-        allowed_domains: string[];
+        allowed_domains?: string[];
+        allowed_emails?: string[];
     }): Promise<{
         folder: Folder;
     }>;
@@ -104,6 +106,7 @@ export declare class ApiClient {
         name?: string;
         description?: string;
         allowed_domains?: string[];
+        allowed_emails?: string[];
     }): Promise<{
         folder: Folder;
     }>;
@@ -117,4 +120,52 @@ export declare class ApiClient {
     removeReportFromFolder(folderSlug: string, reportSlug: string): Promise<{
         success: boolean;
     }>;
+    listProducts(): Promise<{
+        products: Array<{
+            id: string;
+            slug: string;
+            name: string;
+            description: string | null;
+            json_file_count: number;
+            binary_file_count: number;
+        }>;
+    }>;
+    getProduct(slug: string): Promise<{
+        product: {
+            id: string;
+            slug: string;
+            name: string;
+            description: string | null;
+            created_at: string;
+            updated_at: string;
+        };
+        knowledge: Record<string, unknown>;
+        binary_files: Array<{
+            path: string;
+            size: number;
+            content_type: string;
+        }>;
+    }>;
+    getProductFile(slug: string, filepath: string): Promise<{
+        path: string;
+        content: unknown;
+        content_type: string;
+        size?: number;
+    }>;
+    updateProductFile(slug: string, filepath: string, body: {
+        content: unknown;
+        updated_by?: string;
+    }): Promise<{
+        success: boolean;
+        path: string;
+        merged?: unknown;
+    }>;
+    uploadProductFiles(slug: string, files: Array<{
+        path: string;
+        content: string;
+        content_type?: string;
+    }>): Promise<{
+        success: boolean;
+        uploaded: string[];
+    }>;
 }

package/dist/api-client.js

@@ -90,4 +90,26 @@ export class ApiClient {
             method: 'DELETE',
         });
     }
+    // --- Product Knowledge ---
+    async listProducts() {
+        return this.request('/api/products');
+    }
+    async getProduct(slug) {
+        return this.request(`/api/products/${slug}`);
+    }
+    async getProductFile(slug, filepath) {
+        return this.request(`/api/products/${slug}/files/${filepath}`);
+    }
+    async updateProductFile(slug, filepath, body) {
+        return this.request(`/api/products/${slug}/files/${filepath}`, {
+            method: 'PUT',
+            body: JSON.stringify(body),
+        });
+    }
+    async uploadProductFiles(slug, files) {
+        return this.request(`/api/products/${slug}/files`, {
+            method: 'POST',
+            body: JSON.stringify({ files }),
+        });
+    }
 }

package/dist/index.js

@@ -8,6 +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, createListProductsTool, createGetProductTool, createReadProductFileTool, createUpdateProductKnowledgeTool, createUploadProductFilesTool, createPullProductFilesTool, } from './tools/products.js';
 const config = loadConfig();
 const client = new ApiClient(config);
 function prop(type, description, extra = {}) {
@@ -18,7 +19,7 @@ const FOLDER_PATH_DESC = 'RECOMMENDED for most contexts. Uploads all supported f
 const toolDefinitions = [
     {
         name: 'deploy_context',
-        description: 'Deploy files to the context repository. Supports any text-based files (code, docs, data, config) and binary files (images, fonts). For simple single-file contexts, use content. For multi-file contexts, use folder_path (recommended). Returns a stable URL for viewing and sharing.',
+        description: 'Deploy an output artifact to the context repository — use for one-time or versioned outputs: research reports, data analysis, dashboards, HTML visualizations, CSV exports, agent session summaries.\n\nIMPORTANT: Do NOT use this for brand or product knowledge (guidelines, copy, ad accounts, CPPs, product positioning). For persistent product knowledge that agents read and update over time, use update_product_knowledge instead.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -40,7 +41,7 @@ const toolDefinitions = [
     },
     {
         name: 'update_context',
-        description: 'Update an existing context. The URL remains stable. You can update metadata, content, or both.',
+        description: 'Update an existing output artifact context. The URL remains stable. You can update metadata, content, or both.\n\nIMPORTANT: Do NOT use this for brand or product knowledge. Use update_product_knowledge for product profiles, brand guidelines, copy, and ad accounts.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -116,7 +117,7 @@ const toolDefinitions = [
     },
     {
         name: 'manage_folders',
-        description: 'Manage folders for domain-scoped access control. Folders let you share specific contexts with external users by email domain (e.g., share investor reports with vgames.vc).',
+        description: 'Manage folders for access control. Folders let you share contexts with external users by email domain (e.g., vgames.vc) or individual email address (e.g., investor@gmail.com).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -126,7 +127,8 @@ const toolDefinitions = [
                 slug: prop('string', 'Folder slug (required for get/update/delete/add_reports/remove_report)'),
                 name: prop('string', 'Folder name (required for create)'),
                 description: prop('string', 'Folder description'),
-                allowed_domains: prop('array', 'Email domains that can access this folder (required for create)', { items: { type: 'string' } }),
+                allowed_domains: prop('array', 'Email domains that can access this folder', { items: { type: 'string' } }),
+                allowed_emails: prop('array', 'Individual email addresses that can access this folder', { items: { type: 'string' } }),
                 report_slugs: prop('array', 'Report slugs to add to folder (for add_reports)', { items: { type: 'string' } }),
                 report_slug: prop('string', 'Report slug to remove (for remove_report)'),
             },
@@ -135,6 +137,95 @@ const toolDefinitions = [
         schema: manageFoldersSchema,
         handler: createManageFoldersTool(client),
     },
+    {
+        name: 'list_products',
+        description: 'List all 44pixels products in the knowledge repository (Cue, Deep, Pixi, Clara, Vivi, Wordcast, etc.) with their knowledge file inventory. Call this first to discover available products and which knowledge files are already populated.',
+        inputSchema: { type: 'object', properties: {} },
+        schema: listProductsSchema,
+        handler: createListProductsTool(client),
+    },
+    {
+        name: 'get_product',
+        description: 'Get a product\'s complete knowledge — returns ALL JSON knowledge files (product.json, brand.json, copy.json, meta-ads.json, cpps.json) fully parsed, plus a listing of binary assets. This is the primary tool to read before generating creative work, writing ad copy, or configuring campaigns — it gives you brand voice, product positioning, hooks, and ad account IDs in one call.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                slug: prop('string', 'Product slug'),
+            },
+            required: ['slug'],
+        },
+        schema: getProductSchema,
+        handler: createGetProductTool(client),
+    },
+    {
+        name: 'read_product_file',
+        description: 'Read a single file from a product by path. Use get_product to read all knowledge files at once (more efficient). Use read_product_file only when you need one specific file — especially useful for binary files (logos, PDFs) returned as base64 data URIs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                slug: prop('string', 'Product slug'),
+                filepath: prop('string', 'File path within the product (e.g., "meta-ads.json", "brand-assets/logo.png")'),
+            },
+            required: ['slug', 'filepath'],
+        },
+        schema: readProductFileSchema,
+        handler: createReadProductFileTool(client),
+    },
+    {
+        name: 'update_product_knowledge',
+        description: 'Write or update product knowledge using deep merge-patch — only the keys you send are changed, all other data is preserved. This is the canonical way to store brand knowledge: ALWAYS use this (not deploy_context) for product profiles, brand guidelines, copy, ad accounts, and CPP config.\n\nKnowledge files per product:\n- product.json — core info, target audience, pain points, selling points, competitors\n- brand.json — colors, typography, voice/tone, brand archetypes, power words\n- copy.json — taglines, hooks, CTAs, approved/banned claims\n- meta-ads.json — Meta account IDs, pixels, creative test config\n- cpps.json — CPP motivations and custom product page config\n\nAlways pass updated_by with your agent name so humans can see who wrote each update.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                slug: prop('string', 'Product slug'),
+                filepath: prop('string', 'Knowledge file to update (e.g., "meta-ads.json", "brand.json", "product.json", "copy.json", "cpps.json")'),
+                content: prop('object', 'JSON object to deep merge-patch into the knowledge file. Use null values to delete keys.'),
+                updated_by: prop('string', 'Agent name or ID writing the update (optional)'),
+            },
+            required: ['slug', 'filepath', 'content'],
+        },
+        schema: updateProductKnowledgeSchema,
+        handler: createUpdateProductKnowledgeTool(client),
+    },
+    {
+        name: 'upload_product_files',
+        description: 'Upload binary assets to a product — logos, brand books, App Store screenshots, ad creatives, videos. Files are organized into sections:\n- brand-assets/ — logos, brand book PDFs, color swatches\n- store-listings/ — App Store / Play Store screenshots and preview videos\n- assets/ — ad creatives, icons, campaign videos',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                slug: prop('string', 'Product slug'),
+                files: prop('array', 'Files to upload', {
+                    items: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'File path within the product (e.g., "brand-assets/logo.png")' },
+                            content: { type: 'string', description: 'File content as text, base64 data URI, or local file path' },
+                            content_type: { type: 'string', description: 'MIME type (auto-detected if not provided)' },
+                        },
+                        required: ['path', 'content'],
+                    },
+                }),
+            },
+            required: ['slug', 'files'],
+        },
+        schema: uploadProductFilesSchema,
+        handler: createUploadProductFilesTool(client),
+    },
+    {
+        name: 'pull_product_files',
+        description: 'Download binary files from a product to a local directory.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                slug: prop('string', 'Product slug'),
+                output_dir: prop('string', 'Local directory to write files to. Will be created if needed.'),
+                files: prop('array', 'Specific file paths to pull. If omitted, all binary files are pulled.', { items: { type: 'string' } }),
+            },
+            required: ['slug', 'output_dir'],
+        },
+        schema: pullProductFilesSchema,
+        handler: createPullProductFilesTool(client),
+    },
 ];
 const toolHandlers = Object.fromEntries(toolDefinitions.map((t) => [t.name, { schema: t.schema, handler: t.handler }]));
 const server = new Server({ name: '44reports', version: '1.0.0' }, { capabilities: { tools: {} } });

package/dist/tools/folders.d.ts

@@ -6,6 +6,7 @@ export declare const manageFoldersSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     allowed_domains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    allowed_emails: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     report_slugs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     report_slug: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
@@ -14,6 +15,7 @@ export declare const manageFoldersSchema: z.ZodObject<{
     slug?: string | undefined;
     description?: string | undefined;
     allowed_domains?: string[] | undefined;
+    allowed_emails?: string[] | undefined;
     report_slugs?: string[] | undefined;
     report_slug?: string | undefined;
 }, {
@@ -22,6 +24,7 @@ export declare const manageFoldersSchema: z.ZodObject<{
     slug?: string | undefined;
     description?: string | undefined;
     allowed_domains?: string[] | undefined;
+    allowed_emails?: string[] | undefined;
     report_slugs?: string[] | undefined;
     report_slug?: string | undefined;
 }>;

package/dist/tools/folders.js

@@ -5,7 +5,8 @@ export const manageFoldersSchema = z.object({
     slug: z.string().optional().describe('Folder slug (required for get, update, delete, add_reports, remove_report)'),
     name: z.string().optional().describe('Folder name (required for create)'),
     description: z.string().optional().describe('Folder description'),
-    allowed_domains: z.array(z.string()).optional().describe('Email domains that can access this folder (required for create)'),
+    allowed_domains: z.array(z.string()).optional().describe('Email domains that can access this folder'),
+    allowed_emails: z.array(z.string()).optional().describe('Individual email addresses that can access this folder'),
     report_slugs: z.array(z.string()).optional().describe('Report slugs to add (for add_reports action)'),
     report_slug: z.string().optional().describe('Report slug to remove (for remove_report action)'),
 });
@@ -19,14 +20,17 @@ export function createManageFoldersTool(client) {
             case 'create': {
                 if (!input.name)
                     throw new Error('name is required for create');
-                if (!input.allowed_domains || input.allowed_domains.length === 0) {
-                    throw new Error('allowed_domains is required for create');
+                const domains = input.allowed_domains ?? [];
+                const emails = input.allowed_emails ?? [];
+                if (domains.length === 0 && emails.length === 0) {
+                    throw new Error('at least one of allowed_domains or allowed_emails is required for create');
                 }
                 return client.createFolder({
                     name: input.name,
                     slug: input.slug,
                     description: input.description,
-                    allowed_domains: input.allowed_domains,
+                    allowed_domains: domains.length > 0 ? domains : undefined,
+                    allowed_emails: emails.length > 0 ? emails : undefined,
                 });
             }
             case 'get': {
@@ -41,6 +45,7 @@ export function createManageFoldersTool(client) {
                     name: input.name,
                     description: input.description,
                     allowed_domains: input.allowed_domains,
+                    allowed_emails: input.allowed_emails,
                 });
             }
             case 'delete': {

package/dist/tools/products.d.ts

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+import type { ApiClient } from '../api-client.js';
+export declare const listProductsSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const getProductSchema: z.ZodObject<{
+    slug: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    slug: string;
+}, {
+    slug: string;
+}>;
+export declare const readProductFileSchema: z.ZodObject<{
+    slug: z.ZodString;
+    filepath: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    slug: string;
+    filepath: string;
+}, {
+    slug: string;
+    filepath: string;
+}>;
+export declare const updateProductKnowledgeSchema: z.ZodObject<{
+    slug: z.ZodString;
+    filepath: z.ZodString;
+    content: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    updated_by: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    slug: string;
+    content: Record<string, unknown>;
+    filepath: string;
+    updated_by?: string | undefined;
+}, {
+    slug: string;
+    content: Record<string, unknown>;
+    filepath: string;
+    updated_by?: string | undefined;
+}>;
+export declare const uploadProductFilesSchema: z.ZodObject<{
+    slug: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        content: z.ZodString;
+        content_type: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        content: string;
+        content_type?: string | undefined;
+    }, {
+        path: string;
+        content: string;
+        content_type?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    slug: string;
+    files: {
+        path: string;
+        content: string;
+        content_type?: string | undefined;
+    }[];
+}, {
+    slug: string;
+    files: {
+        path: string;
+        content: string;
+        content_type?: string | undefined;
+    }[];
+}>;
+export declare const pullProductFilesSchema: z.ZodObject<{
+    slug: z.ZodString;
+    output_dir: z.ZodString;
+    files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    slug: string;
+    output_dir: string;
+    files?: string[] | undefined;
+}, {
+    slug: string;
+    output_dir: string;
+    files?: string[] | undefined;
+}>;
+export declare function createListProductsTool(client: ApiClient): (_input: z.infer<typeof listProductsSchema>) => Promise<{
+    products: Array<{
+        id: string;
+        slug: string;
+        name: string;
+        description: string | null;
+        json_file_count: number;
+        binary_file_count: number;
+    }>;
+}>;
+export declare function createGetProductTool(client: ApiClient): (input: z.infer<typeof getProductSchema>) => Promise<{
+    product: {
+        id: string;
+        slug: string;
+        name: string;
+        description: string | null;
+        created_at: string;
+        updated_at: string;
+    };
+    knowledge: Record<string, unknown>;
+    binary_files: Array<{
+        path: string;
+        size: number;
+        content_type: string;
+    }>;
+}>;
+export declare function createReadProductFileTool(client: ApiClient): (input: z.infer<typeof readProductFileSchema>) => Promise<{
+    path: string;
+    content: unknown;
+    content_type: string;
+    size?: number;
+}>;
+export declare function createUpdateProductKnowledgeTool(client: ApiClient): (input: z.infer<typeof updateProductKnowledgeSchema>) => Promise<{
+    success: boolean;
+    path: string;
+    merged?: unknown;
+}>;
+export declare function createUploadProductFilesTool(client: ApiClient): (input: z.infer<typeof uploadProductFilesSchema>) => Promise<{
+    success: boolean;
+    uploaded: string[];
+}>;
+export declare function createPullProductFilesTool(client: ApiClient): (input: z.infer<typeof pullProductFilesSchema>) => Promise<{
+    product: {
+        name: string;
+        slug: string;
+    };
+    files_pulled: number;
+    output_dir: string;
+    files: {
+        path: string;
+        size: number;
+    }[];
+}>;

package/dist/tools/products.js

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+// --- Schemas ---
+export const listProductsSchema = z.object({});
+export const getProductSchema = z.object({
+    slug: z.string().describe('Product slug'),
+});
+export const readProductFileSchema = z.object({
+    slug: z.string().describe('Product slug'),
+    filepath: z.string().describe('File path within the product (e.g., "meta-ads.json", "brand-assets/logo.png")'),
+});
+export const updateProductKnowledgeSchema = z.object({
+    slug: z.string().describe('Product slug'),
+    filepath: z.string().describe('Knowledge file to update (e.g., "meta-ads.json", "brand.json", "product.json", "copy.json", "cpps.json")'),
+    content: z.record(z.unknown()).describe('JSON object to deep merge-patch into the knowledge file. Use null values to delete keys.'),
+    updated_by: z.string().optional().describe('Agent name or ID writing the update'),
+});
+export const uploadProductFilesSchema = z.object({
+    slug: z.string().describe('Product slug'),
+    files: z.array(z.object({
+        path: z.string().describe('File path within the product (e.g., "brand-assets/logo.png")'),
+        content: z.string().describe('File content as text or base64 data URI (e.g., "data:image/png;base64,...")'),
+        content_type: z.string().optional().describe('MIME type (auto-detected if not provided)'),
+    })).describe('Files to upload'),
+});
+export const pullProductFilesSchema = z.object({
+    slug: z.string().describe('Product slug'),
+    output_dir: z.string().describe('Local directory to write files to. Will be created if needed.'),
+    files: z.array(z.string()).optional().describe('Specific file paths to pull. If omitted, all binary files are pulled.'),
+});
+// --- Tool factories ---
+export function createListProductsTool(client) {
+    return async (_input) => {
+        const result = await client.listProducts();
+        return result;
+    };
+}
+export function createGetProductTool(client) {
+    return async (input) => {
+        const result = await client.getProduct(input.slug);
+        return result;
+    };
+}
+export function createReadProductFileTool(client) {
+    return async (input) => {
+        const result = await client.getProductFile(input.slug, input.filepath);
+        return result;
+    };
+}
+export function createUpdateProductKnowledgeTool(client) {
+    return async (input) => {
+        const result = await client.updateProductFile(input.slug, input.filepath, {
+            content: input.content,
+            updated_by: input.updated_by,
+        });
+        return result;
+    };
+}
+export function createUploadProductFilesTool(client) {
+    return async (input) => {
+        const processedFiles = await Promise.all(input.files.map(async (file) => {
+            let content = file.content;
+            if (content.startsWith('/') || content.startsWith('./') || content.startsWith('../')) {
+                const filePath = path.resolve(content);
+                const buffer = await fs.readFile(filePath);
+                const ext = path.extname(filePath).slice(1).toLowerCase();
+                const mimeTypes = {
+                    png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg',
+                    gif: 'image/gif', webp: 'image/webp', pdf: 'application/pdf',
+                    mp4: 'video/mp4', mov: 'video/quicktime', svg: 'image/svg+xml',
+                };
+                const mimeType = file.content_type || mimeTypes[ext] || 'application/octet-stream';
+                const base64 = buffer.toString('base64');
+                content = `data:${mimeType};base64,${base64}`;
+            }
+            return { ...file, content };
+        }));
+        const result = await client.uploadProductFiles(input.slug, processedFiles);
+        return result;
+    };
+}
+export function createPullProductFilesTool(client) {
+    return async (input) => {
+        const { product, binary_files } = await client.getProduct(input.slug);
+        let filesToPull = binary_files.map((f) => f.path);
+        if (input.files && input.files.length > 0) {
+            filesToPull = input.files;
+        }
+        if (filesToPull.length === 0) {
+            return { product: { name: product.name, slug: product.slug }, files_pulled: 0, output_dir: input.output_dir, files: [] };
+        }
+        const outputDir = path.resolve(input.output_dir);
+        await fs.mkdir(outputDir, { recursive: true });
+        const written = [];
+        const resolvedOutputDir = path.resolve(outputDir);
+        for (const filePath of filesToPull) {
+            const result = await client.getProductFile(input.slug, filePath);
+            const destPath = path.join(outputDir, filePath);
+            const resolvedDestPath = path.resolve(destPath);
+            if (!resolvedDestPath.startsWith(resolvedOutputDir + path.sep) && resolvedDestPath !== resolvedOutputDir) {
+                throw new Error(`Unsafe file path rejected: ${filePath}`);
+            }
+            await fs.mkdir(path.dirname(destPath), { recursive: true });
+            const content = result.content;
+            if (content.startsWith('data:')) {
+                const commaIndex = content.indexOf(',');
+                const base64Data = content.slice(commaIndex + 1);
+                await fs.writeFile(destPath, Buffer.from(base64Data, 'base64'));
+                written.push({ path: filePath, size: result.size || 0 });
+            }
+            else {
+                await fs.writeFile(destPath, content, 'utf-8');
+                written.push({ path: filePath, size: content.length });
+            }
+        }
+        return {
+            product: { name: product.name, slug: product.slug },
+            files_pulled: written.length,
+            output_dir: outputDir,
+            files: written,
+        };
+    };
+}

package/package.json

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