@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レジストリに公開されています：

パッケージ名: @masamunet/npm-dev-mcp
バージョン: 1.1.0
レジストリ: https://www.npmjs.com/package/@masamunet/npm-dev-mcp

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サーバーとして起動

npm start

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のインストール:

npm install -g 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

npm-dev-mcp

README Documentation

@masamunet/npm-dev-mcp

機能

利用可能なツール

scan_project_dirs

start_dev_server

get_dev_status

get_dev_logs

stop_dev_server

restart_dev_server

get_health_status

recover_from_state

インストールと使用

0. 公開情報

1. npx経由での直接使用（推奨）

2. グローバルインストール

3. ローカル開発用ビルド

4. MCPサーバーとして起動

5. Claude Codeでの設定

5.1 コマンドラインから追加（推奨）

5.2 手動での設定ファイル編集

5.3 Claude Codeの再起動

5.4 動作確認

開発

スクリプト

プロジェクト構造

対応プラットフォーム

トラブルシューティング

MCPサーバーが応答しない場合

1. 開発サーバーのみ復旧する場合

2. MCPサーバー全体を復旧する場合

3. 設定の確認

4. PM2を使用したプロセス管理（上級者向け）

5. 外部監視用ヘルスチェックエンドポイント

6. よくある問題と解決方法

ライセンス

Quick Actions

Key Features