Testing and Debugging

Testing Your Server

Now that our server is complete, we need to test it thoroughly. We will use two approaches: manual testing with a test script and integration with Claude Desktop.

Manual Testing with STDIO

Since our server uses STDIO, we can test it by piping JSON-RPC requests directly.

Create: test_server.sh

Create a test script called test_server.sh:

#!/bin/bash
# test_server.sh - Test the Notes MCP Server

# Function to send a request and display the response
send_request() {
    echo ">>> Sending: $1"
    echo "$1" | python3 notes_server.py
    echo ""
}

echo "=== Testing Notes MCP Server ==="
echo ""

# Test 1: Initialize
echo "--- Test 1: Initialize ---"
send_request '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# Send initialized notification (no response expected)
echo "--- Sending initialized notification ---"
send_request '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# Test 2: List Tools
echo "--- Test 2: List Tools ---"
send_request '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Test 3: Create a Note
echo "--- Test 3: Create Note ---"
send_request '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"create_note","arguments":{"title":"Test Note","content":"This is a test note.","tags":["test","demo"]}}}'

# Test 4: List Resources
echo "--- Test 4: List Resources ---"
send_request '{"jsonrpc":"2.0","id":4,"method":"resources/list","params":{}}'

# Test 5: Read Notes List Resource
echo "--- Test 5: Read Notes List ---"
send_request '{"jsonrpc":"2.0","id":5,"method":"resources/read","params":{"uri":"notes://list"}}'

# Test 6: Search Notes
echo "--- Test 6: Search Notes ---"
send_request '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"search_notes","arguments":{"query":"test"}}}'

# Test 7: List Prompts
echo "--- Test 7: List Prompts ---"
send_request '{"jsonrpc":"2.0","id":7,"method":"prompts/list","params":{}}'

# Test 8: Get Prompt
echo "--- Test 8: Get Summarize Prompt ---"
send_request '{"jsonrpc":"2.0","id":8,"method":"prompts/get","params":{"name":"summarize_notes","arguments":{"style":"brief"}}}'

echo "=== Tests Complete ==="

Run the test script:

chmod +x test_server.sh
./test_server.sh

Interactive Testing

For interactive testing, you can run the server and send requests manually:

# Start the server in interactive mode
python3 notes_server.py

# Then type JSON-RPC requests (one per line):
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

# Press Ctrl+D to exit

Claude Desktop Integration

The ultimate test is integrating with Claude Desktop. Add your server to the Claude Desktop configuration.

macOS Configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
    "mcpServers": {
        "notes": {
            "command": "python3",
            "args": ["/full/path/to/notes_server.py"],
            "env": {}
        }
    }
}

Windows Configuration

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
    "mcpServers": {
        "notes": {
            "command": "python",
            "args": ["C:\\full\\path\\to\\notes_server.py"],
            "env": {}
        }
    }
}

Testing with Claude

Once configured, restart Claude Desktop and try these conversations:

You: Create a note about my project ideas with tags "work" and "ideas"

Claude: I'll create that note for you using the notes server.

[Claude uses create_note tool]

I've created a new note titled "Project Ideas" with your specified tags.
The note ID is abc123.

---

You: Show me all my notes

Claude: Let me check your notes.

[Claude reads notes://list resource]

You have 3 notes:
1. [abc123] Project Ideas (tags: work, ideas)
2. [def456] Meeting Notes (tags: work, meeting)
3. [ghi789] Shopping List (tags: personal)

---

You: Summarize my work-related notes

Claude: I'll summarize your work notes.

[Claude uses summarize_notes prompt with tag="work"]

Here's a summary of your work notes:
- Project Ideas discusses potential new features...
- Meeting Notes covers the Q4 planning session...

Debugging Common Issues

Server Not Starting

# Test that the server runs without errors
python3 notes_server.py < /dev/null

# Check for syntax errors
python3 -m py_compile notes_server.py

JSON Parse Errors

If you see "Parse error" responses, ensure your JSON is valid:

• Use double quotes for strings, not single quotes
• No trailing commas in objects or arrays
• Escape special characters properly

Method Not Found

Check that you are using the correct method names:

• initialize (not "init" or "handshake")
• tools/list (not "listTools")
• tools/call (not "callTool")

Claude Desktop Not Connecting

1. Check the config file syntax is valid JSON
2. Verify the path to your server is correct
3. Ensure Python is in your PATH
4. Check Claude Desktop logs for errors
5. Restart Claude Desktop completely (quit and reopen)

Adding Debug Output

For debugging, you can add logging to your server (write to stderr so it does not interfere with STDIO communication):

import sys

def debug(message):
    """Write debug message to stderr."""
    print(f"[DEBUG] {message}", file=sys.stderr)

# Use in your handlers:
def handle_request(self, request: dict):
    debug(f"Received request: {request.get('method')}")
    # ... rest of handler

Testing Checklist

Before considering your server complete, verify: