MCP Prompt Engine

🚀 MCP 提示引擎

MCP 提示引擎是一個基於 Model Control Protocol (MCP) 的服務器，藉助優雅強大的文本模板引擎，實現對動態提示模板的管理與服務。它能創建可複用、基於邏輯的提示，支持變量、部分模板和條件語句，可服務於任何 兼容 MCP 的客戶端，如 Claude Code、Claude Desktop、Gemini CLI、集成 Copilot 的 VSCode 等。

🚀 快速開始

1. 安裝

使用 Go 進行安裝：

go install github.com/vasayxtx/mcp-prompt-engine@latest

（其他安裝方法，如 Docker 或預構建二進制文件，請參閱下面的 安裝指南。）

2. 創建提示

創建一個 prompts 目錄並添加一個模板文件。下面以創建一個用於撰寫 Git 提交信息的提示為例。

首先，創建一個可複用的部分模板 prompts/_git_commit_role.tmpl：

{{ define "_git_commit_role" }}
You are an expert programmer specializing in writing clear, concise, and conventional Git commit messages.
Commit message must strictly follow the Conventional Commits specification.

The final commit message you generate must be formatted exactly as follows:

: A brief, imperative-tense summary of changes

[Optional longer description, explaining the "why" of the change. Use dash points for clarity.]

{{ if .type -}}
Use {{.type}} as a type.
{{ end }}
{{ end }}

接著，創建一個使用該部分模板的主提示 prompts/git_stage_commit.tmpl：

{{- /* Commit currently staged changes */ -}}

{{- template "_git_commit_role" . -}}

Your task is to commit all currently staged changes.
To understand the context, analyze the staged code using the command: `git diff --staged`
Based on that analysis, commit staged changes using a suitable commit message.

3. 驗證提示

驗證提示以確保其沒有語法錯誤：

mcp-prompt-engine validate git_stage_commit
✓ git_stage_commit.tmpl - Valid

4. 將 MCP 服務器連接到客戶端

將 MCP 服務器添加到你的 MCP 客戶端。有關配置示例，請參閱 連接到客戶端。

5. 使用提示

現在，你的 git_stage_commit 提示將在客戶端中可用！

例如，在 Claude Desktop 中，你可以選擇 git_stage_commit 提示，提供 type MCP 提示參數，然後獲得一個生成的提示，幫助你撰寫完美的提交信息。

在 Claude Code 或 Gemini CLI 中，你可以開始輸入 /git_stage_commit，它將提示你提供參數，選擇後即可執行。

✨ 主要特性

• MCP 兼容：可直接與任何支持 提示 的 MCP 客戶端 配合使用。
• 強大的 Go 模板：充分利用 Go text/template 語法，支持變量、條件語句、循環等。
• 可複用部分模板：在部分模板（如 _header.tmpl）中定義通用組件，並在提示中重複使用。
• 提示參數：所有模板變量會自動作為 MCP 提示參數暴露，允許客戶端動態輸入。
• 熱加載：自動檢測提示文件的更改，無需重啟服務器即可重新加載。
• 豐富的 CLI：提供現代命令行界面，可列出、驗證和渲染模板，便於開發和測試。
• 智能參數處理：
  • 自動解析 JSON 參數（布爾值、數字、數組、對象）。
  • 將環境變量作為模板參數的備用值注入。
• 容器化：全面支持 Docker，便於部署和集成。

📦 安裝指南

預構建二進制文件

從 GitHub 發佈頁面 下載適用於你操作系統的最新版本。

從源代碼構建

git clone https://github.com/vasayxtx/mcp-prompt-engine.git
cd mcp-prompt-engine
make build

Docker

提供預構建的 Docker 鏡像。將本地的 prompts 和 logs 目錄掛載到容器中。

# 從 GHCR 拉取並運行預構建鏡像
docker run -i --rm \
  -v /path/to/your/prompts:/app/prompts:ro \
  -v /path/to/your/logs:/app/logs \
  ghcr.io/vasayxtx/mcp-prompt-engine

你也可以使用 make docker-build 在本地構建鏡像。

💻 使用示例

基礎用法

創建提示模板

創建一個目錄來存儲提示模板。每個模板應為 .tmpl 文件，使用 Go 的 text/template 語法，格式如下：

{{/* Brief description of the prompt */}}
Your prompt text here with {{.template_variable}} placeholders.

第一行註釋 ({{/* description */}}) 用作提示描述，文件的其餘部分為提示模板。

部分模板應以下劃線開頭（如 _header.tmpl），並可使用 {{template "partial_name" .}} 包含在其他模板中。

高級用法

模板語法

服務器使用 Go 的 text/template 引擎，提供強大的模板功能：

• 變量：{{.variable_name}} - 訪問模板變量
• 內置變量：
  • {{.date}} - 當前日期和時間
• 條件語句：{{if .condition}}...{{end}}, {{if .condition}}...{{else}}...{{end}}
• 邏輯運算符：{{if and .condition1 .condition2}}...{{end}}, {{if or .condition1 .condition2}}...{{end}}
• 循環：{{range .items}}...{{end}}
• 模板包含：{{template "partial_name" .}} 或 {{template "partial_name" dict "key" "value"}}

更多語法和功能細節，請參閱 Go text/template 文檔。

JSON 參數解析

服務器會在可能的情況下自動將參數值解析為 JSON，從而在模板中支持豐富的數據類型：

• 布爾值：true, false → Go 布爾值
• 數字：42, 3.14 → Go 數值
• 數組：["item1", "item2"] → Go 切片，可與 {{range}} 配合使用
• 對象：{"key": "value"} → Go 映射，用於結構化數據
• 字符串：無效的 JSON 會回退為字符串值

這允許進行高級模板操作，例如：

{{range .items}}Item: {{.}}{{end}}
{{if .enabled}}Feature is enabled{{end}}
{{.config.timeout}} seconds

要禁用 JSON 解析並將所有參數視為字符串，請在 serve 和 render 命令中使用 --disable-json-args 標誌。

CLI 命令

CLI 是管理和測試模板的主要工具。默認情況下，它會在 ./prompts 目錄中查找模板，但你可以使用 --prompts 標誌指定不同的目錄。

1. 列出模板

# 查看可用提示的簡單列表
mcp-prompt-engine list

# 查看帶有描述和變量的詳細視圖
mcp-prompt-engine list --verbose

2. 渲染模板 在終端中直接渲染提示，並使用 -a 或 --arg 標誌提供參數。它會自動將環境變量作為缺失參數的備用值注入。例如，如果你有一個環境變量 TYPE=fix，它將作為 {{.type}} 注入到模板中。

# 渲染 Git 提交提示，提供 'type' 變量
mcp-prompt-engine render git_stage_commit --arg type=feat

3. 驗證模板 檢查所有模板是否存在語法錯誤。如果任何模板無效，命令將返回錯誤。

# 驗證目錄中的所有模板
mcp-prompt-engine validate

# 驗證單個模板
mcp-prompt-engine validate git_stage_commit

4. 啟動服務器 運行 MCP 服務器，使提示可供客戶端使用。

# 使用默認設置運行（查找 ./prompts）
mcp-prompt-engine serve

# 指定不同的提示目錄和日誌文件
mcp-prompt-engine --prompts /path/to/prompts serve --log-file ./server.log

📚 詳細文檔

連接到客戶端

要將此引擎與任何支持 MCP 提示的客戶端一起使用，請在其 MCP 服務器配置中添加一個新條目。

全局配置位置（MacOS）：

• Claude Code：~/.claude.json（mcpServers 部分）
• Claude Desktop：~/Library/Application\ Support/Claude/claude_desktop_config.json（mcpServers 部分）
• Gemini CLI：~/.gemini/settings.json（mcpServers 部分）

本地二進制文件示例：

{
  "prompts": {
    "command": "/path/to/your/mcp-prompt-engine",
    "args": [
      "--prompts", "/path/to/your/prompts",
      "serve",
      "--quiet"
    ]
  }
}

Docker 示例：

{
  "mcp-prompt-engine-docker": {
    "command": "docker",
    "args": [
      "run", "-i", "--rm",
      "-v", "/path/to/your/prompts:/app/prompts:ro",
      "-v", "/path/to/your/logs:/app/logs",
      "ghcr.io/vasayxtx/mcp-prompt-engine"
    ]
  }
}

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。