# NeoCoder Neo4j Ai Workflow > An MCP server allowing AI assistants to use a Neo4j knowledge graph as their primary, dynamic instruction manual and long term project memory with adaptive templating and autonomous tool development tools. - **Type:** MCP server - **Install:** `agentstack add mcp-angrysky56-neocoder-neo4j-ai-workflow` - **Verified:** Pending review - **Seller:** [angrysky56](https://agentstack.voostack.com/s/angrysky56) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [angrysky56](https://github.com/angrysky56) - **Source:** https://github.com/angrysky56/NeoCoder-neo4j-ai-workflow ## Install ```sh agentstack add mcp-angrysky56-neocoder-neo4j-ai-workflow ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About [](https://mseep.ai/app/angrysky56-neocoder-neo4j-ai-workflow) # NeoCoder: Neo4j-Guided AI Coding Workflow An MCP server implementation that enables AI assistants like Claude to use a Neo4j knowledge graph as their primary, dynamic "instruction manual" and project memory for standardized coding workflows. # NeoCoder: Hybrid AI Reasoning & Workflow System An advanced MCP server implementation that combines Neo4j knowledge graphs, Qdrant vector databases, and sophisticated AI orchestration to create a hybrid reasoning system for knowledge management, research analysis, and standardized workflows. ## Overview NeoCoder implements a revolutionary **Context-Augmented Reasoning** system that goes far beyond traditional RAG (Retrieval-Augmented Generation) by combining: ### **Core Architecture:** 1. **Neo4j Knowledge Graphs** - Authoritative structured facts, relationships, and workflows 2. **Qdrant Vector Databases** - Semantic search, similarity detection, and contextual understanding 3. **MCP Orchestration** - Intelligent routing between data sources with synthesis and citation 4. **F-Contraction Synthesis** - Dynamic knowledge merging that preserves source attribution ### **Key Capabilities:** - **Hybrid Knowledge Reasoning**: Seamlessly combine structured facts with semantic context - **Dynamic Knowledge Extraction**: Process documents, code, and conversations into interconnected knowledge structures - **Citation-Based Analysis**: Every claim tracked to its source across multiple databases - **Multi-Incarnation System**: Specialized modes for coding, research, decision support, and knowledge management - **Intelligent Workflow Templates**: Neo4j-guided procedures with mandatory verification steps ### **Revolutionary Features:** 🧠 **Smart Query Routing**: AI automatically determines optimal data source (graph, vector, or hybrid) 🔬 **Research Analysis Engine**: Process academic papers with citation graphs and semantic content ⚡ **F-Contraction Processing**: Dynamically merge similar concepts while preserving provenance 🎯 **Context-Augmented Reasoning**: Generate insights impossible with single data sources 📊 **Full Audit Trails**: Complete tracking of knowledge synthesis and workflow execution 🛡️ **Production-Ready Process Management**: Automatic cleanup, signal handling, and resource tracking to prevent process leaks 🔧 **Enhanced Tool Handling**: Robust async initialization with proper background task management New from an idea I had- **Lotka-Volterra Ecological Framework** integrated into Knowledge Graph Incarnation ## Process Management & Reliability NeoCoder implements comprehensive process management following MCP best practices: - **Signal Handlers**: Proper SIGTERM/SIGINT handling for graceful shutdowns - **Resource Tracking**: Automatic tracking of processes, Neo4j connections, and background tasks - **Zombie Cleanup**: Active detection and cleanup of orphaned server instances - **Memory Management**: Prevention of resource leaks through proper cleanup patterns - **Background Task Management**: Safe handling of async initialization and concurrent operations - **Connection Pooling**: Efficient Neo4j driver management with automatic cleanup ### Monitoring Commands Use these tools to monitor server health: - `get_cleanup_status()` - View resource usage and cleanup status - `check_connection()` - Verify Neo4j connectivity and permissions ## Quick Start ### Prerequisites - **Neo4j**: Running locally or remote instance (for structured knowledge graphs) - **Qdrant**: Vector database for semantic search and embeddings (for hybrid reasoning) - **Python 3.10+**: For running the MCP server - **uv**: The Python package manager for MCP servers - **Claude Desktop**: For using with Claude AI - [MCP-Desktop-Commander](https://github.com/wonderwhy-er/DesktopCommanderMCP): Invaluable for CLI and filesystem operations - For the Lotka-Volterra Ecosystem and generally enhanced abilities- - [wolframalpha-llm-mcp](https://github.com/Garoth/wolframalpha-llm-mcp): really nice! - [mcp-server-qdrant-enhanced](https://github.com/angrysky56/mcp-server-qdrant-enhanced): My qdrant-enhanced mcp server - **Optional for more utility** - [arxiv-mcp-server](https://github.com/blazickjp/arxiv-mcp-server) **This incarnation is still being developed** - [For Code Analysis Incarnation: AST/ASG](https://github.com/angrysky56/ast-mcp-server): Currently needs development and an incarnation re-write - Get a free API key from WolframAlpha: To get a free API key (AppID) for Wolfram|Alpha, you need to sign up for a Wolfram ID and then register an application on the Wolfram|Alpha Developer Portal. Create a Wolfram ID: If you don't already have one, create a Wolfram ID at https://account.wolfram.com/login/create Navigate to the Developer Portal: Once you have a Wolfram ID, sign in to the Wolfram|Alpha Developer Portal https://developer.wolframalpha.com/portal/myapps Sign up for your first AppID: Click on the "Sign up to get your first AppID" button. Fill out the AppID creation dialog: Provide a name and a simple description for your application. Receive your AppID: After filling out the necessary information, you will be presented with your API key, also referred to as an AppID. The Wolfram|Alpha API is free for non-commercial usage, and you get up to 2,000 requests per month. Each application requires its own unique AppID. ## The MCP server runs the Python code, bridging the gap between the Neo4j graph and the AI assistant ( e.g. Claude) ### Installation #### 1. Clone the repository ```bash git clone https://github.com/angrysky56/NeoCoder-neo4j-ai-workflow.git cd NeoCoder-neo4j-ai-workflow ``` #### 2. Set up Python and the virtual environment Make sure you have [pyenv](https://github.com/pyenv/pyenv) and [uv](https://github.com/astral-sh/uv) installed. ```bash pyenv install 3.11.12 # if not already installed pyenv local 3.11.12 uv venv source .venv/bin/activate ``` #### 3. Install dependencies ```bash uv pip install -e '.[dev,docs,gpu]' ``` #### 4. Start Neo4j and Qdrant - **Neo4j:** Start your Neo4j server (locally or remote). Default connection: `bolt://localhost:7687` Neo4j connection parameters: - **URL**: `bolt://localhost:7687` (default) - **Username**: `neo4j` (default) - **Password**: Your Neo4j database password - **Database**: `neo4j` (default) Set credentials via environment variables if needed: - `NEO4J_URL` - `NEO4J_USERNAME` - `NEO4J_PASSWORD` - `NEO4J_DATABASE` - **Qdrant:** For persistent Qdrant storage, use this Docker command (recommended): ```bash docker run -p 6333:6333 -p 6334:6334 \ -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \ qdrant/qdrant ``` This will store Qdrant data in a `qdrant_storage` folder in your project directory. #### 5. (Optional) VS Code users - Open the Command Palette (`Ctrl+Shift+P`), select **Python: Select Interpreter**, and choose `.venv/bin/python`. 1. It should auto-install when using the config- not sure anymore haven't tried that and some dependencies are rather large. #### Potential Quickstart- lol sorry ## Recommended: Claude Desktop Integration: Configure Claude Desktop by adding the following to your `claude-app-config.json`: ```json { "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" } } } } ``` **Important**: The password in this configuration must match your Neo4j database password. Otherwise- Install dependencies: **Quick Troubleshooting:** - If you see errors about missing packages, double-check that your `.venv` is activated and you are using the correct Python version. - If you need to reset your environment, you can remove `.venv` and repeat the steps above. - Can't conect to DB? Install neo4j Desktop and QDRANT. Make sure they are running. NEO4J requires a password set. ```bash docker pull qdrant/qdrant docker run -p 6333:6333 -p 6334:6334 \ -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \ qdrant/qdrant ``` --- **You are now ready to use NeoCoder with full Neo4j and Qdrant hybrid Lotka-Volterra Ecosystem reasoning!** ## Suggested system prompt ```plaintext > **System Instruction:** You are an AI assistant integrated with a Neo4j knowledge graph that defines our standard procedures and tracks project changes. > > **Your Core Interaction Loop:** > 1. **Identify Task & Keyword:** Determine the action required (e.g., fix a bug -> `FIX`). > 2. **Consult the Hub:** If unsure about keywords or process, start by querying `:AiGuidanceHub {id: 'main_hub'}` for guidance and links to best practices or other guides. > 3. **Retrieve Instructions:** Formulate a Cypher query to fetch the `steps` from the current `:ActionTemplate` matching the keyword (e.g., `MATCH (t:ActionTemplate {keyword: 'FIX', isCurrent: true}) RETURN t.steps`). Execute this query. > 4. **Execute Guided Workflow:** Follow the retrieved `steps` meticulously. This includes reviewing project READMEs, implementing changes, and critically: > 5. **Perform Verification:** Execute the testing steps defined in the template. **ALL required tests MUST pass before you consider the task complete.** > 6. **Record Completion (Post-Testing):** Only if tests pass, formulate and execute the Cypher query specified in the template to create a `:WorkflowExecution` node, linking it appropriately. Do NOT record if tests failed. > 7. **Finalize Updates:** Update the project's README content (in Neo4j or the file) as per the template's instructions. > > **Strict Rule:** Always prioritize instructions retrieved from the Neo4j graph over your general knowledge for workflow procedures. Use the graph as your single source of truth for *how* tasks are done here. --- > **knowledge_graph_incarnation with integrated Lotka Volterra Special System Instruction:** You are an AI assistant integrated with a sophisticated hybrid reasoning system that combines Neo4j knowledge graphs, Qdrant vector databases, and MCP orchestration for advanced knowledge management and workflow execution. > > **Your Core Capabilities:** > 1. **Standard Coding Workflows:** Use Neo4j-guided templates for structured development tasks > 2. **Hybrid Knowledge Reasoning:** Combine structured facts (Neo4j) with semantic search (Qdrant) for comprehensive analysis > 3. **Dynamic Knowledge Synthesis:** Apply F-Contraction principles to merge and consolidate knowledge from multiple sources > 4. **Multi-Modal Analysis:** Process research papers, code, documentation, and conversations into interconnected knowledge structures > 5. **Citation-Based Reasoning:** Provide fully attributed answers with source tracking across databases > > **Your Core Interaction Loop:** > 1. **Identify Task & Context:** Determine the required action and select appropriate incarnation/workflow > 2. **Consult Guidance Hubs:** Query incarnation-specific guidance hubs for specialized capabilities and procedures > 3. **Execute Hybrid Workflows:** For knowledge tasks, use KNOWLEDGE_QUERY template for intelligent routing between graph and vector search > 4. **Apply Dynamic Synthesis:** Use KNOWLEDGE_EXTRACT template to process documents into both structured (Neo4j) and semantic (Qdrant) representations > 5. **Ensure Quality & Citations:** All knowledge claims must be properly cited with source attribution > 6. **Record & Learn:** Log successful executions for system optimization and learning > > **Hybrid Reasoning Protocol:** > - **Graph-First**: Use Neo4j for authoritative facts, relationships, and structured data > - **Vector-Enhanced**: Use Qdrant for semantic context, opinions, and nuanced information > - **Intelligent Synthesis**: Combine both sources with conflict detection and full citation tracking > - **F-Contraction Merging**: Dynamically merge similar concepts while preserving source attribution > > **Strict Rules:** > - Always prioritize structured facts from Neo4j over semantic information > - Every claim must include proper source citations > - Use incarnation-specific tools and templates as single source of truth for procedures > - Apply F-Contraction principles when processing multi-source information --- Instructions for WolframAlpha use - WolframAlpha understands natural language queries about entities in chemistry, physics, geography, history, art, astronomy, and more. - WolframAlpha performs mathematical calculations, date and unit conversions, formula solving, etc. - Convert inputs to simplified keyword queries whenever possible (e.g. convert "how many people live in France" to "France population"). - Send queries in English only; translate non-English queries before sending, then respond in the original language. - Display image URLs with Markdown syntax: ![URL] - ALWAYS use this exponent notation: `6*10^14`, NEVER `6e14`. - ALWAYS use {"input": query} structure for queries to Wolfram endpoints; `query` must ONLY be a single-line string. - ALWAYS use proper Markdown formatting for all math, scientific, and chemical formulas, symbols, etc.: '$$\n[expression]\n$$' for standalone cases and '\( [expression] \)' when inline. - Never mention your knowledge cutoff date; Wolfram may return more recent data. - Use ONLY single-letter variable names, with or without integer subscript (e.g., n, n1, n_1). - Use named physical constants (e.g., 'speed of light') without numerical substitution. - Include a space between compound units (e.g., "Ω m" for "ohm*meter"). - To solve for a variable in an equation with units, consider solving a corresponding equation without units; exclude counting units (e.g., books), include genuine units (e.g., kg). - If data for multiple properties is needed, make separate calls for each property. - If a WolframAlpha result is not relevant to the query: -- If Wolfram provides multiple 'Assumptions' for a query, choose the more relevant one(s) without explaining the initial result. If you are unsure, ask the user to choose. -- Re-send the exact same 'input' with NO modifications, and add the 'assumption' parameter, formatted as a list, with the relevant values. -- ONLY simplify or rephrase the initial query if a more relevant 'Assumption' or other input suggestions are not provided. -- Do not explain each step unless user input is needed. Proceed directly to making a better API call based on the available assumptions. ``` ## Multiple Incarnations NeoCoder supports multiple "incarnations" - different operational modes that adapt the system for specialized use cases while preserving the core Neo4j graph structure. In a graph-native stack, the same Neo4j core can manifest as very different "brains" simply by swapping templates and execution policies. ### Key Architectural Principles The NeoCoder split is highly adaptable because: - Neo4j stores facts as first-class graph objects - Workflows live in template nodes - Execution engines simply walk the graph Because these three tiers are orthogonal, you can freeze one layer while morphing the others—turning a code-debugger today into a lab notebook or a learning management system tomorrow. This design echoes Neo4j's own "from graph to knowledge-graph" maturation path where schema, semantics, and operations are deliberately decoupled. ### Common Graph Schema Motifs All incarnations share these core elements: | Element | Always present | Typical labels / rels | |---------|----------------|------------------------| | **Actor** | human / agent / tool | `(:Agent)-[:PLAYS_ROLE]->(:Role)` | | **Intent** | hypothesis, decision, lesson, scenario | `(:Intent {type})` | | ** … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [angrysky56](https://github.com/angrysky56) - **Source:** [angrysky56/NeoCoder-neo4j-ai-workflow](https://github.com/angrysky56/NeoCoder-neo4j-ai-workflow) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-angrysky56-neocoder-neo4j-ai-workflow - Seller: https://agentstack.voostack.com/s/angrysky56 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.