Merge pull request #17 from Countly/ar2rsawseen/main

Update docker docs

Author: ar2rsawseen

.env.example

@@ -24,8 +24,9 @@ COUNTLY_SERVER_URL=https://api.count.ly
 # Useful for Docker secrets, Kubernetes secrets, or secure file storage
 # COUNTLY_AUTH_TOKEN_FILE=/run/secrets/countly_token
 
-# Note: If neither is set, the token must be provided by the MCP client
-# via metadata.countlyAuthToken or as a tool argument
+# Note: If neither is set, credentials can be provided:
+# - Via HTTP headers (X-Countly-Auth-Token) for HTTP/SSE transport
+# - Via tool arguments (countly_auth_token) in individual tool calls
 
 
 # ==============================================================================
@@ -42,8 +43,8 @@ COUNTLY_TIMEOUT=30000
 # AUTHENTICATION PRIORITY
 # ==============================================================================
 # The server uses the following priority for authentication:
-# 1. MCP client metadata (metadata.countlyAuthToken)
-# 2. Tool argument (countly_auth_token)
+# 1. HTTP headers (X-Countly-Auth-Token) - for HTTP/SSE transport
+# 2. Tool argument (countly_auth_token) - per-request override
 # 3. Environment variable (COUNTLY_AUTH_TOKEN)
 # 4. Token file (COUNTLY_AUTH_TOKEN_FILE)
 #
@@ -78,10 +79,10 @@ COUNTLY_TIMEOUT=30000
 
 
 # ==============================================================================
-# MCP CLIENT CONFIGURATION EXAMPLE
+# MCP CLIENT CONFIGURATION EXAMPLES
 # ==============================================================================
-# If using MCP client (e.g., Claude Desktop), configure in your MCP settings:
-#
+
+# STDIO Transport (Claude Desktop, local clients):
 # {
 #   "mcpServers": {
 #     "countly": {
@@ -95,19 +96,17 @@ COUNTLY_TIMEOUT=30000
 #   }
 # }
 #
-# Or using metadata for per-user authentication:
-#
+# HTTP/SSE Transport (VS Code, web clients):
 # {
-#   "mcpServers": {
-#     "countly": {
-#       "command": "node",
-#       "args": ["/path/to/countly-mcp-server/build/index.js"],
-#       "env": {
-#         "COUNTLY_SERVER_URL": "https://your-countly-instance.com"
-#       },
-#       "metadata": {
-#         "countlyAuthToken": "your-auth-token-here"
+#   "servers": {
+#     "countly-docker": {
+#       "type": "sse",
+#       "url": "http://localhost:3000/mcp",
+#       "headers": {
+#         "X-Countly-Server-Url": "https://your-countly-instance.com",
+#         "X-Countly-Auth-Token": "your-auth-token-here"
 #       }
 #     }
 #   }
 # }
+

.github/workflows/test.yml

@@ -50,6 +50,10 @@ jobs:
 
       - name: Run tests
         run: npm run test:ci
+        env:
+          # Set test credentials for transport integration tests
+          COUNTLY_SERVER_URL: https://test.count.ly
+          COUNTLY_AUTH_TOKEN: test-token-for-ci
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5

DOCKER.md

@@ -20,8 +20,8 @@ The fastest way to get started:
 
 ```bash
 # 1. Clone and navigate to the repository
-git clone https://github.com/countly/mcp-server.git
-cd mcp-server
+git clone https://github.com/countly/countly-mcp-server.git
+cd countly-mcp-server
 
 # 2. Run the quick start script
 ./docker-start.sh
@@ -37,7 +37,7 @@ The script will guide you through:
 ### Pull from Docker Hub
 
 ```bash
-docker pull countly/mcp-server:latest
+docker pull countly/countly-mcp-server:latest
 ```
 
 ### Run from Docker Hub
@@ -48,7 +48,7 @@ docker run -d \
   -p 3000:3000 \
   -e COUNTLY_SERVER_URL=https://your-countly-instance.com \
   -e COUNTLY_AUTH_TOKEN=your-token-here \
-  countly/mcp-server:latest
+  countly/countly-mcp-server:latest
 ```
 
 ## Local Build
@@ -227,7 +227,7 @@ spec:
     spec:
       containers:
       - name: countly-mcp-server
-        image: countly/mcp-server:latest
+        image: countly/countly-mcp-server:latest
         imagePullPolicy: Always
         ports:
         - containerPort: 3000
@@ -523,6 +523,6 @@ logging:
 
 ## Support
 
-- Issues: [GitHub Issues](https://github.com/countly/mcp-server/issues)
+- Issues: [GitHub Issues](https://github.com/countly/countly-mcp-server/issues)
 - Community: [Countly Community](https://community.count.ly)
 - Documentation: [README.md](./README.md)

Dockerfile

@@ -23,6 +23,17 @@ RUN npm run build
 # Stage 2: Production
 FROM node:20-alpine
 
+# OCI Labels for metadata and Docker Desktop icon
+LABEL org.opencontainers.image.title="Countly MCP Server" \
+    org.opencontainers.image.description="Model Context Protocol server for Countly Analytics Platform" \
+    org.opencontainers.image.vendor="Countly" \
+    org.opencontainers.image.authors="Countly Team" \
+    org.opencontainers.image.url="https://count.ly" \
+    org.opencontainers.image.documentation="https://github.com/countly/countly-mcp-server" \
+    org.opencontainers.image.source="https://github.com/countly/countly-mcp-server" \
+    org.opencontainers.image.licenses="MIT" \
+    com.docker.extension.icon="https://cdn.prod.website-files.com/61c1b7c3e2f3805325be4594/63cc3bf4993f0072054270a6_Logo%20-%20Dark%20background.png"
+
 WORKDIR /app
 
 # Install dumb-init for proper signal handling
@@ -65,5 +76,5 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
 # Use dumb-init to handle signals properly
 ENTRYPOINT ["dumb-init", "--"]
 
-# Default command: run in HTTP mode (can be overridden for stdio mode)
-CMD ["node", "build/index.js", "--http"]
+# Default command: run in HTTP mode on port 3000 (can be overridden for stdio mode)
+CMD ["node", "build/index.js", "--http", "--port", "3000", "--hostname", "0.0.0.0"]

README.md

@@ -10,23 +10,42 @@ Countly is an open-source, enterprise-grade product analytics platform. It helps
 
 The Model Context Protocol (MCP) is an open protocol that enables seamless integration between AI applications and external data sources. This server implements MCP to allow AI assistants like Claude to interact with your Countly analytics data naturally through conversation.
 
+## Requirements
+
+### Server Requirements
+- **Node.js 18+** (for local installation) OR **Docker** (recommended)
+- **Countly Server**: Access to a Countly instance (cloud or self-hosted)
+- **Auth Token**: Valid Countly authentication token with appropriate permissions
+
+### Client Requirements
+- **MCP Protocol Version**: `2025-03-26` (Streamable HTTP specification)
+- **Compatible Clients**:
+  - VS Code MCP Extension (latest version)
+  - Claude Desktop (recent versions supporting 2025-03-26 spec)
+  - Any MCP client implementing the Streamable HTTP transport protocol
+
+> ⚠️ **Note**: For SSE type this server uses `StreamableHTTPServerTransport` which implements the modern MCP specification (2025-03-26). Older MCP clients that only support the legacy SSE protocol (2024-11-05) are not compatible. Please ensure your MCP client is up-to-date.
+
 ## Features
 
-- 🔐 Multiple authentication methods (metadata, environment variables, file-based)
+- 🔐 Multiple authentication methods (HTTP headers, environment variables, file-based)
 - 📊 Comprehensive Countly API access
 - �️ Fine-grained tools configuration with CRUD operation control per category
 - �🐳 Docker support with production-ready configuration
 - 🔄 Support for both stdio and HTTP transports
 - 🏥 Built-in health checks
-- 🔒 Secure token handling with Docker secrets support
+- 🔒 Secure token handling with cryptographically secure session IDs
+- 🌐 Multi-client support with per-client credential passing
 
 ## Quick Start
 
 ### Prerequisites
 
-- **Countly Server**: Access to a Countly instance (cloud or self-hosted)
-- **Auth Token**: Valid Countly authentication token with appropriate permissions
-- **Node.js 18+** (for local installation) OR **Docker** (recommended)
+Before starting, ensure you have:
+- Access to a Countly instance (cloud or self-hosted)
+- Valid Countly authentication token with appropriate permissions
+- Node.js 18+ (for local installation) OR Docker (recommended)
+- MCP client supporting protocol version 2025-03-26 (Streamable HTTP)
 
 ### Using Docker (Recommended)
 
@@ -94,17 +113,21 @@ docker run -d \
 
 The server supports multiple authentication methods (in priority order):
 
-1. **MCP Client Metadata** (highest priority)
-   - Passed via `metadata.countlyAuthToken`
-   
+1. **HTTP Headers** (recommended for HTTP/SSE transport)
+   - Pass via `X-Countly-Server-Url` and `X-Countly-Auth-Token` headers
+   - Supported by VS Code MCP extension and other HTTP clients
+   - See [VS Code MCP Configuration](examples/vscode-mcp.md) for details
+
 2. **Tool Arguments**
-   - Passed as `countly_auth_token` parameter
+   - Passed as `countly_auth_token` parameter in individual tool calls
 
 3. **Environment Variable**
    - Set `COUNTLY_AUTH_TOKEN` in environment
+   - Recommended for stdio transport mode
 
 4. **Token File** (recommended for production)
    - Set `COUNTLY_AUTH_TOKEN_FILE` pointing to a file containing the token
+   - Useful with Docker secrets
 
 ## Configuration
 
@@ -290,7 +313,7 @@ The most common use case is with Claude Desktop. Add to your Claude configuratio
 }
 ```
 
-**Using metadata for token (more secure):**
+**Using environment variable for token (alternative):**
 
 ```json
 {
@@ -299,10 +322,8 @@ The most common use case is with Claude Desktop. Add to your Claude configuratio
       "command": "node",
       "args": ["/path/to/countly-mcp-server/build/index.js"],
       "env": {
-        "COUNTLY_SERVER_URL": "https://your-countly-instance.com"
-      },
-      "metadata": {
-        "countlyAuthToken": "your-token-here"
+        "COUNTLY_SERVER_URL": "https://your-countly-instance.com",
+        "COUNTLY_AUTH_TOKEN": "your-token-here"
       }
     }
   }
@@ -312,8 +333,8 @@ The most common use case is with Claude Desktop. Add to your Claude configuratio
 ### Other MCP Clients
 
 This server is compatible with any MCP client that supports:
-- **stdio transport** (default) - For local/desktop clients
-- **HTTP/SSE transport** - For web-based or remote clients
+- **stdio transport** (default) - For local/desktop clients (uses environment variables for auth)
+- **HTTP/SSE transport** - For web-based or remote clients (uses HTTP headers for auth)
 
 For HTTP mode, clients should connect to: `http://your-server:3000/mcp`
 
@@ -457,6 +478,8 @@ npm run test:ci
 - Authentication and credential handling
 - Tool handlers and parameter validation
 - HTTP client configuration
+- Transport layer (stdio and HTTP/SSE)
+- End-to-end server connectivity
 - Error handling
 
 ---
@@ -494,7 +517,7 @@ MIT
 ## Support
 
 For issues and questions:
-- GitHub Issues: [countly/mcp-server](https://github.com/countly/mcp-server)
+- GitHub Issues: [countly/countly-mcp-server](https://github.com/countly/countly-mcp-server)
 - Countly Community: [https://community.count.ly](https://community.count.ly)
 
 ## CI/CD

docker-compose.yml

@@ -1,45 +1,43 @@
-version: '3.8'
-
 services:
   countly-mcp-server:
     build:
       context: .
       dockerfile: Dockerfile
     container_name: countly-mcp-server
     restart: unless-stopped
-    
-    # Environment variables
+
+    # Environment variables (optional - can be provided by MCP client via HTTP headers)
     environment:
-      - COUNTLY_SERVER_URL=${COUNTLY_SERVER_URL:-https://api.count.ly}
+      # Countly server URL (optional - can be provided via X-Countly-Server-Url header)
+      - COUNTLY_SERVER_URL=${COUNTLY_SERVER_URL:-}
+      # Auth token (optional - can be provided via X-Countly-Auth-Token header)
+      - COUNTLY_AUTH_TOKEN=${COUNTLY_AUTH_TOKEN:-}
+      # Request timeout in milliseconds
       - COUNTLY_TIMEOUT=${COUNTLY_TIMEOUT:-30000}
-      # Option 1: Direct token (not recommended for production)
-      # - COUNTLY_AUTH_TOKEN=${COUNTLY_AUTH_TOKEN}
-      # Option 2: Token from file (recommended for production)
-      - COUNTLY_AUTH_TOKEN_FILE=/run/secrets/countly_token
-    
+
     # Ports
     ports:
       - "3000:3000"
-    
-    # Docker secrets (recommended for production)
-    secrets:
-      - countly_token
-    
+
+    # Docker secrets (optional - uncomment for production use)
+    # secrets:
+    #   - countly_token
+
     # Health check
     healthcheck:
-      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"]
+      test: [ "CMD", "node", "-e", "require('http').get('http://localhost:3000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})" ]
       interval: 30s
       timeout: 10s
       retries: 3
       start_period: 5s
-    
+
     # Logging
     logging:
       driver: "json-file"
       options:
         max-size: "10m"
         max-file: "3"
-    
+
     # Resource limits (adjust as needed)
     deploy:
       resources:
@@ -50,28 +48,13 @@ services:
           cpus: '0.5'
           memory: 256M
 
-# Docker secrets configuration
-secrets:
-  countly_token:
-    # Option 1: Load from file
-    file: ./countly_token.txt
-    # Option 2: External secret (for Docker Swarm)
-    # external: true
+# Docker secrets configuration (optional - for production use)
+# Uncomment the secrets section in the service above and this section to use secrets
+# secrets:
+#   countly_token:
+#     file: ./countly_token.txt
 
-# Alternative configuration without secrets (development only)
-# Uncomment this and comment out the secrets section above
-# ---
-# version: '3.8'
-# services:
-#   countly-mcp-server:
-#     build:
-#       context: .
-#       dockerfile: Dockerfile
-#     container_name: countly-mcp-server
-#     restart: unless-stopped
-#     environment:
-#       - COUNTLY_SERVER_URL=https://api.count.ly
-#       - COUNTLY_AUTH_TOKEN=your-token-here
-#       - COUNTLY_TIMEOUT=30000
-#     ports:
-#       - "3000:3000"
+# For production with Docker Swarm:
+# 1. Uncomment the secrets sections above
+# 2. Create the secret: echo "your-token" | docker secret create countly_token -
+# 3. Change the secret config to: external: true

examples/vscode-mcp.md

@@ -58,16 +58,17 @@ This example shows how to configure VS Code's MCP support to connect to Countly
     "countly": {
       "type": "sse",
       "url": "http://localhost:3000/mcp",
-      "metadata": {
-        "countlyAuthToken": "your-auth-token-here"
+      "headers": {
+        "X-Countly-Server-Url": "https://your-countly-instance.com",
+        "X-Countly-Auth-Token": "your-auth-token-here"
       }
     }
   },
   "inputs": []
 }
 ```
 
-**Note**: The client can pass authentication via `metadata.countlyAuthToken`. The server will use this token to authenticate with your Countly instance.
+**Note**: The VS Code MCP extension passes credentials via HTTP headers (`X-Countly-Server-Url` and `X-Countly-Auth-Token`). This allows multiple users to connect to the same Docker instance with their own credentials.
 
 **Method 3: Docker Container (stdio)**