Local Dev MCP

1台のWindowsマシン上で、AIエージェントが複数のプロジェクトを操作するためのローカルMCPサーバーです。

Local Dev MCPは、AIクライアントにローカルプロジェクト、ファイルシステム、PowerShellを介したコマンド実行へのアクセスを提供します。サーバーの1つのインスタンスで、1つまたは複数のルートディレクトリにある複数のリポジトリを同時に操作できます。

Dockerは必須の依存関係ではありません。プロジェクトはDocker、Node.js、PHP、Python、またはその他のローカルにインストールされたスタックを使用できます。

インストール

1. Node.jsをインストールする

Local Dev MCPを使用するには、Node.jsバージョン20以降が必要です。

現在のバージョンを確認します:

node --version
npm --version

Node.jsがインストールされていない場合は、Node.js公式サイトから最新のLTSバージョンをインストールしてください。

インストール後、PowerShellまたはWindows Terminalを閉じて再度開きます。

2. Local Dev MCPを取得する

リポジトリをクローンします:

git clone https://github.com/mfokusnik/LocalDevMCP
cd LocalDevMCP

または、リポジトリのアーカイブをダウンロードして、任意のディレクトリに解凍します。例:

C:\Tools\local-dev-mcp

3. 初期設定を実行する

以下を実行します:

FIRST_RUN.cmd

スクリプトは自動的に:

• Node.jsの存在を確認します;

• ローカルプロジェクトのあるルートディレクトリを要求します;

• config.local.jsonを作成します;

• npm依存関係をインストールします;

• TypeScriptをチェックします;

• MCPサーバーを起動します。

たとえば、従業員のプロジェクトがここにある場合:

C:\Users\User\Documents\GitHub

初回起動時にこのディレクトリを指定する必要があります。

別の従業員のパスは任意です:

D:\Projects

または:

C:\Development

設定はローカルに保存され、Gitにはコミットされません。

4. 起動を確認する

正常に起動したら、次を開きます:

http://127.0.0.1:7676/health

期待される応答:

{
  "ok": true,
  "name": "local-dev-mcp",
  "version": "0.1.0",
  "mcp": "http://127.0.0.1:7676/mcp"
}

MCPエンドポイント:

http://127.0.0.1:7676/mcp

5. MCPクライアントを接続する

使用しているローカルMCPトンネルで、次を指定します:

http://127.0.0.1:7676/mcp

接続後、AIクライアントは登録されたMCPツールにアクセスできるようになります。

6. MCPインターフェースを確認する

サーバーが起動している状態で、次を実行します:

SMOKE_TEST.cmd

または:

npm run smoke

テストはMCPエンドポイントに正常に接続し、利用可能なツールのリストを返すはずです。

Related MCP server: Windows-MCP

以降の起動

初回インストール後、再設定は不要です。

サーバーを起動するには、次を使用します:

START.cmd

または:

npm run dev

ローカル設定は次に保存されます:

config.local.json

プロジェクトディレクトリを変更するには、このファイルを手動で編集するか、初回設定を再実行します。

機能

• 1つまたは複数のルートディレクトリ内のプロジェクトの自動検出;

• 名前またはエイリアスによるアクティブプロジェクトの選択;

• 選択したプロジェクト内でのファイル操作;

• 選択したプロジェクトの作業ディレクトリでのPowerShellコマンドの実行;

• 使用されているスタックの基本的な検出;

• ローカルCLIツールの可用性の確認;

• ローカルシェルを介したGitおよびGitHub CLIの操作;

• Streamable HTTP MCPエンドポイント;

• ローカルヘルスチェックエンドポイント;

• アクティブプロジェクトの外部へのファイルMCP操作の保護。

次のテクノロジーとツールの自動検出がサポートされています:

• Git;

• Node.js;

• PHP / Composer;

• Laravel;

• Docker / Docker Compose;

• Python;

• Go;

• Rust。

アーキテクチャ

AI-клиент
    │
    │ MCP
    ▼
Local Dev MCP
    │
    ├── обнаружение проектов
    ├── выбор workspace
    ├── файловые операции
    └── PowerShell
            │
            ├── git
            ├── gh
            ├── docker
            ├── npm
            ├── composer
            ├── php / artisan
            ├── python
            └── другие локальные CLI

サーバーは、各フレームワークやランタイム用の個別のMCPツールを実装していません。

次のようなコマンド:

npm test
php artisan test
docker compose ps
git status
gh pr create

は、汎用ツールshell.runを介して実行されます。

これにより、MCPサーバーは特定のプロジェクトのテクノロジースタックに依存しません。

要件

必須:

• Windows 10またはWindows 11;

• Node.js 20以降;

• プロジェクトを含むローカルディレクトリが少なくとも1つ。

追加ツールは必要な場合にのみインストールされます:

• Git;

• GitHub CLI;

• Docker Desktop;

• PHP;

• Composer;

• Python;

• プロジェクトで使用されるその他のCLIおよびランタイム。

Local Dev MCPの動作にDockerは必要ありません。

初回起動

1. プロジェクトをクローンまたは解凍する

例:

C:\Tools\local-dev-mcp

2. 初回設定を実行する

FIRST_RUN.cmd

スクリプト:

1. Node.jsの存在を確認します;

2. プロジェクトディレクトリへのパスを要求します;

3. ローカル設定ファイルを作成します;

4. npm依存関係をインストールします;

5. TypeScriptチェックを実行します;

6. MCPサーバーを起動します。

デフォルトでは、次のパスが提案されます:

%USERPROFILE%\Documents\GitHub

必要に応じて別のパスを指定できます:

D:\Projects

3. 起動を確認する

次を開きます:

http://127.0.0.1:7676/health

期待される応答:

{
  "ok": true,
  "name": "local-dev-mcp",
  "version": "0.1.0",
  "mcp": "http://127.0.0.1:7676/mcp"
}

MCPエンドポイント:

http://127.0.0.1:7676/mcp

デフォルトでは、サーバーは127.0.0.1のみをリッスンし、ローカルネットワークやインターネットに直接公開されません。

4. MCPクライアントを接続する

ローカルMCPトンネルまたはその他の互換性のあるクライアントで、次を指定します:

http://127.0.0.1:7676/mcp

5. スモークテストを実行する

サーバーが起動している状態で:

SMOKE_TEST.cmd

または:

npm run smoke

テストはMCPへの接続を確認し、登録されたツールのリストを出力します。

通常の起動

初回設定後:

START.cmd

または:

npm run dev

設定

ローカル設定は次に保存されます:

config.local.json

このファイルは.gitignoreを介してGitから除外され、特定のワークステーションの設定用です。

例:

{
  "roots": [
    "C:\\Users\\YourName\\Documents\\GitHub"
  ],
  "scanDepth": 1,
  "host": "127.0.0.1",
  "port": 7676,
  "mcpPath": "/mcp",
  "shell": {
    "executable": "powershell.exe",
    "timeoutMs": 120000,
    "maxOutputChars": 200000
  },
  "skipDirectories": [
    ".git",
    "node_modules",
    "vendor",
    ".next",
    "dist",
    "build"
  ],
  "projects": []
}

複数のルートディレクトリ

{
  "roots": [
    "C:\\Users\\YourName\\Documents\\GitHub",
    "D:\\Work",
    "D:\\Experiments"
  ]
}

各ディレクトリは独立してスキャンされます。

スキャン深度

プロジェクト構造がネストされている場合:

D:\Work
├── clients
│   ├── project-a
│   └── project-b
└── internal
    └── project-c

増やすことができます:

{
  "scanDepth": 2
}

現在のバージョンの最大値は5です。

プロジェクトとエイリアスの明示的な追加

プロジェクトは手動で追加できます:

{
  "projects": [
    {
      "name": "sample-app",
      "path": "D:\\Projects\\sample-app",
      "aliases": [
        "sample",
        "app"
      ]
    }
  ]
}

これにより、プロジェクトはメイン名とエイリアスの両方で選択できます。

プロジェクトの検出

ディレクトリは、サポートされているマーカーの少なくとも1つを含む場合にプロジェクトと見なされます:

.git
package.json
composer.json
artisan
compose.yml
compose.yaml
docker-compose.yml
docker-compose.yaml
Dockerfile
pyproject.toml
requirements.txt
go.mod
Cargo.toml

ディレクトリがプロジェクトとして決定されると、その内部フォルダのスキャンは停止します。

これにより、内部依存関係やサービスディレクトリが個別のワークスペースとして検出されるのを防ぎます。

MCPツール

projects.list

検出されたプロジェクトと明示的に設定されたプロジェクトのリストを返します。

projects.select

名前またはエイリアスでアクティブプロジェクトを選択します。

例:

Пользователь:
Работаем с sample-app

AI:
projects.select({ "name": "sample-app" })

サーバーは応答として次を返します:

• プロジェクトの絶対パス;

• 検出されたスタック;

• 現在のGitブランチ;

• ワーキングツリーの状態;

• 利用可能なローカルCLIツールのリスト。

projects.current

現在のアクティブプロジェクトとその状態を返します。

fs.list

アクティブプロジェクト内のディレクトリの内容を出力します。

fs.read

UTF-8ファイルを読み取ります。

行範囲の読み取りがサポートされています。

fs.write

新しいファイルを作成するか、既存のファイルを完全に上書きします。

fs.replace

ファイル内のテキストを正確に置換します。

1つの一致またはすべての一致の置換がサポートされています。

fs.move

アクティブプロジェクト内のファイルまたはディレクトリを移動または名前変更します。

fs.delete

アクティブプロジェクト内のファイルまたはディレクトリを削除します。

このツールを介したアクティブプロジェクトのルートディレクトリの削除は禁止されています。

shell.run

アクティブプロジェクトの作業ディレクトリでPowerShellコマンドを実行します。

例:

git status

git switch -c feature/example

npm test

php artisan test

docker compose ps

docker compose exec app php artisan test

gh pr create

現在のバージョンでは、個別のdocker.*、git.*、artisan.*ツールは実装されていません。

コマンド実行の汎用インターフェースはローカルシェルです。

Docker

Dockerはオプションのツールです。

Docker Desktopがインストールされている場合、AIクライアントはshell.runを介してDocker CLIを使用できます。

例:

docker compose ps

または:

docker compose exec app npm test

Dockerがなくても、MCPサーバーは他のツールに対して制限なく動作し続けます。

PHP、Composer、Python、GitHub CLI、その他のランタイムについても同様です。

GitとGitHub

Git操作は、ローカルにインストールされたGit CLIを介して実行されます。

例:

git status
git diff
git switch -c feature/example
git commit

GitHub CLIがインストールされ認証されている場合、ghを介した操作が可能です:

gh pr create
gh pr view
gh issue list
gh issue comment

Local Dev MCPはGitHubトークンを保存せず、既存のローカル認証を使用します。

セキュリティモデル

ファイルMCPツールはアクティブプロジェクトに制限されています。

ワークスペースの外部にあるパスを介してファイルにアクセスしようとすると、ブロックされます。

例:

..\..\some-file.txt

fs.read、fs.write、その他のファイルツールが選択したプロジェクトの外部にアクセスすることはできません。

一方、shell.runはサンドボックスではありません。

コマンドはアクティブプロジェクトのディレクトリから実行されます:

cwd = active project

ただし、PowerShell自体は、コマンドで直接指定されている場合、技術的には他のディレクトリやローカルリソースにアクセスできます。

したがって、現在のバージョンは信頼できるローカル開発環境を想定しています:

один сотрудник
=
один локальный MCP
=
одна рабочая станция

アクティブプロジェクトの状態

選択されたプロジェクトはMCPプロセスのメモリに保存されます。

サーバーを再起動した後、プロジェクトを再度選択する必要があります。

現在のバージョンは、サーバーの1つのインスタンスを介した複数の独立したユーザーの同時操作を想定していません。

プロジェクト構造

local-dev-mcp/
├── src/
│   ├── index.ts
│   ├── server.ts
│   ├── config.ts
│   ├── projects.ts
│   ├── fs-tools.ts
│   ├── shell.ts
│   ├── smoke.ts
│   └── types.ts
├── scripts/
│   └── setup.ps1
├── FIRST_RUN.cmd
├── START.cmd
├── SMOKE_TEST.cmd
├── config.example.json
├── package.json
└── tsconfig.json

開発コマンド

依存関係のインストール:

npm install

起動:

npm run dev

型チェック:

npm run check

ビルド:

npm run build

ビルド済みバージョンの実行:

npm start

スモークテスト:

npm run smoke

現在のバージョンの制限

現在のバージョンには以下がありません:

• Webインターフェース;

• ユーザーシステム;

• データベース;

• 個々のシェルコマンドのACL;

• サーバーレベルでの潜在的に危険なコマンドの確認;

• MCP自体のDockerコンテナ;

• 個別のランタイムプロファイル;

• 再起動後のアクティブプロジェクトの保存;

• パブリックリモートエンドポイント;

• マルチユーザーモード。

これらの機能は、必要に応じて追加される可能性があります。

診断

Node.jsが見つからない

確認します:

node --version
npm --version

Node.js 20以降が必要です。

MCPは起動しているが、クライアントが接続できない

まず、次を確認します:

http://127.0.0.1:7676/health

/healthが利用できない場合、問題はローカルMCP側にあります。

/healthが機能する場合は、MCPエンドポイントを確認します:

http://127.0.0.1:7676/mcp

および使用しているMCPトンネルの設定。

ポート7676が使用中

config.local.jsonでポートを変更します:

{
  "port": 7677
}

その後、MCPクライアントで新しいポートを使用します。

プロジェクトが検出されない

確認します:

1. プロジェクトがrootsのいずれかの中にあるか;

2. ディレクトリがサポートされているプロジェクトマーカーを含むか;

3. scanDepthの値が十分か;

4. 必要に応じて、projectsを介してプロジェクトを明示的に追加します。

テクノロジー

• TypeScript;

• Node.js;

• Model Context Protocol;

• 公式MCP TypeScript SDK。

ドキュメント:

https://modelcontextprotocol.io/
https://github.com/modelcontextprotocol/typescript-sdk