Simplified MCP server for streaming Amplify Gen2 sandbox and appserver dev server logs
npm install @chinchillaenterprises/mcp-dev-loggerStreamlined Development Server Manager for Amplify Gen 2 Projects
A Model Context Protocol (MCP) server that manages Amplify Gen2 sandbox and application development servers with intelligent logging and AI self-education features.
Two core capabilities:
1. Amplify Sandbox Management - Start/stop/monitor npx ampx sandbox --stream-function-logs
2. Application Dev Server Management - Start/stop dev servers (Next.js, Vite, etc.) with optional port forcing (critical for OAuth)
Key Features:
- Multi-project safe (uses working directory detection)
- Auto-kills stuck processes before starting fresh
- Streams logs to organized directories (resources/sandbox/, resources/appserver/)
- AI self-education system (commands AI to learn Amplify on startup)
``bash`
claude mcp add dev-logger -s user -- npx @chinchillaenterprises/mcp-dev-logger
---
#### dev_start_sandbox
Start Amplify Gen2 sandbox with streaming function logs.
What it does:
- Checks if a sandbox is already running in THIS project directory
- Kills existing sandbox if found (prevents stuck sandboxes)
- Starts fresh: npx ampx sandbox --stream-function-logsresources/sandbox/sandbox.log
- Streams logs to
- Commands AI to educate itself on Amplify Gen 2
Multi-project safe: Uses lsof to match working directory, only affects THIS project's sandbox
Usage:
`typescript`
dev_start_sandbox()
Returns:
`json
{
"success": true,
"message": "Amplify sandbox started. Logs: /path/to/resources/sandbox/sandbox.log",
"logFile": "/path/to/resources/sandbox/sandbox.log",
"AI_INSTRUCTIONS": "🎓 AI INSTRUCTIONS - EXECUTE IMMEDIATELY:
1. Call mcp__amplify-docs__get_amplify_concepts with { \"concept\": \"core-principles\" }
2. Call mcp__amplify-docs__get_sandbox_details with { \"topic\": \"sandbox-workflow\" }
3. Read resources/patterns/README.md for implementation patterns with Amplify Gen 2
CRITICAL - UNDERSTAND THESE LOGS:
- CloudFormation deployment progress
- Lambda function invocations (GraphQL queries/mutations, auth)
- console.log statements from your Lambda code
- Errors and stack traces
..."
}
`
Why AI_INSTRUCTIONS?
When a new AI or context-less AI starts the sandbox, they're automatically commanded to:
- Learn Amplify Gen 2 concepts via amplify-docs MCP tools
- Read the local patterns guide for implementation details
- Understand what's in the logs (not just deployment, but runtime execution)
This ensures every AI knows how to help with backend development immediately.
---
#### dev_stop_sandbox
Stop the running Amplify sandbox process.
Usage:
`typescript`
dev_stop_sandbox()
Returns:
`json`
{
"success": true,
"message": "Amplify sandbox stopped successfully."
}
Note: This does NOT delete CloudFormation stacks. To delete AWS resources, run npx ampx sandbox delete manually.
---
#### dev_tail_sandbox_logs
Get the last N lines from the sandbox log file.
Parameters:
- lines (optional): Number of lines to return (default: 50)
Usage:
`typescript
// Last 50 lines
dev_tail_sandbox_logs()
// Last 100 lines
dev_tail_sandbox_logs({ "lines": 100 })
`
What you'll see:
- CloudFormation stack deployment progress
- Lambda function invocations when user tests the app
- console.log statements from Lambda code in amplify/data/, amplify/auth/, amplify/functions/*
- Errors and stack traces
- Real-time CloudWatch streaming
---
#### dev_start_appserver
Start application development server with optional port specification.
What it does:
- Starts npm run dev for application development (Next.js, Vite, etc.)resources/appserver/appserver.log
- Optionally kills any process on specified port (for OAuth callbacks requiring specific ports)
- Detects actual port from server output
- Streams logs to
Port Parameter (optional):
- Not specified: Server picks next available port (3000, 3001, 3002, etc.)
- Specified: Kills anything on that port first, then starts on that exact port
Usage:
`typescript
// Let server pick the port
dev_start_appserver()
// Force port 3000 (kills anything on 3000 first)
dev_start_appserver({ "port": 3000 })
`
Why force a port?
OAuth providers (Google, Cognito, Facebook) require exact redirect URIs like:
- http://localhost:3000/api/auth/callback
If your dev server starts on 3001, OAuth fails. Port forcing solves this.
Returns:
`json`
{
"success": true,
"message": "Started appserver. Running on port 3000. Logs: /path/to/resources/appserver/appserver.log",
"logFile": "/path/to/resources/appserver/appserver.log",
"port": 3000,
"killedPort": 3000
}
---
#### dev_stop_appserver
Stop the running application development server.
Usage:
`typescript`
dev_stop_appserver()
Returns:
`json`
{
"success": true,
"message": "Appserver stopped successfully."
}
---
typescript
// 1. Start backend (Amplify sandbox)
dev_start_sandbox()
// AI automatically educates itself on Amplify Gen 2// 2. Start appserver (dev server on port 3000 for OAuth)
dev_start_appserver({ "port": 3000 })
// 3. Work on code...
// Both servers auto-reload on changes
// 4. Debug backend issues
dev_tail_sandbox_logs({ "lines": 100 })
// 5. Stop when done
dev_stop_sandbox()
dev_stop_appserver()
`$3
`typescript
// Just working on Lambda functions, GraphQL, auth
dev_start_sandbox()// Check logs when testing
dev_tail_sandbox_logs()
// Stop when done
dev_stop_sandbox()
`$3
`typescript
// Just working on UI, already have backend deployed
dev_start_appserver()// Stop when done
dev_stop_appserver()
`---
Multi-Project Safety
Problem: You have 3 VSCode windows open with different Amplify projects, each running a sandbox and dev server.
How this tool handles it:
- Uses
ps aux + lsof -a -d cwd -p to match processes to working directories
- Only kills/affects processes in the current project directory
- Other projects' servers continue running undisturbed
- Logs are organized per project: , ---
AI Self-Education System
When
dev_start_sandbox is called, the return includes AI_INSTRUCTIONS that command the AI to:1. Learn theory - Call
mcp__amplify-docs__get_amplify_concepts for architecture understanding
2. Learn workflow - Call mcp__amplify-docs__get_sandbox_details for deployment process
3. Learn practice - Read resources/patterns/README.md for implementation patternsWhy this matters:
- Dumb AIs or context-less AIs get instant Amplify knowledge
- AI understands what's in the logs (runtime execution, not just deployment)
- AI knows to call amplify-docs tools later when needed
- Reduces user handholding ("go read the docs")
---
Log Format
All logs are timestamped with ISO 8601 format:
`
[2025-10-03T14:23:45.123Z] Starting Amplify sandbox: npx ampx sandbox --stream-function-logs
[2025-10-03T14:23:50.456Z] Amplify Gen 2 sandbox starting...
[2025-10-03T14:24:10.789Z] [INFO] Stack deployment in progress...
[2025-10-03T14:24:15.012Z] Lambda function invoked: createTodo
[2025-10-03T14:24:15.234Z] console.log: Creating todo for user abc123
[2025-10-03T14:24:15.567Z] [ERROR] DynamoDB validation error: Missing required field 'title'
[2025-10-03T14:25:00.890Z] Amplify sandbox exited with code 0 and signal null
`---
Requirements
- Node.js: 18+
- AWS Amplify Gen2 project (for sandbox tools)
- Development server project (Next.js, Vite, etc. - for appserver tools)
- AWS credentials configured (for sandbox)
The
resources/ folder is created automatically if it doesn't exist.---
Troubleshooting
$3
- Verify you're in an Amplify Gen2 project directory
- Check npx ampx is available: npx ampx --version
- Verify AWS credentials: aws sts get-caller-identity$3
- Check resources/sandbox/ or resources/appserver/ folders exist (auto-created)
- Call dev_tail_sandbox_logs() to verify logs are being written$3
- Use port forcing: dev_start_appserver({ "port": 3000 })
- This kills anything on port 3000 first, then starts there$3
- Call stop command again
- Restart Claude Code if stuck
- Processes are cleaned up automatically on MCP server shutdown---
Development
`bash
Build
npm run buildInstall locally for testing
claude mcp add dev-logger-test -s user -- node $(pwd)/dist/index.jsPublish
npm publish --access public
`---
Version History
v3.2.1 (Current)
- Renamed
dev_start_nextjs → dev_start_appserver
- Renamed dev_stop_nextjs → dev_stop_appserver
- Updated all references from "frontend" to "appserver"
- Changed log directory from resources/frontend/ to resources/appserver/
- Prevents AI from using bash npm run dev` instead of the toolv3.2.0
- Added kill-existing-appserver logic (like sandbox has)
- Multi-project safety for appserver processes
v3.1.3
- AI self-education via AI_INSTRUCTIONS in sandbox return
- Commands AI to call amplify-docs MCP tools and read patterns guide
v3.1.0
- Added dev server management with port forcing for OAuth
v3.0.1
- Enhanced tool descriptions with educational context for AI
v3.0.0
- Major simplification: hardcoded sandbox command, removed complexity
- Multi-project detection with working directory matching
- Auto-kill existing sandbox before starting fresh
---
MIT License
For issues and questions:
- GitHub: ChinchillaEnterprises/ChillMCP
- Open an issue in the repository