mcp-go-starter

MCP Go Starter

公式の go-sdk を使用した、機能が充実した Go 製 Model Context Protocol（MCP）サーバーテンプレートです。このスターターでは、主要な MCP 機能をすべて、クリーンで慣用的な Go コードで紹介します。

📚 ドキュメント

• Model Context Protocol
• Go SDK
• MCP サーバーの構築

✨ 機能

カテゴリ	機能	説明
ツール	hello	アノテーション付きの基本的なツール
	get_weather	構造化データを返すツール
	ask_llm	LLM サンプリングを呼び出すツール
	long_task	5 秒間隔で進捗を更新するツール
	load_bonus_tool	新しいツールを動的に読み込む
リソース	info://about	静的な情報リソース
	file://example.md	ファイルベースの Markdown リソース
テンプレート	greeting://{name}	個別にカスタマイズされた挨拶
	data://items/{id}	ID によるデータ検索
プロンプト	greet	さまざまなスタイルの挨拶
	code_review	注目点を指定したコードレビュー

MCP サンプリング（ask_llm）は、プロトコルバージョン 2026-07-28 で非推奨になりました （SEP-2577）。 このワークショップでは、サポートされている非推奨化期間中はサンプルを維持します。新しい 本番サーバーでは、LLM プロバイダーの API を直接呼び出してください。

🚀 クイックスタート

前提条件

• Go 1.26.8+
• （任意）ライブリロード用の air
• （任意）リンティング用の golangci-lint

air と goimports は、依存関係も含めて tools/go.mod に固定されており、サーバーモジュールと合わせて Dependabot によって更新されます。 go -C tools install tool でインストールしてください。

インストール

# Clone the repository
git clone https://github.com/SamMorrowDrums/mcp-go-starter.git
cd mcp-go-starter

# Download dependencies
go mod download

サーバーの実行

stdio トランスポート（ローカル開発用）：

go run ./cmd/stdio
# Or: make run-stdio

HTTP トランスポート（リモート／Web デプロイ用）：

go run ./cmd/http
# Or: make run-http
# Server runs on http://localhost:3000

HTTP エンドポイントは JSON リクエストを必要とし、クロスオリジンのブラウザーリクエストを拒否します。Origin ヘッダーを送信しないネイティブ MCP クライアントと、同一オリジンのブラウザークライアントは引き続き利用できます。

バイナリのビルド

make build
# Creates bin/stdio and bin/http

🔧 VS Code との連携

このプロジェクトには、スムーズに開発できるよう VS Code の設定が含まれています。

1. VS Code でプロジェクトを開きます
2. MCP の設定は .vscode/mcp.json にあります
3. Ctrl+Shift+B（Mac では Cmd+Shift+B）でビルドします
4. VS Code の MCP ツールを使ってサーバーをテストします

DevContainers の使用

1. Dev Containers 拡張機能をインストールします
2. コマンドパレットを開き、「Dev Containers: Reopen in Container」を選択します
3. すべて設定済みで、すぐに使用できます！

📁 プロジェクト構成

.
├── cmd/
│   ├── stdio/
│   │   └── main.go        # stdio transport entrypoint
│   └── http/
│       └── main.go        # HTTP transport entrypoint
├── internal/
│   └── server/
│       ├── server.go      # Server orchestration
│       ├── tools.go       # Tool definitions (hello, get_weather, etc.)
│       ├── resources.go   # Resource and template definitions
│       └── prompts.go     # Prompt definitions
├── .vscode/
│   ├── mcp.json           # MCP server configuration
│   ├── tasks.json         # Build/run tasks
│   └── extensions.json
├── .devcontainer/
│   └── devcontainer.json
├── .air.toml              # Live reload configuration
├── .golangci.yml          # Linter configuration
├── go.mod
├── Makefile
└── README.md

🛠️ 開発

# Development with live reload (recommended)
make dev
# Requires air: go install github.com/air-verse/air@latest

# Run without live reload
make run-stdio

# Run tests
make test

# Format code
make fmt

# Lint code
make lint

# Install all dev tools
make install-tools

# Clean build artifacts
make clean

ライブリロード

自動再ビルド用に air をインストールします：

go install github.com/air-verse/air@latest
make dev

.go ファイルを変更すると、サーバーが自動的に再ビルドされ、再起動します。

🔍 MCP Inspector

MCP Inspector は、MCP サーバーのテストとデバッグに欠かせない開発ツールです。

Inspector の実行

npx @modelcontextprotocol/inspector -- go run ./cmd/stdio/main.go

Inspector が提供する機能

• Tools タブ：登録済みのすべてのツールとパラメーターを一覧表示し、呼び出せます
• Resources タブ：リソースとテンプレートを参照して読み込めます
• Prompts タブ：プロンプトテンプレートを表示してテストできます
• Logs タブ：クライアントとサーバー間の JSON-RPC メッセージを確認できます
• スキーマ検証：ツールの入出力スキーマを検証できます

デバッグのヒント

1. IDE／クライアントに接続する前に Inspector を起動します
2. 「Logs」タブで正確なリクエスト／レスポンスのペイロードを確認します
3. ツールのアノテーション（ToolAnnotations）が正しく公開されているかテストします
4. long_task の進捗通知が表示されることを確認します
5. ask_llm でサンプリングが機能することを確認します

📖 機能の例

アノテーション付きツール

mcp.AddTool(server, &mcp.Tool{
    Name:        "hello",
    Title:       "Say Hello",
    Description: "A friendly greeting tool",
    Annotations: &mcp.ToolAnnotations{
        ReadOnlyHint: ptr(true),
    },
}, helloHandler)

func helloHandler(ctx context.Context, req *mcp.CallToolRequest, input helloInput) (*mcp.CallToolResult, any, error) {
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            &mcp.TextContent{Text: fmt.Sprintf("Hello, %s!", input.Name)},
        },
    }, nil, nil
}

リソーステンプレート

server.AddResourceTemplate(&mcp.ResourceTemplate{
    Name:        "Personalized Greeting",
    URITemplate: "greeting://{name}",
    MIMEType:    "text/plain",
}, greetingHandler)

進捗更新付きツール

func longTaskHandler(ctx context.Context, req *mcp.CallToolRequest, input longTaskInput) (*mcp.CallToolResult, any, error) {
    progressToken := req.Params.GetProgressToken()
    
    for i := 0; i < 5; i++ {
        req.Session.NotifyProgress(ctx, &mcp.ProgressNotificationParams{
            ProgressToken: progressToken,
            Progress:      float64(i) / 5.0,
            Total:         1.0,
        })
        time.Sleep(time.Second)
    }
    
    return &mcp.CallToolResult{
        Content: []mcp.Content{&mcp.TextContent{Text: "Done!"}},
    }, nil, nil
}

サンプリング付きツール

result, err := req.Session.CreateMessage(ctx, &mcp.CreateMessageParams{
    Messages: []*mcp.SamplingMessage{
        {Role: "user", Content: &mcp.TextContent{Text: prompt}},
    },
    MaxTokens: 100,
})

🔐 環境変数

.env.example を .env にコピーし、設定します。

cp .env.example .env

変数	説明	デフォルト
PORT	HTTP サーバーのポート	3000

🤝 貢献

貢献を歓迎します！変更によって、ほかの言語のスターターとの機能の同等性が維持されるようにしてください。

📄 ライセンス

MIT License - 詳細については LICENSE を参照してください。