# Managing MCP Prompts > **⚠️ DEPRECATION NOTICE** > > This MCP server is **EXPERIMENTAL** and **NOT ACTIVELY MAINTAINED**. > > The author currently manages prompts through slash commands and meta-commands > in the hexai agent system, making this MCP server redundant for its original > purpose. This code is kept for potential future enhancements (possibly with > different functionality beyond prompt management), but no guarantees are made > about stability or continued support. > > **This documentation is preserved for reference only.** Quick reference for managing hexai MCP server prompts. ## 🚀 All Management Through MCP Protocol All prompt management is done through the MCP server protocol. Use any MCP client (Claude Code, Cursor, etc.) to: - **Create prompts**: `prompts/create` method - **Update prompts**: `prompts/update` method - **Delete prompts**: `prompts/delete` method - **List prompts**: `prompts/list` method - **Get prompts**: `prompts/get` method **Automatic backups** are created on every operation! ## 📍 Prompt Locations - **Default prompts**: `~/.local/hexai/data/prompts/default.jsonl` (built-in, auto-regenerated) - **Custom prompts**: `~/.local/hexai/data/prompts/user.jsonl` (your prompts) - **Backups**: `~/.local/hexai/data/prompts/backups/` (automatic backups) - **Override directory**: Set `HEXAI_MCP_PROMPTS_DIR` environment variable ## 📝 Method 1: Using MCP Protocol (Recommended) ### List All Prompts Use your MCP client (Claude Code, Cursor) to list prompts, or use the MCP protocol: ```json { "jsonrpc": "2.0", "id": 1, "method": "prompts/list", "params": {} } ``` ### Create a New Prompt ```json { "jsonrpc": "2.0", "id": 2, "method": "prompts/create", "params": { "name": "performance_analysis", "title": "Performance Analysis", "description": "Analyzes code performance", "arguments": [ { "name": "code", "description": "Code to analyze", "required": true } ], "messages": [ { "role": "user", "content": { "type": "text", "text": "Analyze performance:\n{{code}}" } } ], "tags": ["performance", "optimization"] } } ``` ### Update a Prompt ```json { "jsonrpc": "2.0", "id": 3, "method": "prompts/update", "params": { "name": "performance_analysis", "description": "Enhanced performance analysis with profiling" } } ``` ### Delete a Prompt ```json { "jsonrpc": "2.0", "id": 4, "method": "prompts/delete", "params": { "name": "old_prompt" } } ``` **Note**: You can only delete custom prompts from `user.jsonl`, not built-in prompts. ## 📝 Method 2: Direct File Editing (Advanced) ### Edit user.jsonl ```bash # Using your editor $EDITOR ~/.local/hexai/data/prompts/user.jsonl # Or with nano nano ~/.local/hexai/data/prompts/user.jsonl ``` ### Prompt Format (JSONL - one line per prompt) ```json {"name":"prompt_name","title":"Display Title","description":"What it does","arguments":[{"name":"arg1","description":"Argument description","required":true}],"messages":[{"role":"user","content":{"type":"text","text":"Prompt text with {{arg1}}"}}],"tags":["tag1","tag2"],"created":"2026-02-10T18:00:00Z","updated":"2026-02-10T18:00:00Z"} ``` ### Pretty Format (for editing) ```json { "name": "api_design", "title": "Design REST API", "description": "Creates RESTful API endpoint specification", "arguments": [ { "name": "resource", "description": "Resource name (e.g., users, posts)", "required": true } ], "messages": [ { "role": "user", "content": { "type": "text", "text": "Design REST API for: {{resource}}" } } ], "tags": ["api", "rest", "design"], "created": "2026-02-10T18:00:00Z", "updated": "2026-02-10T18:00:00Z" } ``` **To add**: Minify with `jq -c` and append: ```bash jq -c . my-prompt.json >> ~/.local/hexai/data/prompts/user.jsonl ``` ## 📝 Method 3: Programmatic Access (Go) ```go package main import ( "time" "codeberg.org/snonux/hexai/internal/promptstore" ) func main() { dir := "/home/paul/.local/hexai/data/prompts" store, _ := promptstore.NewJSONLStore(dir) prompt := &promptstore.Prompt{ Name: "optimize_query", Title: "Optimize Database Query", Description: "Analyzes and optimizes SQL queries", Arguments: []promptstore.PromptArgument{ { Name: "query", Description: "SQL query to optimize", Required: true, }, }, Messages: []promptstore.PromptMessage{ { Role: "user", Content: promptstore.MessageContent{ Type: "text", Text: "Optimize this query: {{query}}", }, }, }, Tags: []string{"database", "sql", "optimization"}, Created: time.Now(), Updated: time.Now(), } store.Create(prompt) } ``` ## 🔄 When Do Changes Take Effect? ### MCP Server Reloads The MCP server reads prompts from disk on each request, so changes are **immediately available** without restarting the server! ### Client Caching Some MCP clients (like Claude Code, Cursor) may cache the prompt list: - **To refresh**: Restart the client - **Or**: Wait for the client's cache timeout (usually a few minutes) ## 🎯 Common Tasks ### View Automatic Backups ```bash ls -lht ~/.local/hexai/data/prompts/backups/ ``` Output shows timestamped backups (most recent first): ``` -rw-r--r-- 1 paul paul 1.2K Feb 10 19:34 user.jsonl.20260210-193422 -rw-r--r-- 1 paul paul 1.1K Feb 10 19:21 user.jsonl.20260210-192145 ``` ### Restore from Backup (Manual) ```bash # Copy backup to restore cp ~/.local/hexai/data/prompts/backups/user.jsonl.20260210-193422 \ ~/.local/hexai/data/prompts/user.jsonl ``` ### Import a Prompt ```bash # From a JSON file jq -c . imported-prompt.json >> ~/.local/hexai/data/prompts/user.jsonl hexai-prompt validate ``` ### Share Prompts with Team ```bash # Export specific prompts hexai-prompt export my_team_prompt > team-prompts/prompt1.json hexai-prompt export security_checklist > team-prompts/prompt2.json # Commit to git git add team-prompts/ git commit -m "Add team prompts" git push ``` ### Team Members Import ```bash cd team-prompts/ for f in *.json; do jq -c . "$f" >> ~/.local/hexai/data/prompts/user.jsonl done ``` ### Update an Existing Prompt **Method 1**: Use MCP protocol ```json { "method": "prompts/update", "params": { "name": "my_prompt", "title": "Updated Title", "description": "Updated description" } } ``` **Method 2**: Edit user.jsonl directly ```bash $EDITOR ~/.local/hexai/data/prompts/user.jsonl # Find the line with the prompt name and edit it hexai-prompt validate ``` **Method 3**: Use Go program with Update ```go store.Update(prompt) // Updates existing prompt by name ``` ### Count Prompts ```bash wc -l ~/.local/hexai/data/prompts/default.jsonl # Built-in wc -l ~/.local/hexai/data/prompts/user.jsonl # Custom ``` ## 🛠️ Troubleshooting ### Invalid JSON ```bash # Check specific file jq empty ~/.local/hexai/data/prompts/user.jsonl ``` ### Prompt Not Appearing ```bash # Check MCP server logs tail -f ~/.local/hexai/state/hexai-mcp-server.log # Verify file exists cat ~/.local/hexai/data/prompts/user.jsonl | jq . ``` ### Duplicate Prompt Names Prompt names must be unique. If you have duplicates: ```bash # List all prompt names cat ~/.local/hexai/data/prompts/user.jsonl | jq -r .name | sort | uniq -d # Fix: Edit user.jsonl and rename or remove duplicates ``` ### Reset to Defaults ```bash # Backup first cp ~/.local/hexai/data/prompts/default.jsonl ~/backup/ # Delete and let server recreate rm ~/.local/hexai/data/prompts/default.jsonl # Restart MCP server or wait for next request ``` ## 📚 See Also - [MCP Setup Guide](mcp-setup.md) - [Creating Custom Prompts](mcp-prompts.md) - [hexai Configuration](configuration.md)