{"id":29961721,"url":"https://github.com/design4pro/mcp-rag-server","last_synced_at":"2025-08-03T23:41:55.195Z","repository":{"id":306928061,"uuid":"1027346447","full_name":"design4pro/mcp-rag-server","owner":"design4pro","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-28T14:11:53.000Z","size":917,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-28T14:34:39.197Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/design4pro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-27T20:43:08.000Z","updated_at":"2025-07-28T14:11:51.000Z","dependencies_parsed_at":"2025-07-28T14:34:41.968Z","dependency_job_id":"bc53fcf2-9964-458d-a69f-09d13ed58eea","html_url":"https://github.com/design4pro/mcp-rag-server","commit_stats":null,"previous_names":["design4pro/mcp-rag-server"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/design4pro/mcp-rag-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/design4pro%2Fmcp-rag-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/design4pro%2Fmcp-rag-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/design4pro%2Fmcp-rag-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/design4pro%2Fmcp-rag-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/design4pro","download_url":"https://codeload.github.com/design4pro/mcp-rag-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/design4pro%2Fmcp-rag-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268629810,"owners_count":24281172,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-03T23:41:52.248Z","updated_at":"2025-08-03T23:41:55.134Z","avatar_url":"https://github.com/design4pro.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP RAG Server\n\nA comprehensive Retrieval-Augmented Generation (RAG) server built with the Model Context Protocol (MCP), featuring advanced memory management, session handling, AI reasoning capabilities, and multi-modal document processing.\n\n## 🚀 Features\n\n- **Document Management**: Add, search, and manage documents with automatic chunking and embedding\n- **Memory Integration**: Advanced memory context retrieval with multi-factor scoring and pattern analysis\n- **Session Management**: User session tracking and comprehensive statistics\n- **AI Reasoning**: Advanced reasoning capabilities including deductive, inductive, abductive, and chain-of-thought reasoning\n- **Context Understanding**: Deep context analysis with entity extraction and relationship mapping\n- **MCP Integration**: Full Model Context Protocol support with comprehensive tools and resources\n- **Vector Search**: Powered by Qdrant vector database with advanced search capabilities\n- **AI Integration**: Gemini API for embeddings and text generation\n- **Self-hosted Memory**: Local mem0 service for conversation memory\n- **Performance Optimization**: Optimized reasoning engine with benchmarking capabilities\n\n## 📊 Project Status\n\n**All Development Phases Completed** ✅\n\n| Phase | Name               | Status      | Progress |\n| ----- | ------------------ | ----------- | -------- |\n| 1     | Foundations        | ✅ Complete | 100%     |\n| 2     | RAG Core           | ✅ Complete | 100%     |\n| 3     | MCP Integration    | ✅ Complete | 100%     |\n| 4     | Memory Integration | ✅ Complete | 100%     |\n| 5     | Advanced Features  | ✅ Complete | 100%     |\n| 6     | AI Reasoning       | ✅ Complete | 100%     |\n\n## 🏗️ Project Structure\n\n```\nmcp-rag/\n├── data/                    # All application data\n│   ├── mem0_data/          # Memory storage\n│   ├── session_data/       # Session storage\n│   └── test_mem0_data/     # Test memory data\n├── docs/                   # Comprehensive project documentation\n│   ├── 00-overview/        # Project overview and documentation index\n│   ├── 01-architecture/    # System architecture documentation\n│   ├── 02-installation/    # Installation and setup guides\n│   ├── 03-api/             # API reference documentation\n│   ├── 04-development/     # Development phases and guides\n│   └── 05-troubleshooting/ # Troubleshooting and support\n├── src/                    # Source code\n│   └── mcp_rag_server/     # Main application package\n│       ├── services/       # Core services (RAG, Memory, AI, etc.)\n│       ├── tools/          # MCP tools implementation\n│       ├── resources/      # MCP resources implementation\n│       └── validation.py   # Data validation schemas\n├── tests/                  # Comprehensive test suite\n│   ├── unit/              # Unit tests\n│   └── integration/       # Integration tests\n├── docker/                 # Docker configuration\n├── deployment/             # Deployment scripts and configurations\n├── scripts/                # Management scripts\n└── examples/               # Usage examples and demonstrations\n```\n\n## 📁 Data Organization\n\nAll application data is organized in the `data/` folder:\n\n- **`data/mem0_data/`**: Stores conversation memories and user data\n- **`data/session_data/`**: Stores user session information and statistics\n- **`data/test_mem0_data/`**: Test-specific memory data for development\n\nThis centralized approach ensures clean project organization and easy data management.\n\n## ⚡ Quick Start\n\n### Prerequisites\n\n- Python 3.11+\n- Docker (for Qdrant)\n- Gemini API key\n\n### 1. Setup\n\n```bash\ngit clone \u003crepository-url\u003e\ncd mcp-rag\npip install -r requirements.txt\ncp .env.example .env\n# Edit .env with your Gemini API key\n```\n\n### 2. Start Services\n\n```bash\n# Start Qdrant\ndocker run -d -p 6333:6333 -p 6334:6334 qdrant/qdrant:latest\n\n# Option 1: Use Cursor IDE (Recommended)\n# Enable RAG tools in Cursor IDE - containers start automatically\n\n# Option 2: Manual Docker run\ndocker run -i --rm \\\n  -p 8001:8000 \\\n  -e MCP_GEMINI_API_KEY=your_api_key \\\n  -e MCP_QDRANT_URL=http://host.docker.internal:6333 \\\n  ghcr.io/design4pro/mcp-rag-server:latest\n\n# Option 3: Use scripts\n./scripts/manage_server.sh start\n```\n\n### 3. Verify Installation\n\n```bash\n# Health check\n./scripts/manage_server.sh health\n\n# Check status\n./scripts/manage_server.sh status\n```\n\n## 🔧 Development\n\n```bash\n# Run tests\npython -m pytest tests/\n\n# Run tests with coverage\npython -m pytest tests/ --cov=src/mcp_rag_server\n\n# Check logs\n./scripts/manage_server.sh logs\n\n# Stop server\n./scripts/manage_server.sh stop\n```\n\n## 📚 Documentation\n\nComprehensive documentation is available in the `docs/` directory:\n\n- **Documentation Index**: [[docs/00-overview/documentation-index.md]]\n- **Project Overview**: [[docs/00-overview/project-overview.md]]\n- **System Architecture**: [[docs/01-architecture/system-architecture.md]]\n- **Installation Guide**: [[docs/02-installation/installation-guide.md]]\n- **Cursor IDE Setup**: [[docs/02-installation/cursor-ide-automatic-container-management|Cursor IDE Automatic Container Management]]\n- **Docker Registry**: [[docs/02-installation/docker-registry-publishing-guide|Docker Registry Publishing Guide]]\n- **API Reference**: [[docs/03-api/api-reference.md]]\n- **Development Phases**: [[docs/04-development/phases/development-phases-overview.md]]\n- **Troubleshooting**: [[docs/05-troubleshooting/troubleshooting-guide.md]]\n\n## 🧪 Testing\n\nThe project includes comprehensive test coverage:\n\n- **Unit Tests**: 183 tests covering all core functionality\n- **Integration Tests**: Complete MCP tool integration testing\n- **Performance Tests**: Benchmarking and performance validation\n- **Error Handling**: Comprehensive error scenario testing\n\nRun tests with:\n\n```bash\npython -m pytest tests/ -v\n```\n\n## 🚀 Advanced Features\n\n### AI Reasoning Capabilities\n\n- **Deductive Reasoning**: Logical inference from premises to conclusions\n- **Inductive Reasoning**: Pattern-based generalizations from observations\n- **Abductive Reasoning**: Hypothesis generation from observations\n- **Chain-of-Thought Reasoning**: Multi-step reasoning with intermediate conclusions\n- **Multi-Hop Reasoning**: Iterative reasoning across multiple contexts\n\n### Memory Management\n\n- **Semantic Memory Search**: Advanced semantic search capabilities\n- **Memory Clustering**: Automatic memory organization and clustering\n- **Pattern Analysis**: Memory pattern identification and analysis\n- **Context Retrieval**: Enhanced memory context with multi-factor scoring\n\n### Session Management\n\n- **User Session Tracking**: Comprehensive session management\n- **Session Statistics**: Detailed usage analytics and statistics\n- **Session Persistence**: Reliable session data storage\n- **Cleanup Management**: Automatic session cleanup and maintenance\n\n## 🤝 Contributing\n\n1. Follow the phased development approach\n2. Update documentation after changes\n3. Test all deployment methods\n4. Use English for all code and documentation\n5. Ensure all tests pass before submitting changes\n\n## 📄 License\n\nMIT License - see LICENSE file for details.\n\n## 🆘 Support\n\nFor support and troubleshooting:\n\n1. Check the troubleshooting guide: [[docs/05-troubleshooting/troubleshooting-guide.md]]\n2. Review the system architecture: [[docs/01-architecture/system-architecture.md]]\n3. Consult the API reference: [[docs/03-api/api-reference.md]]\n\n## 🔄 Version History\n\n- **v1.0.0**: Complete implementation with all phases finished\n  - Advanced AI reasoning capabilities\n  - Comprehensive memory management\n  - Full MCP integration\n  - Performance optimization\n  - Complete test coverage\n\n---\n\n**Project Status**: ✅ Production Ready  \n**Last Updated**: 2025-01-25  \n**Version**: 1.0.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdesign4pro%2Fmcp-rag-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdesign4pro%2Fmcp-rag-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdesign4pro%2Fmcp-rag-server/lists"}