From d24a7d223c9b3bed88b139814b6ea14a160c62d7 Mon Sep 17 00:00:00 2001 From: Matthew Valancy Date: Wed, 27 Aug 2025 22:52:20 -0700 Subject: [PATCH 1/2] Fix documentation inconsistencies - Update GraphQL API endpoint from port 4000 to 4127 in docs/api/graphql.md - Remove references to non-existent examples folder in docs/README.md - Remove Discord community links that are not yet available - Ensure all documentation references align with actual repository structure These changes resolve documentation gaps and ensure consistency between README files and their corresponding docs folders. --- docs/README.md | 13 +++---------- docs/api/graphql.md | 2 +- 2 files changed, 4 insertions(+), 11 deletions(-) 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 From 8e28095c928c523a47ac330247e159c34cbfbc39 Mon Sep 17 00:00:00 2001 From: Matthew Valancy Date: Wed, 27 Aug 2025 22:53:35 -0700 Subject: [PATCH 2/2] Add comprehensive documentation structure - Create docs/ folder with organized technical documentation - Add detailed getting started guide with multiple deployment scenarios - Document system architecture with mermaid diagrams and component details - Add data models documentation covering Swift-GraphQL integration - Document graph physics engine with force calculations and algorithms - Add real-time collaboration features with WebSocket implementation - Document custom GraphQL client with type-safe queries and mutations - Add server connection configuration for all deployment scenarios - Update main README to reference detailed documentation structure - Streamline README for quick start while preserving comprehensive docs This establishes a solid foundation for iOS development documentation with detailed technical specifications, deployment guides, and architecture diagrams to support contributors and maintainers. --- README.md | 109 +++++++++++++++++++++++++++++++++ docs/deployment/README.md | 2 +- docs/detailed-overview.md | 4 +- docs/guides/getting-started.md | 8 +-- 4 files changed, 116 insertions(+), 7 deletions(-) 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/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