WebForm

주요 기능

아키텍처

┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Designer │ │ Runtime │ │ MCP Server │
│ (React) │ │ (React) │ │ (stdio/HTTP)│
│ :3000 │ │ :3001 │ │ :4100 │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
 │ /api proxy │ /api proxy │
 └────────┬───────────┴────────────────────┘
 ▼
 ┌───────────────┐
 │ Server │
 │ (Express) │
 │ :4000 │
 ├───────────────┤
 │ EventEngine │──▶ isolated-vm 샌드박스
 │ WebSocket │──▶ 실시간 동기화
 └───────┬───────┘
 │
 ┌───────┴───────┐
 │ │
 ┌────▼────┐ ┌─────▼────┐
 │ MongoDB │ │ Redis │
 └─────────┘ └──────────┘

사전 요구사항

설치 및 실행

빠른 시작

git clone <repository-url>
cd webform
./run.sh

초기 데이터 설정

# 프리셋 테마 시딩 (24개 테마 → MongoDB)
./generate-themes.sh
# 데모 프로젝트 + 샘플 데이터 생성 (선택)
./generate-sample.sh

수동 설치

# 1. 의존성 설치
pnpm install
# 2. Redis 실행
docker run -d --name webform-redis -p 6379:6379 redis:7-alpine
# 3. 서버 환경 변수 설정
cp packages/server/.env.example packages/server/.env
# .env 파일에서 JWT_SECRET(32자 이상)과 ENCRYPTION_KEY(64자 hex)를 변경
# 4. 실행
pnpm dev
# 5. 별도 터미널에서 초기 데이터 설정
./generate-themes.sh # 프리셋 테마 시딩
./generate-sample.sh # 데모 데이터 (선택)

개별 서비스 실행

pnpm dev:server # Server — http://localhost:4000
pnpm dev:designer # Designer — http://localhost:3000
pnpm dev:runtime # Runtime — http://localhost:3001

Docker로 실행

# 이미지 빌드 + 실행
./build.sh up
# 이미지 빌드만
./build.sh
# 종료
./build.sh down
# 재시작 (rebuild + up)
./build.sh restart
# 로그 확인
./build.sh logs

┌─────────────────────────────────────────────┐
│ designer (nginx :80 → host :3000) │
│ └── Designer SPA + API/WS 프록시 → webform │
├─────────────────────────────────────────────┤
│ webform (Express :4000 → host :3001,:4000) │
│ ├── /api/* → API 라우트 │
│ ├── /auth/* → 인증 라우트 │
│ ├── /ws/* → WebSocket │
│ └── /* → Runtime SPA │
├─────────────────────────────────────────────┤
│ mcp (Node :4100 → host :4100) │
│ └── /mcp → MCP Streamable HTTP │
├──────────────┬──────────────────────────────┤
│ MongoDB :27017 (내부) │ Redis :6379 (내부) │
└──────────────┴──────────────────────────────┘

./generate-themes.sh # 프리셋 테마 시딩
./generate-sample.sh # 데모 데이터 (선택)

테스트

pnpm test # 전체 테스트
pnpm test:watch # Watch 모드

환경 변수

데이터소스

지원 데이터소스

Designer 데이터소스 패널

쿼리 API

구조화 쿼리 (SQL DB)

ctx.http.post(BASE + DS_URL + '/query', {
 table: 'employees',
 filter: { department: 'Engineering' },
 columns: ['id', 'name', 'email'],
 limit: 100,
 offset: 0
});

Raw SQL 쿼리

ctx.http.post(BASE + DS_URL + '/query', {
 sql: "SELECT e.name, d.dept_name FROM employees e JOIN departments d ON e.dept_id = d.id WHERE d.dept_name = 'Sales' ORDER BY e.name LIMIT 50"
});

MongoDB 구조화 쿼리

ctx.http.post(BASE + DS_URL + '/query', {
 collection: 'employees',
 filter: { age: { $gt: 30 } },
 projection: { name: 1, email: 1 },
 limit: 100,
 skip: 0
});

이벤트 핸들러 예제

const BASE = 'http://localhost:4000';
const DS = '/api/datasources/<datasource-id>';
// 부서 필터 + 이름 검색
const dept = ctx.controls.cmbDepartment.selectedValue;
const name = ctx.controls.txtSearchName.text || '';
// 방법 1: Raw SQL (JOIN, LIKE 등 자유롭게 사용)
const res = ctx.http.post(BASE + DS + '/query', {
 sql: `SELECT * FROM employees WHERE department = '${dept}' AND name LIKE '%${name}%' ORDER BY id LIMIT 100`
});
// 방법 2: 구조화 쿼리 (간단한 조건)
const res2 = ctx.http.post(BASE + DS + '/query', {
 table: 'employees',
 filter: { department: dept },
 limit: 100
});
if (res.ok) {
 ctx.controls.gridEmployees.dataSource = res.data.data;
}

REST API 엔드포인트

샌드박스 보안

SwaggerConnector

주요 기능

디자이너 설정

이벤트 핸들러에서 사용

// operationId 기반 API 호출
const result = await ctx.controls.petApi.listPets({
 query: { limit: 10 }
});
// Path 파라미터 + Request Body
const updated = await ctx.controls.petApi.updatePet({
 path: { petId: 123 },
 body: { name: 'Buddy Jr' }
});
// multipart 파일 업로드
const upload = await ctx.controls.fileApi.uploadFile({
 body: {
 file: { dataUrl: 'data:image/png;base64,...', filename: 'photo.png' },
 description: 'My photo'
 }
});
// 응답: { status: number, ok: boolean, data: unknown }
if (result.ok) {
 ctx.controls.grid.dataSource = result.data;
}

Google OAuth2 인증

인증 흐름

사용자가 Runtime 접속
 → Shell의 auth 설정 확인
 → 인증 필요 시 LoginRequiredPage 표시
 → "Google로 로그인" 클릭
 → Google OAuth2 인증
 → 서버에서 ID Token 검증 + 도메인 화이트리스트 확인
 → Runtime JWT 발급 (24시간)
 → URL fragment로 토큰 전달 → localStorage 저장

설정 방법

MCP 서버 (AI 통합)

47개 MCP 도구

로컬 실행 (stdio)

# 개발 모드
pnpm --filter @webform/mcp dev
# MCP Inspector로 디버깅
npx @modelcontextprotocol/inspector npx tsx packages/mcp/src/index.ts

{
 "mcpServers": {
 "webform": {
 "command": "npx",
 "args": ["tsx", "packages/mcp/src/index.ts"],
 "cwd": "/path/to/webform",
 "env": { "WEBFORM_API_URL": "http://localhost:4000" }
 }
 }
}

원격 실행 (Streamable HTTP)

# packages/mcp/.env
MCP_API_KEYS=your-secret-key-1,your-secret-key-2 # 허용 API 키 (콤마 구분, 필수)
MCP_PORT=4100 # HTTP 리슨 포트 (기본값: 4100)
MCP_HOST=0.0.0.0 # 바인드 주소 (기본값: 0.0.0.0)
WEBFORM_API_URL=http://localhost:4000 # 백엔드 API URL (기본값: http://localhost:4000)

# 랜덤 API 키 생성
openssl rand -hex 32

pnpm --filter @webform/mcp start:remote

{
 "mcpServers": {
 "webform": {
 "type": "streamable-http",
 "url": "http://your-server:4100/mcp",
 "headers": {
 "Authorization": "Bearer your-secret-key-1"
 }
 }
 }
}

Claude Code 계정 레벨 MCP 설정

pnpm --filter @webform/mcp start:remote

cat packages/mcp/.env | grep MCP_API_KEYS

claude mcp add --transport http -s user webform \
 "http://localhost:4100/mcp" \
 --header "Authorization: Bearer <YOUR_API_KEY>"

claude mcp list

claude mcp remove -s user webform

기술 스택