mulmocast-vision 1.0.5 → 1.0.7

package/README.md

@@ -72,9 +72,62 @@ You can instruct these actions via prompts.
 - SWOT, PEST, and 3C Analysis
 - Summary, Agenda, and Closing Slides
 
+## Logging
+
+mulmocast-vision automatically logs all operations and errors to help with debugging and monitoring.
+
+### Log Location
+
+Logs are saved in `/tmp/mulmocast-vision-mcp/` with daily rotation:
+- Format: `mcp_yyyymmdd.log` (e.g., `mcp_20251206.log`)
+- Each day creates a new log file
+
+### What is Logged
+
+- **MCP Server Operations**: Server initialization, tool calls, and results
+- **File Operations**: Template reads, HTML/PNG generation, PDF creation
+- **Errors**: Detailed error messages with full stack traces
+- **Debug Information**: Template rendering, directory operations, and more
+
+### Log Format
+
+Logs are written in JSON Lines format for easy parsing:
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:45.123Z",
+  "level": "ERROR",
+  "message": "Template file not found",
+  "data": {
+    "errorMessage": "getHtml: file /path/to/template.html not exists.",
+    "errorName": "Error",
+    "stack": "Error: getHtml: file...\n    at htmlPlugin.getHtml...",
+    "templateFilePath": "/path/to/template.html",
+    "functionName": "createAgendaSlide"
+  }
+}
+```
+
+### Custom Logger
+
+You can replace the default logger with your own implementation (e.g., for telemetry):
+
+```typescript
+import { setLogger, LoggerInterface } from 'mulmocast-vision/logger';
+
+class CustomLogger implements LoggerInterface {
+  info(message: string, data?: unknown) {
+    // Your implementation
+  }
+  // ... other methods
+}
+
+setLogger(new CustomLogger());
+```
+
 ## For Developers
 
-MulmoCast Vision is open source, so you can apply various designs by modifying the HTML.  
+MulmoCast Vision is open source, so you can apply various designs by modifying the HTML.
 For adding styles, please refer to [Style.ja.md](https://github.com/receptron/mulmocast-vision/blob/main/Style.ja.md).
 
 ### Official Repository & Package
@@ -139,3 +192,58 @@ MCP対応ツール（例: Claude Desktop）の設定ファイルに以下を追
 - SWOT分析、PEST分析、3C分析
 - サマリースライド、アジェンダスライド、クロージングスライド
 
+---
+
+## ログ機能
+
+mulmocast-visionは、デバッグや監視を支援するため、すべての操作とエラーを自動的にログに記録します。
+
+### ログの保存場所
+
+ログは `/tmp/mulmocast-vision-mcp/` に日次ローテーションで保存されます：
+- 形式: `mcp_yyyymmdd.log` (例: `mcp_20251206.log`)
+- 日付が変わると新しいログファイルが作成されます
+
+### 記録される内容
+
+- **MCPサーバー操作**: サーバーの初期化、ツール呼び出し、実行結果
+- **ファイル操作**: テンプレート読み込み、HTML/PNG生成、PDF作成
+- **エラー**: 詳細なエラーメッセージとスタックトレース
+- **デバッグ情報**: テンプレートレンダリング、ディレクトリ操作など
+
+### ログフォーマット
+
+ログはJSON Lines形式で記録され、解析が容易です：
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:45.123Z",
+  "level": "ERROR",
+  "message": "Template file not found",
+  "data": {
+    "errorMessage": "getHtml: file /path/to/template.html not exists.",
+    "errorName": "Error",
+    "stack": "Error: getHtml: file...\n    at htmlPlugin.getHtml...",
+    "templateFilePath": "/path/to/template.html",
+    "functionName": "createAgendaSlide"
+  }
+}
+```
+
+### カスタムロガー
+
+デフォルトのロガーを独自の実装（テレメトリーなど）に置き換えることができます：
+
+```typescript
+import { setLogger, LoggerInterface } from 'mulmocast-vision/logger';
+
+class CustomLogger implements LoggerInterface {
+  info(message: string, data?: unknown) {
+    // 独自の実装
+  }
+  // ... その他のメソッド
+}
+
+setLogger(new CustomLogger());
+```
+

package/lib/html_class.d.ts

@@ -1,3 +1,4 @@
+import nunjucks from "nunjucks";
 import { type PluginOptionParams, type ToolArgs, type CreatePageOptions } from "./type";
 export declare class htmlPlugin {
     protected outputDir: string;
@@ -6,6 +7,7 @@ export declare class htmlPlugin {
     protected templateDir: string;
     protected sessionDir: string;
     protected templateOptions: CreatePageOptions;
+    protected nunjucksEnv: nunjucks.Environment;
     constructor({ outputDir, rootDir, templateOptions, htmlDir, // relative path
     templateDir, }: {
         outputDir?: string;

package/lib/html_class.js

@@ -10,6 +10,7 @@ const pdfkit_1 = __importDefault(require("pdfkit"));
 const utils_1 = require("./utils");
 const commons_1 = require("./commons");
 const nunjucks_1 = __importDefault(require("nunjucks"));
+const logger_1 = require("./logger");
 class htmlPlugin {
     constructor({ outputDir, rootDir, templateOptions, 
     // for html template. If templateDir exists, it takes precedence over htmlDir.
@@ -18,6 +19,8 @@ class htmlPlugin {
      }) {
         // api for mcp
         this.callNamedFunction = async (functionName, args, options) => {
+            const logger = (0, logger_1.getLogger)();
+            logger.debug(`callNamedFunction: ${functionName}`, { args, options });
             const member = this[functionName];
             if (member && typeof member === "function") {
                 return member(args, { ...options, functionName });
@@ -25,79 +28,138 @@ class htmlPlugin {
             return this.generateHtml(args, { ...options, functionName });
         };
         this.generateHtml = async (args, options) => {
+            const logger = (0, logger_1.getLogger)();
             const { outputFileName, functionName, imageFilePath, htmlFilePath } = options ?? {};
             if (!functionName) {
                 throw new Error("functionName is required");
             }
-            const html = this.getHtml(functionName, args);
-            const outfile = imageFilePath ?? path_1.default.resolve(this.outputDir, this.sessionDir, `${outputFileName}.png`);
-            const htmlFile = htmlFilePath ?? path_1.default.resolve(this.outputDir, this.sessionDir, `${outputFileName}.html`);
-            await (0, utils_1.createPage)(this.rootDir, outfile, html, { htmlFile, ...this.templateOptions });
-            return {
-                text: `html generated successfully to: ${outfile}`,
-            };
+            logger.info("Generating HTML", { functionName, outputFileName });
+            try {
+                const html = this.getHtml(functionName, args);
+                const outfile = imageFilePath ?? path_1.default.resolve(this.outputDir, this.sessionDir, `${outputFileName}.png`);
+                const htmlFile = htmlFilePath ?? path_1.default.resolve(this.outputDir, this.sessionDir, `${outputFileName}.html`);
+                await (0, utils_1.createPage)(this.rootDir, outfile, html, { htmlFile, ...this.templateOptions });
+                logger.fileWrite(outfile);
+                logger.fileWrite(htmlFile);
+                logger.info("HTML generated successfully", { outfile, htmlFile });
+                return {
+                    text: `html generated successfully to: ${outfile}`,
+                };
+            }
+            catch (error) {
+                logger.error("Failed to generate HTML", error, {
+                    functionName,
+                    outputFileName,
+                    args,
+                    outputDir: this.outputDir,
+                    sessionDir: this.sessionDir,
+                });
+                throw error;
+            }
         };
         // for electron
         this.getHtml = (functionName, args) => {
+            const logger = (0, logger_1.getLogger)();
             const templateFileName = (0, commons_1.functionNameToTemplateName)(functionName);
             const templateFilePath = path_1.default.resolve(this.templateDir ? this.templateDir : path_1.default.resolve(this.rootDir, "html", this.htmlDir), `${templateFileName}.html`);
             if (!fs_1.default.existsSync(templateFilePath)) {
-                throw new Error(`getHtml: file ${templateFilePath} not exists.`);
+                const error = new Error(`getHtml: file ${templateFilePath} not exists.`);
+                logger.error("Template file not found", error, {
+                    templateFilePath,
+                    functionName,
+                    templateFileName,
+                    templateDir: this.templateDir,
+                    htmlDir: this.htmlDir,
+                    rootDir: this.rootDir,
+                });
+                throw error;
+            }
+            logger.fileRead(templateFilePath);
+            logger.debug("Rendering template", { templateFileName, args });
+            try {
+                // Use the configured Nunjucks environment instead of the default
+                // This ensures the FileSystemLoader can find the template
+                return this.nunjucksEnv.render(`${templateFileName}.html`, args);
+            }
+            catch (error) {
+                logger.error("Template rendering failed", error, { templateFilePath, templateFileName, args });
+                throw error;
             }
-            return nunjucks_1.default.render(templateFilePath, args);
         };
         // for mcp
         this.setDirectory = async (args, __options) => {
+            const logger = (0, logger_1.getLogger)();
             this.sessionDir = args.directoryName;
             const outputDir = path_1.default.resolve(this.outputDir, this.sessionDir);
-            // console.error(outputDir);
+            logger.info("Setting directory", { sessionDir: this.sessionDir, outputDir });
             (0, utils_1.mkdir)(outputDir);
             return {
                 text: `set directory: ${this.sessionDir}`,
             };
         };
         this.createPDF = async (args, __options) => {
+            const logger = (0, logger_1.getLogger)();
             const { filename, images } = args ?? {};
-            const imageWidth = 1536;
-            const imageHeight = 1024;
-            const pageWidth = imageWidth * 0.75; // 1152pt
-            const pageHeight = imageHeight * 0.75; // 768pt
-            const outputDir = path_1.default.resolve(this.outputDir, this.sessionDir);
-            const files = images ??
-                fs_1.default
-                    .readdirSync(outputDir)
-                    .filter((f) => f.toLowerCase().endsWith(".png"))
-                    .sort(new Intl.Collator("ja", { numeric: true }).compare);
-            if (files.length === 0) {
-                console.error("no PNG file");
-                return;
-            }
-            const doc = new pdfkit_1.default({
-                size: [pageWidth, pageHeight],
-                margins: {
-                    top: 0,
-                    bottom: 0,
-                    left: 0,
-                    right: 0,
-                },
-            });
-            doc.pipe(fs_1.default.createWriteStream(path_1.default.resolve(outputDir, filename)));
-            files.forEach((f, i) => {
-                if (i > 0) {
-                    doc.addPage({
-                        size: [pageWidth, pageHeight],
-                        margins: { top: 0, bottom: 0, left: 0, right: 0 },
-                    });
+            logger.info("Creating PDF", { filename, imagesCount: images?.length });
+            try {
+                const imageWidth = 1536;
+                const imageHeight = 1024;
+                const pageWidth = imageWidth * 0.75; // 1152pt
+                const pageHeight = imageHeight * 0.75; // 768pt
+                const outputDir = path_1.default.resolve(this.outputDir, this.sessionDir);
+                const files = images ??
+                    fs_1.default
+                        .readdirSync(outputDir)
+                        .filter((f) => f.toLowerCase().endsWith(".png"))
+                        .sort(new Intl.Collator("ja", { numeric: true }).compare);
+                if (files.length === 0) {
+                    const error = new Error("No PNG files found");
+                    logger.error("No PNG files found", error, { outputDir });
+                    console.error("no PNG file");
+                    return;
                 }
-                doc.image(path_1.default.join(outputDir, f), 0, 0, {
-                    width: pageWidth,
-                    height: pageHeight,
+                logger.debug("PNG files found", { count: files.length, files });
+                const doc = new pdfkit_1.default({
+                    size: [pageWidth, pageHeight],
+                    margins: {
+                        top: 0,
+                        bottom: 0,
+                        left: 0,
+                        right: 0,
+                    },
                 });
-            });
-            doc.end();
-            return {
-                text: `pdf created: ${outputDir}`,
-            };
+                const pdfPath = path_1.default.resolve(outputDir, filename);
+                doc.pipe(fs_1.default.createWriteStream(pdfPath));
+                files.forEach((f, i) => {
+                    const imagePath = path_1.default.join(outputDir, f);
+                    logger.fileRead(imagePath);
+                    if (i > 0) {
+                        doc.addPage({
+                            size: [pageWidth, pageHeight],
+                            margins: { top: 0, bottom: 0, left: 0, right: 0 },
+                        });
+                    }
+                    doc.image(imagePath, 0, 0, {
+                        width: pageWidth,
+                        height: pageHeight,
+                    });
+                });
+                doc.end();
+                logger.fileWrite(pdfPath);
+                logger.info("PDF created successfully", { pdfPath, pageCount: files.length });
+                return {
+                    text: `pdf created: ${outputDir}`,
+                };
+            }
+            catch (error) {
+                logger.error("Failed to create PDF", error, {
+                    filename,
+                    images,
+                    outputDir: this.outputDir,
+                    sessionDir: this.sessionDir,
+                });
+                throw error;
+            }
         };
         this.dumpMulmoScript = () => { };
         this.outputDir = outputDir ?? (0, utils_1.getOutDir)();
@@ -106,6 +168,15 @@ class htmlPlugin {
         this.htmlDir = htmlDir ?? "html2";
         this.templateDir = templateDir ?? "";
         this.templateOptions = templateOptions ?? {};
+        // Configure Nunjucks environment with FileSystemLoader
+        const templatePath = this.templateDir ? this.templateDir : path_1.default.resolve(this.rootDir, "html", this.htmlDir);
+        const loader = new nunjucks_1.default.FileSystemLoader(templatePath, {
+            noCache: true, // Disable cache to ensure fresh templates
+        });
+        this.nunjucksEnv = new nunjucks_1.default.Environment(loader, {
+            autoescape: false, // Don't escape HTML
+            throwOnUndefined: false, // Don't throw on undefined variables
+        });
     }
 }
 exports.htmlPlugin = htmlPlugin;

package/lib/logger.d.ts

@@ -0,0 +1,49 @@
+type LogLevel = "INFO" | "ERROR" | "WARN" | "DEBUG";
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    data?: unknown;
+}
+export interface LoggerInterface {
+    info(message: string, data?: unknown): void;
+    error(message: string, error?: Error | unknown, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+    fileRead(filePath: string): void;
+    fileWrite(filePath: string, size?: number): void;
+    fileDelete(filePath: string): void;
+    toolCall(toolName: string, args: unknown): void;
+    toolResult(toolName: string, success: boolean, result?: unknown): void;
+}
+declare class FileLogger implements LoggerInterface {
+    private logDir;
+    private logFile;
+    constructor(logDir?: string);
+    private formatTimestamp;
+    private writeLog;
+    info(message: string, data?: unknown): void;
+    error(message: string, error?: Error | unknown, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+    fileRead(filePath: string): void;
+    fileWrite(filePath: string, size?: number): void;
+    fileDelete(filePath: string): void;
+    toolCall(toolName: string, args: unknown): void;
+    toolResult(toolName: string, success: boolean, result?: unknown): void;
+}
+declare class NoOpLogger implements LoggerInterface {
+    info(__message: string, __data?: unknown): void;
+    error(__message: string, __error?: Error | unknown, __data?: unknown): void;
+    warn(__message: string, __data?: unknown): void;
+    debug(__message: string, __data?: unknown): void;
+    fileRead(__filePath: string): void;
+    fileWrite(__filePath: string, __size?: number): void;
+    fileDelete(__filePath: string): void;
+    toolCall(__toolName: string, __args: unknown): void;
+    toolResult(__toolName: string, __success: boolean, __result?: unknown): void;
+}
+export declare const setLogger: (logger: LoggerInterface) => void;
+export declare const getLogger: () => LoggerInterface;
+export declare const logger: LoggerInterface;
+export { FileLogger, NoOpLogger };

package/lib/logger.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoOpLogger = exports.FileLogger = exports.logger = exports.getLogger = exports.setLogger = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+// Default file-based logger implementation
+class FileLogger {
+    constructor(logDir) {
+        this.logDir = logDir ?? path_1.default.join(os_1.default.tmpdir(), "mulmocast-vision-mcp");
+        // Generate date suffix (yyyymmdd)
+        const now = new Date();
+        const year = now.getFullYear();
+        const month = String(now.getMonth() + 1).padStart(2, "0");
+        const day = String(now.getDate()).padStart(2, "0");
+        const dateSuffix = `${year}${month}${day}`;
+        this.logFile = path_1.default.join(this.logDir, `mcp_${dateSuffix}.log`);
+        // Ensure log directory exists
+        if (!fs_1.default.existsSync(this.logDir)) {
+            fs_1.default.mkdirSync(this.logDir, { recursive: true });
+        }
+    }
+    formatTimestamp() {
+        return new Date().toISOString();
+    }
+    writeLog(level, message, data) {
+        const timestamp = this.formatTimestamp();
+        const logEntry = {
+            timestamp,
+            level,
+            message,
+        };
+        if (data !== undefined) {
+            logEntry.data = data;
+        }
+        const logLine = JSON.stringify(logEntry) + "\n";
+        try {
+            fs_1.default.appendFileSync(this.logFile, logLine);
+        }
+        catch (error) {
+            // Fallback to console.error if file write fails
+            console.error("Failed to write to log file:", error);
+            console.error(logLine);
+        }
+    }
+    info(message, data) {
+        this.writeLog("INFO", message, data);
+    }
+    error(message, error, data) {
+        const errorData = {};
+        if (error instanceof Error) {
+            errorData.errorMessage = error.message;
+            errorData.errorName = error.name;
+            errorData.stack = error.stack;
+            // Include any custom properties on the error
+            const errorObj = error;
+            Object.keys(error).forEach((key) => {
+                if (key !== "message" && key !== "name" && key !== "stack") {
+                    errorData[key] = errorObj[key];
+                }
+            });
+        }
+        else if (error !== undefined) {
+            errorData.error = error;
+        }
+        const combinedData = data ? { ...errorData, ...data } : errorData;
+        this.writeLog("ERROR", message, Object.keys(combinedData).length > 0 ? combinedData : undefined);
+    }
+    warn(message, data) {
+        this.writeLog("WARN", message, data);
+    }
+    debug(message, data) {
+        this.writeLog("DEBUG", message, data);
+    }
+    fileRead(filePath) {
+        this.info("File read", { operation: "read", filePath });
+    }
+    fileWrite(filePath, size) {
+        this.info("File write", { operation: "write", filePath, size });
+    }
+    fileDelete(filePath) {
+        this.info("File delete", { operation: "delete", filePath });
+    }
+    toolCall(toolName, args) {
+        this.info("Tool called", { toolName, args });
+    }
+    toolResult(toolName, success, result) {
+        this.info("Tool result", { toolName, success, result });
+    }
+}
+exports.FileLogger = FileLogger;
+// No-op logger for disabling logging
+class NoOpLogger {
+    info(__message, __data) { }
+    error(__message, __error, __data) { }
+    warn(__message, __data) { }
+    debug(__message, __data) { }
+    fileRead(__filePath) { }
+    fileWrite(__filePath, __size) { }
+    fileDelete(__filePath) { }
+    toolCall(__toolName, __args) { }
+    toolResult(__toolName, __success, __result) { }
+}
+exports.NoOpLogger = NoOpLogger;
+// Logger manager
+class LoggerManager {
+    constructor() {
+        this.logger = new FileLogger();
+    }
+    setLogger(logger) {
+        this.logger = logger;
+    }
+    getLogger() {
+        return this.logger;
+    }
+}
+// Export singleton instance
+const loggerManager = new LoggerManager();
+const setLogger = (logger) => {
+    loggerManager.setLogger(logger);
+};
+exports.setLogger = setLogger;
+const getLogger = () => {
+    return loggerManager.getLogger();
+};
+exports.getLogger = getLogger;
+// Proxy object that delegates to current logger
+// This ensures that the exported logger updates when setLogger() is called
+exports.logger = {
+    info: (message, data) => loggerManager.getLogger().info(message, data),
+    error: (message, error, data) => loggerManager.getLogger().error(message, error, data),
+    warn: (message, data) => loggerManager.getLogger().warn(message, data),
+    debug: (message, data) => loggerManager.getLogger().debug(message, data),
+    fileRead: (filePath) => loggerManager.getLogger().fileRead(filePath),
+    fileWrite: (filePath, size) => loggerManager.getLogger().fileWrite(filePath, size),
+    fileDelete: (filePath) => loggerManager.getLogger().fileDelete(filePath),
+    toolCall: (toolName, args) => loggerManager.getLogger().toolCall(toolName, args),
+    toolResult: (toolName, success, result) => loggerManager.getLogger().toolResult(toolName, success, result),
+};

package/lib/mcp.js

@@ -9,7 +9,9 @@ const html_class_1 = require("./html_class");
 const commons_1 = require("./commons");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const utils_1 = require("./utils");
+const logger_1 = require("./logger");
 const getServer = (handler) => {
+    const logger = (0, logger_1.getLogger)();
     const server = new index_js_1.Server({
         name: "mulmocast-vision",
         version: "1.0.2",
@@ -18,18 +20,22 @@ const getServer = (handler) => {
             tools: {},
         },
     });
+    logger.info("MCP Server initialized", { name: "mulmocast-vision", version: "1.0.2" });
     // List available tools
     server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+        logger.debug("List tools requested");
         return (0, commons_1.openAIToolsToAnthropicTools)([...tools_1.tools, ...tools_1.mcp_tools]);
     });
     // Handle tool calls
     server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
+        logger.toolCall(name, args);
         console.error([...tools_1.tools, ...tools_1.mcp_tools]);
         try {
             if (args) {
                 const fileName = (0, commons_1.generateUniqueId)();
                 const result = await handler.callNamedFunction(name, args, { outputFileName: fileName });
+                logger.toolResult(name, true, result);
                 return {
                     content: [
                         {
@@ -43,6 +49,8 @@ const getServer = (handler) => {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.toolResult(name, false, { error: errorMessage });
+            logger.error(`Tool call failed: ${name}`, error, { toolName: name, args });
             return {
                 content: [
                     {
@@ -58,12 +66,22 @@ const getServer = (handler) => {
 };
 exports.getServer = getServer;
 const main = async () => {
-    const rootDir = (0, utils_1.getRootDir)();
-    const outputDir = (0, utils_1.getOutDir)();
-    const htmlDir = "html2";
-    const handler = new html_class_1.htmlPlugin({ outputDir, rootDir, htmlDir });
-    const server = (0, exports.getServer)(handler);
-    const transport = new stdio_js_1.StdioServerTransport();
-    await server.connect(transport);
+    const logger = (0, logger_1.getLogger)();
+    try {
+        logger.info("Starting MCP server");
+        const rootDir = (0, utils_1.getRootDir)();
+        const outputDir = (0, utils_1.getOutDir)();
+        const htmlDir = "html2";
+        logger.info("Configuration loaded", { rootDir, outputDir, htmlDir });
+        const handler = new html_class_1.htmlPlugin({ outputDir, rootDir, htmlDir });
+        const server = (0, exports.getServer)(handler);
+        const transport = new stdio_js_1.StdioServerTransport();
+        await server.connect(transport);
+        logger.info("MCP server connected and ready");
+    }
+    catch (error) {
+        logger.error("Failed to start MCP server", error);
+        throw error;
+    }
 };
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmocast-vision",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Easy and stylish presentation slide generator",
   "mcpName": "io.github.isamu/mulmocast-vision",
   "main": "lib/index.js",