Update documentation and contributing guidelines

CONTRIBUTING.md

@@ -0,0 +1,158 @@
+# Contributing to Neo4j MCP
+
+Thank you for your interest in contributing to the Neo4j MCP server! This document provides guidelines and information for contributors.
+
+## Code of Conduct
+
+This project follows the [Neo4j Community Guidelines](todo: missing link here). Please read and follow these guidelines to ensure a welcoming environment for everyone.
+
+## Project Status
+
+Active development; not yet production‑hardened.
+
+## Prerequisites
+
+- Go 1.25+ (see `go.mod`)
+- Git
+- A Neo4j instance (4.x or 5.x; 5.x recommended)
+- (Optional) APOC plugin for richer schema / procedures
+
+## Getting Started
+
+### Fork & Clone
+
+1. Fork the repository (GitHub guide: https://docs.github.com/en/get-started/quickstart/fork-a-repo)
+2. Clone your fork: `git clone https://github.com/<your-username>/mcp.git && cd mcp`
+3. Add upstream remote (to sync later): `git remote add upstream https://github.com/neo4j/mcp.git`
+
+### 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.
+
+Manual inspection (optional):
+
+```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,48 +1,45 @@
 # 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 production‑hardened.
 
-## 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/).
+- Any MCP-compatible client (ie. [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)
+
+Releases: https://github.com/neo4j/mcp/releases
 
-### 2. Set up Go Environment
+1. Download the archive for your OS/arch.
+2. Extract and place `neo4j-mcp` somewhere on your PATH (examples below).
 
-Ensure your Go environment is properly configured:
+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
+To verify basic startup (will wait for MCP host on stdio):
 
 ```bash
-go install -C cmd/neo4j-mcp
+neo4j-mcp # should block; Ctrl+C to stop
 ```
 
-This will install the `neo4j-mcp` binary to your `$GOBIN` directory.
-
-### 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
 {
@@ -61,51 +58,47 @@ Create or update your VSCode MCP configuration file (`mcp.json`), as document he
 }
 ```
 
-Adjust the environment variables according to your Neo4j instance configuration.
+<!-- TODO: add claude desktop MCP installation instructions -->
 
-Open the VSCode chat in agentic mode and ask about your configured Neo4j database.
+Notes:
 
-## Documentation
+- Adjust env vars for your setup (defaults shown above).
+- Desktop default URI: `bolt://localhost:7687`.
+- Aura: use the connection string from the Aura console.
+- Provide an absolute path to the binary if not on PATH.
 
-📚 **[Development Guide](docs/README.md)** - Testing, mockgen setup, and development workflows
+Restart VSCode; open Copilot Chat and ask: "List Neo4j MCP tools" to confirm.
 
-## Logging
+## Tools & Usage
 
-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.
+Provided tools:
 
-We achieve this by using Go's standard `log` package, which writes to stderr by default. This ensures:
+| Tool         | Purpose                                                                    | Notes                                        |
+| ------------ | -------------------------------------------------------------------------- | -------------------------------------------- |
+| `get-schema` | Introspect labels, relationship types, property keys, indexes, constraints | Read-only, safe to repeat                    |
+| `run-cypher` | Execute arbitrary Cypher (read/write)                                      | Use caution; respects Neo4j auth permissions |
 
-- **MCP Compliance**: stdout remains clean for JSON-RPC protocol messages
-- **Proper Stream Separation**: Application logs go to stderr, protocol messages to stdout
+Example natural language prompts (in Copilot / other MCP client):
 
-## Extra
-
-### Building and Running
-
-To build the project:
-
-```bash
-go build -C cmd/neo4j-mcp -o ../../bin/
 ```
-
-To run directly:
-
-```bash
-go run ./cmd/neo4j-mcp
+Get the database schema
 ```
 
-To install:
+```
+Find all Person nodes and their relationships
+```
 
-```bash
-go install -C cmd/neo4j-mcp
+```
+Create a new User node with name "John"
 ```
 
-### Testing with MCP Inspector
+Security tips:
 
-Use the MCP Inspector to test and explore the functionality:
+- Prefer a read-only Neo4j user for exploration.
+- Review generated Cypher before executing in production databases.
 
-```bash
-npx @modelcontextprotocol/inspector go run ./cmd/neo4j-mcp
-```
+## Documentation
+
+📚 **[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).