intro-to-mcp-with-aws-bedrock-knowledge-bases

# MCP Bedrock Knowledge Base Server Connect your AI assistants (Q CLI, Q Developer) to AWS Bedrock Knowledge Bases using Model Context Protocol (MCP). ## 🎯 Learning Objectives 1. Understand MCP server fundamentals 2. Connect MCP servers to AWS Bedrock Knowledge Base 3. Integrate with AI assistants (Q CLI, Q Developer) 4. Create comprehensive documentation and testing # 🚀 Quick Start **Want to use the MCP server right now?** ## **👉 [Go to Phase 3 Quick Start Instructions](examples/phase-3-q-cli-integration/README.md#quick-start) 👈** This will get your MCP server running with Q CLI and Q Developer in minutes. --- ## 📚 Learning Path (Build Your Own) **Want to learn how MCP servers work?** This project teaches you step-by-step: ## 📚 Choose Your Learning Path ### Path A: Example Folders (Recommended for Beginners) **Best for**: New programmers, those unfamiliar with git ```bash # Clone the repository git clone <repository-url> cd mcp-bedrock-kb # Start with Phase 1 cd examples/phase-1-foundation # Follow the README in that folder ``` **Advantages**: - No git knowledge required - Complete working examples - Can't accidentally break previous work - Easy to compare phases side-by-side ### Path B: Git Tags (Recommended for Intermediate+) **Best for**: Developers familiar with git, want to see progression ```bash # Clone the repository git clone <repository-url> cd mcp-bedrock-kb # Start with Phase 1 git checkout phase-1-complete # Follow lessons/01-mcp-basics.md # Later, move to Phase 2 git checkout phase-2-complete ``` **Advantages**: - Learn professional git workflow - See exact code changes between phases - Understand development progression - Practice version control ## 📖 Learning Phases ### Phase 1: Foundation ✅ **Status**: Complete - Basic MCP server structure - Tool registration and handling - Testing methodology - Comprehensive documentation **Files**: `examples/phase-1-foundation/` or `git checkout phase-1-complete` ### Phase 2: AWS Integration ✅ **Status**: Complete - Connect to Bedrock Knowledge Base - Real query implementation - Response formatting - AWS authentication **Files**: `examples/phase-2-aws-integration/` or `git checkout phase-2-complete` ### Phase 3: Q CLI Integration ✅ **Status**: Complete - Configure MCP server for Q CLI - Virtual environment dependency management - Integration testing and validation - Troubleshooting common issues **Files**: `examples/phase-3-q-cli-integration/` or `git checkout phase-3-complete` ### Phase 4: Q Developer Integration 🔄 **Status**: In Development - Configure MCP server for Q Developer (IDE) - VS Code integration setup - Development workflow enhancement - Advanced IDE features **Files**: `examples/phase-4-q-developer-integration/` or `git checkout phase-4-complete` ## 🛠️ Prerequisites - Python 3.8+ - AWS CLI configured with credentials - AWS Bedrock Knowledge Base (optional - we'll help you create one) ## 🚀 Quick Start (Either Path) 1. Choose your learning path above 2. Follow the README in your chosen starting point 3. Work through lessons sequentially 4. Experiment and modify the code! ## 📋 Project Structure ``` mcp-bedrock-kb/ ├── examples/ # Complete phase examples │ ├── phase-1-foundation/ # Standalone working example │ ├── phase-2-aws-integration/ # AWS Bedrock KB integration │ └── phase-3-q-cli-integration/ # Q CLI MCP server setup ├── src/ # Current development ├── lessons/ # Step-by-step tutorials │ ├── 01-mcp-basics.md │ ├── 02-testing-basics.md │ └── 03-aws-integration.md ├── explanations/ # Detailed code explanations │ ├── server-explained.md │ ├── test-explained.md │ └── aws-integration-explained.md ├── tests/ # Test files │ ├── test_basic.py # Phase 1 reference │ ├── test_mcp_protocol.py # Current working test │ ├── test_q_cli_integration.py # Q CLI integration test │ └── comparative-testing/ # Knowledge base value demonstration │ ├── development-task-test.md │ ├── implementation_with_kb.py │ ├── implementation_without_kb.py │ └── comparative-analysis.md ├── README.md # This file └── implementation-plan.md # Development roadmap ``` ## 🎓 Educational Features - **Line-by-line explanations**: Every line of code explained for new programmers - **Why-focused learning**: Understanding the reasoning behind each decision - **Real-world testing**: Learn to test MCP servers properly - **Professional practices**: Git workflow, documentation, error handling ## 🤝 Contributing This is an educational project. Feel free to: - Suggest improvements to explanations - Report unclear documentation - Share your learning experience - Propose additional examples --- **Happy Learning!** 🎉 *Choose your path above and start building MCP servers that enhance AI assistants with your own knowledge bases.*