Merge pull request #63 from IBM/documentation-faq

Added FAQ to docs

Author: crivetimihai

.pre-commit-config.yaml

@@ -55,7 +55,7 @@ repos:
   # the repository — including:
   #
   #   • `:contentReference`
-  #   • `[oaicite:??<digits>]` (e.g. `[oaicite:??12345]`)
+  #   • `[oaicite:??<digits>]` or filecite (e.g. `[oaicite:??12345]`)
   #   • source=chatgpt.com
   #   • Stock phrases such as
   #       – "As an AI language model"
@@ -89,7 +89,7 @@ repos:
       - id: forbid-ai-stock-phrases
         name: ❌ Forbid AI Stock Phrases
         description: Prevents common AI-generated phrases from being committed.
-        entry: '(?i)(source=chatgpt.com|turn0search0|as an ai language model|i am an ai developed by|this response was generated by|i don''t have real-time information|i don''t have access to real-time|i can''t browse the internet|i cannot browse the internet|my knowledge cutoff|my training data|i''m not able to access|i don''t have the ability to)'
+        entry: '(?i)(source=chatgpt.com|turn0search0|filecite|as an ai language model|i am an ai developed by|this response was generated by|i don''t have real-time information|i don''t have access to real-time|i can''t browse the internet|i cannot browse the internet|my knowledge cutoff|my training data|i''m not able to access|i don''t have the ability to)'
         language: pygrep
         types: [text]
         exclude: ^\.pre-commit-config\.yaml$

docs/docs/.pages

@@ -8,3 +8,4 @@ nav:
   - "🧪 Test": testing
   - "📐 Architecture": architecture
   - "📰 Media": media
+  - "❓ FAQ": faq

docs/docs/faq/index.md

@@ -0,0 +1,267 @@
+# ContextForge MCP Gateway – Frequently Asked Questions
+
+## ⚡ Quickstart
+
+???+ example "🚀 How can I install and run MCP Gateway in one command?"
+    PyPI (pipx / uvenv makes an isolated venv):
+
+    ```bash
+    # Using pipx - pip install pipx
+    pipx run mcp-contextforge-gateway
+
+    # Or uvenv - pip install uvenv (default: admin/changeme)
+    uvenv run mcp-contextforge-gateway --port 4444
+    ```
+
+    OCI image (Docker/Podman) – shares host network so localhost works:
+
+    ```bash
+    podman run --network=host -p 4444:4444 ghcr.io/ibm/mcp-context-forge:latest
+    ```
+
+???+ example "🗂️ What URLs are available for the admin interface and API docs?"
+    - Admin UI → <https://localhost:4444>
+    - Swagger → <https://localhost:4444/docs>
+    - ReDoc → <https://localhost:4444/redoc>
+
+---
+
+## 🤔 What is MCP (Model Context Protocol)?
+
+???+ info "💡 What is MCP in a nutshell?"
+    MCP is an open‑source protocol released by Anthropic in Nov 2024 that lets language models invoke external tools via a typed JSON‑RPC envelope. Community folks call it "USB‑C for AI"—one connector for many models.
+
+???+ info "🌍 Who supports MCP and what's the ecosystem like?"
+    - Supported by GitHub & Microsoft Copilot, AWS Bedrock, Google Cloud Vertex AI, IBM watsonx, AgentBee, LangChain, CrewAI and 15,000+ community servers.
+    - Contracts enforced via JSON Schema.
+    - Multiple transports (STDIO, SSE, HTTP) — still converging.
+
+---
+
+## 🧰 Media Kit
+
+???+ tip "🖼️ I want to make a social media post, where can I find samples and logos?"
+    See the provided [media kit](../media/index.md)
+
+???+ tip "📄 How do I describe the gateway in boilerplate copy?"
+    > "ContextForge MCP Gateway is an open‑source reverse‑proxy that unifies MCP and REST tool servers under a single secure HTTPS endpoint with discovery, auth and observability baked in."
+
+---
+
+## 🛠️ Installation & Configuration
+
+???+ example "🔧 What is the minimal .env setup required?"
+    ```bash
+    cp .env.example .env
+    ```
+
+    Then edit:
+
+    ```env
+    BASIC_AUTH_USER=admin
+    BASIC_AUTH_PASSWORD=changeme
+    JWT_SECRET_KEY=my-test-key
+    ```
+
+???+ example "🪛 What are some advanced environment variables I can configure?"
+    - Basic: `HOST`, `PORT`, `APP_ROOT_PATH`
+    - Auth: `AUTH_REQUIRED`, `BASIC_AUTH_*`, `JWT_SECRET_KEY`
+    - Logging: `LOG_LEVEL`, `LOG_FORMAT`, `LOG_FILE`
+    - Transport: `TRANSPORT_TYPE`, `WEBSOCKET_PING_INTERVAL`, `SSE_RETRY_TIMEOUT`
+    - Tools: `TOOL_TIMEOUT`, `MAX_TOOL_RETRIES`, `TOOL_RATE_LIMIT`, `TOOL_CONCURRENT_LIMIT`
+    - Federation: `FEDERATION_ENABLED`, `FEDERATION_PEERS`, `FEDERATION_SYNC_INTERVAL`
+
+---
+
+## 🚀 Running & Deployment
+
+???+ example "🏠 How do I run MCP Gateway locally using PyPI?"
+    ```bash
+    python -m venv .venv && source .venv/bin/activate
+    pip install mcp-contextforge-gateway
+    mcpgateway
+    ```
+
+???+ example "🐳 How do I use the provided Makefile and Docker/Podman setup?"
+    ```bash
+    make podman # or make docker
+    make podman-run-ssl # or make docker-run-ssl
+    make podman-run-ssl-host # or make docker-run-ssl-host
+    ```
+
+    Docker Compose is also available, ex: `make compose-up`.
+
+???+ example "☁️ How can I deploy MCP Gateway on Google Cloud Run, Code Engine, Kubernetes, AWS, etc?"
+    See the [Deployment Documentation](../deployment/index.md) for detailed deployment instructions across local, docker, podman, compose, AWS, Azure, GCP, IBM Cloud, Helm, Minikube, Kubernetes, OpenShift and more.
+
+---
+
+## 💾 Databases & Persistence
+
+???+ info "🗄️ What databases are supported for persistence?"
+    - SQLite (default) - used for development / small deployments.
+    - PostgreSQL / MySQL / MariaDB via `DATABASE_URL`
+    - Redis (optional) for high performance session management. Sessions can also be stored in the DB or memory.
+    - Other databases supported by SQLAlchemy.
+
+???+ info "📦 How do I persist SQLite across container restarts?"
+    Include a persistent volume with your container or Kubernetes deployment. Ex:
+
+    ```bash
+    docker run -v $(pwd)/data:/app ghcr.io/ibm/mcp-context-forge:latest
+    ```
+
+    For production use, we recommend PostgreSQL. A Docker Compose target with PostgreSQL and Redis is provided.
+
+---
+
+## 🔐 Security & Auth
+
+???+ danger "🆓 How do I disable authentication for development?"
+    Set `AUTH_REQUIRED=false` — disables login for local testing.
+
+???+ example "🔑 How do I generate and use a JWT token?"
+    ```bash
+    export MCPGATEWAY_BEARER_TOKEN=$(python -m mcpgateway.utils.create_jwt_token -u admin -exp 0 --secret my-test-key)
+    curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" https://localhost:4444/tools
+    ```
+
+    The token is used for all API interactions and can be configured to expire using `-exp`.
+
+???+ example "🛡️ How do I enable TLS and configure CORS?"
+    - Use `make podman-run-ssl` for self-signed certs or drop your own certificate under `certs`.
+    - Set `ALLOWED_ORIGINS` or `CORS_ENABLED` for CORS headers.
+
+---
+
+## 📡 Tools, Servers & Federation
+
+???+ example "➕ How do I register a tool with the gateway?"
+    ```bash
+    curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \\
+         -H "Content-Type: application/json" \\
+         -d '{"name":"clock_tool","url":"http://localhost:9000/rpc","input_schema":{"type":"object"}}' \\
+         http://localhost:4444/tools
+    ```
+
+???+ example "🌉 How do I add a peer MCP gateway?"
+    A "Gateway" is another MCP Server. The MCP Gateway itself is an MCP Server. This means you can add any MCP Server under "Gateways" and it will retrieve Tools/Resources/Prompts.
+
+    ```bash
+    curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \\
+         -d '{"name":"peer","url":"http://peer:4444"}' \\
+         http://localhost:4444/gateways
+    ```
+
+???+ example "🖇️ What are virtual servers and how do I use them?"
+    A Virtual Server is a MCP Server composed from Tools/Resources/Prompts from multiple servers. Add one or more MCP Servers under "Gateways", then select which Tools/Prompts/Resources to use to create your Virtual Server.
+
+---
+
+## 🏎️ Performance Tuning & Scaling
+
+???+ example "⚙️ What environment variables affect performance?"
+    - `TOOL_CONCURRENT_LIMIT`
+    - `TOOL_RATE_LIMIT`
+    - `WEBSOCKET_PING_INTERVAL`
+    - `SSE_RETRY_TIMEOUT`
+
+???+ example "🧵 How do I scale the number of worker processes?"
+    - `GUNICORN_WORKERS` (for Gunicorn)
+    - `UVICORN_WORKERS` (for Uvicorn)
+
+???+ example "📊 How can I benchmark performance?"
+    Use `ab` or `wrk` against `/health` to measure raw latency.
+    Check out the detail performance testing harness under `tests/hey`.
+
+---
+
+## 📈 Observability & Logging
+
+???+ example "🔍 What metrics are available?"
+    - Prometheus-style `/metrics` endpoint
+    - Tool/server/prompt stats via Admin UI
+
+???+ example "📜 What log formats are supported?"
+    - `LOG_FORMAT=json` or `text`
+    - Adjust with `LOG_LEVEL`
+
+---
+
+## 🧪 Smoke Tests & Troubleshooting
+
+???+ example "🛫 Is there a full test script I can run?"
+    Yes — see `docs/basic.md`.
+
+???+ example "🚨 What common errors should I watch for?"
+    | Symptom               | Resolution                             |
+    |-----------------------|----------------------------------------|
+    | 401 Unauthorized      | Refresh token / check Authorization    |
+    | database is locked    | Use Postgres / increase DB_POOL_SIZE   |
+    | already exists errors | Use *Show inactive* toggle in UI       |
+    | SSE drops every 30 s  | Raise `SSE_RETRY_TIMEOUT`              |
+
+---
+
+## 💻 Integration Recipes
+
+???+ example "🦜 How do I use MCP Gateway with LangChain?"
+    ```python
+    from langchain.tools import MCPTool
+    tool = MCPTool(endpoint="https://localhost:4444/json-rpc",
+                   token=os.environ["MCPGATEWAY_BEARER_TOKEN"])
+    ```
+
+???+ example "🦾 How do I connect GitHub's mcp-server-git via SuperGateway?"
+    ```bash
+    npx -y supergateway --stdio "uvx run mcp-server-git"
+    ```
+
+---
+
+## 🗺️ Roadmap
+
+???+ info "🧭 What features are planned for future versions?"
+    - 🔐 OAuth2 client-credentials upstream auth with full spec compliance
+    - [🌙 Dark-mode UI](https://github.com/IBM/mcp-context-forge/issues/26)
+    - [🧾 Add "Version and Environment Info" tab to Admin UI](https://github.com/IBM/mcp-context-forge/issues/25)
+    - 🔒 Fine-grained role-based access control (RBAC) for Admin UI and API routes and per-virtual-server API keys
+    - 📦 Marketplace-style tool catalog with categories, tags, and search
+    - 🔁 Support for long-running / async tool executions with polling endpoints
+    - 📂 UI-driven prompt and resource file management (upload/edit from browser)
+    - 🛠️ Visual "tool builder" UI to design new tools with schema and auth interactively
+    - 🧪 Auto-validation tests for registered tools (contract + mock invocation)
+    - 🚨 Event subscription framework: trigger hooks or alerts on Gateway changes
+    - 🧵 Real-time tool logs and debug traces in Admin UI
+    - 🧠 Adaptive routing based on tool health, model, or load
+    - 🔍 Filterable tool invocation history with replay support
+    - 📡 Plugin-based architecture for custom transports or auth methods
+
+    [Check out the Feature issues](https://github.com/IBM/mcp-context-forge/issues?q=is%3Aissue%20state%3Aopen%20label%3Aenhancement) tagged `enhancement` on GitHub for more upcoming features!
+
+---
+
+## ❓ Rarely Asked Questions (RAQ)
+
+???+ example "🐙 Does MCP Gateway work on a Raspberry Pi?"
+    Yes — build as `arm64` and reduce RAM/workers.
+
+---
+
+## 🤝 Contributing & Community
+
+???+ tip "👩‍💻 How can I file issues or contribute?"
+    Use [GitHub Issues](https://github.com/IBM/mcp-context-forge/issues) and `CONTRIBUTING.md`.
+
+???+ tip "🧑‍🎓 What code style and CI tools are used?"
+    - Pre-commit: `ruff`, `black`, `mypy`, `isort`
+    - Run `make lint` before PRs
+
+???+ tip "💬 Where can I chat or ask questions?"
+    Join the [GitHub Discussions board](https://github.com/IBM/mcp-context-forge/discussions).
+
+---
+
+### 🙋 Need more help?
+
+Open an [Issue](https://github.com/IBM/mcp-context-forge/issues) or [discussion](https://github.com/IBM/mcp-context-forge/discussions) on GitHub.