Report Generator MCP Tool v1.3.0

A powerful CLI tool for generating HTML reports with embedded interactive charts, designed to work seamlessly with Claude Desktop as an MCP (Model Context Protocol) extension.

Features

• Generate professional HTML reports from Markdown documents
• Embed customizable interactive charts (bar, line, pie, doughnut, radar, polarArea) directly in reports
• Embed images from URLs or generated by pollinations.ai service
• Dual operation modes:
  • Command-line interface for direct usage
  • Stdio mode for Claude Desktop integration
• Full MCP compliance for seamless Claude Desktop integration
• TypeScript implementation with comprehensive type safety

Installation

Global Installation (Recommended)

npm install -g @vint.tri/report_gen_mcp@latest

Direct Execution with npx

REPORTS_DIR=./reports npx @vint.tri/report_gen_mcp@latest

Usage

Command Line Interface

The CLI mode now requires the REPORTS_DIR environment variable to be set to specify where reports should be generated.

Start Server Mode

REPORTS_DIR=./reports report_gen_mcp start-server

Starts an HTTP server for generating reports via REST API.

Generate Report Directly

REPORTS_DIR=./reports report_gen_mcp generate \
  --document "path/to/document.md" \
  --charts '{"chart1":{"type":"bar","config":{...}}}' \
  --output "report.html"

Generates a report directly from command line arguments.

Note: If you run the CLI commands without setting the REPORTS_DIR environment variable, you will get an error message with instructions on how to set it:

Error: REPORTS_DIR environment variable is required.
Please set the REPORTS_DIR environment variable to specify where reports should be generated.
Example:
  export REPORTS_DIR=/path/to/reports && npx @vint.tri/report_gen_mcp@latest
Or:
  REPORTS_DIR=/path/to/reports npx @vint.tri/report_gen_mcp@latest

Claude Desktop Integration

To use this tool with Claude Desktop, add the following configuration to your Claude Desktop settings:

{
  "report_gen_mcp": {
    "name": "report_gen_mcp",
    "type": "stdio",
    "isActive": true,
    "registryUrl": "",
    "longRunning": false,
    "tags": [],
    "command": "npx",
    "env": {
      "REPORTS_DIR": "./reports"
    },
    "args": [
      "@vint.tri/report_gen_mcp@latest"
    ]
  }
}

Once configured, Claude can generate reports by sending requests. Here's how to properly format your requests:

How to Provide Data for Reports

When calling the generate-report method, you need to provide three main pieces of data:

1. document: A Markdown string containing your report content with chart placeholders
2. charts: An object mapping chart IDs to their configurations
3. outputFile: (Optional) The name of the output HTML file

After Generating a Report

After successfully generating a report, it's important to provide the user with complete information about the generated file. To do this, you should use the get-report-url and get-report-file tools:

1. Provide File Path and URL: Use the get-report-url tool to get the file path and a clickable URL for the report
2. Attach the File Content: Use the get-report-file tool to retrieve and attach the actual file content

This ensures that users receive:

• The absolute file path to the generated report
• A clickable file:// URL to open the report directly in a browser

Document Format

Your document should be a Markdown string that can include chart placeholders in the format [[chart:chartId]]. For example:

# Sales Report

## Monthly Performance

[[chart:salesChart]]

As shown above, our sales have increased by 15% this month.

## Regional Comparison

[[chart:regionalChart]]

Different regions show varying performance levels.

Charts Configuration

The charts parameter is an object where each key is a chart ID that matches a placeholder in your document, and each value is a chart configuration object with:

• type: The chart type ("bar", "line", "pie", "doughnut", "radar", or "polarArea")
• config: The Chart.js configuration for that chart

Required Chart Data Structure

All charts must follow a specific data structure:

Method 1: Direct Method Call (Simple Format)

{
  "method": "generate-report",
  "params": {
    "document": "# Sales Report\n\nThis is our monthly sales report.\n\n[[chart:sales]]\n\n## Conclusion\n\nThis report shows our sales performance.",
    "charts": {
      "sales": {
        "type": "bar",
        "config": {
          "labels": ["January", "February", "March", "April", "May"],
          "datasets": [
            {
              "label": "Sales (USD)",
              "data": [12000, 19000, 15000, 18000, 22000],
              "backgroundColor": ["#FF6384", "#36A2EB", "#FFCE56", "#4BC0C0", "#9966FF"]
            }
          ],
          "options": {
            "title": "Monthly Sales Data"
          }
        }
      }
    },
    "outputFile": "sales-report.html"
  }
}

Method 2: MCP Standard Format (Advanced)

{
  "method": "tools/call",
  "params": {
    "name": "generate-report",
    "arguments": {
      "document": "# Performance Report\n\n[[chart:performance]]\n\nDetailed analysis below.",
      "charts": {
        "performance": {
          "type": "line",
          "config": {
            "labels": ["Q1", "Q2", "Q3", "Q4"],
            "datasets": [
              {
                "label": "Revenue",
                "data": [45000, 52000, 48000, 61000],
                "borderColor": "#36A2EB",
                "fill": false
              },
              {
                "label": "Expenses",
                "data": [30000, 32000, 31000, 35000],
                "borderColor": "#FF6384",
                "fill": false
              }
            ],
            "options": {
              "title": "Quarterly Performance",
              "scales": {
                "yAxes": [{
                  "ticks": {
                    "beginAtZero": true
                  }
                }]
              }
            }
          }
        }
      },
      "outputFile": "performance-report.html"
    }
  }
}

How to Insert Charts in Documents

Charts are inserted into your Markdown document using placeholders with the format [[chart:chartId]], where chartId corresponds to the key in your charts object.

Example:

# My Report

## Sales Overview

[[chart:salesChart]]

As we can see from the chart above, sales have been increasing steadily.

## Regional Performance

[[chart:regionalChart]]

Different regions show varying performance levels.

Health Check

To verify the tool is working correctly:

{
  "method": "health"
}

Expected response:

{
  "status": "ok"
}

List Available Tools

To see what tools are available:

{
  "method": "tools/list"
}

### Detailed Chart Configuration Requirements

Each chart type has specific configuration requirements that must be met. All chart configurations must include `labels` and `datasets` as arrays.

#### Bar Charts

Required structure:
```json
{
  "type": "bar",
  "config": {
    "labels": ["Label1", "Label2", "Label3"],
    "datasets": [
      {
        "label": "Dataset Name",
        "data": [10, 20, 30],
        "backgroundColor": ["red", "blue", "green"] // Optional
      }
    ],
    "options": {
      "title": "Chart Title" // Optional
    }
  }
}

Line Charts

Required structure:

{
  "type": "line",
  "config": {
    "labels": ["Label1", "Label2", "Label3"],
    "datasets": [
      {
        "label": "Dataset Name",
        "data": [10, 20, 30],
        "borderColor": "blue" // Optional
      }
    ],
    "options": {
      "title": "Chart Title" // Optional
    }
  }
}

Pie Charts

Required structure:

{
  "type": "pie",
  "config": {
    "labels": ["Label1", "Label2", "Label3"],
    "datasets": [
      {
        "data": [10, 20, 30],
        "backgroundColor": ["red", "blue", "green"] // Optional
      }
    ],
    "options": {
      "title": "Chart Title" // Optional
    }
  }
}

Important Notes:

1. labels must be an array of strings
2. datasets must be an array of objects
3. Each dataset must include the required fields for its chart type:
   • Bar charts: label and data (both required)
   • Line charts: label and data (both required)
   • Pie charts: data (required)
4. All numerical data must be provided as arrays of numbers
5. Color values (when provided) must be valid CSS color strings
6. IMPORTANT for Neural Networks: All color properties (backgroundColor, borderColor) must be provided as arrays of strings, even if there is only one color. This is a common source of errors.

For detailed examples of correct chart configurations for all supported chart types, please see CORRECT_CHART_EXAMPLES.md.

For special instructions for neural networks on how to properly interact with users after generating reports, please see NEURAL_NETWORK_INSTRUCTIONS.md.

Health Check

To verify the tool is working correctly:

{
  "method": "health"
}

Expected response:

{
  "status": "ok"
}

Development

Building the Project

npm run build

Running Tests

npm test

API Reference

Methods

1. generate-report: Creates an HTML report with embedded charts
2. get-report-url: Returns a clickable URL for a generated report file and shows all available formats
3. get-report-file: Returns the content of a generated report file
4. health: Checks if the tool is running correctly
5. mcp:list-tools: Returns available tools (used by Claude Desktop)

Method Details

generate-report

Parameters:

• document (string): Markdown document with chart placeholders [[chart:id]]
• charts (object): Chart configurations mapped by ID
  • type (string): Chart type ("bar", "line", "pie", "doughnut", "radar", or "polarArea")
  • config (object): Chart.js configuration object
• outputFile (string, optional): Output HTML file path (defaults to "report.html")
• tempDirectory (string, required for Claude Desktop): Temporary directory for file storage. This parameter is required when using the tool with Claude Desktop to prevent read-only file system errors.

Response:

{
  "success": true,
  "filePath": "/absolute/path/to/report.html",
  "message": "Report generated successfully"
}

get-report-url

Description: Get information about a generated report file including a clickable URL and file statistics

Parameters:

• filePath (string): Full path to the report file

Response:

{
  "success": true,
  "message": "Report file information retrieved successfully",
  "filePath": "/absolute/path/to/report.html",
  "relativePath": "report.html",
  "fileUrl": "file:///absolute/path/to/report.html",
  "fileStats": {
    "size": 12345,
    "created": "2023-01-01T00:00:00.000Z",
    "modified": "2023-01-01T00:00:00.000Z"
  }
}

Note: This method only returns metadata about the file, not the file content itself. Use get-report-file to retrieve the actual file content.

get-report-file

Description: Get the content of a generated report file

Parameters:

• filePath (string): Full path to the report file

Response:

{
  "success": true,
  "message": "Report file content retrieved successfully",
  "filePath": "/absolute/path/to/report.html"
}

The file content is returned as a resource attachment in the response with the following structure:

{
  "type": "resource",
  "resource": {
    "uri": "file:///absolute/path/to/report.html",
    "mimeType": "text/html",
    "text": "<!DOCTYPE html><html>...</html>"
  }
}

health

Response:

{
  "status": "ok"
}

Troubleshooting

Common Issues

1. Tool appears inactive in Claude Desktop: Ensure isActive is set to true in the configuration
2. mcp:list-tools -32001 error: Verify the tool is properly installed and the configuration is correct
3. Report generation fails: Check that chart configurations are valid and file paths are accessible
4. Read-only file system errors in Claude Desktop: When using the tool with Claude Desktop, the tempDirectory parameter is required. Always include "tempDirectory": "/tmp" (or another writable directory) in your generate-report requests to prevent read-only file system errors.

Verification

Run the included verification script to test all functionality:

node verify-claude-integration.js

Version History

• 1.0.9: Fixed Claude Desktop integration issues, improved error handling
• 1.0.8: Enhanced chart customization options
• 1.0.7: Initial public release with full feature set

License

MIT