# 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`:

```powershell
Copy-Item .env.example .env
```

2. Create and install the Python environment:

```powershell
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:

```powershell
.\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:

```powershell
.\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

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

Useful questions:

```text
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`:

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

Then test the connection:

```powershell
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:

```powershell
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:

```powershell
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:

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

To store the current SEO audit in Neo4j:

```powershell
node .\add_seo_audit_to_graph.mjs
```

## Inspect the Graph in Neo4j Browser

Quick queries:

```cypher
MATCH (n) RETURN n LIMIT 50;
```

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

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

```cypher
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;
```

```cypher
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;
```

```cypher
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:

```bat
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:

```bat
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:

```powershell
npm.cmd run test:mcp
```

Example questions Codex can answer through MCP:

```text
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?
```