项目介绍
概述
Golf 是一个旨在简化MCP服务器应用程序创建的框架。它允许开发者通过简单的Python文件定义服务器的功能——工具、提示和资源——这些文件位于常规目录结构中。Golf 自动发现、解析并编译这些组件到可运行的MCP服务器，减少样板代码并加速开发。
在Golf v0.2.0中，您将获得企业级认证（JWT、OAuth服务器、API密钥、开发令牌）、内置的LLM交互实用工具以及自动遥测集成。专注于实现您的代理逻辑，而Golf处理认证、监控和服务器基础设施。
快速开始
按照几个简单步骤启动您的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服务器，通常在http://localhost:3000（可在golf.json中配置）。
就这样！您的Golf服务器正在运行并准备好进行集成。
基本项目结构
使用golf init初始化的Golf项目将具有类似以下的结构：
<your-project-name>/
│
├─ golf.json # 主项目配置
│
├─ tools/ # 工具实现目录
│ └─ hello.py # 示例工具
│
├─ resources/ # 资源实现目录
│ └─ info.py # 示例资源
│
├─ prompts/ # 提示模板目录
│ └─ welcome.py # 示例提示
│
├─ .env # 环境变量（例如，API密钥、服务器端口）
└─ auth.py # 认证配置（JWT、OAuth服务器、API密钥、开发认证）
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（文件名，加上主要类别下的反向父目录，用下划线连接）。
- 组件ID自动从其文件路径推导而来。例如，
示例：定义一个工具
创建一个新的工具就像在tools/目录中添加一个Python文件一样简单。样板中的tools/hello.py如下所示：
# tools/hello.py
"""Hello World工具 {{project_name}}."""
from typing import Annotated
from pydantic import BaseModel, Field
class Output(BaseModel):
"""来自hello工具的响应"""
message: str
async def hello(
name: Annotated[str, Field(description="要问候的人的名字")] = "World",
greeting: Annotated[str, Field(description="使用的问候语")] = "Hello"
) -> Output:
"""向给定的名字问候。
这是一个简单的示例工具，展示了Golf中工具实现的基本结构。
"""
print(f"{greeting} {name}...")
return Output(message=f"{greeting}, {name}!")
# 指定入口函数
export = hello
Golf会自动发现这个文件。模块文档字符串"""Hello World工具 {{project_name}}."""用作工具的描述。它从hello函数签名中推断参数，并使用OutputPydantic模型作为输出模式。该工具将注册为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服务器模式（Golf充当OAuth 2.0服务器）
# configure_auth(OAuthServerConfig(
# base_url="https://your-golf-server.com",
# valid_scopes=["read", "write", "admin"]
# ))
# 静态令牌（仅限开发）
# configure_auth(StaticTokenConfig(
# tokens={"dev-token": {"client_id": "dev", "scopes": ["read"]}}
# ))
# 在所有工具中可用的内置实用工具
from golf.utils import elicit, sample, get_context
# 启用OpenTelemetry跟踪
export OTEL_TRACES_EXPORTER="otlp_http"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318/v1/traces"
golf run # ✅ 开启遥测
配置
基本配置在golf.json中：
{
"name": "我的Golf服务器",
"host": "localhost",
"port": 3000,
"transport": "sse",
"opentelemetry_enabled": false,
"detailed_tracing": false
}
transport：选择"sse"、"streamable-http"或"stdio"opentelemetry_enabled：启用OpenTelemetry跟踪detailed_tracing：捕获输入/输出（谨慎使用敏感数据）
隐私及遥测
Golf收集CLI上的匿名使用数据，帮助我们了解框架的使用情况并随着时间改进它。收集的数据包括：
- 执行的命令（init、build、run）
- 成功/失败状态（无错误详情）
- Golf版本、Python版本（仅主次版本）和操作系统类型
- 模板名称（仅针对init命令）
- 构建环境（仅针对构建命令的dev/prod）
不会收集个人资料、项目名称、代码内容或错误消息。
退出遥测
您可以通过几种方式禁用遥测：
-
使用遥测命令（推荐）：
golf telemetry disable这将永久保存您的偏好。要重新启用：
golf telemetry enable -
在任何命令期间：添加
--no-telemetry以保存您的偏好：golf init my-project --no-telemetry
您的遥测偏好存储在~/.golf/telemetry.json中，并在所有Golf命令中持久化。