Claude Custom Prompts Server

Features

• Easy integration with Claude using MCP

• Define custom prompt templates using Markdown files

• Support for prompt arguments with validation

• Organized prompt categories for better management

• Multiple transport options (SSE and STDIO)

• Special context placeholders for accessing conversation history

• Support for prompt chains to break complex tasks into steps

• Distributed prompts configuration with category-specific files

Quick Start

Prerequisites

• Node.js v16 or higher

• npm or yarn

Installation

Basic Usage

Documentation

• [Installation Guide](server/docs/installation-guide.md) - Detailed setup instructions and configuration

• [Prompt Format Guide](server/docs/prompt-format-guide.md) - How to create and format prompt templates

• [Chain Execution Guide](server/docs/chain-execution-guide.md) - Creating and using prompt chains

• [Prompt Management](server/docs/prompt-management.md) - Managing prompts and categories

• [Architecture](server/docs/architecture.md) - System architecture and internals

• [API Endpoints Reference](server/docs/api-endpoints-reference.md) - Available API endpoints

• [Contributing Guide](server/docs/contributing.md) - How to contribute to this project

TODO

• Add functionality to modify the prompt library with different tool commands directly within the MCP client

• Add more comprehensive testing

• Create a simple web UI for managing prompts

License

Working Directory Considerations

How the Server Uses Working Directory

• The server uses `process.cwd()` to determine its working directory

• All file paths in the code are constructed relative to this directory using `path.join(__dirname, "..", ...)`

• Key files that must be accessible from the working directory: - `config.json` - Server configuration - `promptsConfig.json` - Main prompt configuration and category imports - `prompts/` directory - Contains all category folders and prompt template files - `server.log` - Log file (created automatically)

Setting the Working Directory

• When running the server directly, the working directory is the directory from which you run the command

• When using Claude Desktop, the working directory is set by the `cwd` parameter in the configuration

• Always use absolute paths for the `cwd` parameter to avoid confusion

• On Windows, use backslashes (`\\`) in the path to follow Windows conventions, making sure to escape them properly in JSON files (double backslashes)

Common Working Directory Issues

• If the server can't find configuration files or prompt files, the working directory is likely incorrect

• The server logs its working directory at startup - check this to verify it's what you expect

• If using relative paths, be aware that they're relative to the working directory, not the script location

Using Built-in Commands

• **process_slash_command**: Processes slash commands that trigger prompt templates with optional arguments ``` /command_name argument1 argument2 ```

• **listprompts**: Displays a formatted list of all available commands and their usage ``` /listprompts ```

Configuration

1. `config.json` - Server configuration (created automatically if not present)

2. `promptsConfig.json` - Main configuration for prompts categories and imports

Server Configuration (config.json)

Prompts Configuration (promptsConfig.json)

Category-Specific Prompt Files

Creating Custom Prompts

Adding a New Prompt to an Existing Category

1. Create a new markdown file in the appropriate category folder (e.g., `prompts/general/my_prompt.md`)

2. Add the prompt template to the file using markdown format

3. Register the prompt in the category's prompts.json file (e.g., `prompts/general/prompts.json`)

Creating a New Category

1. Create a new folder in the `prompts` directory for your category (e.g., `prompts/mycategory/`)

2. Create a `prompts.json` file in the new category folder with the following structure: ```json { "prompts": [] } ```

3. Add your category to the `categories` array in `promptsConfig.json`

4. Add the path to your category's prompts.json file to the `imports` array in `promptsConfig.json`

Special Placeholders

• `{{previous_message}}` - Inserts a prompt asking Claude to reference the previous message in its context - This leverages Claude's built-in conversation memory rather than trying to track messages server-side - The actual message content is never accessed by the server, only by Claude

Example Template

Prompt Chains

Creating a Chain Prompt

• The prompt ID to execute

• A descriptive name for the step

• Input mapping (how chain inputs map to prompt inputs)

• Output mapping (how prompt outputs map to chain variables)

How Chain Prompts Work

1. When a chain prompt is executed, the server: - Processes the initial user message template with the provided arguments - Executes each step in sequence, passing inputs and collecting outputs - Maps variables between steps according to the input/output mappings - Returns the final result to Claude

2. Input and output mappings use a simple key-value format: - `prompt_input: chain_input` means "pass the chain's input named 'chain_input' to the prompt's input named 'prompt_input'" - `prompt_output: chain_variable` means "store the prompt's output named 'prompt_output' in the chain variable named 'chain_variable'"

3. Chain variables persist throughout the execution of the chain and can be used by any subsequent step

Debugging Chain Prompts

1. Check that all prompt IDs in the chain steps exist in your category prompts.json files

2. Verify that the input and output mappings match the expected inputs and outputs of each prompt

3. Test each individual prompt in the chain to ensure it works correctly on its own

4. Look for error messages in the server logs related to chain execution

5. Try running the chain with simple inputs to isolate any issues

Example Chain Prompt

Claude Desktop Configuration

1. Locate your Claude Desktop configuration file: - Windows: `%APPDATA%\Claude\claude_desktop_config.json` (Typically `C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json`) - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

2. Add the following to your `claude_desktop_config.json` file:

• Replace `C:\\path\\to\\claude-prompts\\server` with the absolute path to your server directory

• For Windows paths, use double backslashes (`\\`) to properly escape them in JSON

• The `cwd` parameter is critical as it sets the working directory for the server

• Without the correct `cwd`, the server won't be able to find prompt files, config files, or log files

• All file paths in the server code are resolved relative to this working directory

• Set `autostart` to `true` to have the server start automatically when Claude Desktop launches

• You can specify environment variables like `PORT` in the `env` object

1. You can also specify the transport method by adding it to the args array:

2. After saving the configuration, restart Claude Desktop to apply the changes.

Using in Claude Desktop

• `>>command_name argument1 argument2` - For regular prompts

• `>>chain_command_name argument1 argument2` - For chain prompts

Troubleshooting

Connection Issues

• Ensure the server is running on the expected port

• Check that the paths in your Claude Desktop config.json are correct

• Verify that the `cwd` parameter points to the correct server directory

• Make sure the `promptsConfig.json` file and category prompts.json files exist and are valid JSON

JSON Parsing Errors

• Check the format of your JSON files

• Ensure all JSON files are properly formatted with no trailing commas

• Validate your JSON using a JSON validator

File Path Issues

• If you see errors about files not being found, check your `cwd` parameter

• The server logs its working directory at startup - verify it matches your expectations

• All file paths in the server are resolved relative to the working directory

• Use absolute paths in the `cwd` parameter to avoid confusion

• Windows paths should use double backslashes (`\\`) in JSON configuration files to properly escape the backslash character

Checking Server Status

• The server logs its status to the console and to a log file (`server.log` in the server directory)

• If using Claude Desktop, check the Claude Desktop logs for server startup messages

• You can manually run the server to see if it starts correctly: ```bash cd path/to/claude-prompts/server node dist/index.js ```

• Look for messages like "Server initialized successfully" and "All prompts loaded successfully"

• If you see error messages, they can help identify the specific issue

Verifying Node.js Installation

• Ensure Node.js is installed and accessible: ```bash node --version npm --version ```

• Both commands should return version numbers without errors

Checking Logs

• On Windows, check the log file at `C:\\path\\to\\claude-prompts\\server\\server.log`

• On macOS, check the log file at `/path/to/claude-prompts/server/server.log`

• The log file contains detailed information about server initialization, prompt loading, and any errors

Contributing

License

Usage

• `>>listprompts` or `/listprompts` - List all available commands

• `>>command_name [arguments]` or `/command_name [arguments]` - Execute a specific command

Available Tools

Prompt Management Tools

• **listprompts**: Displays a formatted list of all available commands and their usage ``` /listprompts [filter_text] ``` - Optional `filter_text` parameter to show only commands matching the filter

• **update_prompt**: Creates or updates a prompt ``` POST /api/v1/tools/update_prompt ``` Parameters: - `id` (required): Unique identifier for the prompt - `name` (required): Display name for the prompt - `category` (required): Category this prompt belongs to - `description` (required): Description of the prompt - `systemMessage` (optional): System message for the prompt - `userMessageTemplate` (required): Template for generating the user message - `arguments` (required): Array of argument objects with name, description, and required properties - `isChain` (optional): Whether this prompt is a chain of prompts - `chainSteps` (optional): Array of steps for chain prompts - `restartServer` (optional): Whether to restart the server after updating the prompt

• **delete_prompt**: Deletes a prompt ``` POST /api/v1/tools/delete_prompt ``` Parameters: - `id` (required): Unique identifier for the prompt to delete - `restartServer` (optional): Whether to restart the server after deleting the prompt

• **modify_prompt_section**: Modifies a specific section of a prompt ``` POST /api/v1/tools/modify_prompt_section ``` Parameters: - `id` (required): Unique identifier of the prompt to modify - `section_name` (required): Name of the section to modify (e.g., "title", "description", "System Message", "User Message Template") - `new_content` (required): New content for the specified section - `restartServer` (optional): Whether to restart the server after modifying the prompt section

Server Management Tools

• **reload_prompts**: Refreshes all prompts and optionally restarts the server ``` POST /api/v1/tools/reload_prompts ``` Parameters: - `restart` (optional): Whether to restart the server after reloading prompts (boolean) - `reason` (optional): Reason for reloading/restarting the server

Category Management Tools

• **create_category**: Creates a new prompt category ``` POST /api/v1/tools/create_category ``` Parameters: - `id` (required): Unique identifier for the category - `name` (required): Display name for the category - `description` (required): Description of the category

Command Processing Tools

• **process_slash_command**: Processes slash commands that trigger prompt templates ``` POST /api/v1/tools/process_slash_command ``` Parameters: - `command` (required): The command to process (e.g., "/content_analysis Hello world")

Activating Tools in Claude

• **listprompts**: List all available commands ``` >>listprompts ``` or ``` /listprompts ```

• **reload_prompts**: Reload all prompts and optionally restart the server ``` >>reload_prompts restart=true reason="Updated configuration" ```

• **update_prompt**: Create or update a prompt

• **delete_prompt**: Delete a prompt

• **modify_prompt_section**: Modify a specific section of a prompt

• **Executing a prompt**: ``` >>prompt_name argument1=value1 argument2=value2 ``` or ``` /prompt_name argument1=value1 argument2=value2 ```

• **Using JSON format for arguments**: ``` >>prompt_name {"argument1": "value1", "argument2": "value2"} ```

Reloading prompts:

Reloading prompts and restarting the server:

API Usage Examples

Creating a new prompt:

Deleting a prompt:

Reloading prompts: