Merge pull request #4 from IBM/add-testing-docs

Add testing documentation

Author: crivetimihai

docs/docs/.pages

@@ -4,4 +4,5 @@ nav:
   - "🧰 Using": using
   - "🚀 Deployment": deployment
   - "🛡️ Manage": manage
-  - "🧪 Development": development
+  - "💻 Development": development
+  - "🧪 Testing": testing

docs/docs/deployment/ibm-code-engine.md

@@ -365,7 +365,7 @@ ibmcloud ce secret create --name mcpgw-redis-url \
 ibmcloud ce application update --name "$IBMCLOUD_CODE_ENGINE_APP" \
     --env-from-secret mcpgw-redis-url \
     --env CACHE_TYPE=redis
-````
+```
 
 ### Choosing the right Redis size
 

docs/docs/testing/.pages

@@ -0,0 +1,4 @@
+title: Testing
+nav:
+  - index.md
+  - basic.md

docs/docs/testing/basic.md

@@ -0,0 +1,209 @@
+# MCP Gateway - Basic
+
+Test script for MCP Gateway development environments.  
+Verifies API readiness, JWT auth, Gateway/Tool/Server lifecycle, and RPC invocation.
+
+---
+
+## 🔧 Environment Setup
+
+### 0. Bootstrap `.env`
+
+```bash
+cp .env.example .env
+```
+
+---
+
+### 1. Start the Gateway
+
+```bash
+make podman podman-run-ssl
+# or
+make venv install serve-ssl
+```
+
+Gateway will listen on:
+
+* Admin UI → [https://localhost:4444/admin](https://localhost:4444/admin)
+* Swagger   → [https://localhost:4444/docs](https://localhost:4444/docs)
+* ReDoc     → [https://localhost:4444/redoc](https://localhost:4444/redoc)
+
+---
+
+## 🔑 Authentication
+
+### 2. Generate and export tokens
+
+#### Gateway JWT (for local API access)
+
+```bash
+export MCPGATEWAY_BEARER_TOKEN=$(python -m mcpgateway.utils.create_jwt_token -u admin)
+curl -k -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" https://localhost:4444/health
+```
+
+Expected: `{"status":"ok"}`
+
+#### Remote gateway token (peer)
+
+```bash
+export MY_MCP_TOKEN="sse-bearer-token-here..."
+```
+
+#### Optional: local test server token (GitHub MCP server)
+
+```bash
+export LOCAL_MCP_URL="http://localhost:8000/sse"
+export LOCAL_MCP_TOOL_URL="http://localhost:9000/rpc"
+```
+
+---
+
+### 3. Set convenience variables
+
+```bash
+export BASE_URL="https://localhost:4444"
+export AUTH_HEADER="Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN"
+export JSON="Content-Type: application/json"
+```
+
+---
+
+## 🧪 Smoke Tests
+
+### 4. Ping JSON-RPC system
+
+```bash
+curl -k -X POST $BASE_URL/protocol/ping \
+  -H "$AUTH_HEADER" -H "$JSON" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'
+```
+
+---
+
+### 5. Add a Peer Gateway
+
+```bash
+curl -k -X POST $BASE_URL/gateways \
+  -H "$AUTH_HEADER" -H "$JSON" \
+  -d '{
+        "name": "my-mcp",
+        "url": "https://link-to-remote-mcp-server/sse",
+        "description": "My MCP Servers",
+        "auth_type": "bearer",
+        "auth_token": "'"$MY_MCP_TOKEN"'"
+      }'
+```
+
+List gateways:
+
+```bash
+curl -k -H "$AUTH_HEADER" $BASE_URL/gateways
+```
+
+---
+
+### 6. Add a Tool
+
+```bash
+curl -k -X POST $BASE_URL/tools \
+  -H "$AUTH_HEADER" -H "$JSON" \
+  -d '{
+        "name": "clock_tool",
+        "url": "'"$LOCAL_MCP_TOOL_URL"'",
+        "description": "Returns current time",
+        "request_type": "POST",
+        "integration_type": "MCP",
+        "input_schema": {
+          "type": "object",
+          "properties": {
+            "timezone": { "type": "string" }
+          }
+        }
+      }'
+```
+
+---
+
+### 7. Create a Virtual Server
+
+```bash
+curl -k -X POST $BASE_URL/servers \
+  -H "$AUTH_HEADER" -H "$JSON" \
+  -d '{
+        "name": "demo-server",
+        "description": "Smoke-test virtual server",
+        "icon": "mdi-server",
+        "associatedTools": ["1"]
+      }'
+```
+
+Check:
+
+```bash
+curl -k -H "$AUTH_HEADER" $BASE_URL/servers
+```
+
+---
+
+### 8. Open an SSE stream
+
+```bash
+curl -k -N -H "$AUTH_HEADER" $BASE_URL/servers/1/sse
+```
+
+Leave running - real-time events appear here.
+
+---
+
+### 9. Invoke the Tool via RPC
+
+```bash
+curl -k -X POST $BASE_URL/rpc \
+  -H "$AUTH_HEADER" -H "$JSON" \
+  -d '{
+        "jsonrpc": "2.0",
+        "id": 99,
+        "method": "clock_tool",
+        "params": {
+          "timezone": "Europe/Dublin"
+        }
+      }'
+```
+
+Expected:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 99,
+  "result": {
+    "time": "2025-05-27T14:23:01+01:00"
+  }
+}
+```
+
+---
+
+## 🧹 Cleanup
+
+```bash
+curl -k -X DELETE -H "$AUTH_HEADER" $BASE_URL/servers/1
+curl -k -X DELETE -H "$AUTH_HEADER" $BASE_URL/tools/1
+curl -k -X DELETE -H "$AUTH_HEADER" $BASE_URL/gateways/1
+```
+
+---
+
+## ✅ Summary
+
+This smoke test validates:
+
+* ✅ Gateway JWT auth
+* ✅ Peer Gateway registration with remote bearer
+* ✅ Tool registration and RPC wiring
+* ✅ Virtual server creation
+* ✅ SSE subscription and live messaging
+* ✅ JSON-RPC invocation flow
+
+---

docs/docs/testing/index.md

@@ -0,0 +1,19 @@
+# 🧪 Testing MCP Gateway
+
+This section contains guides for testing your MCP Gateway deployment.
+
+## 🔹 Basic Smoke Test
+
+Use the [Basic Smoke Test](basic.md) to verify:
+
+- JWT token generation and authentication
+- Gateway registration
+- Tool registration
+- Server creation and event streaming
+- Tool invocation via JSON-RPC
+
+This test is ideal for validating local development environments or freshly deployed test instances.
+
+---
+
+For additional scenarios (e.g., completion APIs, multi-hop toolchains), expand the test suite as needed.

docs/docs/using/clients/openwebui.md

@@ -25,7 +25,7 @@ Start the MCP Gateway to expose its tools via OpenAPI endpoints. For example:
 
 ```bash
 uv run mcpgateway
-````
+```
 
 Ensure that the MCP Gateway is accessible at a known URL, such as `http://localhost:4444`.