Code Scanner Server

code-scanner-server

コードファイルをスキャンして定義（クラス、関数など）を検出し、.gitignore を尊重して行番号を表示するとともに、LLM に適した形式（XML／Markdown）で出力する CLI ツール兼 MCP サーバーです。

このプロジェクトは、TypeScript と Node.js で構築された多用途のコードスキャンツールを提供します。Tree-sitter 構文解析ライブラリを利用してソースコードを分析し、構造情報を抽出します。コマンドラインインターフェース（CLI）ツールおよび MCP（Model Context Protocol）サーバーのどちらとしても動作します。

注記： このツールは現在も活発に開発されています。主要な機能は動作しますが、一部の機能や特定の言語パーサーは十分にテストされておらず、バグや制限が含まれている可能性があります。

機能

• コード定義の抽出： 関数、クラス、変数、インターフェース、メソッドなどを識別します。
• 複数言語への対応： Tree-sitter を介して JavaScript（.js、.jsx）、TypeScript（.ts、.tsx）、C#（.cs）、PHP（.php）、CSS（.css）、Python（.py）を解析します。
• .gitignore への対応： .gitignore ファイルで定義されたルールを自動的に尊重します。
• 柔軟なフィルタリング： 定義の種類、修飾子（public、private）、名前パターン（正規表現）、ファイルパスパターンで結果を絞り込めます。
• 複数の出力形式： Markdown（デフォルト）、XML、JSON で結果を生成します。
• 詳細レベルの設定： 出力の詳細度を minimal、standard（デフォルト）、detailed から選べます。
• 2 つの動作モード： 単独の CLI ツールまたは統合された MCP サーバーとして実行できます。

使用モード

1. コマンドラインインターフェース（CLI）

ターミナルからスキャナーを直接実行します。このモードでは、対象のコードベースを指定する --directory 引数が必要です。

基本的な使い方：

node build/index.js --directory /path/to/your/codebase

主なオプション：

• -d, --directory <path>：スキャンするディレクトリへの絶対パスまたは相対パス（必須）。
• -p, --patterns <patterns...>：ファイル拡張子の Glob パターン（例："**/*.ts" "**/*.js"）。デフォルトでは JS、TSX、CS、PHP、CSS、PY ファイルが対象です。
• -f, --format <format>：出力形式（xml、markdown、json）。デフォルト：markdown。
• -l, --detail <level>：詳細レベル（minimal、standard、detailed）。デフォルト：standard。
• --include-types <types...>：特定の定義タイプのみを含めます（例：class、method）。
• --exclude-types <types...>：特定の定義タイプを除外します。
• --include-modifiers <modifiers...>：特定の修飾子を持つ定義のみを含めます（例：public）。
• --exclude-modifiers <modifiers...>：特定の修飾子を持つ定義を除外します。
• --name-pattern <regex>：JavaScript の正規表現パターンに一致する定義を含めます。
• --exclude-name-pattern <regex>：JavaScript の正規表現パターンに一致する定義を除外します。
• --include-paths <paths...>：追加で含めるファイルパスパターン（Glob）です。
• --exclude-paths <paths...>：除外するファイルパスパターン（Glob）です。
• -h, --help：すべてのオプションの詳細なヘルプ情報を表示します。

例（src 内の TypeScript ファイルをスキャンし、詳細な JSON を出力）：

node build/index.js -d ./src -p "**/*.ts" -f json -l detailed

2. MCP サーバーモード（scan_code ツール）

--directory 引数を指定せずに実行すると、ツールは MCP サーバーとして起動し、標準入出力を介してリクエストを受け付けます。これにより、AI アシスタントなどの MCP クライアントと連携できます。

• ツール名： scan_code
• 説明： 指定されたディレクトリ内のコードファイルをスキャンし、指定されたフィルターに基づいて定義の一覧を返します。
• 入力スキーマ： CLI オプションに対応する引数を受け付けます。directory プロパティは必須です。

  {
    "type": "object",
    "properties": {
      "directory": { "type": "string", "description": "Absolute path to the directory to scan." },
      "filePatterns": { "type": "array", "items": { "type": "string" }, "description": "Glob patterns for files.", "default": ["**/*.js", ..., "**/*.py"] },
      "outputFormat": { "type": "string", "enum": ["xml", "markdown", "json"], "default": "markdown" },
      "detailLevel": { "type": "string", "enum": ["minimal", "standard", "detailed"], "default": "standard" },
      "includeTypes": { "type": "array", "items": { "type": "string" } },
      "excludeTypes": { "type": "array", "items": { "type": "string" } },
      "includeModifiers": { "type": "array", "items": { "type": "string" } },
      "excludeModifiers": { "type": "array", "items": { "type": "string" } },
      "namePattern": { "type": "string", "description": "Regex pattern for names." },
      "excludeNamePattern": { "type": "string", "description": "Regex pattern to exclude names." },
      "includePaths": { "type": "array", "items": { "type": "string" } },
      "excludePaths": { "type": "array", "items": { "type": "string" } }
    },
    "required": ["directory"]
  }
  

• AI アシスタントでの使用例：「code-scanner-server scan_code を使用して、ディレクトリ /path/to/project を xml 形式で出力してください。」

インストール

1. 前提条件： Node.js と npm がインストールされていることを確認してください。
2. クローン（任意）： コードをまだお持ちでない場合は、リポジトリをクローンしてください。

   # git clone <repository_url>
   # cd code-scanner-server
   

3. 依存関係のインストール：

   npm install
   

4. ビルド： TypeScript コードをコンパイルします。

   npm run build
   

   これにより、実行可能な JavaScript ファイルが build/index.js に作成されます。

設定（MCP サーバー）

MCP サーバーモードを使用するには、MCP クライアントの設定ファイル（デスクトップアプリ用の claude_desktop_config.json や VS Code 拡張機能用の cline_mcp_settings.json など）に追加してください。

重要： 以下の例にある /path/to/code-scanner-server を、お使いのシステム上にあるこのプロジェクトの絶対パスに置き換えてください。

例（claude_desktop_config.json / cline_mcp_settings.json）：

{
  "mcpServers": {
    "code-scanner-server": {
      "command": "node",
      "args": [
        "/absolute/path/to/your/code-scanner-server/build/index.js" // <-- Replace this path! (e.g., "C:\\Users\\YourUser\\Projects\\code-scanner-server\\build\\index.js" on Windows)
      ],
      "env": {},
      "disabled": false,
      "autoApprove": [] // Add tool names here for auto-approval if desired
    }
  }
}

設定を変更した後、変更を反映するために MCP クライアントアプリケーション（IDE、デスクトップアプリ）を再起動してください。

開発

• ウォッチモード： ソースファイルが変更されるたびに、プロジェクトを自動的に再ビルドします。

  npm run watch
  

• デバッグ（MCP モード）： stdio 経由の MCP サーバーのデバッグは複雑な場合があります。より簡単にデバッグするには、MCP Inspector ツールを使用してください。

  npm run inspector
  

  Node.js インスペクターをアタッチした状態でサーバーを起動し、デバッグツール（Chrome DevTools など）を接続するための URL を表示します。

謝辞

このプロジェクトの開発には AI の支援が大きく活用されており、主に Visual Studio Code 用の Roo Code 拡張機能から利用した Google の Gemini 2.5 Pro モデルを使用しました。

ライセンス

このプロジェクトは GNU General Public License v3.0 の下でライセンスされています。詳細については LICENSE ファイルをご覧ください。