mcp-prompt-engine

MCP Prompt Engine

A Model Control Protocol (MCP) server for managing and serving dynamic prompt templates using elegant and powerful text template engine. Create reusable, logic-driven prompts with variables, partials, and conditionals that can be served to any compatible MCP client like Claude Code, Claude Desktop, Gemini CLI, VSCode with Copilot, etc.

Key Features

• MCP Compatible: Works out-of-the-box with any MCP client that supports prompts.
• Powerful Go Templates: Utilizes the full power of Go text/template syntax, including variables, conditionals, loops, and more.
• Reusable Partials: Define common components in partial templates (e.g., _header.tmpl) and reuse them across your prompts.
• Prompt Arguments: All template variables are automatically exposed as MCP prompt arguments, allowing dynamic input from clients.
• Hot-Reload: Automatically detects changes to your prompt files and reloads them without restarting the server.
• Rich CLI: A modern command-line interface to list, validate, and render templates for easy development and testing.
• Smart Argument Handling:
  • Automatically parses JSON arguments (booleans, numbers, arrays, objects).
  • Injects environment variables as fallbacks for template arguments.
• Containerized: Full Docker support for easy deployment and integration.

Getting Started

1. Installation

Install using Go:

(For other methods like Docker or pre-built binaries, see the Installation section below.)

2. Create a Prompt

Create a prompts directory and add a template file. Let's create a prompt to help write a Git commit message.

First, create a reusable partial named prompts/_git_commit_role.tmpl: ```go {{ 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.

Now, create a main prompt prompts/git_stage_commit.tmpl that uses this partial: ```go {{- /* Commit currently staged changes */ -}}

3. Validate Your Prompt

Validate your prompt to ensure it has no syntax errors:

4. Connect MCP Server to Your Client

Add MCP Server to your MCP client. See Connecting to Clients for configuration examples.

5. Use Your Prompt

Your git_stage_commit prompt will now be available in your client!

For example, in Claude Desktop, you can select the git_stage_commit prompt, provide the type MCP Prompt argument and get a generated prompt that will help you to do a commit with a perfect message.

In Claude Code or Gemini CLI, you can start typing /git_stage_commit and it will suggest the prompt with the provided arguments that will be executed after you select it.

Installation

Pre-built Binaries

Download the latest release for your OS from the GitHub Releases page.

Build from Source

Docker

A pre-built Docker image is available. Mount your local prompts and logs directories to the container.

You can also build the image locally with make docker-build.

Usage

Creating Prompt Templates

Create a directory to store your prompt templates. Each template should be a .tmpl file using Go's text/template syntax with the following format:

The first line comment ({{/* description */}}) is used as the prompt description, and the rest of the file is the prompt template.

Partial templates should be prefixed with an underscore (e.g., _header.tmpl) and can be included in other templates using {{template "partial_name" .}}.

Template Syntax

The server uses Go's text/template engine, which provides powerful templating capabilities:

• Variables: {{.variable_name}} - Access template variables
• Built-in variables:
  • {{.date}} - Current date and time
• Conditionals: {{if .condition}}...{{end}}, {{if .condition}}...{{else}}...{{end}}
• Logical operators: {{if and .condition1 .condition2}}...{{end}}, {{if or .condition1 .condition2}}...{{end}}
• Loops: {{range .items}}...{{end}}
• Template inclusion: {{template "partial_name" .}} or {{template "partial_name" dict "key" "value"}}

See the Go text/template documentation for more details on syntax and features.

JSON Argument Parsing

The server automatically parses argument values as JSON when possible, enabling rich data types in templates:

• Booleans: true, false → Go boolean values
• Numbers: 42, 3.14 → Go numeric values
• Arrays: ["item1", "item2"] → Go slices for use with {{range}}
• Objects: {"key": "value"} → Go maps for structured data
• Strings: Invalid JSON falls back to string values

This allows for advanced template operations like:

To disable JSON parsing and treat all arguments as strings, use the --disable-json-args flag for the serve and render commands.

CLI Commands

The CLI is your main tool for managing and testing templates. By default, it looks for templates in the ./prompts directory, but you can specify a different directory with the --prompts flag.

1. List Templates

2. Render a Template

Render a prompt directly in your terminal, providing arguments with the -a or --arg flag. It will automatically inject environment variables as fallbacks for any missing arguments. For example, if you have an environment variable TYPE=fix, it will be injected into the template as {{.type}}.

3. Validate Templates

Check all your templates for syntax errors. The command will return an error if any template is invalid.

4. Start the Server

Run the MCP server to make your prompts available to clients.

Connecting to Clients

To use this engine with any client that supports MCP Prompts, add a new entry to its MCP servers configuration.

Global configuration locations (MacOS):

• Claude Code: ~/.claude.json (mcpServers section)
• Claude Desktop: ~/Library/Application\ Support/Claude/claude_desktop_config.json (mcpServers section)
• Gemini CLI: ~/.gemini/settings.json (mcpServers section)

Example for a local binary:

Example for Docker:

License

This project is licensed under the MIT License - see the LICENSE file for details.