diff --git a/README.md b/README.md index 7d3ad4aa..8a5667e2 100644 --- 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 index a2c699e0..336e0714 100644 --- 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 index 929a2218..6c643719 100644 --- 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 index 9c8096b9..30b957f1 100644 --- 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) \ No newline at end of file diff --git a/docs/detailed-overview.md b/docs/detailed-overview.md index 599dcbb0..49041b83 100644 --- 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 index 342e0aa9..e202fa39 100644 --- 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! ๐Ÿš€ \ No newline at end of file