sort of a gui
This commit is contained in:
senstella
340
src/prompt.txt
Normal file
340
src/prompt.txt
Normal file
@@ -0,0 +1,340 @@
|
||||
# Fossil MCP Server - Complete User Guide
|
||||
|
||||
## Overview
|
||||
Fossil is an MCP server that provides git-like version control for code artifacts with fuzzy pattern matching. It enables precise, incremental code editing without rewriting entire files.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### What is a Fossil?
|
||||
A "fossil" is a versioned code artifact stored in memory. Each fossil has:
|
||||
- A unique ID (e.g., `"main.py"`, `"config-v2.json"`)
|
||||
- Full version history (like git commits)
|
||||
- Support for fuzzy pattern matching during edits
|
||||
|
||||
### Why Fuzzy Matching?
|
||||
Traditional string replacement requires exact character-by-character matches. Fuzzy matching allows you to:
|
||||
- Ignore whitespace differences (spaces, tabs, blank lines)
|
||||
- Match patterns even if formatting changed slightly
|
||||
- Target code sections without knowing exact formatting
|
||||
|
||||
## Available Functions
|
||||
|
||||
### 1. `create_fossil`
|
||||
Creates a new fossil with initial content.
|
||||
|
||||
**Parameters:**
|
||||
- `id` (string, required): Unique identifier for the fossil
|
||||
- Use descriptive names like `"api-handler.py"` or `"utils-v1.js"`
|
||||
- This ID is used to reference the fossil in all other operations
|
||||
- `content` (string, required): Initial code/text content
|
||||
- Can be any text content (code, JSON, markdown, etc.)
|
||||
|
||||
**Example:**
|
||||
```
|
||||
create_fossil(
|
||||
id: "calculator.py",
|
||||
content: "def add(a, b):\
|
||||
return a + b"
|
||||
)
|
||||
```
|
||||
|
||||
**Returns:** Success message with the fossil ID
|
||||
|
||||
---
|
||||
|
||||
### 2. `list_fossils`
|
||||
Lists all currently managed fossils.
|
||||
|
||||
**Parameters:** None
|
||||
|
||||
**Returns:** Array of fossil IDs currently in memory
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
Current fossils: main.py, config.json, utils.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. `fuzzy_edit`
|
||||
Replaces a section of code using fuzzy pattern matching. This is the primary editing function.
|
||||
|
||||
**Parameters:**
|
||||
- `id` (string, required): The fossil ID to edit
|
||||
- `start_pattern` (string, required): Pattern marking the START of the section to replace
|
||||
- Should be distinctive enough to find the right location
|
||||
- Doesn't need exact whitespace - fuzzy matching handles variations
|
||||
- **Best practice:** Use complete lines when possible
|
||||
- `end_pattern` (string, required): Pattern marking the END of the section to replace
|
||||
- The matched section includes both start and end patterns
|
||||
- **Best practice:** Use complete lines when possible
|
||||
- `replacement` (string, required): New code that replaces the matched section
|
||||
- Empty string `""` performs deletion (equivalent to `delete_fossil` functionality)
|
||||
|
||||
**How it works:**
|
||||
1. Finds the first occurrence of `start_pattern` in the file
|
||||
2. Finds the first occurrence of `end_pattern` after the start
|
||||
3. Replaces everything from start to end (inclusive) with `replacement`
|
||||
|
||||
**Important Notes:**
|
||||
- Patterns are fuzzy matched - whitespace differences are tolerated
|
||||
- Both start and end patterns are INCLUDED in the replacement
|
||||
- If you want to keep the start/end patterns, include them in the replacement
|
||||
- Empty replacement = deletion
|
||||
|
||||
**Example 1 - Simple replacement:**
|
||||
```
|
||||
# Original code:
|
||||
def greet(name):
|
||||
return "Hello"
|
||||
|
||||
# Edit:
|
||||
fuzzy_edit(
|
||||
id: "main.py",
|
||||
start_pattern: "def greet(name):",
|
||||
end_pattern: "return \\"Hello\\"",
|
||||
replacement: "def greet(name):\
|
||||
return f\\"Hello, {name}!\\""
|
||||
)
|
||||
|
||||
# Result:
|
||||
def greet(name):
|
||||
return f"Hello, {name}!"
|
||||
```
|
||||
|
||||
**Example 2 - Adding a parameter:**
|
||||
```
|
||||
# Original:
|
||||
def calculate(x, y):
|
||||
|
||||
# Edit:
|
||||
fuzzy_edit(
|
||||
id: "calc.py",
|
||||
start_pattern: "def calculate(x, y):",
|
||||
end_pattern: "def calculate(x, y):",
|
||||
replacement: "def calculate(x, y, operation='add'):"
|
||||
)
|
||||
|
||||
# Result:
|
||||
def calculate(x, y, operation='add'):
|
||||
```
|
||||
|
||||
**Example 3 - Deletion (empty replacement):**
|
||||
```
|
||||
fuzzy_edit(
|
||||
id: "main.py",
|
||||
start_pattern: "\# TODO: remove this",
|
||||
end_pattern: "\# End of temporary code",
|
||||
replacement: ""
|
||||
)
|
||||
```
|
||||
|
||||
**Example 4 - Append to end of file:**
|
||||
```
|
||||
# Target the last line and rewrite from there
|
||||
fuzzy_edit(
|
||||
id: "main.py",
|
||||
start_pattern: "if __name__ == '__main__':",
|
||||
end_pattern: " main()",
|
||||
replacement: "if __name__ == '__main__':\
|
||||
main()\
|
||||
\
|
||||
def new_function():\
|
||||
pass"
|
||||
)
|
||||
```
|
||||
|
||||
**Returns:**
|
||||
- Success message with a clean diff showing what changed
|
||||
- The diff uses `@@ line numbers @@` format
|
||||
- `+` indicates added lines, `-` indicates removed lines
|
||||
|
||||
---
|
||||
|
||||
### 4. `get_version`
|
||||
Retrieves a specific version of a fossil without modifying it. Use this to preview history.
|
||||
|
||||
**Parameters:**
|
||||
- `id` (string, required): The fossil ID
|
||||
- `version` (integer, optional): Version index to retrieve
|
||||
- `0` = initial version (first creation)
|
||||
- `1, 2, 3...` = subsequent versions (counting from start)
|
||||
- `-1` = latest version (default)
|
||||
- `-2` = previous version
|
||||
- `-3` = two versions ago, etc.
|
||||
|
||||
**Example:**
|
||||
```
|
||||
get_version(id: "main.py", version: 0) # See original
|
||||
get_version(id: "main.py", version: -1) # See latest
|
||||
get_version(id: "main.py", version: -2) # See previous
|
||||
```
|
||||
|
||||
**Returns:** The complete content of the fossil at that version
|
||||
|
||||
---
|
||||
|
||||
### 5. `revert`
|
||||
Undoes recent edits by rolling back to a previous version. This actually modifies the fossil.
|
||||
|
||||
**Parameters:**
|
||||
- `id` (string, required): The fossil ID to revert
|
||||
- `steps` (integer, optional): Number of edits to undo (default: 1)
|
||||
- `steps: 1` = undo last edit
|
||||
- `steps: 2` = undo last 2 edits
|
||||
- `steps: 5` = undo last 5 edits
|
||||
|
||||
**Example:**
|
||||
```
|
||||
revert(id: "main.py", steps: 1) # Undo last edit
|
||||
revert(id: "main.py", steps: 3) # Undo last 3 edits
|
||||
```
|
||||
|
||||
**Returns:**
|
||||
- Success message with diff showing what was reverted
|
||||
- The fossil is now at the earlier version
|
||||
|
||||
**Use cases:**
|
||||
- "Oops, that edit broke something" → `revert(steps: 1)`
|
||||
- "Let's try a different approach" → `revert()` then make new edit
|
||||
- "Go back to working version" → `revert(steps: 5)`
|
||||
|
||||
---
|
||||
|
||||
### 6. `delete_fossil`
|
||||
Permanently deletes a fossil and all its history.
|
||||
|
||||
**Parameters:**
|
||||
- `id` (string, required): The fossil ID to delete
|
||||
|
||||
**Returns:** Success confirmation
|
||||
|
||||
**Warning:** This cannot be undone! The entire fossil and its version history are removed from memory.
|
||||
|
||||
---
|
||||
|
||||
## Workflow Patterns
|
||||
|
||||
### Pattern 1: Create and Iterate
|
||||
```
|
||||
1. create_fossil(id: "app.py", content: "initial code")
|
||||
2. fuzzy_edit(id: "app.py", ...) # Add feature
|
||||
3. fuzzy_edit(id: "app.py", ...) # Fix bug
|
||||
4. fuzzy_edit(id: "app.py", ...) # Refactor
|
||||
5. If something breaks: revert(id: "app.py", steps: 1)
|
||||
```
|
||||
|
||||
### Pattern 2: Surgical Edits
|
||||
```
|
||||
# Only change what needs changing
|
||||
fuzzy_edit(
|
||||
start_pattern: "def problematic_function",
|
||||
end_pattern: "return result",
|
||||
replacement: "def fixed_function...\
|
||||
return new_result"
|
||||
)
|
||||
```
|
||||
|
||||
### Pattern 3: Exploration with Safety Net
|
||||
```
|
||||
1. get_version(id: "main.py", version: -1) # Check current state
|
||||
2. fuzzy_edit(...) # Try experimental change
|
||||
3. Test it mentally/logically
|
||||
4. If it works: continue
|
||||
5. If it breaks: revert(steps: 1)
|
||||
```
|
||||
|
||||
### Pattern 4: Append Pattern
|
||||
```
|
||||
# To add to end of file, target the last line(s)
|
||||
fuzzy_edit(
|
||||
start_pattern: "last_line_or_function",
|
||||
end_pattern: "last_line_or_function",
|
||||
replacement: "last_line_or_function\
|
||||
\
|
||||
new_content_here"
|
||||
)
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ DO:
|
||||
- Use distinctive patterns that uniquely identify the location
|
||||
- Include complete lines in patterns when possible
|
||||
- Use `get_version` to check current state before editing
|
||||
- Use `revert` freely - it's there to help you experiment
|
||||
- Keep fossil IDs descriptive and clear
|
||||
- Remember that both start and end patterns are INCLUDED in the match
|
||||
|
||||
### ❌ DON'T:
|
||||
- Use overly generic patterns that might match multiple locations
|
||||
- Worry about exact whitespace in patterns - fuzzy matching handles it
|
||||
- Rewrite entire files - use targeted edits instead
|
||||
- Forget that the start/end patterns get replaced too
|
||||
- Use patterns that are too short (might match wrong location)
|
||||
|
||||
## Advanced Tips
|
||||
|
||||
### Tip 1: Multi-line Patterns
|
||||
Patterns can span multiple lines. Use `\
|
||||
` for newlines:
|
||||
```
|
||||
start_pattern: "class MyClass:\
|
||||
def __init__"
|
||||
```
|
||||
|
||||
### Tip 2: Partial Line Matching
|
||||
You don't need the entire line, just enough to be distinctive:
|
||||
```
|
||||
start_pattern: "def calculate(" # Matches any line starting with this
|
||||
```
|
||||
|
||||
### Tip 3: Pattern Selection Strategy
|
||||
- **Too specific:** Might not match due to whitespace differences
|
||||
- **Too generic:** Might match wrong location
|
||||
- **Just right:** Distinctive enough to be unique, fuzzy enough to be flexible
|
||||
|
||||
### Tip 4: When Edits Fail
|
||||
If fuzzy matching can't find your pattern:
|
||||
1. Use `get_version` to see the current actual content
|
||||
2. Check if your pattern actually exists in the file
|
||||
3. Try a more distinctive or simpler pattern
|
||||
4. Remember: patterns are case-sensitive for content (but whitespace-flexible)
|
||||
|
||||
## Error Handling
|
||||
|
||||
If a fuzzy match fails, you'll get an error message. Common causes:
|
||||
- Pattern doesn't exist in the file
|
||||
- Pattern exists multiple times (uses first match)
|
||||
- Pattern text doesn't match actual content
|
||||
|
||||
**Solution:** Use `get_version` to inspect the current content and adjust your pattern.
|
||||
|
||||
## Comparison to Traditional Artifacts
|
||||
|
||||
### Traditional Artifacts:
|
||||
- ❌ Full file rewrites every edit
|
||||
- ❌ Exact string matching (brittle)
|
||||
- ❌ No version history
|
||||
- ❌ No undo capability
|
||||
- ❌ Token-heavy
|
||||
|
||||
### Fossil System:
|
||||
- ✅ Surgical edits to specific sections
|
||||
- ✅ Fuzzy pattern matching (robust)
|
||||
- ✅ Full version history
|
||||
- ✅ Git-like revert functionality
|
||||
- ✅ Token-efficient
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Create:** `create_fossil(id, content)`
|
||||
**Edit:** `fuzzy_edit(id, start_pattern, end_pattern, replacement)`
|
||||
**Undo:** `revert(id, steps)`
|
||||
**View:** `get_version(id, version)`
|
||||
**List:** `list_fossils()`
|
||||
**Delete:** `delete_fossil(id)`
|
||||
|
||||
---
|
||||
|
||||
Remember: Fossil enables **iterative, precise code editing** with full version control. Use fuzzy patterns to target sections, make incremental changes, and revert freely when needed. It's designed to make LLM-assisted coding efficient and safe.
|
||||
Reference in New Issue
Block a user