Metadata-Version: 2.4
Name: oremi-rediyo
Version: 1.0.0b1
Summary: An MCP server for discovering public radio stations and stream URLs through Radio Browser
Project-URL: Say Thanks!, https://www.buymeacoffee.com/demsking
Project-URL: Source, https://gitlab.com/demsking/oremi-rediyo
Project-URL: Tracker, https://gitlab.com/demsking/oremi-rediyo/-/issues
Project-URL: Documentation, https://gitlab.com/demsking/oremi-rediyo/-/blob/main/README.md
Author-email: Sébastien Demanou <demsking@gmail.com>
Maintainer-email: Sébastien Demanou <demsking@gmail.com>
License: Apache-2.0
License-File: LICENSE
License-File: LICENSE_HEADER.txt
Keywords: agent,ai,llm,mcp,model-context-protocol,oremi,radio
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: fastapi[standard]<1.0.0,>=0.115.0
Requires-Dist: mcp>=1.28.1
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pydantic<3.0.0,>=2.10.0
Requires-Dist: radios>=0.3.2
Requires-Dist: uvicorn<1.0.0,>=0.34.0
Description-Content-Type: text/markdown

# Oremi Rediyo

[![Buy me a beer](https://img.shields.io/badge/Buy%20me-a%20beer-1f425f.svg)](https://www.buymeacoffee.com/demsking)

**Oremi Rediyo** is an MCP server for internet radio streaming. It
provides AI assistants and autonomous agents with a unified interface to
discover, search, and play radio stations from around the world through the
Model Context Protocol (MCP).

Built to run in Docker, Oremi Rediyo offers reliable access to thousands of
internet radio stations, allowing agents to browse stations by name, country,
language, genre, or popularity, and control playback using a standardized MCP
interface.

The name **Oremi Rediyo** comes from the Yoruba language. _Oremi_ means
_"my friend"_, reflecting the project's goal of building a helpful and
trustworthy AI ecosystem. _Rediyo_ is the Yoruba word for _"radio"_,
representing the service's responsibility for discovering and streaming
internet radio stations through a unified MCP interface.

![Oremi Rediyo Logo](htdocs/logo.jpg)

## Core Capabilities

- Search by station name, UUID, codec, country, country code, state, language,
  or tag
- Return complete station metadata, including the preferred `url_resolved`
  stream URL
- Browse countries, languages, and tags with station counts
- Inspect Radio Browser service statistics
- Register a Radio Browser click when playback starts
- Configure timeouts, result limits, broken-station filtering, HTTP binding,
  API prefix, and logging through environment variables
- Serve MCP over Streamable HTTP
- Run as a lightweight Docker container with simple deployment.
- Integrate seamlessly with the Oremi ecosystem and other MCP-compatible
  clients.

## MCP tools

| Tool                      | Purpose                                         |
| ------------------------- | ----------------------------------------------- |
| `search_radio_stations`   | Discover stations and their stream URLs         |
| `get_radio_station`       | Retrieve current metadata for one station UUID  |
| `list_radio_countries`    | Browse countries and station counts             |
| `list_radio_languages`    | Browse languages and station counts             |
| `list_radio_tags`         | Browse genres/tags and station counts           |
| `get_radio_browser_stats` | Inspect directory status and totals             |
| `register_radio_playback` | Register a click after playback actually starts |

Search results expose both `url` and `url_resolved`. Prefer `url_resolved` for
playback because Radio Browser has already followed playlist/redirect URLs.

## Documentation

All project documentation—including architecture details, configuration
reference, and the Home Assistant integration guide—can be found at:
https://demsking.gitlab.io/oremi-rediyo/

## Development

Oremi Device is built with Python and uses `uv` for dependency management. The
project follows standard Python development practices with type hints, linting,
and automated testing.

For detailed information on setting up your development environment, running
tests, code style guidelines, and the pull request process, please refer to
[CONTRIBUTING.md](https://gitlab.com/demsking/oremi-rediyo/-/blob/main/CONTRIBUTING.md).

## Versioning

This project adheres to [Semantic Versioning](https://semver.org/) (SemVer).
Version numbers follow the `MAJOR.MINOR.PATCH` format:

- **MAJOR** version increments for incompatible API changes
- **MINOR** version increments for backward-compatible new functionality
- **PATCH** version increments for backward-compatible bug fixes

## License

Copyright 2026 Sébastien Demanou. All Rights Reserved.

Licensed under the Apache License, Version 2.0. See the
[LICENSE](https://gitlab.com/demsking/oremi-rediyo/-/blob/main/LICENSE) for the
complete license text.
