Hyperterse

Hyperterse란?

Hyperterse는 선언적 구성으로 MCP (Model Context Protocol) 툴 서버를 구축하는 오픈소스 프레임워크입니다. 수많은 개별 MCP 툴 엔드포인트를 노출하는 대신, 툴 정의를 표준 준수 MCP 서버로 컴파일하여 에이전트가 일관된 인터페이스를 통해 사용하도록 합니다.

프레임워크의 핵심 목적은 “툴을 한 번 정의” (데이터베이스 연결 및 인증 규칙 포함)하면 Hyperterse가 런타임 문제를 처리—auth 적용, 결과 캐싱, 관측성 등—하도록 하여 각 툴 엔드포인트별 글루 코드를 작성·유지할 필요가 없습니다.

주요 기능

• 디렉토리 및 선언 파일 기반 선언적 툴 정의: app/tools/ 아래 각 디렉토리가 자동으로 툴이 되므로 각 툴 등록 코드를 작성할 필요가 없습니다.
• 두 개 툴 MCP 인터페이스 (search + execute): 에이전트가 정확히 두 MCP 툴—search와 execute—만 노출된 서버와 상호작용하며, Hyperterse가 적합한 기본 툴 구현을 동적으로 탐지·라우팅합니다.
• 내장 api_key 플러그인 인증: 내장 api_key 플러그인 (또는 자체 구현)으로 툴에 인증을 연결하면 각 execute 호출 전에 자동으로 auth가 적용됩니다.
• 전역 또는 툴별 TTL 캐싱: 결과 캐싱을 활성화하여 동일 execute 호출이 데이터베이스를 재조회하지 않고 캐시 결과를 반환할 수 있습니다; 캐싱 규칙은 전역 또는 툴별로 설정 가능합니다.
• 관리형 풀링 및 라이프사이클 지원 다중 데이터베이스: 어댑터로 PostgreSQL, MySQL, MongoDB, Redis 연결; Hyperterse가 연결 풀링, 헬스체크, graceful shutdown을 관리합니다.
• OpenTelemetry 관측성: Hyperterse에 OpenTelemetry 추적, 메트릭, 구조화 로깅이 포함되어 search와 execute 호출을 엔드투엔드 디버깅할 수 있습니다.
• 핸들러 및 변환용 TypeScript 스크립트: 선언 파일만으로 부족할 때 fetch와 console이 지원되는 샌드박스 런타임에서 실행되는 스크립트로 핸들러/변환 추가.
• 단일 아티팩트로 컴파일 및 배포: Hyperterse가 선언 파일과 스크립트를 하나의 아티팩트로 컴파일하여 Docker, Kubernetes, 베어메탈 또는 클라우드 환경에서 제공 가능.

Hyperterse 사용법

1. Hyperterse 설치 제공 명령어 (cURL, NPM, Bun, Homebrew 중 하나) 사용.
2. 툴 및 어댑터 정의 생성:
   • 데이터베이스 어댑터는 app/adapters/ 아래 배치.
   • 툴 선언은 app/tools/ 아래 배치; 각 툴은 디렉토리 이름으로 표현되며 SQL 문장, 타입화 입력, 선택적 auth·캐싱 규칙을 포함한 선언 파일 포함.
3. (선택) 선언 파일 초과 로직 필요 시 TypeScript 핸들러/변환 추가.
4. 서버 아티팩트 빌드/컴파일하여 툴, 스크립트, 구성을 번들링.
5. 대상 환경에서 컴파일된 MCP 서버 제공; 에이전트가 search로 툴 검색 후 구조화 입력으로 선택 툴을 execute 실행.

사용 사례

• 데이터베이스 기반 연구 또는 분석 툴: app/tools/에 다수 SQL 기반 툴 정의 후 에이전트가 search로 적합 쿼리 툴 검색하고 타입화 입력으로 execute 실행.
• 멀티테넌트 또는 접근 제어 툴 실행: 특정 툴에 API 키 인증 규칙 연결하여 각 execute 호출 전에 auth 자동 실행.
• 비용 또는 지연 민감 쿼리 워크플로: TTL로 전역 또는 툴별 캐싱 활성화하여 반복 execute 호출이 데이터베이스 재쿼리 대신 캐시 결과 반환.
• MCP 서버 동작 표준화 팀: Hyperterse 내장 auth, 캐싱, OpenTelemetry 추적으로 툴 엔드포인트별 별도 보일러플레이트 없이 일관성 유지.
• 인프라 유형 간 프로덕션 배포: 단일 아티팩트로 컴파일하여 Docker, Kubernetes, 베어메탈 또는 클라우드 환경에 툴 정의 방식 변경 없이 배포.

자주 묻는 질문

• Hyperterse는 무엇을 위해 만들어졌나요? Hyperterse는 선언 파일로 MCP 툴 서버를 구축하며, auth·캐싱·관측 기능을 내장해 컴파일 및 제공합니다.

• Hyperterse는 무료로 사용할 수 있나요? 네. Apache 2.0 라이선스 하에 무료 오픈소스이며, 자체 호스팅이 가능합니다.

• 선언 파일은 어떻게 툴에 매핑되나요? 툴은 app/tools/ 아래에 정의되며, 각 툴 디렉터리가 툴 이름에 대응하고 디렉터리의 선언 파일이 SQL 문장, 타입화된 입력, 선택적 auth/캐싱 규칙을 지정합니다.

• 어떤 데이터베이스가 지원되나요? Hyperterse는 전용 어댑터로 PostgreSQL, MySQL, MongoDB, Redis를 기본 지원합니다.

• Hyperterse가 에이전트에 노출하는 MCP 인터페이스는 무엇인가요? Hyperterse는 툴 정의 개수와 관계없이 정확히 두 개의 MCP 툴—search와 execute—만 노출합니다.

대안

• 명시적 엔드포인트로 커스텀 MCP 툴 서버: 각 기능당 하나의 툴 엔드포인트를 노출하는 MCP 서버를 구축합니다. 세밀한 제어가 가능하지만, 등록·유효성 검사·auth·캐싱·관측 코드를 더 작성·유지보수해야 합니다.
• 컴파일 대신 라우팅/발견에 초점 맞춘 프레임워크: 에이전트나 라우터가 요청을 백엔드 함수/툴에 매핑하는 방식을 사용합니다. Hyperterse에 비해 유효성 검사·auth·캐싱·추적을 일관되게 구현해야 할 수 있습니다.
• 애플리케이션 관리 미들웨어를 사용하는 데이터베이스 전용 툴 라이브러리: 타입화된 데이터베이스 액세스 라이브러리를 사용하고 auth·캐싱·추적 미들웨어를 앱 레이어에서 구현합니다. MCP 프레임워크의 책임을 앱으로 옮겨 툴당 통합 노력이 증가할 수 있습니다.
• 툴 실행을 위한 범용 워크플로우 엔진: 구성 기반으로 태스크를 실행하는 오케스트레이터입니다. 이러한 대안은 툴 체이닝을 지원할 수 있지만, Hyperterse는 MCP 서버 동작과 표준 준수 인터페이스로의 선언적 툴 컴파일에 특화되어 있습니다.