mcp-neo4j-knowledge-graph: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

@henrychong-ai/mcp-neo4j-knowledge-graph is a Model Context Protocol (MCP) server implementing a Neo4j-based knowledge graph with temporal versioning and semantic search capabilities. Maintained by Henry Chong, built on foundational work by Gannon Hall.

Key Features:

• Temporal versioning for entities and relations (track historical changes)
• Neo4j graph database as primary storage backend
• Vector embeddings and semantic search via OpenAI
• MCP server for Claude Desktop and Claude Code integration
• Full test coverage with Vitest

Public Repository

This repository is public. Maintainer-only operational notes, when present, are in the untracked CLAUDE.local.md.

Public-content gate: pnpm run public:check (scripts/check-public-sanitization.mjs) reads every git-tracked file, and every tracked file name, and fails on:

Rule	Fails on	Passes
Personal home path	a home directory under /Users with a real name	a placeholder name (you, username, <name>)
Secret reference	an op:// reference that names a real vault	the bare scheme in prose; a placeholder vault (your-…, example…, vault)
Account host	a named 1Password account host	the shared sign-in hosts; your-… and example… names
Tailnet host	any *.ts.net name	a your-…, example… or tailnet… label
Private server name	the vps-<n> form	nothing
Server deployment path	the two server directories under /opt that hold deployment backups and scripts	any other /opt path
Email address	any address	reserved example domains, GitHub no-reply addresses, the contact published in package.json
Known private identifier	a 32-character hexadecimal token whose SHA-256 is on the list in the script	every other token

• Where it runs: pnpm run check; the last step of .husky/pre-commit (with --staged, which reads the staged content the commit will contain rather than the files on disk); its own CI step. On a public repository CI reports a leak only after the push, so the pre-commit step is the one that prevents it. Never commit with --no-verify.
• Never write a private value into the script, its tests or any doc. An exact identifier goes in as its SHA-256 only (hash the lowercase value with no trailing newline). Everything else is matched by shape.
• The script and its tests are scanned too. Describe a forbidden shape in words; in tests, build it from fragments at runtime.
• A finding is fixed, not allow-listed. Replace the value with a placeholder, or move the note to CLAUDE.local.md. Widening an allow list is the owner's decision.
• A finding names the file, line and rule, never the matched text. CI logs of a public repository are public.
• Out of reach: untracked and git-ignored files, commit messages, git history, and text that is not UTF-8.