Testing the MCP Server Interactively

Prerequisites

Before testing, ensure:

Start Docker services:

docker compose up -d
# Wait for services to be healthy
curl http://localhost:59200/_cluster/health
curl http://localhost:58080/health

Some data is indexed (at least one mbox file):

# Download and index a recent month via Docker
docker compose exec scheduler retrieve-mbox --date 2024-12
docker compose exec scheduler index-mbox /app/data/dev/2024-12.mbox

Verify data is indexed:

curl http://localhost:59200/maven-dev/_count
# Should show: {"count": <some number>, ...}

Option 1: Streamable HTTP with Docker (Production-like)

Test the MCP server via Streamable HTTP transport, the same way MCP clients connect in production:

# Start all services
docker compose up -d

# Check health
curl http://localhost:58080/health

# Get server info
curl http://localhost:58080/info

For full MCP protocol testing (tool calls via Streamable HTTP), use an MCP client like Claude Code:

claude mcp add maven-mail --transport http http://localhost:58080/mcp

Option 2: MCP Inspector (Development)

The official MCP Inspector provides a web UI for testing MCP servers via stdio transport. This is useful for development when running the server directly without Docker.

Installation and Launch

# From the mail-mcp directory (requires local Python/Poetry)
npx @modelcontextprotocol/inspector poetry run maven-mail-mcp

This will:

Start the MCP server
Launch a web interface (usually http://localhost:5173)
Show all available tools
Allow you to test each tool interactively

Using the Inspector

Open your browser to the URL shown (typically http://localhost:5173)
Explore available tools - You should see:
- search_emails
- get_message
- get_thread
- find_references
Test a tool - For example, try search_emails:
- Click on search_emails
- Fill in parameters:
  - query: "release"
  - size: 5
- Click "Call Tool"
- View the formatted response
Try other tools:
- Use a Message-ID from search results with get_message
- Use the same Message-ID with get_thread to see the conversation
- Search for a JIRA reference like "MNG-1234" with find_references

Example Test Sequence

1. search_emails
   - query: "maven 4"
   - size: 3
   → Returns recent discussions about Maven 4

2. Copy a Message-ID from results (e.g., <abc123@apache.org>)

3. get_message
   - message_id: <abc123@apache.org>
   → Shows full message with metadata

4. get_thread
   - message_id: <abc123@apache.org>
   → Shows entire conversation thread

5. find_references
   - reference: "MNG-7891"
   - reference_type: "jira"
   → Shows all emails mentioning MNG-7891

Option 2: Direct Python Testing

You can test the tools directly in Python without the MCP protocol layer:

poetry run python

Then in the Python REPL:

import asyncio
from mail_mcp.server.tools import search_emails, get_message, find_references

# Test search
async def test():
    # Search for emails
    result = await search_emails(
        query="release",
        size=5
    )
    print(result)
    print("\n" + "="*80 + "\n")

    # Find JIRA references
    result = await find_references(
        reference="MNG-1234",
        reference_type="jira",
        size=3
    )
    print(result)

asyncio.run(test())

Example Python Test Script

Create a file test_tools.py:

#!/usr/bin/env python
"""Interactive test script for MCP tools."""

import asyncio
from mail_mcp.server.tools import search_emails, get_message, get_thread, find_references


async def main():
    """Run interactive tests."""
    print("=== Testing MCP Tools ===\n")

    # Test 1: Search
    print("1. Searching for 'maven 4.0'...")
    result = await search_emails(query="maven 4.0", size=3)
    print(result)
    print("\n" + "="*80 + "\n")

    # Test 2: Find JIRA references
    print("2. Finding emails about MNG-7891...")
    result = await find_references(reference="MNG-7891", reference_type="jira")
    print(result)
    print("\n" + "="*80 + "\n")

    # Test 3: Search with filters
    print("3. Searching for emails with votes...")
    result = await search_emails(query="release", has_vote=True, size=3)
    print(result)
    print("\n" + "="*80 + "\n")

    # Test 4: Search with date filter
    print("4. Searching emails from 2024...")
    result = await search_emails(
        query="dependency",
        from_date="2024-01-01",
        to_date="2024-12-31",
        size=3
    )
    print(result)


if __name__ == "__main__":
    asyncio.run(main())

Then run:

poetry run python test_tools.py

Option 3: MCP Client Testing with Claude Desktop

Once you have data indexed, you can test with Claude Desktop:

Add configuration to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "maven-mail": {
      "command": "poetry",
      "args": ["run", "maven-mail-mcp"],
      "cwd": "/Users/ascheman/wrk/maven/maven-support-and-care/maven-mcps/mail-mcp",
      "env": {
        "MAIL_MCP_ELASTICSEARCH_URL": "http://localhost:59200",
        "MAIL_MCP_ELASTICSEARCH_INDEX_PREFIX": "maven",
        "MAIL_MCP_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Restart Claude Desktop completely (Quit and reopen)
Check MCP servers - Look for the hammer icon or MCP indicator
Test with queries:
- "Search the Maven mailing list for discussions about version 4.0"
- "Find all emails mentioning MNG-1234"
- "Show me recent votes on the dev mailing list"
Check logs if issues occur:
- macOS: ~/Library/Logs/Claude/mcp*.log
- Look for server startup and tool calls

Option 4: Simple Elasticsearch Query Testing

Test that your data is properly indexed and searchable:

# Count indexed emails
curl http://localhost:59200/maven-dev/_count

# Search for a term
curl -X POST http://localhost:59200/maven-dev/_search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "match": {
        "subject": "release"
      }
    },
    "size": 3
  }'

# Find emails with JIRA references
curl -X POST http://localhost:59200/maven-dev/_search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "exists": {
        "field": "jira_references"
      }
    },
    "size": 5
  }'

# Get a specific message
curl http://localhost:59200/maven-dev/_doc/<message-id>

Troubleshooting

No Results Found

Check index status:

# List all indices
curl http://localhost:59200/_cat/indices?v

# Check specific index
curl http://localhost:59200/maven-dev/_count

# View sample documents
curl -X POST http://localhost:59200/maven-dev/_search \
  -H 'Content-Type: application/json' \
  -d '{"size": 1}'

If count is 0, index some data:

poetry run index-mbox data/dev/2024-12.mbox

MCP Inspector Won’t Start

Check Node.js version:
```
node --version  # Should be v18+
```

Try with explicit port:

PORT=5173 npx @modelcontextprotocol/inspector poetry run maven-mail-mcp

Check server starts independently:

poetry run maven-mail-mcp
# Should wait for input (Ctrl+C to exit)

Python Testing Errors

If you get connection errors:

Ensure Elasticsearch is running:

docker compose ps
curl http://localhost:59200/_cluster/health

Check environment variables:

poetry run python -c "from mail_mcp.config import settings; print(settings.elasticsearch_url)"

Enable debug logging:

MAIL_MCP_LOG_LEVEL=DEBUG poetry run python test_tools.py

Claude Desktop Integration Issues

Check configuration path - Make sure cwd is correct:

# Should show mail-mcp directory
ls /Users/ascheman/wrk/maven/maven-support-and-care/maven-mcps/mail-mcp

Check logs:

# On macOS
tail -f ~/Library/Logs/Claude/mcp-server-maven-mail.log

Test command manually:

cd /Users/ascheman/wrk/maven/maven-support-and-care/maven-mcps/mail-mcp
poetry run maven-mail-mcp
# Should start and wait for input

Sample Test Data

If you want to test with minimal data, index just one recent month:

# Get December 2024 (usually has release discussions)
poetry run retrieve-mbox --date 2024-12

# Index it
poetry run index-mbox data/dev/2024-12.mbox

# Verify
curl http://localhost:59200/maven-dev/_count

This should give you enough emails to test all features.

Quick Start Test Sequence

Complete minimal test in 5 minutes:

# 1. Start Elasticsearch (if not running)
docker compose up -d elasticsearch
sleep 10  # Wait for startup

# 2. Index one month of data
poetry run retrieve-mbox --date 2024-12
poetry run index-mbox data/dev/2024-12.mbox

# 3. Launch MCP Inspector
npx @modelcontextprotocol/inspector poetry run maven-mail-mcp

# 4. Open browser to http://localhost:5173
# 5. Try search_emails with query="release" and size=5
# 6. Explore the results!