Update mcpgateway.wrapper docs

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

Author: crivetimihai

.github/ISSUE_TEMPLATE/bug-report-code.md

@@ -17,7 +17,7 @@ Select the area of the project impacted:
 
 - [ ] `mcpgateway` - API
 - [ ] `mcpgateway` - UI (admin panel)
-- [ ] `mcpgateway-wrapper` - stdio wrapper
+- [ ] `mcpgateway.wrapper` - stdio wrapper
 - [ ] Federation or Transports
 - [ ] CLI, Makefiles, or shell scripts
 - [ ] Container setup (Docker/Podman/Compose)

DEVELOPING.md

@@ -1,28 +1,58 @@
-## Development Testing with MCP Inspector
+# Development Quick-Start
 
-```
+## 🧪 Development Testing with **MCP Inspector**
+
+```bash
+# Gateway & auth
 export MCP_GATEWAY_BASE_URL=http://localhost:4444
 export MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1
-export MCP_AUTH_TOKEN="your_bearer_token"
+export MCP_AUTH_TOKEN="<your_bearer_token>"
+```
 
+| Mode                                                        | Command                                                                      | Notes                                                                         |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| **SSE (direct)**                                            | `npx @modelcontextprotocol/inspector`                                        | Connects straight to the Gateway's SSE endpoint.                              |
+| **Stdio wrapper** <br/>*(for clients that can't speak SSE)* | `npx @modelcontextprotocol/inspector python -m mcpgateway.wrapper`           | Spins up the wrapper **in-process** and points Inspector to its stdio stream. |
+| **Stdio wrapper via uv / uvenv**                            | `npx @modelcontextprotocol/inspector uvenv run python -m mcpgateway.wrapper` | Uses the lightning-fast `uv` virtual-env if installed.                        |
 
-npx @modelcontextprotocol/inspector # SSE
-npx @modelcontextprotocol/inspector uv --directory "/home/cmihai/mcpgateway-wrapper" run mcpgateway-wrapper # wrapper
-```
+🔍 MCP Inspector boots at **[http://localhost:5173](http://localhost:5173)** – open it in a browser and add:
 
-🔍 MCP Inspector is up and running at http://localhost:5173 🚀
+```text
+Server URL: http://localhost:4444/servers/1/sse
+Headers:    Authorization: Bearer <your_bearer_token>
+```
 
+---
 
-## SuperGateway
+## 🌉 SuperGateway (stdio-in ⇢ SSE-out bridge)
 
-Supergateway runs a MCP stdio-based servers over SSE (Server-Sent Events) with one command. This is useful for remote access, debugging, or connecting to SSE-based clients when your MCP server only speaks stdio.
+SuperGateway lets you expose *any* MCP **stdio** server over **SSE** with a single command – perfect for
+remote debugging or for clients that only understand SSE.
 
-`npx -y supergateway --stdio "uvx run mcp-server-git"``
-or
-```
+```bash
+# Using uvx (ships with uv)
+npx -y supergateway --stdio "uvx run mcp-server-git"
+# OR: using uvenv (pip-based)
 pip install uvenv
 npx -y supergateway --stdio "uvenv run mcp-server-git"
 ```
 
-SSE endpoint: GET http://localhost:8000/sse
-POST messages: POST http://localhost:8000/message
+| Endpoint                 | Method | URL                                                            |
+| ------------------------ | ------ | -------------------------------------------------------------- |
+| **SSE stream**           | `GET`  | [http://localhost:8000/sse](http://localhost:8000/sse)         |
+| **Message back-channel** | `POST` | [http://localhost:8000/message](http://localhost:8000/message) |
+
+Combine this with the Gateway:
+
+```bash
+# Register the SuperGateway SSE endpoint as a peer
+curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
+     -H "Content-Type: application/json" \
+     -d '{"name":"local-supergateway","url":"http://localhost:8000/sse"}' \
+     http://localhost:4444/gateways
+```
+
+The tools hosted by **`mcp-server-git`** are now available in the Gateway catalog, and therefore
+also visible through `mcpgateway.wrapper` or any other MCP client.
+
+```

README.md

@@ -206,7 +206,7 @@ docker run --rm -i \
   python3 -m mcpgateway.wrapper
 ```
 
-**Testing `mcpgateway-wrapper` by hand:**
+**Testing `mcpgateway.wrapper` by hand:**
 
 Because the wrapper speaks JSON-RPC over stdin/stdout, you can interact with it using nothing more than a terminal or pipes.
 
@@ -221,7 +221,8 @@ export MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1
 python3 -m mcpgateway.wrapper
 ```
 
-**Initialize the protocol:**
+<details>
+<summary><strong>Initialize the protocol</strong></summary>
 
 ```json
 # Initialize the protocol
@@ -243,7 +244,10 @@ python3 -m mcpgateway.wrapper
 {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_current_time","arguments":{"timezone":"Europe/Dublin"}}}
 ```
 
-Expected:
+</details>
+
+<details>
+<summary><strong>Expected responses from mcpgateway.wrapper</strong></summary>
 
 ```json
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","capabilities":{"experimental":{},"prompts":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"tools":{"listChanged":false}},"serverInfo":{"name":"mcpgateway-wrapper","version":"0.1.0"}}}
@@ -256,9 +260,9 @@ Expected:
 
 # Running the time tool:
 {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{'content': [{'type': 'text', 'text': '{\\n  \"timezone\": \"Europe/Dublin\",\\n  \"datetime\": \"2025-06-08T21:47:07+01:00\",\\n  \"is_dst\": true\\n}'}], 'is_error': False}"}],"isError":false}}
-
 ```
 
+</details>
 
 ### 🧩 Running from an MCP Client (`mcpgateway.wrapper`)
 
@@ -341,7 +345,7 @@ pipx install uv
 uv venv ~/.venv/mcpgateway
 source ~/.venv/mcpgateway/bin/activate
 
-# Install the gateway package very quickly
+# Install the gateway package very quicmcpkly
 uv pip install mcp-contextforge-gateway
 
 # Launch wrapper
@@ -552,7 +556,10 @@ A `make compose-up` target is provided along with a [docker-compose.yml](docker-
 
 > ⚠️ If any required `.env` variable is missing or invalid, the gateway will fail fast at startup with a validation error via Pydantic.
 
-You can get started by copying the provided `.env.examples` to `.env` and making the necessary edits to fit your environment.
+You can get started by copying the provided [.env.examples](.env.example) to `.env` and making the necessary edits to fit your environment.
+
+<details>
+<summary><strong>🔧 Environment Configuration Variables</strong></summary>
 
 ### Basic
 
@@ -710,6 +717,8 @@ You can get started by copying the provided `.env.examples` to `.env` and making
 | `RELOAD`   | Auto-reload on changes | `false` | bool    |
 | `DEBUG`    | Debug logging          | `false` | bool    |
 
+</details>
+
 ---
 
 ## Running
@@ -1174,6 +1183,9 @@ make lint            # Run lint tools
 
 ## Project Structure
 
+<details>
+<summary><strong>📁 Directory and file structure for mcpgateway</strong></summary>
+
 ```bash
 # ────────── CI / Quality & Meta-files ──────────
 ├── .bumpversion.cfg                # Automated semantic-version bumps
@@ -1346,6 +1358,8 @@ make lint            # Run lint tools
 │   └── unit/…                      # Pure unit tests for business logic
 ```
 
+</details>
+
 ---
 
 ## API Documentation
@@ -1358,7 +1372,10 @@ make lint            # Run lint tools
 
 ## Makefile targets
 
-This project offer the following Makefile targets. Type `make` in the project root to show all targets:
+This project offer the following Makefile targets. Type `make` in the project root to show all targets.
+
+<details>
+<summary><strong>🔧 Available Makefile targets</strong></summary>
 
 ```bash
 🐍 MCP CONTEXT FORGE  (An enterprise-ready Model Context Protocol Gateway)
@@ -1540,6 +1557,7 @@ devpi-clean          - Full cycle: build → upload → install locally
 devpi-status         - Show devpi server status
 devpi-web            - Open devpi web interface
 ```
+</details>
 
 ## Contributing
 

docs/docs/using/clients/claude-desktop.md

@@ -1,71 +1,107 @@
-# Claude Desktop
+# Claude Desktop × MCP Gateway
 
-[Claude Desktop](https://www.anthropic.com/index/claude-desktop) is a desktop application that supports MCP integration via stdio. You can configure it to launch `mcpgateway-wrapper`, enabling Claude to access all tools registered in MCP Gateway.
+[Claude Desktop](https://www.anthropic.com/index/claude-desktop) can launch a local **stdio**
+process for every chat "backend".
+By pointing it at **`mcpgateway.wrapper`** you give Claude instant access to every tool,
+prompt and resource registered in your Gateway.
 
 ---
 
-## 🖥️ Where to Configure
+## 📂 Where to edit the config
 
-Depending on your OS, edit the Claude configuration file:
-
-- **macOS**:
-  `~/Library/Application Support/Claude/claude_desktop_config.json`
-
-- **Windows**:
-  `%APPDATA%/Claude/claude_desktop_config.json`
+| OS | Path |
+|----|------|
+| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |
+| **Linux (Flatpak / AppImage)** | `$HOME/.config/Claude/claude_desktop_config.json` |
 
 ---
 
-## ⚙️ Example Configuration
-
-Add this block to the `"mcpServers"` section of your config:
-
-```json
-"mcpServers": {
-  "mcpgateway-wrapper": {
-    "command": "uv",
-    "args": [
-      "--directory",
-      "/path/to/mcpgateway-wrapper",
-      "run",
-      "mcpgateway-wrapper"
-    ],
-    "env": {
-      "MCP_GATEWAY_BASE_URL": "http://localhost:4444",
-      "MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/2",
-      "MCP_AUTH_TOKEN": "your_bearer_token"
+## ⚙️ Minimal JSON block
+
+```jsonc
+{
+  "mcpServers": {
+    "mcpgateway-wrapper": {
+      "command": "python3",
+      "args": ["-m", "mcpgateway.wrapper"],
+      "env": {
+        "MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/1",
+        "MCP_AUTH_TOKEN": "<YOUR_JWT_TOKEN>",
+        "MCP_TOOL_CALL_TIMEOUT": "120"
+      }
     }
   }
 }
 ```
 
-> 🔁 Adjust `path/to/mcpgateway-wrapper` and server ID as needed.
+> *Use the real server ID instead of `1` and paste your bearer token.*
 
 ---
 
-## 🧪 Test it in Claude
-
-Once Claude launches:
+### 🐳 Docker alternative
+
+```jsonc
+{
+  "command": "docker",
+  "args": [
+    "run", "--rm", "--network=host", "-i",
+    "-e", "MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1",
+    "-e", "MCP_AUTH_TOKEN=<YOUR_JWT_TOKEN>",
+    "ghcr.io/ibm/mcp-context-forge:latest",
+    "python3", "-m", "mcpgateway.wrapper"
+  ]
+}
+```
 
-1. Choose the `mcpgateway-wrapper` backend
-2. Type a tool invocation (e.g., `weather`, `hello`, etc.)
-3. The tool should be fetched from the Gateway and executed dynamically
+*(Mac / Windows users should replace `localhost` with `host.docker.internal`.)*
 
 ---
 
-## 🚀 Advanced: Pre-installed Wrapper Mode
+### ⚡ pipx / uvx one-liner (wrapper already installed)
 
-If you've published the wrapper to PyPI or have it globally installed:
+If you installed the package globally:
 
-```json
-"mcpServers": {
-  "mcpgateway-wrapper": {
-    "command": "uvx",
-    "args": ["mcpgateway-wrapper"]
+```jsonc
+{
+  "command": "pipx",
+  "args": ["run", "python3", "-m", "mcpgateway.wrapper"],
+  "env": {
+    "MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/1",
+    "MCP_AUTH_TOKEN": "<YOUR_JWT_TOKEN>"
   }
 }
 ```
 
-This assumes your environment variables are managed globally or set in the terminal session launching Claude.
+---
+
+## 🧪 Smoke-test inside Claude
+
+1. **Restart** Claude Desktop (quit from system-tray).
+2. Select **"mcpgateway-wrapper"** in the chat dropdown.
+3. Type:
+
+   ```
+   #get_current_time { "timezone": "Europe/Dublin" }
+   ```
+4. The wrapper should proxy the call → Gateway → tool → chat reply.
+
+If tools don't appear, open *File ▸ Settings ▸ Developer ▸ View Logs* to see wrapper output.
+
+---
+
+## 🔑 Environment variables recap
+
+| Var                       | Purpose                                           |
+| ------------------------- | ------------------------------------------------- |
+| `MCP_SERVER_CATALOG_URLS` | One or more `/servers/{id}` endpoints (comma-sep) |
+| `MCP_AUTH_TOKEN`          | JWT bearer for Gateway auth                       |
+| `MCP_TOOL_CALL_TIMEOUT`   | Per-tool timeout (seconds, optional)              |
+| `MCP_WRAPPER_LOG_LEVEL`   | `DEBUG`, `INFO`, `OFF` (optional)                 |
+
+You can place them:
+
+* under `"env"` in the **mcpServers** block (preferred)
+* in your user/environment shell before launching Claude.
 
 ---