Golf

概要

Golf は、MCP サーバーアプリケーションの作成を効率化するために設計されたフレームワークです。開発者は、一般的なディレクトリ構造の中にあるシンプルな Python ファイルで、サーバーの機能であるツール、プロンプト、リソースを定義できます。Golf はこれらのコンポーネントを自動的に検出、解析、コンパイルして実行可能な MCP サーバーにするため、定型コードを最小限に抑え、開発を加速できます。

Golf は FastMCP 4.0.0 と、現行の MCP 2026-07-28 プロトコルを対象としています。 FastMCP は互換モードを通じて、従来の MCP クライアントとのネゴシエーションにも対応しています。

Golf v0.2.0 では、エンタープライズレベルの認証（JWT、OAuth Server、開発用トークン）、LLM とのやり取りに使える組み込みユーティリティ、そして自動テレメトリー連携を利用できます。Golf が認証、監視、サーバーインフラストラクチャを処理するため、エージェントのロジックの実装に集中できます。

クイックスタート

簡単な手順で Golf プロジェクトを開始できます。

1. Golf をインストールする

Golf には Python 3.10 以降が必要です。次に、pip を使って Golf をインストールします。

pip install golf-mcp

2. プロジェクトを初期化する

Golf CLI を使って、新しいプロジェクトのひな形を作成します。

golf init your-project-name

このコマンドは、サンプルのツール、リソース、golf.json 設定ファイルを含む基本的なプロジェクト構造とともに、新しいディレクトリ（your-project-name）を作成します。

3. 開発サーバーを起動する

新しいプロジェクトディレクトリに移動し、開発サーバーを起動します。

cd your-project-name
golf build dev
golf run

これにより MCP サーバーが起動します。通常は http://localhost:3000 で実行されます（golf.json で設定できます）。

これで完了です。Golf サーバーが起動し、連携できる状態になりました。

基本的なプロジェクト構造

golf init で初期化した Golf プロジェクトは、次のような構造になります。

<your-project-name>/
│
├─ golf.json          # Main project configuration
│
├─ tools/             # Directory for tool implementations
│   └─ hello.py       # Example tool
│
├─ resources/         # Directory for resource implementations
│   └─ info.py        # Example resource
│
├─ prompts/           # Directory for prompt templates
│   └─ welcome.py     # Example prompt
│
├─ .env               # Environment variables (e.g., API keys, server port)
└─ auth.py            # Authentication configuration (JWT, OAuth Server, API key, dev tokens)

• golf.json：サーバー名、ポート、トランスポート、テレメトリー、その他のビルド設定を構成します。
• auth.py：JWT、OAuth Server、API キー、または開発用認証を設定する専用の認証設定ファイルです（v0.2.0 で追加。v0.1.x の認証 API からの破壊的変更です）。
• tools/、resources/、prompts/：それぞれ単一のコンポーネントを定義する Python ファイルを格納します。これらのディレクトリには、コンポーネントをさらに整理するために、ネストしたサブディレクトリを作成することもできます（例：tools/payments/charge.py）。各ファイルのモジュール docstring がコンポーネントの説明として使われます。
  • コンポーネント ID はファイルパスから自動的に決定されます。たとえば、tools/hello.py は hello になり、tools/payments/submit.py のようなネストしたファイルは submit_payments になります（ファイル名の後に、メインカテゴリ以下の親ディレクトリを逆順に並べ、アンダースコアで連結します）。

例：ツールを定義する

新しいツールを作成するには、tools/ ディレクトリに Python ファイルを追加するだけです。ひな形に含まれる tools/hello.py の例は次のとおりです。

# tools/hello.py
"""Hello World tool {{project_name}}."""

from typing import Annotated
from pydantic import BaseModel, Field

class Output(BaseModel):
    """Response from the hello tool."""
    message: str

async def hello(
    name: Annotated[str, Field(description="The name of the person to greet")] = "World",
    greeting: Annotated[str, Field(description="The greeting phrase to use")] = "Hello"
) -> Output:
    """Say hello to the given name.
    
    This is a simple example tool that demonstrates the basic structure
    of a tool implementation in Golf.
    """
    print(f"{greeting} {name}...")
    return Output(message=f"{greeting}, {name}!")

# Designate the entry point function
export = hello

Golf はこのファイルを自動的に検出します。モジュール docstring """Hello World tool {{project_name}}.""" がツールの説明として使われます。hello 関数のシグネチャからパラメーターを推測し、出力スキーマには Output Pydantic モデルを使います。このツールは ID hello で登録されます。

認証と機能

Golf には、エンタープライズグレードの認証、組み込みユーティリティ、自動テレメトリが備わっています。

# auth.py - Configure authentication
from golf.auth import configure_auth, JWTAuthConfig, StaticTokenConfig, OAuthServerConfig

# JWT authentication (production)
configure_auth(JWTAuthConfig(
    jwks_uri_env_var="JWKS_URI",
    issuer_env_var="JWT_ISSUER", 
    audience_env_var="JWT_AUDIENCE",
    required_scopes=["read", "write"]
))

# OAuth Server mode (Golf acts as OAuth 2.0 server)
# configure_auth(OAuthServerConfig(
#     base_url="https://your-golf-server.com",
#     valid_scopes=["read", "write", "admin"]
# ))

# Static tokens (development only)
# configure_auth(StaticTokenConfig(
#     tokens={"dev-token": {"client_id": "dev", "scopes": ["read"]}}
# ))

# Built-in utilities available in all tools
from golf.utilities import elicit, sample, get_current_context

MCP 2026-07-28 では、エリシテーションとサンプリングは、呼び出し元が所有する複数ラウンドトリップの制御フローを使用します。ネストされたヘルパーから、外側のツールを透過的に続行することはできません。ツールの戻り値の型で InputRequiredResult を宣言し、そのような結果は変更せずに返してください。その後、回答とともにツールが再度呼び出されます。レガシー接続では、引き続き命令型リクエストが使用されます。

from mcp_types import InputRequiredResult
from golf.utilities import sample

async def explain(topic: str) -> str | InputRequiredResult:
    result = await sample(f"Explain {topic}")
    if isinstance(result, InputRequiredResult):
        return result
    return result

JWT 認証には audience が必要です。これにより、トークンはこの MCP リソースに紐付けられます。受信した MCP の JWT／OAuth ベアラートークンを上流 API に転送してはいけません。別の上流用認証情報、または標準準拠のトークン交換／委任フローを使用してください。

# Enable OpenTelemetry tracing
export OTEL_TRACES_EXPORTER="otlp_http"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318/v1/traces"
golf run  # ✅ Telemetry enabled

📚 ドキュメント全文を見る →

設定

golf.json の基本設定：

{
  "name": "My Golf Server",
  "host": "localhost",
  "port": 3000,
  "transport": "streamable-http",
  "opentelemetry_enabled": false,
  "detailed_tracing": false
}

• transport："streamable-http" または "stdio" を使用します。SSE は、非推奨のレガシートランスポートとしてのみ引き続き利用できます。
• stateless_http：任意のレガシー Streamable HTTP 動作です。MCP 2026-07-28 は本質的にセッションレスであり、この設定には依存しません。
• opentelemetry_enabled：OpenTelemetry トレーシングを有効にします
• detailed_tracing：入力／出力を記録します（機密データを扱う場合は慎重に使用してください）

プライバシーとテレメトリ

Golf は、フレームワークがどのように使用されているかを把握し、継続的に改善するため、CLI の匿名使用状況データを収集します。収集されるデータは次のとおりです。

• 実行されたコマンド（init、build、run）
• 成功／失敗の状態（エラーの詳細は含まれません）
• Golf のバージョン、Python のバージョン（メジャー．マイナーのみ）、OS の種類
• テンプレート名（init コマンドの場合のみ）
• ビルド環境（build コマンドの場合のみ、dev／prod）

個人情報、プロジェクト名、コードの内容、エラーメッセージは一切収集されません。

オプトアウト

テレメトリは、いくつかの方法で無効にできます。

1. telemetry コマンドを使用する（推奨）：

   golf telemetry disable
   

   設定は恒久的に保存されます。再度有効にするには、次のコマンドを実行します：

   golf telemetry enable
   

2. 任意のコマンドの実行時：--no-telemetry を追加して設定を保存します：

   golf init my-project --no-telemetry
   

テレメトリの設定は ~/.golf/telemetry.json に保存され、すべての Golf コマンドで維持されます。