mr-wolf-gb/jasper-server-mcp

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)

1. Start the HTTP Server:

   python -m jasper_mcp.http_server
   

2. 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"
       }
     }
   }
   

3. Restart Cursor: Complete restart required (close all windows, wait 10 seconds, restart)

4. 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

📝 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

1. 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
   

2. Configure for development:

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

3. 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:

1. Fork the repository on GitHub
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run the test suite: pytest
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. 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