⛳ Golf

最简易的 MCP Server 构建框架。

📚 文档

概述

Golf 是一个旨在简化 MCP Server 应用创建的框架。它允许开发者在约定的目录结构中，通过简单的 Python 文件定义 Server 的功能——包括 tools（工具）、prompts（提示词）和 resources（资源）。Golf 会自动发现、解析并将这些组件编译为可运行的 MCP Server，从而最大限度地减少模板代码并加速开发进程。

在 Golf v0.2.0 版本中，你将获得企业级身份验证（支持 JWT、OAuth Server、API Key 和开发令牌）、用于 LLM 交互的内置工具库以及自动遥测（Telemetry）集成。你只需专注于实现 Agent 的逻辑，而 Golf 会处理身份验证、监控和 Server 基础设施。

快速入门

通过以下几个简单步骤即可启动你的 Golf 项目：

1. 安装 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 Server，默认地址为 http://localhost:3000（可在 golf.json 中配置）。

一切就绪！你的 Golf Server 已启动并可随时接入。

基础项目结构

通过 golf init 初始化的 Golf 项目结构如下所示：

/
│
├─ golf.json          # 主项目配置
│
├─ tools/             # 工具实现目录
│   └─ hello.py       # 示例工具
│
├─ resources/         # 资源实现目录
│   └─ info.py        # 示例资源
│
├─ prompts/           # 提示词模板目录
│   └─ welcome.py     # 示例提示词
│
├─ .env               # 环境变量 (如 API Keys, Server 端口)
└─ auth.py            # 身份验证配置 (JWT, OAuth Server, API Key, 开发令牌)

• golf.json: 配置 Server 名称、端口、传输协议、遥测以及其他构建设置。
• auth.py: 专门的身份验证配置文件（v0.2.0 新增，相比 v0.1.x 的身份验证 API 有重大变更），用于配置 JWT、OAuth Server、API Key 或开发阶段的身份验证。
• tools/, resources/, prompts/: 存放你的 Python 文件，每个文件定义一个组件。这些目录可以包含嵌套的子目录，以便更好地组织组件（例如 tools/payments/charge.py）。每个文件的模块文档字符串（docstring）将作为该组件的描述。
  • 组件 ID 会根据其文件路径自动生成。例如，tools/hello.py 的 ID 为 hello；嵌套文件如 tools/payments/submit.py 的 ID 将变为 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}}.""" 将作为工具的描述。它会自动从 hello 函数的签名中推断参数，并使用 Pydantic 模型 Output 作为输出架构。该工具将被注册为 ID hello。

身份验证与功能

Golf 包含企业级身份验证、内置实用工具和自动遥测功能：

# auth.py - 配置身份验证
from golf.auth import configure_auth, JWTAuthConfig, StaticTokenConfig, OAuthServerConfig

# JWT 身份验证 (生产环境)
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 模式 (Golf 作为 OAuth 服务端)