Project Hub MCP Server

Project Hub MCP サーバー

包括的なプロジェクト管理、ローカル Git 機能、GitHub 連携機能を提供する MCP サーバーです。このサーバーを使うと、ローカルプロジェクトの管理、変更の追跡、ローカルコミットの作成、GitHub リポジトリとの同期ができます。

機能

プロジェクト管理

• 大文字と小文字を区別しない、柔軟な部分一致による名前検索で、プロジェクトの作成と管理ができます
• カスタマイズ可能な除外パターンを使って、ソースファイルのスキャンと監視ができます
• プロジェクトのメタデータを追跡および更新できます

ローカル Git 機能

• GitHub を必要とせずに、ローカルコミットを作成および管理できます
• ブランチを管理できます（作成、切り替え、一覧表示）
• メタデータ（サイズ、作成日時、更新日時）付きのファイルスナップショットを作成できます
• 復元機能により、以前のコミットやブランチの状態に戻せます
• クローン機能により、コミットやブランチから新しいインスタンスを作成できます

変更の追跡

• 関連ファイルとともに変更を記録および追跡できます
• 変更を種類（機能追加、修正、リファクタリングなど）別に分類できます
• 変更をコミットに紐付けて、包括的な履歴を管理できます

ノートシステム

• リッチな Markdown コンテンツを含むプロジェクトノートを作成および管理できます
• ノートを分類およびタグ付けして、整理しやすくできます
• 検索機能で関連ドキュメントを見つけられます

GitHub 連携

• リポジトリを管理できます（作成、更新、削除、名前変更）
• ファイル内容を追跡しながら、コミットを管理できます
• ブランチ操作を実行できます（作成、削除、マージ）
• プルリクエストを作成および管理できます
• リポジトリをクローンしてローカルにセットアップできます
• 複数の GitHub アカウントをサポートします

ツール

プロジェクト管理

create_project

ローカルおよびリモートのリポジトリ管理機能を備えた新しいプロジェクトを作成します。

• name：プロジェクト名
• path：ローカルプロジェクトのパス
• type：プロジェクトの種類
• description：プロジェクトの説明

find_project

プロジェクトを名前で検索します（大文字と小文字を区別しない、柔軟な部分一致）。変更やノートを含む詳細なプロジェクト情報を返します。

• name：検索するプロジェクト名

list_projects

必要に応じて絞り込みながら、すべてのプロジェクトを一覧表示します。

• type：プロジェクトの種類で絞り込み（任意）
• has_repo：リポジトリの有無で絞り込み（任意）
• page：ページネーションで使用するページ番号（任意）
• page_size：1 ページあたりの項目数（任意）

update_project_details

既存のプロジェクトの詳細を更新します。

• projectId：プロジェクト ID
• name：新しいプロジェクト名（任意）
• path：新しいプロジェクトのパス（任意）
• type：新しいプロジェクトの種類（任意）
• description：新しいプロジェクトの説明（任意）
• status：新しいプロジェクトのステータス（任意）

delete_project

プロジェクトを削除します。

• projectId：プロジェクト ID

scan_project_files

プロジェクトのディレクトリ内にあるソースファイルをスキャンし、プロジェクトのレコードを更新します。

• projectId：プロジェクト ID
• excludePatterns：除外するファイルを指定する正規表現パターン（任意）

projectdb_location

プロジェクトデータベースの場所を絶対パスで取得します。

変更管理

record_change

プロジェクトの変更を記録します。

• projectId：プロジェクト ID
• type：変更の種類
• description：変更の説明
• files：この変更の影響を受けるファイルパスの一覧（任意）

get_pending_changes

プロジェクトの保留中の変更を取得します。

• projectId：プロジェクト ID

clear_committed_changes

プロジェクトのコミット済み変更をクリアします。

• projectId：プロジェクト ID

ローカル Git 機能

init_local_repository

プロジェクトのローカル Git リポジトリを初期化します。

• projectId：プロジェクト ID

create_local_commit

保留中の変更からローカルコミットを作成します。

• projectId：プロジェクト ID
• message：コミットメッセージ
• authorName：作成者名（任意）
• authorEmail：作成者のメールアドレス（任意）

get_local_commit_history

プロジェクトのローカルコミット履歴を取得します。

• projectId：プロジェクト ID

create_local_branch

新しいローカルブランチを作成します。

• projectId：プロジェクト ID
• name：ブランチ名
• startingCommitId：開始コミット ID（任意）

switch_local_branch

別のローカルブランチに切り替えます。

• projectId：プロジェクト ID
• branchName：ブランチ名

list_local_branches

プロジェクトのすべてのローカルブランチを一覧表示します。

• projectId：プロジェクト ID

restore_to_local_commit

プロジェクトのファイルを特定のローカルコミットに復元します。

• projectId：プロジェクト ID
• commitId：復元先のコミット ID

restore_to_local_branch

プロジェクトのファイルを特定のローカルブランチに復元します。

• projectId：プロジェクト ID
• branchName：復元先のブランチ名

restore_local_commit_to_new_location

特定のローカルコミットを新しいフォルダーの場所に復元します。

• projectId：プロジェクト ID
• commitId：復元するコミット ID
• newLocation：復元先の新しいフォルダーのパス

restore_local_branch_to_new_location

特定のローカルブランチを新しいフォルダーの場所に復元します。

• projectId：プロジェクト ID
• branchName：復元するブランチ名
• newLocation：復元先の新しいフォルダーのパス

push_local_commits

ローカルコミットを GitHub にプッシュします。

• projectId：プロジェクト ID
• repo：リポジトリ名
• branch：ブランチ名（任意）

force_local_commit

保留中の変更の有無にかかわらず、プロジェクト内のすべてのファイルを強制的にローカルコミットします。

• projectId：プロジェクト ID
• message：コミットメッセージ
• authorName：作成者名（任意）
• authorEmail：作成者のメールアドレス（任意）

cleanup_project_files

プロジェクトの Project Hub データから、存在しないファイルの記録を削除します。

• projectId：プロジェクト ID

ファイルスナップショットの管理

get_file_snapshots

コミットのファイルスナップショットを取得します。

• commitId：コミット ID

get_file_snapshots_metadata

コミットのファイルスナップショットのメタデータを取得します（ファイルの内容を除く）。

• commitId：コミット ID

get_file_content

スナップショットのファイルの内容を取得します。

• snapshotId：スナップショット ID

ノートの管理

create_note

プロジェクトの新しいノートを作成します。

• project_name：プロジェクト名
• title：ノートのタイトル
• content：ノートの内容
• category：ノートのカテゴリ（任意）
• tags：ノートのタグ（任意）

update_note

既存のノートを更新します。

• project_name：プロジェクト名
• note_id：ノート ID
• title：新しいノートのタイトル（任意）
• content：新しいノートの内容（任意）
• category：新しいノートのカテゴリ（任意）
• tags：新しいノートのタグ（任意）

delete_note

ノートを削除します。

• project_name：プロジェクト名
• note_id：ノート ID

search_notes

プロジェクト内のノートを検索します。

• project_name：プロジェクト名
• query：検索クエリ
• category：カテゴリで絞り込む（任意）

リポジトリの管理

create_repository

新しい GitHub リポジトリを作成します。

• name：リポジトリ名
• description：リポジトリの説明（任意）
• isPrivate：リポジトリを非公開にするかどうか（任意）

get_repository

特定のリポジトリに関する詳細情報を取得します。

• name：リポジトリ名

update_repository

リポジトリの設定を更新します。

• name：リポジトリ名
• description：新しいリポジトリの説明（任意）
• private：リポジトリの公開設定を変更（任意）
• default_branch：デフォルトブランチを変更（任意）
• has_issues：Issue を有効／無効にする（任意）
• has_wiki：Wiki を有効／無効にする（任意）

delete_repository

GitHub リポジトリを削除します。

• name：リポジトリ名

rename_repository

GitHub リポジトリの名前を変更します。

• oldName：現在のリポジトリ名
• newName：新しいリポジトリ名

list_repositories

認証済みユーザーのすべてのリポジトリを一覧表示します。

• visibility：公開設定でリポジトリを絞り込む（任意）
• sort：フィールドでリポジトリを並べ替える（任意）
• per_page：1 ページあたりの結果数（任意）

fork_repository

既存のリポジトリをフォークします。

• name：フォークするリポジトリ名
• organization：フォーク先の組織（任意）

transfer_repository

リポジトリの所有権を移転します。

• name：リポジトリ名
• new_owner：新しい所有者のユーザー名または組織名
• team_ids：リポジトリに追加するチーム ID（任意）

clone_repository

指定したフォルダーにリポジトリをクローンします。

• repo：リポジトリ名
• targetFolder：リポジトリのクローン先フォルダー
• branch：クローンするブランチ（任意）

ファイル管理

get_file

GitHub リポジトリからファイルの内容を取得します。

• repo：リポジトリ名
• path：リポジトリ内のファイルパス
• ref：Git の参照（ブランチ、タグ、またはコミット SHA）（任意）

コミット管理

create_commit

GitHub リポジトリにコミットを作成します。

• repo：リポジトリ名
• branch：ブランチ名（任意。デフォルトは main）
• message：コミットメッセージ
• changes：ファイル変更の配列（path、content、operation）

list_commits

GitHub リポジトリのコミット一覧を取得します。

• repo：リポジトリ名
• branch：ブランチ名（任意）

get_commit

GitHub リポジトリからコミットの詳細を取得します。

• repo：リポジトリ名
• sha：コミット SHA

revert_commit

GitHub リポジトリのコミットを取り消します。

• repo：リポジトリ名
• sha：取り消すコミットの SHA

ブランチ管理

create_branch

GitHub リポジトリに新しいブランチを作成します。

• repo：リポジトリ名
• name：新しいブランチ名
• sourceBranch：作成元のブランチ（任意。デフォルトは main）

delete_branch

リポジトリからブランチを削除します。

• repo：リポジトリ名
• name：削除するブランチ名

list_branches

リポジトリのすべてのブランチを一覧表示します。

• repo：リポジトリ名

get_branch

指定したブランチの詳細を取得します。

• repo：リポジトリ名
• name：ブランチ名

merge_branches

リポジトリ内の2つのブランチをマージします。

• repo：リポジトリ名
• base：ベースブランチ名
• head：ヘッドブランチ名
• message：マージコミットメッセージ（任意）

プルリクエスト管理

create_pull_request

新しいプルリクエストを作成します。

• repo：リポジトリ名
• title：プルリクエストのタイトル
• head：ヘッドブランチ名
• base：ベースブランチ名
• body：プルリクエストの説明（任意）
• draft：ドラフト PR として作成（任意）
• maintainer_can_modify：メンテナーによる変更を許可（任意）

ユーティリティツール

list_tools

Project Hub MCP で利用可能なすべてのツールを一覧表示します。

アーキテクチャ

データベーススキーマ

Project Hub MCP サーバーは、データの保存に SQLite を使用し、以下の主要なテーブルを備えています。

• projects：プロジェクトのメタデータを保存します
• changes：プロジェクトに加えられた変更を追跡します
• notes：プロジェクトのドキュメントを保存します
• source_files：プロジェクト内のファイルをカタログ化します
• local_commits：ローカルコミット情報を保存します
• local_branches：ブランチ情報を追跡します
• file_snapshots：コミット時点のファイル内容とメタデータを保存します
• commit_changes：コミットと変更を対応付けます

主要コンポーネント

• ProjectManager：プロジェクトの CRUD 操作とメタデータを管理します
• LocalGitService：ローカル Git 機能を管理します
• FileSnapshotService：ファイルスナップショット操作を処理します
• GitHubService：GitHub API と連携します
• StorageService：データベース操作を管理します
• SourceScanner：プロジェクトファイルをスキャンしてカタログ化します

インストール

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

git clone https://github.com/peterparker57/project-hub-mcp-server.git
cd project-hub-mcp-server

2. 依存関係をインストールします：

npm install

3. プロジェクトをビルドします：

npm run build

設定

MCP 設定ファイルにサーバーを追加します：

{
  "mcpServers": {
    "project-hub": {
      "command": "node",
      "args": ["path/to/project-hub-mcp-server/dist/index.js"],
      "env": {
        "NODE_ENV": "development",
        "DEFAULT_PRIVATE": "true",
        "DEFAULT_OWNER": "your-github-username",
        "GITHUB_TOKEN": "your-github-token",
        "GIT_PATH": "C:\\Program Files\\Git\\bin\\git.exe"
      },
      "alwaysAllow": [
        "list_projects",
        "find_project",
        "get_pending_changes",
        "get_local_commit_history",
        "list_local_branches"
      ]
    }
  }
}

環境変数

• NODE_ENV：「development」または「production」に設定します
• DEFAULT_PRIVATE：新しいリポジトリをデフォルトで非公開にするかどうか
• DEFAULT_OWNER：リポジトリ操作に使用するデフォルトの GitHub ユーザー名
• GITHUB_TOKEN：適切な権限を持つ GitHub パーソナルアクセストークン
• GIT_PATH：ローカル Git 操作用の Git 実行ファイルのパス

使用例

プロジェクト管理

// Create a new project
await mcp.use("project-hub", "create_project", {
  name: "my-project",
  path: "./projects/my-project",
  type: "typescript",
  description: "A new TypeScript project"
});

// Find a project (flexible name search)
await mcp.use("project-hub", "find_project", {
  name: "my-project" // Works with "My-Project", "MY-PROJECT", "my project notes", etc.
});

// Record a change
await mcp.use("project-hub", "record_change", {
  projectId: "project-id",
  description: "Added new feature",
  type: "feature",
  files: ["src/feature.ts"]
});

// Scan project files
await mcp.use("project-hub", "scan_project_files", {
  projectId: "project-id",
  excludePatterns: ["node_modules", "\\.git", "dist", "build"]
});

ローカル Git 機能

// Initialize local repository
await mcp.use("project-hub", "init_local_repository", {
  projectId: "project-id"
});

// Create a local commit
await mcp.use("project-hub", "create_local_commit", {
  projectId: "project-id",
  message: "Implemented new feature",
  authorName: "John Doe",
  authorEmail: "[email protected]"
});

// Create a new branch
await mcp.use("project-hub", "create_local_branch", {
  projectId: "project-id",
  name: "feature/new-feature"
});

// Switch to a branch
await mcp.use("project-hub", "switch_local_branch", {
  projectId: "project-id",
  branchName: "feature/new-feature"
});

// Restore to a previous commit
await mcp.use("project-hub", "restore_to_local_commit", {
  projectId: "project-id",
  commitId: "commit-id"
});

// Clone a branch to a new location
await mcp.use("project-hub", "restore_local_branch_to_new_location", {
  projectId: "project-id",
  branchName: "main",
  newLocation: "C:/Projects/new-clone"
});

// Push local commits to GitHub
await mcp.use("project-hub", "push_local_commits", {
  projectId: "project-id",
  repo: "my-project",
  branch: "main"
});

メモ管理

// Create a project note
await mcp.use("project-hub", "create_note", {
  project_name: "my-project",
  title: "Architecture Decision Record",
  content: "# ADR-001: Project Structure\n\n...",
  category: "documentation",
  tags: ["architecture", "decision"]
});

// Search notes
await mcp.use("project-hub", "search_notes", {
  project_name: "my-project",
  query: "architecture",
  category: "documentation"
});

GitHub 連携

// Create and link repository
await mcp.use("project-hub", "create_repository", {
  name: "my-project",
  description: "A new TypeScript project",
  isPrivate: true
});

// Clone a repository
await mcp.use("project-hub", "clone_repository", {
  repo: "my-project",
  targetFolder: "./projects/my-project",
  branch: "main"
});

// Create a feature branch
await mcp.use("project-hub", "create_branch", {
  repo: "my-project",
  name: "feature/new-feature",
  sourceBranch: "main"
});

// Create a commit on the feature branch
await mcp.use("project-hub", "create_commit", {
  repo: "my-project",
  changes: [{
    path: "src/feature.ts",
    content: "// New feature code",
    operation: "add"
  }],
  message: "feat: add new feature",
  branch: "feature/new-feature"
});

// Create pull request
await mcp.use("project-hub", "create_pull_request", {
  repo: "my-project",
  title: "Add new feature",
  head: "feature/new-feature",
  base: "main",
  body: "This PR adds a new feature",
  draft: false,
  maintainer_can_modify: true
});

// After PR review, merge the branches
await mcp.use("project-hub", "merge_branches", {
  repo: "my-project",
  base: "main",
  head: "feature/new-feature",
  message: "Merge feature/new-feature into main"
});

開発

1. ソースコードを変更します
2. テストを実行します：

npm test

3. プロジェクトをビルドします：

npm run build

最近の機能強化

ローカル Git 機能（2025 年 3 月）

• コミット、ブランチ、ファイルスナップショットを含む包括的なローカル Git 機能を追加しました
• 以前の状態に戻すための復元機能を実装しました
• コミットまたはブランチから新しいインスタンスを作成するクローン機能を追加しました
• メタデータの追跡（サイズ、作成日時、変更日時）によってファイルスナップショットを強化しました

プロジェクト管理の改善（2025 年 2 月）

• GitHub リポジトリを指定したフォルダーにクローンする clone_repository ツールを追加しました
• プロジェクトディレクトリをスキャンし、ソースファイルをカタログ化する scan_project_files ツールを実装しました
• 柔軟な大文字・小文字を区別しない部分一致によって、プロジェクト検索を強化しました
• メタデータを改善し、ファイル追跡を強化しました

貢献

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更をコミットします
4. ブランチにプッシュします
5. プルリクエストを作成します

ライセンス

MIT