Rawsug Fastmcp Demo
No description available
Ask AI about Rawsug Fastmcp Demo
Powered by Claude Β· Grounded in docs
I know everything about Rawsug Fastmcp Demo. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
FastMCP Vinyl Collection Chatbot
A production-ready serverless chatbot demonstrating Model Context Protocol (MCP) and FastMCP on AWS. Built for live AWS User Group demo in Richmond.
Overview
This project showcases:
- MCP: Universal contract for agent-to-tool integration
- FastMCP: Easy tool authoring with schemas, validation, and registry
- AWS Serverless: S3 + CloudFront for web UI, API Gateway + Lambda for backend
- Agentic AI: Deterministic routing with optional Bedrock enhancement
Chat naturally about your vinyl collection:
- "What records do I have by Grimes?"
- "Do I have anything on 4AD?"
- "Show me records from 2016"
- "Give me a quick stats summary"
Architecture
User Browser
β HTTPS
CloudFront Distribution
β OAC
S3 Website Bucket (Private)
User Browser
β API Calls
API Gateway (HTTP API)
β Invoke
Lambda Function (Python 3.11)
β Read CSV
S3 Data Bucket (discogs.csv)
β Logs
CloudWatch Logs
β Optional
AWS Bedrock (Claude 3.5 Haiku)
See architecture/diagram.md for detailed diagrams.
Prerequisites
- AWS Account with appropriate permissions
- Terraform >= 1.5.0
- Python 3.11
- AWS CLI configured with credentials
- Discogs CSV export of your vinyl collection
Quick Start
1. Clone and Install Dependencies
git clone <repository-url>
cd vinyl-collection-chatbot
pip install -r app/requirements.txt
2. Run Tests
cd app
pytest -v
3. Deploy Infrastructure
cd infra
# Copy and edit variables
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your AWS region and project name
# Initialize and deploy
terraform init
terraform plan
terraform apply
4. Upload Your Discogs CSV
After deployment, Terraform outputs the data bucket name:
# Get bucket name from Terraform output
DATA_BUCKET=$(terraform output -raw data_bucket_name)
# Upload your Discogs CSV
aws s3 cp /path/to/your/discogs.csv s3://${DATA_BUCKET}/discogs.csv
5. Access the Chatbot
Terraform outputs the CloudFront URL:
terraform output cloudfront_url
Open this URL in your browser to start chatting!
Discogs CSV Format
Export your collection from Discogs. The system expects these columns:
Catalog#- Catalog numberArtist- Artist nameTitle- Album/release titleLabel- Record labelFormat- Format (Vinyl, CD, etc.)Rating- Your ratingReleased- Release yearrelease_id- Discogs release IDCollectionFolder- Folder nameDate Added- Date added to collectionCollection Media Condition- Media conditionCollection Sleeve Condition- Sleeve condition
Missing columns are handled gracefully with partial functionality.
Optional: Enable Bedrock Mode
By default, the system uses deterministic routing. To enable Bedrock for enhanced conversational responses:
- Ensure your AWS account has access to Claude 3.5 Haiku in Bedrock
- Update Lambda environment variables in
infra/lambda.tf:environment { variables = { USE_BEDROCK = "true" BEDROCK_MODEL_ID = "anthropic.claude-3-5-haiku-20241022-v1:0" BEDROCK_REGION = "us-east-1" # ... other variables } } - Redeploy:
terraform apply
Development
Project Structure
βββ app/ # Backend application
β βββ server.py # Lambda handler
β βββ requirements.txt # Python dependencies
β βββ vinyl/ # Core modules
β β βββ discogs.py # CSV reader
β β βββ router.py # Deterministic router
β β βββ tools.py # FastMCP tools
β βββ tests/ # Test suite
βββ web/ # Frontend
β βββ index.html # Chatbot UI
β βββ app.js # Application logic
β βββ styles.css # Styling
β βββ config.js.tmpl # Config template
βββ infra/ # Terraform infrastructure
β βββ main.tf
β βββ providers.tf
β βββ variables.tf
β βββ outputs.tf
β βββ iam.tf
β βββ apigw.tf
β βββ lambda.tf
β βββ s3.tf
β βββ cloudfront.tf
β βββ website.tf
βββ architecture/ # Documentation
βββ diagram.md
Running Tests Locally
cd app
pytest -v # Run all tests
pytest -v -k test_discogs # Run specific test file
pytest -v --cov=vinyl # Run with coverage
All tests use mocked AWS services (moto) and run without credentials.
API Endpoints
POST /chat- Process chat message- Request:
{ "message": "string", "sessionId": "string", "mode": "auto|deterministic|bedrock" } - Response:
{ "answer": "string", "toolUsed": bool, "toolName": "string", ... }
- Request:
GET /tools- List available tools and schemasGET /health- Health check
Tools
The chatbot provides four FastMCP tools:
- query_vinyl_collection - Query by artist, title, label, year, or all fields
- list_artists - List unique artists with optional prefix filter
- stats_summary - Get collection statistics
- filter_records - Filter by multiple criteria with year ranges
Troubleshooting
Lambda can't read CSV
- Verify CSV is uploaded to the data bucket
- Check Lambda IAM role has S3 read permissions
- Check CloudWatch logs for detailed errors
Frontend can't reach API
- Verify CORS is configured on API Gateway
- Check CloudFront distribution is deployed
- Verify config.js has correct API_BASE_URL
Tests failing
- Ensure Python 3.11 is installed
- Install all dependencies:
pip install -r app/requirements.txt - Check that moto is properly installed for AWS mocking
Cleanup
To remove all AWS resources:
cd infra
terraform destroy
Note: S3 buckets with content may need to be emptied first.
License
MIT License - See LICENSE file for details
Demo Notes
This is a production-ready demo showcasing:
- FastMCP tool definitions with automatic schema generation
- Serverless AWS architecture with least-privilege IAM
- Deterministic routing that works without LLMs
- Optional Bedrock integration for enhanced responses
- Comprehensive testing with property-based tests
- Infrastructure-as-code with Terraform
Perfect for demonstrating modern agentic AI patterns on AWS!
