NeoCoder

You run an MCP server that connects a Neo4j knowledge graph with vector-based search to power context-aware AI workflows. This hybrid system coordinates data from structured graphs and semantic vectors, enabling reliable workflows, strong provenance, and scalable knowledge reasoning for coding, research, and decision support.

How to use

You interact with the NeoCoder MCP server through your MCP client or Claude Desktop integration. Start the local MCP server, ensure your Neo4j and Qdrant services are running, and then connect your AI assistant to the neocoder MCP endpoint. The system exposes encoded workflows and templates that guide tasks from task identification through to execution and auditing, with each knowledge claim tied to its source.

Typical usage pattern: choose a task such as coding, research synthesis, or decision analysis. The system routes your query to the appropriate incarnations and templates, fetches the relevant instructions from the graph, executes the guided workflow, and records the workflow execution in the audit trail. You can switch incarnations at runtime if you need a different working mode. Pay attention to citations and verification steps that are mandatory before marking a workflow as complete.

How to install

Prerequisites you must have running locally or accessible remotely:

Steps to set up the development environment and run NeoCoder in your workspace:

# 1. Clone the repository
git clone https://github.com/angrysky56/NeoCoder-neo4j-ai-workflow.git
cd NeoCoder-neo4j-ai-workflow

# 2. Set up Python environment (recommended via pyenv)
pyenv install 3.11.12  # if not already installed
pyenv local 3.11.12
uv venv
source .venv/bin/activate

# 3. Install dependencies
uv pip install -e '.[dev,docs,gpu]'

# 4. Start Neo4j and Qdrant (examples)
# Neo4j should be running and accessible at bolt://localhost:7687
# Qdrant (persistent storage)
docker run -p 6333:6333 -p 6334:6334 
  -v "$(pwd)/qdrant_storage:/qdrant/storage:z" 
  qdrant/qdrant

# 5. Optional client integration (Claude Desktop)
# See Claude integration snippet for exact mcpServer config

Configuration, security, and notes

Claude Desktop integration uses a single MCP stdio server configuration to connect the local MCP process to Claude. The following config runs the MCP server from a local directory and passes necessary environment variables for Neo4j access and transport mode.

{
  "mcpServers": {
    "neocoder": {
      "command": "uv",
      "args": [
        "--directory",
        "/your-path-to/NeoCoder-neo4j-ai-workflow",
        "run",
        "mcp_neocoder"
      ],
      "env": {
        "NEO4J_URL": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-neo4j-password-here",
        "NEO4J_DATABASE": "neo4j",
        "LOG_LEVEL": "INFO",
        "MCP_TRANSPORT": "stdio",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Troubleshooting and notes

If you encounter connectivity or initialization issues, verify that Neo4j is up and the password matches the environment variable NEO4J_PASSWORD. Ensure Qdrant is running and accessible at the correct ports. Activate your virtual environment before launching commands, and confirm that the Python version matches the project requirements. If you need to refresh dependencies, delete the .venv directory and recreate it using the steps above.

Available tools

check_connection

Verify Neo4j connection status to ensure the graph API is reachable.

get_guidance_hub

Access the central guidance hub to navigate best practices and templates.

get_action_template

Fetch a specific workflow template from the graph.

list_action_templates

List all available workflow templates stored in the system.

get_best_practices

Retrieve coding standards and best practices for reference.

get_project

View project details including its README and structure.

list_projects

List all projects managed by the MCP server.

log_workflow_execution

Record a completed workflow run in the audit trail.

get_workflow_history

Query the history of workflow executions for auditing.

add_template_feedback

Provide feedback on templates to improve guidance.

run_custom_query

Execute direct Cypher queries when needed.

write_neo4j_cypher

Perform write operations on the graph through Cypher.

get_current_incarnation

Query the currently active incarnation.

list_incarnations

List all available incarnations.

switch_incarnation

Switch to a different incarnation at runtime.

suggest_tool

Suggest tools based on a given task description.

KNOWLEDGE_QUERY

Hybrid Knowledge Query Workflow for intelligent multi-source reasoning.

KNOWLEDGE_EXTRACT

Dynamic knowledge extraction workflow with F-Contraction merging.

CODE_ANALYZE

Code analysis workflow using AST/ASG tools.