Golf: MCP 서버 애플리케이션 개발 프레임워크

Golf는 MCP(Message Control Protocol) 서버 애플리케이션 생성을 간소화하도록 설계된 프레임워크입니다. 이 프레임워크를 사용하면 개발자가 도구(tools), 프롬프트(prompts), 그리고 *리소스(resources)*와 같은 서버의 기능을 일반적인 디렉토리 구조 내의 간단한 Python 파일로 정의할 수 있습니다. Golf는 이러한 구성 요소를 자동으로 발견하고, 구문 분석하며, 실행 가능한 MCP 서버로 컴파일하여 보일러플레이트 코드를 최소화하고 개발 속도를 높입니다.

Golf는 FastMCP 4.0.0 및 현재의 MCP 2026-07-28 프로토콜을 목표로 합니다. FastMCP는 또한 호환성 모드를 통해 레거시 MCP 클라이언트와 통신합니다.

Golf v0.2.0을 사용하면 엔터프라이즈급 인증(JWT, OAuth Server, 개발 토큰), LLM 상호 작용을 위한 내장 유틸리티, 그리고 자동 원격 측정(telemetry) 통합 기능을 얻을 수 있습니다. Golf가 인증, 모니터링, 서버 인프라를 처리하는 동안 에이전트의 로직 구현에만 집중할 수 있습니다.

몇 가지 간단한 단계를 거쳐 Golf 프로젝트를 실행해 보세요:

Golf는 Python 3.10 이상을 요구합니다. 그런 다음 pip를 사용하여 Golf를 설치하세요:

pip install golf-mcp

Golf CLI를 사용하여 새 프로젝트의 구조를 잡으세요(scaffold):

golf init your-project-name

이 명령어는 기본 프로젝트 구조를 포함하는 새 디렉토리(your-project-name)를 생성하며, 여기에는 예제 도구, 리소스 및 golf.json 구성 파일이 포함됩니다.

새 프로젝트 디렉토리로 이동하여 개발 서버를 시작하세요:

cd your-project-name
golf build dev
golf run

이렇게 하면 일반적으로 http://localhost:3000에서 MCP 서버가 시작됩니다(이는 golf.json에서 구성 가능합니다).

이것으로 끝입니다! Golf 서버가 실행되어 통합할 준비가 되었습니다.

golf init으로 초기화된 Golf 프로젝트는 다음과 유사한 구조를 가집니다:

<your-project-name>/ 
│
├─ golf.json # 메인 프로젝트 구성 파일
... 

: 서버 이름, 포트, 전송 방식(transport), 원격 측정 및 기타 빌드 설정을 구성합니다.
golf.json: JWT, OAuth Server, API 키 또는 개발 인증을 위한 전용 인증 구성 파일입니다 (v0.2.0에서 추가되었으며 v0.1.x 인증 API와는 호환성 변경 사항이 있습니다).
auth.py,
tools/

,resources/

: Python 파일을 포함하며, 각 파일은 단일 컴포넌트를 정의합니다. 이 디렉토리에는 컴포넌트를 추가로 구성할 수 있는 중첩된 하위 디렉토리를 포함할 수도 있습니다 (예: prompts/

tools/payments/charge.py
)
각 파일의 모듈 독스트링(module docstring)이 해당 컴포넌트의 설명 역할을 합니다.

• 컴포넌트 ID는 파일 경로에서 자동으로 파생됩니다. 예를 들어,
  tools/hello.py
  은 hello가 되고, tools/payments/submit.py와 같은 중첩된 파일은 submit_payments가 됩니다 (파일명 뒤에 메인 카테고리 아래의 역순 부모 디렉토리를 언더스코어(_)로 결합).

• 컴포넌트 ID는 파일 경로에서 자동으로 파생됩니다. 예를 들어,

새로운 툴(tool)을 만드는 것은 tools/ 디렉토리에 Python 파일을 추가하는 것만큼 간단합니다. 보일러플레이트의 예시인 tools/hello.py는 다음과 같습니다:

# tools/hello.py
"""Hello World tool {{project_name}}."""
from typing import Annotated
...

Golf는 이 파일을 자동으로 발견합니다. 모듈 독스트링인 """Hello World tool {{project_name}}."""이 툴의 설명으로 사용됩니다. 이는 hello 함수의 시그니처에서 매개변수를 추론하고, 출력 스키마를 위해 Output Pydantic 모델을 사용합니다. 이 툴은 ID hello로 등록됩니다.

Golf는 엔터프라이즈급 인증(authentication), 내장 유틸리티, 자동 원격 측정(telemetry) 기능을 포함합니다:

# auth.py - 인증 구성
from golf.auth import configure_auth, JWTAuthConfig, StaticTokenConfig, OAuthServerConfig
# JWT 인증 (운영 환경)
...

MCP 2026-07-28에 이르러, 유도(elicitation) 및 샘플링은 호출자 소유의 다중 왕복 제어 흐름을 사용합니다. 중첩된 헬퍼는 포함하는 툴을 투명하게 계속할 수 없습니다: 툴의 반환 타입에 InputRequiredResult를 선언하고 그러한 결과를 변경 없이 반환해야 합니다. 그러면 해당 툴은 답변과 함께 재진입됩니다. 레거시 연결은 여전히 명령형 요청(imperative requests)을 사용합니다.

from mcp_types import InputRequiredResult
from golf.utilities import sample
async def explain(topic: str) -> str | InputRequiredResult:
...

JWT 인증은 오디언스(audience)를 필요로 하므로 토큰이 이 MCP 리소스에 바인딩됩니다. 인바운드 MCP JWT/OAuth 베어러 토큰을 업스트림 API로 절대 전달해서는 안 됩니다. 대신 별도의 업스트림 자격 증명(credential)이나 표준 기반의 토큰 교환/위임 흐름(token exchange/delegation flow)을 사용해야 합니다.

# OpenTelemetry 추적 활성화
export OTEL_TRACES_EXPORTER="otlp_http"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318/v1/traces"
...

golf.json의 기본 구성

:

{
"name": "My Golf Server",
"host": "localhost",
...
}

: transport 사용: "streamable-http" 또는 "stdio"를 사용하세요. SSE는 더 이상 지원되지 않는 레거시 전송 방식(deprecated legacy transport)으로만 사용할 수 있습니다.: 선택적 레거시 Streamable HTTP 동작. MCP 2026-07-28은 본질적으로 세션이 없으며 이 설정에 의존하지 않습니다.stateless_http

: OpenTelemetry 추적 활성화: opentelemetry_enabled

: 입력/출력 캡처 (민감한 데이터 처리 시 주의): detailed_tracing

Golf는 프레임워크가 어떻게 사용되고 있는지 이해하고 시간이 지남에 따라 개선하는 데 도움을 주기 위해 CLI에서 익명 사용 데이터를 수집합니다. 수집되는 데이터에는 다음이 포함됩니다:

• 실행된 명령어 (init, build, run)
• 성공/실패 상태 (오류 상세 내용은 제외)
• Golf 버전, Python 버전 (주요.부 버전만), 및 OS 유형
• 템플릿 이름 (init 명령어에 한함)
• 빌드 환경 (build 명령어에 한함: dev/prod)

개인 정보, 프로젝트 이름, 코드 내용, 또는 오류 메시지는 절대 수집되지 않습니다.

다음과 같은 여러 방법으로 원격 측정(telemetry)을 비활성화할 수 있습니다:

• 원격 측정 명령 사용(권장): golf telemetry disable

이 명령어는 사용자 기본 설정을 영구적으로 저장합니다. 다시 활성화하려면:

golf telemetry enable

• 모든 명령어 실행 중: --no-telemetry를 추가하여 사용자 기본 설정을 저장할 수 있습니다: golf init my-project --no-telemetry

원격 측정 기본 설정은 ~/.golf/telemetry.json에 저장되며 모든 Golf 명령어에서 지속됩니다.