Prerequisites

1. Install Dependencies

npm install

Build the TypeScript aggregator

npm run build

4. Build and Preview the Site

```bash

5. Build for Production

```bash hugo --minify

GitHub Actions Setup

The repository includes a GitHub Actions workflow that automatically: 1. Runs data aggregation every 6 hours 2. Commits updated data to the repository 3. Builds and deploys the Hugo site to GitHub Pages

Quick Start

Option 1: Snap (recommended - always up to date)

sudo snap install hugo

Option 2: apt (may be older version)

sudo apt update sudo apt install -y hugo

Option 3: Download latest release directly (if you need extended version)

CLI Options

npm run aggregate -- [options]

Options:
  --dry-run, -n    Compute metrics but don't write files
  --verbose, -v    Enable verbose logging
  --owner <name>   Repository owner (default: modelcontextprotocol)
  --repo <name>    Repository name (default: modelcontextprotocol)
  --help, -h       Show help message

Setting Up GitHub Actions

Step 1: Create a Fine-Grained Personal Access Token

Since the workflow fetches data from external repositories (modelcontextprotocol/modelcontextprotocol and modelcontextprotocol/access), you need a PAT with cross-repo access.

1. Go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens 2. Click "Generate new token" 3. Configure the token: - Token name: MCP Dashboard GitHub Actions - Expiration: 90 days (or longer; you'll need to rotate it when it expires) - Resource owner: Your username - Repository access: Select "Public Repositories (read-only)" - Permissions: No additional permissions needed 4. Click "Generate token" 5. Copy the token

Step 2: Add the Token as a Repository Secret

1. Go to your repository's Settings > Secrets and variables > Actions
2. Click New repository secret
3. Name: GH_PAT
4. Value: Paste your personal access token
5. Click Add secret

Step 3: Enable GitHub Pages

1. Go to your repository's Settings > Pages 2. Under Build and deployment: - Source: GitHub Actions 3. Save

Step 4: Run the Workflow

The workflow runs automatically on: - Schedule: Every 6 hours (0 */6 * * *) - Manual trigger: Go to Actions > Aggregate Repository Data > Run workflow

To trigger your first run: 1. Go to the Actions tab 2. Select "Aggregate Repository Data" 3. Click "Run workflow" 4. Select the branch and click "Run workflow"

"GITHUB_TOKEN or GH_PAT environment variable is required"

Set your GitHub token before running the aggregator:

export GITHUB_TOKEN=ghp_your_token_here

Hugo "Unable to locate config file"

Make sure you're running Hugo from the repository root directory where hugo.toml is located.

Workflow Permissions

The workflow requires these permissions (already configured in aggregate.yml): - contents: write - To commit data file updates - pages: write - To deploy to GitHub Pages - id-token: write - For GitHub Pages deployment authentication

GitHub Actions workflow fails

1. Check that GH_PAT secret is set in repository settings
2. Verify the token has "Public Repositories (read-only)" access
3. Check if the token has expired (fine-grained tokens have expiration dates)
4. Check the Actions log for specific error messages

Troubleshooting