Employee Graph MCP Server (completed)

Finishes module 4 of 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

pip install -r requirements.txt

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

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

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

Test with MCP Inspector:

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:

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