Merge pull request #53 from neo4j/move-to-read-only

Introduce read-cypher (read-only) tool and rename run-cypher to write-cypher

Author: MacondoExpress

.changes/unreleased/Minor-20250930-163503.yaml

@@ -0,0 +1,8 @@
+kind: Minor
+body: |
+  Renamed "run-cypher" to "write-cypher" and added "read-cypher".
+  The new read-cypher enforces read-only Cypher queries and only accepts queries
+  that do not modify data. It explicitly disallows admin/schema commands,
+  write queries, and profiling queries using the PROFILE keyword.
+
+time: 2025-09-30T16:35:03.012848+01:00

README.md

@@ -104,10 +104,22 @@ Notes:
 
 Provided tools:
 
-| Tool         | Purpose                                              | Notes                                                                                      |
-| ------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `get-schema` | Introspect labels, relationship types, property keys | Read-only. Provide valuable context to the client LLMs.                                    |
-| `run-cypher` | Execute arbitrary Cypher (read/write)                | **Caution:** LLM-generated queries could cause harm. Use only in development environments. |
+| Tool           | Purpose                                              | Notes                                                                                                |
+| -------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `get-schema`   | Introspect labels, relationship types, property keys | Read-only. Provide valuable context to the client LLMs.                                              |
+| `read-cypher`  | Execute arbitrary Cypher (read mode)                 | Read-only. rejects writes, schema/admin operations, and PROFILE queries. Use `write-cypher` instead. |
+| `write-cypher` | Execute arbitrary Cypher (write mode)                | **Caution:** LLM-generated queries could cause harm. Use only in development environments.           |
+
+### Query Classification
+
+The `read-cypher` tool performs an extra round-trip to the Neo4j database to guarantee read-only operations.
+
+Important notes:
+
+- **Write operations**: `CREATE`, `MERGE`, `DELETE`, `SET`, etc., are treated as non-read queries.
+- **Admin queries**: Commands like `SHOW USERS`, `SHOW DATABASES`, etc., are treated as non-read queries and must use `write-cypher` instead.
+- **Profile queries**: `EXPLAIN PROFILE` queries are treated as non-read queries, even if the underlying statement is read-only.
+- **Schema operations**: `CREATE INDEX`, `DROP CONSTRAINT`, etc., are treated as non-read queries.
 
 ## Example Natural Language Prompts
 

internal/database/interfaces.go

@@ -15,6 +15,10 @@ type QueryExecutor interface {
 
 	// ExecuteWriteQuery executes a write-only Cypher query and returns raw records
 	ExecuteWriteQuery(ctx context.Context, cypher string, params map[string]any, database string) ([]*neo4j.Record, error)
+
+	// GetQueryType prefixes the provided query with EXPLAIN and returns the query type (e.g. 'r' for read, 'w' for write, 'rw' etc.)
+	// This allows read-only tools to determine if a query is safe to run in read-only context.
+	GetQueryType(ctx context.Context, cypher string, params map[string]any, database string) (neo4j.StatementType, error)
 }
 
 // RecordFormatter defines the interface for formatting Neo4j records

internal/database/mocks/mock_database.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"log"
+	"strings"
 
 	"github.com/neo4j/neo4j-go-driver/v5/neo4j"
 )
@@ -59,6 +60,33 @@ func (s *Neo4jService) ExecuteWriteQuery(ctx context.Context, cypher string, par
 	return res.Records, nil
 }
 
+// GetQueryType prefixes the provided query with EXPLAIN and returns the query type (e.g. 'r' for read, 'w' for write, 'rw' etc.)
+// This allows read-only tools to determine if a query is safe to run in read-only context.
+func (s *Neo4jService) GetQueryType(ctx context.Context, cypher string, params map[string]any, database string) (neo4j.StatementType, error) {
+	if s.driver == nil {
+		err := fmt.Errorf("neo4j driver is not initialized")
+		log.Printf("Error in GetQueryType: %v", err)
+		return neo4j.StatementTypeUnknown, err
+	}
+
+	explainedQuery := strings.Join([]string{"EXPLAIN", cypher}, " ")
+	res, err := neo4j.ExecuteQuery(ctx, *s.driver, explainedQuery, params, neo4j.EagerResultTransformer, neo4j.ExecuteQueryWithDatabase(database))
+	if err != nil {
+		wrappedErr := fmt.Errorf("error during GetQueryType: %w", err)
+		log.Printf("Error during GetQueryType: %v", wrappedErr)
+		return neo4j.StatementTypeUnknown, wrappedErr
+	}
+
+	if res.Summary == nil {
+		err := fmt.Errorf("error during GetQueryType: no summary returned for explained query")
+		log.Printf("Error during GetQueryType: %v", err)
+		return neo4j.StatementTypeUnknown, err
+	}
+
+	return res.Summary.StatementType(), nil
+
+}
+
 // Neo4jRecordsToJSON converts Neo4j records to JSON string
 func (s *Neo4jService) Neo4jRecordsToJSON(records []*neo4j.Record) (string, error) {
 	results := make([]map[string]any, 0)
@@ -76,6 +104,5 @@ func (s *Neo4jService) Neo4jRecordsToJSON(records []*neo4j.Record) (string, erro
 
 	formattedResponseStr := string(formattedResponse)
 
-
 	return formattedResponseStr, nil
 }

internal/database/service.go

@@ -28,7 +28,7 @@ func NewNeo4jMCPServer(version string, cfg *config.Config) (*Neo4jMCPServer, err
 		version,
 		server.WithToolCapabilities(true),
 		server.WithInstructions("This is the Neo4j official MCP server and can provide tool calling to interact with your Neo4j database,"+
-			"by inferring the schema with tools like get-schema and executing arbitrary Cypher queries with run-cypher."),
+			"by inferring the schema with tools like get-schema and executing arbitrary Cypher queries with read-cypher."),
 	)
 
 	// Initialize Neo4j driver once

internal/server/server.go

@@ -0,0 +1,71 @@
+package tools
+
+import (
+	"context"
+	"log"
+
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/neo4j/mcp/internal/config"
+	"github.com/neo4j/mcp/internal/database"
+	"github.com/neo4j/neo4j-go-driver/v5/neo4j"
+)
+
+func ReadCypherHandler(deps *ToolDependencies) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	return func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+		return handleReadCypher(ctx, request, deps.DBService, deps.Config)
+	}
+}
+
+func handleReadCypher(ctx context.Context, request mcp.CallToolRequest, dbService database.DatabaseService, config *config.Config) (*mcp.CallToolResult, error) {
+	var args ReadCypherInput
+	// Bind arguments to the struct
+	if err := request.BindArguments(&args); err != nil {
+		log.Printf("Error binding arguments: %v", err)
+		return mcp.NewToolResultError(err.Error()), nil
+	}
+	Query := args.Query
+	Params := args.Params
+
+	log.Printf("cypher-query: %s", Query)
+
+	// Validate that query is not empty
+	if Query == "" {
+		errMessage := "Query parameter is required and cannot be empty"
+		log.Printf("%s", errMessage)
+		return mcp.NewToolResultError(errMessage), nil
+	}
+
+	if dbService == nil {
+		errMessage := "Database service is not initialized"
+		log.Printf("%s", errMessage)
+		return mcp.NewToolResultError(errMessage), nil
+	}
+
+	// Get queryType by pre-appending "EXPLAIN" to identify if the query is of type "r", if not raise a ToolResultError
+	queryType, err := dbService.GetQueryType(ctx, Query, Params, config.Database)
+	if err != nil {
+		log.Printf("Error while classifying Cypher query: %v", err)
+		return mcp.NewToolResultError(err.Error()), nil
+	}
+
+	if queryType != neo4j.StatementTypeReadOnly { // only queryType == "r" are allowed in read-cypher
+		errMessage := "read-cypher can only run read-only Cypher statements. For write operations (CREATE, MERGE, DELETE, SET, etc...), schema/admin commands, or PROFILE queries, use write-cypher instead."
+		log.Printf("Rejected non-read query (type=%v): %v", queryType, Query)
+		return mcp.NewToolResultError(errMessage), nil
+	}
+
+	// Execute the Cypher query using the database service (now confirmed read-only)
+	records, err := dbService.ExecuteReadQuery(ctx, Query, Params, config.Database)
+	if err != nil {
+		log.Printf("Error executing Cypher query: %v", err)
+		return mcp.NewToolResultError(err.Error()), nil
+	}
+
+	response, err := dbService.Neo4jRecordsToJSON(records)
+	if err != nil {
+		log.Printf("Error formatting query results: %v", err)
+		return mcp.NewToolResultError(err.Error()), nil
+	}
+
+	return mcp.NewToolResultText(response), nil
+}