jasper-server-mcp by mr-wolf-gb - MCP Server

Jaspersoft Server MCP Integration

A Model Context Protocol (MCP) server that bridges AI-powered development environments with Jaspersoft Server 8.2 CE. Enable developers and analysts to generate, manage, and execute JasperReports using natural language and AI assistance, significantly reducing manual report development time.

🌟 Repository: https://github.com/mr-wolf-gb/jasper-server-mcp

🎯 Key Benefits

Reduce Report Development Time by 80%: Generate complex JRXML templates from natural language descriptions
AI-Enhanced Analytics: Intelligent summarization of report data into executive insights
Seamless IDE Integration: Works natively with Cursor, Kiro, and other MCP-compatible IDEs
Enterprise-Ready: Built for Jaspersoft Server 8.2 CE with production-grade reliability
Multi-Model AI Support: Cost-optimized AI through OpenRouter with fallback mechanisms

🚀 Features

🤖 AI-Driven JRXML Generation: Generate valid JasperReports templates from natural language descriptions using advanced AI models
📊 Multi-Source Data Integration: Connect to SQL databases, REST APIs, CSV files, and JSON data sources
🧠 OpenRouter AI Integration: Support for multiple AI models (Claude, GPT-4, etc.) with intelligent cost optimization
📈 Intelligent Data Summarization: Generate executive summaries and business insights from report data
🔄 Automated Report Management: Schedule, execute, and manage reports through Jaspersoft CE REST API
🎯 Deep IDE Integration: Native support for Cursor, Kiro, and other MCP-compatible development environments
🛡️ Production-Ready: Robust error handling, logging, and monitoring for enterprise deployments
📝 Documentation Compliance: All JRXML templates follow official Jaspersoft documentation standards

🚀 Quick Start

Prerequisites

Python 3.9+ with pip package manager
Jaspersoft Server 8.2 CE (running instance)
OpenRouter API key or compatible AI provider
MCP-compatible IDE (Cursor recommended) or MCP client

📦 Installation

# Clone the repository
git clone https://github.com/mr-wolf-gb/jasper-server-mcp.git
cd jasper-server-mcp

# Install dependencies
pip install -r requirements.txt

# Copy and configure environment
cp .env.example .env
# Edit .env with your actual credentials and URLs

# Validate setup
python setup.py

⚙️ Configuration

Create a .env file with the following settings:

# Jaspersoft Server Configuration
JASPERSOFT_BASE_URL=http://localhost:8080/jasperserver
JASPERSOFT_USERNAME=jasperadmin
JASPERSOFT_PASSWORD=jasperadmin

# AI Provider Configuration (OpenRouter)
OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_DEFAULT_MODEL=anthropic/claude-3.5-sonnet

# MCP Server Configuration
MCP_SERVER_HOST=localhost
MCP_SERVER_PORT=8000
LOG_LEVEL=INFO

# Optional: Alternative AI Providers
# OPENAI_API_KEY=your_openai_key
# ANTHROPIC_API_KEY=your_anthropic_key

⚠️ Important: Ensure your Jaspersoft Server URL doesn't have double protocol prefixes (e.g., avoid http://http://localhost). Always validate URLs for correct formatting.

🖥️ Running the Server

For Cursor IDE Integration (Recommended)

# Quick start with automatic setup validation
python start.py --http

# Or start directly
python -m jasper_mcp.http_server

# Server will run on http://localhost:8000
# All 5 MCP tools will be available

For Standard MCP Protocol

# Start the standard MCP server for stdin/stdout communication
python -m jasper_mcp.server

# The server will be available for direct MCP client connections

📝 IDE Integration

🎯 Cursor IDE Setup (Recommended)

Start the HTTP Server:
```
python -m jasper_mcp.http_server
```

Configure Cursor: Create or update your MCP configuration file:

Windows: C:\Users\<USERNAME>\AppData\Roaming\Cursor\User\globalStorage\mcp.json
Alternative: C:\Users\<USERNAME>\.cursor\mcp.json

Add this configuration:

{
  "mcpServers": {
    "jaspersoft": {
      "url": "http://localhost:8000",
      "name": "Jaspersoft Report Server",
      "description": "AI-powered report generation and management"
    }
  }
}

Restart Cursor: Complete restart required (close all windows, wait 10 seconds, restart)
Verify Integration:
- Check MCP panel in Cursor for "jaspersoft" server
- Confirm all 5 tools are loaded and available
- Test with a simple report generation prompt

🔧 Other MCP-Compatible IDEs

For IDEs supporting standard MCP protocol:

{
  "mcpServers": {
    "jaspersoft-mcp": {
      "command": "python",
      "args": ["-m", "jasper_mcp.server"],
      "cwd": "/path/to/jasper-server-mcp"
    }
  }
}

🔍 Troubleshooting IDE Integration

Connection Issues: Ensure server is running on correct port (8000)
Configuration Not Loading: Enable debug logging with "mcp.logLevel": "debug" in Cursor settings
Tools Not Appearing: Check server logs for import errors or missing dependencies
Authentication Failures: Verify Jaspersoft credentials in .env file

🛠️ Available MCP Tools

Tool	Description	Use Case
`generate_jrxml_template`	Generate JRXML templates from natural language	"Create a sales report with charts and regional breakdown"
`upload_report_to_jaspersoft`	Upload reports to Jaspersoft repository	Deploy generated reports to server
`run_report`	Execute reports with parameters and export	Generate PDF/Excel/HTML reports
`summarize_report_data`	Generate AI-powered data insights	Create executive summaries from report data
`schedule_report`	Create scheduled report executions	Automate recurring report generation

📝 Example Usage in Cursor IDE

Generate a Sales Report:

Create a monthly sales report template with:
- Regional breakdown by sales amount
- Bar charts showing trends
- Parameters for month and year selection
- Professional layout with company branding

Upload and Execute:

Upload the generated report to /reports/sales/monthly_sales and then run it with parameters: month=2025-01, include_charts=true, format=PDF

Data Analysis:

Analyze the sales data from the monthly report and provide key insights about performance trends, top regions, and recommendations for next quarter

🏢 Architecture

graph TB
    subgraph "AI-Enhanced IDEs"
        A[Cursor IDE] 
        B[Kiro IDE]
        C[VS Code with MCP]
        D[Other MCP Clients]
    end
    
    subgraph "MCP Server (jasper-server-mcp)"
        E[FastAPI HTTP Server]
        F[Tool Registry]
        G[JRXML Generator]
        H[AI Service Layer]
        I[Report Executor]
        J[Data Summarizer]
    end
    
    subgraph "External Services"
        K[Jaspersoft Server 8.2 CE]
        L[OpenRouter APIs]
        M[Database Sources]
        N[REST APIs]
    end
    
    A --> E
    B --> E
    C --> E
    D --> E
    E --> F
    F --> G
    F --> I
    F --> J
    G --> H
    I --> K
    J --> H
    H --> L
    K --> M
    K --> N

📊 Technology Stack

Backend: Python 3.9+, FastAPI, Uvicorn
MCP Protocol: Model Context Protocol v1.13.0+
AI Integration: OpenRouter, OpenAI SDK compatible
Report Engine: Jaspersoft Server 8.2 CE REST API
Data Processing: SQLAlchemy, Pandas, NumPy
HTTP Client: HTTPX (async), Requests (sync)
Template Processing: Jinja2, lxml, xmlschema
Configuration: Pydantic Settings, python-dotenv

🛠️ Development

📁 Project Structure

jasper-server-mcp/
├── jasper_mcp/                   # Main package
│   ├── __init__.py
│   ├── server.py                  # Standard MCP server (stdin/stdout)
│   ├── http_server.py             # HTTP MCP server (for IDEs)
│   ├── config.py                  # Configuration management
│   ├── tools/                     # MCP tool implementations
│   │   ├── registry.py               # Tool registration system
│   │   ├── jrxml_generator.py        # AI-powered JRXML generation
│   │   ├── jaspersoft_uploader.py    # Report upload to Jaspersoft
│   │   ├── report_runner.py          # Report execution
│   │   ├── data_summarizer.py        # AI data analysis
│   │   └── report_scheduler.py       # Report scheduling
│   ├── services/                  # Business logic layer
│   │   ├── ai_service.py             # AI provider integration
│   │   ├── report_executor.py        # Report execution logic
│   │   └── monitoring.py             # System monitoring
│   ├── clients/                   # External API clients
│   │   ├── jaspersoft_client.py      # Jaspersoft Server client
│   │   └── data_source_client.py     # Data source connections
│   ├── models/                    # Data models and schemas
│   │   ├── exceptions.py             # Custom exceptions
│   │   └── schemas.py                # Pydantic models
│   └── utils/                     # Utility modules
│       ├── jrxml_templates.py        # Main JRXML template interface
│       ├── jrxml_standard.py         # Documentation-compliant templates
│       └── jrxml_with_datasource.py  # Data source templates
├── tests/                         # Comprehensive test suite
│   ├── test_tools.py              # Tool functionality tests
│   ├── test_services.py           # Service layer tests
│   └── test_integration.py        # Integration tests
├── docs/                          # Documentation
│   └── jrxml.md                   # JRXML documentation reference
├── examples/                      # Usage examples
├── .env.example                   # Environment configuration template
├── requirements.txt               # Python dependencies
├── setup.py                       # Setup validation script
└── start.py                       # Server startup script

🧪 Testing

# Run all tests
pytest

# Run with coverage report
pytest --cov=jasper_mcp

# Run specific test categories
pytest tests/test_tools.py          # Tool functionality
pytest tests/test_services.py       # Service layer
pytest tests/test_integration.py    # Integration tests

# Validate setup
python setup.py

📝 Development Setup

Clone and setup development environment:

git clone https://github.com/mr-wolf-gb/jasper-server-mcp.git
cd jasper-server-mcp
pip install -r requirements.txt
cp .env.example .env

Configure for development:
- Update .env with development credentials
- Set LOG_LEVEL=DEBUG for verbose logging
- Ensure Jaspersoft Server is running locally

Run in development mode:

# With auto-reload
python start.py --http --reload

# Or using uvicorn directly
uvicorn jasper_mcp.http_server:app --reload --port 8000

🔍 Troubleshooting

Common Issues

Server won't start:

Check Python version (3.9+ required)
Verify all dependencies installed: pip install -r requirements.txt
Validate .env configuration: python setup.py

IDE not connecting:

Ensure server is running on correct port (8000)
Verify MCP configuration file path and syntax
Restart IDE completely after configuration changes
Enable debug logging: "mcp.logLevel": "debug"

Jaspersoft authentication errors:

Verify server URL (no double protocols like http://http://)
Check username/password credentials
Ensure Jaspersoft Server is accessible
Test connection: curl http://your-jaspersoft-url/rest_v2/serverInfo

AI generation failures:

Verify OpenRouter API key is valid
Check AI service status and rate limits
Review model availability and pricing
Enable fallback mechanisms in configuration

Getting Help

GitHub Issues: Report bugs and request features
Discussions: Community support and questions
Documentation: Check docs/ directory for detailed guides

📜 Documentation

- Official Jaspersoft documentation compliance
API Documentation - Detailed API reference
- Real-world usage examples
- Development guidelines

📝 License

This project is licensed under the MIT License - see the file for details.

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork the repository on GitHub
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Run the test suite: pytest
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Follow PEP 8 style guidelines
Add tests for new functionality
Update documentation for API changes
Ensure all tests pass before submitting
Use meaningful commit messages

🎆 Roadmap

Enhanced AI Models: Support for local LLMs and additional providers
Advanced Scheduling: Cron-like scheduling with dependencies
Dashboard Integration: Web UI for report management
Multi-tenant Support: Organization and user management
Report Templates Library: Pre-built industry-specific templates
Real-time Data Streaming: Live dashboard updates
API Expansion: RESTful API for external integrations

⭐ Support the Project

If this project helps you, please consider:

⭐ Starring the repository on GitHub
🐛 Reporting issues and suggesting improvements
📝 Contributing code or documentation
💬 Sharing your use cases in discussions

Repository: https://github.com/mr-wolf-gb/jasper-server-mcp

Made with ❤️ for the AI-powered development community