QualAI

# 🔬 QualAI - AI-Powered Qualitative Research MCP Server > **Community-driven, RAG-enhanced qualitative research analysis powered by Claude** Transform qualitative research with AI assistance. QualAI is a Model Context Protocol (MCP) server that brings advanced AI capabilities to qualitative data analysis while maintaining methodological rigor. --- ## 💡 Share Your Innovative Research Methods! **QualAI grows stronger with every researcher who contributes.** Have you developed a unique qualitative methodology? A novel coding technique? An innovative analysis approach? **🌟 Share it with the global research community!** When you contribute your methodology to QualAI: - ✅ **Help thousands of researchers** worldwide discover and use your approach - ✅ **Get cited** every time someone uses your methodology - ✅ **Receive feedback** and improvements from peer researchers - ✅ **Build your reputation** as a methodological innovator - ✅ **Make qualitative research better** for everyone **Your innovation can transform how the world does qualitative research.** 👉 [**Contribute Your Methodology**](#contributing-your-methodology) | [**Browse Community Methods**](https://github.com/qualai-community/methodologies) --- ## ✨ Revolutionary Features ### 🤖 **AI-Native Analysis** - Automatic coding with semantic understanding - Theme extraction with theoretical depth - Saturation detection - Negative case discovery - Inter-coder reliability automation ### 🌍 **Community-Driven Methodologies** - **RAG-powered methodology library**: Access community-contributed research methods - **GitHub integration**: Share and discover methodologies from researchers worldwide - **Validated approaches**: Peer-reviewed methodologies with quality ratings - **Flexible**: Use established methods or create your own ### 🎯 **Core Tools (v1.0)** #### Methodology Management (3) - `selectMethodology` - AI finds the best methodology for your research - `loadMethodology` - Load community methodologies - `listMethodologies` - Browse available methods #### Coding Tools (5) - `autoCoding` - AI-powered automatic coding - `refineCodebook` - Optimize your codebook - `mergeCodesSmart` - Intelligent code merging - `suggestSubcodes` - Hierarchical code suggestions - `validateCoding` - Consistency checking #### Thematic Analysis (4) - `extractThemes` - Inductive/deductive theme extraction - `analyzePatterns` - Pattern and relationship analysis - `detectSaturation` - Theoretical saturation detection - `compareThemesAcrossCases` - Cross-case comparison #### Theory Building (3) - `buildGroundedTheory` - Guided grounded theory development - `generateConceptMap` - Automatic concept mapping - `analyzeNarrative` - Narrative structure analysis #### Validation (4) - `findNegativeCases` - Negative case analysis - `triangulate` - Multi-source triangulation - `calculateReliability` - Inter-coder reliability - `assessQuality` - Research quality assessment #### Reporting (1) - `generateReport` - Comprehensive analysis reports --- **Note:** v1.0 includes methodology management and knowledge graph. Advanced analysis tools (auto-coding, theme extraction, etc.) are in active development for v1.1. ## 📋 Prerequisites ### System Requirements - **Node.js**: Version 18.0 or higher - **Operating System**: Windows 10+, macOS 11+, or Ubuntu 20.04+ - **Disk Space**: At least 500 MB free ### 🐳 Qdrant Vector Database (Optional but Recommended) QualAI uses **Qdrant** for semantic methodology search and RAG-enhanced analysis. While QualAI can work without Qdrant (using local keyword search as fallback), **installing Qdrant significantly improves methodology recommendations** and semantic search capabilities. #### Option 1: Docker (Recommended - Easiest) **Using PowerShell (Windows):** ```powershell # Install Docker Desktop if not already installed # Download from: https://www.docker.com/products/docker-desktop # Verify Docker is running docker --version # Run Qdrant container docker run -d -p 6333:6333 -p 6334:6334 ` -v ${PWD}/qdrant_storage:/qdrant/storage ` --name qualai-qdrant ` qdrant/qdrant # Verify Qdrant is running docker ps | Select-String "qualai-qdrant" # Test Qdrant connection curl http://localhost:6333 ``` **Using Bash (Linux/macOS):** ```bash # Verify Docker is running docker --version # Run Qdrant container docker run -d -p 6333:6333 -p 6334:6334 \ -v $(pwd)/qdrant_storage:/qdrant/storage \ --name qualai-qdrant \ qdrant/qdrant # Verify Qdrant is running docker ps | grep qualai-qdrant # Test Qdrant connection curl http://localhost:6333 ``` **Stop/Start Qdrant:** ```powershell # Stop Qdrant docker stop qualai-qdrant # Start Qdrant again docker start qualai-qdrant # Remove Qdrant (if needed) docker rm -f qualai-qdrant ``` #### Option 2: Qdrant Cloud (No Docker Required) If you don't want to run Docker locally: 1. Sign up for free at [Qdrant Cloud](https://cloud.qdrant.io) 2. Create a cluster 3. Get your API URL and API Key 4. Use them in the configuration (see below) #### Option 3: Run Without Qdrant (Fallback Mode) QualAI will automatically use local keyword search if Qdrant is not available. No additional setup required, but semantic search will be limited. --- ## 🚀 Quick Start ### Installation ```bash # Clone the repository git clone https://github.com/seanshin0214/qualai-mcp.git cd qualai-mcp # Install dependencies npm install # Build npm run build ``` ### Configure Claude Desktop #### Basic Configuration (Without Qdrant) Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "qualai": { "command": "node", "args": ["C:\\Users\\YOUR-USERNAME\\Documents\\qualai-mcp\\dist\\index.js"] } } } ``` #### With Qdrant (Recommended for Best Performance) If you installed Qdrant using Docker locally: ```json { "mcpServers": { "qualai": { "command": "node", "args": ["C:\\Users\\YOUR-USERNAME\\Documents\\qualai-mcp\\dist\\index.js"], "env": { "QDRANT_URL": "http://localhost:6333", "OPENAI_API_KEY": "sk-your-openai-api-key", "QUALAI_GITHUB_REPO": "qualai-community/methodologies" } } } } ``` If you're using Qdrant Cloud: ```json { "mcpServers": { "qualai": { "command": "node", "args": ["C:\\Users\\YOUR-USERNAME\\Documents\\qualai-mcp\\dist\\index.js"], "env": { "QDRANT_URL": "https://your-cluster.cloud.qdrant.io:6333", "QDRANT_API_KEY": "your-qdrant-api-key", "OPENAI_API_KEY": "sk-your-openai-api-key", "QUALAI_GITHUB_REPO": "qualai-community/methodologies" } } } } ``` **Environment Variables Explained:** - `QDRANT_URL`: Qdrant server URL (default: `http://localhost:6333`) - `QDRANT_API_KEY`: Required only for Qdrant Cloud (optional for local Docker) - `OPENAI_API_KEY`: For generating text embeddings (required if using Qdrant) - `QUALAI_GITHUB_REPO`: Community methodologies repository (default: `qualai-community/methodologies`) ### Restart Claude Desktop That's it! QualAI is now available in Claude. **💬 First time? Try this:** ``` "I have 15 interview transcripts about remote work experiences. Help me choose the right methodology and start coding." ``` --- ## 🌍 Community Methodologies ### Current Methodologies (10) **Built-in:** 1. **Constructivist Grounded Theory** (Charmaz, 2014) - Complete 4-stage process with memo writing 2. **Reflexive Thematic Analysis** (Braun & Clarke, 2006) - 6-phase systematic approach 3. **Discourse Analysis** (Gee, 2014) - Language-in-use and power relations analysis 4. **Narrative Analysis** - Story structure and meaning-making 5. **Phenomenography** - Variation in ways of experiencing phenomena 6. **Ethnography** - Cultural and social patterns in context 7. **Hermeneutic Analysis** - Interpretive understanding and hermeneutic circle 8. **Case Study** (Yin/Stake) - In-depth contextual investigation 9. **Action Research** - Participatory change-oriented inquiry 10. **Critical Incident Technique** (Flanagan) - Significant events analysis **Community Contributed:** - *Be the first to contribute!* ### Contributing Your Methodology **Your methodology could help thousands of researchers worldwide.** #### Step 1: Create Your Methodology Use our template (see CONTRIBUTING.md) #### Step 2: Test Locally ```bash # Place in methodologies/ directory cp your-methodology.json qualai-mcp/methodologies/ # Restart QualAI and test ``` #### Step 3: Share with Community 1. Fork [qualai-community/methodologies](https://github.com/qualai-community/methodologies) 2. Add your methodology with documentation 3. Create Pull Request 4. Community peer review (2+ reviewers) 5. Merged and available to all! 🎉 #### Recognition - Your name appears in methodology metadata - Automatic citation generation - Contributor leaderboard - Usage statistics (opt-in) **Ready to contribute?** See [CONTRIBUTING.md](CONTRIBUTING.md) --- ## 🏗️ Architecture ``` ┌─────────────────────────────────────┐ │ Claude Desktop │ │ (User Interface & Conversations) │ └──────────────┬──────────────────────┘ │ MCP Protocol ┌──────────────▼──────────────────────┐ │ QualAI MCP Server │ │ │ │ ┌────────────────────────────┐ │ │ │ Methodology Orchestrator │ │ │ └────────────────────────────┘ │ │ │ │ ┌─────────┬─────────┬──────────┐ │ │ │ Coding │ Thematic│ Theory │ │ │ │ Engine │ Engine │ Engine │ │ │ └─────────┴─────────┴──────────┘ │ │ │ │ ┌─────────────────────────────┐ │ │ │ RAG System (Qdrant) │ │ │ │ - Community methodologies │ │ │ └─────────────────────────────┘ │ │ │ │ ┌─────────────────────────────┐ │ │ │ Knowledge Graph (SQLite) │ │ │ └─────────────────────────────┘ │ └─────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ GitHub: qualai-community │ │ Community Methodologies Registry │ │ - YOUR methodology! 🌟 │ └─────────────────────────────────────┘ ``` --- ## 🤝 Contributing We welcome all forms of contribution! ### Ways to Contribute 1. **📖 Share Methodologies**: Most valuable contribution! 2. **🐛 Report Bugs**: Help us improve 3. **💡 Suggest Features**: Shape QualAI's future 4. **📝 Improve Docs**: Help others learn 5. **💻 Submit Code**: Enhance functionality --- ## 📊 Roadmap ### v1.0 (Current) ✅ - [x] 10 built-in methodologies - [x] RAG-powered methodology selection - [x] Knowledge graph for research data - [x] 20 analysis tools ### v1.1 (Q1 2025) - [ ] Interpretive Phenomenological Analysis (IPA) - [ ] Conversation Analysis - [ ] Content Analysis - [ ] 15+ total methodologies - [ ] Enhanced auto-coding with GPT-4 ### v1.2 (Q2 2025) - [ ] Real-time collaboration - [ ] Multi-language support (Korean, Spanish, Chinese) - [ ] 25+ community methodologies - [ ] Export to ATLAS.ti, NVivo formats ### v2.0 (Q3 2025) - [ ] Web interface - [ ] 50+ community methodologies - [ ] Live interview transcription --- ## 📄 License MIT License - see [LICENSE](LICENSE) --- ## 📞 Support & Community - **💬 Discussions**: [GitHub Discussions](https://github.com/seanshin0214/qualai-mcp/discussions) - **🐛 Issues**: [GitHub Issues](https://github.com/seanshin0214/qualai-mcp/issues) - **📧 Email**: sshin@geri.kr --- ## 🌟 Final Call to Action **To Researchers Using QualAI:** Your research benefits from methodologies shared by others. Consider giving back! **To Methodology Innovators:** Your unique approach could revolutionize how thousands conduct research. Share it! **To the Qualitative Research Community:** Together, we're building the world's most comprehensive, open, and accessible methodology library. **Let's transform qualitative research together.** [**→ Start Contributing Today**](https://github.com/qualai-community/methodologies) --- **Made with ❤️ by researchers, for researchers** **Version**: 1.0.0 **Last Updated**: 2025-11-02