# Configuration Guide This document provides comprehensive configuration guidance for the Slack MCP Client, covering everything from basic setup to advanced deployment scenarios. ## Overview The Slack MCP Client has evolved from a simple MCP server connector to a comprehensive LLM orchestration platform. This guide outlines the unified configuration approach that prioritizes simplicity, DRY principles, and excellent user experience. ### Naming Convention Configuration files use **camelCase** naming for JSON fields (e.g., `botToken`, `mcpServers`, `useNativeTools`). This follows modern JSON API conventions and provides better IDE support with the included JSON schema. > **Note**: The application automatically detects and converts legacy snake\_case configurations for backward compatibility. ## Configuration Architecture ### Philosophy: Single File, Logical Sections **Reject complexity. Embrace simplicity.** Instead of multiple configuration files that create cognitive overhead, use a **single, well-structured configuration file** with logical sections. ### Unified Configuration Structure ``` config.json # Single configuration file custom-prompt.txt # Optional custom prompt file ├── examples/ │ ├── minimal.json # Minimal setup example │ ├── development.json # Development config example │ ├── production.json # Production config example │ └── custom-prompt.txt # Custom prompt example ├── schema/ │ └── config-schema.json # JSON schema for validation └── scripts/ └── migrate-config.sh # Migration utility ``` ### JSON Schema Support The configuration includes comprehensive JSON schema support for enhanced developer experience: * **Schema Reference**: Include `"$schema": "https://github.com/tuannvm/slack-mcp-client/schema/config-schema.json"` for IDE support * **Autocomplete**: IDEs provide intelligent autocomplete for configuration fields * **Validation**: Real-time validation of field types, required fields, and value constraints * **Documentation**: Inline field descriptions and examples ## Complete Configuration Reference Below is the complete configuration schema showing all available options. Fields marked with ⭐ are **required**, fields marked with ⚙️ have **smart defaults**, and fields marked with 🔧 are **optional**. ```json { "$schema": "https://github.com/tuannvm/slack-mcp-client/schema/config-schema.json", "version": "2.0", // ⭐ Required "slack": { "botToken": "${SLACK_BOT_TOKEN}", // ⭐ Required "appToken": "${SLACK_APP_TOKEN}", // ⭐ Required "messageHistory": 50, // ⚙️ Default: 50 messages per channel "thinkingMessage": "Thinking..." // ⚙️ Default: "Thinking..." }, "llm": { "provider": "openai", // ⚙️ Default: "openai" "useNativeTools": false, // ⚙️ Default: false "useAgent": false, // ⚙️ Default: false "customPrompt": "You are a helpful assistant.", // 🔧 Optional "customPromptFile": "custom-prompt.txt", // 🔧 Optional "replaceToolPrompt": false, // ⚙️ Default: false "maxAgentIterations": 20, // ⚙️ Default: 20 (maximum reasoning steps for agent mode) "providers": { "openai": { "model": "gpt-4o", // ⚙️ Default: "gpt-4o" "apiKey": "${OPENAI_API_KEY}", // ⭐ Required if using OpenAI "temperature": 0.7, // ⚙️ Default: 0.7 "maxTokens": 2000 // 🔧 Optional }, "anthropic": { "model": "claude-3-5-sonnet-20241022", // ⚙️ Default: "claude-3-5-sonnet-20241022" "apiKey": "${ANTHROPIC_API_KEY}", // ⭐ Required if using Anthropic "temperature": 0.7 // ⚙️ Default: 0.7 }, "ollama": { "model": "llama3", // ⚙️ Default: "llama3" "baseUrl": "http://localhost:11434", // ⚙️ Default: "http://localhost:11434" "temperature": 0.7 // ⚙️ Default: 0.7 } } }, "mcpServers": { "server-name": { "command": "npx", // 🔧 Optional (required if not using url) "args": ["-y", "@modelcontextprotocol/server"], // 🔧 Optional "url": "http://localhost:3000/sse", // 🔧 Optional (required if not using command) "transport": "stdio", // ⚙️ Smart default: "stdio" for command, "sse" for url "env": { // 🔧 Optional "DEBUG": "true" }, "disabled": false, // ⚙️ Default: false "initializeTimeoutSeconds": 30, // ⚙️ Default: 30 "tools": { "allowList": ["tool1", "tool2"], // 🔧 Optional "blockList": ["dangerous_tool"] // 🔧 Optional } } }, "rag": { "enabled": false, // ⚙️ Default: false "provider": "simple", // ⚙️ Default: "simple" "chunkSize": 1000, // ⚙️ Default: 1000 "providers": { "simple": { "databasePath": "./rag.db" // ⚙️ Default: "./rag.db" }, "openai": { "indexName": "slack-mcp-rag", // ⚙️ Default: "slack-mcp-rag" "vectorStoreId": "vs_existing_store_id", // 🔧 Optional: reuse existing vector store "dimensions": 1536, // ⚙️ Default: 1536 "similarityMetric": "cosine", // 🔧 Optional: cosine, euclidean "maxResults": 10 // ⚙️ Default: 10 search results } } }, "timeouts": { "httpRequestTimeout": "30s", // ⚙️ Default: 30s "mcpInitTimeout": "30s", // ⚙️ Default: 30s "toolProcessingTimeout": "3m", // ⚙️ Default: 3m "bridgeOperationTimeout": "3m", // ⚙️ Default: 3m "pingTimeout": "5s", // ⚙️ Default: 5s "responseProcessing": "1m" // ⚙️ Default: 1m }, "retry": { "maxAttempts": 3, // ⚙️ Default: 3 attempts "baseBackoff": "500ms", // ⚙️ Default: 500ms "maxBackoff": "5s", // ⚙️ Default: 5s "mcpReconnectAttempts": 5, // ⚙️ Default: 5 attempts "mcpReconnectBackoff": "1s" // ⚙️ Default: 1s }, "monitoring": { "enabled": true, // ⚙️ Default: true "metricsPort": 8080, // ⚙️ Default: 8080 "loggingLevel": "info" // ⚙️ Default: "info" } } ``` **Legend:** * ⭐ **Required**: Must be provided or application will fail to start * ⚙️ **Smart Default**: Automatically set if not specified * 🔧 **Optional**: Can be omitted, no default value ## Configuration Examples by User Type ### 1. Quick Start User (5 minutes) **Need**: Get up and running in minutes with minimal setup ```json { "$schema": "https://github.com/tuannvm/slack-mcp-client/schema/config-schema.json", "version": "2.0", "slack": { "botToken": "${SLACK_BOT_TOKEN}", "appToken": "${SLACK_APP_TOKEN}" }, "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"] } } } ``` ### 2. Production User (15 minutes) **Need**: Robust configuration with monitoring and security ```json { "$schema": "https://github.com/tuannvm/slack-mcp-client/schema/config-schema.json", "version": "2.0", "slack": { "botToken": "${SLACK_BOT_TOKEN}", "appToken": "${SLACK_APP_TOKEN}" }, "llm": { "provider": "openai", "useNativeTools": true, "customPrompt": "You are a DevOps assistant." }, "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"], "tools": { "allowList": ["read_file", "write_file", "list_directory"] } }, "api-server": { "url": "https://api.company.com/mcp", "transport": "sse", "tools": { "allowList": ["weather", "search"] } } }, "rag": { "enabled": true, "provider": "openai" }, "monitoring": { "enabled": true, "metricsPort": 8080, "loggingLevel": "info" } } ``` ### 3. Advanced User (30 minutes) **Need**: Maximum customization and control ```json { "$schema": "https://github.com/tuannvm/slack-mcp-client/schema/config-schema.json", "version": "2.0", "slack": { "botToken": "${SLACK_BOT_TOKEN}", "appToken": "${SLACK_APP_TOKEN}" }, "llm": { "provider": "anthropic", "useNativeTools": true, "useAgent": true, "customPromptFile": "custom-prompt.txt", "providers": { "openai": { "model": "gpt-4o", "apiKey": "${OPENAI_API_KEY}", "temperature": 0.7, "maxTokens": 2000 }, "anthropic": { "model": "claude-3-5-sonnet-20241022", "apiKey": "${ANTHROPIC_API_KEY}", "temperature": 0.5 }, "ollama": { "model": "llama3.1:8b", "baseUrl": "http://localhost:11434", "temperature": 0.8 } } }, "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"], "env": { "DEBUG": "true" }, "initializeTimeoutSeconds": 60, "tools": { "blockList": ["delete_file"] } }, "kubernetes": { "command": "kubectl-mcp-server", "args": ["--context", "production"], "transport": "stdio", "tools": { "allowList": ["get_pods", "get_services", "describe_pod"] } } }, "rag": { "enabled": true, "provider": "openai", "chunkSize": 1500, "providers": { "openai": { "indexName": "company-knowledge-base", "dimensions": 1536 } } }, "monitoring": { "enabled": true, "metricsPort": 8080, "loggingLevel": "debug" } } ``` ## Environment Variables ### Required Environment Variables ```bash # Slack configuration SLACK_BOT_TOKEN=xoxb-your-bot-token SLACK_APP_TOKEN=xapp-your-app-token # LLM provider API keys (set based on your provider) OPENAI_API_KEY=sk-your-openai-key ANTHROPIC_API_KEY=sk-ant-your-anthropic-key OLLAMA_BASE_URL=http://localhost:11434 ``` ### Optional Environment Variable Overrides ```bash # Application configuration overrides LLM_PROVIDER=anthropic MONITORING_ENABLED=true CUSTOM_PROMPT="You are a DevOps assistant." ``` ## Slack App Setup ### Token Types The application requires two types of tokens: 1. **Bot Token** (`SLACK_BOT_TOKEN`): Starts with `xoxb-` 2. **App-Level Token** (`SLACK_APP_TOKEN`): Starts with `xapp-` ### Required Bot Token Scopes Add these OAuth scopes to your Bot Token in the "OAuth & Permissions" section: **Essential Scopes:** * `app_mentions:read` - Allows the bot to receive mention events * `chat:write` - Allows the bot to post messages * `im:history` - Allows the bot to read direct messages * `im:read` - Allows the bot to receive DM events **Additional Scopes (for full functionality):** * `channels:history` - Allows reading public channel history * `groups:history` - Allows reading private channel history * `mpim:history` - Allows reading multi-person IM history ### App-Level Token Configuration 1. Go to the "Socket Mode" section in your Slack app settings 2. Enable Socket Mode 3. Create an App-Level Token with the `connections:write` scope 4. Use this token for the `SLACK_APP_TOKEN` environment variable ### Event Subscriptions In the "Event Subscriptions" section: 1. Turn ON Event Subscriptions 2. Under "Subscribe to bot events", add these event subscriptions: * `message.im` - For direct messages to your app * `app_mention` - For mentions of your app in channels ### App Home Configuration In the "App Home" section: 1. Enable the Messages Tab 2. Turn ON "Allow users to send Slash commands and messages from the messages tab" ## Custom Prompt Configuration ### Option 1: Simple Inline Prompt (Most Common) ```json { "llm": { "provider": "openai", "customPrompt": "You are a helpful DevOps assistant focused on Kubernetes." } } ``` ### Option 2: File-Based Prompt (For Long Prompts) ```json { "llm": { "provider": "openai", "customPromptFile": "custom-prompt.txt" } } ``` **Priority**: `customPromptFile` takes precedence over `customPrompt` if both are set ## Kubernetes Deployment ### Basic Helm Configuration ```yaml # values.yaml app: config: llm: provider: "openai" customPrompt: "You are a DevOps assistant." secrets: create: true data: SLACK_BOT_TOKEN: "" # Set via external secret manager SLACK_APP_TOKEN: "" # Set via external secret manager OPENAI_API_KEY: "" # Set via external secret manager ANTHROPIC_API_KEY: "" # Set via external secret manager configMap: create: true data: config.json: | { "$schema": "https://github.com/tuannvm/slack-mcp-client/schema/config-schema.json", "version": "2.0", "slack": { "botToken": "${SLACK_BOT_TOKEN}", "appToken": "${SLACK_APP_TOKEN}" }, "llm": { "provider": {{ .Values.app.config.llm.provider | quote }}, "customPrompt": {{ .Values.app.config.llm.customPrompt | quote }} } } ``` ### Security Best Practices * Use **Secrets** for tokens and API keys * Use **ConfigMaps** for non-sensitive configuration * Secret key names must match environment variable names in config file * Consider using external secret management (AWS Secrets Manager, Vault, etc.) ## Configuration Validation ### Runtime Validation The application validates configuration after loading environment variables and applying defaults: ```bash # Test configuration ./slack-mcp-client --config-validate # Migrate from legacy format ./slack-mcp-client --migrate-config ``` ### Common Validation Errors **Missing Required Fields:** ```json { "error": "Configuration validation failed", "details": "SLACK_BOT_TOKEN environment variable not set", "suggestion": "Set SLACK_BOT_TOKEN environment variable with your Slack bot token" } ``` **Invalid Provider Configuration:** ```json { "error": "Configuration validation failed", "details": "LLM provider 'openai' not configured", "suggestion": "Add OpenAI configuration to llm.providers.openai section" } ``` ## Migration from Legacy Format The application supports both automatic detection and manual migration from legacy formats: ### Automatic Detection (Recommended) Legacy configurations are automatically detected and converted at runtime: * **Legacy `mcp-servers.json`**: Automatically detected by presence of `mcpServers` field without `version`, `slack`, or `llm` fields * **Snake\_case format**: Legacy snake\_case field names are automatically converted during loading * **No action required**: Existing configurations continue to work without changes ### Manual Migration For permanent migration to the new format: 1. **Automatic Migration**: Run `./slack-mcp-client --migrate-config --config legacy-config.json` 2. **Manual Migration**: Use the provided examples as templates 3. **Validation**: Test with `--config-validate` before deployment ### Migration Benefits * **IDE Support**: JSON schema provides autocomplete and validation * **Modern Format**: camelCase follows current JSON API conventions * **Better Documentation**: Inline field descriptions via schema ## Troubleshooting ### Common Issues **"Sending messages to this app has been turned off"** * Check App Home settings * Verify Event Subscriptions are configured * Ensure app is installed with required scopes **Configuration validation failures** * Check environment variables are set * Validate JSON syntax * Ensure required fields are present **MCP server connection issues** * Check server commands and arguments * Verify network connectivity for URL-based servers * Review server logs for initialization errors ### Debug Mode Enable debug logging for detailed troubleshooting: ```json { "monitoring": { "enabled": true, "loggingLevel": "debug" } } ``` ## Best Practices 1. **Start Simple**: Begin with minimal configuration, add complexity as needed 2. **Use Environment Variables**: Never hardcode secrets in configuration files 3. **Validate Early**: Use `--config-validate` to catch issues before deployment 4. **Monitor Usage**: Enable monitoring to track performance and costs 5. **Version Control**: Keep configuration examples in version control 6. **Document Changes**: Update configuration documentation when adding new features ## Advanced Configuration For AI/ML-specific configuration options including enhanced LLM providers, advanced RAG settings, and production AI features, see the [AI Configuration Guide](https://github.com/tuannvm/slack-mcp-client/blob/main/docs/configuration-ai.md). ## Support For configuration issues: 1. Check the troubleshooting section above 2. Validate your configuration with `--config-validate` 3. Review application logs for specific error messages 4. Consult the [AI Configuration Guide](https://github.com/tuannvm/slack-mcp-client/blob/main/docs/configuration-ai.md) for advanced features --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tuannvm.com/slack-mcp-client/docs/configuration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.