From e31124a317510e5a10b38074199aa2a229a7b211 Mon Sep 17 00:00:00 2001 From: Mihai Criveti Date: Tue, 27 May 2025 12:05:01 +0100 Subject: [PATCH] Add testing documentation --- docs/docs/.pages | 3 +- docs/docs/deployment/ibm-code-engine.md | 2 +- docs/docs/testing/.pages | 4 + docs/docs/testing/basic.md | 209 ++++++++++++++++++++++++ docs/docs/testing/index.md | 19 +++ docs/docs/using/clients/openwebui.md | 2 +- 6 files changed, 236 insertions(+), 3 deletions(-) create mode 100644 docs/docs/testing/.pages create mode 100644 docs/docs/testing/basic.md create mode 100644 docs/docs/testing/index.md diff --git a/docs/docs/.pages b/docs/docs/.pages index c1bea153e..ddccc7c4b 100644 --- a/docs/docs/.pages +++ b/docs/docs/.pages @@ -4,4 +4,5 @@ nav: - "๐Ÿงฐ Using": using - "๐Ÿš€ Deployment": deployment - "๐Ÿ›ก๏ธ Manage": manage - - "๐Ÿงช Development": development + - "๐Ÿ’ป Development": development + - "๐Ÿงช Testing": testing diff --git a/docs/docs/deployment/ibm-code-engine.md b/docs/docs/deployment/ibm-code-engine.md index af54fb1bb..d1b7d518d 100644 --- a/docs/docs/deployment/ibm-code-engine.md +++ b/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 diff --git a/docs/docs/testing/.pages b/docs/docs/testing/.pages new file mode 100644 index 000000000..73980a722 --- /dev/null +++ b/docs/docs/testing/.pages @@ -0,0 +1,4 @@ +title: Testing +nav: + - index.md + - basic.md diff --git a/docs/docs/testing/basic.md b/docs/docs/testing/basic.md new file mode 100644 index 000000000..3ea8dd621 --- /dev/null +++ b/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 + +--- diff --git a/docs/docs/testing/index.md b/docs/docs/testing/index.md new file mode 100644 index 000000000..5d74442a7 --- /dev/null +++ b/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. diff --git a/docs/docs/using/clients/openwebui.md b/docs/docs/using/clients/openwebui.md index 2306941b4..5f9a94a6b 100644 --- a/docs/docs/using/clients/openwebui.md +++ b/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`.