Skip to content

implementation.md

Latest commit

 

History

History
199 lines (164 loc) · 7.51 KB

implementation.md

File metadata and controls

199 lines (164 loc) · 7.51 KB

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:

{
  "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:

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