GraphDone · mvalancy · Aug 28, 2025 · Aug 28, 2025 · Aug 28, 2025
diff --git a/README.md b/README.md
@@ -74,10 +74,16 @@ Visit **http://localhost:3127** when you see the "GraphDone is Ready!" message.
 
 ### What You Get
 
+**Core GraphDone Services:**
 - 🌐 **Web Application**: http://localhost:3127 - Full graph visualization and collaboration interface
 - 🔗 **GraphQL API**: http://localhost:4127/graphql - Auto-generated resolvers with @neo4j/graphql  
 - 🩺 **Health Check**: http://localhost:4127/health - Service status monitoring
 - 🗄️ **Database**: Neo4j 5.15-community with APOC plugins for native graph storage
+
+**Optional Claude Code Integration:**
+- 🤖 **MCP Server**: Separate service for Claude Code integration (see [MCP Setup](#mcp-server-setup) below)
+
+**Development Tools:**
 - 🐳 **Docker Setup**: Development and production containers ready to go
 - 🧪 **Testing**: Comprehensive test suite with coverage reporting
 
@@ -131,6 +137,109 @@ The app now provides user-friendly error messages instead of technical errors. I
 - Visit http://localhost:4127/health to verify the server is running
 - The error UI will guide you through common troubleshooting steps
 
+## MCP Server Setup
+
+The **MCP (Model Context Protocol) Server** is a **separate service** that allows Claude Code to interact with your GraphDone graph through natural language. It connects directly to your Neo4j database and runs independently from the GraphDone web application.
+
+### Architecture Overview
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│ Claude Code     │◄───│ MCP Server      │◄───│ Neo4j Database  │
+│ (Your machine)  │    │ (Port 3128)     │    │ (Port 7687)     │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+                                │
+                                ▼
+                       ┌─────────────────┐
+                       │ GraphDone Web   │
+                       │ (Port 3127)     │◄──── Browser
+                       └─────────────────┘
+```
+
+### Quick MCP Setup
+
+**One-command setup:**
+```bash
+./scripts/setup-mcp.sh
+```
+
+This script will:
+- ✅ Build the MCP server automatically
+- 🔗 Configure Claude Code to use it  
+- 📋 Show you exactly what to do next
+- 🛡️ Create backups of your settings
+
+### Manual MCP Setup
+
+If automatic setup doesn't work, configure manually:
+
+```bash
+# Build MCP server
+cd packages/mcp-server
+npm run build
+
+# Add to Claude Code
+claude mcp add graphdone "$(which node)" "$(pwd)/dist/index.js" \
+  --env "NEO4J_URI=bolt://localhost:7687" \
+  --env "NEO4J_USER=neo4j" \
+  --env "NEO4J_PASSWORD=graphdone_password"
+```
+
+### Distributed Setup (Multiple Machines)
+
+**If Claude Code is on a different machine than GraphDone:**
+
+```bash
+# On your development machine with Claude Code
+claude mcp add graphdone node /path/to/mcp-server/dist/index.js \
+  --env "NEO4J_URI=bolt://192.168.1.100:7687" \
+  --env "NEO4J_USER=neo4j" \
+  --env "NEO4J_PASSWORD=graphdone_password"
+```
+
+**Multiple developers sharing one GraphDone instance:**
+```bash
+# Developer A (default port)
+claude mcp add graphdone node dist/index.js --env "MCP_HEALTH_PORT=3128"
+
+# Developer B (different port to avoid conflicts)  
+claude mcp add graphdone node dist/index.js --env "MCP_HEALTH_PORT=3129"
+```
+
+### Using the MCP Server
+
+Once configured, just talk to Claude Code naturally:
+- *"Show me all active tasks"*
+- *"Create a new epic for mobile development"*  
+- *"What's blocking the user authentication feature?"*
+- *"Add a dependency between task A and task B"*
+
+### MCP Troubleshooting
+
+**MCP server not appearing?**
+```bash
+claude mcp list  # Check if registered
+curl http://localhost:3128/health  # Test health endpoint
+```
+
+**Connection errors?**  
+```bash
+# Verify Neo4j is running
+docker-compose up -d  # Or ./start
+cypher-shell -u neo4j -p graphdone_password "RETURN 1"
+```
+
+**Port conflicts?**
+```bash
+# Check what's using port 3128
+lsof -i :3128
+
+# Use different port for additional MCP servers
+MCP_HEALTH_PORT=3129 node dist/index.js
+```
+
+> **Note:** The MCP server requires the Neo4j database to be running but is independent of the GraphDone web application. You can use Claude Code with your graph even if the web interface is offline.
+
 ## Core Concepts
 
 ### Graph Structure

diff --git a/docs/README.md b/docs/README.md
@@ -2,7 +2,7 @@
 
 **AI-Generated Content Warning: This documentation contains AI-generated content. Verify information before depending on it for decision making.**
 
-Welcome to the GraphDone documentation! This directory contains comprehensive guides, API references, and examples for working with GraphDone.
+Welcome to the GraphDone documentation! This directory contains comprehensive guides, API references, and deployment information for working with GraphDone.
 
 ## 📚 Documentation Structure
 
@@ -18,12 +18,6 @@ Welcome to the GraphDone documentation! This directory contains comprehensive gu
 - Architecture overview
 - Contributing guidelines
 
-### [Examples](./examples/)
-- Integration examples
-- AI agent implementations
-- Custom visualizations
-- Deployment configurations
-
 ### [Deployment](./deployment/)
 - Docker setup
 - Kubernetes manifests
@@ -68,9 +62,8 @@ Welcome to the GraphDone documentation! This directory contains comprehensive gu
 
 ## 📞 Support
 
-- [GitHub Issues](https://github.com/your-org/graphdone/issues)
-- [Discussions](https://github.com/your-org/graphdone/discussions)
-- [Discord Community](https://discord.gg/graphdone)
+- [GitHub Issues](https://github.com/GraphDone/GraphDone-Core/issues)
+- [Discussions](https://github.com/GraphDone/GraphDone-Core/discussions)
 
 ---
 

diff --git a/docs/api/graphql.md b/docs/api/graphql.md
@@ -7,7 +7,7 @@ GraphDone provides a comprehensive GraphQL API for all data operations. The API
 ## Endpoint
 
 ```
-http://localhost:4000/graphql
+http://localhost:4127/graphql
 ```
 
 ## Authentication

diff --git a/docs/deployment/README.md b/docs/deployment/README.md
@@ -435,6 +435,6 @@ docker-compose build --no-cache
 ## Support
 
 For deployment support:
-- [GitHub Issues](https://github.com/your-org/graphdone/issues)
+- [GitHub Issues](https://github.com/GraphDone/GraphDone-Core/issues)
 - [Community Discord](https://discord.gg/graphdone)
 - [Documentation](../README.md)
diff --git a/docs/detailed-overview.md b/docs/detailed-overview.md
@@ -478,7 +478,7 @@ GraphDone includes a comprehensive setup script that handles all prerequisites a
 
 ```bash
 # Clone and setup
-git clone https://github.com/your-org/graphdone.git
+git clone https://github.com/GraphDone/GraphDone-Core.git
 cd graphdone
 ./tools/setup.sh
 ```
@@ -664,7 +664,7 @@ agent.subscribe('node.priorityChanged', async (node) => {
 ### 🚀 **Ready for Development**
 ```bash
 # Get started in 30 seconds
-git clone https://github.com/your-org/graphdone.git
+git clone https://github.com/GraphDone/GraphDone-Core.git
 cd graphdone
 ./tools/setup.sh
 ./tools/run.sh

diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md
@@ -19,7 +19,7 @@ Before you begin, ensure you have the following installed:
 
 ```bash
 # Clone the repository
-git clone https://github.com/your-org/graphdone.git
+git clone https://github.com/GraphDone/GraphDone-Core.git
 cd graphdone
 
 # Run setup script
@@ -37,7 +37,7 @@ The setup script will:
 
 ```bash
 # Clone and install dependencies
-git clone https://github.com/your-org/graphdone.git
+git clone https://github.com/GraphDone/GraphDone-Core.git
 cd graphdone
 npm install
 
@@ -118,7 +118,7 @@ Your node will appear in the graph visualization, positioned based on its comput
 - [Explore the Architecture](./architecture.md)
 - [Learn about AI Agent Integration](./ai-agents.md)
 - [Set up Production Deployment](../deployment/README.md)
-- [Join the Community Discussions](https://github.com/your-org/graphdone/discussions)
+- [Join the Community Discussions](https://github.com/GraphDone/GraphDone-Core/discussions)
 
 ## Common Issues
 
@@ -141,7 +141,7 @@ node --version
 
 If you encounter issues:
 1. Check the [Troubleshooting Guide](./troubleshooting.md)
-2. Search [existing issues](https://github.com/your-org/graphdone/issues)
+2. Search [existing issues](https://github.com/GraphDone/GraphDone-Core/issues)
 3. Create a new issue with detailed information
 
 Welcome to the future of collaborative work! 🚀