DOCSEARCHbyAlgolia
Submit Docs

chatmcp Documentation

repository·main·Indexed 24 days ago

https://github.com/daodao97/chatmcp

A cross-platform AI chat client supporting LLM providers such as OpenAI, Claude, Ollama, and DeepSeek. It integrates with the Model Context Protocol (MCP) via stdio and SSE transports, featuring OAuth 2.0 + PKCE auto-discovery for remote servers. The documentation covers installation for macOS, Linux, and Android, data storage management, and developer guides for iOS launch screen customization and ToastUtils notification implementation.

Tokens
10.2K
Snippets
9
Records
60
Agent score
79%

What's inside chatmcp

  1. Manage pagination states and UI feedback

    main

    Effective pagination requires managing several state variables to prevent duplicate requests and provide user feedback.

    Required State Variables:

    • _currentPage: The current page number (starting from 1).
    • hasMoreChats: A boolean indicating if more data is available to load.
    • isLoadingChats: A boolean indicating if a network request is currently active.
    • _isLoadingMore: A local flag used to prevent duplicate triggers during rapid scrolling.

    UI Feedback States:

    • Loading: Display a spinner animation with the text "正在下载数据..." (Downloading data...).
    • No More Data: Display the message "—— 没有更多了 ——" (No more data) when hasMoreChats is false.
    • Ready to Scroll: Ensure sufficient whitespace/footer height (recommended ~50px) to allow the ScrollController to detect the trigger distance.

  2. Toast positioning and styling defaults

    main

    By default, all toasts generated by ToastUtils follow these visual and positional rules:

    • Positioning: Toasts use Alignment(0.0, -0.8). This centers them horizontally (0.0) and places them near the top of the screen (-0.8) to avoid being obscured by the status bar while maintaining a safe distance from the edge.
    • Text Styling: Text is white, with a font size of 14px and medium weight.
    • Responsiveness: The design is responsive and adapts to different screen sizes automatically.

  3. Supported MCP server transport modes

    main

    ChatMCP supports two primary transport modes for the Model Context Protocol (MCP):

    1. stdio MCP server: Uses standard input/output for communication. This is typically used when the MCP server is run as a local process by an MCP client (like Claude Desktop).
    2. sse MCP server: Uses Server-Sent Events (SSE) for communication. This is used when the MCP server is hosted over HTTP, allowing for remote connections.

  4. How OAuth 2.0 + PKCE Auto-Discovery works for MCP Servers

    main

    The system provides automatic OAuth 2.0 authentication for remote MCP servers that protect their endpoints. It uses a three-phase lifecycle to manage authentication without manual credential entry:

    1. Discovery Phase: When an MCP server URL is provided, the system checks for /.well-known/oauth-authorization-server (RFC 8414) to detect OAuth requirements. It attempts dynamic client registration (RFC 7591) or falls back to public client mode.
    2. Authentication Phase: The system opens an OAuth authorization popup, generates PKCE (Proof Key for Code Exchange) credentials (RFC 7636), processes the callback with state validation, and exchanges the authorization code for an access token.
    3. Usage Phase: The system automatically attaches Authorization: Bearer <token> to MCP requests and manages token refreshes and expiry automatically.

    This allows seamless integration with services like Notion MCP and Atlassian MCP.

  5. How to use ChatMCP

    main
    1. Configure LLM: Go to the 'Settings' page to configure your LLM API keys and endpoints.
    2. Install MCP Servers: Go to the 'MCP Servers' page to install desired MCP servers.
    3. Chat: Start a conversation with your installed MCP servers (supports both stdio and sse transport).

    Prerequisites: Ensure uvx or npx is installed on your system.

    • For uvx: brew install uv
    • For npx: brew install node

  6. Set up development environment and Git hooks

    main

    ChatMCP uses Dart formatting enforced by Git pre-commit hooks. To ensure code style consistency, follow these steps.

    1. Install Git Hooks

    Run this command once after cloning the repository:

    make setup-git-hooks

    Alternatively, configure them manually:

    git config core.hooksPath .githooks
chmod +x .githooks/pre-commit

    2. Environment Requirements

    Ensure either the Dart SDK or Flutter is in your PATH.

    3. Running the App

    flutter pub get
flutter run -d macos

  7. Set up development environment for chatmcp

    main

    To develop chatmcp, ensure you have the Flutter SDK installed.

    Install dependencies:

    flutter pub get

    Run the application:

    • Linux: flutter run -d linux
    • macOS: flutter run -d macos
    • Windows: flutter run -d windows
    • Android: flutter run -d "Pixel ..." (replace with your device name)

    Git Hooks (Mandatory): This project requires Dart formatting before every commit. To set up the pre-commit hooks automatically:

    make setup-git-hooks

    Alternatively, install them manually:

    git config core.hooksPath .githooks
chmod +x .githooks/pre-commit

  8. Use ToastUtils for message notifications

    main

    The ToastUtils class provides a unified way to display toast notifications with different severity levels. Each level uses specific color coding and default durations to help users quickly identify the nature of the message.

    Prerequisites: Ensure that BotToast is correctly configured in your main.dart file before using ToastUtils.

    Available Notification Levels:

    • Error: Red background (Colors.red.shade600), defaults to 5 seconds. Use for operation failures or system errors.
    • Warning: Orange background (Colors.orange.shade600), defaults to 4 seconds. Use for network issues or permission warnings.
    • Info: Blue background (Colors.blue.shade600), defaults to 3 seconds. Use for status updates or progress notifications.
    • Success: Green background (Colors.green.shade600), defaults to 3 seconds. Use for successful operations or completions.
    import '../utils/toast.dart';

// Error level
ToastUtils.error('操作失败，请重试');

// Warning level
ToastUtils.warn('网络连接不稳定');

// Info level
ToastUtils.info('正在处理您的请求');

// Success level
ToastUtils.success('操作成功完成');

// Custom style
ToastUtils.custom(
  message: '自定义消息',
  color: Colors.purple,
  duration: Duration(seconds: 2),
);

  9. Customize the iOS launch screen assets

    main

    To change the launch screen image for the iOS version of the application, you can use one of two methods:

    1. Direct File Replacement: Replace the existing image files directly within the ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory with your own assets.
    2. Xcode Interface:
      • Open the iOS project in Xcode by running open ios/Runner.xcworkspace from your terminal.
      • In the Xcode Project Navigator, navigate to Runner/Assets.xcassets.
      • Drag and drop your desired images into the asset catalog to replace the current launch images.
    open ios/Runner.xcworkspace

  10. Install ChatMCP on various platforms

    main

    ChatMCP is a cross-platform AI chat client. You can install it on the following platforms:

    • macOS: Download from Releases.
    • Windows: Download from Releases.
    • Linux: Download from Releases. (Note: Requires specific runtime dependencies listed in the Linux section).
    • iOS: Join via TestFlight.
    • Android: Download from Releases.
    • Web: Run directly in your browser via GitHub Pages. (Note: Uses local storage for chat history and settings).

  11. Configure Android signing for local development

    main

    To sign ChatMcp Android applications locally, follow these three steps:

    1. Generate a signing key: Run the provided script to create a keystore. The script will prompt you for a filename (default: chatmcp-release-key.jks), an alias (default: chatmcp), passwords, and certificate information.
    2. Configure environment variables: The script automatically generates an android/signing.env file. Ensure this file contains the following keys:
      • SIGNING_STORE_PATH
      • SIGNING_KEY_ALIAS
      • SIGNING_STORE_PASSWORD
      • SIGNING_KEY_PASSWORD
    3. Build the signed binary: Use Flutter commands to generate the signed output.

    Note: Never commit your keystore file to version control.

  12. Basic usage: Configure LLM and MCP Servers

    main

    To start chatting with Model Context Protocol (MCP) servers, follow these steps:

    1. Open the Setting page to configure your LLM API Key and Endpoint.
    2. Navigate to the MCP Server page to install an MCP Server.
    3. Start chatting with the installed MCP Server (supports both stdio and sse transport modes).