@iflow-mcp/saewoohan-mcp-graphql-tools 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 saewoohan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# GraphQL MCP Tools
+
+A Model Context Protocol (MCP) server implementation that provides GraphQL API interaction capabilities. This server enables AI assistants to interact with GraphQL APIs through a set of standardized tools.
+
+## Components
+
+### Tools
+
+- **graphql_query**
+  - Execute GraphQL queries against any endpoint
+  - Input:
+    - `query` (string): The GraphQL query to execute
+    - `variables` (object, optional): Variables for the query
+    - `endpoint` (string, optional): GraphQL endpoint URL
+    - `headers` (object, optional): HTTP headers for the request
+    - `timeout` (number, optional): Request timeout in milliseconds
+    - `allowMutations` (boolean, optional): Whether to allow mutation operations
+
+- **graphql_introspect**
+  - Retrieve and explore GraphQL schema information
+  - Input:
+    - `endpoint` (string, optional): GraphQL endpoint URL
+    - `headers` (object, optional): HTTP headers for the request
+    - `includeDeprecated` (boolean, optional): Whether to include deprecated types/fields
+
+## Usage with Claude Desktop
+
+### NPX
+
+```json
+{
+  "mcpServers": {
+    "graphql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-graphql-tools",
+        "--endpoint=https://api.github.com/graphql",
+        "--headers={\"Authorization\":\"Bearer YOUR_GITHUB_TOKEN\"}",
+        "--timeout=30000",
+        "--maxComplexity=100"
+      ]
+    }
+  }
+}
+```
+
+## Configuration Options
+The server accepts the following command-line arguments:
+
+- --endpoint (-e): Default GraphQL endpoint URL (default: http://localhost:4000/graphql)
+- --headers (-H): Default headers for all requests as JSON string
+- --timeout (-t): Default request timeout in milliseconds (default: 30000)
+- --maxComplexity (-m): Maximum allowed query complexity (default: 100)
+
+## License
+This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

package/build/config.js

@@ -0,0 +1,65 @@
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageVersion = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
+export const parseArguments = () => {
+    return yargs(hideBin(process.argv))
+        .option("endpoint", {
+        alias: "e",
+        description: "Default GraphQL endpoint URL",
+        type: "string",
+        default: process.env.ENDPOINT ?? "http://localhost:4000/graphql",
+    })
+        .option("headers", {
+        alias: "H",
+        description: "Default headers for all requests (as JSON string)",
+        type: "string",
+    })
+        .option("timeout", {
+        alias: "t",
+        description: "Default request timeout in milliseconds",
+        type: "number",
+        default: Number(process.env.TIMEOUT) ?? 30000,
+    })
+        .option("maxComplexity", {
+        alias: "m",
+        description: "Maximum allowed query complexity",
+        type: "number",
+        default: Number(process.env.MAX_DEPTH) ?? 100,
+    })
+        .help()
+        .alias("help", "h")
+        .version(packageVersion)
+        .alias("version", "v")
+        .parseSync();
+};
+export class Config {
+    endpoint;
+    maxQueryComplexity;
+    timeout;
+    headers;
+    version;
+    constructor() {
+        const argv = parseArguments();
+        this.endpoint = argv.endpoint;
+        this.maxQueryComplexity = argv.maxComplexity;
+        this.timeout = argv.timeout;
+        this.version = packageVersion;
+        // Parse default headers
+        this.headers = {};
+        if (argv.headers) {
+            try {
+                Object.assign(this.headers, JSON.parse(argv.headers));
+            }
+            catch (e) {
+                console.error("Error parsing default headers:", e);
+                console.error("Headers should be a valid JSON object string");
+            }
+        }
+    }
+}
+export const config = new Config();

package/build/index.js

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { parse, printSchema } from "graphql";
+import { config } from "./config.js";
+import { calculateQueryComplexity, executeGraphQLQuery, fetchGraphQLSchema, formatGraphQLQuery, isMutation, sanitizeErrorMessage, } from "./utils.js";
+const DEFAULT_GRAPHQL_ENDPOINT = config.endpoint;
+const MAX_QUERY_COMPLEXITY = config.maxQueryComplexity;
+const DEFAULT_TIMEOUT = config.timeout;
+const DEFAULT_HEADERS = config.headers;
+const GRAPHQL_QUERY_TOOL = {
+    name: "graphql_query",
+    description: "Execute GraphQL queries using either a specified endpoint or the default endpoint configured during installation",
+    inputSchema: {
+        type: "object",
+        properties: {
+            endpoint: {
+                type: "string",
+                description: "GraphQL endpoint URL (can be omitted to use default)",
+            },
+            query: {
+                type: "string",
+                description: "GraphQL query to execute",
+            },
+            variables: {
+                type: "object",
+                description: "Variables to use with the query (JSON object)",
+            },
+            headers: {
+                type: "object",
+                description: "Additional headers to include in the request (will be merged with default headers)",
+            },
+            timeout: {
+                type: "number",
+                description: "Request timeout in milliseconds",
+            },
+        },
+        required: ["query"],
+    },
+};
+const GRAPHQL_INTROSPECT_TOOL = {
+    name: "graphql_introspect",
+    description: "Introspect a GraphQL schema from an endpoint with configurable headers",
+    inputSchema: {
+        type: "object",
+        properties: {
+            endpoint: {
+                type: "string",
+                description: "GraphQL endpoint URL (can be omitted to use default)",
+            },
+            headers: {
+                type: "object",
+                description: "Additional headers to include in the request (will be merged with default headers)",
+            },
+            includeDeprecated: {
+                type: "boolean",
+                description: "Whether to include deprecated fields",
+            },
+        },
+    },
+};
+const GRAPHQL_TOOLS = [GRAPHQL_QUERY_TOOL, GRAPHQL_INTROSPECT_TOOL];
+const handleGraphQLQuery = async (query, variables, endpoint = DEFAULT_GRAPHQL_ENDPOINT, headers = {}, timeout = DEFAULT_TIMEOUT, allowMutations = false) => {
+    try {
+        // Validate query syntax
+        parse(query);
+        // Check for mutations if they're not allowed
+        if (!allowMutations && isMutation(query)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Mutation operations are not allowed unless explicitly enabled with allowMutations=true",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Calculate query complexity
+        const queryComplexity = calculateQueryComplexity(query);
+        if (queryComplexity > MAX_QUERY_COMPLEXITY) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Query complexity (${queryComplexity}) exceeds maximum allowed (${MAX_QUERY_COMPLEXITY})`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Process variables
+        let processedVariables = variables;
+        if (typeof variables === "string") {
+            try {
+                processedVariables = JSON.parse(variables);
+            }
+            catch (parseError) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to parse variables as JSON: ${parseError.message}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        // Execute query
+        const startTime = Date.now();
+        const response = await executeGraphQLQuery({
+            endpoint,
+            query,
+            variables: processedVariables,
+            headers,
+            timeout,
+        });
+        const executionTime = Date.now() - startTime;
+        // Check for GraphQL errors
+        if (response.data.errors) {
+            const errorMessages = response.data.errors
+                .map((e) => e.message)
+                .join(", ");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `GraphQL server returned errors: ${errorMessages}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Return successful response
+        const formattedQuery = formatGraphQLQuery(query);
+        const formattedData = JSON.stringify(response.data.data, null, 2);
+        const hasDefaultHeaders = Object.keys(DEFAULT_HEADERS).length > 0;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Query executed successfully in ${executionTime}ms at ${endpoint}`,
+                },
+                ...(hasDefaultHeaders
+                    ? [
+                        {
+                            type: "text",
+                            text: `Using default headers: ${JSON.stringify(DEFAULT_HEADERS, null, 2)}`,
+                        },
+                    ]
+                    : []),
+                {
+                    type: "text",
+                    text: `\nQuery:\n\`\`\`graphql\n${formattedQuery}\n\`\`\``,
+                },
+                {
+                    type: "text",
+                    text: `\nResult:\n\`\`\`json\n${formattedData}\n\`\`\``,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = sanitizeErrorMessage(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error executing GraphQL query: ${errorMessage}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+};
+const handleGraphQLIntrospect = async (endpoint = DEFAULT_GRAPHQL_ENDPOINT, headers = {}, includeDeprecated = true) => {
+    try {
+        // Fetch schema
+        const { schema } = await fetchGraphQLSchema({
+            endpoint,
+            headers,
+            includeDeprecated,
+        });
+        const schemaString = printSchema(schema);
+        const hasDefaultHeaders = Object.keys(DEFAULT_HEADERS).length > 0;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Schema introspection from ${endpoint} completed successfully`,
+                },
+                ...(hasDefaultHeaders
+                    ? [
+                        {
+                            type: "text",
+                            text: `Using default headers: ${JSON.stringify(DEFAULT_HEADERS, null, 2)}`,
+                        },
+                    ]
+                    : []),
+                {
+                    type: "text",
+                    text: `\nGraphQL Schema:\n\`\`\`graphql\n${schemaString}\n\`\`\``,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = sanitizeErrorMessage(error);
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `Error introspecting GraphQL schema: ${errorMessage}`,
+                },
+            ],
+        };
+    }
+};
+const server = new Server({
+    name: "graphql-mcp-server",
+    version: config.version,
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: GRAPHQL_TOOLS,
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        switch (request.params.name) {
+            case "graphql_query": {
+                const { query, variables, endpoint, headers, timeout, allowMutations } = request.params.arguments;
+                return await handleGraphQLQuery(query, variables, endpoint, headers, timeout, allowMutations);
+            }
+            case "graphql_introspect": {
+                const { endpoint, headers, includeDeprecated } = request.params
+                    .arguments;
+                return await handleGraphQLIntrospect(endpoint, headers, includeDeprecated);
+            }
+            default:
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Unknown tool: ${request.params.name}`,
+                        },
+                    ],
+                    isError: true,
+                };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+async function runServer() {
+    try {
+        console.error("Starting GraphQL MCP server...");
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        console.error("GraphQL MCP server ready");
+    }
+    catch (error) {
+        console.error("Error starting server:", error);
+        process.exit(1);
+    }
+}
+runServer().catch((error) => {
+    console.error("Fatal error running server:", error);
+    process.exit(1);
+});

package/build/utils.js

@@ -0,0 +1,92 @@
+import axios, { AxiosError } from "axios";
+import { parse, visit, Kind, OperationTypeNode, getIntrospectionQuery, buildClientSchema, } from "graphql";
+import { config } from "./config.js";
+const DEFAULT_GRAPHQL_ENDPOINT = config.endpoint;
+const DEFAULT_TIMEOUT = config.timeout;
+const DEFAULT_HEADERS = config.headers;
+const MAX_QUERY_COMPLEXITY = config.maxQueryComplexity;
+export const sanitizeErrorMessage = (error) => {
+    if (error instanceof AxiosError) {
+        if (error.response) {
+            return `Server responded with status ${error.response.status}: ${error.message}`;
+        }
+        if (error.request) {
+            return `No response received: ${error.message}`;
+        }
+    }
+    return error instanceof Error ? error.message : String(error);
+};
+export const formatGraphQLQuery = (query) => {
+    return query.replace(/\s+/g, " ").trim();
+};
+export const isMutation = (query) => {
+    try {
+        const document = parse(query);
+        for (const definition of document.definitions) {
+            if (definition.kind === Kind.OPERATION_DEFINITION &&
+                definition.operation === OperationTypeNode.MUTATION) {
+                return true;
+            }
+        }
+        return false;
+    }
+    catch (e) {
+        return false;
+    }
+};
+export const calculateQueryComplexity = (query) => {
+    try {
+        const document = parse(query);
+        let complexity = 0;
+        visit(document, {
+            Field(_) {
+                complexity += 1;
+            },
+        });
+        return complexity;
+    }
+    catch (e) {
+        return MAX_QUERY_COMPLEXITY + 1;
+    }
+};
+export const executeGraphQLQuery = async ({ endpoint = DEFAULT_GRAPHQL_ENDPOINT, query, variables, headers = {}, timeout = DEFAULT_TIMEOUT, }) => {
+    let processedVariables = variables;
+    if (typeof variables === "string") {
+        processedVariables = JSON.parse(variables);
+    }
+    const response = await axios.post(endpoint, {
+        query,
+        variables: processedVariables,
+    }, {
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            ...DEFAULT_HEADERS, // Apply default headers
+            ...headers, // Request-specific headers override defaults
+        },
+        timeout,
+    });
+    return response;
+};
+export const fetchGraphQLSchema = async ({ endpoint = DEFAULT_GRAPHQL_ENDPOINT, headers = {}, includeDeprecated = true, timeout = DEFAULT_TIMEOUT, }) => {
+    const response = await axios.post(endpoint, {
+        query: getIntrospectionQuery({
+            descriptions: true,
+            inputValueDeprecation: includeDeprecated,
+        }),
+    }, {
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            ...DEFAULT_HEADERS, // Apply default headers
+            ...headers, // Request-specific headers override defaults
+        },
+        timeout,
+    });
+    if (response.data.errors) {
+        throw new Error(`GraphQL server returned errors: ${JSON.stringify(response.data.errors)}`);
+    }
+    const introspectionResult = response.data.data;
+    const schema = buildClientSchema(introspectionResult);
+    return { schema, introspectionResult };
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@iflow-mcp/saewoohan-mcp-graphql-tools",
+  "version": "0.0.1",
+  "description": "GraphQL MCP server for AI assistants",
+  "author": "saewoohan <hso2341@naver.com>",
+  "license": "MIT",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "mcp-graphql": "./build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "format": "npx @biomejs/biome format --write src/",
+    "check": "npx @biomejs/biome check --apply src/",
+    "lint": "npx @biomejs/biome lint src/"
+  },
+  "keywords": [
+    "graphql",
+    "mcp",
+    "claude",
+    "ai",
+    "assistant",
+    "modelcontextprotocol",
+    "llm"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/saewoohan/mcp-server-tools"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.7.0",
+    "axios": "^1.8.4",
+    "graphql": "^16.10.0",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.13.13",
+    "typescript": "^5.8.2"
+  }
+}