Update documentation and contributing guidelines

CONTRIBUTING.md

@@ -0,0 +1,154 @@
+# Contributing to Neo4j MCP
+
+Thank you for your interest in contributing to the Neo4j MCP server! This document provides guidelines and information for contributors.
+
+If you're an external contributor you must sign the [https://neo4j.com/developer/contributing-code/#sign-cla](https://neo4j.com/developer/contributing-code/#sign-cla)
+
+## Code of Conduct
+
+Please read and follow these guidelines to ensure a welcoming environment for everyone.
+
+## Prerequisites
+
+- Go 1.25+ (see `go.mod`)
+- A Neo4j instance with APOC plugin installed.
+
+## Clone the repository (forks are currently disabled)
+
+```bash
+git clone git@github.com:neo4j/mcp.git && cd mcp
+```
+
+## Install Dependencies
+
+```bash
+# Install Go dependencies
+go mod download
+
+# Install mock generator (only if you will change interfaces)
+go install go.uber.org/mock/mockgen@latest
+export PATH="$PATH:$(go env GOPATH)/bin"
+```
+
+## Build / Test / Run
+
+```bash
+# Tests (coverage)
+go test ./... -cover
+
+# Verbose / single package
+go test ./internal/tools -v
+
+# Build binary
+go build -C cmd/neo4j-mcp -o ../../bin/
+
+# Run from source
+go run ./cmd/neo4j-mcp
+
+# Optional: install
+go install -C cmd/neo4j-mcp
+```
+
+## Environment Variables
+
+For local testing, set these environment variables:
+
+```bash
+export NEO4J_URI="bolt://localhost:7687"
+export NEO4J_USERNAME="neo4j"
+export NEO4J_PASSWORD="password"
+export NEO4J_DATABASE="neo4j"
+```
+
+## Mocks
+
+We rely on interface-based dependency injection plus generated mocks (gomock) so tests run without a live Neo4j instance.
+
+Regenerate mocks ONLY after changing interfaces (e.g. `internal/database/interfaces.go`):
+
+```bash
+cd internal/database && go generate
+```
+
+Minimal gomock example:
+
+```go
+func TestMyFunction(t *testing.T) {
+    ctrl := gomock.NewController(t)
+    defer ctrl.Finish()
+
+    mockDB := mocks.NewMockDatabaseService(ctrl)
+    mockDB.EXPECT().
+        ExecuteReadQuery(gomock.Any(), "MATCH (n) RETURN n", gomock.Nil(), "neo4j").
+        Return([]*neo4j.Record{}, nil)
+
+    // Use mockDB in your test ...
+}
+```
+
+See `internal/tools/get_schema_handler_gomock_test.go` for a fuller pattern.
+
+## Testing using the @modelcontextprotocol/inspector:
+
+The Neo4j MCP capabilities can be tested using the `@modelcontextprotocol/inspector`:
+
+```bash
+npx @modelcontextprotocol/inspector go run ./cmd/neo4j-mcp
+```
+
+## Adding New MCP Tools
+
+1. **Define tool specification** in `internal/tools/`:
+
+   ```go
+   func NewMyToolSpec() mcp.Tool {
+       return mcp.NewTool("my-tool",
+           mcp.WithDescription("Tool description"),
+           mcp.WithInputSchema[MyToolInput](),
+       )
+   }
+   ```
+
+2. **Implement tool handler**:
+
+   ```go
+   func NewMyToolHandler(deps *ToolDependencies) mcp.ToolHandler {
+       return func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+           // Implementation
+       }
+   }
+   ```
+
+3. **Register in tool_register.go**:
+
+   ```go
+   {
+       Tool:    NewMyToolSpec(),
+       Handler: NewMyToolHandler(deps),
+   },
+   ```
+
+4. **Write tests** with mocked dependencies
+
+### Database Interface Extensions
+
+When adding new database operations:
+
+1. **Extend the interface** in `internal/database/interfaces.go`
+2. **Implement in service** in `internal/database/service.go`
+3. **Regenerate mocks**: `cd internal/database && go generate`
+4. **Update tests** to use new mock methods
+
+### Quick Fixes
+
+Mock generation fails → ensure `mockgen` on PATH.
+Tests failing unexpectedly → regenerate mocks, verify env vars, rerun full test suite.
+Dependency/build issues → `go mod tidy`.
+
+### Getting Help
+
+- Check existing [GitHub Issues](https://github.com/neo4j/mcp/issues)
+- Ask questions in pull request discussions
+- Reach out to maintainers for complex architectural questions
+
+Thank you for contributing to making Neo4j MCP better!

README.md

@@ -1,55 +1,55 @@
 # Neo4j MCP
 
-Official repository for the Neo4j MCP.
+Official Model Context Protocol (MCP) server for Neo4j.
 
 ## Status
 
-This project is currently under active development and is not ready for production use.
+Active development; not yet suitable for production
 
-## Setup
+## Prerequisites
 
-### 1. Clone the Repository
+- A running Neo4j database instance; either local [neo4j–desktop](https://neo4j.com/download/) or [Aura](https://neo4j.com/product/auradb/).
+- APOC plugin installed in the Neo4j instance.
+- Any MCP-compatible client (e.g. [VSCode](https://code.visualstudio.com/) with [MCP support](https://code.visualstudio.com/docs/copilot/customization/mcp-servers))
 
-```bash
-git clone https://github.com/neo4j/mcp.git
-cd mcp
-```
+## Installation (Binary)
 
-### 2. Set up Go Environment
+Releases: https://github.com/neo4j/mcp/releases
 
-Ensure your Go environment is properly configured:
+1. Download the archive for your OS/arch.
+2. Extract and place `neo4j-mcp` in a directory present in your PATH variables (see examples below).
+
+Mac / Linux:
 
 ```bash
-# Check Go installation
-go version
+chmod +x neo4j-mcp
+sudo mv neo4j-mcp /usr/local/bin/
 ```
 
-Set up GOPATH and GOBIN (if not already configured in your favorite shell file, such as: .bashrc,.zshrc)
+Windows (PowerShell / cmd):
 
-```bash
-export GOPATH=$HOME/go
-export GOBIN=$GOPATH/bin
-export PATH=$PATH:$GOBIN
+```powershell
+move neo4j-mcp.exe C:\Windows\System32
 ```
 
-### 3. Install the Neo4j MCP Server
+Verify the neo4j-mcp installation:
 
 ```bash
-go install -C cmd/neo4j-mcp
+neo4j-mcp -v
 ```
 
-This will install the `neo4j-mcp` binary to your `$GOBIN` directory.
+Should print the installed version.
 
-### 4. Configure VSCode MCP
+## Configure VSCode (MCP)
 
-Create or update your VSCode MCP configuration file (`mcp.json`), as document here:https://code.visualstudio.com/docs/copilot/customization/mcp-servers
+Create / edit `mcp.json` (docs: https://code.visualstudio.com/docs/copilot/customization/mcp-servers):
 
 ```json
 {
   "servers": {
     "neo4j": {
       "type": "stdio",
-      "command": "neo4j-mcp", // Use full path to binary or ensure neo4j-mcp is in PATH
+      "command": "neo4j-mcp",
       "env": {
         "NEO4J_URI": "bolt://localhost:7687",
         "NEO4J_USERNAME": "neo4j",
@@ -61,57 +61,69 @@ Create or update your VSCode MCP configuration file (`mcp.json`), as document he
 }
 ```
 
-Adjust the environment variables according to your Neo4j instance configuration.
+Restart VSCode; open Copilot Chat and ask: "List Neo4j MCP tools" to confirm.
 
-Open the VSCode chat in agentic mode and ask about your configured Neo4j database.
+## Configure Claude Desktop
 
-## Documentation
-
-📚 **[Development Guide](docs/README.md)** - Testing, mockgen setup, and development workflows
+First, make sure you have Claude for Desktop installed. [You can install the latest version here](https://claude.ai/download).
 
-## Logging
+We’ll need to configure Claude for Desktop for whichever MCP servers you want to use. To do this, open your Claude for Desktop App configuration at:
 
-This project follows the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) recommendation that all log output should be written to **stderr** to keep **stdout** clean for protocol communication.
+- (MacOS/Linux) `~/Library/Application Support/Claude/claude_desktop_config.json`
+- (Windows) `$env:AppData\Claude\claude_desktop_config.json`
 
-We achieve this by using Go's standard `log` package, which writes to stderr by default. This ensures:
+in a text editor. Make sure to create the file if it doesn’t exist.
 
-- **MCP Compliance**: stdout remains clean for JSON-RPC protocol messages
-- **Proper Stream Separation**: Application logs go to stderr, protocol messages to stdout
+You’ll then add the `neo4j-mcp` MCP in the mcpServers key:
 
-## Extra
+```json
+{
+  "mcpServers": {
+    "neo4j-mcp": {
+      "type": "stdio",
+      "command": "neo4j-mcp",
+      "args": [],
+      "env": {
+        "NEO4J_URI": "bolt://localhost:7687",
+        "NEO4J_USERNAME": "neo4j",
+        "NEO4J_PASSWORD": "password",
+        "NEO4J_DATABASE": "neo4j"
+      }
+    }
+  }
+}
+```
 
-### Building and Running
+Notes:
 
-To build the project:
+- Adjust env vars for your setup (defaults shown above).
+- Neo4j Desktop default URI: `bolt://localhost:7687`.
+- Aura: use the connection string from the Aura console.
 
-```bash
-go build -C cmd/neo4j-mcp -o ../../bin/
-```
+## Tools & Usage
 
-Check the version:
+Provided tools:
 
-```bash
-go run ./cmd/neo4j-mcp -v
-```
+| 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. |
 
-To run directly:
+## Example Natural Language Prompts
 
-```bash
-go run ./cmd/neo4j-mcp
-```
+Below are some example prompts you can try in Copilot or any other MCP client:
 
-To install:
+- "What does my Neo4j instance contain? List all node labels, relationship types, and property keys."
+- "Find all Person nodes and their relationships in my Neo4j instance."
+- "Create a new User node with a name 'John' in my Neo4j instance."
 
-```bash
-go install -C cmd/neo4j-mcp
-```
+## Security tips:
 
-### Testing with MCP Inspector
+- Use a restricted Neo4j user for exploration.
+- Review generated Cypher before executing in production databases.
 
-Use the MCP Inspector to test and explore the functionality:
+## Documentation
 
-```bash
-npx @modelcontextprotocol/inspector go run ./cmd/neo4j-mcp
-```
+📚 **[Contributing Guide](CONTRIBUTING.md)** – Contribution workflow, development environment, mocks & testing.
 
-This will launch the MCP Inspector interface where you can interact with the Neo4j MCP server and test the read-cypher capabilities.
+Issues / feedback: open a GitHub issue with reproduction details (omit sensitive data).