Merge pull request #77 from neo4j/readonly-mode

Add NEO4J_READ_ONLY env var to enable read‑only

Author: MacondoExpress

.changes/unreleased/Patch-20251024-115523.yaml

@@ -0,0 +1,4 @@
+kind: Patch
+body: |
+  Add NEO4J_READ_ONLY env var to enable read-only mode. When enabled, only tools annotated as read-only are registered.
+time: 2025-10-24T11:55:23.771684+01:00

CONTRIBUTING.md

@@ -41,6 +41,7 @@ export NEO4J_URI="bolt://localhost:7687"
 export NEO4J_USERNAME="neo4j"
 export NEO4J_PASSWORD="password"
 export NEO4J_DATABASE="neo4j"
+export NEO4J_READ_ONLY="true" // Optional: disables write tools
 ```
 
 ## Build / Test / Run
@@ -157,10 +158,14 @@ func MyToolHandler(deps *ToolDependencies) mcp.ToolHandler {
        return mcp.NewTool("my-tool",
            mcp.WithDescription("Tool description"),
            mcp.WithInputSchema[MyToolInput](),
+           mcp.WithReadOnlyHintAnnotation(true), // This flag will be used filter tools for the read-only mode.
        )
    }
    ```
-
+    **Note:** WithReadOnlyHintAnnotation marks a tool with a read-only hint is used for filtering.
+    When set to true, the tool will be considered read-only and included when selecting
+    tools for read-only mode. If the annotation is not present or set to false,
+    the tool is treated as a write-capable tool (i.e., not considered read-only).
 2. **Implement tool handler**:
 
    ```go
@@ -171,7 +176,7 @@ func MyToolHandler(deps *ToolDependencies) mcp.ToolHandler {
    }
    ```
 
-3. **Register in tool_register.go**:
+3. **Register in tool_register.go, in the right section (cypher/GDS/etc...)**:
 
    ```go
    {

README.md

@@ -54,7 +54,8 @@ Create / edit `mcp.json` (docs: https://code.visualstudio.com/docs/copilot/custo
         "NEO4J_URI": "bolt://localhost:7687",
         "NEO4J_USERNAME": "neo4j",
         "NEO4J_PASSWORD": "password",
-        "NEO4J_DATABASE": "neo4j"
+        "NEO4J_DATABASE": "neo4j",
+        "NEO4J_READ_ONLY": "true" // Optional: disables write tools
       }
     }
   }
@@ -87,7 +88,8 @@ You’ll then add the `neo4j-mcp` MCP in the mcpServers key:
         "NEO4J_URI": "bolt://localhost:7687",
         "NEO4J_USERNAME": "neo4j",
         "NEO4J_PASSWORD": "password",
-        "NEO4J_DATABASE": "neo4j"
+        "NEO4J_DATABASE": "neo4j",
+        "NEO4J_READ_ONLY": "true" // Optional: disables write tools
       }
     }
   }
@@ -97,19 +99,26 @@ You’ll then add the `neo4j-mcp` MCP in the mcpServers key:
 Notes:
 
 - Adjust env vars for your setup (defaults shown above).
+- Set `NEO4J_READ_ONLY=true` to disable all write tools (e.g., `write-cypher`).
+- When enabled, only read operations are available; write tools are not exposed to clients.
 - Neo4j Desktop default URI: `bolt://localhost:7687`.
 - Aura: use the connection string from the Aura console.
 
 ## Tools & Usage
 
 Provided tools:
 
-| 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.           |
-| `list-gds-procedures` | List GDS procedures available in the Neo4j instance  | Read-only. Help the client LLM to have a better visibility on the GDS procedures available           |
+| Tool                  | ReadOnly | Purpose                                              | Notes                                                                                                                          |
+| --------------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `get-schema`          | `true`   | Introspect labels, relationship types, property keys | Provide valuable context to the client LLMs.                                                                                   |
+| `read-cypher`         | `true`   | Execute arbitrary Cypher (read mode)                 | Rejects writes, schema/admin operations, and PROFILE queries. Use `write-cypher` instead.                                      |
+| `write-cypher`        | `false`  | Execute arbitrary Cypher (write mode)                | **Caution:** LLM-generated queries could cause harm. Use only in development environments. Disabled if `NEO4J_READ_ONLY=true`. |
+| `list-gds-procedures` | `true`   | List GDS procedures available in the Neo4j instance  | Help the client LLM to have a better visibility on the GDS procedures available                                                |
+
+### Readonly mode flag
+
+Enable readonly mode by setting the `NEO4J_READ_ONLY` environment variable to `true` (for example, `"NEO4J_READ_ONLY": "true"`).
+When enabled, write tools (for example, `write-cypher`) are not exposed to clients.
 
 ### Query Classification
 

internal/config/config.go

@@ -11,6 +11,7 @@ type Config struct {
 	Username string
 	Password string
 	Database string
+	ReadOnly string // If true, disables write tools
 }
 
 // Validate validates the configuration and returns an error if invalid
@@ -39,11 +40,13 @@ func (c *Config) Validate() error {
 
 // LoadConfig loads configuration from environment variables with defaults
 func LoadConfig() (*Config, error) {
+
 	cfg := &Config{
 		URI:      GetEnvWithDefault("NEO4J_URI", "bolt://localhost:7687"),
 		Username: GetEnvWithDefault("NEO4J_USERNAME", "neo4j"),
 		Password: GetEnvWithDefault("NEO4J_PASSWORD", "password"),
 		Database: GetEnvWithDefault("NEO4J_DATABASE", "neo4j"),
+		ReadOnly: GetEnvWithDefault("NEO4J_READ_ONLY", "false"),
 	}
 
 	if err := cfg.Validate(); err != nil {

internal/server/tool_register_test.go

@@ -9,20 +9,19 @@ import (
 	"go.uber.org/mock/gomock"
 )
 
-func TestGetAllTools(t *testing.T) {
+func TestToolRegister(t *testing.T) {
 	ctrl := gomock.NewController(t)
 	defer ctrl.Finish()
 
-	cfg := &config.Config{
-		URI:      "bolt://test-host:7687",
-		Username: "neo4j",
-		Password: "password",
-		Database: "neo4j",
-	}
-
 	mockDB := mocks.NewMockService(ctrl)
 
 	t.Run("verifies expected tools are registered", func(t *testing.T) {
+		cfg := &config.Config{
+			URI:      "bolt://test-host:7687",
+			Username: "neo4j",
+			Password: "password",
+			Database: "neo4j",
+		}
 		s := server.NewNeo4jMCPServer("test-version", cfg, mockDB)
 
 		// Expected tools that should be registered
@@ -36,9 +35,59 @@ func TestGetAllTools(t *testing.T) {
 		}
 		registeredTools := len(s.MCPServer.ListTools())
 
-		if registeredTools != expectedTotalToolsCount {
-			t.Errorf("Expected 4 tools, but test configuration shows %d", expectedTotalToolsCount)
+		if expectedTotalToolsCount != registeredTools {
+			t.Errorf("Expected %d tools, but test configuration shows %d", expectedTotalToolsCount, registeredTools)
 		}
 	})
 
+	t.Run("should register only readonly tools when readonly", func(t *testing.T) {
+		cfg := &config.Config{
+			URI:      "bolt://test-host:7687",
+			Username: "neo4j",
+			Password: "password",
+			Database: "neo4j",
+			ReadOnly: "true",
+		}
+		s := server.NewNeo4jMCPServer("test-version", cfg, mockDB)
+
+		// Expected tools that should be registered
+		// update this number when a tool is added or removed.
+		expectedTotalToolsCount := 3
+
+		// Register tools
+		err := s.RegisterTools()
+		if err != nil {
+			t.Fatalf("RegisterTools() failed: %v", err)
+		}
+		registeredTools := len(s.MCPServer.ListTools())
+
+		if expectedTotalToolsCount != registeredTools {
+			t.Errorf("Expected %d tools, but test configuration shows %d", expectedTotalToolsCount, registeredTools)
+		}
+	})
+	t.Run("should not register only readonly tools when readonly is set to false", func(t *testing.T) {
+		cfg := &config.Config{
+			URI:      "bolt://test-host:7687",
+			Username: "neo4j",
+			Password: "password",
+			Database: "neo4j",
+			ReadOnly: "false",
+		}
+		s := server.NewNeo4jMCPServer("test-version", cfg, mockDB)
+
+		// Expected tools that should be registered
+		// update this number when a tool is added or removed.
+		expectedTotalToolsCount := 4
+
+		// Register tools
+		err := s.RegisterTools()
+		if err != nil {
+			t.Fatalf("RegisterTools() failed: %v", err)
+		}
+		registeredTools := len(s.MCPServer.ListTools())
+
+		if expectedTotalToolsCount != registeredTools {
+			t.Errorf("Expected %d tools, but test configuration shows %d", expectedTotalToolsCount, registeredTools)
+		}
+	})
 }

internal/server/tools_register.go

@@ -13,14 +13,32 @@ func (s *Neo4jMCPServer) RegisterTools() error {
 		Config:    s.config,
 		DBService: s.dbService,
 	}
-	registerAllTools(s.MCPServer, deps)
+	registerEnabledTools(s.MCPServer, deps)
 	return nil
 }
 
-// registerAllTools registers all available MCP tools
-func registerAllTools(mcpServer *server.MCPServer, deps *tools.ToolDependencies) {
-	tools := getAllTools(deps)
-	mcpServer.AddTools(tools...)
+// registerEnabledTools registers all available MCP tools and adds them to the provided MCP server.
+// Tools are filtered according to the server configuration. For example, when the read-only
+// mode is enabled (e.g. via the NEO4J_READ_ONLY environment variable or the Config.ReadOnly flag),
+// any tool that performs state mutation will be excluded; only tools annotated as read-only will be registered.
+// Note: this read-only filtering relies on the tool annotation "readonly" (ReadOnlyHint). If the annotation
+// is not defined or is set to false, the tool will be added (i.e., only tools with readonly=true are filtered in read-only mode).
+func registerEnabledTools(mcpServer *server.MCPServer, deps *tools.ToolDependencies) {
+	all := getAllTools(deps)
+
+	// If read-only mode is enabled, expose only tools annotated as read-only.
+	if deps != nil && deps.Config != nil && deps.Config.ReadOnly == "true" {
+		readOnlyTools := make([]server.ServerTool, 0, len(all))
+		for _, t := range all {
+			if t.Tool.Annotations.ReadOnlyHint != nil && *t.Tool.Annotations.ReadOnlyHint {
+				readOnlyTools = append(readOnlyTools, t)
+			}
+		}
+		mcpServer.AddTools(readOnlyTools...)
+		return
+	}
+
+	mcpServer.AddTools(all...)
 }
 
 // getAllTools returns all available tools with their specs and handlers