Report Generator MCP Tool

A powerful CLI tool for generating HTML reports with embedded 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 charts (bar, line, pie) directly in reports
• 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@1.0.19

Direct Execution with npx

npx @vint.tri/report_gen_mcp@1.0.19

Usage

Command Line Interface

Start Server Mode

report_gen_mcp start-server

Starts an HTTP server for generating reports via REST API.

Generate Report Directly

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.

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",
    "args": [
      "@vint.tri/report_gen_mcp@1.0.19"
    ]
  }
}

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

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", or "pie")
• 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

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
3. health: Checks if the tool is running correctly
4. 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", or "pie")
  • config (object): Chart.js configuration object
• outputFile (string, optional): Output HTML file path (defaults to "report.html")
• tempDirectory (string, optional): Temporary directory for file storage (defaults to current working directory if not specified)

Response:

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

get-report-url

Description: Get a clickable URL for a generated report file

Parameters:

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

Response:

{
  "success": true,
  "fileUrl": "file:///absolute/path/to/report.html",
  "message": "Click the URL to open the report",
  "filePath": "/absolute/path/to/report.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

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