# Implementation Notes: Slack MCP Client ## Current State 1. **Project Goal:** Build a Slack bot that interacts with external tools and data sources via the Model Context Protocol (MCP), implemented in Go. 2. **Architecture:** See `README.md` for the high-level design. The core components are the Slack integration, the Go application (`slack-mcp-client`), and external MCP servers. 3. **Slack Integration:** Full-featured Slack client using `slack-go/slack` with Socket Mode for secure communication, supporting mentions, direct messages, and rich Block Kit formatting. 4. **MCP Client Configuration:** Uses a flexible configuration approach for multiple MCP servers through `mcp-servers.json` following the schema defined in `mcp-schema.json`. 5. **LLM Integration:** Multi-provider LLM support through a factory pattern with LangChain (v0.1.14) as the gateway, supporting OpenAI, Anthropic, and Ollama providers. ## Architecture & Implementation ### Core Components 1. **Configuration System (`internal/config/`)** * Configuration loaded from environment variables for Slack credentials and LLM settings * MCP server configurations from JSON file following the schema with `mcpServers` property * Each server defined with `command`, `args`, `mode`, and optional `env` properties * Support for both HTTP/SSE and stdio transport modes * LLM provider configuration with factory pattern support 2. **Slack Client (`internal/slack/`)** * Connects to Slack using Socket Mode for secure, firewall-friendly communication * Handles app mentions and direct messages * Processes user prompts and forwards them to LLM providers * Advanced message formatting with Block Kit support through `internal/slack/formatter/` * Returns responses and tool results back to Slack channels/DMs with rich formatting 3. **MCP Client (`internal/mcp/`)** * Support for multiple transport protocols: * **HTTP/SSE (Server-Sent Events):** For real-time communication with web-based MCP servers * **stdio:** For local development with command-line tools * Dynamic initialization with proper command line argument parsing * Runtime discovery of available tools from MCP servers * Uses mcp-go v0.42.0 with enhanced HTTP transport and session management 4. **LLM Provider System (`internal/llm/`)** * Factory pattern for provider registration and initialization * Registry system for managing multiple LLM providers * Configuration-driven provider setup * LangChain (v0.1.14) as the unified gateway for all providers * Support for OpenAI, Anthropic, and Ollama providers with enhanced stability * Streaming memory and goroutine leak fixes (v0.1.14) * Improved agent parsing and error handling * Availability checking and fallback mechanisms 5. **Handler System (`internal/handlers/`)** * Interface-based design for tool handlers * LLM-MCP Bridge for detecting tool invocation patterns * Registry for centralized handler management * Support for both structured JSON tool calls and natural language detection 6. **Common Utilities (`internal/common/`)** * Structured logging with hierarchical loggers (`internal/common/logging/`) * Standardized error handling (`internal/common/errors/`) * HTTP client with retry logic (`internal/common/http/`) * Shared types and utilities ### MCP Server Configuration MCP servers are configured using a JSON file following this structure: ```json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/tuannvm/Projects", "/Users/tuannvm/Downloads" ], "env": { "DEBUG": "mcp:*" } }, "github": { "command": "github-mcp-server", "args": ["stdio"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token" } }, "web-server": { "mode": "http", "url": "http://localhost:8080/mcp", "initialize_timeout_seconds": 30 } } } ``` ### LLM Provider Configuration LLM providers are configured in the main configuration with factory pattern support: ```yaml llm_provider: "openai" # Which provider to use llm_providers: openai: type: "openai" model: "gpt-4.1" # Latest: 21.4% improvement in coding (Oct 2025) # api_key loaded from OPENAI_API_KEY env var ollama: type: "ollama" model: "llama3.3" # Latest: 70B state-of-the-art (2025) base_url: "http://localhost:11434" anthropic: type: "anthropic" model: "claude-sonnet-4.5" # Latest: Best for coding and agents (Sept 2025) # api_key loaded from ANTHROPIC_API_KEY env var ``` ### Main Process Flow 1. **Start-up Sequence:** * Parse command-line arguments with debug flags * Load environment variables and configuration file * Initialize structured logging system * Initialize LLM provider registry with configured providers * Initialize MCP clients for each configured server * Connect to Slack using Socket Mode 2. **Message Processing:** * Receive messages from Slack (mentions or DMs) * Forward messages to configured LLM provider through registry * Process LLM response through LLM-MCP Bridge with enhanced parsing (v0.1.14) * If tool invocation is detected: * Execute appropriate MCP tool call * Format tool results with Slack-compatible formatting * Return final response to Slack with Block Kit formatting * Streaming responses now have memory and goroutine leak protection (v0.1.14) 3. **Tool Detection & Execution:** * JSON pattern matching for structured tool invocations * Regular expression matching for natural language requests * Validate against available tools discovered from MCP servers * Execute tool call with appropriate parameters * Process and format tool results with rich Slack formatting ### Slack Message Formatting The application includes a comprehensive Slack formatting system: 1. **Automatic Format Detection:** * Plain text with mrkdwn formatting * JSON Block Kit structures * Structured data converted to Block Kit 2. **Markdown Support:** * Automatic conversion from standard Markdown to Slack mrkdwn * Support for bold, italic, strikethrough, code blocks, lists, links * Quoted string conversion to inline code blocks 3. **Block Kit Support:** * Headers, sections, fields, actions, dividers * Automatic field truncation for Slack limits * Rich interactive components ### Debugging & Troubleshooting 1. **Logging System:** * Structured logging with different levels (Debug, Info, Warn, Error) * Component-specific loggers for better tracking * Environment variable support for log level configuration 2. **MCP Transport Issues:** * Resolved stdio transport issues by sequential processing * Proper timeout handling for server initialization * Support for both HTTP/SSE and stdio transports 3. **Configuration Validation:** * Automatic fallback to available providers * Server disable/enable functionality * Environment variable overrides ### Future Improvements 1. **Enhanced Tool Discovery** * Better caching of discovered tools * Dynamic tool refresh capabilities * Tool usage analytics 2. **Advanced LLM Features** * Function calling support for compatible providers * Conversation context management * Multi-turn conversation support 3. **Monitoring & Observability** * Metrics collection for tool usage * Performance monitoring * Health check endpoints 4. **Security Enhancements** * Tool permission controls * User-based access restrictions * API key rotation support --- # 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/implementation.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.