Claude Codeの「npm run dev問題」を解決するMCPサーバーを作った話

Zenn

しゃばさんによる記事

Zenn

はじめに

github.com

github.com

問題の本質を理解する

• 開発サーバーをバックグラウンドで起動し、すぐに制御を返してくれる仕組み
• サーバーの状態を監視したり、ログを確認したり、必要に応じて再起動できる機能
• ブラウザのコンソールログやネットワークエラーを、サーバーサイドから確認できる仕組み つまり、開発環境全体の「可視性」を向上させることでした。

導入するとどうなるか

開発サーバーの起動と監視

Claude Code: start_dev_serverツールを呼び出し中...
引数: {
"command": "npm run dev",
"name": "nextjs-app",
"port": 3000,
"cwd": "/Users/dev/my-project"
}

結果:
Development server "nextjs-app" started successfully in background.
Command: npm run dev
Port: 3000
PID: 12345
Working Directory: /Users/dev/my-project

Server is running in the background. Use check_dev_server to monitor status.

ブラウザログの統合監視

{
	"totalLogs": 157,
	"portStats": {
		"3000": 98,
		"8080": 59
	},
	"recentErrors": [
		{
			"timestamp": "2024-06-10T15:23:45.123Z",
			"level": "error",
			"message": "POST <http://localhost:3000/api/users> 500 (Internal Server Error)",
			"url": "<http://localhost:3000/dashboard>",
			"port": "3000"
		},
		{
			"timestamp": "2024-06-10T15:24:12.456Z",
			"level": "error",
			"message": "Uncaught TypeError: Cannot read properties of undefined (reading 'name')",
			"url": "<http://localhost:3000/profile>",
			"port": "3000"
		}
	]
}

統合デバッグ体験

⏺ ブラウザでエラーが発生していることを検出しました。詳細を確認します。

⏺ devtools:get_browser_logs (MCP)(filter: {"level": ["error"], "limit": 10})
⎿ 最新のエラーログ:
- GET <http://localhost:3000/_next/static/css/app.css> 404 (Not Found)
- GET <http://localhost:3000/favicon.ico> 404 (Not Found)

⏺ 静的ファイルが見つからないエラーが発生しています。開発サーバーのログも確認してみましょう。

⏺ devtools:get_server_logs (MCP)(name: "nextjs-app", lines: 10)
⎿ サーバーログから、ビルドプロセスでエラーが発生していることがわかりました。

⏺ 開発サーバーを再起動してみましょう。

⏺ devtools:restart_dev_server (MCP)(name: "nextjs-app")
⎿ Development server "nextjs-app" started successfully in background.
Server is running in the background.

⏺ 開発サーバーを再起動しました。ブラウザでページをリロード（⌘+R）してみてください。

設計について

• 新しいツールをClaude Codeに教えるのも簡単
• 既存のWebアプリケーションに一切の変更を加えずに済む

実装とClaudeCodeとのラリー

プロセス管理まわり

// 最初の実装（問題あり）
const childProcess = spawn(cmd, cmdArgs, options);
// すぐに成功として返してしまう
return { success: true };

const startupPromise = new Promise<boolean>((resolve) => {
const timeout = setTimeout(() => resolve(true), 2000);childProcess.once('exit', () => {
  clearTimeout(timeout);
  resolve(false);
});

setTimeout(() => {
  if (!childProcess.killed && childProcess.exitCode === null) {
    clearTimeout(timeout);
    resolve(true);
  }
}, 500);
});

ブラウザログ収集

1. Injected Script: ページのコンテキストで動作し、console.*メソッドをオーバーライド
2. Content Script: Injected Scriptからのメッセージを中継
3. Background Service Worker: MCPサーバーへのHTTP通信を担当

// Injected Scriptでのconsole.logの傍受
Object.keys(originalConsole).forEach(method => {
	console[method] = function(...args) {
		// 元のメソッドを呼び出し
		originalConsole[method].apply(console, args);
		// ログ情報をContent Scriptに送信
		sendLog(method, args);
	};
});

// fetchのエラー検出
const originalFetch = window.fetch;
window.fetch = function(...args) {
const request = originalFetch.apply(this, args);
return request.then(response => {
  if (!response.ok) {
    const url = args[0];
    const method = args[1]?.method || 'GET';
    sendLog('error', [`${method} ${url} ${response.status} (${response.statusText})`]);
  }
  return response;
}).catch(error => {
  // ネットワークエラーをログに記録
  const url = args[0];
  const method = args[1]?.method || 'GET';
  sendLog('error', [`Network Error: ${method} ${url}`, error.message]);
  throw error;
});
};

ログ管理方法

const timestamp = new Date().toISOString();
const truncatedLog = log.length > this.maxLogLength
  ? log.substring(0, this.maxLogLength) + '...[truncated]'
  : log;

server.logs.push(`[${timestamp}] ${truncatedLog}`);

if (server.logs.length > this.maxLogLines) {
  server.logs = server.logs.slice(-this.maxLogLines);
}
}

既存サーバーの発見機能

// ポートスキャンによるサーバー発見
const { stdout } = await execAsync(`lsof -i :${port}`);
const lines = stdout.trim().split('\\n');

if (lines.length > 1) {
const firstLine = lines[1];
const parts = firstLine.trim().split(/\\s+/);
const pid = parseInt(parts[1]);

// プロセス情報を取得してサーバーリストに追加
const { stdout: commandOutput } = await execAsync(`ps -p ${pid} -o command=`);
const command = commandOutput.trim();

return { port, pid, command, protocol: 'tcp' };
}

クリーンアップの重要性

constructor() {
	process.on('exit', () => this.cleanup());
	process.on('SIGINT', () => this.cleanup());
	process.on('SIGTERM', () => this.cleanup());
}

private cleanup(): void {
	for (const [name, server] of this.servers) {
		if (server.status === 'running' || server.status === 'starting') {
			console.error(`Cleaning up server "${name}"`);
			server.process.kill('SIGTERM');
		}
	}
}

おわりに