diff options
Diffstat (limited to 'docs/mcp-managing-prompts.md')
| -rw-r--r-- | docs/mcp-managing-prompts.md | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/docs/mcp-managing-prompts.md b/docs/mcp-managing-prompts.md new file mode 100644 index 0000000..282564a --- /dev/null +++ b/docs/mcp-managing-prompts.md @@ -0,0 +1,324 @@ +# Managing MCP Prompts + +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/share/hexai/prompts/default.jsonl` (built-in, auto-regenerated) +- **Custom prompts**: `~/.local/share/hexai/prompts/user.jsonl` (your prompts) +- **Backups**: `~/.local/share/hexai/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/share/hexai/prompts/user.jsonl + +# Or with nano +nano ~/.local/share/hexai/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/share/hexai/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/share/hexai/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/share/hexai/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/share/hexai/prompts/backups/user.jsonl.20260210-193422 \ + ~/.local/share/hexai/prompts/user.jsonl +``` + +### Import a Prompt +```bash +# From a JSON file +jq -c . imported-prompt.json >> ~/.local/share/hexai/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/share/hexai/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/share/hexai/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/share/hexai/prompts/default.jsonl # Built-in +wc -l ~/.local/share/hexai/prompts/user.jsonl # Custom +``` + +## 🛠️ Troubleshooting + +### Invalid JSON +```bash +# Check specific file +jq empty ~/.local/share/hexai/prompts/user.jsonl +``` + +### Prompt Not Appearing +```bash +# Check MCP server logs +tail -f ~/.local/state/hexai/hexai-mcp-server.log + +# Verify file exists +cat ~/.local/share/hexai/prompts/user.jsonl | jq . +``` + +### Duplicate Prompt Names +Prompt names must be unique. If you have duplicates: +```bash +# List all prompt names +cat ~/.local/share/hexai/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/share/hexai/prompts/default.jsonl ~/backup/ + +# Delete and let server recreate +rm ~/.local/share/hexai/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) |