WebAgent

Overview

Features

Quick Start

Prerequisites

Install Dependencies

# Clone the repository
git clone https://github.com/opentiny/web-agent.git
cd web-agent
# Install dependencies
pnpm install

Configure Environment Variables

cp example.env .env

Start the Service

# Development mode (hot reload)
pnpm dev
# Build production version
pnpm build
# Run production version (requires dist from build)
pnpm start
# Run with PM2
pnpm pm2:start

Project Architecture

web-agent/
├── src/
│ ├── app.ts # Application entry point
│ ├── server.ts # Server startup file
│ ├── Logger.ts # Winston logger configuration
│ ├── config/
│ │ ├── index.ts # Application configuration
│ │ └── logger.ts # Logger configuration
│ ├── middleware/
│ │ ├── index.ts # Middleware entry point
│ │ ├── corsMiddleware.ts # CORS handling
│ │ ├── errorMiddleware.ts # Error handling
│ │ ├── loggingMiddleware.ts # Request logging
│ │ ├── requestIdMiddleware.ts # Request ID
│ │ ├── securityMiddleware.ts # Security headers
│ │ └── validationMiddleware.ts # Request validation
│ ├── routes/
│ │ ├── index.ts # Routes entry point
│ │ ├── health.ts # Health check routes
│ │ └── v1/
│ │ ├── index.ts # v1 API routes entry
│ │ └── webmcp.ts # MCP proxy routes
│ └── utils/
│ └── ... # Utility functions
├── ecosystem.config.cjs # PM2 configuration
├── example.env # Environment variables example
├── package.json
└── tsconfig.json

Core Modules

API Endpoints

Health Check

MCP Proxy Endpoints

Debugging with MCP Inspector

# SSE Mode
http://localhost:3000/api/v1/webmcp/sse?sessionId=<your-session-id>
# Streamable HTTP Mode
http://localhost:3000/api/v1/webmcp/mcp?sessionId=<your-session-id>

Deployment Guide

Development Environment

# Use nodemon for hot reload
pnpm dev

Production Environment

Using PM2 (Recommended)

# Start
pnpm pm2:start
# Check status
pm2 status
# View logs
pnpm pm2:logs
# Stop
pnpm pm2:stop
# Restart
pnpm pm2:restart
# Delete
pnpm pm2:delete

Using Docker

FROM node:22-alpine
WORKDIR /app
COPY package.json ./
COPY pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile --prod
COPY dist ./dist
ENV NODE_ENV=production
ENV AGENT_PORT=3000
ENV AGENT_HOST=0.0.0.0
EXPOSE 3000
CMD ["node", "dist/server.js"]

Nginx Reverse Proxy Configuration Example

upstream webagent {
 server 127.0.0.1:3000;
}
server {
 listen 80;
 server_name your-domain.com;
 location / {
 proxy_pass http://webagent;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection 'upgrade';
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_cache_bypass $http_upgrade;
 # SSE Support
 proxy_buffering off;
 proxy_read_timeout 86400;
 }
}

Configuration

PM2 Configuration

Development Guide

Script Commands

pnpm dev # Run in development mode
pnpm build # Build production version
pnpm start # Run production version
pnpm lint # Code linting
pnpm lint:fix # Auto-fix lint issues
pnpm format # Format code
pnpm format:check # Check formatting
pnpm test # Run tests

Code Standards

Contributing

Related Links