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 文件。