Prompt Serve
MCP server: Prompt Serve
Installation
npx prompt-serveAsk AI about Prompt Serve
Powered by Claude Β· Grounded in docs
I know everything about Prompt Serve. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
PromptServe - File based prompt management for MCP
A Model Context Protocol (MCP) server designed for managing, organizing, and serving AI prompts. PromptServe follows a "Prompts as Code" paradigm where prompts are stored in text files with frontmatter metadata.
Features
- Centralized Prompt Management: Store and organize your prompts and reusable workflows in one location.
- Prompt as Code: Use Markdown with frontmatter for human-readable and AI friendly, version-control compatible prompt definitions.
- Dynamic Parameters: Use dynamic parameters in your prompts and fill them in at runtime.
- Template Parts: Use template parts to build more complex prompts from reusable components.
- Automatic Detection of New Prompts: Automatically detects when new prompt files are added via periodic scanning.
Dependencies
- TypeScript
- MCP SDK (@modelcontextprotocol/sdk)
- Zod (for schema validation)
- gray-matter (for frontmatter parsing)
Setup
-
Install dependencies:
npm install -
Build the project:
npm run build
Client Configurations
Claude Desktop
- Add the following to
~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"prompt-serve": {
"command": "node",
"args": ["/path/to/prompt-serve/dist/index.js"],
"env": {
"PROMPTS_DIR": "/path/to/your/prompts"
}
}
}
}
- Replace
/path/to/prompt-serve/dist/index.jsand/path/to/your/promptswith the correct absolute paths on your system. - After saving changes to
claude_desktop_config.json, you will need to restart Claude Desktop for the new configuration to be loaded.
Cursor / RooCode / GitHub Copilot (via PromptLink Extension)
To use PromptServe prompts with Cursor, RooCode, or GitHub Copilot, you need the PromptLink VS Code Extension. This extension acts as a bridge between MCP servers (like PromptServe) and these tools.
-
Install the PromptLink Extension from the VS Code Marketplace.
-
Configure PromptLink in your VS Code
settings.jsonto connect to your running PromptServe instance. Add an entry to thepromptLink.serversarray:"promptLink.servers": [ { "name": "PromptServe", "command": "node", "args": [ "/path/to/prompt-serve/dist/index.js" ], "env": { "PROMPTS_DIR": "/path/to/your/prompts" } } ], -
Replace
/path/to/prompt-serve/dist/index.jsand/path/to/your/promptswith the correct absolute paths on your system. -
Once configured, you can use the PromptLink command (default:
Cmd+Shift+A/Ctrl+Shift+A) to select a prompt from PromptServe and send it to Cursor, RooCode, or Copilot.
Configuration
Prompt Serve uses environment variables for configuration:
PROMPTS_DIR(Required): The absolute path to the directory containing your.mdprompt files.PROMPT_SCAN_INTERVAL_MS(Optional): The interval, in milliseconds, at which the server scans thePROMPTS_DIRfor new files. Defaults to10000(10 seconds) if not set or invalid.
Development
- Use
npm run devto run in watch mode during development (compiles TypeScript on change). - Use
npm run cleanto clean the build directory.
Project Structure
prompt-serve/
βββ src/ # Source code
βββ dist/ # Compiled JavaScript (generated)
βββ example-prompts/ # Example prompt files
βββ package.json # Project configuration
βββ tsconfig.json # TypeScript configuration
Prompt Files
Prompt files are Markdown files with frontmatter metadata. Example:
---
name: Github PR
description: Generates a PR, git commit message, and provides a code review.
schema:
type: object
properties:
changes:
description: The code changes to review
required: true
issueNumber:
description: The issue number this PR addresses
context:
description: Additional context about the changes
---
Your prompt content here...
Frontmatter Fields
name: The display name for the prompt (can include spaces and special characters). This is the primary identifier shown in MCP clients.description: A description of what the prompt does.schema: (Optional) A JSON schema defining the prompt's parameters.
The server uses the name field from frontmatter as the prompt identifier in the UI, allowing for more user-friendly prompt names with spaces and special characters.
Schema Definition
The schema field uses a simplified schema format to define prompt parameters, based on the Model Context Protocol documentation.
- Properties: Define parameters with their descriptions and requirements.
- Required Fields: Mark required parameters using
required: truein the property definition. - Types: All parameters are handled as strings.
- Descriptions: Each parameter can have a description that will appear in the UI of your AI client.
Example schema:
{
"type": "object",
"properties": {
"changes": {
"description": "The code changes to review",
"required": true
},
"issueNumber": {
"description": "The issue number this PR addresses"
},
"context": {
"description": "Additional context about the changes"
}
}
}
Default Values for Parameters
You can provide default values for optional parameters directly within the prompt template using the || operator. This is useful when you want a fallback value if an optional argument isn't provided by the user.
- Syntax:
${parameterName || 'Your Default Value'}or${parameterName || "Your Default Value"} - Requirement: The parameter (
parameterNamein the example) must be defined as optional (i.e., not haverequired: true) in the prompt's schema. - Quotes: The default value must be enclosed in either single (
') or double (") quotes.
Example:
If you have an optional language parameter, you could use:
Explain this code snippet, assuming it's ${language || 'code'}:
If the user provides a language argument, it will be used. If not, the text "code" will be substituted.
Importing Content (@import) with Template Parts
You can include content from other Markdown files within your prompt directory using the @import directive. This allows you to reuse common sections or structure complex prompts.
Files whose names start with an underscore (e.g., _shared_header.md) are treated as partials. They won't be loaded as standalone prompts by the server but can be included using the @import syntax.
This allows you to build complex prompts from reusable components like building blocks.
Example Prompts
The project includes several example prompts in the example-prompts/ directory:
github-pr.md: Demonstrates a complex prompt with both required (changes) and optional (issueNumber,context) arguments defined in the schema.explain-code.md: Shows a mix of required (code) and optional (language) arguments. It also utilizes the default value syntax (${language || 'code'}) for an optional parameter with a fallback value.random-idea-generator.md: An example of a prompt that requires no arguments (empty schemaproperties).meeting-summary.md: Uses a required argument (notes) and demonstrates the template part import feature by including@_common-formatting.md._common-formatting.md: A partial file (name starts with_) intended to be included in other prompts. It is not loaded as a standalone prompt itself.
These examples showcase various features like:
- Defining required and optional arguments using the schema.
- Using default values for optional arguments (
${arg || 'default'}). - Creating prompts with no arguments.
- Reusing content via template parts (
@_partial.md).
Troubleshooting
Common issues and solutions:
PROMPTS_DIRnot set: Make sure to set thePROMPTS_DIRenvironment variable in your client configuration to the correct path.- New prompts not detected quickly: Detection occurs via periodic scanning. Check the
PROMPT_SCAN_INTERVAL_MSsetting (defaults to 10 seconds). If new files still aren't detected after the interval, check file permissions and ensure the server process is running correctly. - Modifications to existing prompts not reflected: This is the current expected behavior and is a limitation of the current MCP SDK (see PR #247). Changes to existing prompt files require a server restart to be loaded.
Contributing
- Fork the repository.
- Create a feature branch.
- Make your changes.
- Submit a pull request.
Please ensure your changes follow the existing code style and include appropriate documentation.
License
This project is licensed under the GNU General Public License v2.0 or later (GPLv2+). See the LICENSE file for details.
