Update stdio quickstart

Signed-off-by: Mihai Criveti <[email protected]>

Author: crivetimihai

docs/docs/overview/features.md

@@ -1,100 +1,168 @@
-# Features
+# ✨ Features Overview
 
-MCP Gateway offers a robust feature set for integrating and managing tools, servers, prompts, and resources under the Model Context Protocol.
+MCP Gateway is a **gateway + registry + proxy** purpose-built for the **Model Context Protocol (MCP)**. It unifies REST, MCP, and stdio worlds while
+adding auth, caching, federation, and an HTMX-powered Admin UI.
 
----
 
-## 🧠 Core Capabilities
+---
 
-- **Full MCP 2025-03-26 Protocol Support**
-  Implements all required methods: `initialize`, `ping`, `notify`, `complete`, `createMessage`, and fallback JSON-RPC.
+## 🌐 Multi-Transport Core
 
-- **Multi-Transport Support**
-  Accessible via:
+???+ abstract "Supported Transports"
 
-  - HTTP/JSON-RPC
-  - WebSocket (bi-directional with ping/pong)
-  - Server-Sent Events (SSE)
-  - stdio (for subprocess embedding)
+    | Transport | Description | Typical Use-case |
+    |-----------|-------------|------------------|
+    | **HTTP / JSON-RPC** | Low-latency request-response, default for most REST clients | Simple tool invocations |
+    | **WebSocket** | Bi-directional, full-duplex | Streaming chat or incremental tool results |
+    | **Server-Sent Events (SSE)** | Uni-directional server → client stream | LLM completions or real-time updates |
+    | **STDIO** | Local process pipes via `mcpgateway-wrapper` | Editor plugins, headless CLI clients |
 
-- **Unified Registry**
-  Maintains a centralized catalog of:
+??? example "Try it: SSE from curl"
 
-  - Tools (native or REST-adapted)
-  - Prompts (Jinja2 templates with schema validation)
-  - Resources (MIME-aware, URI-addressable)
-  - Servers (virtual or federated)
-  - Federated Gateways
+    ```bash
+    curl -N -H "Accept: text/event-stream" \
+         -H "Authorization: Bearer $TOKEN" \
+         http://localhost:4444/servers/1/sse
+    ```
 
 ---
 
-## 🌐 Federation & Discovery
+## 🌍 Federation & Discovery
+
+??? summary "Features"
+
+    * **Auto-discovery** – DNS-SD (`_mcp._tcp.local.`) or static peer list
+    * **Health checks** – fail-over + removal of unhealthy gateways
+    * **Capability sync** – merges remote tool catalogs into the local DB
+    * **Request forwarding** – automatic routing to the correct gateway
+
+??? diagram "Architecture"
+
+    ```mermaid
+    graph TD
+      subgraph Local_Gateway
+        A[MCP Gateway Core]
+      end
+      subgraph Remote_Gateway_1
+        B[Peer 1]
+      end
+      subgraph Remote_Gateway_2
+        C[Peer 2]
+      end
+      A <-- ping / register --> B
+      A <-- ping / register --> C
+    ```
 
-- Peer discovery (mDNS or explicit list)
-- Periodic health checks with failover logic
-- Transparent merging of capabilities
-- Federation timeouts, retries, and sync intervals configurable
+??? note "Configuration"
+
+    Enable or tweak discovery via `.env`:
+
+    ```env
+    FEDERATION_ENABLED=true
+    FEDERATION_DISCOVERY=true
+    FEDERATION_PEERS=https://remote.example.com
+    HEALTH_CHECK_INTERVAL=30
+    ```
 
 ---
 
-## 🛠 Tool Management
+## 🔐 Security
+
+??? tip "Auth mechanisms"
+
+    * **JWT bearer** (default, signed with `JWT_SECRET_KEY`)
+    * **HTTP Basic** for the Admin UI
+    * **Custom headers** (e.g., API keys) per tool or gateway
+
+??? info "Rate limiting"
 
-- Register tools via REST, UI, or JSON-RPC
-- Wrap any REST API, CLI command, or function
-- Supports:
+    Set `MAX_TOOL_CALLS_PER_MINUTE` to throttle abusive clients.
+    Exceeding the limit returns **HTTP 429** with a `Retry-After` header.
 
-  - JSON Schema validation
-  - Concurrency limits
-  - Rate limiting
-  - Retry policies
-  - Output filtering via JSONPath
+??? example "Generate a 24 h token"
+
+    ```bash
+    python -m mcpgateway.utils.create_jwt_token \
+      --username alice --exp 1440 --secret "$JWT_SECRET_KEY"
+    ```
 
 ---
 
-## 💬 Prompt Templates
+## 🛠 Tool & Server Registry
+
+??? success "What you can register"
+
+    | Registry | Entities | Notes |
+    |----------|----------|-------|
+    | **Tools** | Native MCP tools or wrapped REST / CLI functions | JSON Schema input validation |
+    | **Resources** | URIs for blobs, text, images | Optional SSE change notifications |
+    | **Prompts** | Jinja2 templates + multimodal content | Versioning & rollback |
+    | **Servers** | Virtual collections of tools/prompts/resources | Exposed as full MCP servers |
 
-- Jinja2-powered text blocks
-- Enforced schema (required/optional args)
-- Versioned templates with rollback
-- Used by agents and sampling calls
+??? code "REST tool example"
+
+    ```bash
+    curl -X POST -H "Authorization: Bearer $TOKEN" \
+         -H "Content-Type: application/json" \
+         -d '{
+               "name": "joke_api",
+               "url": "https://icanhazdadjoke.com/",
+               "requestType": "GET",
+               "integrationType": "REST",
+               "headers": {"Accept":"application/json"}
+             }' \
+         http://localhost:4444/tools
+    ```
 
 ---
 
-## 📦 Resource Handling
+## 🖥 Admin UI
+
+??? abstract "Built with"
 
-- URI-addressed resources
-- MIME type detection
-- LRU+TTL caching (in-memory, Redis, or DB)
-- SSE-based subscriptions to dynamic resources
+    * **FastAPI** + Jinja2 + HTMX + Alpine.js
+    * Tailwind CSS for styling
 
 ---
 
-## 📊 Observability
+## 🗄 Persistence, Caching & Observability
+
+??? info "Storage options"
 
-- Structured JSON logs
-- Log levels per route
-- `/health` endpoint with live latency stats
-- Metrics for tools, servers, prompts, and gateways
+    * **SQLite** (default dev)
+    * **PostgreSQL**, **MySQL/MariaDB**, **MongoDB** — via `DATABASE_URL`
+
+??? example "Redis cache"
+
+    ```env
+    CACHE_TYPE=redis
+    REDIS_URL=redis://localhost:6379/0
+    ```
+
+??? abstract "Observability"
+
+    * Structured JSON logs (tap with `jq`)
+    * `/metrics` – Prometheus-friendly counters (`tool_calls_total`, `gateway_up`)
+    * `/health` – readiness + dependency checks
 
 ---
 
-## 🖥 Admin Interface
+## 🧩 Dev & Extensibility
 
-- Interactive UI with full CRUD for:
+??? summary "Highlights"
 
-  - Tools
-  - Resources
-  - Prompts
-  - Servers
-  - Gateways
-  - Roots
-- Built with HTMX, Alpine.js, and Tailwind CSS
+    * **Makefile targets** – `make dev`, `make test`, `make lint`
+    * **400+ unit tests** – Pytest + HTTPX TestClient
+    * **VS Code Dev Container** – Python 3.11 + Docker/Podman CLI
+    * **Plug-in friendly** – drop-in FastAPI routers or Pydantic models
 
 ---
 
-## 🔐 Authentication & Security
+## Next Steps
+
+* **Hands-on Walk-through** → [Quick Start](quick_start.md)
+* **Deployment Guides** → [Compose](../deployment/compose.md), [K8s & Cloud](../deployment/index.md)
+* **Admin UI deep dive** → [UI Guide](ui.md)
 
-- Supports both Basic and JWT authentication
-- Bearer tokens signed with configurable secrets
-- TLS verification options
-- Optional anonymous/public mode (`AUTH_REQUIRED=false`)
+!!! success "Ready to explore"
+    With transports, federation, and security handled for you, focus on building great **MCP tools, prompts, and agents**—the gateway has your back.