stackguide-mcp

StackGuide MCP サーバー

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

できること

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

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

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

v4.x の新機能

• アクティブな 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）を使用します。

クイックスタート

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：ワークフローのアセット（エージェント／スキル／フック／コマンド）を遅延読み込みします
• 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 の1行目から生成します

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