Atlas GraphRAG, Neo4j, DataForSEO, and MCP

This repository contains a prototype for a graph-based project memory. It combines Graphiti, Neo4j, DataForSEO OnPage audits, a reusable Codex skill, and a read-only MCP server that lets Codex query projects, clients, tasks, and SEO audit results.

What This Project Includes

• Initial project memory seeding with Graphiti and Neo4j.
• A deterministic Cypher project map for direct visualization in Neo4j Browser.
• DataForSEO OnPage scripts, with sandbox-first and real-audit modes.
• Conversion of SEO findings into SeoAudit, SeoIssue, and Task nodes.
• A reusable Codex skill named seo-dataforseo-audit.
• A read-only MCP server named project_memory for querying the graph from Codex.

Local Setup

1. Copy the example environment file and add real credentials only to .env:

Copy-Item .env.example .env

2. Create and install the Python environment:

python -m venv venv
.\venv\Scripts\python.exe -m pip install -r requirements.txt

3. Make sure Neo4j is running locally and configure NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD in .env.

4. JavaScript scripts require Node.js 18 or newer.

Important: .env, node_modules, venv, reports, and generated files are ignored by Git. Do not commit real API keys or passwords.

Seed a Graphiti Project Memory

1. Start your local Neo4j database.
2. Check that .env contains OPENAI_API_KEY. Add NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD if your local Neo4j setup differs from the defaults.
3. Run:

.\venv\Scripts\python.exe seed_project_graph.py

This command clears the configured database and loads the Atlas GraphRAG project memory with vision, roles, scope, milestones, tasks, risks, and technical decisions.

Load a Direct Neo4j Project Map

If you want to see nodes and relationships immediately in Neo4j Browser without using OpenAI, run:

.\seed_project_map.ps1

This command also clears the current graph, but it creates deterministic nodes with labels such as Project, Client, ClientContact, Task, Technology, Risk, Milestone, and Decision.

Use the Interactive GraphRAG Console

.\venv\Scripts\python.exe main.py

Useful questions:

ask what technologies does the project use?
ask which tasks are blocked?
ask who is responsible for the MVP?
ask what risks does Atlas GraphRAG have?
ask which client owns the Website Blog project?
ask what ideas belong to the Website Blog project?
ask which tasks are still open for the blog?

You can also enter a new project note as free text. It will be stored as a new memory episode in the graph.

Test DataForSEO

Add your DataForSEO credentials to .env:

DATAFORSEO_LOGIN=your_dataforseo_login
DATAFORSEO_PASSWORD=your_dataforseo_password
SEO_TARGET_URL=https://your-blog.example

Then test the connection:

node .\dataforseo_test_connection.mjs

This test uses GET /v3/appendix/user_data, a DataForSEO endpoint that is safe for checking credentials before creating real paid OnPage tasks.

Next, test the OnPage flow in sandbox mode:

node .\dataforseo_onpage_sandbox.mjs

The sandbox uses test data, but it confirms that the OnPage API flow is wired correctly.

When you are ready to run a real audit limited to one page:

node .\dataforseo_onpage_real_audit.mjs --run-real

The script creates a real OnPage task with SEO_AUDIT_MAX_PAGES=1, waits for the result, and stores reports in the ignored reports directory.

If a task already exists and you have its Task ID, retrieve the report without creating another paid task:

node .\dataforseo_onpage_real_audit.mjs --task-id TASK_ID

To store the current SEO audit in Neo4j:

node .\add_seo_audit_to_graph.mjs

Inspect the Graph in Neo4j Browser

Quick queries:

MATCH (n) RETURN n LIMIT 50;

MATCH p=()-[r]-() RETURN p LIMIT 100;

MATCH (e:Episodic)
RETURN e.name, e.content
ORDER BY e.valid_at;

MATCH (p:Project)-[:FOR_CLIENT]->(c:Client)
OPTIONAL MATCH (c)-[:HAS_CONTACT]->(contact:ClientContact)
RETURN p.name AS project, c.name AS client, c.email AS email,
       c.phone AS phone, contact.name AS contact;

MATCH (p:Project {id: "website-blog"})-[:HAS_IDEA]->(idea:Idea)
RETURN p.name AS project, idea.name AS idea,
       idea.status AS status, idea.priority AS priority;

MATCH p=(:Project {id: "website-blog"})-[:HAS_SEO_AUDIT|FOUND|CREATES_TASK*1..3]-()
RETURN p;

Query the Graph from Codex with MCP

The mcp-project-memory server connects Codex to Neo4j in read-only mode. It allows Codex to answer questions about projects, clients, tasks, and SEO audits without modifying graph data.

From cmd, run the guided setup once:

cd /d C:\Users\yohan\prueba-graphiti
.\mcp-project-memory\setup.cmd

The installer installs the official MCP SDK, registers the server in Codex, and tests its tools. Manual setup is also possible:

cd /d C:\Users\yohan\prueba-graphiti\mcp-project-memory
npm.cmd install
codex mcp add project_memory -- node "C:\Users\yohan\prueba-graphiti\mcp-project-memory\server.mjs"
codex mcp list

If you prefer manual configuration, use the equivalent block in mcp-project-memory/codex-config.toml.example. Reopen this project in Codex and keep Neo4j running. To test the MCP server from the terminal:

npm.cmd run test:mcp

Example questions Codex can answer through MCP:

What projects are stored?
Which project belongs to Demo Client?
Show me the pending tasks for the website-blog project.
Which SEO audits are stored for the blog, and what issues were found?