feat(mcp): Add a tool that can validate the syntax of a DQL query (#9465)

**Description**

This PR adds the `validate_query_syntax` tool.

NOTE: the tool does not validate mutations. Long story, but the parser
used removed its ability to parse mutation blocks way back.

**Checklist**

- [x] Code compiles correctly and linting passes locally
- [ ] For all _code_ changes, an entry added to the `CHANGELOG.md` file
describing and linking to
      this PR
- [x] Tests added for new functionality, or regression tests for bug
fixes added as applicable

---------

Co-authored-by: mattthew <matthew.mcneely@gmail.com>

Author: Harshil Goel

dgraph/cmd/mcp/mcp_server.go

@@ -11,6 +11,8 @@ import (
 
 	"github.com/dgraph-io/dgo/v250"
 	"github.com/dgraph-io/dgo/v250/protos/api"
+
+	"github.com/hypermodeinc/dgraph/v25/dql"
 	"github.com/hypermodeinc/dgraph/v25/x"
 
 	"github.com/golang/glog"
@@ -72,14 +74,68 @@ func NewMCPServer(connectionString string, readOnly bool) (*server.MCPServer, er
 		}),
 	)
 
+	validateQuerySyntaxTool := mcp.NewTool("validate_query_syntax",
+		mcp.WithDescription("Check if a Dgraph DQL Query is valid"),
+		mcp.WithString("query",
+			mcp.Required(),
+			mcp.Description("The query to validate"),
+		),
+		mcp.WithString("variables",
+			mcp.Description("The variables to be used in the query. Should be in JSON format to be unmarshalled into map[string]string"),
+		),
+		mcp.WithToolAnnotation(mcp.ToolAnnotation{
+			ReadOnlyHint:    &True,
+			DestructiveHint: &False,
+			IdempotentHint:  &True,
+			OpenWorldHint:   &False,
+		}),
+	)
+
+	s.AddTool(validateQuerySyntaxTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+		args := request.GetArguments()
+		if args == nil {
+			return mcp.NewToolResultError("Query must be present"), nil
+		}
+		queryArg, ok := args["query"]
+		if !ok || queryArg == nil {
+			return mcp.NewToolResultError("Query must be present"), nil
+		}
+
+		op, ok := queryArg.(string)
+		if !ok {
+			return mcp.NewToolResultError("Query must be a string"), nil
+		}
+
+		var variablesMap map[string]string
+		variablesArg, ok := args["variables"]
+		if ok && variablesArg != nil {
+			variables, ok := variablesArg.(string)
+			if !ok {
+				return mcp.NewToolResultError("Variables must be a string"), nil
+			}
+			if err := json.Unmarshal([]byte(variables), &variablesMap); err != nil {
+				return mcp.NewToolResultErrorFromErr("Error unmarshalling variables", err), nil
+			}
+		}
+
+		req := &dql.Request{
+			Str:       op,
+			Variables: variablesMap,
+		}
+		_, err := dql.Parse(*req)
+		if err != nil {
+			return mcp.NewToolResultErrorFromErr("Error parsing query", err), nil
+		}
+		return mcp.NewToolResultText("Query is valid"), nil
+	})
+
 	queryTool := mcp.NewTool("run_query",
 		mcp.WithDescription("Run DQL Query on Dgraph"),
 		mcp.WithString("query",
 			mcp.Required(),
-			mcp.Description("The query to perform"),
+			mcp.Description("The query to run"),
 		),
 		mcp.WithString("variables",
-			mcp.Required(),
 			mcp.Description("The parameters to pass to the query in JSON format. The JSON should be a map of string keys to string, number or boolean values. Example: {\"$param1\": \"value1\", \"$param2\": 123, \"$param3\": true}"),
 		),
 		mcp.WithToolAnnotation(mcp.ToolAnnotation{
@@ -133,11 +189,14 @@ func NewMCPServer(connectionString string, readOnly bool) (*server.MCPServer, er
 			return mcp.NewToolResultText("Schema updated successfully"), nil
 		})
 
+		mutationArgumentDescription := `The mutation to perform in JSON format.
+		For example: {"set": [{ "uid": "_:1", "n": "Foo", "m": 20, "p": 3.14 }]} to set a node with blank identifier _:1 with name "Foo", m=20 and p=3.14
+		Another example: { "delete": [{ "uid": "0xfa12" }]} to delete a node with uid 0xfa12`
 		mutationTool := mcp.NewTool("run_mutation",
 			mcp.WithDescription("Run DQL Mutation on Dgraph"),
 			mcp.WithString("mutation",
 				mcp.Required(),
-				mcp.Description("The mutation to perform in JSON format"),
+				mcp.Description(mutationArgumentDescription),
 			),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
 				ReadOnlyHint:    &False,

dgraph/cmd/mcp/mcp_server_sse_test.go

@@ -69,7 +69,7 @@ func TestMCPSSE(t *testing.T) {
 		}
 
 		if result.IsError {
-			return "", fmt.Errorf("tool error: %v", result.Content[0])
+			return result.Content[0].(mcp.TextContent).Text, fmt.Errorf("tool error: %v", result.Content[0])
 		}
 		if textContent, ok := result.Content[0].(mcp.TextContent); ok {
 			return textContent.Text, nil
@@ -91,6 +91,7 @@ func TestMCPSSE(t *testing.T) {
 
 		expectedTools := []string{
 			"get_schema",
+			"validate_query_syntax",
 			"run_query",
 			"alter_schema",
 			"run_mutation",
@@ -102,6 +103,7 @@ func TestMCPSSE(t *testing.T) {
 			foundTools[tool.Name] = true
 		}
 
+		require.Equal(t, len(expectedTools), len(foundTools), "Expected %d tools, found %d", len(expectedTools), len(foundTools))
 		for _, expected := range expectedTools {
 			require.True(t, foundTools[expected], "Expected tool %s to be available", expected)
 		}
@@ -189,7 +191,7 @@ func TestMCPSSE(t *testing.T) {
 			"mutation": `{
   "set": [
     {
-      "uid": "_:1",
+      "uid": "_:foo",
       "n": "Foo",
       "m": 20,
       "p": 3.14
@@ -218,6 +220,65 @@ func TestMCPSSE(t *testing.T) {
 		require.Regexp(t, `^0x[0-9a-f]+$`, uidValue, "UID should be in the format 0x followed by hexadecimal digits")
 	}
 
+	t.Run("ValidateQuerySyntax", func(t *testing.T) {
+		t.Run("Valid", func(t *testing.T) {
+			t.Run("Query", func(t *testing.T) {
+				args := map[string]interface{}{
+					"query": `{q(func: allofterms(name, "Foo")) { uid }}`,
+				}
+				resultText, err := callTool("validate_query_syntax", args)
+				require.NoError(t, err, "ValidateQuerySyntax should not fail")
+				require.NotEmpty(t, resultText, "Should receive validate query syntax result")
+				require.Equal(t, "Query is valid", resultText)
+			})
+			t.Run("QueryWithVariables", func(t *testing.T) {
+				args := map[string]interface{}{
+					"query":     `query me($name: string) {q(func: allofterms(name, $name)) { uid }}`,
+					"variables": `{"$name": "Foo"}`,
+				}
+				resultText, err := callTool("validate_query_syntax", args)
+				require.NoError(t, err, "ValidateQuerySyntax should not fail")
+				require.NotEmpty(t, resultText, "Should receive validate query syntax result")
+				require.Equal(t, "Query is valid", resultText)
+			})
+		})
+		t.Run("Invalid", func(t *testing.T) {
+			t.Run("Query", func(t *testing.T) {
+				args := map[string]interface{}{
+					"query": `{q(func: foo(n, "Foo")) { uid }}`,
+				}
+				resultText, err := callTool("validate_query_syntax", args)
+				require.Error(t, err, "ValidateQuerySyntax should fail")
+				require.Contains(t, resultText, "foo is not valid")
+			})
+			t.Run("QueryWithVariables", func(t *testing.T) {
+				args := map[string]interface{}{
+					"query":     `query me($name: string) {q(func: allofterms(name, $name)) { uid }}`,
+					"variables": `{"$notname": "Foo"}`,
+				}
+				resultText, err := callTool("validate_query_syntax", args)
+				require.Error(t, err, "ValidateQuerySyntax should fail")
+				require.Contains(t, resultText, "Type of variable $notname not specified")
+			})
+			t.Run("MisuseOfVariables", func(t *testing.T) {
+				misuseOfVariables := `{
+					var(func: eq(name, "Alice")) {
+						b as uid
+					}
+					me(func: uid(a)) {
+						name
+					}
+				}`
+				args := map[string]interface{}{
+					"query": misuseOfVariables,
+				}
+				resultText, err := callTool("validate_query_syntax", args)
+				require.Error(t, err, "ValidateQuerySyntax should fail")
+				require.Contains(t, resultText, "Variables are not used properly")
+			})
+		})
+	})
+
 	t.Run("RunQuery", func(t *testing.T) {
 		args := map[string]interface{}{
 			"query": `{q(func: allofterms(n, "Foo")) { uid }}`,
@@ -227,16 +288,7 @@ func TestMCPSSE(t *testing.T) {
 		require.NoError(t, err, "RunQuery should not fail")
 		require.NotEmpty(t, resultText, "Should receive run query result")
 
-		var result map[string][]map[string]string
-		err = json.Unmarshal([]byte(resultText), &result)
-		require.NoError(t, err, "Should be able to parse JSON response")
-
-		require.Contains(t, result, "q", "Response should contain 'q' field")
-		require.Len(t, result["q"], 1, "Should have exactly one result")
-		require.Contains(t, result["q"][0], "uid", "Result should have 'uid' field")
-
-		uidValue := result["q"][0]["uid"]
-		require.Regexp(t, `^0x[0-9a-f]+$`, uidValue, "UID should be in the format 0x followed by hexadecimal digits")
+		checkUIDResult(t, resultText)
 	})
 
 	t.Run("RunQueryWithEmptyArgs", func(t *testing.T) {

dgraph/cmd/mcp/prompt.txt

@@ -14,6 +14,7 @@ MCP TOOLS
 Tools Available:
 - "get_schema": Gets Graph schema
 - "alter_schema": Alters Graph Schema.
+- "validate_query_syntax": Validates DQL query syntax.
 - "run_query": Executes DQL statements queries on the provided Dgraph connection and returns results. Variables are optional.
 - "run_mutation": Executes DQL statements mutations on the provided Dgraph connection and returns results.
 - "get_common_queries": Some common queries that can be done on the Graph
@@ -37,6 +38,7 @@ WORKFLOW
 3. Query Execution:
    - Interpret user queries about data retrieval or analysis.
    - Match user intent to schema structure and generate DQL.
+   - Use the `validate_query_syntax` tool to validate the DQL query syntax.
    - Use the `run_query` tool to run the DQL and return results.
    - Provide explanations for the query structure and results, especially for less technical users.
 
@@ -96,6 +98,7 @@ CONVERSATION FLOW
    - Confirm which predicates or types are relevant.
    - Fetch schema if necessary.
    - Generate the corresponding DQL queries.
+   - Use the `validate_query_syntax` tool to validate the DQL query syntax.
    - Execute and present results.
    - Visualize where helpful.