stackguide-mcp

StackGuide MCP Server

Cursor、VS Code、その他の MCP クライアントで AI コーディングアシスタントに動的なコンテキストと実践的なエンジニアリングワークフローを提供します。

できること

@stackguide/mcp-server は、次の機能により、チームの実装品質の標準化を支援します。

• プロジェクトを認識したルール／コンテキストの読み込み
• コードレビューと健全性のスコアリング
• 自動検出によるセットアップとスタックのひな形作成
• 実際の作業を実行するアクティブなエージェントワークフロー（intake、plan、verify、release）
• プロジェクトごとに適応する TDD の設定（モデル＋トークンプロファイル）
• 厳格な MAIN DESCRIPTION テンプレートに基づく Jira チケットの作成
• トラッカー＋VCS＋テストのオーケストレーションによるデリバリーフロー

このサーバーは、プロンプトテンプレートだけでなく、実際のチームでの利用を想定して構築されています。

v4.x の新機能

全履歴：CHANGELOG.md。

• v4.3.1 - 更新通知機能：StackGuide はバックグラウンドで 1 日に 1 回 npm を確認し、新しいバージョンがある場合はセッションごとに 1 回、安全な更新コマンドとともに通知します。STACKGUIDE_NO_UPDATE_CHECK=1 で無効にできます。
• v4.3.0 - チームモード：
  • setup wizard:true を実行すると、スタック、アーキテクチャ、方法論、規約、トラッカーを尋ね、リポジトリのルートに共有 stackguide.config.json を書き込みます。これをコミットすると、チーム全員が同じコンテキストを利用できます。
  • 起動時に StackGuide はこのファイルを（サブフォルダーからも）見つけて読み込みます。setup の実行やプロジェクトの再検出は行いません。context はアーキテクチャと方法論ごとに 1 行のガイダンスを返します。
  • オプションの ruleCategories で読み込むルールを絞り込めます（トークンを節約できます）。ファイル内の既存の healthWeights は保持されます。
  • 使用中の IDE に応じたマルチエージェントの役割（MCP クライアントから検出）。デフォルトは、Claude Code が opus／haiku／haiku、Cursor が inherit（選択中のモデル。例：Composer または Grok）／fast／fast、その他の IDE が inherit です。ウィザードでは各役割に使用するモデルを尋ねます（推奨デフォルト、使用頻度の高いモデルを優先、または IDE に表示される任意の ID を入力）。デフォルトを受け入れるには models:{planner,implementer,verifier} または models:{} と回答してください。選択内容は IDE ごとに stackguide.config.json に保存されるため、異なる IDE を使うチームでも設定が競合しません。
  • agent action:"plan" は現在の IDE 向けの delegation ブロックを返し、ウィザードは .claude/agents/ と .cursor/agents/ に stackguide-implementer.md／stackguide-verifier.md を書き込みます。編集済みファイルは保持され、model: 行のみ更新されます。
  • setup wizard:true を再実行すると保存済み設定を編集できます。.stackguide/ はローカルに保持され、保護されます。
• アクティブな agent ツールを追加（実行優先のワークフロー）。
• init が .stackguide/config.json を自動生成するようになりました。
• GitHub、GitLab、Jira のトラッカーサービス対応を追加。
• ブランチチェック、コミット解析、CI ステータス、PR/MR 作成に対応する VCS サービスを追加。
• test／lint／build を構造化して実行するテストランナーサービスを追加。
• TDD プロンプトを更新し、大きな受動的 Markdown ペイロードではなく、アクティブなツール呼び出しを使用するようにしました。
• ローカル永続化を強化：
  • .stackguide のアーティファクトをバージョン管理から除外
  • リポジトリガードでローカルアーティファクトの誤った追跡を防止
  • キャッシュと健全性履歴に整合性検証と、より安全な書き込みを追加

IDE ごとのインストール

Cursor

• ファイル（ワークスペース）：.cursor/mcp.json
• ファイル（グローバル）：~/.cursor/mcp.json

{
  "mcpServers": {
    "stackguide": {
      "command": "npx",
      "args": ["-y", "@stackguide/mcp-server@latest"]
    }
  }
}

JetBrains（IntelliJ、WebStorm、PhpStorm など）

• Settings | Tools | AI Assistant | Model Context Protocol (MCP) を開きます。
• Add をクリックし、JSON 設定を貼り付けます。
• 推奨：グローバルに適用する場合を除き、Project-level に設定してください。

{
  "mcpServers": {
    "stackguide": {
      "command": "npx",
      "args": ["-y", "@stackguide/mcp-server@latest"]
    }
  }
}

VS Code

• 要件：MCP が有効になっている GitHub Copilot Chat。
• ファイル（ワークスペース）：.vscode/mcp.json
• VS Code の MCP スキーマでは、ルートキーとして servers を使用します。

{
  "servers": {
    "stackguide": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stackguide/mcp-server@latest"]
    }
  }
}

Visual Studio（Windows、2022 17.14+ / 2026+）

• GitHub Copilot のエージェントモードを有効にします。
• 対応する設定ファイルの場所：
  • %USERPROFILE%\\.mcp.json（グローバル）
  • <solution>\\.mcp.json（リポジトリスコープ）
  • <solution>\\.vs\\mcp.json（ソリューション／ユーザースコープ）
• Visual Studio の MCP スキーマでは、ルートキーとして servers を使用します。

{
  "servers": {
    "stackguide": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stackguide/mcp-server@latest"]
    }
  }
}

使用方法（すべての IDE）

1. MCP 設定を追加した後、IDE を再起動します。
2. エージェント／ツールモードで AI チャットを開きます。
3. setup を呼び出して、プロジェクトのコンテキストを検出します。
4. init action:"full" を呼び出して、.stackguide/ とデフォルト設定を生成します。
5. agent アクション（intake、create_ticket、plan、verify、release）を使って、デリバリーフローを実行します。

クイックスタート

チームでのセットアップ（プロジェクトごとに一度実行し、その後 stackguide.config.json をコミットします）：

setup wizard:true
setup wizard:true type:"nextjs" architecture:"clean" methodology:"tdd" conventions:["Use named exports"] tracker:"jira"

個人でのセットアップ：

1. プロジェクトを設定します：

setup type:"react-typescript" enableAdaptiveTdd:true model:"gpt-5" integrations:["jira","github"] tokenMode:"compact"
init action:"full" model:"gpt-5" tokenMode:"compact" integrations:["jira","github"] mcpSyncTargets:["cursor","root"] applyMcpTemplates:true

1. 生成されたセットアップを確認します：

init action:"status"
agent action:"status"

1. アクティブな TDD ワークフローを実行します：

agent action:"intake" ticket:"PROJ-123"
agent action:"create_ticket" mainDescription:"<MAIN DESCRIPTION>" projectKey:"PROJ"
agent action:"plan" brief:"<brief-from-intake>"
agent action:"verify"
agent action:"release" version:"v1.2.0"

ツール（16）

コア

• setup：プロジェクトの種類に応じて StackGuide のコンテキストを設定します
• context：現在読み込まれているコンテキストを表示します
• rules：ルールセットの一覧表示／検索／取得／選択を行います
• knowledge：ナレッジファイルの一覧表示／検索／取得を行います
• review：ファイル／URL／プロジェクトのコード品質を分析します

ユーティリティ

• cursor：コミュニティルールを閲覧／インポートします
• docs：ドキュメントを取得／検索／一覧表示します
• config：設定を保存／読み込み／エクスポート／インポートします
• custom_rule：プロジェクトのカスタムルールを作成／更新／削除／一覧表示します
• help：トピック別の使用方法を確認します

高度な機能

• generate：ボイラープレートを生成します（component/hook/service/test/api/model/util）
• health：プロジェクトの健全性スコアと推奨事項を表示します
• analyze：プロジェクトのインテリジェンス機能（構成／設定／依存関係／生成／適用）を実行します

ワークフロー

• workflow：ワークフローのアセット（agents/skills/hooks/commands）をオンデマンドで読み込みます
• init：スタックに応じたデフォルト設定で .stackguide を生成します
• agent：アクティブなワークフロー実行ツールです（status、intake、create_ticket、plan、verify、release）

アクティブなワークフローの詳細

agent action:"intake"

• 設定済みのトラッカーからチケットを読み込みます
• 標準化された概要と不足情報を返します
• ブランチ名の規則を提案します
• 必要に応じて、先に Jira チケットを作成できます（createFromDescription:true）

agent action:"create_ticket"

• 厳密な MAIN DESCRIPTION 形式で Jira の課題を作成します
• .stackguide/config.json のプロジェクトのデフォルト設定（projectKey、issueType）を使用します
• summary が省略された場合、MAIN DESCRIPTION の最初の行から導出します

agent action:"plan"

• 規約とプロジェクトの構成を調査します
• 垂直スライス計画を作成します
• 構造化形式で、対象テストを正確に 3 件返します

agent action:"verify"

• レイヤーごとに、設定されたテスト／lint／ビルドを実行します
• ブランチ名、コミット規約、TDD のテスト予算を確認します
• ブロッカーの一覧と最終的な合否レポートを返します

agent action:"release"

• CI のステータスを確認します
• 最後のタグ以降のコミットを解析します
• semver の影響度（major／minor／patch）を提案します
• 有効になっている場合、タグと PR/MR を作成できます

ローカルデータとセキュリティ

init は以下を生成します：

• .stackguide/config.json（プロジェクトのワークフロー設定）

実行時／ローカルのアーティファクト：

• .stackguide/analysis-cache.json
• .stackguide/health-history.json

これらはマシンローカルのものであり、コミットしてはいけません。

リポジトリガード

pnpm lint には以下が含まれます：

pnpm run guard:repo

.stackguide のアーティファクトが追跡対象になっている場合、ガードは失敗します。

整合性の強化

キャッシュ／履歴の永続化には、以下が含まれます：

• 境界／シンボリックリンクのチェック
• ファイルサイズとエントリー数の制限
• アトミックな書き込み方式
• チェックサム検証
• 以下を使用するオプションの HMAC 署名：

STACKGUIDE_INTEGRITY_KEY=<long-random-secret>

チームでは、改ざん耐性をさらに強化するため、ローカル／開発環境と CI 環境で STACKGUIDE_INTEGRITY_KEY を設定してください。

対応スタック

python-django、python-fastapi、python-flask、react-node、react-typescript、vue-node、nextjs、express、nestjs、laravel、rails、golang、rust、custom。

開発

すべてのコマンドで pnpm を使用します。

pnpm install
pnpm lint
pnpm test
pnpm build
pnpm dev

リリースとバージョンポリシー

• 現在のセキュアな基準バージョン：4.1.2+
• 3.0.0 から 4.1.1 までのバージョンは、ローカルの成果物管理上の問題により、npm で非推奨となっています。
• すべての環境で最新の 4.x リリースを使用してください。

レジストリ識別子

• npm パッケージ：@stackguide/mcp-server
• MCP Registry サーバー：io.github.isucorp-taimiralain/stackguide-mcp

ライセンス

GPL-3.0