[논문] HarnessAPI: 스킬 우선 통합 스트리밍 API 및 MCP 도구 프레임워크

Source: arXiv - 2605.22733v1

개요

이 논문은 HarnessAPI 라는 파이썬 프레임워크를 소개한다. 개발자는 하나의 “스킬”(타입 힌트가 달린 함수와 Pydantic 스키마)만 정의하면 자동으로 스트리밍 HTTP 엔드포인트와 설정이 필요 없는 MCP(Model‑Centered Programming) 도구 등록을 생성할 수 있다. 스킬 폴더를 단일 진실 원천으로 취급함으로써, HarnessAPI는 현재 팀이 인간용 API와 LLM‑에이전트 런타임을 위해 별도의 코드 경로를 유지해야 하는 번거로운 중복을 없앤다.

핵심 기여

• 통합된 스킬‑우선 추상화 – 하나의 handler.py와 Pydantic 모델만으로 SSE를 지원하는 FastAPI 엔드포인트와 FastMCP 도구 등록을 동시에 생성한다.
• 이중 모드 콘텐츠 협상 – 동일한 핸들러가 에이전트에게는 스트리밍 Server‑Sent Events(SSE)를, 일반 클라이언트에게는 일반 JSON 응답을 코드 수정 없이 투명하게 제공한다.
• 동적 코드‑생성 브리지 – Pydantic 타입 정보를 FastMCP의 검사 레이어에 자동으로 주입해, 오래된 클로저 기반 등록 제한을 해결한다.
• 보일러플레이트 감소 – 실제 현업 스킬 6개에 대한 실험에서 기존 수동 FastAPI + FastMCP 스택 대비 **74 %**의 프레임워크 수준 코드 감소를 보였다.
• 완전한 FastAPI 호환성 – HarnessAPI는 FastAPI를 서브클래싱하여 미들웨어, 의존성 주입, 배포 생태계(Docker, Uvicorn 등)를 그대로 유지한다.

방법론

1. 스킬 폴더 구조 – 개발자는 타입이 지정된 함수와 해당 Pydantic 스키마 파일을 포함한 handler.py를 전용 폴더에 배치한다.
2. 프레임워크 부트스트래핑 – HarnessAPI는 폴더를 스캔하고 타입 힌트를 읽어 다음을 생성한다.
   • 클라이언트가 text/event-stream을 요청하면 Server‑Sent Events 로 결과를 스트리밍하는 FastAPI 라우트.
   • 동일한 스키마에서 자동으로 채워지는 OpenAPI/Swagger UI.
   • Claude/Cursor 에이전트가 호출할 수 있는 FastMCP 도구 등록 객체.
3. 동적 코드 생성 – import 시점에 HarnessAPI는 핸들러 시그니처를 반영한 작은 파이썬 모듈을 출력해 FastMCP 검사 시스템에 정확한 타입 메타데이터를 제공한다.
4. 평가 – 저자들은 코드 생성, 데이터 추출, 요약 등 6개의 대표적인 “스킬”을 선정하고, 수동 듀얼‑스택, HarnessAPI, 그리고 FastAPI‑전용 구현 세 가지 설정에 대해 cloc으로 라인 수를 측정했다.

결과 및 발견

• 정확성 – 모든 자동 생성 엔드포인트는 수작업 버전과 동일한 통합 테스트를 통과했으며, 동적 코드 생성이 런타임 의미론을 변경하지 않음을 확인했다.
• 성능 – 스트리밍 지연시간이 네이티브 FastAPI SSE 구현 대비 5 ms 이내로 유지돼 추상화 레이어가 거의 오버헤드를 추가하지 않음을 보여준다.
• 개발자 경험 – 짧은 개발자 설문조사(n = 12)에서 유지보수 용이성에 대한 인식이 5점 리커트 척도 기준 3.5점 상승했다.

실용적 함의

• LLM‑보강 서비스의 시장 출시 속도 가속 – 팀은 새로운 스킬을 한 번 정의하면 웹 클라이언트와 LLM 에이전트 모두에 즉시 노출할 수 있어 릴리즈 주기가 단축된다.
• 운영 부채 감소 – 단일 코드베이스를 유지함으로써 API 계약과 에이전트 도구 정의 간의 불일치를 방지하고, 스키마 불일치로 인한 버그를 줄인다.
• 기존 DevOps 파이프라인과의 원활한 통합 – HarnessAPI가 FastAPI 서브클래스이므로 Docker, Kubernetes, CI/CD 등 익숙한 도구를 그대로 사용하면서 MCP 지원을 “무료”로 얻을 수 있다.
• 소규모 팀·스타트업 진입 장벽 낮춤 – 설정이 필요 없는 MCP 등록 덕분에 별도의 “에이전트‑런타임” 엔지니어가 보일러플레이트 코드를 작성할 필요가 없다.
• 미래 대비 – 새로운 LLM 플랫폼이 MCP 모델을 채택하면 기존 스킬이 별도 리팩터링 없이 자동으로 호환된다.

제한점 및 향후 연구

• 파이썬 전용 – 현재 구현은 파이썬에만 초점을 맞추고 있다. TypeScript나 Rust 등 다른 언어로 스킬‑우선 개념을 확장하면 채택 범위가 넓어질 것이다.
• 정적 분석 제약 – 조건부 Pydantic 모델처럼 런타임에 동적으로 생성되는 복잡한 스키마는 동적 코드 생성 단계에서 완전히 포착되지 않을 수 있다.
• 확장성 테스트 부족 – 논문에서는 단일 노드 환경에서 지연 시간을 평가했으며, 수천 개 동시 SSE 스트림과 같은 대규모 고처리량 시나리오는 아직 벤치마크되지 않았다.
• 에이전트‑런타임 기능 격차 – HarnessAPI가 기본 도구 등록을 지원하지만, 도구 버전 관리나 세밀한 권한 스코프와 같은 고급 MCP 기능은 아직 구현되지 않았다.

HarnessAPI는 HTTP API와 LLM‑에이전트 도구를 통합하고 싶지만 FastAPI의 풍부한 생태계를 포기하고 싶지 않은 개발자를 위한 실용적인 접근법이다. 보일러플레이트를 줄이고 런타임 간 스키마를 일치시킴으로써, 엔지니어가 AI‑보강 애플리케이션의 핵심 비즈니스 로직에 집중할 수 있게 만든다.

저자

• Edwin Jose

논문 정보

• arXiv ID: 2605.22733v1
• 분류: cs.AI, cs.SE
• 발표일: 2026년 5월 21일
• PDF: Download PDF