Update MCP SDK from 0.6.0 to 1.6.0

.gitignore

@@ -27,3 +27,12 @@ yarn-error.log*
 # OS
 .DS_Store
 Thumbs.db
+
+# MCP Inspector
+.mcp-inspector/
+
+# Local Docker images
+*.local
+
+# Temporary files
+/tmp/confluence-cloud-mcp/

DEVELOPMENT.md

@@ -0,0 +1,144 @@
+# Confluence Cloud MCP Server Development Guide
+
+This document provides information about development and troubleshooting for the Confluence Cloud MCP server.
+
+## Troubleshooting
+
+### API Verification
+
+The server performs API verification during initialization to ensure that the Confluence API credentials are valid and the API is reachable. If the verification fails, the server will exit with an error message, preventing it from starting with invalid credentials.
+
+This approach has several advantages:
+
+1. Users get immediate feedback if their API credentials are invalid
+2. The server won't start with invalid credentials, avoiding confusion when tools don't work
+3. Detailed error messages help users troubleshoot connection issues
+
+The verification is implemented in the `verifyApiConnection` method in the `ConfluenceClient` class:
+
+```typescript
+async verifyApiConnection(): Promise<void> {
+  try {
+    // Make a simple API call that should work with minimal permissions
+    await this.v2Client.get('/spaces', { params: { limit: 1 } });
+    console.error('Successfully connected to Confluence API');
+  } catch (error) {
+    let errorMessage = 'Failed to connect to Confluence API';
+
+    if (axios.isAxiosError(error)) {
+      // Provide specific error messages based on status code
+      if (error.response && error.response.status === 401) {
+        errorMessage = 'Authentication failed: Invalid API token or email';
+      } else if (error.response && error.response.status === 403) {
+        errorMessage = 'Authorization failed: Insufficient permissions';
+      } else if (error.response && error.response.status === 404) {
+        errorMessage = 'API endpoint not found: Check Confluence domain';
+      } else if (error.response && error.response.status >= 500) {
+        errorMessage = 'Confluence server error: API may be temporarily unavailable';
+      }
+
+      console.error(`${errorMessage}:`, errorDetails);
+    } else {
+      console.error(errorMessage + ':', error instanceof Error ? error.message : String(error));
+    }
+
+    // Throw error with detailed message to fail server initialization
+    throw new Error(errorMessage);
+  }
+}
+```
+
+The server initialization in the `ConfluenceServer` class calls this method:
+
+```typescript
+// Verify API connection - will throw an error if verification fails
+await this.confluenceClient.verifyApiConnection();
+```
+
+If the verification fails, the error is caught in the constructor's catch block, which logs the error and exits the process:
+
+```typescript
+constructor() {
+  // Initialize asynchronously
+  this.initialize().catch(error => {
+    console.error("Failed to initialize server:", error);
+    process.exit(1);
+  });
+}
+```
+
+This approach ensures that the server only starts if the API credentials are valid, providing a better user experience.
+
+## Local Development
+
+### Building and Running Locally
+
+1. Build the project:
+```bash
+npm run build
+```
+
+2. Run the server with test credentials:
+```bash
+CONFLUENCE_API_TOKEN=your_token CONFLUENCE_EMAIL=your_email CONFLUENCE_DOMAIN=your_domain node build/index.js
+```
+
+### Building and Running with Docker
+
+1. Build the Docker image:
+```bash
+./scripts/build-local.sh
+```
+
+2. Run the Docker image:
+```bash
+CONFLUENCE_API_TOKEN=your_token CONFLUENCE_EMAIL=your_email CONFLUENCE_DOMAIN=your_domain ./scripts/run-local.sh
+```
+
+### Using the MCP Inspector
+
+The MCP Inspector is a tool that helps diagnose issues with MCP servers:
+
+1. Run the inspector:
+```bash
+npm run inspector
+```
+
+2. Open http://localhost:5173 in your browser
+3. Configure the inspector to connect to your server
+4. Use the inspector to test the server's capabilities
+
+## Updating the MCP SDK
+
+The server uses the MCP SDK to communicate with the MCP system. If you encounter compatibility issues, you may need to update the SDK:
+
+```bash
+npm install @modelcontextprotocol/sdk@latest
+```
+
+After updating the SDK, rebuild the project and the Docker image.
+
+## Configuring Claude Desktop
+
+To use the local Docker image with Claude Desktop:
+
+1. Update the Claude desktop config file:
+```json
+{
+  "mcpServers": {
+    "confluence": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i", "confluence-cloud-mcp:local"],
+      "env": {
+        "CONFLUENCE_DOMAIN": "your-domain.atlassian.net",
+        "CONFLUENCE_EMAIL": "your-email@domain.com",
+        "CONFLUENCE_API_TOKEN": "your-api-token"
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+2. Restart the Claude desktop app for the changes to take effect

README.md

@@ -27,7 +27,7 @@ The easiest way to use this server is with the pre-built Docker image:
 docker run --rm -i \
   -e CONFLUENCE_API_TOKEN=your-api-token \
   -e CONFLUENCE_EMAIL=your-email@domain.com \
-  -e CONFLUENCE_HOST=your-domain.atlassian.net \
+  -e CONFLUENCE_DOMAIN=your-domain.atlassian.net \
   ghcr.io/aaronsb/confluence-cloud-mcp:latest
 ```
 
@@ -58,7 +58,7 @@ npm install
 2. Configure environment variables:
 Create a `.env` file with your Confluence credentials:
 ```
-CONFLUENCE_HOST=your-domain.atlassian.net
+CONFLUENCE_DOMAIN=your-domain.atlassian.net
 CONFLUENCE_EMAIL=your-email@domain.com
 CONFLUENCE_API_TOKEN=your-api-token
 ```
@@ -84,7 +84,7 @@ The server can be integrated with MCP-compatible AI assistants by adding it to t
       "command": "docker",
       "args": ["run", "--rm", "-i", "ghcr.io/aaronsb/confluence-cloud-mcp:latest"],
       "env": {
-        "CONFLUENCE_HOST": "your-domain.atlassian.net",
+        "CONFLUENCE_DOMAIN": "your-domain.atlassian.net",
         "CONFLUENCE_EMAIL": "your-email@domain.com",
         "CONFLUENCE_API_TOKEN": "your-api-token"
       },

confluence-handlers.todo

@@ -47,6 +47,13 @@ Error Handling:
   - EmptyContent
 ☐ Improve error messages to be AI-friendly
 ☐ Add debug logging throughout
+✓ Improve API verification:
+  - Implemented API verification that fails server initialization if verification fails
+  - Added detailed error messages based on HTTP status codes
+  - Added clear error reporting for connection issues
+☐ Further API verification improvements:
+  - Add environment variable to optionally disable verification if needed
+  - Add retry mechanism for transient connection failures
 
 Testing:
 ☐ Test with various scenarios:

llms-install.md

@@ -21,7 +21,7 @@ This guide provides detailed instructions for AI assistants like Cline to instal
       "args": ["run", "--rm", "-i", 
         "ghcr.io/aaronsb/confluence-cloud-mcp:latest"],
       "env": {
-        "CONFLUENCE_HOST": "your-domain.atlassian.net",
+        "CONFLUENCE_DOMAIN": "your-domain.atlassian.net",
         "CONFLUENCE_EMAIL": "your-email@domain.com",
         "CONFLUENCE_API_TOKEN": "your-api-token"
       },
@@ -53,7 +53,7 @@ cd confluence-cloud-mcp
       "command": "docker",
       "args": ["run", "--rm", "-i", "confluence-cloud-mcp:local"],
       "env": {
-        "CONFLUENCE_HOST": "your-domain.atlassian.net",
+        "CONFLUENCE_DOMAIN": "your-domain.atlassian.net",
         "CONFLUENCE_EMAIL": "your-email@domain.com",
         "CONFLUENCE_API_TOKEN": "your-api-token"
       },
@@ -86,7 +86,7 @@ npm run build
       "command": "node",
       "args": ["/path/to/confluence-cloud-mcp/build/index.js"],
       "env": {
-        "CONFLUENCE_HOST": "your-domain.atlassian.net",
+        "CONFLUENCE_DOMAIN": "your-domain.atlassian.net",
         "CONFLUENCE_EMAIL": "your-email@domain.com",
         "CONFLUENCE_API_TOKEN": "your-api-token"
       },
@@ -105,15 +105,15 @@ npm run build
 4. Click "Create" and copy the generated token
 5. Use this token as the `CONFLUENCE_API_TOKEN` value
 6. Use your Atlassian account email as the `CONFLUENCE_EMAIL` value
-7. Use your Confluence Cloud instance URL (e.g., "your-domain.atlassian.net") as the `CONFLUENCE_HOST` value
+7. Use your Confluence Cloud instance URL (e.g., "your-domain.atlassian.net") as the `CONFLUENCE_DOMAIN` value
 
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
 | CONFLUENCE_API_TOKEN | Yes | Your Atlassian API token |
 | CONFLUENCE_EMAIL | Yes | Your Atlassian account email |
-| CONFLUENCE_HOST | No | Your Confluence Cloud domain (defaults to "your-domain.atlassian.net") |
+| CONFLUENCE_DOMAIN | No | Your Confluence Cloud domain (defaults to "your-domain.atlassian.net") |
 | MCP_MODE | No | Set to "true" by default in Docker container |
 | LOG_FILE | No | Path to log file (defaults to "/app/logs/confluence-cloud-mcp.log" in Docker) |