@letoribo/mcp-graphql-enhanced 3.2.1 → 3.3.0

package/README.md

@@ -4,6 +4,7 @@ An **enhanced MCP (Model Context Protocol) server for GraphQL** that fixes real-
 > Drop-in replacement for `mcp-graphql` — with dynamic headers, robust variables parsing, and zero breaking changes.
 
 ## ✨ Key Enhancements
+* ✅ **Built-in GraphiQL IDE** — Visual playground at http://localhost:MCP_PORT/ (or /graphiql) with pre-configured headers.
 * ✅ **Dual Transport** — Supports both **STDIO** (for local CLI/client tools) and **HTTP/JSON-RPC** (for external/browser clients).
 * ✅ **Dynamic headers** — pass `Authorization`, `X-API-Key`, etc., via tool arguments (no config restarts)
 * ✅ **Robust variables parsing** — fixes `“Query variables must be a null or an object”` error
@@ -12,6 +13,11 @@ An **enhanced MCP (Model Context Protocol) server for GraphQL** that fixes real-
 * ✅ **Secure by default** — mutations disabled unless explicitly enabled
 
 ---
+## 🎨 Visual Command Center (GraphiQL)
+Unlike standard MCP servers, this one provides a visual interface for humans. When running with `ENABLE_HTTP=true`, you can open a full-featured **GraphiQL IDE** in your browser.
+
+* **Endpoint:** `http://localhost:6274/` (or `/graphiql`)
+* **Header Sync:** Any headers set in your environment (like GitHub tokens) are automatically injected into the GraphiQL "Headers" tab for immediate testing.
 
 ## 💻 HTTP / Dual Transport
 
@@ -21,6 +27,7 @@ This allows external systems, web applications, and direct `curl` commands to ac
 
 | **Endpoint** | **Method** | **Description** |
 | :--- | :--- | :--- |
+| `/graphiql` | `GET` | Human Interface: The visual GraphQL IDE. |
 | `/mcp` | `POST` | The main JSON-RPC 2.0 endpoint for tool execution. |
 | `/health` | `GET` | Simple health check, returns `{ status: 'ok' }`. |
 
@@ -46,21 +53,21 @@ curl http://localhost:6274/health
 # Example: Test the query tool via JSON-RPC (using port 6275 if 6274 was busy)
 curl -X POST http://localhost:6275/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"query-graphql","params":{"query":"query { __typename }"},"id":1}'
 
-## 🔍 Filtered Introspection (New!)
+## 🔍 Filtered Introspection
 Avoid 50k-line schema dumps. Ask for only what you need:
-```@introspect-schema typeNames ["Query", "User"]```
+`@introspect-schema typeNames ["Query", "User"]`
 ## 🔍 Debug & Inspect
 Use the official MCP Inspector to test your server live:
 ```bash
 npx @modelcontextprotocol/inspector \
   -e ENDPOINT=https://api.example.com/graphql \
-  npx @letoribo/mcp-graphql-enhanced --debug
+  npx @letoribo/mcp-graphql-enhanced
 ```
 ### Environment Variables (Breaking change in 1.0.0)
 > **Note:** As of version 1.0.0, command line arguments have been replaced with environment variables.
 
 | Environment Variable | Description | Default |
-|----------|-------------|---------|
+| :--- | :--- | :--- |
 | `ENDPOINT` | GraphQL endpoint URL | `https://mcp-neo4j-discord.vercel.app/api/graphiql` |
 | `HEADERS` | JSON string containing headers for requests | `{}` |
 | `ALLOW_MUTATIONS` | Enable mutation operations (disabled by default) | `false` |
@@ -93,6 +100,13 @@ npx @letoribo/mcp-graphql-enhanced
 MCP_PORT=8080 npx @letoribo/mcp-graphql-enhanced
 # Disable HTTP transport (fastest, recommended for Claude Desktop)
 ENABLE_HTTP=false npx @letoribo/mcp-graphql-enhanced
+# Test the surgical precision and the IDE immediately:
+ENDPOINT=https://api.github.com/graphql \
+HEADERS='{"Authorization":"Bearer YOUR_GITHUB_TOKEN"}' \
+ENABLE_HTTP=true \
+npx @letoribo/mcp-graphql-enhanced
+
+# Then visit http://localhost:6274/graphiql
 ```
 ### 🖥️ Claude Desktop Configuration Examples
 You can connect Claude Desktop to your GraphQL API using either the npx package (recommended for simplicity) or the Docker image (ideal for reproducibility and isolation).

package/dist/helpers/graphiql.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Renders the GraphiQL IDE template with visible headers
+ * @param endpoint The GraphQL API endpoint to connect to
+ * @param headers Optional default headers to inject into the editor
+ */
+export declare function renderGraphiQL(endpoint: string, headers?: object): string;
+//# sourceMappingURL=graphiql.d.ts.map

package/dist/helpers/graphiql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphiql.d.ts","sourceRoot":"","sources":["../../src/helpers/graphiql.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAAW,GAAG,MAAM,CAoE7E"}

package/dist/helpers/graphiql.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderGraphiQL = renderGraphiQL;
+/**
+ * Renders the GraphiQL IDE template with visible headers
+ * @param endpoint The GraphQL API endpoint to connect to
+ * @param headers Optional default headers to inject into the editor
+ */
+function renderGraphiQL(endpoint, headers = {}) {
+    // Stringify headers for the injection into the script
+    const stringifiedHeaders = JSON.stringify(headers, null, 2);
+    return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>GraphiQL Explorer | Surgical MCP</title>
+    <link href="https://unpkg.com/graphiql@3.8.2/graphiql.min.css" rel="stylesheet" />
+    <style>
+        body { 
+            margin: 0; 
+            height: 100vh; 
+            width: 100vw; 
+            overflow: hidden; 
+            background: #0b1016; 
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+        }
+        #graphiql { height: 100vh; }
+        .loading-screen { 
+            color: white; 
+            display: flex; 
+            justify-content: center; 
+            align-items: center; 
+            height: 100%; 
+            font-size: 1.2rem;
+        }
+    </style>
+</head>
+<body>
+    <div id="graphiql">
+        <div class="loading-screen">Initializing Surgical GraphiQL...</div>
+    </div>
+
+    <script src="https://unpkg.com/react@18.2.0/umd/react.production.min.js" crossorigin referrerpolicy="no-referrer"></script>
+    <script src="https://unpkg.com/react-dom@18.2.0/umd/react-dom.production.min.js" crossorigin referrerpolicy="no-referrer"></script>
+    <script src="https://unpkg.com/graphiql@3.8.2/graphiql.min.js" crossorigin referrerpolicy="no-referrer"></script>
+
+    <script>
+        window.addEventListener('load', function() {
+            if (typeof GraphiQL !== 'undefined') {
+                const fetcher = GraphiQL.createFetcher({ 
+                    url: '${endpoint}'
+                });
+                
+                const root = ReactDOM.createRoot(document.getElementById('graphiql'));
+                root.render(
+                    React.createElement(GraphiQL, { 
+                        fetcher: fetcher,
+                        headerEditorEnabled: true,
+                        shouldPersistHeaders: true,
+                        // This makes the headers visible in the UI tab
+                        defaultHeaders: \`${stringifiedHeaders}\`,
+                        theme: 'dark',
+                        defaultEditorToolsVisibility: true
+                    })
+                );
+            } else {
+                document.getElementById('graphiql').innerHTML = 
+                    '<div class="loading-screen" style="color: #ff4d4d">Error: GraphiQL SDK failed to load.</div>';
+            }
+        });
+    </script>
+</body>
+</html>`;
+}

package/dist/index.js

@@ -9,6 +9,7 @@ const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const language_1 = require("graphql/language");
 const zod_1 = __importDefault(require("zod"));
+const graphiql_js_1 = require("./helpers/graphiql.js");
 // Helper imports
 const deprecation_js_1 = require("./helpers/deprecation.js");
 const introspection_js_1 = require("./helpers/introspection.js");
@@ -164,6 +165,12 @@ async function handleHttpRequest(req, res) {
         return;
     }
     const url = new URL(req.url || '', `http://${req.headers.host}`);
+    // NEW FEATURE: Web GUI for Humans
+    if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/graphiql')) {
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        // Pass env.HEADERS to the explorer
+        return res.end((0, graphiql_js_1.renderGraphiQL)(env.ENDPOINT, env.HEADERS));
+    }
     if (url.pathname === '/mcp' && req.method === 'POST') {
         let body = '';
         req.on('data', chunk => { body += chunk; });
@@ -201,6 +208,8 @@ async function main() {
         const serverHttp = node_http_1.default.createServer(handleHttpRequest);
         serverHttp.listen(env.MCP_PORT, () => {
             console.error(`[HTTP] Server started on http://localhost:${env.MCP_PORT}`);
+            console.error(`🎨 GraphiQL IDE: http://localhost:${env.MCP_PORT}/graphiql`);
+            console.error(`🤖 MCP Endpoint: http://localhost:${env.MCP_PORT}/mcp\n`);
         });
     }
     const transport = new stdio_js_1.StdioServerTransport();

package/package.json

@@ -50,5 +50,5 @@
 		"tsx": "^4.21.0",
 		"typescript": "5.8.3"
 	},
-	"version": "3.2.1"
+	"version": "3.3.0"
 }