Skip to main content
Glama
masamunet

npm-dev-mcp

by masamunet
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Local

@masamunet/npm-dev-mcp

npm run devプロセスを管理するMCPサーバーです。プロジェクトの自動検出、バックグラウンド実行、ログ監視、ポート管理機能を提供します。

機能

  • プロジェクト自動検出: package.jsonとdevスクリプトを持つディレクトリを自動で検索

  • モノレポ対応: サブディレクトリのプロジェクトも検出・管理

  • 環境変数読み込み: .envファイルの自動検出・適用

  • ポート管理: 開発サーバーが使用するポートの自動検出

  • ログ監視: リアルタイムログ監視と履歴管理

  • プロセス管理: 複数プロジェクトの並行実行、安全な開始・停止・再起動

Related MCP server: DevTools MCP Server

利用可能なツール

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": "2個のDev serverが実行中です",
  "isRunning": true,
  "processes": [
    {
      "pid": 12345,
      "directory": "/path/to/project-a",
      "status": "running",
      "ports": [3000],
      "uptime": 120000
    },
    {
      "pid": 12346,
      "directory": "/path/to/project-b",
      "status": "running",
      "ports": [3001],
      "uptime": 60000
    }
  ]
}

get_dev_logs

npm run devのログを取得します。

パラメータ:

  • lines (オプション): 取得行数（デフォルト：50、最大：1000）

  • directory (オプション): 対象のプロジェクトディレクトリ。複数実行時に特定するために使用します。

{
  "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プロセスを停止します。

パラメータ:

  • directory (オプション): 対象のプロジェクトディレクトリ。複数実行時に特定するために使用します。

{
  "success": true,
  "message": "Dev serverを正常に停止しました",
  "wasRunning": true,
  "stoppedProcess": {
    "pid": 12345,
    "uptime": 300000,
    "ports": [3000]
  }
}

restart_dev_server

npm run devプロセスを再起動します。

パラメータ:

  • directory (オプション): 対象のプロジェクトディレクトリ。複数実行時に特定するために使用します。

{
  "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": {
    "devProcessesRecovered": true,
    "projectContextRecovered": true,
    "warnings": [],
    "restoredProcesses": [
      {
        "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 logs /path/to/app 50

# サーバー停止（ディレクトリ指定可）
npx @masamunet/npm-dev-mcp stop
npx @masamunet/npm-dev-mcp stop /path/to/app

# ヘルプ表示
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

Available Tools

9 tools
auto_recoverC

MCPサーバーの自動復旧を実行（ヘルスチェック→復旧→再検証）

ParametersJSON Schema
NameRequiredDescriptionDefault
maxRetriesNo最大復旧試行回数（デフォルト: 3）
forceRecoverNo強制復旧モード（デフォルト: false）
restartMcpNoMCPサーバー自体の再起動を含むか（デフォルト: false）

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. While it mentions the three-step sequence (health check → recovery → revalidation), it doesn't describe what constitutes a failed health check, what specific recovery actions are taken, what revalidation entails, whether the operation requires special permissions, or what happens if recovery fails. For an automated recovery tool with no annotation coverage, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise - a single Japanese sentence that efficiently communicates the core functionality. It's front-loaded with the main purpose and includes the operational sequence in parentheses. There's no wasted verbiage, though some might argue it's too brief for a complex automated recovery operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given this is a complex automated recovery tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what the tool returns, what constitutes success/failure, what side effects occur, or how it interacts with the MCP server ecosystem. The three-step sequence is mentioned but not elaborated, leaving significant gaps in understanding the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the input schema already documents all three parameters thoroughly with descriptions and defaults. The tool description adds no additional parameter information beyond what's in the schema. According to the scoring rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no param info in the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as executing automatic recovery of MCP servers with a specific sequence (health check → recovery → revalidation). It uses a specific verb ('実行' - execute) and resource ('MCPサーバーの自動復旧' - MCP server automatic recovery). However, it doesn't explicitly differentiate from sibling tools like 'recover_from_state' or 'restart_dev_server' which may have overlapping functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'recover_from_state', 'restart_dev_server', 'get_health_status', and 'get_dev_status' available, there's no indication of when this automated recovery sequence is preferred over manual recovery options or status checks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_dev_logsC

npm run devのログ取得

ParametersJSON Schema
NameRequiredDescriptionDefault
linesNo取得行数（デフォルト：50）
directoryNo対象ディレクトリ（複数起動時に指定）

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden for behavioral disclosure. While 'ログ取得' implies a read-only operation, it doesn't specify whether this requires specific permissions, how logs are formatted, whether they're real-time or historical, or any rate limits. The description mentions the source but lacks operational context needed for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise - a single Japanese phrase that directly states the tool's function. Every word earns its place with no wasted text. It's front-loaded with the core purpose and could not be more efficiently structured given its brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what format the logs are returned in, whether they include timestamps, error levels, or other metadata. Given the complexity of log retrieval and the lack of structured output documentation, the description should provide more context about the return value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both parameters well-documented in Japanese. The description doesn't add any parameter information beyond what's in the schema. Since the schema already fully describes 'lines' and 'directory', the baseline score of 3 is appropriate - the description doesn't compensate but doesn't need to given complete schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('ログ取得' - log retrieval) and specifies the source ('npm run dev'), making the purpose understandable. However, it doesn't distinguish this tool from potential sibling logging tools (none are listed, but the agent might assume others exist). The description is specific about what logs are being retrieved but lacks differentiation context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'get_dev_status' and 'get_health_status' available, there's no indication whether this tool should be used for monitoring, debugging, or other purposes. No prerequisites, timing, or exclusion criteria are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_dev_statusC

npm run devプロセスの状態確認

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool checks status but doesn't describe what information is returned (e.g., running/stopped, PID, uptime), whether it's a read-only operation, or any side effects. For a status-checking tool with zero annotation coverage, this is inadequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient phrase ('npm run devプロセスの状態確認') that directly states the purpose. It's appropriately sized for a simple tool with no parameters, though it could be slightly clearer in English for broader accessibility.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is incomplete. It doesn't explain what 'status' entails, how the result is formatted, or how it differs from sibling tools. For a status-checking tool in a server with multiple monitoring options, more context is needed to guide the agent effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and schema description coverage is 100% (since there are no parameters to describe). The description doesn't need to add parameter semantics, so a baseline of 4 is appropriate. No additional value is required or provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'npm run devプロセスの状態確認' states the purpose (checking the status of the npm run dev process) but is vague about what 'status' means. It doesn't distinguish from sibling tools like get_health_status or get_dev_logs, which might provide different types of status information. The Japanese text adds localization but doesn't improve specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like get_health_status or get_dev_logs. The description implies usage for checking dev process status but doesn't specify contexts, prerequisites, or exclusions. This leaves the agent to guess based on tool names alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_health_statusC

MCPサーバーのヘルス状態を取得

ParametersJSON Schema
NameRequiredDescriptionDefault
detailedNo詳細なヘルスレポートを取得するかどうか（デフォルト: false）

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves health status but doesn't describe what that includes (e.g., uptime, resource usage, error counts), whether it's a read-only operation, if it has side effects, or any rate limits. For a health-check tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence in Japanese: 'MCPサーバーのヘルス状態を取得'. It's front-loaded with the core purpose, has zero wasted words, and is appropriately sized for a simple tool. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 parameter, 100% schema coverage) and lack of annotations or output schema, the description is incomplete. It doesn't explain what health status entails, how it differs from sibling tools like 'get_dev_status', or what the return value looks like. For a health-check tool in a server management context, more context is needed to guide effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the 'detailed' parameter fully documented in the schema. The description doesn't add any parameter semantics beyond what the schema provides (e.g., it doesn't explain what 'detailed' health reports include). With high schema coverage, the baseline is 3, as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'MCPサーバーのヘルス状態を取得' (Get MCP server health status). It specifies the verb '取得' (get) and resource 'ヘルス状態' (health status), making the action clear. However, it doesn't differentiate from sibling tools like 'get_dev_status' or 'get_dev_logs', which also retrieve status information.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_dev_status' (which might provide different status information) or 'auto_recover' (which might handle health issues). There's no context about prerequisites, timing, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recover_from_stateC

保存された状態から復旧を試行

ParametersJSON Schema
NameRequiredDescriptionDefault
forceNo強制的に復旧を実行するかどうか（デフォルト: false）

TDQS

C2.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'attempt recovery' which implies a mutation operation, but doesn't specify what gets recovered, whether it's destructive to current state, what permissions are needed, or what happens on failure. The description is too vague to understand the tool's actual behavior beyond the basic concept.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (one phrase) but under-specified rather than efficiently informative. While it's front-loaded with the core concept, it lacks necessary detail about what's being recovered. The single sentence doesn't waste words, but fails to provide adequate information for tool selection.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a recovery tool with no annotations and no output schema, the description is incomplete. It doesn't explain what 'saved state' means, what gets recovered, success/failure conditions, or return values. Given the complexity implied by a recovery operation and the lack of structured metadata, the description should provide more context about the operation's scope and outcomes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With only 1 parameter and 100% schema description coverage, the schema already fully documents the 'force' parameter. The description doesn't add any parameter-specific information beyond what's in the schema, but with zero parameters requiring additional explanation, this meets the baseline expectation. The description doesn't need to compensate for any schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description '保存された状態から復旧を試行' (Attempt recovery from saved state) is a tautological restatement of the tool name 'recover_from_state'. It doesn't specify what type of recovery (system, data, application) or what 'saved state' refers to. While it includes a verb ('復旧を試行' - attempt recovery), it lacks specificity about the resource or scope being recovered.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus the 8 sibling tools listed (auto_recover, get_dev_logs, etc.). There's no mention of prerequisites, when recovery should be attempted, or what distinguishes this from 'auto_recover'. The agent receives no help in selecting this tool over alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

restart_dev_serverC

npm run devプロセス再起動

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryNo再起動対象のディレクトリ（複数起動時に指定。未指定時は唯一のプロセスまたはエラー）

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden but only states the action. It doesn't disclose behavioral traits such as whether it requires specific permissions, how it handles errors, or if it affects other processes. This leaves significant gaps for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero waste, clearly front-loading the core action. It's appropriately sized for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and a mutation tool with behavioral gaps, the description is incomplete. It lacks details on outcomes, error handling, or interaction with sibling tools, making it inadequate for safe agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents the single parameter. The description adds no additional meaning beyond what the schema provides, such as examples or edge cases, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('restart') and target ('npm run dev process'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'start_dev_server' or 'stop_dev_server' beyond the restart action, missing explicit sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'start_dev_server' or 'stop_dev_server'. The description only states what it does, without context for selection among siblings or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

scan_project_dirsB

プロジェクト内のpackage.jsonとdevスクリプトを検索

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions searching but doesn't clarify whether this is a read-only operation, if it requires specific permissions, what the output format might be, or any potential side effects like performance impacts. For a tool with zero annotation coverage, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence in Japanese that directly states the tool's function without any unnecessary words. It is front-loaded with the core action and resources, making it highly concise and well-structured for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (simple search operation with no parameters) and the lack of annotations and output schema, the description is minimally adequate. It states what the tool does but lacks details on behavior, output, or usage context. For a tool with no structured data beyond the input schema, this leaves gaps in completeness, though it meets the basic requirement of stating the purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the lack of inputs. The description doesn't need to add parameter semantics, and it doesn't introduce any confusion about parameters. A baseline score of 4 is appropriate as the description doesn't contradict the schema and the schema handles the parameter documentation completely.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: searching for package.json files and dev scripts within a project. It specifies both the target resources (package.json and dev scripts) and the action (searching). However, it doesn't explicitly differentiate from sibling tools like 'get_dev_logs' or 'get_dev_status', which might also involve project directory operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, context for usage, or comparisons to sibling tools such as 'get_dev_logs' or 'restart_dev_server'. This leaves the agent with minimal direction on appropriate invocation scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_dev_serverC

指定ディレクトリでnpm run devをバックグラウンドで開始

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryNo実行ディレクトリ（オプション、未指定時は自動検出）

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions running 'npm run dev' in the background, which implies a long-running process, but doesn't describe what happens if a server is already running, error handling, or output behavior. The description adds minimal context beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence in Japanese that directly states the tool's function. It's front-loaded with the core action and includes key details like 'バックグラウンドで' (in the background). There's no wasted text, making it appropriately concise for its purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (starting a background process) and lack of annotations and output schema, the description is incomplete. It doesn't explain what 'npm run dev' entails, how to verify success, or potential side effects. For a tool that initiates a server process, more context on behavior and outcomes is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with one optional parameter 'directory' documented as '実行ディレクトリ（オプション、未指定時は自動検出）'. The description doesn't add any parameter details beyond what the schema provides, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'npm run devをバックグラウンドで開始' (start npm run dev in the background). It specifies the action (start) and resource (npm run dev), though it doesn't explicitly differentiate from sibling tools like 'restart_dev_server' or 'stop_dev_server'. The description is specific but lacks sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose 'start_dev_server' over 'restart_dev_server' or other siblings, nor does it indicate any prerequisites or exclusions. Usage is implied from the action, but no explicit guidelines are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

stop_dev_serverC

npm run devプロセス停止

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryNo停止対象のディレクトリ（複数起動時に指定。未指定時は唯一のプロセスまたはエラー）

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose important behavioral traits like whether this is destructive (likely yes, but not stated), what happens if no process is running, error conditions, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise single phrase that communicates the core purpose efficiently. No wasted words or unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive operation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'stop' entails, what gets terminated, error handling, or return values, leaving significant gaps for agent understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the single parameter well. The description adds no parameter information beyond what's in the schema, meeting the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('stop') and target ('npm run dev process'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'restart_dev_server' or 'auto_recover' that might also affect the dev server process.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives like 'restart_dev_server' or 'auto_recover'. The description only states what it does, not when it's appropriate versus other options.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • Changedget_dev_logs1 field changed
      • addedInput schema / properties / directory
        Added value: +{
+  "description": "対象ディレクトリ（複数起動時に指定）",
+  "type": "string"
+}
    • Changedrestart_dev_server1 field changed
      • addedInput schema / properties / directory
        Added value: +{
+  "description": "再起動対象のディレクトリ（複数起動時に指定。未指定時は唯一のプロセスまたはエラー）",
+  "type": "string"
+}
    • Changedstop_dev_server1 field changed
      • addedInput schema / properties / directory
        Added value: +{
+  "description": "停止対象のディレクトリ（複数起動時に指定。未指定時は唯一のプロセスまたはエラー）",
+  "type": "string"
+}
  2. 9 tool updates
    • First observedauto_recover
    • First observedget_dev_logs
    • First observedget_dev_status
    • First observedget_health_status
    • First observedrecover_from_state
    • First observedrestart_dev_server
    • First observedscan_project_dirs
    • First observedstart_dev_server
    • First observedstop_dev_server
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0

Scored across 9 tools

Disambiguation5/5

Every tool has a clearly distinct purpose with no ambiguity. For example, get_dev_logs retrieves logs, get_dev_status checks process state, and restart_dev_server restarts the process—each targets a specific action on a specific resource. There is no overlap in functionality that would cause misselection.

Naming Consistency5/5

Tool names follow a consistent verb_noun pattern throughout, such as get_dev_logs, restart_dev_server, and scan_project_dirs. All tools use snake_case with descriptive verbs (e.g., get, restart, scan, start, stop), making them predictable and readable.

Tool Count5/5

With 9 tools, the count is well-scoped for managing npm development processes and MCP server health. Each tool earns its place by covering distinct aspects like monitoring, control, recovery, and project scanning, without being excessive or insufficient for the domain.

Completeness5/5

The tool set provides complete lifecycle coverage for npm development and MCP server management. It includes monitoring (get_dev_status, get_health_status), control (start, stop, restart), recovery (auto_recover, recover_from_state), and utilities (scan_project_dirs, get_dev_logs), with no obvious gaps that would cause agent failures.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • DevServer MCP

    Uninen
    A
    license
    Not graded
    quality
    F
    maintenance
    An MCP server that enables programmatic management and monitoring of development servers through a unified interface and interactive TUI. It provides tools for process control, log streaming, and experimental browser automation via Playwright.
    1
    MIT

  • devctl-mcp

    adarsh-devappsys
    F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that lets Claude manage long-running development processes across frameworks like Flutter, Next.js, Spring Boot, and Vite, with lifecycle control, log streaming, and hot reload support.
    1
    -

  • bg-server-mcp-shell

    bgbruno
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for running long-running processes in PTY with real-time output streaming, enabling interactive dev servers, watch modes, and CLI tools.
    21
    MIT

Appeared in Searches