@masamunet/npm-dev-mcp
npm run devプロセスを管理するMCPサーバーです。プロジェクトの自動検出、バックグラウンド実行、ログ監視、ポート管理機能を提供します。
機能
- プロジェクト自動検出: package.jsonとdevスクリプトを持つディレクトリを自動で検索
- モノレポ対応: サブディレクトリのプロジェクトも検出・管理
- 環境変数読み込み: .envファイルの自動検出・適用
- ポート管理: 開発サーバーが使用するポートの自動検出
- ログ監視: リアルタイムログ監視と履歴管理
- プロセス管理: 安全な開始・停止・再起動
利用可能なツール
scan_project_dirs
プロジェクト内のpackage.jsonとdevスクリプトを検索します。
{
"success": true,
"message": "2個のプロジェクトが見つかりました",
"projects": [
{
"directory": "/path/to/project",
"name": "my-app",
"devScript": "vite",
"hasEnvFile": true,
"envPath": "/path/to/project/.env",
"priority": 15
}
]
}
start_dev_server
指定ディレクトリでnpm run devをバックグラウンドで開始します。
パラメータ:
directory (オプション): 実行ディレクトリ（未指定時は自動検出）
{
"success": true,
"message": "Dev serverが開始されました",
"process": {
"pid": 12345,
"directory": "/path/to/project",
"status": "running",
"startTime": "2024-01-01T00:00:00.000Z",
"ports": [3000]
}
}
get_dev_status
npm run devプロセスの状態を確認します。
{
"success": true,
"message": "Dev serverはrunning状態です",
"isRunning": true,
"process": {
"pid": 12345,
"directory": "/path/to/project",
"status": "running",
"ports": [3000],
"uptime": 120000
},
"logs": {
"total": 50,
"errors": 0,
"warnings": 2,
"hasRecentErrors": false
}
}
get_dev_logs
npm run devのログを取得します。
パラメータ:
lines (オプション): 取得行数（デフォルト：50、最大：1000）
{
"success": true,
"message": "50行のログを取得しました",
"logs": [
{
"timestamp": "2024-01-01T00:00:00.000Z",
"level": "info",
"source": "stdout",
"message": "Server running on http://localhost:3000"
}
]
}
stop_dev_server
npm run devプロセスを停止します。
{
"success": true,
"message": "Dev serverを正常に停止しました",
"wasRunning": true,
"stoppedProcess": {
"pid": 12345,
"uptime": 300000,
"ports": [3000]
}
}
restart_dev_server
npm run devプロセスを再起動します。
{
"success": true,
"message": "Dev serverを正常に再起動しました",
"restarted": true,
"newProcess": {
"pid": 12346,
"status": "running",
"ports": [3000]
}
}
get_health_status
MCPサーバー自身のヘルス状態を取得します。
パラメータ:
detailed (オプション): 詳細なヘルスレポートを取得するかどうか（デフォルト: false）
{
"success": true,
"message": "MCPサーバーは正常状態です",
"health": {
"isHealthy": true,
"uptime": 300,
"devServerStatus": "running",
"memoryUsage": {
"heapUsed": 45,
"rss": 78
},
"checks": {
"memory": true,
"processManager": true,
"devServer": true
},
"timestamp": "2024-01-01T00:00:00.000Z"
}
}
recover_from_state
保存された状態からの復旧を試行します。
パラメータ:
force (オプション): 強制的に復旧を実行するかどうか（デフォルト: false）
{
"success": true,
"message": "状態の復旧が完了しました",
"recovery": {
"devProcessRecovered": true,
"projectContextRecovered": true,
"warnings": [],
"previousProcess": {
"pid": 12345,
"directory": "/path/to/project",
"status": "running",
"ports": [3000]
},
"recoveryTimestamp": "2024-01-01T00:00:00.000Z"
}
}
インストールと使用
0. 公開情報
パッケージはnpmレジストリに公開されています：
1. npx経由での直接使用（推奨）
# プロジェクトをスキャン
npx @masamunet/npm-dev-mcp scan
# dev serverを開始
npx @masamunet/npm-dev-mcp start
# 状態確認
npx @masamunet/npm-dev-mcp status
# ログを表示
npx @masamunet/npm-dev-mcp logs 50
# サーバー停止
npx @masamunet/npm-dev-mcp stop
# ヘルプ表示
npx @masamunet/npm-dev-mcp --help
2. グローバルインストール
# グローバルインストール
npm install -g @masamunet/npm-dev-mcp
# 使用例
npm-dev-mcp scan
npm-dev-mcp start
npm-dev-mcp status
3. ローカル開発用ビルド
git clone https://github.com/masamunet/npm-dev-mcp.git
cd npm-dev-mcp
npm install
npm run build
4. MCPサーバーとして起動
5. Claude Codeでの設定
5.1 コマンドラインから追加（推奨）
Claude Codeのmcpコマンドを使用して簡単に追加できます：
claude mcp add npm-dev-mcp -- npx @masamunet/npm-dev-mcp --mcp
このコマンド実行後、Claude Codeを再起動すると@masamunet/npm-dev-mcpが利用可能になります。
5.2 手動での設定ファイル編集
手動で設定する場合は、設定ファイルを直接編集します：
設定ファイルの場所:
macOS:
~/.claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
設定内容:
方法1: 直接パス指定
{
"mcpServers": {
"@masamunet/npm-dev-mcp": {
"command": "node",
"args": ["/absolute/path/to/@masamunet/npm-dev-mcp/dist/index.js"]
}
}
}
方法2: npx経由（--mcpフラグ使用）
{
"mcpServers": {
"@masamunet/npm-dev-mcp": {
"command": "npx",
"args": ["@masamunet/npm-dev-mcp", "--mcp"]
}
}
}
注意事項:
- 方法1の
argsの配列内のパスは絶対パスで指定してください - 例:
"/Users/username/projects/@masamunet/npm-dev-mcp/dist/index.js" - 相対パスや
~は使用できません - 方法2では
--mcpフラグが必要です（MCPサーバーモードを強制）
5.3 Claude Codeの再起動
設定を追加した後、Claude Codeを再起動すると、@masamunet/npm-dev-mcpサーバーが利用可能になります。
5.4 動作確認
Claude Code内で以下のように使用できます：
プロジェクトを検索してください
→ scan_project_dirs ツールが実行される
npm run devを開始してください
→ start_dev_server ツールが実行される
開発サーバーの状態を確認してください
→ get_dev_status ツールが実行される
開発
スクリプト
npm run build: TypeScriptをコンパイルnpm run dev: 開発モード（ウォッチモード）npm start: MCPサーバーを起動
プロジェクト構造
src/
├── index.ts # MCPサーバーエントリーポイント
├── types.ts # 型定義
├── components/ # コアコンポーネント
│ ├── ProjectScanner.ts # プロジェクト検出
│ ├── ProcessManager.ts # プロセス管理
│ ├── LogManager.ts # ログ管理
│ ├── PortDetector.ts # ポート検出
│ └── EnvLoader.ts # 環境変数読み込み
├── tools/ # MCPツール実装
└── utils/ # ユーティリティ関数
対応プラットフォーム
- macOS (lsofコマンド使用)
- Linux (netstatコマンド使用)
- Node.js 18以上
トラブルシューティング
MCPサーバーが応答しない場合
MCPサーバーがクラッシュしたり応答しなくなった場合の復旧方法：
1. 開発サーバーのみ復旧する場合
Claude Code内での復旧:
→ restart_dev_server ツールが自動実行されます
コマンドラインからの復旧:
# 開発サーバーの状態確認
npx @masamunet/npm-dev-mcp status
# 開発サーバー再起動
npx @masamunet/npm-dev-mcp restart
# ログ確認
npx @masamunet/npm-dev-mcp logs 50
2. MCPサーバー全体を復旧する場合
Claude Codeの再起動:
- Claude Codeアプリケーションを完全に終了
- アプリケーションを再起動
- MCPサーバーが自動的に再接続されます
手動でのMCPサーバー確認:
# プロセス確認
ps aux | grep @masamunet/npm-dev-mcp
# 必要に応じてプロセス終了
pkill -f @masamunet/npm-dev-mcp
3. 設定の確認
MCPサーバーが起動しない場合、設定ファイルを確認：
macOS:
cat ~/.claude/claude_desktop_config.json
Windows:
type %APPDATA%\Claude\claude_desktop_config.json
正しい設定例：
{
"mcpServers": {
"@masamunet/npm-dev-mcp": {
"command": "npx",
"args": ["@masamunet/npm-dev-mcp", "--mcp"]
}
}
}
4. PM2を使用したプロセス管理（上級者向け）
より堅牢な運用を行いたい場合、PM2プロセスマネージャーを使用できます：
PM2のインストール:
PM2でのMCPサーバー管理:
# MCPサーバーをPM2で開始
npm run pm2:start
# 状態確認
npm run pm2:status
# ログ確認
npm run pm2:logs
# 再起動
npm run pm2:restart
# 停止
npm run pm2:stop
# 完全削除
npm run pm2:delete
PM2の利点:
- 自動再起動（クラッシュ時）
- メモリ監視と制限
- ログローテーション
- クラスター機能（必要に応じて）
5. 外部監視用ヘルスチェックエンドポイント
外部の監視システム（Prometheus、Nagios等）と連携するためのHTTPエンドポイントを提供できます：
ヘルスエンドポイントの有効化:
# 環境変数を設定
export HEALTH_ENDPOINT=true
export HEALTH_PORT=8080
export HEALTH_HOST=127.0.0.1
# MCPサーバーを開始
npm start
利用可能なエンドポイント:
# 基本ヘルスチェック
curl http://127.0.0.1:8080/health
# 詳細ヘルスレポート
curl http://127.0.0.1:8080/health/detailed
# Prometheusメトリクス
curl http://127.0.0.1:8080/metrics
環境変数:
HEALTH_ENDPOINT: エンドポイントを有効化（true/false）HEALTH_PORT: ポート番号（デフォルト: 8080）HEALTH_HOST: ホスト（デフォルト: 127.0.0.1）HEALTH_PATH: ヘルスチェックパス（デフォルト: /health）
6. よくある問題と解決方法
問題: "spawn ENOENT" エラー
- 原因: Node.jsまたはnpxが見つからない
- 解決: PATHの確認とNode.jsの再インストール
問題: 開発サーバーが起動しない
- 原因: ポートが使用中、package.jsonの設定不備
- 解決:
npx @masamunet/npm-dev-mcp scan でプロジェクト検出を確認
問題: ログが表示されない
- 原因: プロセスが正常に開始されていない
- 解決:
npx @masamunet/npm-dev-mcp status で状態確認
ライセンス
MIT