# Employee Graph MCP Server (completed)

Finishes module 4 of [neo4j-employee-graph](https://github.com/neo4j-product-examples/neo4j-employee-graph) by packaging **all** the workshop's tools into a single, ready-to-run MCP server.

## What the repo had vs. what's finished here

| Piece | Repo state | Here |
|---|---|---|
| Expert Cypher tools (modules 2–3) | Defined inline in notebooks + partial tools.yaml | All exposed as MCP tools in `server.py`, plus completed `tools.yaml` |
| Vector resume search (module 1) | Only a local Python function — **not in the MCP config** (Toolbox can't embed the prompt) | `search_resumes` tool: embeds the prompt with OpenAI, queries the `text_embeddings` vector index |
| Schema + free Cypher | Delegated to a separate `mcp-neo4j-cypher` server | Built in: `get_schema` and `read_neo4j_cypher` (read-only enforced, embedding-return blocked) |
| Meta context | `__MetaContext__` node written by module 4 | `get_context` tool, with a fallback if the node doesn't exist |
| tools.yaml | Generated with hard-coded credentials, no schema tool, no toolset | Completed template with env-var substitution, `get_schema`, and a `toolsets` block |

## Files

- `server.py` — the complete standalone MCP server (recommended)
- `person.py` — enums copied from the repo (Domain, WorkType, SkillName)
- `tools.yaml` — completed MCP Toolbox config, if you prefer the Toolbox route
- `requirements.txt`
- `claude_desktop_config.example.json`

## Prerequisites

Run modules 1–3 of the workshop first so the graph exists: `Person` nodes with `text` + `embedding` properties, the `text_embeddings` vector index, `Thing`/`Domain`/`WorkType`/`Skill` nodes, and HRIS project data.

## Setup

```bash
pip install -r requirements.txt
```

Set the same environment variables as the notebooks (or put them in `nb.env` / `.env`):

```bash
export NEO4J_URI="neo4j+s://xxxx.databases.neo4j.io"
export NEO4J_USERNAME="neo4j"
export NEO4J_PASSWORD="..."
export OPENAI_API_KEY="sk-..."   # for search_resumes embeddings
```

## Run

```bash
python server.py                              # stdio
MCP_TRANSPORT=streamable-http python server.py  # HTTP on :8000 for remote clients
```

Test with MCP Inspector:

```bash
npx @modelcontextprotocol/inspector python server.py
```

## Use from Claude Desktop

Copy `claude_desktop_config.example.json` contents into your Claude Desktop config (`mcpServers` section) and fix the paths/credentials.

## Use from Google ADK (as in the notebooks)

Replace the `mcp-neo4j-cypher` MCPToolset in module 2/3 with this server — the agent now gets the expert tools AND schema/cypher/vector search from one place:

```python
MCPToolset(
    connection_params=StdioServerParameters(
        command="python",
        args=["/path/to/server.py"],
        env={k: os.environ[k] for k in
             ["NEO4J_URI", "NEO4J_USERNAME", "NEO4J_PASSWORD", "OPENAI_API_KEY"]},
    )
)
```

## Tools exposed

1. `get_context` — meta context / system guidance from the `__MetaContext__` node (call first)
2. `search_resumes(search_prompt, k)` — semantic vector search over resumes
3. `find_similar_people(person_id, limit)`
4. `find_similarities_between_people(person1_id, person2_id)` — ascii path strings
5. `get_person_resume(person_id)`
6. `get_person_name(person_id)`
7. `get_person_ids_from_name(person_name)`
8. `find_collaborators_in_domain(domains)` — validated against the Domain enum
9. `get_schema` — labels, properties, relationship patterns (embedding excluded)
10. `read_neo4j_cypher(query, params)` — read-only; rejects write clauses and embedding returns