# fyipedia-mcp

[![PyPI](https://img.shields.io/pypi/v/fyipedia-mcp)](https://pypi.org/project/fyipedia-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/fyipedia-mcp)](https://pypi.org/project/fyipedia-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Unified [MCP](https://modelcontextprotocol.io/) server for the [FYIPedia](https://github.com/fyipedia) developer tools ecosystem. One server gives AI assistants access to 53 tools from 10 packages -- [color conversion](https://colorfyi.com/), [emoji metadata](https://emojifyi.com/), [symbol encoding](https://symbolfyi.com/), [Unicode lookup](https://unicodefyi.com/), [Google Fonts](https://fontfyi.com/), [distance calculation](https://distancefyi.com/), [timezone operations](https://timefyi.com/), [Korean romanization](https://namefyi.com/), [unit conversion](https://unitfyi.com/), and [holiday dates](https://holidayfyi.com/).

> **One config, 53 tools.** Works with [Claude Desktop](https://claude.ai/download), [Cursor](https://cursor.com/), [Windsurf](https://codeium.com/windsurf), [Continue](https://continue.dev/), and any [MCP-compatible](https://modelcontextprotocol.io/) client. Each package is loaded lazily -- only installed packages register their tools.

<p align="center">
  <img src="demo.gif" alt="fyipedia-mcp demo — MCP server for AI agents" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Integration Guides](#integration-guides)
  - [Claude Desktop](#claude-desktop)
  - [Cursor](#cursor)
  - [Windsurf](#windsurf)
  - [Claude Code](#claude-code)
  - [Standalone](#standalone)
- [What You Can Do](#what-you-can-do)
  - [Color Analysis](#color-analysis)
  - [Text & Encoding](#text--encoding)
  - [Geography & Time](#geography--time)
  - [Reference Data](#reference-data)
- [Available Tools (53 total)](#available-tools-53-total)
  - [Color Tools (9 tools)](#color-tools-9-tools----colorfyi)
  - [Emoji Tools (7 tools)](#emoji-tools-7-tools----emojifyi)
  - [Symbol Tools (3 tools)](#symbol-tools-3-tools----symbolfyi)
  - [Unicode Tools (4 tools)](#unicode-tools-4-tools----unicodefyi)
  - [Font Tools (6 tools)](#font-tools-6-tools----fontfyi)
  - [Distance Tools (5 tools)](#distance-tools-5-tools----distancefyi)
  - [Time Tools (5 tools)](#time-tools-5-tools----timefyi)
  - [Unit Tools (4 tools)](#unit-tools-4-tools----unitfyi)
  - [Name Tools (4 tools)](#name-tools-4-tools----namefyi)
  - [Holiday Tools (5 tools)](#holiday-tools-5-tools----holidayfyi)
- [Architecture](#architecture)
- [Features](#features)
- [Also Available as CLI](#also-available-as-cli)
- [FYIPedia Developer Tools](#fyipedia-developer-tools)
- [Links](#links)
- [License](#license)

## Install

```bash
pip install "fyipedia-mcp[all]"              # All 53 tools from 10 packages
pip install "fyipedia-mcp[color,distance]"   # Just color + distance (14 tools)
pip install "fyipedia-mcp[color,emoji,font]" # Pick any combination
pip install fyipedia-mcp                     # Core only (no tools)
```

Requires Python 3.10+. Each package is an optional dependency.

## Integration Guides

### Claude Desktop

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

```json
{
    "mcpServers": {
        "fyipedia": {
            "command": "python",
            "args": ["-m", "fyipedia_mcp.server"]
        }
    }
}
```

Restart Claude Desktop. You should see 53 tools available under "fyipedia".

### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
    "mcpServers": {
        "fyipedia": {
            "command": "python",
            "args": ["-m", "fyipedia_mcp.server"]
        }
    }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
    "mcpServers": {
        "fyipedia": {
            "command": "python",
            "args": ["-m", "fyipedia_mcp.server"]
        }
    }
}
```

### Claude Code

Add to `~/.claude/settings.json`:

```json
{
    "mcpServers": {
        "fyipedia": {
            "command": "python",
            "args": ["-m", "fyipedia_mcp.server"]
        }
    }
}
```

### Standalone

Run the server directly for testing:

```bash
python -m fyipedia_mcp.server
```

## What You Can Do

### Color Analysis

AI assistants can use the 9 color tools to answer questions about color accessibility, design systems, and visual perception. Ask your assistant to check whether a text/background combination meets WCAG 2.1 AA or AAA standards, generate a Tailwind-style shade palette from a brand color, simulate how a UI appears to users with protanopia or deuteranopia, or mix two colors in perceptual Lab space for accurate blending.

```
"Check if #1A1A2E text on #F0F0F0 background passes WCAG AA"
"Generate a shade palette from our brand blue #3B82F6"
"How does #FF5733 look to someone with color blindness?"
"What's the complementary color of #8B5CF6?"
```

Learn more: [ColorFYI](https://colorfyi.com/)

### Text & Encoding

The emoji, Unicode, and symbol tools give AI assistants access to 3,953 emoji metadata records, 17 Unicode encoding formats, and 11 symbol encoding representations. Your assistant can look up any emoji by keyword or character, encode text for HTML/CSS/JavaScript/Python, find Unicode character properties like script and bidirectional class, and reverse-lookup HTML entities.

```
"What's the Unicode codepoint for the fire emoji?"
"Encode the copyright symbol for use in HTML, CSS, and JavaScript"
"Search for all arrow-related Unicode characters"
"What HTML entity represents the hearts symbol?"
```

Learn more: [EmojiFYI](https://emojifyi.com/) · [UnicodeFYI](https://unicodefyi.com/) · [SymbolFYI](https://symbolfyi.com/)

### Geography & Time

The 10 distance and time tools let AI assistants calculate great-circle distances using the Haversine formula, determine compass bearings between coordinates, find geographic midpoints, estimate travel times by car/train/plane, and handle timezone conversions across all IANA zones. Assistants can also find overlapping business hours across multiple time zones and look up sunrise/sunset times for any location.

```
"How far is it from Seoul to Tokyo, and what's the flight time?"
"What time is it in New York when it's 9 AM in Seoul?"
"Find overlapping business hours between London, Tokyo, and San Francisco"
"When is sunrise today in Paris?"
```

Learn more: [DistanceFYI](https://distancefyi.com/) · [TimeFYI](https://timefyi.com/)

### Reference Data

The unit, font, holiday, and name tools provide AI assistants with structured reference data. Convert between 220 units across 20 measurement categories with Decimal precision. Look up Google Fonts metadata, CSS import snippets, and font pairing recommendations. Check public holidays for 100+ countries, calculate Easter dates, and find specific weekday occurrences. Romanize Korean text using the official Revised Romanization system and look up Five Elements for CJK stroke counts.

```
"Convert 185 centimeters to feet and inches"
"What Google Fonts pair well with Inter for body text?"
"Is December 25th a holiday in Japan?"
"Romanize the Korean name 김민준"
```

Learn more: [UnitFYI](https://unitfyi.com/) · [FontFYI](https://fontfyi.com/) · [HolidayFYI](https://holidayfyi.com/) · [NameFYI](https://namefyi.com/)

## Available Tools (53 total)

### Color Tools (9 tools) -- `colorfyi`

| Tool | Parameters | Description |
|------|-----------|-------------|
| `colorfyi_color_info` | `hex_code` | Convert hex to 7 color spaces (RGB, HSL, HSV, CMYK, Lab, OKLCH) |
| `colorfyi_contrast_check` | `fg`, `bg` | WCAG 2.1 contrast ratio with AA/AAA compliance checks |
| `colorfyi_color_harmonies` | `hex_code` | 5 harmony types (complementary, analogous, triadic, split-comp, tetradic) |
| `colorfyi_color_shades` | `hex_code` | Tailwind-style shade palette (50-950 scale) |
| `colorfyi_simulate_color_blindness` | `hex_code` | Protanopia, deuteranopia, tritanopia, achromatopsia simulation |
| `colorfyi_mix_colors` | `hex1`, `hex2`, `ratio?` | Mix two colors in perceptual Lab space |
| `colorfyi_compare_colors` | `hex1`, `hex2` | Delta E comparison, contrast ratio, gradient |
| `colorfyi_gradient` | `hex1`, `hex2`, `steps?` | Smooth perceptual gradient steps |
| `colorfyi_text_color_for_background` | `hex_code` | Best text color (black or white) for any background |

### Emoji Tools (7 tools) -- `emojifyi`

| Tool | Parameters | Description |
|------|-----------|-------------|
| `emojifyi_emoji_lookup` | `slug` | Full emoji metadata (character, codepoint, category, Unicode version, skin tones) |
| `emojifyi_emoji_by_char` | `character` | Reverse lookup -- find emoji info from character |
| `emojifyi_emoji_search` | `query`, `limit?` | Search 3,953 emojis by keyword |
| `emojifyi_emoji_encode` | `character` | 8 encodings (UTF-8, UTF-16, HTML decimal/hex, CSS, Python, JS, Java) |
| `emojifyi_emoji_categories` | -- | All 10 emoji categories with icons and counts |
| `emojifyi_emoji_by_category` | `category_slug`, `limit?` | Browse emojis within a category |
| `emojifyi_emoji_stats` | -- | Dataset statistics (total emojis, ZWJ sequences, skin tone variants) |

### Symbol Tools (3 tools) -- `symbolfyi`

| Tool | Parameters | Description |
|------|-----------|-------------|
| `symbolfyi_symbol_info` | `character` | Full Unicode properties (name, block, script, bidi, combining) + 11 encodings |
| `symbolfyi_symbol_encode` | `character` | 11 formats (Unicode, HTML decimal/hex/entity, CSS, JS, Python, Java, UTF-8/16, URL) |
| `symbolfyi_html_entity_lookup` | `entity` | Reverse HTML entity lookup (e.g., `&hearts;` to character) |

### Unicode Tools (4 tools) -- `unicodefyi`

| Tool | Parameters | Description |
|------|-----------|-------------|
| `unicodefyi_char_info` | `codepoint_or_char` | Full Unicode info (accepts U+hex, character, or hex codepoint) |
| `unicodefyi_char_encode` | `codepoint_or_char` | 17 encodings (HTML, CSS, JS, Python, Go, Ruby, Rust, C/C++, URL, UTF-8/16/32) |
| `unicodefyi_unicode_search` | `query`, `limit?` | Search characters by name substring |
| `unicodefyi_html_entity_lookup` | `entity` | HTML entity lookup (e.g., `&amp;` to ampersand) |

### Font Tools (6 tools) -- `fontfyi`

| Tool | Parameters | Description |
|------|-----------|-------------|
| `fontfyi_font_info` | `slug` | Google Font metadata (family, category, weights, subsets, designer, rank) |
| `fontfyi_font_search` | `query`, `limit?` | Search Google Fonts by name |
| `fontfyi_font_css` | `slug` | CSS import snippet + font-family declaration |
| `fontfyi_font_pairings` | `slug` | Font pairing recommendations with mood and use cases |
| `fontfyi_font_stacks` | -- | 10 CSS font stack presets for common use cases |
| `fontfyi_popular_fonts` | `limit?` | Most popular Google Fonts by rank |

### Distance Tools (5 tools) -- `distancefyi`

| Tool | Parameters | Description |
|------|-----------|-------------|
| `distancefyi_calculate_distance` | `lat1`, `lon1`, `lat2`, `lon2`, `same_continent?` | Full distance report (km/miles/NM), bearing, midpoint, travel times |
| `distancefyi_get_bearing` | `lat1`, `lon1`, `lat2`, `lon2` | Bearing degrees + compass direction (N, NE, E, etc.) |
| `distancefyi_get_midpoint` | `lat1`, `lon1`, `lat2`, `lon2` | Geographic midpoint coordinates |
| `distancefyi_get_flight_time` | `distance_km` | Estimated flight time (variable speed 600-850 km/h) |
| `distancefyi_convert_distance` | `value`, `from_unit`, `to_unit` | Distance conversion between km, miles, nautical miles |

### Time Tools (5 tools) -- `timefyi`

| Tool | Parameters | Description |
|------|-----------|-------------|
| `timefyi_current_time` | `timezone_id` | Current time in IANA timezone (with UTC offset, DST status) |
| `timefyi_time_difference` | `from_tz`, `to_tz` | Time difference between two timezones |
| `timefyi_convert_time` | `time_str`, `from_tz`, `to_tz` | Convert specific time across timezones |
| `timefyi_business_hours_overlap` | `timezones`, `start_hour?`, `end_hour?` | Find overlapping business hours across timezones |
| `timefyi_sun_info` | `latitude`, `longitude`, `timezone_id` | Sunrise, sunset, day length, current daylight status |

### Unit Tools (4 tools) -- `unitfyi`

| Tool | Parameters | Description |
|------|-----------|-------------|
| `unitfyi_convert_unit` | `value`, `from_unit`, `to_unit` | Convert between 220 units in 20 categories with Decimal precision |
| `unitfyi_conversion_table` | `from_unit`, `to_unit` | Markdown table with common conversion values |
| `unitfyi_list_categories` | -- | All 20 measurement categories (length, weight, temperature, volume, etc.) |
| `unitfyi_list_units` | `category` | All units in a category with slug, name, and symbol |

### Name Tools (4 tools) -- `namefyi`

| Tool | Parameters | Description |
|------|-----------|-------------|
| `namefyi_romanize_korean` | `hangul` | Revised Romanization of Korean text |
| `namefyi_five_elements` | `stroke_count` | Five Elements category (Wood/Fire/Earth/Metal/Water) for CJK stroke count |
| `namefyi_element_compatibility` | `element_a`, `element_b` | Compatibility between two Five Elements (compatible/neutral/incompatible) |
| `namefyi_format_population` | `population` | Format large numbers with M/K suffixes |

### Holiday Tools (5 tools) -- `holidayfyi`

| Tool | Parameters | Description |
|------|-----------|-------------|
| `holidayfyi_upcoming_holidays` | `country_iso`, `n?` | Next N public holidays for ISO country code |
| `holidayfyi_check_holidays_on_date` | `date_str`, `countries` | Check holidays on a specific date across multiple countries |
| `holidayfyi_easter_date` | `year`, `orthodox?` | Western or Orthodox Easter date for any year |
| `holidayfyi_nth_weekday` | `year`, `month`, `weekday`, `n` | Find nth occurrence of weekday in a month (e.g., 4th Thursday) |
| `holidayfyi_count_days_until` | `target_date_str`, `from_date_str?` | Days countdown to a target date |

## Architecture

FYIPedia MCP uses a **hub aggregation pattern**. Each package has its own standalone MCP server. The hub collects all tools into a single server:

```
fyipedia-mcp (hub server)
│
├── colorfyi.mcp_server     →  9 tools prefixed with colorfyi_
├── emojifyi.mcp_server     →  7 tools prefixed with emojifyi_
├── symbolfyi.mcp_server    →  3 tools prefixed with symbolfyi_
├── unicodefyi.mcp_server   →  4 tools prefixed with unicodefyi_
├── fontfyi.mcp_server      →  6 tools prefixed with fontfyi_
├── distancefyi.mcp_server  →  5 tools prefixed with distancefyi_
├── timefyi.mcp_server      →  5 tools prefixed with timefyi_
├── namefyi.mcp_server      →  4 tools prefixed with namefyi_
├── unitfyi.mcp_server      →  4 tools prefixed with unitfyi_
└── holidayfyi.mcp_server   →  5 tools prefixed with holidayfyi_
                               ──
                               52 tools total
```

**How it works:**

1. Hub defines a catalog of 10 `(package_name, module_path)` entries
2. At startup, `importlib.import_module()` loads each package's MCP module
3. Tools are extracted from each package's `FastMCP._tool_manager._tools`
4. Each tool is re-registered on the hub with a `{package}_` prefix to avoid collisions
5. Missing packages are silently skipped -- partial installation works fine

**Why a hub?** Instead of configuring 10 separate MCP servers, you configure one. AI assistants see all tools in a single namespace. Install only the packages you need, and only those tools appear.

**Standalone mode** -- each package can also run its own MCP server independently:

```json
{
    "mcpServers": {
        "colorfyi": {
            "command": "python",
            "args": ["-m", "colorfyi.mcp_server"]
        }
    }
}
```

## Features

- **53 tools from 10 packages**: Color, emoji, symbol, Unicode, font, distance, time, name, unit, holiday
- **One config**: Single MCP server entry instead of 10 separate configurations
- **Lazy loading**: Only installed packages register their tools -- no bloat
- **Flexible installation**: Install all tools or pick specific packages
- **Tool name prefixing**: Automatic `{package}_` prefix prevents collisions
- **Graceful degradation**: Missing packages are silently skipped
- **MCP v1.0 compatible**: Works with any MCP client (Claude, Cursor, Windsurf, Continue, etc.)
- **Markdown responses**: All tools return formatted markdown for readable AI output
- **Type-safe**: Full type annotations, strict mypy, PEP 561 compliant
- **Zero lock-in**: Each package's MCP server also works standalone

## Also Available as CLI

Use all 10 tools from the terminal via the [unified CLI](https://github.com/fyipedia/fyipedia):

```bash
pip install "fyipedia[all]"
fyi color info FF6B35
fyi distance calc --lat1 37.57 --lon1 126.98 --lat2 35.68 --lon2 139.65
```

See the [fyipedia README](https://github.com/fyipedia/fyipedia) for the full command reference.

## FYIPedia Developer Tools

Part of the [FYIPedia](https://github.com/fyipedia) open-source developer tools ecosystem:

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| [colorfyi](https://colorfyi.com/) | [`colorfyi`](https://pypi.org/project/colorfyi/) | [`@fyipedia/colorfyi`](https://www.npmjs.com/package/@fyipedia/colorfyi) | Color conversion, WCAG contrast, harmonies, 809 named colors |
| [emojifyi](https://emojifyi.com/) | [`emojifyi`](https://pypi.org/project/emojifyi/) | [`emojifyi`](https://www.npmjs.com/package/emojifyi) | Emoji encoding & metadata for 3,953 Unicode emojis |
| [symbolfyi](https://symbolfyi.com/) | [`symbolfyi`](https://pypi.org/project/symbolfyi/) | [`symbolfyi`](https://www.npmjs.com/package/symbolfyi) | Symbol encoding in 11 formats + Unicode properties |
| [unicodefyi](https://unicodefyi.com/) | [`unicodefyi`](https://pypi.org/project/unicodefyi/) | [`unicodefyi`](https://www.npmjs.com/package/unicodefyi) | Unicode character lookup, 17 encodings + search |
| [fontfyi](https://fontfyi.com/) | [`fontfyi`](https://pypi.org/project/fontfyi/) | [`fontfyi`](https://www.npmjs.com/package/fontfyi) | Google Fonts metadata, CSS helpers, font pairings |
| [distancefyi](https://distancefyi.com/) | [`distancefyi`](https://pypi.org/project/distancefyi/) | [`distancefyi`](https://www.npmjs.com/package/distancefyi) | Haversine distance, bearing, travel times |
| [timefyi](https://timefyi.com/) | [`timefyi`](https://pypi.org/project/timefyi/) | [`timefyi`](https://www.npmjs.com/package/timefyi) | Timezone operations, time differences, sunrise/sunset |
| [namefyi](https://namefyi.com/) | [`namefyi`](https://pypi.org/project/namefyi/) | [`namefyi`](https://www.npmjs.com/package/namefyi) | Korean romanization, Five Elements, CJK stroke count |
| [unitfyi](https://unitfyi.com/) | [`unitfyi`](https://pypi.org/project/unitfyi/) | [`unitfyi`](https://www.npmjs.com/package/unitfyi) | Unit conversion, 220 units, 20 categories |
| [holidayfyi](https://holidayfyi.com/) | [`holidayfyi`](https://pypi.org/project/holidayfyi/) | [`holidayfyi`](https://www.npmjs.com/package/holidayfyi) | Holiday dates, Easter calculation, 100+ countries |
| [fyipedia](https://github.com/fyipedia/fyipedia) | [`fyipedia`](https://pypi.org/project/fyipedia/) | -- | Unified CLI (`fyi` command) for all 10 tools |
| **fyipedia-mcp** | [`fyipedia-mcp`](https://pypi.org/project/fyipedia-mcp/) | -- | Unified MCP server for AI assistants |

## Links

- [Model Context Protocol](https://modelcontextprotocol.io/) -- MCP specification
- [FYIPedia GitHub Organization](https://github.com/fyipedia) -- All repositories
- [fyipedia CLI](https://github.com/fyipedia/fyipedia) -- Terminal interface for all 10 tools
- [awesome-fyi](https://github.com/fyipedia/awesome-fyi) -- Curated list of FYIPedia resources
- [Source Code](https://github.com/fyipedia/fyipedia-mcp) -- MIT licensed

## License

MIT
