@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の再起動:

1. Claude Codeアプリケーションを完全に終了
2. アプリケーションを再起動
3. 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