Synthflow MCP Tool

Synthflow AI Voice API를 위한 Model Context Protocol (MCP) 도구입니다. AI 음성 에이전트 생성, 관리 및 자동화 기능을 제공합니다.

🎯 특징

• ✅ 완전한 Synthflow API 지원: 모든 주요 API 엔드포인트 지원
• ✅ 에이전트 관리: AI 음성 에이전트 생성, 수정, 삭제
• ✅ 통화 관리: 통화 시작, 모니터링, 기록 조회
• ✅ 시뮬레이션: 에이전트 테스트 및 검증
• ✅ 분석: 사용량 및 성능 메트릭 추적
• ✅ 전화 시스템: 전화번호 관리 및 연락처 관리
• ✅ 지식 베이스: 컨텐츠 업로드 및 관리
• ✅ TypeScript: 완전한 타입 안정성
• ✅ npx 즉시 실행: 별도 설치 없이 바로 사용 가능

🚀 빠른 시작

설치

# npm으로 설치
npm install -g @estros/synthflow-mcp-tool

# 또는 npx로 직접 실행
npx @estros/synthflow-mcp-tool

환경 설정

1. 환경변수 파일 생성:

cp env.example .env

2. .env 파일에 API 키 설정:

SYNTHFLOW_API_KEY=your-api-key-here

API 키 발급 방법:

1. Synthflow 웹사이트 방문
2. INTEGRATIONS → REST API 메뉴로 이동
3. "Create New API Key" 클릭하여 API 키 발급

개발 모드

# 의존성 설치
npm install

# 개발 모드 (hot reload)
npm run dev

# 빌드
npm run build

# 프로덕션 실행
npm start

🛠️ 사용 가능한 도구

에이전트 관리 (Agents)

• create_agent - 새 AI 음성 에이전트 생성
• get_agent - 에이전트 정보 조회
• list_agents - 모든 에이전트 목록 조회
• update_agent - 에이전트 정보 수정
• delete_agent - 에이전트 삭제

통화 관리 (Calls)

• make_call - 새 통화 시작
• get_call - 통화 정보 조회
• list_calls - 통화 목록 조회 (필터링 가능)
• monitor_call - 활성 통화 모니터링

시뮬레이션 (Simulations)

• create_simulation - 에이전트 테스트 시뮬레이션 생성
• get_simulation - 시뮬레이션 결과 조회
• run_simulation - 시뮬레이션 실행

액션 관리 (Actions)

• create_action - Webhook 액션 생성
• get_action - 액션 정보 조회
• list_actions - 액션 목록 조회
• update_action - 액션 수정
• delete_action - 액션 삭제

분석 (Analytics)

• get_usage_summary - 사용량 요약 조회
• export_metrics - 메트릭 데이터 내보내기

전화 시스템 (Telephony)

• list_phone_numbers - 전화번호 목록 조회
• provision_phone_number - 새 전화번호 프로비저닝
• manage_contact - 연락처 생성/수정
• get_contact - 연락처 정보 조회
• list_contacts - 연락처 목록 조회

지식 베이스 (Knowledge)

• create_knowledge_base - 지식 베이스 생성
• get_knowledge_base - 지식 베이스 조회
• list_knowledge_bases - 지식 베이스 목록 조회
• upload_content - 컨텐츠 업로드
• delete_knowledge_base - 지식 베이스 삭제
• list_voices - 사용 가능한 음성 목록 조회

📋 AI 어시스턴트 통합

Cursor IDE

Cursor의 MCP 설정 파일 (~/.cursor/mcp.json 또는 프로젝트의 .cursor/mcp.json)에 추가:

{
  "mcpServers": {
    "synthflow": {
      "command": "npx",
      "args": ["@estros/synthflow-mcp-tool"],
      "env": {
        "SYNTHFLOW_API_KEY": "your-api-key-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Claude Desktop

Claude Desktop 설정 파일에 추가:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "synthflow": {
      "command": "npx",
      "args": ["-y", "@estros/synthflow-mcp-tool"],
      "env": {
        "SYNTHFLOW_API_KEY": "your-api-key-here"
      }
    }
  }
}

📦 프로젝트 구조

.
├── src/
│   ├── index.ts              # MCP 서버 진입점
│   ├── config/
│   │   └── env.ts           # 환경변수 검증 및 설정
│   ├── tools/               # MCP 도구 구현
│   │   ├── agents.ts        # 에이전트 관리
│   │   ├── calls.ts         # 통화 관리
│   │   ├── simulations.ts   # 시뮬레이션
│   │   ├── actions.ts       # 액션 관리
│   │   ├── analytics.ts     # 분석
│   │   ├── telephony.ts     # 전화 시스템
│   │   └── knowledge.ts     # 지식 베이스
│   ├── types/
│   │   ├── index.ts         # 공통 타입 정의
│   │   └── synthflow.ts     # Synthflow API 타입
│   └── utils/
│       └── logger.ts        # Winston 로거
├── dist/                    # 빌드 출력
├── package.json             # 프로젝트 설정
├── tsconfig.json            # TypeScript 설정
└── env.example              # 환경변수 템플릿

💡 사용 예제

에이전트 생성

// Claude 또는 Cursor에서:
// "Synthflow에서 'Customer Support'라는 이름의 새 에이전트를 생성해줘"

// 도구가 자동으로 다음을 실행:
{
  "name": "create_agent",
  "arguments": {
    "name": "Customer Support",
    "description": "고객 지원 에이전트",
    "language": "ko",
    "greeting_message": "안녕하세요! 무엇을 도와드릴까요?"
  }
}

통화 시작

// "010-1234-5678로 전화를 걸어줘. 에이전트 ID는 agent_123"

{
  "name": "make_call",
  "arguments": {
    "model_id": "agent_123",
    "phone": "+82-10-1234-5678",
    "name": "홍길동"
  }
}

사용량 조회

// "이번 달 Synthflow 사용량을 보여줘"

{
  "name": "get_usage_summary",
  "arguments": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  }
}

🔒 보안 권장사항

1. API 키 관리

   • .env 파일을 절대 Git에 커밋하지 마세요
   • API 키는 환경변수로만 관리
   • 정기적으로 API 키 갱신

2. 네트워크 보안

   • HTTPS를 통한 안전한 통신
   • 타임아웃 설정으로 무한 대기 방지

3. 로깅

   • API 키나 민감한 정보는 로그에 남기지 마세요
   • 적절한 로그 레벨 사용

🧪 테스트

# 테스트 실행
npm test

# 커버리지 포함
npm test -- --coverage

📝 퍼블리싱

# 1. 버전 업데이트
npm version patch  # 또는 minor, major

# 2. 빌드
npm run build

# 3. npm 퍼블리싱
npm publish

# 이제 npx로 실행 가능
npx @estros/synthflow-mcp-tool

🤝 기여

1. 이슈 생성
2. Feature 브랜치 생성
3. 변경사항 커밋
4. Pull Request 생성

📄 라이선스

MIT License

🆘 지원

• GitHub Issues: Issues
• npm 패키지: @estros/synthflow-mcp-tool

📚 참고 자료

• Synthflow API 문서
• Model Context Protocol
• @modelcontextprotocol/sdk

🔄 업데이트 히스토리

v1.0.0 (2024-01)

• 초기 릴리스
• 모든 Synthflow API 엔드포인트 지원
• TypeScript로 완전히 재작성
• MCP SDK 통합