Imported from neo4j-field/neo4j-mcp-workspace-template (AGENTS.md). Install upstream with npx skills add neo4j-field/neo4j-mcp-workspace-template. Copyright stays with the author.

Agent Context — neo4j-mcp-workspace-template

This file is read by multiple coding agents (Codex CLI, Mistral Vibe, and others that follow the shared AGENTS.md convention) — do not assume a specific tool or a specific generated MCP config file/path when following it.

1. Setup Status Check

On every session start, verify the following before doing any work:

# Check .env exists
test -f .env && echo ".env OK" || echo ".env MISSING"

Then check MCP readiness directly, not by checking for a specific config file — different tools generate different config files/paths (e.g. .codex/config.toml for Codex CLI, .vibe/config.toml for Mistral Vibe, .mcp.json for Claude Code) and this file has no reliable way to know which one your tool uses. Instead, call the list_example_data_models tool (from neo4j-data-modeling, which needs no credentials) directly. If it responds, MCP is loaded — proceed.

If .env is missing, tell the user:

"Run ./setup.sh first to configure credentials and MCP servers, then restart this tool."

If .env exists but list_example_data_models (or any other neo4j-* tool) is not available to you, tell the user:

"MCP servers are configured but not loaded. Restart this tool from this directory to load them."

Do not attempt graph operations if Neo4j MCP tools are unavailable.

2. Project Structure

neo4j-mcp-workspace-template/
├── setup.sh                        # Run once before opening the tool
├── .env                            # Credentials (gitignored, created by setup.sh)
├── .env.example                    # Documents all variables — no secrets
├── AGENTS.md                       # This file (read by Codex CLI, Mistral Vibe, and others)
├── .codex/config.toml               # Generated by setup.sh (gitignored) — Codex CLI MCP config
├── .vibe/config.toml                # Mistral Vibe MCP config (gitignored) — not yet generated by setup.sh
├── .agents/
│   └── skills/
│       └── develop-neo4j-graph/    # Cross-tool skill (Agent Skills standard)
│           ├── SKILL.md
│           └── references/
├── data/                           # Input data (gitignored contents, tracked structure)
│   ├── csv/                        # Structured data
│   └── pdf/                        # PDF documents
├── outputs/                        # Generated outputs (gitignored contents, tracked structure)
│   ├── data_models/                # Graph data model JSON files
│   ├── queries/                    # Cypher query YAML files
│   ├── reports/                    # Markdown reports
│   └── schemas/                    # Pydantic extraction schema files
├── mcp-neo4j-ingest/               # Local: structured CSV ingestion server
├── mcp-neo4j-lexical-graph/        # Local: PDF → lexical graph server
├── mcp-neo4j-entity-graph/         # Local: entity extraction server
└── mcp-neo4j-graphrag/             # Local: cloned by setup.sh (gitignored)

3. MCP Servers Reference

Five MCP servers are configured for this workspace:

neo4j-data-modeling

• Purpose: Design and validate graph schemas from sample data
• Key tools: list_example_data_models, get_example_data_model, get_mermaid_config_str
• Required env: none (stateless)

neo4j-ingest

• Purpose: Load structured CSV data into Neo4j
• Key tools: ingest_csv_into_neo4j
• Required env: reads from .env via python-dotenv

neo4j-lexical-graph

• Purpose: Parse PDFs into a searchable graph with chunk nodes and embeddings
• Required env: reads from .env via python-dotenv

neo4j-entity-graph

• Purpose: Extract structured entities from lexical graph chunks using LLM
• Required env: reads from .env via python-dotenv

Two extraction paths — choose one per project:

Additional tools: check_extraction_status, cancel_extraction

neo4j-graphrag

• Purpose: Query and write the graph using vector search, fulltext search, and Cypher
• Key tools: get_neo4j_schema_and_indexes, vector_search, fulltext_search, read_neo4j_cypher, write_neo4j_cypher, search_cypher_query, read_node_image
• Required env: reads from .env via python-dotenv

4. Primary Workflow

Invoke the develop-neo4j-graph skill using your tool's own convention (e.g. $develop-neo4j-graph in Codex CLI), or simply describe your task — most tools auto-trigger the skill from its description when they detect a graph development use case.

The full workflow is in .agents/skills/develop-neo4j-graph/SKILL.md.

Workflow steps:

1. Analyze source data samples
2. Discuss use case → infer CHATBOT or ANALYTICAL mode
3. Design graph data model (neo4j-data-modeling)
4. Ingest data — CSV (neo4j-ingest) and/or PDF (neo4j-lexical-graph + neo4j-entity-graph)
5. Verify ingestion counts (neo4j-graphrag) 6–7. [PDF only] Schema export, entity extraction, verify — file-based (convert_schema) or ontology DB (generate_schema_from_ontology)
6. Output — Q&A report (CHATBOT) or Cypher analysis (ANALYTICAL)

5. Credential Management

• Never ask the user for credentials. They are in .env and read by each MCP server automatically.
• Never read or print passwords from .env.
• Never modify your tool's generated MCP config file (e.g. .codex/config.toml, .vibe/config.toml). Direct the user to re-run ./setup.sh if credentials need updating.

6. Common Failure Modes

7. What NOT to Do

• Do not run uv sync in the workspace root — each server has its own pyproject.toml
• Do not use relative paths in Cypher LOAD CSV or ingest tool calls — always use absolute paths
• Do not commit .env or any generated MCP config file (.codex/config.toml, .vibe/config.toml, etc.) — they are gitignored