README.md

---
title: Hieroglyph Mcp Server
emoji: 👁
colorFrom: gray
colorTo: yellow
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false
short_description: Detect and classify hieroglyphs to its Gardiner code
tags:
  - building-mcp-track-creative
  - mcp-server
---


# 𓀀 Egyptian Hieroglyph Detector (MCP Server)

Welcome to our submission for the MCP Hackathon (Track 1: Building MCP)!

This project bridges the gap between ancient history and modern AI Agents.  
It provides an MCP Server that allows Claude Desktop to "see" and identify Gardiner's Egyptian Hieroglyphs in any image.

---

## 🎥 Demo Video

(Replace **YOUR_VIDEO_ID** in the link above with your actual YouTube video ID)

---

## 🚨🌍 IMPORTANT NOTICE FOR HACKATHON 🤖

We are participating in the Creative Track (**building-mcp-track-creative**) because this tool unlocks new cultural and educational capabilities for AI agents.

**🔗 Social Media Post:**  
[Link to your X/LinkedIn Post Here]

---

## 🌐 Project Overview

This is not just a standard object detector.  
It is a **Hybrid Security Architecture** designed for the Model Context Protocol:

### **🔓 Public Interface**
An open MCP endpoint hosted on Hugging Face Spaces that anyone can connect to.

### **🔐 Private Intelligence**
The core intelligence (a fine-tuned YOLOv8 model) is hosted in a **Private Repository**.  
The Space acts as a secure proxy, authenticating with a secret token to load the weights without exposing them to the public.

### **🛡️ Secure Bridge**
We built a custom **Upload Helper** tool that allows Claude Desktop to securely transfer local files from your computer to the cloud server for analysis.

---

## 🗂️ Capabilities & Tools

When connected to Claude, this server exposes **two powerful tools**:

### **1. `detect_hieroglyphs` (The AI Eye)**

- **Purpose:** Takes an image input and performs object detection for Egyptian Hieroglyphs.  
- **Output:** Annotated image + JSON summary of symbol counts (e.g., `"3x Owl"`, `"1x Water"`).  
- **Model:** Custom-trained YOLOv8 model specialized on Gardiner signs.

---

### **2. `upload_file` (The Bridge)**

- **Purpose:** Solves the “local vs. cloud” problem.  
- **Function:** Uploads a local file from your machine to the Space’s temporary storage so the AI can analyze it.

---

## 🚀 How to Use (Claude Desktop)

You can connect this tool to your own Claude Desktop right now!

### **📌 Prerequisites**

- Claude Desktop installed  
- Node.js & Python  
- Gradio MCP extension:  
  ```sh
  pip install "gradio[mcp]"

### ⚙️ Configuration

Add the following JSON to your Claude Desktop configuration file.

Windows path: %APPDATA%\Claude\claude_desktop_config.json

Mac path: ~/Library/Application Support/Claude/claude_desktop_config.json

Replace C:\\Claude_Work with the actual folder where you keep images, and update the URLs if your Space address differs.