/ 目录 / 演练场 / golf
● 社区 golf-mcp ⚡ 即开即用

golf

作者 golf-mcp · golf-mcp/golf

用于部署生产级 MCP 服务器的 Python 框架——自动发现工具文件、内置认证(JWT/OAuth/API key)以及 OpenTelemetry 开箱即用。

Golf(golf-mcp)让你在约定的目录里以普通 Python 文件的形式定义 MCP 工具;框架会将它们编译成生产级服务器,认证、遥测和日志已全部搞定。目标是为需要内部 MCP 平台的团队服务,而不是一次性脚本。

为什么要用

核心特性

实时演示

实际使用效果

golf.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "golf": {
      "command": "uvx",
      "args": [
        "golf"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "golf": {
      "command": "uvx",
      "args": [
        "golf"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "golf": {
      "command": "uvx",
      "args": [
        "golf"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "golf": {
      "command": "uvx",
      "args": [
        "golf"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "golf",
      "command": "uvx",
      "args": [
        "golf"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "golf": {
      "command": {
        "path": "uvx",
        "args": [
          "golf"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add golf -- uvx golf

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: golf

用 Golf 构建内部公司 MCP

👤 平台工程师 ⏱ ~60 min advanced

何时使用: 你想用单个经过认证的 MCP 向员工通过 Claude 暴露 20+ 个内部工具(Jira、Grafana、工单系统)。

前置条件
  • Python 3.11+、uv — astral.sh/uv
步骤
  1. 初始化
    运行 uvx golf new acme-mcp 并进入目录。✓ 已复制
    → 项目包含 tools/、prompts/、resources/ 目录
  2. 添加工具文件
    在 tools/list_tickets.py 中创建导出异步函数的工具。Golf 会自动连接 schema。✓ 已复制
    → 工具在 /tools 列表中可见
  3. 启用绑定到你 IdP 的 JWT 认证
    在 golf.yaml 中配置 auth:jwt,提供你 IdP 的 JWKS URL。要求 mcp:use scope。✓ 已复制
    → 未经认证的调用被拒绝

结果: 一个只有授权员工能调用的可部署 MCP,追踪流向你的 APM。

注意事项
  • 任何工具导入失败都会导致服务器启动失败 — Golf 急加载工具——修复导入错误或将重依赖移到函数内部

从第一天起就带上 OpenTelemetry 发布 MCP

👤 SRE、可观测性工程师 ⏱ ~30 min advanced

何时使用: 你已经运行 OTel 收集器,想要 agent 工具调用出现在追踪中。

步骤
  1. 启用遥测
    在 golf.yaml 中启用 telemetry.otlp,配置你的收集器端点。✓ 已复制
    → 工具调用在你的 OTel 后端以 span 形式出现
  2. 用认证中的 user id 标记追踪
    添加中间件,从 JWT sub 为每个 span 设置 user.id✓ 已复制
    → 按用户的调用图

结果: MCP 使用在你现有的可观测性系统中成为一等公民。

搭配使用: prometheus

用 Golf 将提示词与代码一起版本化

👤 提示词工程师 ⏱ ~25 min intermediate

何时使用: 你的提示词在 Notion 中,与实际部署的版本漂移。

步骤
  1. 将提示词移入 prompts/ 目录
    创建 prompts/triage.py,包含提示词模板和变量。✓ 已复制
    → 提示词出现在 MCP 的 /prompts/list
  2. 在每次提交时进行 CI 验证
    添加测试,用示例输入渲染每个提示词以捕获破坏性变更✓ 已复制
    → 提示词编辑的回归安全性

结果: 提示词通过与代码相同的 PR 流程发布。

组合

与其他 MCP 搭配,撬动十倍杠杆

golf + hyper

比较基于 Python 的 Golf 服务器与 WASM hyper-mcp 插件模型

我在 Golf 和 hyper-mcp 中有相同的工具。运行 100 个调用中每个的延迟和内存比较。✓ 已复制
golf + prometheus

将 Golf 的 metrics 端点抓取到 Prometheus

将我的 Prometheus 指向 golf 的 /metrics,然后用 prometheus-mcp 查询 p99 工具延迟。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
golf new <name> project_name: str 启动新服务器 0
golf build 将工具目录编译成服务器二进制文件/镜像 0
golf run --transport stdio|http 本地开发或生产启动 0

成本与限制

运行它的成本

API 配额
无限制——框架在你部署的任何地方运行
每次调用 Token 数
取决于工具
费用
免费,开源
提示
在生产环境中启用遥测采样(例如 10% 的工具调用)来控制 OTel 摄入成本

安全

权限、密钥、影响范围

凭据存储: JWT/OAuth 密钥通过环境变量;Golf 默认不记录它们
数据出站: 你的工具调用到任何地方

故障排查

常见错误与修复

工具未显示在工具列表中

检查文件导出 Golf 期望的确切名称的异步函数(参见框架文档);缺失 __tool__ 元数据是最常见的原因

验证: golf run --debug shows discovery log
有效 token 的 JWT 验证失败

JWKS URL 无法访问或发行者错误。用 curl 验证;检查主机上的时钟偏差

追踪未出现在 OTel 后端

Golf 使用 OTLP/HTTP——确保收集器启用了该接收器,而不仅仅是 gRPC

验证: curl -v $OTLP_ENDPOINT/v1/traces

替代方案

golf 对比其他方案

替代方案何时用它替代权衡
FastMCP你想要一个更简单的、没有认证/遥测特性的东西需自行处理生产相关事项
MCP-Nest (NestJS)你的团队是 NestJS 技术栈仅限 TypeScript
Arcade同样关注分发/共享和构建目标受众略有不同

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills