WebAgent

Intelligent Agent Hub Service - MCP Proxy Forwarding Solution

Features • Quick Start • Project Architecture • API Endpoints • Deployment Guide • Contributing

English | 简体中文

---

Overview

WebAgent is an open-source intelligent agent hub service that provides core MCP (Model Context Protocol) proxy forwarding functionality.

Features

• 🔄 MCP Proxy Forwarding: Full support for Model Context Protocol proxy forwarding
• 📡 SSE Connection Management: Support for Server-Sent Events real-time communication
• 🌐 Streamable HTTP: Support for streaming HTTP request handling
• 🏥 Health Checks: Comprehensive health check endpoints for monitoring and operations
• 🔒 Security Middleware: Built-in CORS, Helmet, and other security middleware
• 📝 Complete Logging: Winston-based logging system with sensitive information masking
• 🚀 Production Ready: PM2 process management support, suitable for production deployment

Quick Start

Prerequisites

• Node.js: >= 22.0.0
• pnpm: >= 10 (recommended)

Install Dependencies

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

# Install dependencies
pnpm install

Configure Environment Variables

Copy the example configuration file and modify as needed:

cp example.env .env

Environment Variables:

Variable	Description	Default
AGENT_PORT	Service listening port	3000
AGENT_HOST	Listening address	0.0.0.0
NODE_ENV	Runtime environment	development
CORS_ORIGIN	CORS origin list (comma-separated)	http://localhost:3000

Start the Service

# Development mode (hot reload)
pnpm dev

# Build production version
pnpm build

# Run production version
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

• MCP Proxy Module (routes/v1/webmcp.ts): Core functionality module that handles MCP protocol proxy forwarding, supporting both SSE and Streamable HTTP transport modes
• Middleware Layer (middleware/): Provides a complete request processing pipeline, including security, logging, validation, etc.
• Configuration Module (config/): Centralized application configuration management with environment variable overrides

API Endpoints

Health Check

Endpoint	Method	Description
/health	GET	Get system status and version info
/health/detailed	GET	Get detailed health status (memory, CPU, etc.)
/health/metrics	GET	Get performance metrics

MCP Proxy Endpoints

All MCP-related endpoints are prefixed with /api/v1/webmcp:

Endpoint	Method	Description
/api/v1/webmcp/ping	GET	Connection test
/api/v1/webmcp/sse	GET	SSE connection endpoint
/api/v1/webmcp/messages	POST	Message forwarding endpoint
/api/v1/webmcp/mcp	ALL	Streamable HTTP MCP endpoint
/api/v1/webmcp/list	GET	Get all client sessions
/api/v1/webmcp/remoter	GET	Get all controller sessions
/api/v1/webmcp/tools	GET	Get client tool list
/api/v1/webmcp/client	GET	Query single client info
/api/v1/webmcp/reset	GET	Reset all connections

Debugging with MCP Inspector

You can use the MCP Inspector tool to connect for debugging:

# 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

Using Docker

FROM node:22-alpine

WORKDIR /app
COPY package.json ./
RUN corepack enable && pnpm install --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

The project provides an ecosystem.config.cjs configuration file:

• Single instance Fork mode
• Auto-restart when memory exceeds 1GB
• Automatic log file management
• Graceful shutdown support

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

Code Standards

• ESLint + Prettier for code standards
• TypeScript strict mode
• Follow Express.js best practices

Contributing

Issues and Pull Requests are welcome!

1. Fork this repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Related Links

• MCP Protocol Specification
• OpenTiny Official Website