Hugo MCP Server

Hugo MCP Server

Hugo 静的サイトジェネレーターを管理するための強力な MCP（Model Context Protocol）サーバーです。このサーバーは、Hugo サイトの作成、管理、デプロイに必要な包括的なツールを提供します。

目次

• インストール
• 使い方
• ツール
  • 環境セットアップツール
  • サイト管理ツール
  • テーマ管理ツール
  • コンテンツ管理ツール
  • プレビューとビルドのツール
• ワークフローの完全な例
• トラブルシューティング

インストール

前提条件

• Python 3.10+
• uv（Python パッケージマネージャー）
• Git（強く推奨）

Hugo MCP Server のインストール

1. リポジトリをクローンします。

   git clone https://github.com/sunnycloudyang/hugo-mcp.git
   

2. サーバーを設定に追加します（事前に uv がインストールされていることを確認してください）。

   {
        "mcpServers": {
            "hugo-mcp": {
                "command": "uv",
                "args": [
                    "--directory",
                    "/ABSOLUTE/PATH/TO/PARENT/FOLDER/hugo-mcp",
                    "run",
                    "main.py"
                ]
            }
        }
    }
   

   "/ABSOLUTE/PATH/TO/PARENT/FOLDER/hugo-mcp" をインストール先のパスに置き換えてください。

3. この MCP サーバーを有効にして、試してみましょう！

使い方

Hugo MCP サーバーは、Hugo サイトの管理に使用できるツール一式を提供します。各ツールには固有のパラメーターがあり、構造化された応答を返します。

基本的な使い方

1. 必要に応じて、サーバーを手動で起動します。

   uv run main.py
   

2. MCP クライアントを使用してサーバーに接続します。

3. ツールを使用して Hugo サイトを管理します。

ツール

環境セットアップツール

check_hugo_installation

説明：Hugo がインストールされているか確認し、バージョンを取得します。

パラメーター：なし

戻り値：

{
  "status": "success",
  "version": "Hugo Static Site Generator v0.92.0/extended linux/amd64 BuildDate=unknown"
}

エラー応答：

{
  "status": "error",
  "message": "Hugo is not installed or not in PATH"
}

前提条件：なし

成功後のアクション：なし

失敗後のアクション：install_hugo ツールを使用して Hugo をインストールします。

install_hugo

説明：現在の OS に適した方法で Hugo をインストールします。

パラメーター：

• version（任意）：インストールする Hugo のバージョンです。既定値は "latest" です。

戻り値：

{
  "status": "success",
  "message": "Hugo installed via Homebrew"
}

エラー応答：

{
  "status": "error",
  "message": "Installation failed: Command 'brew install hugo' returned non-zero exit status 1."
}

前提条件：適切なパッケージマネージャー（Homebrew、apt、dnf、yum）がインストールされている必要があります。

成功後のアクション：Hugo がインストールされ、使用できる状態になります。

失敗後のアクション：手動でのインストールが必要になる場合があります。

check_go_installation

説明：Go がインストールされているか確認し、バージョンを取得します。

パラメーター：なし

戻り値：

{
  "status": "success",
  "version": "go version go1.17.5 darwin/amd64"
}

エラー応答：

{
  "status": "error",
  "message": "Go is not installed or not in PATH"
}

前提条件：なし

成功後のアクション：なし

失敗後のアクション：install_go ツールを使用して Go をインストールします。

install_go

説明：現在の OS に適した方法で Go をインストールします。

パラメーター：

• version（任意）：インストールする Go のバージョンです。既定値は "latest" です。

戻り値：

{
  "status": "success",
  "message": "Go installed via Homebrew"
}

エラー応答：

{
  "status": "error",
  "message": "Installation failed: Command 'brew install go' returned non-zero exit status 1."
}

前提条件：適切なパッケージマネージャー（Homebrew、apt、dnf、yum）がインストールされている必要があります。

成功後のアクション：Go がインストールされ、使用できる状態になります。

失敗後のアクション：手動でのインストールが必要になる場合があります。

check_git_installation

説明：Git がインストールされているか確認し、その設定を取得します。

パラメーター：なし

戻り値：

{
  "status": "success",
  "version": "git version 2.30.1 (Apple Git-130)",
  "user": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "default_branch": "main"
}

エラー応答：

{
  "status": "error",
  "message": "Git is not installed or not in PATH"
}

前提条件：なし

成功後のアクション：なし

失敗後のアクション：install_git ツールを使用して Git をインストールします。

install_git

説明：現在の OS に適した方法で Git をインストールします。

パラメーター：なし

戻り値：

{
  "status": "success",
  "message": "Git installed via Homebrew"
}

エラー応答：

{
  "status": "error",
  "message": "Installation failed: Command 'brew install git' returned non-zero exit status 1."
}

前提条件：適切なパッケージマネージャー（Homebrew、apt、dnf、yum）がインストールされている必要があります。

成功後のアクション：Git がインストールされ、使用できる状態になります。

失敗後のアクション：手動でのインストールが必要になる場合があります。

configure_git

説明：ユーザー名とメールアドレスを指定して Git を設定します。

パラメーター：

• name：設定するユーザー名。
• email：設定するメールアドレス。

戻り値：

{
  "status": "success",
  "message": "Git configured with name 'John Doe' and email '[email protected]'"
}

エラーレスポンス：

{
  "status": "error",
  "message": "Failed to configure Git: Command 'git config --global user.name John Doe' returned non-zero exit status 1."
}

前提条件：Git がインストールされている必要があります。

成功後の動作：指定したユーザー名とメールアドレスで Git が設定されます。

失敗後の動作：手動での設定が必要になる場合があります。

サイト管理ツール

create_site

説明：新しい Hugo サイトを作成します。

パラメーター：

• site_name：作成するサイトの名前。
• theme（任意）：サイトで使用するテーマ。
• force（任意）：ディレクトリがすでに存在する場合に、強制的に作成するかどうか。デフォルトは false です。
• use_example_site（任意）：テーマのサンプルサイトを使用するかどうか。デフォルトは true です。

戻り値：

{
  "status": "success",
  "path": "/path/to/site",
  "theme": "paper",
  "example_site": true,
  "author": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

エラーレスポンス：

{
  "status": "error",
  "message": "Directory 'site' already exists. Use force=True to overwrite."
}

前提条件：Hugo がインストールされている必要があります。

成功後の動作：指定したテーマとサンプルコンテンツを含む新しい Hugo サイトが作成されます。

失敗後の動作：サイトは作成されません。

テーマ管理ツール

list_themes

説明：Hugo の公式テーマウェブサイトから、利用可能な Hugo テーマの一覧を取得します。

パラメーター：なし

戻り値：

{
  "status": "success",
  "themes": [
    {
      "name": "PaperMod",
      "url": "https://github.com/gohugoio/hugoThemes/tree/master/themes/hugo-papermod",
      "image": "https://themes.gohugo.io/themes/hugo-papermod/tn-featured_hu_275191178647f5e7.png"
    },
    {
      "name": "Hugo Blox - Tailwind",
      "url": "https://github.com/gohugoio/hugoThemes/tree/master/themes/blox-tailwind",
      "image": "https://themes.gohugo.io/themes/blox-tailwind/tn-featured_hu_8c1541d303ce3b9b.png"
    }
  ],
  "count": 150
}

エラーレスポンス：

{
  "status": "error",
  "message": "Network error: Connection refused"
}

前提条件：インターネット接続が必要です。

成功後の動作：利用可能なテーマの一覧が返されます。

失敗後の動作：テーマは返されません。

get_theme_details

説明：指定した Hugo テーマの詳細情報を取得します。

パラメーター：

• theme_name：詳細情報を取得するテーマの名前。

戻り値：

{
  "status": "success",
  "theme": {
    "name": "Paper",
    "url": "https://github.com/gohugoio/hugoThemes/tree/master/themes/paper",
    "image": "https://themes.gohugo.io/themes/paper/tn-featured.png",
    "description": "A simple, clean, and responsive Hugo theme for personal blog.",
    "features": [
      "Responsive design",
      "Clean and minimal",
      "Fast and lightweight",
      "SEO friendly"
    ],
    "tags": ["blog", "minimal", "responsive"],
    "github_url": "https://github.com/nanxiaobei/hugo-paper",
    "demo_url": "https://themes.gohugo.io/theme/paper/",
    "installation": "git submodule add https://github.com/nanxiaobei/hugo-paper themes/paper"
  }
}

エラーレスポンス：

{
  "status": "error",
  "message": "Theme 'NonExistentTheme' not found on the Hugo themes website"
}

前提条件：インターネット接続が必要です。

成功後の動作：テーマの詳細情報が返されます。

失敗後の動作：テーマの詳細情報は返されません。

install_theme

説明：Git サブモジュールまたは Hugo モジュールを使用して Hugo テーマをインストールします。

パラメーター：

• site_path：Hugo サイトへのパス。
• theme_name：インストールするテーマの名前。
• theme_url：テーマリポジトリの URL。
• use_modules（任意）：Git サブモジュールの代わりに Hugo モジュールを使用するかどうか。デフォルトは false です。

戻り値：

{
  "status": "success",
  "theme": "paper",
  "method": "git_submodule"
}

エラーレスポンス：

{
  "status": "error",
  "message": "Failed to install theme: Command 'git submodule add https://github.com/nanxiaobei/hugo-paper themes/paper' returned non-zero exit status 1."
}

前提条件：

• Hugo がインストールされている必要があります。
• Git サブモジュールを使用する場合は、Git がインストールされている必要があります。
• Hugo モジュールを使用する場合は、Go がインストールされている必要があります。

成功後の動作：テーマがインストールされ、サイトに設定されます。

失敗後の動作：テーマはインストールされません。

update_theme

説明：インストール済みの Hugo テーマを更新します。

パラメーター：

• site_path：Hugo サイトへのパス。
• theme_name：更新するテーマの名前。
• use_modules（任意）：テーマが Hugo モジュールを使用してインストールされたかどうか。デフォルトは false です。

戻り値：

{
  "status": "success",
  "theme": "paper",
  "method": "git_submodule"
}

エラーレスポンス：

{
  "status": "error",
  "message": "Failed to update theme: Command 'git submodule update --remote themes/paper' returned non-zero exit status 1."
}

前提条件：

• Hugo がインストールされている必要があります。
• Git サブモジュールを使用する場合は、Git がインストールされている必要があります。
• Hugo モジュールを使用する場合は、Go がインストールされている必要があります。
• テーマがすでにインストールされている必要があります。

成功後の動作：テーマが最新バージョンに更新されます。

失敗後の動作：テーマは更新されません。

コンテンツ管理ツール

create_post

説明：新しい Hugo 投稿を作成します。

パラメーター：

• site_path：Hugo サイトへのパス。
• post_title：投稿のタイトル。
• content_type（任意）：投稿のコンテンツタイプ。デフォルトは "posts" です。
• draft（任意）：投稿を下書きにするかどうか。デフォルトは true です。
• date（任意）：投稿の日付。

戻り値：

{
  "status": "success",
  "file": "content/posts/my-first-post.md",
  "draft": true
}

エラーレスポンス：

{
  "status": "error",
  "message": "Site path '/path/to/site' does not exist"
}

前提条件：Hugo がインストールされている必要があります。

成功後の動作：指定したコンテンツタイプのディレクトリに新しい投稿が作成されます。

失敗後の動作：投稿は作成されません。

list_content

説明：Hugo サイトのコンテンツを一覧表示します。

パラメーター：

• site_path：Hugo サイトへのパス。
• content_type（任意）：一覧表示するコンテンツの種類。指定しない場合は、すべてのコンテンツが一覧表示されます。

戻り値：

{
  "status": "success",
  "content": [
    "posts/my-first-post.md",
    "posts/another-post.md",
    "pages/about.md"
  ]
}

エラーレスポンス：

{
  "status": "error",
  "message": "Site path '/path/to/site' does not exist"
}

前提条件：Hugo がインストールされている必要があります。

成功後の動作：コンテンツファイルの一覧が返されます。

失敗後の動作：コンテンツは返されません。

プレビューとビルドのツール

start_preview

説明：Hugo のローカルサーバーを起動します。

パラメーター：

• site_path：Hugo サイトへのパス。
• port（任意）：使用するポート。デフォルトは 1313 です。
• bind（任意）：バインドするアドレス。デフォルトは "127.0.0.1" です。
• build_drafts（任意）：下書きコンテンツをビルドするかどうか。デフォルトは false です。
• build_future（任意）：将来公開されるコンテンツをビルドするかどうか。デフォルトは false です。
• build_expired（任意）：有効期限切れのコンテンツをビルドするかどうか。デフォルトは false です。

戻り値：

{
  "status": "success",
  "url": "http://127.0.0.1:1313",
  "pid": 12345,
  "options": {
    "build_drafts": false,
    "build_future": false,
    "build_expired": false
  }
}

エラーレスポンス：

{
  "status": "error",
  "message": "Site path '/path/to/site' does not exist"
}

前提条件：Hugo がインストールされている必要があります。

成功後の動作：Hugo サーバーが起動し、指定された URL からアクセスできるようになります。

失敗後の動作：サーバーは起動しません。

stop_preview

説明：実行中の Hugo プレビューサーバーを停止します。

パラメーター：

• pid：停止するサーバーのプロセス ID。

戻り値：

{
  "status": "success",
  "message": "Server with PID 12345 stopped"
}

エラーレスポンス：

{
  "status": "error",
  "message": "Process with PID 12345 not found"
}

前提条件：ありません。

成功後の動作：Hugo サーバーが停止します。

失敗後の動作：サーバーは停止しません。

build_site

説明：Hugo サイトを本番環境向けにビルドします。

パラメーター：

• site_path：Hugo サイトへのパス。
• destination（任意）：出力先ディレクトリ。デフォルトは "public" です。
• clean_destination（任意）：ビルド前に出力先ディレクトリをクリーンアップするかどうか。デフォルトは false です。
• minify（任意）：出力を圧縮するかどうか。デフォルトは false です。

戻り値：

{
  "status": "success",
  "destination": "/path/to/site/public",
  "output": "Built in 123 ms"
}

エラーレスポンス：

{
  "status": "error",
  "message": "Site path '/path/to/site' does not exist"
}

前提条件：Hugo がインストールされている必要があります。

成功後の動作：サイトがビルドされ、デプロイできる状態になります。

失敗後の動作：サイトはビルドされません。

deploy_site

説明：Hugo サイトをさまざまなプラットフォームにデプロイします。

パラメーター：

• site_path：Hugo サイトへのパス。
• platform：デプロイ先のプラットフォーム（github-pages、netlify、vercel、custom）。
• destination（任意）：ビルドの出力先ディレクトリ。デフォルトは "public" です。
• branch（任意）：デプロイ先のブランチ。デフォルトは "main" です。
• commit_message（任意）：デプロイ時のコミットメッセージ。デフォルトは "Update site" です。
• remote_url（任意）：カスタムデプロイ用のリモート URL。
• api_key（任意）：デプロイ先プラットフォームの API キー。
• additional_options（任意）：プラットフォーム固有の追加オプション。

戻り値：

{
  "status": "success",
  "platform": "github-pages",
  "branch": "gh-pages",
  "url": "https://username.github.io"
}

エラーレスポンス：

{
  "status": "error",
  "message": "Deployment failed: GitHub Pages deployment failed: Command 'git push origin gh-pages --force' returned non-zero exit status 1."
}

前提条件：

• Hugo がインストールされている必要があります。
• Git がインストールされている必要があります。
• GitHub Pages の場合：Git リポジトリが初期化されている必要があります。
• Netlify の場合：Netlify CLI がインストールされている必要があります（インストールされていない場合は自動的にインストールされます）。
• Vercel の場合：Vercel CLI がインストールされている必要があります（インストールされていない場合は自動的にインストールされます）。

成功後の動作：サイトが指定されたプラットフォームにデプロイされ、返された URL からアクセスできるようになります。

失敗後の動作：サイトはデプロイされません。

プラットフォーム固有の注意事項：

• GitHub Pages：Git リポジトリが必要です。認証には API キーも使用できます。
• Netlify：Netlify CLI が必要です。認証には API キーも使用できます。
• Vercel：Vercel CLI が必要です。認証には API キーも使用できます。
• Custom：Git リポジトリとリモート URL が必要です。

ワークフローの完全な例

テーマを使って新しい Hugo サイトを作成する、ワークフローの完全な例です（一般的な手順を示すため、MCP サーバーのツールではなく Python スクリプトを使用しています）。

1. Hugo がインストールされているか確認します。

   result = await check_hugo_installation()
   if result["status"] != "success":
       result = await install_hugo()
   

2. Git がインストールされているか確認します。

   result = await check_git_installation()
   if result["status"] != "success":
       result = await install_git()
   

3. Git を設定します。

   result = await configure_git("John Doe", "[email protected]")
   

4. 利用可能なテーマを一覧表示します。

   result = await list_themes()
   themes = result["themes"]
   

5. 特定のテーマの詳細を取得します。

   result = await get_theme_details("Paper")
   theme_details = result["theme"]
   

6. テーマを使って新しいサイトを作成します。

   result = await create_site("my-blog", theme="nanxiaobei/hugo-paper", use_example_site=True)
   site_path = result["path"]
   

7. プレビューサーバーを起動します。

   result = await start_preview(site_path, build_drafts=True)
   preview_url = result["url"]
   

8. 新しい投稿を作成します。

   result = await create_post(site_path, "my-first-post", draft=False)
   post_file = result["file"]
   

9. 本番環境用にサイトをビルドします。

   result = await build_site(site_path, minify=True)
   

10. サイトを GitHub Pages にデプロイします。

    result = await deploy_site(
        site_path=site_path,
        platform="github-pages",
        branch="gh-pages",
        commit_message="Deploy site",
        api_key="your-github-token"
    )
    deploy_url = result["url"]
    

トラブルシューティング

よくある問題

1. Hugo がインストールされていない：

   • install_hugo ツールを使って Hugo をインストールします。

2. Git がインストールされていない：

   • install_git ツールを使って Git をインストールします。

3. テーマのインストールに失敗する：

   • テーマの URL が正しいか確認します。
   • Git サブモジュールを使うには、Git がインストールされていることを確認します。
   • Hugo モジュールを使うには、Go がインストールされていることを確認します。
   • テーマのドキュメントを読み、異なる点がないか確認します。

4. プレビューサーバーの起動に失敗する：

   • ポートがすでに使用されていないか確認します。
   • サイトのパスが正しいことを確認します。
   • ネットワークを確認します。

5. ビルドに失敗する：

   • サイトのパスが正しいか確認します。
   • 必要な依存関係がすべてインストールされていることを確認します。

ヘルプを求める

このドキュメントに記載されていない問題が発生した場合は、GitHub リポジトリでissue を作成してください。