name: develop-neo4j-graph
description: Develop Neo4j graphs end-to-end: analyze source data, design data models, ingest CSV and/or PDF data, extract entities, and validate with queries. Use when importing data to Neo4j, designing graph data models, creating knowledge graphs, or building chatbots or analytical applications backed by Neo4j.
Develop Neo4j Graph
Pre-flight: Confirm Models
Before starting, read .env and report the configured models:
EMBEDDING_MODEL — used by embed_chunksEXTRACTION_MODEL — used by extract_entities
Never substitute, correct, or override these values. Model names in .env are user-configured and may include models you don't recognize (recently released models, LiteLLM aliases, custom endpoints). If a name looks unfamiliar, that is intentional — use it as-is.
If extraction or embedding fails with a model error, report the exact error and stop. Do not silently switch to a different model.
Progress Checklist
Copy this checklist to track progress:
- [ ] Step 1: Discovery — read source data, identify entities
- [ ] Step 2: Use case discussion → determine MODE (CHATBOT or ANALYTICAL)
- [ ] Step 3: Graph data model
- [ ] Step 4: Ingest data (CSV and/or PDF)
- [ ] Step 4.5: Verify ingestion counts
- [ ] Step 5 [PDF only]: Export schema and review validators
- [ ] Step 6 [PDF only]: Extract entities
- [ ] Step 7 [PDF only]: Verify extraction results
- [ ] Step 8: Output [MODE-SPECIFIC]
Step 1: Discovery
Read source data samples to understand content and structure. Do not use MCP tools at this stage.
CSV data: Read samples from data/csv/. Reference HANDLE_STRUCTURED_DATA.md for discovery guidance, including the cross-file ID consistency check.
PDF data: List files in data/pdf/ (and subfolders) using Glob. For each PDF, use the Read tool with pages: "1-2" to sample content. Reference the Parse Mode Guide in HANDLE_UNSTRUCTURED_DATA.md to identify the appropriate parse mode for each document type.
Summarize what you found: data types present, content domain, entity types visible, structural observations.
Step 2: Use Case Discussion → Mode Selection
Ask the user what they want to accomplish with the data. Do not ask them to choose a mode explicitly.
To determine the mode, ask yourself: does the user describe how someone will interact with the application (natural language Q&A), or what the data should reveal (patterns, aggregations, cohort analysis)?
-
CHATBOT mode signals: user mentions asking questions, a chatbot, a search interface, natural language queries, or retrieving answers on demand. The interaction is the point.
-
ANALYTICAL mode signals: user mentions tracking, identifying patterns, correlations, treatment outcomes, cohort comparisons, monitoring, or surfacing insights across the dataset. The findings are the point — even if the result will power an application.
When ambiguous (e.g. "building an application" without specifying how users interact with it, or "connect X with Y" which could be retrieval or analysis), ask one clarifying question:
"Will users primarily explore the data through natural language questions, or should the application surface structured patterns and reports from the data?"
Set MODE = CHATBOT or ANALYTICAL. State it clearly. You will return to this at Step 8.
Step 3: Graph Data Model
Reference GRAPH_DATA_MODELING_MCP.md for the full modeling process using the neo4j-data-modeling MCP server.
If handling both CSV and PDF data, design four distinct sub-models, each visualized separately with get_mermaid_config_str:
- Structured data model — nodes and relationships derived from CSV only
- Entity extraction model — focused subset of nodes to extract from PDFs via LLM; must partially overlap with the structured model via bridge nodes (merged on a shared key property such as
name)
- Lexical graph model —
Document → Chunk, created by neo4j-lexical-graph; no design needed, provided by the server
- Unified model — all three layers combined; show explicitly how extracted entities connect to structured nodes (bridge nodes + MERGE key)
[CHATBOT mode] Map each confirmed target question to the nodes/relationships that will answer it. Flag any questions the current model cannot address.
Save the final model JSON to outputs/data_models/<topic>_data_model.json.
Step 4: Ingest Data
CSV data — neo4j-ingest
Reference HANDLE_STRUCTURED_DATA.md for ingestion details.
Always use absolute paths. Use ingest_csv_into_neo4j.
PDF data — neo4j-lexical-graph
Load the mode-specific reference file for the exact tool sequence:
Quick reference (all modes):
| Step | Tool | pymupdf | docling | page_image | vlm_blocks |
|---|
| 1 | create_lexical_graph | ✓ | ✓ | ✓ | ✓ |
| 2 | chunk_lexical_graph | ✗ skip | ✓ | ✓ | ✓ |
| 3 | list_documents | ✓ | ✓ | ✓ | ✓ |
| 4 | verify_lexical_graph | optional | optional | ✗ never | optional |
| 5 | assign_section_hierarchy | ✗ skip | optional | ✗ skip | optional |
| 6 | generate_chunk_descriptions | if images/tables | if images/tables | required | if images/tables |
| 7 | embed_chunks | ✓ | ✓ | ✓ | ✓ |
generate_chunk_descriptions — call without document_id to run for all active documents at once.
embed_chunks — call with no parameters. Auto-detects textDescription and applies the right embedding strategy (VLM descriptions for Table/Image/Page nodes, raw text for others — all in one unified index).
Step 4.5: Verify Ingestion Counts
After all ingestion is complete, run count checks for every node label and key relationship type using read_neo4j_cypher from neo4j-graphrag:
MATCH (n:NodeLabel) RETURN COUNT(n) AS count
For CSV nodes: verify counts match source row counts (accounting for deduplication).
Check for orphan nodes:
MATCH (n:NodeLabel) WHERE NOT (n)--() RETURN COUNT(n) AS orphans
If orphans are found, check for cross-file ID mismatches before proceeding.
Step 5 [PDF only]: Export Schema and Review Validators
Use convert_schema from neo4j-entity-graph — not export_to_pydantic_models from the data-modeling server.
- Input: the entity extraction sub-model (not the full unified model)
- Set
output_path to outputs/schemas/<topic>_schema.json
- Output:
<topic>_schema.json (extraction config) + <topic>_schema.json.py (Pydantic models)
Review the Pydantic .py file. For each node's key property, verify or add a normalizing validator:
@field_validator('name')
@classmethod
def normalize_name(cls, v: str) -> str:
return v.strip().lower()
This prevents duplicate nodes from minor text variations (e.g. "Aspirin" vs "aspirin "). Present the validators to the user and confirm before proceeding.
Step 6 [PDF only]: Extract Entities
Use extract_entities from neo4j-entity-graph:
- Pass the schema JSON path from Step 5
- Extraction is async — poll with
check_extraction_status until complete
- Report progress to the user: chunks processed, entities found so far
Step 7 [PDF only]: Verify Extraction Results
Use read_neo4j_cypher from neo4j-graphrag:
-- Count per label
MATCH (n:NodeLabel) RETURN count(n) as count
-- Check for duplicates on key property
MATCH (n:NodeLabel)
WITH n.keyProp as key, count(*) as cnt
WHERE cnt > 1
RETURN key, cnt ORDER BY cnt DESC LIMIT 10
-- Verify entity-chunk links
MATCH (n)-[:EXTRACTED_FROM]->(c:Chunk) RETURN count(*) as entity_chunk_links
If CSV data is also present, run entity reconciliation to check for name mismatches between extracted and structured nodes. See HANDLE_UNSTRUCTURED_DATA.md.
If significant duplicates: document them for next iteration. Do not re-run extraction.
Step 8: Output [MODE-SPECIFIC]
Reminder — current MODE: CHATBOT or ANALYTICAL (set in Step 2).
[CHATBOT mode] → Load CHATBOT_MODE.md:
Answer each confirmed target question using neo4j-graphrag tools (vector search, fulltext search, Cypher, read_node_image), then generate the chatbot report saved to outputs/reports/<topic>_chatbot_report.md.
[ANALYTICAL mode] → Load ANALYTICAL_MODE.md:
Generate Cypher queries per use case in YAML format, validate them against the graph, then generate the analytical report saved to outputs/reports/<topic>_report.md.
MCP Server Quick Reference
| Server | Steps | Key Tools |
|---|
neo4j-data-modeling | 3 | list_example_data_models, get_example_data_model, get_mermaid_config_str, validate_data_model |
neo4j-ingest | 4 | ingest_csv_into_neo4j |
neo4j-lexical-graph | 4 | create_lexical_graph, chunk_lexical_graph, list_documents, generate_chunk_descriptions, embed_chunks, check_processing_status, verify_lexical_graph (spot-check, single doc only), assign_section_hierarchy (optional) |
neo4j-entity-graph | 5–6 | convert_schema, extract_entities, check_extraction_status |
neo4j-graphrag | 4.5–8 | read_neo4j_cypher, write_neo4j_cypher, get_neo4j_schema_and_indexes, vector_search, fulltext_search, search_cypher_query, read_node_image |
