MCP Amplify Docs Revamped

✅ PRODUCTION READY & FULLY OPERATIONAL - Live AWS Amplify documentation server with 245 real operations extracted from official docs

🚀 CRITICAL SUCCESS - FACTORY IS OPERATIONAL!

DATA STATUS: ✅ LIVE with 7,099 lines / 227KB of real AWS documentation!

• 245 operations extracted from official AWS Amplify docs
• 5 categories: general, storage, data, auth, functions
• Generated: 2025-07-30 (fresh extraction from GitHub)
• All components tested and functional

🤖 FOR AI ASSISTANTS: COMPLETE REPRODUCTION GUIDE

If you need to reproduce this system or understand how it works, here's the complete process that was successfully executed:

🏗️ Architecture Overview

AWS Amplify GitHub Docs → MDX Parser → Content Transformer → JSON Schema Validator → MCP Tools → Claude AI

📁 Directory Structure Explained

• src/: Main source code
  • parser/: MDX parsing engine (handles AWS-specific components)
  • transformer/: Converts parsed MDX to AI-optimized JSON
  • tools/: 5 MCP tools that serve documentation to Claude
  • schemas/: JSON validation and data quality assurance
  • types/: TypeScript interfaces for type safety
• scripts/: Automation pipeline
  • clone-docs.js: Downloads AWS docs (~100MB git repo)
  • extract-docs.js: Main extraction engine
  • build-weekly.js: Orchestrates weekly updates
• generated/: CRITICAL - Contains amplify-docs.json (7,099 lines of real data)
• tests/: Comprehensive test suite with fixtures
• aws-amplify-docs/: Cloned AWS repository (git ignored, auto-generated)

🔄 CRITICAL REPRODUCTION STEPS

Step 1: Initial Setup

# Navigate to project
cd mcp-amplify-docs-revamped

# Install all dependencies (includes MDX parsing, file system, glob utilities)
npm install

# CRITICAL: Build TypeScript first
npm run build

Step 2: Data Population (THE KEY STEP)

# Clone AWS Amplify docs repository (~100MB, takes 1-2 minutes)
npm run clone-docs

# Extract and transform documentation (THIS IS THE MAGIC)
npm run extract-docs

Expected Output:

• Process 251 MDX files from AWS
• Extract 245 operations
• Generate 7,099-line JSON file (227KB)
• Create structured data for 5 categories

Step 3: Verification

# Check that real data was extracted
wc -l generated/amplify-docs.json  # Should show ~7,099 lines
ls -lh generated/amplify-docs.json # Should show ~227KB

# Test the MCP server locally
node dist/index.js  # Should start without errors

🚨 COMMON PITFALLS & SOLUTIONS

Problem 1: Empty/Small JSON File

• Symptom: generated/amplify-docs.json only has ~226 lines / 16KB
• Cause: Extraction pipeline never ran successfully
• Solution: Run npm run extract-docs after npm run clone-docs

Problem 2: Module Not Found Errors

• Symptom: Cannot find module 'fs-extra' or similar
• Cause: Dependencies not installed
• Solution: npm install then npm run build

Problem 3: TypeScript Compilation Errors

• Symptom: Build fails with type errors
• Cause: MCP SDK type mismatches
• Solution: Check src/index.ts handler returns are cast as any

Problem 4: Glob API Errors

• Symptom: promisify errors in extraction
• Cause: Newer glob versions have different API
• Solution: Use const { glob } = require('glob') (not const glob = require('glob'))

🔧 Technical Deep Dive

MDX Parser Engine:

• Handles AWS-specific JSX components (<InlineFilter>, <Callout>, <Tabs>)
• Filters content for JavaScript platforms only (skips mobile)
• Extracts metadata, code blocks, prerequisites, errors

Content Transformer:

• Converts MDX AST to structured JSON
• Groups implementations by variant (basic, social, mfa, advanced)
• Extracts patterns, imports, warnings, next steps

MCP Tools:

• get_amplify_code: Returns implementation examples
• get_amplify_setup: Backend configuration guidance
• get_amplify_errors: Error handling and troubleshooting
• get_amplify_concepts: Conceptual explanations
• search_amplify_docs: Smart search across all docs

📊 Data Quality Metrics

• Coverage: 245 operations from 251 processed files (97.6% success rate)
• Categories: 5 main categories with balanced distribution
• Platforms: JavaScript, TypeScript, React, Next.js, Vue, Angular
• Content Types: Code examples, setup instructions, error handling, concepts

🔄 Weekly Automation

GitHub Actions workflow runs every Sunday to:

1. Clone latest AWS docs
2. Run extraction pipeline
3. Detect changes in content
4. Publish updated NPM package if changes found
5. Create GitHub release with changelog

Why Revamped?

The original mcp-amplify-docs contained 3,000+ lines of hardcoded documentation that quickly became outdated. This new version:

• 📅 Always Current: Automatically extracts from AWS Amplify's official docs weekly
• 🎯 AI-Optimized: Structured for faster, more accurate AI responses
• 🚀 Better Performance: 4-5 smart tools instead of 20+ granular ones
• 📦 Smaller, Smarter: Only JavaScript/TypeScript platforms, only Gen 2

Quick Start

# Install the MCP server
claude mcp add amplify-docs -s user -- npx @chinchillaenterprises/mcp-amplify-docs-revamped

# Start Claude and use the tools
claude

Available Tools

🔧 get_amplify_code

Get implementation code examples with full context.

Parameters:

• feature (required): Feature identifier like "auth.signIn", "storage.upload"
• variant (optional): Implementation variant like "basic", "social", "mfa"

Example:

Human: How do I implement social login with Google?

Claude will call: get_amplify_code({ feature: "auth.signIn", variant: "social" })

Returns complete code example with imports, prerequisites, and common mistakes.

📋 get_amplify_setup

Get backend configuration and setup instructions.

Parameters:

• category (required): "auth", "storage", "data", "functions", or "ai"
• feature (optional): Specific feature within category

Example:

Human: How do I set up authentication with MFA?

Claude will call: get_amplify_setup({ category: "auth", feature: "mfa" })

Returns backend configuration with all options explained.

❌ get_amplify_errors

Get error handling and troubleshooting guidance.

Parameters:

• feature (required): Feature experiencing errors
• errorCode (optional): Specific error code

Example:

Human: I'm getting NotAuthorizedException when signing in

Claude will call: get_amplify_errors({ feature: "auth.signIn", errorCode: "NotAuthorizedException" })

Returns error explanation, common causes, and solutions.

💡 get_amplify_concepts

Get conceptual explanations and architecture guidance.

Parameters:

• topic (required): Concept like "mfa", "authorization", "real-time"

Example:

Human: Explain how Amplify authorization works

Claude will call: get_amplify_concepts({ topic: "authorization" })

Returns detailed explanation with diagrams and examples.

🔍 search_amplify_docs

Search across all documentation.

Parameters:

• query (required): Search terms
• category (optional): Limit to specific category

Example:

Human: How do I handle file uploads with progress tracking?

Claude will call: search_amplify_docs({ query: "upload progress", category: "storage" })

Returns relevant documentation sections.

Migration from Original mcp-amplify-docs

What's Changed

| Old Server | New Server | |------------|------------| | 20+ specific tools | 4-5 smart tools | | Hardcoded strings | Dynamic JSON | | Monthly manual updates | Weekly automatic updates | | All platforms | JavaScript/TypeScript only | | Gen 1 + Gen 2 | Gen 2 only |

Tool Mapping

| Old Tool | New Tool | Parameters | |----------|----------|------------| | get_auth_setup | get_amplify_setup | { category: "auth" } | | get_auth_client_code | get_amplify_code | { feature: "auth.*" } | | get_storage_operations | get_amplify_code | { feature: "storage.*" } | | get_function_setup | get_amplify_setup | { category: "functions" } |

Breaking Changes

1. Tool Names: All tools now start with get_amplify_
2. Parameters: More flexible parameter structure
3. Response Format: Consistent markdown with better formatting

Advanced Usage

Understanding Features

Features follow a category.operation pattern:

• auth.signIn - Sign in existing users
• auth.signUp - Register new users
• storage.upload - Upload files to S3
• storage.download - Download files from S3
• data.query - Query GraphQL data
• data.mutate - Mutate GraphQL data
• functions.invoke - Call Lambda functions

Response Structure

All tools return markdown-formatted responses with:

1. 📍 Prerequisites - What must be configured first
2. Implementation - Complete code examples
3. Common Mistakes - What to avoid
4. Related Operations - What to explore next
5. Errors - Potential errors and solutions

For Developers

Local Development

# Clone the repository
git clone https://github.com/ChinchillaEnterprises/ChillMCP.git
cd mcp-amplify-docs-revamped

# Install dependencies
npm install

# Clone AWS docs (first time only)
npm run clone-docs

# Extract and transform docs
npm run extract-docs

# Run tests
npm test

# Build the server
npm run build

# Test locally
claude mcp add amplify-local -s user -- node $(pwd)/dist/index.js

How It Works

1. Weekly Automation: GitHub Actions runs every Sunday
2. Doc Extraction: Clones AWS Amplify docs, parses MDX files
3. Transformation: Converts to AI-optimized JSON structure
4. Validation: Ensures data quality with JSON Schema
5. Publishing: Updates NPM package if changes detected

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Architecture

Input (MDX Files) → Parser (AST) → Transformer (JSON) → Validator → MCP Tools
                                                                        ↓
                                                                    Claude AI

Troubleshooting

"Feature not found" Error

• Check available features with search_amplify_docs
• Ensure you're using Gen 2 feature names
• Try without the variant parameter

Outdated Information

• The server updates weekly on Sundays
• Check NPM version: npm show @chinchillaenterprises/mcp-amplify-docs-revamped version
• Force update: claude mcp update amplify-docs

Performance Issues

• First call may be slower (loading JSON)
• Subsequent calls should be < 50ms
• Report issues on GitHub

License

MIT © Chinchilla Enterprises

Built with ❤️ by Chinchilla Enterprises for the AWS Amplify community