# Respona Dashboard MCP Server
An MCP (Model Context Protocol) server that provides tools to interact with the Respona Dashboard backend API. This server allows users to query ticket data, analytics, and AI flags through natural language interactions.
## Features
This MCP server implements 13 tools corresponding to the Respona Dashboard API endpoints:
### Ticket Management Tools
- **get_tickets** - Retrieve tickets with filtering and pagination
- **get_ticket_stats** - Get ticket statistics and metrics
- **get_ticket_by_id** - Retrieve a specific ticket by ID
- **get_ticket_ai_analysis** - Get AI analysis for a specific ticket
### Analytics Tools
- **get_ai_flags_distribution** - Get AI flags distribution for analytics
- **get_similar_incidents** - Get count of similar incidents
- **get_source_channels_distribution** - Get distribution of ticket source channels
- **get_priority_distribution** - Get distribution of ticket priorities
- **get_status_distribution** - Get distribution of ticket statuses
- **get_dashboard_analytics** - Get comprehensive analytics for dashboard
### AI Flags Tools
- **get_analysis_flags** - Get all flags for a specific AI analysis
- **get_analysis_flag_stats** - Get flag statistics for an AI analysis
- **get_all_flags** - Get all flags with pagination (admin view)
## Installation
1. **Clone the repository:**
```bash
git clone <repository-url>
cd respona_mcp_server
```
2. **Install dependencies:**
```bash
pip install -e .
```
Or using uv (recommended):
```bash
uv pip install -e .
```
3. **Set up configuration:**
```bash
cp .env.example .env
# Edit .env with your configuration
```
## Configuration
The server can be configured through environment variables or a `.env` file:
### API Configuration
- `RESPONA_API_BASE_URL`: Base URL for the Respona Dashboard API (default: `http://10.250.201.107:3001`)
- `RESPONA_API_KEY`: API key for authentication (optional)
### Request Configuration
- `RESPONA_REQUEST_TIMEOUT`: Request timeout in seconds (default: 30)
- `RESPONA_MAX_RETRIES`: Maximum number of request retries (default: 3)
### Pagination Configuration
- `RESPONA_DEFAULT_PAGE_SIZE`: Default number of items per page (default: 20)
- `RESPONA_MAX_PAGE_SIZE`: Maximum allowed page size (default: 100)
## Usage
### Running the Server
```bash
# Run directly
python -m respona_mcp_server
# Or using the installed script
respona-mcp-server
```
### MCP Client Configuration
Add this server to your MCP client configuration. For example, in Claude Desktop, add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"respona-dashboard": {
"command": "python",
"args": ["-m", "respona_mcp_server"],
"env": {
"RESPONA_API_BASE_URL": "http://10.250.201.107:3001"
}
}
}
}
```
Or if you have the package installed globally:
```json
{
"mcpServers": {
"respona-dashboard": {
"command": "respona-mcp-server",
"env": {
"RESPONA_API_BASE_URL": "http://10.250.201.107:3001"
}
}
}
}
```
## Tool Usage Examples
### Get All Tickets
```
Get me all tickets with high priority from the last week
```
### Get Ticket Statistics
```
Show me the current ticket statistics
```
### Get Specific Ticket
```
Show me details for ticket ID 12345
```
### Get Analytics
```
What's the distribution of ticket priorities?
```
### Filter Tickets
```
Show me all tickets assigned to John Doe with status "open"
```
### Get AI Analysis
```
Get the AI analysis for ticket 67890
```
## API Endpoints Mapping
| Tool Name | API Endpoint | Description |
|-----------|--------------|-------------|
| get_tickets | GET /api/tickets | Retrieve tickets with filtering |
| get_ticket_stats | GET /api/tickets/stats | Get ticket statistics |
| get_ticket_by_id | GET /api/tickets/{id} | Get specific ticket |
| get_ticket_ai_analysis | GET /api/tickets/{id}/ai-analysis | Get AI analysis |
| get_ai_flags_distribution | GET /api/analytics/ai-flags | Get AI flags distribution |
| get_similar_incidents | GET /api/analytics/similar-incidents | Get similar incidents count |
| get_source_channels_distribution | GET /api/analytics/source-channels | Get source channels distribution |
| get_priority_distribution | GET /api/analytics/priority-distribution | Get priority distribution |
| get_status_distribution | GET /api/analytics/status-distribution | Get status distribution |
| get_dashboard_analytics | GET /api/analytics/dashboard | Get all analytics |
| get_analysis_flags | GET /api/ai-flags/analysis/{analysisId}/flags | Get analysis flags |
| get_analysis_flag_stats | GET /api/ai-flags/analysis/{analysisId}/flags/stats | Get flag statistics |
| get_all_flags | GET /api/ai-flags/flags | Get all flags (admin) |
## Error Handling
The server includes comprehensive error handling:
- **Network Errors**: Automatic retries with exponential backoff
- **API Errors**: Proper HTTP status code handling
- **Parameter Validation**: Input validation with helpful error messages
- **Connection Issues**: Graceful handling of API server downtime
## Development
### Running Tests
```bash
pytest
```
### Code Formatting
```bash
ruff format .
ruff check .
```
### Type Checking
```bash
mypy respona_mcp_server/
```
## Troubleshooting
### Common Issues
1. **Connection Refused**
- Check if the Respona API server is running
- Verify the `RESPONA_API_BASE_URL` configuration
- Check network connectivity
2. **Authentication Errors**
- Verify API key configuration if required
- Check if the API key has proper permissions
3. **Timeout Errors**
- Increase `RESPONA_REQUEST_TIMEOUT`
- Check network latency to the API server
### Logging
The server uses Python's standard logging. Set the log level:
```bash
export PYTHONPATH=.
python -m respona_mcp_server --log-level DEBUG
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-respona-dashboard",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "raihan0824 <raihan0824@users.noreply.github.com>",
"keywords": "analytics, api, dashboard, mcp, model-context-protocol, respona, tickets",
"author": null,
"author_email": "raihan0824 <raihan0824@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/42/7c/1218b911284f71ca49ec485678f5910ad09c04b6c91b895c9ad13192a5e6/mcp_respona_dashboard-1.0.2.tar.gz",
"platform": null,
"description": "# Respona Dashboard MCP Server\n\nAn MCP (Model Context Protocol) server that provides tools to interact with the Respona Dashboard backend API. This server allows users to query ticket data, analytics, and AI flags through natural language interactions.\n\n## Features\n\nThis MCP server implements 13 tools corresponding to the Respona Dashboard API endpoints:\n\n### Ticket Management Tools\n- **get_tickets** - Retrieve tickets with filtering and pagination\n- **get_ticket_stats** - Get ticket statistics and metrics\n- **get_ticket_by_id** - Retrieve a specific ticket by ID\n- **get_ticket_ai_analysis** - Get AI analysis for a specific ticket\n\n### Analytics Tools\n- **get_ai_flags_distribution** - Get AI flags distribution for analytics\n- **get_similar_incidents** - Get count of similar incidents\n- **get_source_channels_distribution** - Get distribution of ticket source channels\n- **get_priority_distribution** - Get distribution of ticket priorities\n- **get_status_distribution** - Get distribution of ticket statuses\n- **get_dashboard_analytics** - Get comprehensive analytics for dashboard\n\n### AI Flags Tools\n- **get_analysis_flags** - Get all flags for a specific AI analysis\n- **get_analysis_flag_stats** - Get flag statistics for an AI analysis\n- **get_all_flags** - Get all flags with pagination (admin view)\n\n## Installation\n\n1. **Clone the repository:**\n ```bash\n git clone <repository-url>\n cd respona_mcp_server\n ```\n\n2. **Install dependencies:**\n ```bash\n pip install -e .\n ```\n \n Or using uv (recommended):\n ```bash\n uv pip install -e .\n ```\n\n3. **Set up configuration:**\n ```bash\n cp .env.example .env\n # Edit .env with your configuration\n ```\n\n## Configuration\n\nThe server can be configured through environment variables or a `.env` file:\n\n### API Configuration\n- `RESPONA_API_BASE_URL`: Base URL for the Respona Dashboard API (default: `http://10.250.201.107:3001`)\n- `RESPONA_API_KEY`: API key for authentication (optional)\n\n### Request Configuration\n- `RESPONA_REQUEST_TIMEOUT`: Request timeout in seconds (default: 30)\n- `RESPONA_MAX_RETRIES`: Maximum number of request retries (default: 3)\n\n### Pagination Configuration\n- `RESPONA_DEFAULT_PAGE_SIZE`: Default number of items per page (default: 20)\n- `RESPONA_MAX_PAGE_SIZE`: Maximum allowed page size (default: 100)\n\n## Usage\n\n### Running the Server\n\n```bash\n# Run directly\npython -m respona_mcp_server\n\n# Or using the installed script\nrespona-mcp-server\n```\n\n### MCP Client Configuration\n\nAdd this server to your MCP client configuration. For example, in Claude Desktop, add to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"respona-dashboard\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"respona_mcp_server\"],\n \"env\": {\n \"RESPONA_API_BASE_URL\": \"http://10.250.201.107:3001\"\n }\n }\n }\n}\n```\n\nOr if you have the package installed globally:\n\n```json\n{\n \"mcpServers\": {\n \"respona-dashboard\": {\n \"command\": \"respona-mcp-server\",\n \"env\": {\n \"RESPONA_API_BASE_URL\": \"http://10.250.201.107:3001\"\n }\n }\n }\n}\n```\n\n## Tool Usage Examples\n\n### Get All Tickets\n```\nGet me all tickets with high priority from the last week\n```\n\n### Get Ticket Statistics\n```\nShow me the current ticket statistics\n```\n\n### Get Specific Ticket\n```\nShow me details for ticket ID 12345\n```\n\n### Get Analytics\n```\nWhat's the distribution of ticket priorities?\n```\n\n### Filter Tickets\n```\nShow me all tickets assigned to John Doe with status \"open\"\n```\n\n### Get AI Analysis\n```\nGet the AI analysis for ticket 67890\n```\n\n## API Endpoints Mapping\n\n| Tool Name | API Endpoint | Description |\n|-----------|--------------|-------------|\n| get_tickets | GET /api/tickets | Retrieve tickets with filtering |\n| get_ticket_stats | GET /api/tickets/stats | Get ticket statistics |\n| get_ticket_by_id | GET /api/tickets/{id} | Get specific ticket |\n| get_ticket_ai_analysis | GET /api/tickets/{id}/ai-analysis | Get AI analysis |\n| get_ai_flags_distribution | GET /api/analytics/ai-flags | Get AI flags distribution |\n| get_similar_incidents | GET /api/analytics/similar-incidents | Get similar incidents count |\n| get_source_channels_distribution | GET /api/analytics/source-channels | Get source channels distribution |\n| get_priority_distribution | GET /api/analytics/priority-distribution | Get priority distribution |\n| get_status_distribution | GET /api/analytics/status-distribution | Get status distribution |\n| get_dashboard_analytics | GET /api/analytics/dashboard | Get all analytics |\n| get_analysis_flags | GET /api/ai-flags/analysis/{analysisId}/flags | Get analysis flags |\n| get_analysis_flag_stats | GET /api/ai-flags/analysis/{analysisId}/flags/stats | Get flag statistics |\n| get_all_flags | GET /api/ai-flags/flags | Get all flags (admin) |\n\n## Error Handling\n\nThe server includes comprehensive error handling:\n\n- **Network Errors**: Automatic retries with exponential backoff\n- **API Errors**: Proper HTTP status code handling\n- **Parameter Validation**: Input validation with helpful error messages\n- **Connection Issues**: Graceful handling of API server downtime\n\n## Development\n\n### Running Tests\n```bash\npytest\n```\n\n### Code Formatting\n```bash\nruff format .\nruff check .\n```\n\n### Type Checking\n```bash\nmypy respona_mcp_server/\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Connection Refused**\n - Check if the Respona API server is running\n - Verify the `RESPONA_API_BASE_URL` configuration\n - Check network connectivity\n\n2. **Authentication Errors**\n - Verify API key configuration if required\n - Check if the API key has proper permissions\n\n3. **Timeout Errors**\n - Increase `RESPONA_REQUEST_TIMEOUT`\n - Check network latency to the API server\n\n### Logging\n\nThe server uses Python's standard logging. Set the log level:\n\n```bash\nexport PYTHONPATH=.\npython -m respona_mcp_server --log-level DEBUG\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Run the test suite\n6. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details. ",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for Respona Dashboard API integration - enables natural language interactions with ticket management and analytics systems",
"version": "1.0.2",
"project_urls": {
"Changelog": "https://github.com/raihan0824/mcp-respona-dashboard/releases",
"Homepage": "https://github.com/raihan0824/mcp-respona-dashboard",
"Issues": "https://github.com/raihan0824/mcp-respona-dashboard/issues",
"Repository": "https://github.com/raihan0824/mcp-respona-dashboard"
},
"split_keywords": [
"analytics",
" api",
" dashboard",
" mcp",
" model-context-protocol",
" respona",
" tickets"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "974a756129c68167885621f4f2419d302a3ec17bc08eaf3e7e8ac5846f79dc40",
"md5": "81b4e70ffdb1c037d4dbbb325b8e6e6c",
"sha256": "924f7675b02505973244ba7246bdfdedc1c351ffe118c2cbfde0a3a8a7c92704"
},
"downloads": -1,
"filename": "mcp_respona_dashboard-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "81b4e70ffdb1c037d4dbbb325b8e6e6c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 10918,
"upload_time": "2025-08-04T14:13:34",
"upload_time_iso_8601": "2025-08-04T14:13:34.741232Z",
"url": "https://files.pythonhosted.org/packages/97/4a/756129c68167885621f4f2419d302a3ec17bc08eaf3e7e8ac5846f79dc40/mcp_respona_dashboard-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "427c1218b911284f71ca49ec485678f5910ad09c04b6c91b895c9ad13192a5e6",
"md5": "fb7ebafca75a1c58a06d489c5d7fd406",
"sha256": "a0f1d942edd1903b59e15fb4b1ac8fb82c48e1020dc9000c14e4a54675c688ac"
},
"downloads": -1,
"filename": "mcp_respona_dashboard-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "fb7ebafca75a1c58a06d489c5d7fd406",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 11119,
"upload_time": "2025-08-04T14:13:36",
"upload_time_iso_8601": "2025-08-04T14:13:36.240424Z",
"url": "https://files.pythonhosted.org/packages/42/7c/1218b911284f71ca49ec485678f5910ad09c04b6c91b895c9ad13192a5e6/mcp_respona_dashboard-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 14:13:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "raihan0824",
"github_project": "mcp-respona-dashboard",
"github_not_found": true,
"lcname": "mcp-respona-dashboard"
}
JSON
