기술 요약: HarnessAPI – 통합 스트리밍 API 및 MCP 도구를 위한 스킬 우선 프레임워크

1. 문제 제기

이 논문은 대규모 언어 모델 (LLM) 도구 배포 시 발생하는 치명적인 아키텍처 마찰을 식별합니다. 현재 개발자는 LLM 도구로 사용하려는 모든 Python 함수에 대해 두 가지 병렬 표현을 유지해야 합니다:

1. HTTP 엔드포인트: 인간 대상 클라이언트, 웹 대시보드, CI 파이프라인을 위해 FastAPI 와 같은 프레임워크를 사용하여 구현합니다.
2. MCP 도구: Claude Desktop, Cursor 와 같은 에이전트 런타임에서 모델 컨텍스트 프로토콜 (MCP) 을 사용하여 구현하며, FastMCP 와 같은 프레임워크를 주로 사용합니다.

이 두 인터페이스는 동일한 기본 비즈니스 로직을 공유하지만, 라우팅, 유효성 검사, 직렬화, 스트리밍, 스키마 유지 관리와 같은 주변 메커니즘에서 차이가 발생합니다. 이러한 "듀얼 스택" 접근 방식은 개발자에게 HTTP/Pydantic 용과 MCP 용이라는 두 개의 별도 스키마 정의를 유지하도록 강요합니다. 코드가 진화함에 따라 이러한 정의는 서로 멀어지게 되어 스키마가 구식화됩니다. 논문은 Patil 등 [9] 을 인용하여 타입 스키마가 없거나 구식화되면 LLM 이 API 호출을 환각 (hallucinate) 한다고 지적하며, 이러한 편차가 신뢰성 위험이 된다고 설명합니다. 또한 Mastouri 등 [10] 은 실증적으로 MCP 서버의 88.6% 가 기존 REST 서비스를 기반으로 구축되어 있음을 발견했는데, 이는 대부분의 배포가 이미 이러한 이중 유지 관리 부담을 안고 있음을 의미합니다.

기존 프레임워크는 라우트 (FastAPI) 나 도구 (FastMCP) 중 하나를 주요 개체로 간주하여 다른 하나에 대한 별도의 등록 행위를 요구합니다. 이는 개발자가 두 가지 사이를 동기화하는 레이어 역할을 하도록 강제합니다.

2. 방법론: 스킬 우선 아키텍처

HarnessAPI 는 의존성을 반전시키는 "스킬 우선" 아키텍처를 제안합니다. 개발자가 라우트를 선언한 후 도구를 (또는 그 반대로) 선언하는 대신, 스킬 폴더가 단일 진실 공급원 (single source of truth) 이 됩니다.

핵심 설계 원칙

• 단일 진실 공급원: 스킬은 타입이 지정된 handler.py 와 Pydantic models.py 를 포함하는 디렉터리로 정의됩니다.
• 파생 표현: 프레임워크는 이 단일 디렉터리 구조에서 HTTP 엔드포인트와 MCP 도구 등록을 모두 자동으로 파생합니다.
• 구조적 불변성: 두 전송 방식 모두 런타임에 동일한 Pydantic 모델로 해결되므로, 스키마 일관성은 개발자의 규율에 의해가 아니라 구조에 의해 강제됩니다.

주요 기술 메커니즘

1. 스킬 발견 및 격리:

   • 프레임워크는 스킬 디렉터리를 스캔하여 handler.py 와 models.py 를 포함하는 하위 폴더를 식별합니다.
   • 네임스페이스 충돌 (예: 여러 스킬이 Input 이라는 클래스를 정의하는 경우) 을 방지하기 위해 HarnessAPI 는 types.ModuleType 을 사용하여 각 스킬에 대해 인조 패키지 네임스페이스를 생성합니다. 이를 통해 여러 스킬이 서로의 클래스를 가리지 않고 공존할 수 있습니다.

2. 이중 모드 콘텐츠 협상:

   • 프레임워크는 단일 핸들러에서 스트리밍 및 비스트리밍 응답을 모두 지원합니다.
   • 스트리밍 (SSE): 클라이언트가 application/json 을 요청하지 않으면 프레임워크는 서버 전송 이벤트 (SSE) 스트림을 엽니다. 이는 chunk, result, done, 또는 error 이벤트를 emit 하며 조각을 점진적으로 생성합니다.
   • 배치 (JSON): 클라이언트가 Accept: application/json 을 보내면 프레임워크는 핸들러의 출력을 버퍼링하여 단일 JSON 응답으로 반환합니다.
   • 이를 통해 동일한 핸들러가 코드 변경 없이 대화형 에이전트 세션 (스트리밍) 과 배치 파이프라인 (JSON) 을 모두 처리할 수 있습니다.

3. 동적 MCP 래퍼 생성:

   • 해결된 중요한 기술적 과제는 FastMCP 의 스키마 introspection 입니다. 이는 함수의 __annotations__ 를 읽고 __globals__ 에 대해 타입을 해결하는 데 의존합니다. Pydantic 모델이 함수의 전역 범위에 없기 때문에 단순한 클로저는 실패합니다.
   • 해결책: HarnessAPI 는 Pydantic 모델을 명시적으로 포함하는 네임스페이스 내에서 exec 를 사용하여 래퍼 함수를 동적으로 컴파일합니다. 이는 FastMCP 의 검사 계층에서 타입이 해결 가능하도록 보장하여 수동 스키마 중복 없이 올바른 도구 등록을 가능하게 합니다.

4. 라이프사이클 관리:

   • HarnessAPI 는 FastAPI 를 서브클래스링하고 FastMCP 애플리케이션을 ASGI 서브애플리케이션으로 마운트합니다.
   • 사용자 애플리케이션 (예: 데이터베이스 연결) 과 FastMCP 서버의 시작/종료 후크를 구성하는 병합 수명 (merged lifespan) 컨텍스트 관리자를 구현하여 단일 프로세스 배포를 가능하게 합니다.

5. 핫스왑 기능 (개발 전용):

   • 선택적 엔드포인트를 통해 코드 문자열을 제출하여 핸들러 로직을 동적으로 교체할 수 있습니다. 이는 프로덕션 환경에서 원격 코드 실행을 방지하기 위해 루프백 주소 (localhost) 에만 엄격하게 제한됩니다.

3. 주요 기여

이 논문은 다음과 같은 기여를 정의합니다:

1. 스킬 우선 아키텍처 패턴: 스킬 디렉터리가 권위 있는 정의가 되는 공식 패턴으로, 라우트 우선 (FastAPI) 및 도구 우선 (FastMCP) 패턴과 대비됩니다.
2. 구현 메커니즘:
   • 동적 라우트 생성 및 이중 모드 콘텐츠 협상.
   • Pydantic 주석을 FastMCP 의 검사 계층으로 전파하는 코드 생성 기술.
   • 단일 프로세스 작동을 위한 수명 병합 전략.
3. 보일러플레이트 감소: 프레임워크 관련 코드가 크게 감소했음을 보여주는 실증적 평가.
4. 오픈소스 출시: PyPI 및 GitHub 에서 사용할 수 있는 HarnessAPI v0.1.4 출시.

4. 평가 결과

저자들은 Echo, Greet, Summarize, VectorNorm, Classify, Translate 등 여섯 가지 대표적인 스킬을 사용하여 HarnessAPI 를 수동으로 유지 관리된 듀얼 스택 구현 (별도의 FastAPI 및 FastMCP 서버) 과 비교 평가했습니다.

• 보일러플레이트 감소: cloc 을 사용하여 비즈니스 로직을 제외한 프레임워크 관련 코드 (비어 있지 않고 주석이 아닌 줄) 를 계산한 결과, HarnessAPI 는 여섯 가지 스킬 전체에 걸쳐 총 44 줄이 필요한 반면, 수동 구현은 170 줄이 필요했습니다. 이는 보일러플레이트가 74% 감소한 것입니다.
• 확장성 행동: 수동 접근 방식은 $O(n)$ 확장성을 보이며, 프레임워크 코드가 스킬 수에 비례하여 선형적으로 증가합니다 (각 스킬마다 새로운 데코레이터와 등록이 필요함). HarnessAPI 는 스킬 수와 관계없이 진입점이 고정되어 있으므로 프레임워크 코드에 대해 $O(1)$ 확장성을 보입니다.
• 기능 동등성: HarnessAPI 는 추가 라이브러리 통합 없이 SSE 스트리밍, OpenAPI/Swagger UI, 스킬별 타임아웃을 포함한 독립형 FastAPI 및 FastMCP 의 모든 기능을 기본적으로 제공합니다.
• 호환성: 프레임워크는 agentskills.io 저장소의 기존 스킬 12 개를 소스 코드 수정 없이 성공적으로 가져와 등록하여 기존 스킬 세트에 대한 마찰 없는 배포를 입증했습니다.

5. 중요성 및 주장

이 논문은 HarnessAPI 가 LLM 도구 배포에서 "불편한 답변"인 이중 유지 관리를 해결한다고 주장합니다. 그 중요성은 스키마 일관성을 개발자의 규율 (오류와 편차에 취약함) 에서 프레임워크가 강제하는 구조적 불변성으로 전환하는 데 있습니다.

저자들은 보일러플레이트가 74% 감소한 것은 이러한 불변성의 결과이지만, 더 오래 지속되는 결과는 확장성 속성이라고 강조합니다. 에이전트 생태계가 성숙해지고 개발자가 수십 개 또는 수백 개의 스킬을 배포함에 따라 수동 듀얼 스택 등록의 누적 유지 관리 부담은 견딜 수 없게 됩니다. HarnessAPI 는 두 가지 등록을 유지하기 위한 더 나은 도구가 아니라, 두 번째 등록 자체를 제거하는 것이 해결책임을 시사합니다.

논문의 범위에 대해서는 다음과 같이 겸손하게 서술합니다:

• 이는 종단 간 지연 시간이나 동시성 벤치마크를 해결한다고 주장하지 않으며, 기본이 되는 FastAPI/Uvicorn 스택의 알려진 성능 특성에 맡깁니다.
• MCP 래퍼 생성에 exec 를 사용하는 것 (FastMCP 의 현재 리졸버를 위한 임시 해결책) 과 MCP 계층의 도구별 인증 부재와 같은 한계를 인정합니다.
• 핫스왑 엔드포인트를 네트워크 접근 가능한 배포에서 사용하지 않도록 명시적으로 경고하며, 이를 로컬 개발 루프로만 제한합니다.

결론적으로 HarnessAPI 는 스키마 일관성을 보장하고 유지 관리 오버헤드를 줄이며 현대 LLM 에이전트를 위한 스트리밍 및 배치 상호작용을 모두 지원하는 통합된 스킬 우선 배포 계층을 제공합니다.