README.md · puseletso55/township-mcp-server at main

metadata

license: apache-2.0
title: Township MCP Server
sdk: gradio
emoji: 📊
colorFrom: indigo
colorTo: blue
pinned: true
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/63cd800cf712328861ab1888/moNs1-VgoT_YpJ49ZW7AL.webp
short_description: JSON-RPC API and UI for registering and discovering township
sdk_version: 5.36.2

✅ Project description
✅ Installation steps
✅ API usage with examples
✅ Gradio testing instructions
✅ Contribution, License, and Contact info

✅ `README.md`

# 🧠 Township MCP Server

This project provides a **Multimodal Command Protocol (MCP) Server** for township businesses, allowing clients to:

- ✅ Register township businesses (name, phone, location, etc.)
- ✅ Query nearby businesses using geolocation
- ✅ Interact with the server via:
  - JSON-RPC API (via Flask)
  - Web UI (via Gradio)

> 🔗 Live Gradio Demo: [puseletso55/township-mcp-server](https://puseletso55-township-mcp-server.hf.space)

---

## 📦 Project Structure

township-mcp-server/ ├── src/ │ ├── app.py # Main Flask + Gradio server │ ├── api/ │ │ └── client_predict.py # CLI tool to send JSON-RPC requests │ ├── utils/ │ │ └── api_logger.py # Logs API interactions ├── requirements.txt ├── README.md


---

## ⚙️ Installation

1. **Clone the repository**
```bash
git clone https://github.com/puseletso55/township-mcp-server.git
cd township-mcp-server

Create a virtual environment

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

Install dependencies

pip install -r requirements.txt

Set up environment variables (optional but recommended)

export MONGO_URI="your_mongo_connection_uri"

🚀 Run the Server

python src/app.py

Flask API: http://localhost:5000/run/predict
Gradio UI: http://localhost:7860

🧪 Sample JSON-RPC Requests

✅ Register a Business

{
  "jsonrpc": "2.0",
  "method": "registerBusiness",
  "params": {
    "name": "Test Business",
    "description": "Test Description",
    "address": "123 Test St",
    "phone": "1234567890",
    "latitude": "26.2041",
    "longitude": "28.0473"
  },
  "id": 1
}

✅ Get Nearby Businesses

{
  "jsonrpc": "2.0",
  "method": "getNearbyBusinesses",
  "params": {
    "latitude": "26.2041",
    "longitude": "28.0473",
    "radius_km": 10
  },
  "id": 2
}

🔁 Send these in POST to /run/predict as:

{
  "data": ["<your JSON-RPC string>"]
}

🖥️ CLI Tool Example

Run the command-line client with input:

python src/api/client_predict.py "{\"jsonrpc\": \"2.0\", \"method\": \"getNearbyBusinesses\", \"params\": {\"latitude\": \"26.2041\", \"longitude\": \"28.0473\"}, \"id\": 1}"

🧾 Logging

API interactions are logged with timestamps and colors using colorlog for better visibility.

📋 Requirements

All dependencies are listed in requirements.txt. Install using:

pip install -r requirements.txt

🤝 Contributing

Fork this repo
Create your feature branch: git checkout -b feature/my-feature
Commit your changes: git commit -m "Add feature"
Push to the branch: git push origin feature/my-feature
Submit a pull request 🚀

📄 License

📬 Contact

Developer: Puseletso Mafisa
Company: Mafisa Tech Affiliate Pty Ltd
Email: [email protected]

Made in 🇿🇦 to empower township businesses.

---

✅ README.md