erdalgunes/ustad-protocol-mcp

Ustad Protocol MCP

"Ustad" (Turkish/Urdu: "Master/Teacher") - Minimal MCP server with sequential thinking and search

✨ Features

• 🧠 Sequential Thinking: Structured problem-solving with chain-of-thought reasoning
• 🎯 Intent Analysis: Optional OpenAI-powered intent analysis with circuit breaker pattern
• 🔍 Web Search: Tavily-powered search for fact-checking and research
• 🐳 Containerized: Production-ready Docker setup with health checks
• 📡 SSE Protocol: Real-time Server-Sent Events communication
• 🚀 FastMCP: Built on FastMCP for optimal performance
• 🔒 Secure: Non-root container user, intelligent host detection (0.0.0.0 in containers, localhost in dev)

🚀 Quick Start

Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/erdalgunes/ustad-protocol-mcp.git
cd ustad-protocol-mcp

# Configure environment
cp .env.example .env
# Edit .env and add your TAVILY_API_KEY

# Build and run
docker-compose up --build

Server will be available at http://localhost:8000

Local Development

# Install dependencies (uv is 10-100x faster than pip/poetry)
uv sync

# Set environment
export TAVILY_API_KEY=your_api_key_here

# Run server
uv run python ustad_mcp_server.py

🛠️ Tools

ustad_think

Sequential thinking for structured problem-solving with optional intent analysis:

{
  "thought": "Analyzing the problem step by step",
  "thought_number": 1,
  "total_thoughts": 5,
  "next_thought_needed": true
}

Intent Analysis Features (when OpenAI configured):

• Analyzes thought complexity and fact-checking needs
• Enforces minimum 10 thinking steps for thorough reasoning
• Circuit breaker pattern prevents cascading failures
• Automatic fallback when OpenAI unavailable

ustad_search

Web search using Tavily API:

{
  "query": "Python best practices 2024",
  "max_results": 5,
  "search_type": "general"
}

📝 Configuration

Set in .env file or environment:

🏗️ Architecture

.
├── ustad_mcp_server.py        # Main MCP server
├── src/
│   └── sequential_thinking.py # Sequential thinking logic
├── Dockerfile                 # Multi-stage Docker build
├── docker-compose.yml         # Docker Compose config
└── pyproject.toml            # Poetry dependencies

📄 License

MIT