/ 目錄 / 演練場 / golf
● 社群 golf-mcp ⚡ 即開即用

golf

作者 golf-mcp · golf-mcp/golf

用於生產級 MCP 伺服器的 Python 框架——自動探索工具檔案、內建驗證(JWT/OAuth/API 金鑰),以及開箱即用的 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

何時使用: 你想透過 Claude 對員工提供一個經過驗證的單一 MCP,涵蓋 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. 啟用與身份識別提供者整合的 JWT 驗證
    在 golf.yaml 中設定 auth: jwt,填入你的身份識別提供者 JWKS URL,並要求 mcp:use 範圍。✓ 已複製
    → 未驗證的呼叫被拒絕

結果: 一個可部署的 MCP,僅授權員工可呼叫,且追蹤資料會流向你的 APM。

注意事項
  • 任一工具的匯入失敗會導致伺服器無法啟動 — Golf 會急切載入工具——修正匯入錯誤,或將大型相依套件移至函式內部再引入

從第一天就具備 OpenTelemetry 的 MCP

👤 SRE、可觀測性工程師 ⏱ ~30 min advanced

何時使用: 你已在運行 OTel 收集器,並希望代理工具呼叫能出現在追蹤記錄中。

步驟
  1. 啟用遙測
    在 golf.yaml 中啟用 telemetry.otlp,並填入你的收集器端點。✓ 已複製
    → 工具呼叫以 span 形式出現在你的 OTel 後端
  2. 將驗證中的使用者 ID 標記至追蹤記錄
    新增一個中介層,從 JWT sub 欄位取出 user.id 並設定至每個 span。✓ 已複製
    → 可查看每位使用者的呼叫圖

結果: 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 的指標端點抓取至 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 預設不會將其寫入日誌
資料出站: 取決於你的工具所呼叫的目標

故障排查

常見錯誤與修復

Tool not showing in tools list

確認該檔案匯出的非同步函式名稱符合 Golf 的預期(參閱框架文件);最常見的原因是缺少 __tool__ 中繼資料

驗證: golf run --debug shows discovery log
JWT validation fails with valid token

JWKS URL 無法連線或 issuer 設定錯誤。請用 curl 驗證,並檢查主機的時鐘偏差

Traces not appearing in OTel backend

Golf 使用 OTLP/HTTP——請確認收集器已啟用該接收器,而非僅啟用 gRPC

驗證: curl -v $OTLP_ENDPOINT/v1/traces

替代方案

golf 對比其他方案

替代方案何時用它替代權衡
FastMCP你想要更簡單、不需要驗證與遙測功能的方案生產環境所需的功能需自行實作
MCP-Nest (NestJS)你的團隊以 NestJS 為主要技術棧僅支援 TypeScript
Arcade你同樣重視工具的發布與分享,而不只是建構目標受眾略有不同

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills