MCP Prompt Engine

1# MCP Prompt Engine
2 
3[![Go Report Card](https://goreportcard.com/badge/github.com/vasayxtx/mcp-prompt-engine)](https://goreportcard.com/report/github.com/vasayxtx/mcp-prompt-engine)
4[![GitHub release (latest by date)](https://img.shields.io/github/v/release/vasayxtx/mcp-prompt-engine)](https://github.com/vasayxtx/mcp-prompt-engine/releases)
5[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6[![Go.Dev reference](https://img.shields.io/badge/go.dev-reference-blue?logo=go&logoColor=white)](https://pkg.go.dev/github.com/vasayxtx/mcp-prompt-engine)
7 
8A Model Control Protocol (MCP) server for managing and serving dynamic prompt templates using elegant and powerful text template engine.
9Create reusable, logic-driven prompts with variables, partials, and conditionals that can be served to any [compatible MCP client](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/clients.mdx) like Claude Code, Claude Desktop, Gemini CLI, VSCode with Copilot, etc.
10 
11## Key Features
12 
13-   **MCP Compatible**: Works out-of-the-box with any [MCP client](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/clients.mdx) that supports [prompts](https://modelcontextprotocol.io/docs/concepts/prompts).
14-   **Powerful Go Templates**: Utilizes the full power of Go [text/template](https://pkg.go.dev/text/template) syntax, including variables, conditionals, loops, and more.
15-   **Reusable Partials**: Define common components in partial templates (e.g., `_header.tmpl`) and reuse them across your prompts.
16-   **Prompt Arguments**: All template variables are automatically exposed as MCP prompt arguments, allowing dynamic input from clients.
17-   **Hot-Reload**: Automatically detects changes to your prompt files and reloads them without restarting the server.
18-   **Rich CLI**: A modern command-line interface to list, validate, and render templates for easy development and testing.
19-   **Smart Argument Handling**:
20    -   Automatically parses JSON arguments (booleans, numbers, arrays, objects).
21    -   Injects environment variables as fallbacks for template arguments.
22-   **Containerized**: Full Docker support for easy deployment and integration.
23 
24## Getting Started
25 
26### 1. Installation
27 
28Install using Go:
29```bash
30go install github.com/vasayxtx/mcp-prompt-engine@latest
31```
32(For other methods like Docker or pre-built binaries, see the [Installation section](#installation) below.)
33 
34### 2. Create a Prompt
35 
36Create a `prompts` directory and add a template file. Let's create a prompt to help write a Git commit message.
37 
38First, create a reusable partial named `prompts/_git_commit_role.tmpl`:
39 
40    ```go
41    {{ define "_git_commit_role" }}
42    You are an expert programmer specializing in writing clear, concise, and conventional Git commit messages.
43    Commit message must strictly follow the Conventional Commits specification.
44 
45    The final commit message you generate must be formatted exactly as follows:
46 
47    ```
48    <type>: A brief, imperative-tense summary of changes
49 
50    [Optional longer description, explaining the "why" of the change. Use dash points for clarity.]
51    ```
52    {{ if .type -}}
53    Use {{.type}} as a type.
54    {{ end }}
55    {{ end }}
56    ```
57 
58Now, create a main prompt `prompts/git_stage_commit.tmpl` that uses this partial:
59    ```go
60    {{- /* Commit currently staged changes */ -}}
61 
62    {{- template "_git_commit_role" . -}}
63 
64    Your task is to commit all currently staged changes.
65    To understand the context, analyze the staged code using the command: `git diff --staged`
66    Based on that analysis, commit staged changes using a suitable commit message.
67    ```
68 
69### 3. Validate Your Prompt
70 
71Validate your prompt to ensure it has no syntax errors:
72```bash
73mcp-prompt-engine validate git_stage_commit
74✓ git_stage_commit.tmpl - Valid
75```
76 
77### 4. Connect MCP Server to Your Client
78 
79Add MCP Server to your MCP client. See [Connecting to Clients](#connecting-to-clients) for configuration examples.
80 
81### 5. Use Your Prompt
82 
83Your `git_stage_commit` prompt will now be available in your client!
84 
85For 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.
86 
87In 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.
88 
89---
90 
91## Installation
92 
93### Pre-built Binaries
94 
95Download the latest release for your OS from the [GitHub Releases page](https://github.com/vasayxtx/mcp-prompt-engine/releases).
96 
97### Build from Source
98 
99```bash
100git clone https://github.com/vasayxtx/mcp-prompt-engine.git
101cd mcp-prompt-engine
102make build
103```
104 
105### Docker
106 
107A pre-built Docker image is available. Mount your local `prompts` and `logs` directories to the container.
108 
109```bash
110# Pull and run the pre-built image from GHCR
111docker run -i --rm \
112  -v /path/to/your/prompts:/app/prompts:ro \
113  -v /path/to/your/logs:/app/logs \
114  ghcr.io/vasayxtx/mcp-prompt-engine
115```
116 
117You can also build the image locally with `make docker-build`.
118 
119---
120 
121## Usage
122 
123### Creating Prompt Templates
124 
125Create a directory to store your prompt templates. Each template should be a `.tmpl` file using Go's [text/template](https://pkg.go.dev/text/template) syntax with the following format:
126 
127```go
128{{/* Brief description of the prompt */}}
129Your prompt text here with {{.template_variable}} placeholders.
130```
131 
132The first line comment (`{{/* description */}}`) is used as the prompt description, and the rest of the file is the prompt template.
133 
134Partial templates should be prefixed with an underscore (e.g., `_header.tmpl`) and can be included in other templates using `{{template "partial_name" .}}`.
135 
136### Template Syntax
137 
138The server uses Go's `text/template` engine, which provides powerful templating capabilities:
139 
140- **Variables**: `{{.variable_name}}` - Access template variables
141- **Built-in variables**:
142    - `{{.date}}` - Current date and time
143- **Conditionals**: `{{if .condition}}...{{end}}`, `{{if .condition}}...{{else}}...{{end}}`
144- **Logical operators**: `{{if and .condition1 .condition2}}...{{end}}`, `{{if or .condition1 .condition2}}...{{end}}`
145- **Loops**: `{{range .items}}...{{end}}`
146- **Template inclusion**: `{{template "partial_name" .}}` or `{{template "partial_name" dict "key" "value"}}`
147 
148See the [Go text/template documentation](https://pkg.go.dev/text/template) for more details on syntax and features.
149 
150### JSON Argument Parsing
151 
152The server automatically parses argument values as JSON when possible, enabling rich data types in templates:
153 
154- **Booleans**: `true`, `false` → Go boolean values
155- **Numbers**: `42`, `3.14` → Go numeric values
156- **Arrays**: `["item1", "item2"]` → Go slices for use with `{{range}}`
157- **Objects**: `{"key": "value"}` → Go maps for structured data
158- **Strings**: Invalid JSON falls back to string values
159 
160This allows for advanced template operations like:
161```go
162{{range .items}}Item: {{.}}{{end}}
163{{if .enabled}}Feature is enabled{{end}}
164{{.config.timeout}} seconds
165```
166 
167To disable JSON parsing and treat all arguments as strings, use the `--disable-json-args` flag for the `serve` and `render` commands.
168 
169### CLI Commands
170 
171The CLI is your main tool for managing and testing templates.
172By default, it looks for templates in the `./prompts` directory, but you can specify a different directory with the `--prompts` flag.
173 
174**1. List Templates**
175```bash
176# See a simple list of available prompts
177mcp-prompt-engine list
178 
179# See a detailed view with descriptions and variables
180mcp-prompt-engine list --verbose
181```
182 
183**2. Render a Template**
184 
185Render a prompt directly in your terminal, providing arguments with the `-a` or `--arg` flag.
186It 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}}`.
187 
188```bash
189# Render the git commit prompt, providing the 'type' variable
190mcp-prompt-engine render git_stage_commit --arg type=feat
191```
192 
193**3. Validate Templates**
194 
195Check all your templates for syntax errors. The command will return an error if any template is invalid.
196```bash
197# Validate all templates in the directory
198mcp-prompt-engine validate
199 
200# Validate a single template
201mcp-prompt-engine validate git_stage_commit
202```
203 
204**4. Start the Server**
205 
206Run the MCP server to make your prompts available to clients.
207```bash
208# Run with default settings (looks for ./prompts)
209mcp-prompt-engine serve
210 
211# Specify a different prompts directory and a log file
212mcp-prompt-engine --prompts /path/to/prompts serve --log-file ./server.log
213```
214 
215---
216 
217## Connecting to Clients
218 
219To use this engine with any client that supports MCP Prompts, add a new entry to its MCP servers configuration.
220 
221Global configuration locations (MacOS):
222- Claude Code: `~/.claude.json` (`mcpServers` section)
223- Claude Desktop: `~/Library/Application\ Support/Claude/claude_desktop_config.json` (`mcpServers` section)
224- Gemini CLI: `~/.gemini/settings.json` (`mcpServers` section)
225 
226**Example for a local binary:**
227```json
228{
229  "prompts": {
230    "command": "/path/to/your/mcp-prompt-engine",
231    "args": [
232      "--prompts", "/path/to/your/prompts",
233      "serve",
234      "--quiet"
235    ]
236  }
237}
238```
239 
240**Example for Docker:**
241```json
242{
243  "mcp-prompt-engine-docker": {
244    "command": "docker",
245    "args": [
246      "run", "-i", "--rm",
247      "-v", "/path/to/your/prompts:/app/prompts:ro",
248      "-v", "/path/to/your/logs:/app/logs",
249      "ghcr.io/vasayxtx/mcp-prompt-engine"
250    ]
251  }
252}
253```
254 
255## License
256 
257This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
258