TESTING_LOCALLY.md•6.34 kB
# Testing MCP Cut-Copy-Paste Clipboard Server Locally with Claude Code
This guide shows you how to test your MCP server locally before publishing to npm.
## Prerequisites
- Claude Code installed and running
- Project built with `npm run build`
## Step 1: Build the Project
```bash
npm run build
```
This compiles TypeScript to the `dist/` folder.
## Step 2: Configure Claude Code
Claude Code uses MCP server configurations. You need to add your local server to the configuration file.
### Configuration File Location
The Claude Code configuration file is typically located at:
**macOS:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Windows:**
```
%APPDATA%/Claude/claude_desktop_config.json
```
**Linux:**
```
~/.config/Claude/claude_desktop_config.json
```
### Add Local Server Configuration
Edit the configuration file and add your local server:
```json
{
"mcpServers": {
"clipboard-local": {
"command": "node",
"args": [
"~/git/cut-copy-paste-mcp/dist/cli.js"
],
"env": {}
}
}
}
```
**Important**: Replace `~/git/cut-copy-paste-mcp` with your actual absolute path to this project.
### Full Example Configuration
If you already have other MCP servers configured, it should look like this:
```json
{
"mcpServers": {
"clipboard-local": {
"command": "node",
"args": [
"~/git/cut-copy-paste-mcp/dist/cli.js"
]
},
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/allowed/files"
]
}
}
}
```
## Step 3: Restart Claude Code
After modifying the configuration file:
1. **Quit Claude Code completely** (not just close the window)
- macOS: `Cmd + Q`
- Windows/Linux: File → Exit
2. **Restart Claude Code**
3. The MCP server will start automatically when Claude Code launches
## Step 4: Verify Server is Running
In Claude Code, you should be able to see the clipboard tools available. You can verify by asking Claude:
```
"What MCP tools do you have access to?"
```
You should see the following tools listed:
- `copy_lines`
- `cut_lines`
- `paste_lines`
- `show_clipboard`
- `undo_last_paste`
- `get_operation_history`
## Step 5: Test the Tools
Create a test file and try the clipboard operations:
### Test 1: Copy Lines
Create a test file:
```bash
echo -e "line 1\nline 2\nline 3\nline 4\nline 5" > /tmp/test-file.txt
```
In Claude Code, ask:
```
"Use copy_lines to copy lines 2-4 from /tmp/test-file.txt"
```
### Test 2: Show Clipboard
```
"Use show_clipboard to show me what's in the clipboard"
```
### Test 3: Paste Lines
```
"Use paste_lines to paste the clipboard content to line 1 of /tmp/test-target.txt"
```
### Test 4: Operation History
```
"Use get_operation_history to show me the recent operations"
```
### Test 5: Cut and Undo
```
"Use cut_lines to cut line 3 from /tmp/test-file.txt"
"Now use undo_last_paste to undo that operation"
```
## Troubleshooting
### Server Not Starting
**Check logs:**
Claude Code may log MCP server errors. Look for error messages in:
- macOS: `~/Library/Logs/Claude/`
- Windows: `%APPDATA%/Claude/logs/`
- Linux: `~/.config/Claude/logs/`
**Common issues:**
1. **Path incorrect**: Verify the absolute path in your config file
```bash
# Get the correct path
cd ~/git/cut-copy-paste-mcp
pwd
```
2. **dist/ folder missing**: Run `npm run build` first
3. **Node.js not in PATH**: Try using absolute path to node:
```json
{
"command": "/usr/local/bin/node",
"args": ["/full/path/to/dist/cli.js"]
}
```
Find node path with: `which node`
4. **Permissions issue**: Ensure cli.js is executable:
```bash
chmod +x dist/cli.js
```
### Tools Not Appearing
1. **Check server name**: Ensure the server name in config matches (e.g., "clipboard-local")
2. **Restart Claude Code**: Fully quit and restart, don't just reload
3. **Check config JSON syntax**: Use a JSON validator to ensure no syntax errors
### Tool Execution Fails
1. **Check file paths**: Ensure test files exist and have correct permissions
2. **Check database**: The server creates `~/.mcp-clipboard/clipboard.db` - ensure this directory is writable
3. **Review error messages**: Claude will show tool execution errors
### Testing with stdio
You can also test the server directly via stdio:
```bash
# Start the server manually
node dist/cli.js
# It will wait for JSON-RPC messages on stdin
# Type Ctrl+C to exit
```
## Development Workflow
While developing and testing:
1. **Make code changes** in `src/`
2. **Rebuild**: `npm run build`
3. **Restart Claude Code** (full quit and restart)
4. **Test** the changes
**Tip**: Keep a terminal open with watch mode during development:
```bash
npm run build -- --watch
```
This will automatically rebuild when you save TypeScript files. You'll still need to restart Claude Code to pick up changes.
## Comparing Local vs. Published
To test both local and published versions side-by-side:
```json
{
"mcpServers": {
"clipboard-local": {
"command": "node",
"args": ["~/git/cut-copy-paste-mcp/dist/cli.js"]
},
"clipboard-published": {
"command": "npx",
"args": ["cut-copy-paste-mcp"]
}
}
}
```
This lets you verify the published version works identically to your local version.
## Ready to Publish?
Once you've tested locally and verified all tools work correctly:
1. ✅ All tools accessible in Claude Code
2. ✅ Copy/cut/paste operations work correctly
3. ✅ Undo functionality works
4. ✅ Operation history is accurate
5. ✅ Error handling works as expected
You're ready to publish! See **PUBLISHING_GUIDE.md** for the next steps.
## Quick Reference
**Config file location (macOS):**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Local server configuration:**
```json
{
"mcpServers": {
"clipboard-local": {
"command": "node",
"args": ["~/git/cut-copy-paste-mcp/dist/cli.js"]
}
}
}
```
**Build command:**
```bash
npm run build
```
**Test commands:**
- Ask Claude: "What MCP tools do you have access to?"
- Ask Claude to use specific tools like `copy_lines`, `paste_lines`, etc.
- Check clipboard state with `show_clipboard`
- View history with `get_operation_history`