NPMJS Model Context Protocol (MCP) Server

NPMJS Model Context Protocol (MCP) サーバー（v1.1.5）

1. プロジェクトの目的

このプロジェクトの主な目的は、軽量な TypeScript ベースの Model Context Protocol（MCP）サーバーを作成することです。このサーバーは、npmjs パッケージに関するバージョン情報、ダウンロード統計、公開日、説明、ライセンスなどの構造化された情報を、シンプルで標準化された JSON 形式で提供します。この形式は、大規模言語モデル（LLM）や AI 駆動型の開発ツールでの利用に適しています。

このサーバーは、複数の npmjs API エンドポイントとの直接的なやり取りを抽象化することで、npm パッケージのメタデータへのアクセスを簡素化します。

2. セットアップ手順

1. リポジトリをクローンします：

   git clone https://github.com/yiannis-spyridakis/npmjs-mcp-server.git
   cd npmjs-mcp-server
   

2. 依存関係をインストールします：

   npm install
   

3. サーバーの実行

この MCP サーバーは、MCP クライアント（LLM エージェントや開発ツールなど）によって子プロセスとして実行されるように設計されています。Model Context Protocol を使用し、標準入力（stdin）と標準出力（stdout）を介してクライアントと通信します。

開発環境

ファイルの変更時に自動的に再起動するようにして、開発目的でサーバーを直接実行するには、次のコマンドを使用します。

npm run dev

または、変更を監視せずに一度だけ実行するには、次のコマンドを使用します。

npm run watch

（注：npm run watch は、開発用に package.json で指定されている nodemon と ts-node を使用します。npm run dev は ts-node を直接使用します。）

サーバーが起動し、標準入出力を介して MCP リクエストを待ち受けます。

本番環境向けのビルド

本番環境向けに TypeScript コードを JavaScript にコンパイルするには、次のコマンドを使用します。

npm run build

コンパイルされたファイルを含む dist ディレクトリが作成されます。

本番環境

本番環境でコンパイル済みのサーバーを実行するには、次のコマンドを使用します。

npm start

このコマンドは node dist/index.js を実行します。MCP クライアントは、このコマンドを子プロセスとして起動します。

4. 利用可能な MCP ツール

このサーバーは、MCP クライアントを使用して呼び出せるツールを提供します。

ツール：get_npm_package_summary

• 説明： パッケージの名前、最新バージョン、説明、最新バージョンの公開日、ライセンス、ホームページ、リポジトリの URL（利用可能な場合）など、基本的なパッケージ情報を提供します。
• 入力スキーマ：

  {
    "type": "object",
    "properties": {
      "packageName": {
        "type": "string",
        "description": "The name of the npm package (e.g., 'express', 'react')"
      }
    },
    "required": ["packageName"]
  }
  

ツール：get_npm_package_versions

• 説明： 利用可能なすべてのパッケージバージョンと、それぞれの公開日を一覧表示します。
• 入力スキーマ：

  {
    "type": "object",
    "properties": {
      "packageName": {
        "type": "string",
        "description": "The name of the npm package"
      }
    },
    "required": ["packageName"]
  }
  

ツール：get_npm_package_downloads

• 説明： ダウンロード統計を提供します。特定の期間を指定するか、period を省略するとデフォルトのすべての期間（last-day、last-week、last-month）を取得できます。
• 入力スキーマ：

  {
    "type": "object",
    "properties": {
      "packageName": {
        "type": "string",
        "description": "The name of the npm package"
      },
      "period": {
        "type": "string",
        "description": "Optional: 'last-day', 'last-week', 'last-month'. If omitted, all are fetched.",
        "enum": ["last-day", "last-week", "last-month"]
      }
    },
    "required": ["packageName"]
  }
  

ツール：get_npm_package_details

• 説明： 概要情報にメンテナーとキーワードを加えた、包括的な情報を提供します。
• 入力スキーマ：

  {
    "type": "object",
    "properties": {
      "packageName": {
        "type": "string",
        "description": "The name of the npm package"
      }
    },
    "required": ["packageName"]
  }
  

5. 利用可能な MCP プロンプト

ツールに加えて、このサーバーは、提供された変数に基づいて特定のユーザーリクエストを生成するためのプロンプトも提供します。これにより、一般的なやり取りを簡素化できます。

プロンプト：get_summary_prompt

• 説明： 指定した npm パッケージの簡単な概要を取得するリクエストを生成します。
• 入力スキーマ：

  {
    "packageName": {
      "type": "string",
      "description": "The name of the npm package"
    }
  }
  

プロンプト：get_details_prompt

• 説明： メンテナーとリポジトリの URL を含む、指定した npm パッケージの詳細情報を取得するリクエストを生成します。
• 入力スキーマ：

  {
    "packageName": {
      "type": "string",
      "description": "The name of the npm package"
    }
  }
  

プロンプト：find_homepage_prompt

• 説明： 指定した npm パッケージの公式ホームページを探すリクエストを生成します。
• 入力スキーマ：

  {
    "packageName": {
      "type": "string",
      "description": "The name of the npm package"
    }
  }
  

プロンプト：list_versions_prompt

• 説明： 指定した npm パッケージで利用可能なすべてのバージョンと公開日を一覧表示するリクエストを生成します。
• 入力スキーマ：

  {
    "packageName": {
      "type": "string",
      "description": "The name of the npm package"
    }
  }
  

プロンプト：get_version_date_prompt

• 説明： 指定した npm パッケージの特定バージョンの公開日を調べるリクエストを生成します。
• 入力スキーマ：

  {
    "packageName": {
      "type": "string",
      "description": "The name of the npm package"
    },
    "version": {
      "type": "string",
      "description": "The specific version string (e.g., '16.8.0')"
    }
  }
  

プロンプト：get_downloads_prompt

• 説明： 指定した期間における、指定された npm パッケージのダウンロード数を取得するリクエストを生成します。
• 入力スキーマ：

  {
    "packageName": {
      "type": "string",
      "description": "The name of the npm package"
    },
    "timePeriod": {
      "type": "string",
      "enum": ["last-day", "last-week", "last-month"],
      "description": "The time period for download counts"
    }
  }
  

プロンプト：get_all_downloads_prompt

• 説明： 過去1日、1週間、1か月の指定された npm パッケージのダウンロード数を取得するリクエストを生成します。
• 入力スキーマ：

  {
    "packageName": {
      "type": "string",
      "description": "The name of the npm package"
    }
  }
  

プロンプト：audit_project_prompt

• 説明： 指定されたプロジェクトディレクトリ内の依存関係について、セキュリティ上の脆弱性を監査するリクエストを生成します。
• 入力スキーマ：

  {
    "projectPath": {
      "type": "string",
      "description": "The path to the project directory (e.g., '.', '../my-app')"
    }
  }
  

プロンプト：simulate_audit_fix_prompt

• 説明： 指定されたプロジェクトディレクトリで npm audit fix を実行した場合のシミュレーションをリクエストするプロンプトを生成します。
• 入力スキーマ：

  {
    "projectPath": {
      "type": "string",
      "description": "The path to the project directory (e.g., '.', '../my-app')"
    }
  }
  

6. ツールの使用例と応答

以下の例では、ツールの呼び出し方法（概念上の例であり、実際のクライアントでの使用方法は異なる場合があります）と、成功した MCP CallToolResponse の data 部分に含まれる内容を示します。MCP SDK が応答全体（バージョン、タイムスタンプなど）を処理します。MCP 応答の data フィールドには content 配列が含まれ、その最初の要素は text 型のオブジェクトであり、その text プロパティに以下に示す結果の JSON 文字列が格納されます。

例：get_npm_package_summary の呼び出し

ツール呼び出しの引数：

{
  "packageName": "express"
}

data.content[0].text に含まれる想定 JSON 文字列：

{
  "name": "express",
  "latestVersion": "4.19.2",
  "description": "Fast, unopinionated, minimalist web framework for node.",
  "publishDateLatest": "2024-03-25T14:30:36.103Z",
  "license": "MIT",
  "homepage": "http://expressjs.com/",
  "repository": "https://github.com/expressjs/express",
  "source": "https://registry.npmjs.org/express"
}

(注：バージョンと日付は例であり、クエリ実行時の実際のデータが反映されます)

例：get_npm_package_versions の呼び出し

ツール呼び出しの引数：

{
  "packageName": "express"
}

data.content[0].text に含まれる想定 JSON 文字列：

{
  "versions": {
    "1.0.0": "2010-12-29T19:38:25.450Z",
    "1.0.1": "2010-12-29T19:38:25.450Z",
    "4.19.2": "2024-03-25T14:30:36.103Z"
    // ... potentially many more versions
  },
  "source": "https://registry.npmjs.org/express"
}

例：get_npm_package_downloads の呼び出し（すべてのデフォルト期間）

ツール呼び出しの引数：

{
  "packageName": "express"
}

data.content[0].text に含まれる想定 JSON 文字列：

{
  "downloads": {
    "last-day": 7895822,
    "last-week": 37439130,
    "last-month": 162348160
  },
  "package": "express",
  "source": "https://api.npmjs.org/downloads/point"
}

(注：ダウンロード数は例であり、クエリ実行時の実際のデータが反映されます)

例：get_npm_package_details の呼び出し

ツール呼び出しの引数：

{
  "packageName": "express"
}

data.content[0].text に含まれる想定 JSON 文字列：

{
  "name": "express",
  "latestVersion": "4.19.2",
  "description": "Fast, unopinionated, minimalist web framework for node.",
  "publishDateLatest": "2024-03-25T14:30:36.103Z",
  "license": "MIT",
  "homepage": "https://expressjs.com/",
  "repository": "https://github.com/expressjs/express",
  "maintainers": [
    { "name": "dougwilson", "email": "[email protected]" },
    { "name": "wesleytodd", "email": "[email protected]" }
    // ... other maintainers
  ],
  "keywords": [
    "express",
    "framework",
    "sinatra",
    "web",
    "rest",
    "restful",
    "router"
  ],
  "source": "https://registry.npmjs.org/express"
}

(注：バージョン、日付、メンテナー、キーワードは例であり、クエリ実行時の実際のデータが反映されます)

エラー処理

ツール呼び出しが失敗した場合（パッケージが見つからない、引数が無効など）、MCP サーバーは標準的な MCP エラー応答を返します。この応答に含まれる result.error オブジェクトには、問題の詳細を示す message が含まれます。

MCP エラー応答の例（概念上の構造）：

{
  "version": "0.2.0", // SDK version
  "id": "response-id-string",
  "type": "CallToolResponse",
  "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ",
  "result": {
    "error": {
      "type": "ToolError", // Or similar error type from SDK
      "message": "Package 'nonexistent-pkg' not found on npmjs."
      // Potentially other fields like 'toolName'
    }
  }
}

packageName などの必須引数が指定されていない場合、ツールハンドラーはエラーをスローし、同様の MCP エラー応答が返されます。

7. プロンプトの使用例

以下の例では、引数を指定して利用可能なプロンプトを使用する方法を示します。サーバーは、生成されたユーザーメッセージを含む GetPromptResponse を返します。

例：get_summary_prompt の使用

プロンプト呼び出しの引数：

{ "packageName": "react" }

生成されたユーザーメッセージ（messages[0].content.text）：

Get a quick summary of the 'react' npm package.

例：get_version_date_prompt の使用

プロンプト呼び出しの引数：

{ "packageName": "lodash", "version": "4.17.21" }

生成されたユーザーメッセージ（messages[0].content.text）：

What was the publish date of version 4.17.21 for 'lodash'?

例：get_downloads_prompt の使用

プロンプト呼び出しの引数：

{ "packageName": "axios", "timePeriod": "last-week" }

生成されたユーザーメッセージ（messages[0].content.text）：

How many times was 'axios' downloaded in the last-week?

例：audit_project_prompt の使用

プロンプト呼び出しの引数：

{ "projectPath": "../my-frontend-app" }

生成されたユーザーメッセージ（messages[0].content.text）：

Audit the dependencies in the project at '../my-frontend-app' for security vulnerabilities.

例：simulate_audit_fix_prompt の使用

プロンプト呼び出しの引数：

{ "projectPath": "." }

生成されたユーザーメッセージ（messages[0].content.text）：

Simulate running 'npm audit fix' on the project at '.' and show me what would change.