Metadata-Version: 2.4
Name: randonneuring-intelligence-mcp
Version: 0.1.0
Summary: MCP server for randonneuring cycling event data analysis - exposes 53 tools for AI agents
Author-email: Prathap Pandian <mprathappandian@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/mprathappandian/randonneuring-intelligence-mcp
Project-URL: Repository, https://github.com/mprathappandian/randonneuring-intelligence-mcp
Project-URL: Issues, https://github.com/mprathappandian/randonneuring-intelligence-mcp/issues
Project-URL: Documentation, https://github.com/mprathappandian/randonneuring-intelligence-mcp#readme
Keywords: mcp,randonneuring,cycling,audax,model-context-protocol,ai,lrm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: randonneuring-intelligence>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Dynamic: license-file

# Randonneuring Intelligence MCP Server

[![PyPI version](https://badge.fury.io/py/randonneuring-intelligence-mcp.svg)](https://badge.fury.io/py/randonneuring-intelligence-mcp)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**AI-powered analysis of randonneuring cycling event data through Model Context Protocol (MCP)**

An MCP server that exposes **53 specialized tools** for analyzing randonneuring cycling events. Works with Kiro, Claude Desktop, and any MCP-compatible AI client.

## What is This?

This MCP server lets AI agents analyze randonneuring (long-distance cycling) event data through natural language. It provides:

- **21 LRM tools** - Worldwide Long Randonnée Medal results
- **32 Audax India tools** - Indian randonneuring event data

Ask questions like:
- "Show me all 1200km events in Maharashtra last year"
- "What's the completion rate for Paris-Brest-Paris?"
- "Which clubs organized the most events in 2023?"

The AI uses the appropriate tools to answer your questions.

## Quick Start

### Installation

```bash
pip install randonneuring-intelligence-mcp
```

### Configure in Kiro

Add to your Kiro MCP config (`C:\Users\<username>\.kiro\settings\mcp.json` on Windows):

```json
{
  "mcpServers": {
    "randonneuring-intelligence": {
      "command": "randonneuring-mcp"
    }
  }
}
```

### Configure in Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "randonneuring-intelligence": {
      "command": "randonneuring-mcp"
    }
  }
}
```

### Restart Your AI Client

Restart Kiro or Claude Desktop to load the server.

## Features

### LRM (Long Randonnée Medal) - 21 Tools

**Filters (8 tools)**
- Filter by year, rider name, country, event, club, distance, gender, time

**Analysis (5 tools)**
- Rider statistics, club statistics, event statistics
- Time analysis, gender distribution

**Queries (6 tools)**
- List riders, clubs, events, countries, distances, years

### Audax India - 32 Tools

**Event Filters (7 tools)**
- Filter by year, club, location, state, distance, status, type

**Participant Filters (5 tools)**
- Filter by name, club, result status, medal, fee payment

**Analysis (6 tools)**
- Event statistics, club statistics, participant statistics
- Completion rates, state statistics, yearly trends

**Queries (8 tools)**
- List clubs, locations, states, distances, years
- List participants, participant clubs, rider numbers

## Example Queries

```
"Show me all 600km BRM events in Karnataka in 2023"
→ AI chains: audax_filter_by_year + audax_filter_by_distance + audax_filter_by_state

"What are the completion rates for different distances?"
→ AI calls: audax_get_completion_rates

"Show me John Smith's LRM statistics"
→ AI calls: lrm_get_rider_stats

"Which clubs have organized the most events?"
→ AI calls: audax_get_club_statistics
```

## Data

The package includes bundled data files (~23 MB):
- LRM worldwide results
- Audax India event catalog with participant details

Data is loaded once at startup for fast query performance.

## Requirements

- Python 3.10 or higher
- Works with any MCP-compatible AI client:
  - [Kiro](https://kiro.ai)
  - [Claude Desktop](https://claude.ai/download)
  - Custom MCP clients

## Architecture

```
AI Agent (Kiro/Claude)
       ↓
MCP Protocol (STDIO)
       ↓
This MCP Server
       ↓
randonneuring-intelligence (business logic)
       ↓
Bundled JSON Data Files
```

## Development

### Install from Source

```bash
git clone https://github.com/mprathappandian/randonneuring-intelligence-mcp.git
cd randonneuring-intelligence-mcp
pip install -e .
```

### Run Tests

```bash
pip install -e ".[dev]"
pytest
```

## Advanced Configuration

### Custom Data Directory

Set environment variable to use your own data files:

```json
{
  "mcpServers": {
    "randonneuring-intelligence": {
      "command": "randonneuring-mcp",
      "env": {
        "RANDONNEURING_DATA_DIR": "/path/to/your/data"
      }
    }
  }
}
```

### Debug Logging

```json
{
  "mcpServers": {
    "randonneuring-intelligence": {
      "command": "randonneuring-mcp",
      "env": {
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}
```

## Troubleshooting

### Server Won't Start

1. Check Python version: `python --version` (must be 3.10+)
2. Verify installation: `pip show randonneuring-intelligence-mcp`
3. Test manually: `randonneuring-mcp` (should show startup logs)

### Tools Not Working

1. Check logs in your AI client's console
2. Enable debug logging (see Advanced Configuration)
3. Verify data files loaded (check startup logs)

### Import Errors

Ensure `randonneuring-intelligence` is installed:
```bash
pip install randonneuring-intelligence
```

## Project Links

- **PyPI**: https://pypi.org/project/randonneuring-intelligence-mcp/
- **GitHub**: https://github.com/mprathappandian/randonneuring-intelligence-mcp
- **Issues**: https://github.com/mprathappandian/randonneuring-intelligence-mcp/issues

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Author

**Prathap Pandian**
- Email: mprathappandian@gmail.com
- GitHub: [@mprathappandian](https://github.com/mprathappandian)

## Acknowledgments

Built with:
- [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic
- [randonneuring-intelligence](https://pypi.org/project/randonneuring-intelligence/) - Core data processing library

## Version History

### 0.1.0 (2024-11-18)
- Initial release
- 53 tools (21 LRM + 32 Audax India)
- Bundled data files
- Support for Kiro and Claude Desktop
