@letoribo/mcp-graphql-enhanced 2.0.5 → 2.0.7

package/README.md

@@ -1,8 +1,7 @@
 # mcp-graphql-enhanced
 
-[![Smithery](https://smithery.ai/badge/mcp-graphql-enhanced)](https://smithery.ai/server/mcp-graphql-enhanced)
-[![Glama](https://glama.ai/mcp/servers/@letoribo/mcp-graphql-enhanced)](https://glama.ai/mcp/servers/@letoribo/mcp-graphql-enhanced)
-
+[![Smithery](https://smithery.ai/badge/@letoribo/mcp-graphql-enhanced)](https://smithery.ai/server/@letoribo/mcp-graphql-enhanced)
+[![Glama](https://glama.ai/mcp/servers/@letoribo/mcp-graphql-enhanced/badge)](https://glama.ai/mcp/servers/@letoribo/mcp-graphql-enhanced)
 An **enhanced MCP (Model Context Protocol) server for GraphQL** that fixes real-world interoperability issues between LLMs and GraphQL APIs.
 
 > Drop-in replacement for `mcp-graphql` — with dynamic headers, robust variables parsing, and zero breaking changes.
@@ -11,9 +10,16 @@ An **enhanced MCP (Model Context Protocol) server for GraphQL** that fixes real-
 
 - ✅ **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
+- ✅ **Filtered introspection** — request only specific types (e.g., `typeNames: ["Query", "User"]`) to reduce LLM context noise
 - ✅ **Full MCP compatibility** — works with **Claude Desktop**, **Cursor**, **Glama**, and **Smithery**
 - ✅ **Secure by default** — mutations disabled unless explicitly enabled
 
+## 🔍 Filtered Introspection (New!)
+
+Avoid 50k-line schema dumps. Ask for only what you need:
+
+@introspect-schema typeNames ["Query", "User"]
+
 ## 🔍 Debug & Inspect
 
 Use the official MCP Inspector to test your server live:
@@ -21,7 +27,7 @@ Use the official MCP Inspector to test your server live:
 ```bash
 npx @modelcontextprotocol/inspector \
   -e ENDPOINT=https://api.example.com/graphql \
-  npx mcp-graphql-enhanced --debug
+  npx @letoribo/mcp-graphql-enhanced --debug
 ```
 
 ### Environment Variables (Breaking change in 1.0.0)
@@ -40,22 +46,22 @@ npx @modelcontextprotocol/inspector \
 
 ```bash
 # Basic usage
-ENDPOINT=http://localhost:3000/graphql npx mcp-graphql-enhanced
+ENDPOINT=http://localhost:3000/graphql npx @letoribo/mcp-graphql-enhanced
 
 # With auth header
 ENDPOINT=https://api.example.com/graphql \
 HEADERS='{"Authorization":"Bearer xyz"}' \
-npx mcp-graphql-enhanced
+npx @letoribo/mcp-graphql-enhanced
 
 # Enable mutations
 ENDPOINT=http://localhost:3000/graphql \
 ALLOW_MUTATIONS=true \
-npx mcp-graphql-enhanced
+npx @letoribo/mcp-graphql-enhanced
 
 # Use local schema file
 ENDPOINT=http://localhost:3000/graphql \
 SCHEMA=./schema.graphql \
-npx mcp-graphql-enhanced
+npx @letoribo/mcp-graphql-enhanced
 ```
 
 ## Resources
@@ -66,8 +72,9 @@ npx mcp-graphql-enhanced
 
 The server provides two main tools:
 
-1. **introspect-schema**: This tool retrieves the GraphQL schema. Use this first if you don't have access to the schema as a resource.
+1. **introspect-schema**: This tool retrieves the GraphQL schema or a filtered subset (via typeNames). Use this first if you don't have access to the schema as a resource.
 This uses either the local schema file, a schema file hosted at a URL, or an introspection query.
+Filtered introspection (typeNames) is only available when using a live GraphQL endpoint (not with SCHEMA file or URL).
 
 2. **query-graphql**: Execute GraphQL queries against the endpoint. By default, mutations are disabled unless `ALLOW_MUTATIONS` is set to `true`.
 
@@ -75,10 +82,10 @@ This uses either the local schema file, a schema file hosted at a URL, or an int
 
 ### Installing via Smithery
 
-To install GraphQL MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-graphql-enhanced):
+To install GraphQL MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@letoribo/mcp-graphql-enhanced):
 
 ```bash
-npx -y @smithery/cli install mcp-graphql-enhanced --client claude
+npx -y @smithery/cli install @letoribo/mcp-graphql-enhanced --client claude
 ```
 
 ### Installing Manually
@@ -89,7 +96,7 @@ It can be manually installed to Claude:
     "mcpServers": {
         "mcp-graphql": {
             "command": "npx",
-            "args": ["mcp-graphql-enhanced"],
+            "args": ["@letoribo/mcp-graphql-enhanced"],
             "env": {
                 "ENDPOINT": "https://your-api.com/graphql"
             }

package/dist/helpers/introspection.d.ts

@@ -17,4 +17,5 @@ export declare function introspectSchemaFromUrl(url: string): Promise<string>;
  * @returns The schema
  */
 export declare function introspectLocalSchema(path: string): Promise<string>;
+export declare function introspectTypes(endpoint: string, headers: Record<string, string> | undefined, typeNames: string[]): Promise<string>;
 //# sourceMappingURL=introspection.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../../src/helpers/introspection.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACvC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,mBAuBhC;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,MAAM,mBASxD;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,mBAGvD"}
+{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../../src/helpers/introspection.ts"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACvC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,mBAuBhC;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,MAAM,mBASxD;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,mBAGvD;AAkBD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,YAAK,EACpC,SAAS,EAAE,MAAM,EAAE,mBA6EpB"}

package/dist/helpers/introspection.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.introspectEndpoint = introspectEndpoint;
 exports.introspectSchemaFromUrl = introspectSchemaFromUrl;
 exports.introspectLocalSchema = introspectLocalSchema;
+exports.introspectTypes = introspectTypes;
 const graphql_1 = require("graphql");
 const promises_1 = require("node:fs/promises");
 /**
@@ -53,3 +54,86 @@ async function introspectLocalSchema(path) {
     const schema = await (0, promises_1.readFile)(path, "utf8");
     return schema;
 }
+function isObjectLikeType(type) {
+    return 'getFields' in type;
+}
+function isUnionType(type) {
+    return 'getTypes' in type;
+}
+function isEnumType(type) {
+    return 'getValues' in type;
+}
+function isInputObjectType(type) {
+    return 'getFields' in type;
+}
+async function introspectTypes(endpoint, headers = {}, typeNames) {
+    const response = await fetch(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...headers },
+        body: JSON.stringify({ query: (0, graphql_1.getIntrospectionQuery)() }),
+    });
+    const data = await response.json();
+    const schema = (0, graphql_1.buildClientSchema)(data.data);
+    const result = {};
+    for (const name of typeNames) {
+        const type = schema.getType(name);
+        if (!type)
+            continue;
+        // Handle object/interface types
+        if (isObjectLikeType(type)) {
+            result[name] = {
+                kind: type instanceof graphql_1.GraphQLObjectType ? "OBJECT" : "INTERFACE",
+                description: type.description,
+                fields: Object.fromEntries(Object.entries(type.getFields()).map(([fieldName, field]) => [
+                    fieldName,
+                    {
+                        type: field.type.toString(),
+                        description: field.description,
+                        args: field.args.map(arg => ({
+                            name: arg.name,
+                            type: arg.type.toString(),
+                            description: arg.description,
+                        }))
+                    }
+                ]))
+            };
+        }
+        // Handle union types
+        else if (isUnionType(type)) {
+            result[name] = {
+                kind: "UNION",
+                description: type.description,
+                possibleTypes: type.getTypes().map(t => t.name)
+            };
+        }
+        // Handle enums
+        else if (isEnumType(type)) {
+            result[name] = {
+                kind: "ENUM",
+                description: type.description,
+                values: type.getValues().map(v => ({
+                    name: v.name,
+                    description: v.description
+                }))
+            };
+        }
+        // Handle scalars and input objects
+        else if (isInputObjectType(type)) {
+            result[name] = {
+                kind: "INPUT_OBJECT",
+                description: type.description,
+                fields: Object.fromEntries(Object.entries(type.getFields()).map(([fieldName, field]) => [
+                    fieldName,
+                    { type: field.type.toString(), description: field.description }
+                ]))
+            };
+        }
+        else if (type instanceof graphql_1.GraphQLScalarType) {
+            result[name] = {
+                kind: "SCALAR",
+                description: type.description
+            };
+        }
+    }
+    return JSON.stringify(result, null, 2);
+}

package/dist/index.d.ts

@@ -4,10 +4,15 @@ declare const StdioServerTransport: any;
 declare const parse: any;
 declare const z: any;
 declare const checkDeprecatedArguments: any;
-declare const introspectEndpoint: any, introspectLocalSchema: any, introspectSchemaFromUrl: any;
+declare const introspectEndpoint: any, introspectLocalSchema: any, introspectSchemaFromUrl: any, introspectTypes: any;
 declare const getVersion: () => any;
 declare const EnvSchema: any;
 declare const env: any;
 declare const server: any;
+interface IntrospectSchemaArgs {
+    typeNames?: string[];
+    descriptions?: boolean;
+    directives?: boolean;
+}
 declare function main(): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,QAAA,MAAQ,SAAS,KAAuD,CAAC;AACzE,QAAA,MAAQ,oBAAoB,KAAyD,CAAC;AACtF,QAAA,MAAQ,KAAK,KAAgC,CAAC;AAC9C,QAAA,MAAM,CAAC,KAAyB,CAAC;AACjC,QAAA,MAAQ,wBAAwB,KAAwC,CAAC;AACzE,QAAA,MACC,kBAAkB,OAClB,qBAAqB,OACrB,uBAAuB,KACiB,CAAC;AAG1C,QAAA,MAAM,UAAU,WAIf,CAAC;AAKF,QAAA,MAAM,SAAS,KAkBb,CAAC;AAEH,QAAA,MAAM,GAAG,KAA+B,CAAC;AAEzC,QAAA,MAAM,MAAM,KAIV,CAAC;AAoMH,iBAAe,IAAI,kBAOlB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,QAAA,MAAQ,SAAS,KAAuD,CAAC;AACzE,QAAA,MAAQ,oBAAoB,KAAyD,CAAC;AACtF,QAAA,MAAQ,KAAK,KAAgC,CAAC;AAC9C,QAAA,MAAM,CAAC,KAAyB,CAAC;AACjC,QAAA,MAAQ,wBAAwB,KAAwC,CAAC;AACzE,QAAA,MACC,kBAAkB,OAClB,qBAAqB,OACrB,uBAAuB,OACvB,eAAe,KACyB,CAAC;AAG1C,QAAA,MAAM,UAAU,WAIf,CAAC;AAKF,QAAA,MAAM,SAAS,KAqBb,CAAC;AAEH,QAAA,MAAM,GAAG,KAA+B,CAAC;AAEzC,QAAA,MAAM,MAAM,KAIV,CAAC;AA+BH,UAAU,oBAAoB;IAC5B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAoKD,iBAAe,IAAI,kBAOlB"}

package/dist/index.js

@@ -5,7 +5,7 @@ const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio
 const { parse } = require("graphql/language");
 const z = require("zod").default;
 const { checkDeprecatedArguments } = require("./helpers/deprecation.js");
-const { introspectEndpoint, introspectLocalSchema, introspectSchemaFromUrl, } = require("./helpers/introspection.js");
+const { introspectEndpoint, introspectLocalSchema, introspectSchemaFromUrl, introspectTypes, } = require("./helpers/introspection.js");
 // Simulate macro import — since "with { type: 'macro' }" is not CommonJS compatible
 const getVersion = () => {
     // Replace with your actual version or read from package.json
@@ -16,7 +16,7 @@ const getVersion = () => {
 checkDeprecatedArguments();
 const EnvSchema = z.object({
     NAME: z.string().default("mcp-graphql"),
-    ENDPOINT: z.string().url().default("http://localhost:4000/graphql"),
+    ENDPOINT: z.preprocess((val) => (typeof val === 'string' ? val.trim() : val), z.string().url("ENDPOINT must be a valid URL (e.g., https://example.com/graphql)")).default("http://localhost:4000/graphql"),
     ALLOW_MUTATIONS: z
         .enum(["true", "false"])
         .transform((value) => value === "true")
@@ -68,38 +68,38 @@ server.resource("graphql-schema", new URL(env.ENDPOINT).href, async (uri) => {
         throw new Error(`Failed to get GraphQL schema: ${error}`);
     }
 });
-server.tool("introspect-schema", "Introspect the GraphQL schema, use this tool before doing a query to get the schema information if you do not have it available as a resource already.", {
-    __ignore__: z
-        .boolean()
-        .default(false)
-        .describe("This does not do anything"),
-}, async () => {
+server.tool("introspect-schema", "Introspect the GraphQL schema. Optionally filter to specific types.", {
+    typeNames: z.array(z.string()).optional().describe("e.g., [\"Query\", \"User\"]"),
+    descriptions: z.boolean().optional().default(true),
+    directives: z.boolean().optional().default(true),
+}, async ({ typeNames, descriptions = true, directives = true }) => {
     try {
-        let schema;
-        if (env.SCHEMA) {
-            schema = await introspectLocalSchema(env.SCHEMA);
+        if (typeNames && typeNames.length > 0) {
+            // ✅ Use your existing introspectTypes helper
+            const filtered = await introspectTypes(env.ENDPOINT, env.HEADERS, typeNames);
+            return { content: [{ type: "text", text: filtered }] };
         }
         else {
-            schema = await introspectEndpoint(env.ENDPOINT, env.HEADERS);
+            // Fallback to full schema
+            let schema;
+            if (env.SCHEMA) {
+                if (env.SCHEMA.startsWith("http://") || env.SCHEMA.startsWith("https://")) {
+                    schema = await introspectSchemaFromUrl(env.SCHEMA);
+                }
+                else {
+                    schema = await introspectLocalSchema(env.SCHEMA);
+                }
+            }
+            else {
+                schema = await introspectEndpoint(env.ENDPOINT, env.HEADERS);
+            }
+            return { content: [{ type: "text", text: schema }] };
         }
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: schema,
-                },
-            ],
-        };
     }
     catch (error) {
         return {
             isError: true,
-            content: [
-                {
-                    type: "text",
-                    text: `Failed to introspect schema: ${error}`,
-                },
-            ],
+            content: [{ type: "text", text: `Introspection failed: ${error}` }],
         };
     }
 });

package/package.json

@@ -31,7 +31,7 @@
 		"format": "prettier --write ."
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "1.12.0",
+		"@modelcontextprotocol/sdk": "^1.20.1",
 		"graphql": "^16.11.0",
 		"yargs": "17.7.2",
 		"zod": "3.25.30",
@@ -46,5 +46,5 @@
 		"ts-node": "^10.9.2",
 		"typescript": "5.8.3"
 	},
-	"version": "2.0.5"
+	"version": "2.0.7"
 }