Add README for mcpgateway.wrapper

crivetimihai · crivetimihai · commit 9e9be3de18e3 · 2025-06-12T11:10:38.000+01:00
Signed-off-by: Mihai Criveti &lt;crivetimihai@gmail.com&gt;
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -1,8 +1,5 @@
 # All files in the repo
 * @crivetimihai
 
-# Ownership for the mcpgateway-wrapper
-/mcpgateway-wrapper/ @crivetimihai @kevalmahajan @madhav165
-
 # Ownership for all tests
 /tests/ @crivetimihai @kevalmahajan @madhav165
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -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|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)'
+        entry: '(?i)(source=chatgpt.com|turn0search0|filecite|unchanged|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$
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,7 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ---
 
-## [0.2.0] - 2025-06-08 (pending)
+## [0.2.0] - 2025-06-15 (pending)
+
+### Added
+
+* Moved mcpgateway-wrapper to mcpgateway/wrapper.py so it can run as a Python module (python3 -m mcpgateway.wrapper)
+* Integrated version into UI. API and separate /version endpoint also available.
+* Added /ready endpoint
 
 ### Fixed
 
diff --git a/Makefile b/Makefile
@@ -342,10 +342,10 @@ lint:
 ## --------------------------------------------------------------------------- ##
 autoflake:                          ## 🧹  Strip unused imports / vars
 	@$(VENV_DIR)/bin/autoflake --in-place --remove-all-unused-imports \
-	          --remove-unused-variables -r mcpgateway mcpgateway-wrapper tests
+	          --remove-unused-variables -r mcpgateway tests
 
 black:                              ## 🎨  Reformat code with black
-	@echo "🎨  black …" && $(VENV_DIR)/bin/black -l 200 mcpgateway mcpgateway-wrapper tests
+	@echo "🎨  black …" && $(VENV_DIR)/bin/black -l 200 mcpgateway tests
 
 isort:                              ## 🔀  Sort imports
 	@echo "🔀  isort …" && $(VENV_DIR)/bin/isort .
@@ -375,19 +375,19 @@ pre-commit:                         ## 🪄  Run pre-commit hooks
 	@$(VENV_DIR)/bin/pre-commit run --all-files --show-diff-on-failure
 
 ruff:                               ## ⚡  Ruff lint + format
-	@$(VENV_DIR)/bin/ruff check mcpgateway && $(VENV_DIR)/bin/ruff format mcpgateway mcpgateway-wrapper tests
+	@$(VENV_DIR)/bin/ruff check mcpgateway && $(VENV_DIR)/bin/ruff format mcpgateway tests
 
 ty:                                 ## ⚡  Ty type checker
-	@$(VENV_DIR)/bin/ty check mcpgateway mcpgateway-wrapper tests
+	@$(VENV_DIR)/bin/ty check mcpgateway tests
 
 pyright:                            ## 🏷️  Pyright type-checking
-	@$(VENV_DIR)/bin/pyright mcpgateway mcpgateway-wrapper tests
+	@$(VENV_DIR)/bin/pyright mcpgateway tests
 
 radon:                              ## 📈  Complexity / MI metrics
-	@$(VENV_DIR)/bin/radon mi -s mcpgateway mcpgateway-wrapper tests && \
-	$(VENV_DIR)/bin/radon cc -s mcpgateway mcpgateway-wrapper tests && \
-	$(VENV_DIR)/bin/radon hal mcpgateway mcpgateway-wrapper tests && \
-	$(VENV_DIR)/bin/radon raw -s mcpgateway mcpgateway-wrapper tests
+	@$(VENV_DIR)/bin/radon mi -s mcpgateway tests && \
+	$(VENV_DIR)/bin/radon cc -s mcpgateway tests && \
+	$(VENV_DIR)/bin/radon hal mcpgateway tests && \
+	$(VENV_DIR)/bin/radon raw -s mcpgateway tests
 
 pyroma:                             ## 📦  Packaging metadata check
 	@$(VENV_DIR)/bin/pyroma -d .
@@ -444,7 +444,7 @@ sbom:								## 🛡️  Generate SBOM & security report
 
 pytype:								## 🧠  Pytype static type analysis
 	@echo "🧠  Pytype analysis…"
-	@$(VENV_DIR)/bin/pytype -V 3.12 -j auto mcpgateway mcpgateway-wrapper tests
+	@$(VENV_DIR)/bin/pytype -V 3.12 -j auto mcpgateway tests
 
 check-manifest:						## 📦  Verify MANIFEST.in completeness
 	@echo "📦  Verifying MANIFEST.in completeness…"
diff --git a/README.md b/README.md
@@ -120,6 +120,12 @@ curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/s
 # To stop the running process, you can either:
 fg # Return the process to foreground, you can not Ctrl + C, or:
 pkill mcpgateway
+
+# Optionally, test the stdio wrapper to mirror tools from the gateway:
+# This lets you connect to the gateway with tools that don't support SSE:
+export MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN}
+export MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1
+python3 -m mcpgateway.wrapper
 ```
 
 See [.env.example](.env.example) for full list of ENV variables you can use to override the configuration.
@@ -172,22 +178,35 @@ curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      http://localhost:4444/version | jq
 ```
 
-### Running the mcpgateway-wrapper
+### Running the MCP Gateway stdio wrapper
+
+The `mcpgateway.wrapper` lets you connect to the gateway over **stdio**, while retaining authentication using the JWT token when the wrapper connect to a remote gateway. You should run this from a MCP client. You can test this from a shell with:
+
+```bash
+# Set environment variables
+export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 10080 --secret my-test-key)
+export MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN}
+export MCP_SERVER_CATALOG_URLS='http://localhost:4444/servers/1'
+export MCP_TOOL_CALL_TIMEOUT=120
+export MCP_WRAPPER_LOG_LEVEL=DEBUG  # or OFF to disable logging
+
+# Run the wrapper from the installed module
+python3 -m mcpgateway.wrapper
+```
 
-The mcpgateway-wrapper lets you connect to the gateway over stdio, while retaining authentication using the JWT token when the wrapper connect to a remote gateway. You should run this from a MCP client. You can test this from a shell with:
+**Or using the container image:**
 
 ```bash
-docker run -i --name mcpgateway-wrapper \
-  --entrypoint uv \
-  -e UV_CACHE_DIR=/tmp/uv-cache \
-  -e MCP_SERVER_CATALOG_URLS=http://host.docker.internal:4444 \
+docker run --rm -i \
   -e MCP_AUTH_TOKEN=$MCPGATEWAY_BEARER_TOKEN \
+  -e MCP_SERVER_CATALOG_URLS=http://host.docker.internal:4444/servers/1 \
+  -e MCP_TOOL_CALL_TIMEOUT=120 \
+  -e MCP_WRAPPER_LOG_LEVEL=DEBUG \
   ghcr.io/ibm/mcp-context-forge:latest \
-  run --directory mcpgateway-wrapper mcpgateway-wrapper
-# You'll see a message similar to: Installed 21 packages in 6ms - it's now expecting input from an MCP client
+  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.
 
@@ -240,81 +259,135 @@ Expected:
 
 ```
 
-### Running from a MCP Client
 
-The `mcpgateway-wrapper` should be used with an MCP Client that does not support SSE. You can configure it as such.
+### 🧩 Running from an MCP Client (`mcpgateway.wrapper`)
+
+The `mcpgateway.wrapper` exposes everything your Gateway knows about over **stdio**, so any MCP client that *can't* (or *shouldn't*) open an authenticated SSE stream still gets full tool-calling power.
+
+> **Remember** to substitute your real Gateway URL (and server ID) for `http://localhost:4444/servers/1`.
+> When inside Docker/Podman, that often becomes `http://host.docker.internal:4444/servers/1` (macOS/Windows) or the gateway container's hostname (Linux).
+
+---
+
+<details>
+<summary><strong>🐳 Docker / Podman</strong></summary>
+
+```bash
+docker run -i --rm \
+  --network=host \
+  -e MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1 \
+  -e MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN} \
+  -e MCP_TOOL_CALL_TIMEOUT=120 \
+  ghcr.io/ibm/mcp-context-forge:latest \
+  python3 -m mcpgateway.wrapper
+```
+
+</details>
+
+---
+
+<details>
+<summary><strong>📦 pipx (one-liner install &amp; run)</strong></summary>
 
-Remember to replace the `MCP_SERVER_CATALOG_URL` with the actual URL of your MCP Gateway. Consider container networking - when running this via a container engine, this should represent a network accessible from Docker/Podman, ex: `http://host.docker.internal:4444/servers/1`
+```bash
+# Install gateway package in its own isolated venv
+pipx install --include-deps mcp-contextforge-gateway
+
+# Run the stdio wrapper
+MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN} \
+MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1 \
+python3 -m mcpgateway.wrapper
+```
 
-You have a number of options for running the wrapper. Docker/Podman, to run it from the container. `uvx`, `uvenv` or `pipx` to run it straight from pip. Or just running it with Python from a local directory. Adjust your command accordingly.
+**Claude Desktop JSON** (uses the host Python that pipx injected):
 
 ```json
 {
-  "servers": {
+  "mcpServers": {
     "mcpgateway-wrapper": {
-      "command": "docker",
-      "args": [
-        "run",
-        "--rm",
-        "--network=host",
-        "-i",
-        "-e",
-        "MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1",
-        "-e",
-        "MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN}",
-        "--entrypoint",
-        "uv",
-        "ghcr.io/ibm/mcp-context-forge:latest",
-        "run",
-        "--directory",
-        "mcpgateway-wrapper",
-        "mcpgateway-wrapper"
-      ],
+      "command": "python3",
+      "args": ["-m", "mcpgateway.wrapper"],
       "env": {
-        "MCPGATEWAY_BEARER_TOKEN": "${MCPGATEWAY_BEARER_TOKEN}"
+        "MCP_AUTH_TOKEN": "<your-token>",
+        "MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/1",
+        "MCP_TOOL_CALL_TIMEOUT": "120"
       }
     }
   }
 }
 ```
 
-## Quick Start (Claude Desktop)
+</details>
+
+---
+
+<details>
+<summary><strong>⚡ uv / uvenv (light-speed venvs)</strong></summary>
+
+#### 1 · Install <code>uv</code>  (<code>uvenv</code> is an alias it provides)
+
+```bash
+# (a) official one-liner
+curl -Ls https://astral.sh/uv/install.sh | sh
+
+# (b) or via pipx
+pipx install uv
+```
+
+#### 2 · Create an on-the-spot venv & run the wrapper
+
+```bash
+# Create venv in ~/.venv/mcpgateway (or current dir if you prefer)
+uv venv ~/.venv/mcpgateway
+source ~/.venv/mcpgateway/bin/activate
+
+# Install the gateway package very quickly
+uv pip install mcp-contextforge-gateway
+
+# Launch wrapper
+MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN} \
+MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1 \
+uv python -m mcpgateway.wrapper # Use this just for testing, as the Client will run the uv command
+```
+
+*(You can swap `uv python` for plain `python` if the venv is active.)*
 
-To add the mcpgateway to Claude Desktop (or similar MCP Clients) go to `File > Settings > Developer > Edit Config` and add:
+#### Claude Desktop JSON (runs through **uvenv run**)
 
 ```json
 {
   "mcpServers": {
     "mcpgateway-wrapper": {
-      "command": "docker",
+      "command": "uvenv",
       "args": [
         "run",
-        "--rm",
-        "--network=host",
-        "-i",
-        "-e",
-        "MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1",
-        "-e",
-        "MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN}",
-        "--entrypoint",
-        "uv",
-        "ghcr.io/ibm/mcp-context-forge:latest",
-        "run",
-        "--directory",
-        "mcpgateway-wrapper",
-        "mcpgateway-wrapper"
+        "--",
+        "python",
+        "-m",
+        "mcpgateway.wrapper"
       ],
       "env": {
-        "MCPGATEWAY_BEARER_TOKEN": "<place your token here>"
-      }
+        "MCP_AUTH_TOKEN": "<your-token>",
+        "MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/1"
     }
   }
 }
 ```
 
-Restart Claude Desktop (exiting from system tray). Go back to `File > Settings > Developer > Edit Config` to check on your configuration and view the logs.
+</details>
+
+---
+
+### 🚀 Using with Claude Desktop (or any GUI MCP client)
+
+1. **Edit Config** → `File ▸ Settings ▸ Developer ▸ Edit Config`
+2. Paste one of the JSON blocks above (Docker / pipx / uvenv).
+3. Restart the app so the new stdio server is spawned.
+4. Open logs in the same menu to verify `mcpgateway-wrapper` started and listed your tools.
+
+Need help? See:
 
-For more details, see the [Claude MCP quickstart](https://modelcontextprotocol.io/quickstart/server). For issues, see [MCP Debugging](https://modelcontextprotocol.io/docs/tools/debugging).
+* **MCP Debugging Guide** – [https://modelcontextprotocol.io/docs/tools/debugging](https://modelcontextprotocol.io/docs/tools/debugging)
 
 ---
 
diff --git a/mcpgateway/utils/create_jwt_token.py b/mcpgateway/utils/create_jwt_token.py
@@ -15,7 +15,7 @@
 CLI (default secret, default payload):
     $ python3 jwt_cli.py
 
-Library (unchanged API):
+Library:
 ```python
 from mcpgateway.utils.create_jwt_token import create_jwt_token, get_jwt_token
 
diff --git a/tests/unit/mcpgateway/services/test_root_service.py b/tests/unit/mcpgateway/services/test_root_service.py
@@ -39,7 +39,6 @@ async def test_add_root_with_scheme():
     # Add an HTTP URI
     uri = "http://example.com/base/path"
     root = await service.add_root(uri)
-    # Should remain unchanged
     assert root.uri == uri
     # Name should be the basename of the URL path
     assert root.name == os.path.basename(urlparse(uri).path)
