MCP Agent Overview

The ZiadaPOS MCP Agent is a Python-based Model Context Protocol (MCP) server with an embedded AI agent that serves as the natural-language interface to the ZiadaPOS platform.

What It Does

• Exposes 111 MCP tools covering every aspect of shop management
• Wraps them in an ask AI agent that interprets Swahili/English queries
• Executes multi-step shop operations automatically (up to 8 tool calls per query)
• Includes a plain HTTP bridge (POST /ask) for mobile clients

Architecture

User (Swahili/English)
    │
    ▼
┌──────────────┐     ┌──────────────┐     ┌─────────────┐
│  MCP Client  │────▶│  MCP Agent   │────▶│  ZiadaPOS   │
│ (Claude/Cursor)   │  (Python)    │     │  REST API   │
└──────────────┘     └──────┬───────┘     └─────────────┘
                            │
                     ┌──────┴───────┐
                     │  Ngamia AI   │
                     │  Gateway     │
                     └──────────────┘

How It Works

1. User sends a question in Swahili or English
2. LLM (via Ngamia gateway) interprets the intent
3. Agent calls the appropriate MCP tools (which map to API endpoints)
4. API executes business logic
5. Agent formats the response and returns it

Quick Start

Local Development

cd agent
uv sync
cp .env.example .env
# Edit .env with your credentials
uv run ziada-mcp

HTTP Bridge (Mobile Clients)

curl -X POST http://localhost:8081/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "What were my sales today?"}'

MCP Client (Claude Desktop)

Add to your Claude Desktop config:

{
  "mcpServers": {
    "ziadapos": {
      "url": "http://localhost:8081/mcp"
    }
  }
}

Key Features

Transport Options