Email Order Agent

An AI-powered agent that processes food orders from emails automatically. The agent monitors an email inbox, uses LLM-based intent detection and data extraction, and submits orders via MCP (Model Context Protocol) tools.

Architecture Overview

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│                 │     │                 │     │                 │
│  Email Inbox    │────▶│  Agent          │────▶│  MCP Server     │
│  (IMAP)         │     │  (LangChain)    │     │  (Products/DB)  │
│                 │     │                 │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌─────────────────┐
                        │                 │
                        │  LangSmith      │
                        │  (Observability)│
                        │                 │
                        └─────────────────┘

Project Structure

email-order-intake/
├── apps/
│   ├── agent/              # AI Agent (to be built in workshop)
│   │   └── src/
│   │       ├── agent/      # Pipeline nodes and orchestration
│   │       ├── mcp/        # MCP client connection
│   │       ├── services/   # Email listener
│   │       └── utils/      # PII redaction utilities
│   ├── dashboard/          # Next.js dashboard to view orders
│   └── mcp/                # MCP server with product/order tools
├── packages/
│   ├── config/             # Shared TypeScript config
│   └── logger/             # Shared logging utilities

Agent Pipeline Flow

The agent processes emails through a sequential pipeline:

1. Intent Detection - Determines if the email is a food order
2. Data Extraction - Extracts customer name and order items
3. Product Lookup - Enriches items with product details via MCP
4. Order Submission - Submits the finalized order to the database

Prerequisites

• Node.js 24+
• pnpm 9+
• OpenAI API key (or compatible provider)
• Neon Database (for orders and products)
• Email account with IMAP access (Gmail recommended)
• LangSmith account (for observability - optional but recommended)

Getting Started

1. Install dependencies

pnpm install

2. Configure environment variables

Copy the example files and fill in your credentials:

# MCP Server
cp apps/mcp/.env.example apps/mcp/.env

# Agent (if present)
cp apps/agent/.env.example apps/agent/.env

# Dashboard
cp apps/dashboard/.env.example apps/dashboard/.env

3a. Set up email listener

IMAP requires an app password (not your regular account password). To generate one:

• Gmail: Go to App Passwords and create a new app password
• Other providers: Check your email provider's documentation for app-specific passwords

Add your email credentials to apps/agent/.env:

EMAIL_ID=your-email@gmail.com
EMAIL_HOST=imap.gmail.com
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password

Test the connection to your email account:

pnpm agent:test:email

3b. Set up the database

Note: This step is only required if you're using your own Neon database. If you're using a pre-configured workshop database, skip to step 4.

1. Go to neon.com and create an account
2. Create a new project and copy your connection string (starts with postgresql://)
3. Add the connection string to apps/mcp/.env and apps/dashboard/.env as ORDER_DATABASE_URL
4. Run the migrations and seed:

# Run migrations
pnpm --filter mcp migrate

# Seed products data
pnpm --filter mcp seed:products

4. Start the services

# Start MCP server (required)
pnpm mcp:dev

# Start the Agent (in a separate terminal)
pnpm agent:dev

# Or start the MCP server and Agent simultaneously
pnpm dev

# Start the dashboard (optional, in a separate terminal)
pnpm dashboard:dev

Available Scripts

Root workspace

Command	Description
pnpm dev	Start MCP server and agent in development
pnpm build	Build all packages
pnpm check-types	Type-check all packages

MCP Server

Command	Description
pnpm mcp:dev	Start MCP server in dev mode
pnpm mcp:test:db	Test database connection
pnpm mcp:test:inspector	Open MCP Inspector UI

Agent

Command	Description
pnpm agent:dev	Start agent in dev mode
pnpm agent:dev:debug	Start agent with debug logging
pnpm agent:test:nodes	Test the pipeline with sample emails
pnpm agent:test:email	Test email connection

Dashboard

Command	Description
pnpm dashboard:dev	Start dashboard in dev mode

Workshop

If you're here for the workshop, see WORKSHOP.md for step-by-step instructions to build the agent from scratch.

Tech Stack

• Runtime: Node.js with TypeScript
• AI/LLM: LangChain with OpenAI
• Protocol: Model Context Protocol (MCP)
• Email: IMAP via imapflow
• Database: Neon PostgreSQL
• Observability: LangSmith
• Logging: Pino

License

MIT