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

오늘날 LLM 도구로 배포되는 모든 Python 함수는 두 가지 형태로 존재해야 합니다. 하나는 인간 대상 클라이언트 및 CI 파이프라인을 위한 HTTP 엔드포인트(endpoint)이고, 다른 하나는 Claude 및 Cursor와 같은 에이전트 런타임(runtime)을 위한 MCP 도구 등록입니다. 이러한 표현 방식들은 비즈니스 로직(business logic)을 공유하지만, 주변의 모든 메커니즘(라우팅(routing), 검증(validation), 직렬화(serialisation), 스트리밍(streaming), 스키마 유지보수(schema maintenance))에서는 서로 갈라지며, 기반 코드가 진화함에 따라 서로 괴리됩니다. 우리는 타입이 지정된 스킬(skill) 폴더를 단일 진실 공급원(single source of truth)으로 취급하여 이러한 중복을 제거하는 Python 프레임워크인 HarnessAPI를 제시합니다. 하나의 handler.py와 Pydantic 스키마(schemas)로부터, 이 프레임워크는 서버 전송 이벤트(Server-Sent Events, SSE)를 사용하는 스트리밍 HTTP 엔드포인트, 대화형 OpenAPI/Swagger UI, 그리고 설정이 필요 없는(zero-configuration) MCP 도구를 단일 프로세스에서 자동으로 도출합니다. 이중 모드 콘텐츠 협상(Dual-mode content negotiation)을 통해 동일한 핸들러가 핸들러 변경 없이 SSE 스트리밍 클라이언트와 JSON 반환 클라이언트를 모두 서비스할 수 있습니다. 동적 코드 생성 메커니즘은 Pydantic 타입 어노테이션(type annotations)이 FastMCP의 검사 계층(inspection layer)으로 올바르게 전파되도록 보장하여, 단순한 클로저(closure) 기반 등록을 방해하는 기술적 한계를 해결합니다. cloc을 사용하여 6개의 대표적인 스킬에 대해 측정한 결과, HarnessAPI는 수동으로 유지 관리되는 이중 스택 구현(FastAPI 서버 + FastMCP 서버)과 비교하여 프레임워크 관련 보일러플레이트(boilerplate)를 74% 감소시켰습니다. HarnessAPI는 FastAPI를 상속(subclasses)하여 FastAPI의 전체 미들웨어(middleware), 의존성 주입(dependency-injection) 및 배포 생태계를 그대로 계승합니다. HarnessAPI는 https://github.com/edwinjosechittilappilly/harnessapi 에서 확인할 수 있으며, PyPI(pip install harnessapi)에서도 사용할 수 있습니다.