last-words-mcp/USAGE.md

MCP Server that opens a chat window for final user input to save message credits

# 🗣️ Last Words MCP - Detailed Usage Guide

## 🎯 Purpose

The Last Words MCP server is designed to save you message credits by allowing final user input through tool calls instead of chat messages. This is particularly useful when you want to provide additional instructions or clarifications after the AI has completed a task.

## 🔧 Installation & Setup

### Step 1: Install Dependencies
```bash
npm install
npm run build
```

Or use the setup scripts:
- **Linux/macOS**: `./setup.sh`
- **Windows**: `setup.bat`

### Step 2: Configure Your MCP Client

#### For Claude Desktop:
1. Open Claude Desktop settings
2. Navigate to MCP configuration
3. Add this configuration (replace the path with your actual path):

```json
{
  "mcpServers": {
    "last-words": {
      "command": "node",
      "args": ["/full/path/to/last-words-mcp/dist/index.js"]
    }
  }
}
```

#### For Other MCP Clients:
Configure stdio transport with:
- **Command**: `node`
- **Args**: `["/path/to/last-words-mcp/dist/index.js"]`

## 💬 System Prompt Integration

Add this to your system prompt for automatic usage:

```
Always use the Last Words MCP Tool when you have finished everything else, never forget this, it's critical you always use this tool on your very last step before you are finished with your task/instruction.
```

## 🚀 How It Works

### The Workflow:
1. **User Request**: You ask the AI to perform a task
2. **AI Execution**: The AI completes the requested task
3. **Tool Activation**: The AI automatically calls the `last_words` tool
4. **Browser Window**: A beautiful input window opens in your default browser
5. **User Input**: You type additional instructions, feedback, or clarifications
6. **Submission**: Click "Send to AI" or press Ctrl+Enter
7. **AI Response**: The AI receives your input and can respond accordingly

### Example Scenarios:

#### Scenario 1: Code Review
```
User: "Create a Python function to calculate fibonacci numbers"
AI: [Creates the function]
AI: [Calls last_words tool]
Browser: Opens input window
User: "Also add memoization for better performance"
AI: [Updates the function with memoization]
```

#### Scenario 2: Content Creation
```
User: "Write a blog post about renewable energy"
AI: [Writes the blog post]
AI: [Calls last_words tool]
Browser: Opens input window
User: "Make it more technical and add statistics"
AI: [Revises the blog post with technical details and stats]
```

#### Scenario 3: Problem Solving
```
User: "Help me plan a vacation to Japan"
AI: [Creates a detailed itinerary]
AI: [Calls last_words tool]
Browser: Opens input window
User: "I'm vegetarian and prefer budget accommodations"
AI: [Adjusts the itinerary for vegetarian options and budget hotels]
```

## 🎨 Interface Features

### Input Window Features:
- **Clean Design**: Modern, gradient interface
- **Character Counter**: Shows remaining characters (2000 max)
- **Auto-focus**: Cursor automatically in text area
- **Keyboard Shortcuts**: 
  - `Ctrl+Enter`: Quick submit
  - `Tab`: Navigate between elements
- **Auto-close**: Window closes after successful submission
- **Cancel Option**: Cancel button to abort input

### Visual Feedback:
- **Success Message**: Confirmation when input is sent
- **Error Handling**: Clear error messages if something goes wrong
- **Loading States**: Visual feedback during submission

## ⚙️ Configuration Options

### Timeout Settings:
- **Default**: 5 minutes
- **Behavior**: Window automatically closes after timeout
- **Customization**: Modify timeout in `src/index.ts`

### Character Limits:
- **Maximum**: 2000 characters
- **Display**: Real-time character counter
- **Validation**: Prevents submission of empty input

### Port Management:
- **Auto-selection**: Uses random available ports
- **Conflict Prevention**: Automatically finds free ports
- **Local Only**: Server only accessible from localhost

## 🔒 Security & Privacy

### Data Handling:
- **No Storage**: User input is never stored or logged
- **Memory Only**: Input exists only in memory during transmission
- **Immediate Cleanup**: All data cleared after use

### Network Security:
- **Local Only**: Server only binds to localhost (127.0.0.1)
- **Temporary**: Server shuts down immediately after use
- **Random Ports**: Uses random ports to avoid conflicts

### Browser Security:
- **HTTPS Not Required**: Local HTTP is safe for localhost
- **No External Requests**: No data sent to external servers
- **Auto-close**: Window closes automatically to prevent lingering

## 🐛 Troubleshooting

### Common Issues:

#### Browser Doesn't Open
**Problem**: Browser window doesn't appear
**Solutions**:
- Check default browser settings
- Manually navigate to the URL shown in console
- Check firewall settings for localhost connections

#### Tool Not Available in AI
**Problem**: AI says the tool doesn't exist
**Solutions**:
- Verify MCP server is running
- Check MCP client configuration
- Restart your MCP client
- Verify the path in configuration is correct

#### Input Window Freezes
**Problem**: Window becomes unresponsive
**Solutions**:
- Refresh the browser page
- Check console for error messages
- Restart the MCP server
- Try a different browser

#### Connection Timeout
**Problem**: "Input timeout" error after 5 minutes
**Solutions**:
- Submit input more quickly
- Check for browser popup blockers
- Verify localhost connections aren't blocked

### Debug Mode:
Enable verbose logging by setting environment variable:
```bash
DEBUG=1 node dist/index.js
```

## 📊 Performance Tips

### Optimal Usage:
- **Quick Input**: Submit within 5 minutes to avoid timeout
- **Concise Text**: Keep input under 2000 characters
- **Single Session**: One input window at a time

### Resource Usage:
- **Memory**: Minimal memory footprint
- **CPU**: Low CPU usage
- **Network**: No external network usage

## 🔄 Updates & Maintenance

### Updating:
```bash
git pull origin main
npm install
npm run build
```

### Version Checking:
```bash
npm list @modelcontextprotocol/sdk
```

### Logs:
Check console output for debugging information and status messages.

## 💡 Pro Tips

1. **System Prompt**: Always include the system prompt for automatic usage
2. **Quick Submit**: Use Ctrl+Enter for faster submission
3. **Context**: Provide context in your input for better AI responses
4. **Backup Plan**: Have a fallback if the tool fails (regular chat message)
5. **Testing**: Test the setup before important tasks

## 🤝 Support

For issues, questions, or contributions:
- Check the troubleshooting section above
- Review console logs for error messages
- Open an issue on the GitHub repository
- Ensure you're using Node.js 18+ and latest dependencies