youngliving/yl-mcp

MCP Server Template for Young Living

A production-ready template for building Model Context Protocol (MCP) servers at Young Living, featuring OAuth authentication, AWS deployment, and comprehensive monitoring.

What is this template?

This template provides everything you need to quickly build and deploy MCP servers that integrate with Young Living's infrastructure. It includes:

• Multiple transport protocols (stdio, HTTP-SSE, HTTP-Streamable)
• Young Living OAuth integration with secure session management
• AWS deployment infrastructure using ECS Fargate
• Comprehensive monitoring with CloudWatch and health checks
• Production-ready patterns following YL best practices

Quick Start

Prerequisites

• Node.js 18.0.0 or newer
• pnpm 9.x or newer
• AWS CLI configured with Young Living credentials
• Docker (optional, for local development)

1. Set up the template

This is a template repository with placeholder values that need to be replaced. You must run the template setup process first:

# Clone and install
git clone <your-repo-url>
cd your-project
pnpm install

# Follow the template setup instructions
# See TEMPLATE-SETUP.md for detailed instructions

2. Build and test

# Build the project
pnpm build

# Test the MCP server locally
pnpm start

# Run tests
pnpm test

3. Deploy to AWS

# Deploy to development environment
pnpm deploy:dev

What's included?

🔧 Core Features

• MCP Protocol Implementation: Full support for Model Context Protocol with resources, tools, and prompts
• Multiple Transports: Choose between stdio, HTTP-SSE, or HTTP-Streamable based on your needs
• TypeScript: Full type safety with strict mode enabled
• Testing Framework: Vitest with comprehensive test coverage

🔐 Security & Authentication

• YL OAuth Integration: Built-in OAuth2 flow with PKCE for web-based access
• Session Management: Secure DynamoDB-backed session storage
• IAM Roles: Least-privilege access patterns
• Parameter Store: Secure credential management

☁️ AWS Infrastructure

• ECS Fargate: Containerized deployment with auto-scaling
• Application Load Balancer: Custom domain with TLS termination
• DynamoDB: Session storage and data persistence
• CloudWatch: Comprehensive logging and monitoring
• Route53: DNS management with custom domains

🛠️ Developer Experience

• Hot Reload: Development server with automatic restarts
• Docker Support: Local development containers
• CDK Infrastructure: Infrastructure as code using Young Living's CDK patterns
• Health Checks: Built-in health endpoints for monitoring

Development Commands

Deployment Commands

Project Structure

src/
├── handlers/           # MCP request handlers
│   ├── prompts.ts     # AI prompt generation
│   ├── resources.ts   # Resource access (customize for your data)
│   ├── templates.ts   # Project templates
│   └── tools.ts       # Utility tools
├── transports/        # Transport protocol implementations
├── utils/             # Configuration and utilities
├── index.ts           # Application entry point
└── server.ts          # Core MCP server implementation

stacks/                # AWS CDK infrastructure
├── mcp-server-stack.ts        # Main ECS deployment
└── mcp-session-storage-stack.ts # DynamoDB session storage

config/                # OAuth and environment configuration
tests/                 # Test files

Transport Protocols

stdio (Default)

Perfect for CLI tools and local development:

pnpm start
echo '{"jsonrpc": "2.0", "method": "initialize", "id": 1, "params": {...}}' | node dist/index.js

HTTP Server-Sent Events (SSE)

Great for real-time web applications:

pnpm start:sse
# Access at: http://localhost:3000/sse

HTTP Streamable

Ideal for streaming responses:

pnpm start:streamable
# Access at: http://localhost:3000/mcp

Dual HTTP

Supports both SSE and Streamable:

pnpm start:http
# SSE: http://localhost:3000/sse
# Streamable: http://localhost:3000/mcp

Customizing for Your Use Case

1. Update Resource Handlers

Edit src/handlers/resources.ts to provide access to your data:

// Replace example resources with your own
const resources = [
  {
    uri: "myapp://documents/",
    name: "Company Documents",
    description: "Access to company documentation"
  }
];

2. Add Custom Tools

Edit src/handlers/tools.ts to add functionality:

// Add tools that your MCP server can perform
export const tools = [
  {
    name: "search_documents",
    description: "Search through company documents",
    inputSchema: { /* ... */ }
  }
];

3. Configure Authentication

Update config/auth*.json files with your OAuth client settings when ready to deploy.

Testing Your MCP Server

Using MCP Inspector

# Test stdio transport
npx @modelcontextprotocol/inspector --cli node dist/index.js

# Test HTTP transport
npx @modelcontextprotocol/inspector --cli http://localhost:3000

# List available prompts
npx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list

Health Check

curl http://localhost:3000/health
# Returns: {"status": "healthy", "service": "your-service-name"}

Deployment

The template is designed for production deployment on AWS ECS Fargate. After template setup:

1. Review OAuth Configuration: Update client IDs in config/auth*.json
2. Deploy to Development: pnpm deploy:dev
3. Test Remote Deployment: pnpm test:remote:dev
4. Deploy to Production: pnpm deploy:prod

Environment Variables

Support

For questions or issues:

1. Check the for setup instructions
2. Review the project documentation
3. Contact the Platform Engineering team
4. Create an issue with detailed reproduction steps

What's Next?

After setting up your MCP server:

1. Customize the handlers in src/handlers/ for your specific use case
2. Add your business logic and integrate with your data sources
3. Configure OAuth settings when ready to deploy
4. Set up monitoring and alerting for production use
5. Deploy to development and test thoroughly before production

This template gets you from zero to production-ready MCP server in minutes, not days.