# Testing Guide
This guide covers different ways to test the Confluence MCP Server.
## Prerequisites
Before testing, ensure you have:
1. Configured your `.env` file with valid Confluence credentials
2. Installed dependencies with `uv sync`
3. Access to a Confluence instance with at least one space and page
## Method 1: Using the Built-in Host Client
The simplest way to test individual tools. The host client supports **two modes**:
### Local Mode (stdio)
```bash
# Activate the virtual environment (or use 'uv run')
source .venv/bin/activate
# Test search functionality
python host.py search_confluence '{"query": "documentation"}'
# Test reading a page (replace with a real page ID)
python host.py read_page '{"page_id": "123456789"}'
# Test listing space content (replace with a real space key)
python host.py list_space_content '{"space_key": "TEAM"}'
```
### Docker Mode (HTTP/SSE)
```bash
# First, start the Docker container
docker run --rm -p 8000:8000 --env-file .env confluence-mcp
# In another terminal, connect via HTTP
python host.py --http http://localhost:8000 search_confluence '{"query": "documentation"}'
python host.py --http http://localhost:8000 read_page '{"page_id": "123456789"}'
python host.py --http http://localhost:8000 list_space_content '{"space_key": "TEAM"}'
```
### Pros:
- Quick and simple
- No additional installation required
- Good for CI/CD testing
- HTTP mode works with containerized deployments
### Cons:
- Command-line only
- Limited debugging capabilities
- Must manually format JSON
## Method 2: Using MCP Inspector (Recommended)
The MCP Inspector provides a visual web interface for testing and debugging.
### Installation
```bash
npm install -g @modelcontextprotocol/inspector
```
### Configuration
1. Create your configuration file:
```bash
cp mcp-config.example.json mcp-config.json
```
2. Edit `mcp-config.json` with your credentials:
```json
{
"mcpServers": {
"confluence": {
"command": "uv",
"args": ["run", "python", "server.py"],
"env": {
"CONFLUENCE_URL": "https://your-domain.atlassian.net",
"CONFLUENCE_USERNAME": "your-email@example.com",
"CONFLUENCE_API_TOKEN": "your-api-token"
}
}
}
}
```
**Alternative:** Use environment file reference:
```json
{
"mcpServers": {
"confluence": {
"command": "uv",
"args": ["run", "python", "server.py"]
}
}
}
```
(The server will automatically load from `.env`)
### Launch the Inspector
```bash
mcp-inspector mcp-config.json
```
This will:
1. Start the MCP Inspector server
2. Launch the Confluence MCP server
3. Open your browser at `http://localhost:5173`
### Using the Inspector
Once the inspector is running:
1. **View Available Tools**
- The left sidebar shows all three tools: `search_confluence`, `read_page`, `list_space_content`
- Click any tool to see its description and input schema
2. **Test search_confluence**
- Click "search_confluence"
- Enter a query in the JSON input:
```json
{
"query": "project documentation"
}
```
- Click "Run"
- View the results showing matching pages
3. **Test read_page**
- Click "read_page"
- Find a page ID from the search results
- Enter:
```json
{
"page_id": "123456789"
}
```
- Click "Run"
- View the page content converted to Markdown
4. **Test list_space_content**
- Click "list_space_content"
- Enter a space key:
```json
{
"space_key": "TEAM"
}
```
- Click "Run"
- View all pages in the space
### Debugging with Inspector
The Inspector shows:
- **Request/Response logs**: See exact JSON-RPC messages
- **Error messages**: View detailed error information
- **Tool schemas**: Understand expected inputs/outputs
- **Real-time updates**: See live data as tools execute
### Pros:
- Visual interface
- Real-time debugging
- Easy JSON formatting
- Request/response inspection
- No code changes needed
### Cons:
- Requires Node.js/npm
- Additional setup step
## Method 3: Direct Python Testing
For programmatic testing or integration:
```python
import asyncio
import json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def test_search():
server_params = StdioServerParameters(
command="uv",
args=["run", "python", "server.py"],
env=None
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
result = await session.call_tool(
"search_confluence",
arguments={"query": "documentation"}
)
print(json.dumps(result.content, indent=2))
asyncio.run(test_search())
```
## Troubleshooting
### Common Issues
**"Missing Confluence environment variables"**
- Ensure `.env` file exists and contains all three variables
- Or ensure `mcp-config.json` has all environment variables set
**"Unauthorized: Check your Confluence credentials"**
- Verify your API token is valid
- Check that your username (email) is correct
- Ensure your Confluence URL is correct (include https://)
**"Not Found: Page with ID 'xxx' does not exist"**
- The page ID doesn't exist or you don't have access
- Use search_confluence first to find valid page IDs
**"Not Found: Space with key 'xxx' does not exist"**
- The space key is incorrect or you don't have access
- Check your Confluence instance for the correct space key
**MCP Inspector won't connect**
- Ensure the server command in `mcp-config.json` is correct
- Check that uv is in your PATH
- Verify the virtual environment is set up (`uv sync`)
## Testing Checklist
Before considering the server production-ready:
- [ ] Search returns results for valid queries
- [ ] Search handles queries with no results gracefully
- [ ] Read page returns content in Markdown format
- [ ] Read page handles invalid page IDs with proper error
- [ ] List space content returns all pages in a space
- [ ] List space content handles invalid space keys properly
- [ ] All tools handle authentication errors (401)
- [ ] All tools handle not found errors (404)
- [ ] Server starts without errors when credentials are valid
- [ ] Server provides helpful error when credentials are missing
## Performance Testing
Test with various data sizes:
```bash
# Small query
python host.py search_confluence '{"query": "test"}'
# Complex page with lots of content
python host.py read_page '{"page_id": "large-page-id"}'
# Space with many pages
python host.py list_space_content '{"space_key": "BUSY-SPACE"}'
```
Monitor:
- Response times
- Memory usage
- Error rates
## Next Steps
Once testing is complete:
1. Deploy to production environment
2. Integrate with LLM applications
3. Set up monitoring and logging
4. Create backup procedures
