How to Build and Deploy the ChatMCP Web Version to GitHub Pages

You can deploy the ChatMCP web client to GitHub Pages either automatically via the included GitHub Actions workflow or manually using Flutter's build web command combined with a force-push to the gh-pages branch.

ChatMCP is a Flutter-based multi-platform AI chat client maintained in the daodao97/chatmcp repository. The web target compiles to static assets (HTML, JavaScript, and CSS) that any static-site host can serve, and the project includes a ready-made CI pipeline that handles the entire deployment process.

Architecture Overview

The deployment pipeline consists of three integrated layers. Flutter SDK generates a pure-web build in the build/web/ directory, producing an index.html entry point that loads the compiled Dart code. The build command flutter build web --base-href /chatmcp/ configures the app to run under the /chatmcp/ sub-path, which matches the repository's GitHub Pages URL structure at https://daodao97.github.io/chatmcp.

GitHub Actions automates the process through .github/workflows/build-web.yml. This workflow installs Flutter, fetches dependencies, builds the release bundle, and uses peaceiris/actions-gh-pages@v4 to publish the contents of build/web/ to the gh-pages branch. GitHub Pages then serves these static files directly from that branch.

Prerequisites

Before building or deploying, ensure your environment meets these requirements:

• Flutter SDK (≥ 3.32.5) installed and available on your system PATH. The repository README provides platform-specific installation instructions for macOS, Linux, and Windows.
• A GitHub Personal Access Token with repo scope. The automated workflow expects this as the MY_GITHUB_TOKEN repository secret.

Automated CI Deployment

The recommended approach uses the project's built-in workflow to deploy on every push to main.

When you push commits to the main branch, the Build & deploy workflow in .github/workflows/build-web.yml triggers automatically. The job runs on Ubuntu, executes flutter build web --base-href /chatmcp/, uploads the build/web/ directory as an artifact, and deploys it to the gh-pages branch. No manual intervention is required after the initial secret configuration.

# .github/workflows/build-web.yml (key steps)

- name: Build release project
  run: flutter build web --base-href /chatmcp/

- name: Deploy to gh-pages
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.MY_GITHUB_TOKEN }}
    publish_dir: build/web

After the workflow completes, GitHub Pages serves the updated site at your repository's Pages URL within minutes.

Manual Deployment

If you need to deploy outside of CI or troubleshoot locally, build and push manually using Git commands.

First, compile the production bundle:

flutter pub get
flutter build web --base-href /chatmcp/

This generates static files in build/web/. Next, create an orphan gh-pages branch, replace its contents with the build output, and force-push:

# Switch to orphan branch (create if missing)

git checkout --orphan gh-pages

# Clean the branch

git rm -rf .

# Copy build artifacts

cp -r build/web/* .

# Commit and deploy

git add .
git commit -m "Deploy ChatMCP web version"
git push origin gh-pages --force

# Return to main branch

git checkout main

GitHub Pages will detect the new commit on gh-pages and update the live site.

Local Development and Testing

To verify changes before deploying, run the web app locally with hot-reload enabled:

# Install dependencies

flutter pub get

# Launch in Chrome for development

flutter run -d chrome

For a production preview that matches the GitHub Pages environment exactly, use the release build command locally and serve the build/web/ directory with any static file server.

Understanding the Base Href Configuration

The --base-href /chatmcp/ parameter is critical for correct asset loading. Because GitHub Pages serves project repositories under a sub-directory (https://<user>.github.io/<repo>/), Flutter must generate relative URLs that include this path. Without this flag, the browser requests assets from the domain root, resulting in 404 errors. The CI workflow and manual commands both include this flag to ensure CSS and JavaScript bundles load correctly.

Summary

• ChatMCP compiles to static web assets using Flutter's build web command.
• The .github/workflows/build-web.yml pipeline automates builds and publishes to the gh-pages branch using peaceiris/actions-gh-pages@v4.
• Always use --base-href /chatmcp/ when building to match the GitHub Pages URL structure.
• You can deploy automatically on every push to main or manually via git commands when needed.
• The Makefile in the repository includes a build-web target as a shortcut for the CI-style build command.

Frequently Asked Questions

Why does the build require the --base-href flag?

GitHub Pages serves project repositories under a sub-path (e.g., /chatmcp/), not at the domain root. The --base-href /chatmcp/ parameter tells Flutter to prefix all asset URLs in index.html with this path, ensuring that JavaScript and CSS files load from the correct location rather than returning 404 errors.

What Flutter version is required to build ChatMCP?

The repository requires Flutter ≥ 3.32.5. You can verify your installation by running flutter --version. Building with older versions may result in compilation errors or missing web-specific features used by the application.

How do I update the deployed site after making changes?

If you are using the automated workflow, simply push your changes to the main branch. The GitHub Action will rebuild and redeploy automatically. For manual updates, rerun the Flutter build command and repeat the git checkout, copy, commit, and force-push steps to the gh-pages branch.

Can I deploy the web version to hosts other than GitHub Pages?

Yes. The build/web/ directory contains standard static files (HTML, JS, CSS) that any static hosting provider (Vercel, Netlify, Cloudflare Pages, or an Nginx server) can serve. When deploying to a root domain or different sub-path, adjust or omit the --base-href flag to match your hosting configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}