Golf

概述

Golf 是一个旨在简化 MCP 服务应用创建流程的框架。开发者可以在规范的目录结构中，将服务端的功能——工具、提示词和资源——定义为简单的 Python 文件。随后，Golf 会自动发现、解析并编译这些组件，生成可运行的 MCP 服务，减少样板代码并加快开发速度。

Golf 面向 FastMCP 4.0.0 和当前的 MCP 2026-07-28 协议。 FastMCP 也会通过兼容模式与旧版 MCP 客户端协商。

Golf v0.2.0 提供企业级身份验证（JWT、OAuth 服务端、开发令牌）、用于大模型交互的内置实用工具以及自动遥测集成。你可以专注于实现 Agent 逻辑，而由 Golf 负责身份验证、监控和服务端基础设施。

快速开始

只需几个简单步骤，即可启动并运行 Golf 项目：

1. 安装 Golf

Golf 需要 Python 3.10 或更高版本。然后使用 pip 安装 Golf：

pip install golf-mcp

2. 初始化项目

使用 Golf CLI 搭建新项目的脚手架：

golf init your-project-name

此命令会创建一个新目录（your-project-name），其中包含基本的项目结构，包括示例工具、资源以及 golf.json 配置文件。

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：专用的身份验证配置文件（v0.2.0 新增，与 v0.1.x 的身份验证 API 不兼容），用于配置 JWT、OAuth 服务端、API 密钥或开发环境身份验证。
• tools/、resources/、prompts/：包含你的 Python 文件，每个文件定义一个组件。这些目录也可以包含嵌套子目录，以便进一步整理组件（例如，tools/payments/charge.py）。每个文件的模块文档字符串将作为该组件的描述。
  • 组件 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 会自动发现此文件。模块文档字符串 """Hello World tool {{project_name}}.""" 将用作工具描述。Golf 会根据 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 身份验证需要受众，以便将令牌绑定到此 MCP 资源。绝不能将传入的 MCP JWT/OAuth Bearer 令牌转发到上游 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 版本（仅主版本.次版本）和操作系统类型
• 模板名称（仅适用于 init 命令）
• 构建环境（仅适用于 build 命令，dev/prod）

绝不会收集个人信息、项目名称、代码内容或错误消息。

退出遥测

你可以通过多种方式禁用遥测：

1. 使用遥测命令（推荐）：

   golf telemetry disable
   

   此操作会永久保存你的偏好设置。如需重新启用：

   golf telemetry enable
   

2. 运行任何命令时：添加 --no-telemetry 以保存你的偏好设置：

   golf init my-project --no-telemetry
   

你的遥测偏好设置存储在 ~/.golf/telemetry.json 中，并在所有 Golf 命令中持续生效。