wu-sheng commented on code in PR #856: URL: https://github.com/apache/skywalking-banyandb/pull/856#discussion_r2554998474
########## docs/operation/mcp/inspector.md: ########## @@ -0,0 +1,214 @@ +# Test via Inspector Guide + +MCP Inspector is a tool for testing and debugging MCP servers. This guide explains how to use it to test the BanyanDB MCP server. + +## Prerequisites + +- MCP server set up (see [Setup Guide](setup.md)) +- BanyanDB running and accessible +- Node.js 20+ installed (for running Inspector) + +## Installation + +Install MCP Inspector globally: + +```bash +npm install -g @modelcontextprotocol/inspector +``` + +Or use it directly with npx (no installation needed): + +```bash +npx @modelcontextprotocol/inspector +``` + +## Basic Setup + +### 1. Create Configuration File + +```bash +cp example-config.json inspector-config.json +``` + +Edit `inspector-config.json` with absolute path, api key and base url. + +**Important:** Use absolute paths for the binary location. + +### 2. Start Inspector (UI Mode) + +```bash +npx @modelcontextprotocol/inspector --config inspector-config.json +``` + +This will: +- Start the MCP server +- Open a web UI at `http://localhost:6274` in your default browser +- Allow you to interactively test MCP tools + +### 3. Using the Inspector UI + +1. **View Available Tools**: The UI shows all available MCP tools (e.g., `list_resources_bydbql`) +2. **Test Queries**: Enter natural language descriptions and see the generated BydbQL queries +3. **View Results**: See the query results returned from BanyanDB +4. **Debug**: Check logs and error messages in the Inspector console + +## CLI Mode + +You can also use Inspector in CLI mode for scripting and automation: + +```bash +npx @modelcontextprotocol/inspector --cli node dist/index.js \ + -e BANYANDB_ADDRESS=localhost:17900 \ + -e LLM_API_KEY=sk-your-key-here \ + --method tools/call \ + --tool-name list_resources_bydbql \ + --tool-arg "description=Show MEASURE service_cpm_minute in sw_metricsMinute from last hour" +``` + +## Usage Examples + +The MCP server translates natural language descriptions into BydbQL queries and executes them against BanyanDB. Here's how it works: + +### Example 1: Top-N Query with Aggregation + +**Natural Language Description:** +``` +Show TOP3 MEASURE endpoint_2xx in metricsMinute from last 48 hours, AGGREGATE BY MAX and ORDER BY DESC +``` + +**Generated BydbQL Query:** +```sql +SHOW TOP 3 FROM MEASURE endpoint_2xx IN metricsMinute TIME >= '-48h' AGGREGATE BY MAX ORDER BY DESC +``` + +**Result:** +```json +{ + "dataPoints": [ + { + "timestamp": "2024-01-14T14:30:00Z", + "fields": { + "endpoint": "/api/users", + "value": 1250 + } + }, + { + "timestamp": "2024-01-14T15:15:00Z", + "fields": { + "endpoint": "/api/products", + "value": 980 + } + }, + { + "timestamp": "2024-01-14T16:00:00Z", + "fields": { + "endpoint": "/api/orders", + "value": 750 + } + } + ] +} +``` + +### Example 2: Querying a Stream + +**Natural Language Description:** +``` +Show STREAM log in recordsLog from last hour Review Comment: I preview MCP could do a little more intelligent, could you try this `list log data in last hour`. The key things are 1. I want the words more tech-irrelative 2. As we don't use the same name in different groups, mcp should have the capabilities to add group automatically. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
