Merge pull request #6 from IBM/update-testing-docs-and-copilot-docs

Update testing docs, copilot docs and minor fix to servers/ also offering a servers (no /) endpoint

Author: crivetimihai

DEVELOPING.md

@@ -18,7 +18,7 @@ npx @modelcontextprotocol/inspector uv --directory "/home/cmihai/mcpgateway-wrap
 
 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.
 
-`npx -y supergateway --stdio "uvx mcp-server-git"``
+`npx -y supergateway --stdio "uvx run mcp-server-git"``
 
 SSE endpoint: GET http://localhost:8000/sse
 POST messages: POST http://localhost:8000/message

docs/docs/manage/backup.md

@@ -62,8 +62,61 @@ Use a secrets manager (e.g., AWS Secrets Manager, Azure Key Vault, or Kubernetes
 Run smoke tests:
 
 ```bash
-curl http://localhost:4444/tools
-curl http://localhost:4444/prompts
+curl -s -k -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools
+curl -s -k -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/prompts
 ```
 
 You should see previously registered tools and templates.
+
+
+---
+
+## 🧬 Understanding the Database Schema
+
+MCP Gateway uses a relational database (e.g. SQLite or PostgreSQL) to persist all registered entities and track tool/server usage. When session storage is configured as `CACHE_TYPE=database`, it also persists active user sessions and streamed message content.
+
+---
+
+### Key Tables
+
+| Table | Purpose |
+|-------|---------|
+| `tools` | Stores registered tools, including schemas and auth configs |
+| `tool_metrics` | Tracks execution stats per tool (latency, success/fail) |
+| `resources` | Stores static or dynamic URI-based resources |
+| `resource_metrics` | Logs usage of resources (access count, latency, etc.) |
+| `resource_subscriptions` | Tracks SSE client subscriptions to resources |
+| `prompts` | Jinja2 prompt templates with input arguments |
+| `prompt_metrics` | Usage metrics for each prompt |
+| `servers` | Virtual servers that group tools/resources under an SSE stream |
+| `server_metrics` | Invocation stats per server |
+| `gateways` | External federated MCP servers added by the admin |
+| `mcp_sessions` | Persistent session registry when using `CACHE_TYPE=database` |
+| `mcp_messages` | Persisted streamed content (text/image/etc.) tied to sessions |
+| `*_association` tables | Many-to-many mapping between tools/resources/prompts and their servers/gateways |
+
+---
+
+### Session and Message Tables
+
+These only appear when session/messaging backend is set to `database`:
+
+- **`mcp_sessions`**: Each record is an open session ID (used for SSE streams and client context).
+- **`mcp_messages`**: Stores streamed messages (text, image, resource) linked to a session—useful for debugging or offline playback.
+
+You can query active sessions:
+
+```sql
+SELECT session_id, created_at FROM mcp_sessions ORDER BY created_at DESC;
+```
+
+Or inspect message content (JSON-encoded):
+
+```sql
+SELECT content FROM mcp_messages WHERE session_id = 'abc123';
+```
+
+---
+
+These tables are cleaned automatically when session TTLs expire, but can also be purged manually if needed.
+

docs/docs/testing/basic.md

@@ -39,7 +39,7 @@ Gateway will listen on:
 
 ```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
+curl -s -k -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" https://localhost:4444/health
 ```
 
 Expected: `{"status":"ok"}`
@@ -74,17 +74,23 @@ export JSON="Content-Type: application/json"
 ### 4. Ping JSON-RPC system
 
 ```bash
-curl -k -X POST $BASE_URL/protocol/ping \
+curl -s -k -X POST $BASE_URL/protocol/ping \
   -H "$AUTH_HEADER" -H "$JSON" \
   -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'
 ```
 
+Expected:
+
+```json
+{"jsonrpc":"2.0","id":1,"result":{}}
+```
+
 ---
 
 ### 5. Add a Peer Gateway
 
 ```bash
-curl -k -X POST $BASE_URL/gateways \
+curl -s -k -X POST $BASE_URL/gateways \
   -H "$AUTH_HEADER" -H "$JSON" \
   -d '{
         "name": "my-mcp",
@@ -98,15 +104,15 @@ curl -k -X POST $BASE_URL/gateways \
 List gateways:
 
 ```bash
-curl -k -H "$AUTH_HEADER" $BASE_URL/gateways
+curl -s -k -H "$AUTH_HEADER" $BASE_URL/gateways
 ```
 
 ---
 
 ### 6. Add a Tool
 
 ```bash
-curl -k -X POST $BASE_URL/tools \
+curl -s -k -X POST $BASE_URL/tools \
   -H "$AUTH_HEADER" -H "$JSON" \
   -d '{
         "name": "clock_tool",
@@ -128,28 +134,59 @@ curl -k -X POST $BASE_URL/tools \
 ### 7. Create a Virtual Server
 
 ```bash
-curl -k -X POST $BASE_URL/servers \
-  -H "$AUTH_HEADER" -H "$JSON" \
+curl -s -k -X POST $BASE_URL/servers/ \
+  -H "$AUTH_HEADER" -H "$JSON" -H 'accept: application/json' \
   -d '{
         "name": "demo-server",
         "description": "Smoke-test virtual server",
-        "icon": "mdi-server",
-        "associatedTools": ["1"]
+        "icon": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png",
+        "associatedTools": ["1"],
+        "associatedResources": [],
+        "associatedPrompts": []
       }'
 ```
 
+Expected:
+
+```json
+{
+  "id": 2,
+  "name": "demo-server",
+  "description": "Smoke-test virtual server",
+  "icon": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png",
+  "createdAt": "2025-05-28T04:28:38.554558",
+  "updatedAt": "2025-05-28T04:28:38.554564",
+  "isActive": true,
+  "associatedTools": [
+    1
+  ],
+  "associatedResources": [],
+  "associatedPrompts": [],
+  "metrics": {
+    "totalExecutions": 0,
+    "successfulExecutions": 0,
+    "failedExecutions": 0,
+    "failureRate": 0,
+    "minResponseTime": null,
+    "maxResponseTime": null,
+    "avgResponseTime": null,
+    "lastExecutionTime": null
+  }
+}
+```
+
 Check:
 
 ```bash
-curl -k -H "$AUTH_HEADER" $BASE_URL/servers
+curl -s -k -H "$AUTH_HEADER" $BASE_URL/servers | jq
 ```
 
 ---
 
 ### 8. Open an SSE stream
 
 ```bash
-curl -k -N -H "$AUTH_HEADER" $BASE_URL/servers/1/sse
+curl -s -k -N -H "$AUTH_HEADER" $BASE_URL/servers/1/sse
 ```
 
 Leave running - real-time events appear here.
@@ -159,12 +196,12 @@ Leave running - real-time events appear here.
 ### 9. Invoke the Tool via RPC
 
 ```bash
-curl -k -X POST $BASE_URL/rpc \
+curl -s -k -X POST $BASE_URL/rpc \
   -H "$AUTH_HEADER" -H "$JSON" \
   -d '{
         "jsonrpc": "2.0",
         "id": 99,
-        "method": "clock_tool",
+        "method": "get_current_time",
         "params": {
           "timezone": "Europe/Dublin"
         }
@@ -175,22 +212,91 @@ Expected:
 
 ```json
 {
-  "jsonrpc": "2.0",
-  "id": 99,
-  "result": {
-    "time": "2025-05-27T14:23:01+01:00"
-  }
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"timezone\": \"Europe/Dublin\",\n  \"datetime\": \"2025-05-28T05:24:13+01:00\",\n  \"is_dst\": true\n}"
+    }
+  ],
+  "is_error": false
+}
+```
+
+---
+
+### 10. Connect to GitHub MCP Tools via SuperGateway
+
+You can test the Gateway against GitHub's official `mcp-server-git` tool using [`supergateway`](https://github.com/modelcontextprotocol/supergateway).
+
+Start a temporary SSE wrapper around the GitHub MCP server:
+
+```bash
+npx -y supergateway --stdio "uvx run mcp-server-git"
+```
+
+This starts:
+
+* SSE endpoint: `http://localhost:8000/sse`
+* Message POST: `http://localhost:8000/message`
+
+To register it with the MCP Gateway:
+
+```bash
+export MY_MCP_TOKEN="optional-auth-header-if-needed"
+
+curl -s -k -X POST $BASE_URL/gateways \
+  -H "$AUTH_HEADER" -H "$JSON" \
+  -d '{
+        "name": "github-mcp",
+        "url": "http://localhost:8000/sse",
+        "description": "GitHub MCP Tools via SuperGateway",
+        "auth_type": "none"
+      }'
+```
+
+This gives you access to GitHub's MCP tools like `get_repo_issues`, `get_pull_requests`, etc.
+
+---
+
+### 11. Development Testing with MCP Inspector
+
+Launch a visual inspector to interactively test your Gateway:
+
+```bash
+npx @modelcontextprotocol/inspector
+```
+
+Once launched at [http://localhost:5173](http://localhost:5173):
+
+1. Click **"Add Server"**
+2. Use the URL for your virtual server's SSE stream:
+
+```
+http://localhost:4444/servers/1/sse
+```
+
+3. Add this header:
+
+```json
+{
+  "Authorization": "Bearer <your-jwt-token>"
 }
 ```
 
+4. Save and test tool invocations by selecting a tool and sending sample input:
+
+```json
+{ "timezone": "Europe/Dublin" }
+```
+
 ---
 
 ## 🧹 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
+curl -s -k -X DELETE -H "$AUTH_HEADER" $BASE_URL/servers/1
+curl -s -k -X DELETE -H "$AUTH_HEADER" $BASE_URL/tools/1
+curl -s -k -X DELETE -H "$AUTH_HEADER" $BASE_URL/gateways/1
 ```
 
 ---
@@ -205,5 +311,7 @@ This smoke test validates:
 * ✅ Virtual server creation
 * ✅ SSE subscription and live messaging
 * ✅ JSON-RPC invocation flow
+* ✅ Connecting MCP Inspector to the MCP Gateway
+* ✅ Connecting the official GitHub MCP server to the Gateway
 
 ---