scopewalker-mcp

Scopewalker MCP

AI エージェントは、そうしないよう指示するルールファイルがあっても、1000 行を超えるソースファイルを喜んで作成し、関数呼び出しに 20 個目のパラメーターを追加します。Scopewalker は、より厳格なコードベースの基準を適用するために開発されました。

これはローカル MCP サーバー（オープンソース、stdio 経由で動作し、ネットワーク呼び出しを行いません）で、読み取り専用ツールを 9 個提供します。

• get_line_counts - ファイルごとの行数（合計、コード、空行、コメント）を取得します。並べ替え、拡張子フィルター、プロジェクト全体の合計にも対応します。
• get_functions - 関数とメソッドを検出します。ファイルごとの件数、または detail=lines による関数ごとの行数指標を取得でき、巨大な関数を探すための min_lines フィルターも利用できます。
• get_complexity_metrics - 最大／平均ネスト深度とパラメーター数（JSX の props を含む）、インポート数、ファイルごとの認知的複雑度スコア、高／極端の重大度区分を備えた関数ごとの循環的複雑度を取得します。また、深くネストした関数やパラメーターが多すぎる関数をホットスポットとして示します。
• check_thresholds - サイズのしきい値を超えるファイルと関数を通知します（既定値：ファイルごとに 300 行、関数ごとに 100 行）。
• get_code_inventory - クラスとそのメソッド、関数、インターフェース／型、列挙型、定数を一覧表示し、それぞれがエクスポートされているかどうかを示します。プライベートシンボルは既定で非表示です。
• get_documentation_coverage - カバレッジ率に加え、ドキュメントコメントがないすべての関数、クラス、メソッドを表示します（JSDoc、Python の docstring、Rust の /// など、言語ごとの形式に対応）。
• get_code_smells - AST を使って実際のコメントをスキャンし、TODO/FIXME/HACK/XXX/BUG/UNUSED/DEPRECATED マーカーを検出します（文字列リテラルによる誤検出はありません）。さらに、TypeScript の as unknown as ／ as any as による二重キャストも検出します。
• get_prop_drilling - 多数の関数やファイルに引き渡されるパラメーター名を、引き渡しの根拠と高／中／低のリスク評価とともに表示します。
• find_dead_code - 参照されていないトップレベルのシンボルとプライベートメソッドを、確実な dead_code と人による判断が必要な unreferenced_exports に分けて表示します。

内部では tree-sitter（構文解析）＋ tokei（行数のカウント）＋ fast-glob（ファイルの検出）を使用しており、独自の構文解析は行いません。macOS と Claude Code でテスト済みですが、Cursor、VS Code、Windsurf、Antigravity CLI、Codex など、MCP に対応する他のツールでも動作するはずです。

クイックリファレンスについては TOOLS.md、各ツールのパラメーターと応答例については docs/、Scopewalker をスキル、サブエージェント、AGENTS.md に組み込む方法については docs/usage-examples.md を参照してください。

安全のための既定値

• ネットワークアクセスなし： すべての分析は stdio 経由でローカルに実行されるため、データがマシンの外部に送信されることはなく、API キーや外部サービスも必要ありません。
• パスのスコープ設定： すべてのツールは、許可されたルート内でのみ動作します。設定されている場合は SCOPEWALKER_ALLOWED_ROOTS=/abs/path1,/abs/path2 が優先されます。それ以外の場合、サーバーは MCP クライアントから共有されたワークスペースルートを使用し、共有されていない場合は現在の作業ディレクトリとシステムの一時ディレクトリを使用します。
• 大容量ファイルのガード： AST ベースのツールは、メモリー／CPU の過剰な使用を避けるため、1 MB を超えるファイルをスキップします。Tokei ベースの行数カウントには、この制限は適用されません。
• 入力上限： max_files は 10000、max_depth は 64、limit は 5000 が上限です。
• シンボリックリンク： ディレクトリのスキャンでは、シンボリックリンクをたどりません。
• 出力制限： limit を設定しない場合、ツールは既定で 20 個のファイル／項目を返します。
• コメントの編集： get_code_smells は既定でコメント本文を編集して返します。スニペットを明示的に返すには、include_text: true を指定してください。

要件

• Node.js 22+
• tokei - brew install tokei または cargo install tokei でインストールしてください。

インストール

Scopewalker は npm で scopewalker-mcp として公開されています。クローンやビルドは不要です。MCP クライアントで npx を使って実行するよう設定するか（以下の例を参照）、npm install -g scopewalker-mcp でグローバルにインストールしてください。

代わりにソースからビルドする場合は、開発を参照してください。

設定

Claude Code

claude mcp add --scope user scopewalker-mcp -- npx -y scopewalker-mcp

または、~/.claude.json に追加します。

{
  "mcpServers": {
    "scopewalker-mcp": {
      "command": "npx",
      "args": ["-y", "scopewalker-mcp"]
    }
  }
}

詳細は、Claude Code MCP のドキュメントを参照してください。

Claude Desktop

最新リリースから scopewalker-mcp.mcpb をダウンロードし、Claude Desktop で開くか、Settings > Extensions にドラッグして、ワンクリックでインストールします。

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）に追加します。

{
  "mcpServers": {
    "scopewalker-mcp": {
      "command": "npx",
      "args": ["-y", "scopewalker-mcp"]
    }
  }
}

または、File > Preferences > Cursor Settings > MCP から設定します。

詳細は、Cursor MCP のドキュメントを参照してください。

VS Code（GitHub Copilot）

ワークスペースの .vscode/mcp.json に追加します。

{
  "servers": {
    "scopewalker-mcp": {
      "command": "npx",
      "args": ["-y", "scopewalker-mcp"]
    }
  }
}

Agent Mode を有効にした VS Code 1.102 以降が必要です。

詳細は、VS Code MCP のドキュメントを参照してください。

Windsurf

~/.codeium/windsurf/mcp_config.json に追加します。

{
  "mcpServers": {
    "scopewalker-mcp": {
      "command": "npx",
      "args": ["-y", "scopewalker-mcp"]
    }
  }
}

または、Windsurf Settings > Cascade > Manage MCPs から設定します。

詳細は、Windsurf MCP のドキュメントを参照してください。

Antigravity CLI

~/.gemini/config/mcp_config.json（グローバル）または .agents/mcp_config.json（プロジェクトごと）に追加します。

{
  "mcpServers": {
    "scopewalker-mcp": {
      "command": "npx",
      "args": ["-y", "scopewalker-mcp"]
    }
  }
}

プロンプトパネル内で /mcp を使うと、サーバーのステータスを確認し、設定を再読み込みできます。

詳細は、Antigravity CLI MCP のドキュメントを参照してください。

Gemini CLI の場合は、同じ mcpServers 設定を ~/.gemini/settings.json に追加します。詳細は、Gemini CLI MCP のドキュメントを参照してください。

OpenAI Codex CLI

~/.codex/config.toml に追加します。

[mcp_servers.scopewalker-mcp]
command = "npx"
args = ["-y", "scopewalker-mcp"]

または、CLI を使います。

codex mcp add scopewalker-mcp -- npx -y scopewalker-mcp

詳細は、Codex MCP のドキュメントを参照してください。

使い方

設定が完了すると、アシスタントがScopewalkerのツールを自動的に呼び出します。特別な構文は必要ありません。たとえば、次のように尋ねてください。

• 「コミットする前に、このリポジトリがサイズのしきい値を満たしているか確認して」
• 「src/ 内で認知的複雑度が最も高い関数はどれ？」
• 「src/auth 内でドキュメント化されていないエクスポートを見つけて」
• 「このモジュールにTODO/FIXME/HACKマーカーは残っている？」
• 「パラメーターが5つを超える関数を表示して」

リクエストに適したツールとパラメーターが選択されます。

このリポジトリでは、スキルとエージェントを通じて共有品質要件を適用しています。

• .claude/skills/review-changes/SKILL.md：サイズ、複雑度、コードスメル、プロップドリリング、またはデッドコードに関する未解決の指摘がある場合、レビューを不合格にします
• .claude/agents/standards-enforcer.md：対応可能な指摘を修正し、再スキャンとテストで検証します
• .claude/skills/polish/SKILL.md：未解決の指摘をパイプライン全体で引き継ぎ、最終状態を検証します
• .claude/agents/docs-reality-sync.md：get_code_inventory と get_functions を使い、ドキュメントをコードと同期させます

開発

npm ではなくソースから実行するには、次のようにします。

git clone https://github.com/timohaa/scopewalker-mcp.git
cd scopewalker-mcp
npm install
npm run build

次に、MCP クライアントでビルド出力を指定します。例：claude mcp add --scope user scopewalker-mcp -- node /path/to/scopewalker-mcp/dist/index.js。

npm run build          # Build the project
npm run check          # Version sync + lint + typecheck
npm run test           # Run tests
npm run test:coverage  # Run tests with coverage

貢献のガイドラインはCONTRIBUTING.mdを、ツールの登録、エラー処理、テストのパターンはdocs/patterns.mdを参照してください。

対応言語

AST ベースのツール（get_line_counts 以外）は、次の言語を解析します。

• TypeScript/JavaScript（.ts、.tsx、.js、.jsx、.mjs、.cjs）
• Python（.py）
• Go（.go）
• Rust（.rs）
• Java（.java）
• C/C++（.c、.h、.cpp、.cc、.cxx、.hpp）
• Ruby（.rb）

get_line_counts は tokei を通じて実行されるため、tokei が認識するすべての言語について報告します。言語ごとの検出内容については、docs/tools-overview.md を参照してください。

ライセンス

MIT