project-synapse

Project Synapse MCP Server provides an autonomous knowledge synthesis environment that builds interconnected knowledge graphs using Montague Grammar-based semantic analysis, a Neo4j-backed knowledge cortex, and an autonomous Zettelkasten engine for pattern detection and insight generation. Once the MCP server is running, you can ingest raw text, trigger autonomous insight generation, and query the knowledge graph with natural-language prompts that prioritize synthesized insights and reasoning trails. Use the ingest_text tool to process new inputs, the generate_insights tool to run the autonomous reasoning and hypothesis generation, and the query_knowledge and explore_connections tools to explore, reason about, and retrieve patterns and connections within the graph. The server exposes MCP-compatible endpoints and can be integrated with LLM clients like Claude via the provided configuration snippet, enabling real-time knowledge retrieval, provenance tracking, and confidence-scored insights.

Prerequisites:

• Python 3.10+ (recommended via uv/virtual environment support)
• Neo4j database server (local or remote)
• uv package manager (recommended)

Step-by-step installation:

1. Clone the repository and set up the project:

# Replace with your actual repository URL
cd /home/ty/Repositories/ai_workspace
git clone <repository-url> project-synapse-mcp
cd project-synapse-mcp

2. Create and activate a Python virtual environment using uv:

uv venv --python 3.12 --seed
source .venv/bin/activate

3. Install dependencies via uv (or your preferred method):

uv add -e .

4. Set up Neo4j database locally (or use an existing instance):

# On Ubuntu/Debian
sudo apt update
sudo apt install neo4j

# Start and enable neo4j service
sudo systemctl start neo4j
sudo systemctl enable neo4j

# Set initial password (default user is neo4j)
sudo neo4j-admin set-initial-password synapse_password

5. Download the spaCy model required by the pipeline:

uv run python -m spacy download en_core_web_sm

6. Configure environment for the MCP server:

cp .env.example .env
# Edit .env with your configuration (DB connection, API keys, etc.)

7. Run the MCP server (example using uv as configured):

# Ensure the environment variables are set or defined in the mcp config
# Start the MCP server as defined in the mcp_config
uv run python -m synapse_mcp.server

Tips and common issues:\n- Ensure Neo4j is reachable at the configured NEO4J_URI and that the user/password in NEO4J_PASSWORD are correct.\n- The environment variable LOG_LEVEL can be tuned (e.g., DEBUG for troubleshooting).\n- For Claude Desktop integration, ensure the path in the configuration points to your local project-synapse-mcp directory and that Python and uv are accessible in your environment.\n- If the spaCy model fails to download, confirm network access and that the uv venv has network permissions.\n- Adjust SEMANTIC_BATCH_SIZE, PATTERN_DETECTION_INTERVAL, and INSIGHT_CONFIDENCE_THRESHOLD in your .env to balance throughput and quality.\n- Regularly back up Neo4j data and provenance trails.\n- Use the provided prompts and endpoints to validate the reasoning trails and ensure traceability of insights.