Project Scope

Project Scope MCP Server

AI エージェントに、ソフトウェアリポジトリの深い意味理解と安全な操作を可能にする、堅牢で本番環境に対応した Model Context Protocol（MCP）サーバーです。

---

概要

Project Scope は、単純なファイル読み取りにとどまらず、意味解析、AST ベースのリファクタリング、Git 統合、多層防御によるセキュリティ検証を提供します。大規模言語モデル（LLM）がコードベースを確実かつ安全に操作できるようにし、チャットインターフェイスと複雑な開発ワークフローの間を橋渡しします。

主な機能

• 意味的なリポジトリ解析：Tree-sitter を使用して、コード構造、依存関係、関連性を解析して理解します。
• コンテキストを考慮したセキュリティ：ソースコードで誤検知をゼロにし、実行時入力に含まれる SQLi、XSS、RCE の試みを検出する、高度なスキャナーです。
• 安全なリファクタリング：構文エラーを防ぐ「最初にプレビュー」機能を備えた、AST ベースの名前変更および抽出ツールです。
• Git 統合：履歴、差分、ブランチ操作を含む、包括的なバージョン管理を行います。
• 多層防御：プロンプトインジェクション検出（Regex + LLM Guard）、入力検証、ファイルアクセス制御など、多層的な保護を備えています。

---

目次

• インストール
• 設定
• セキュリティアーキテクチャ
• クライアントの接続
• ツールリファレンス
  • リポジトリ解析
  • セキュリティスキャン
  • リファクタリング
  • Git 操作
• トラブルシューティング
• ライセンス

---

---

クイックスタート

npx ですぐに実行できます。

npx -y @adityasasidhar/project-scope-mcp

---

インストール（ソースから）

ソースからビルドするには、次の手順を実行します。

# Clone the repository
git clone https://github.com/adityasasidhar/Project-Scope-MCP.git
cd Project-Scope-MCP

# Install dependencies
npm install

# Build the project
npm run build

---

設定

Project Scope ではセキュリティを最優先しています。サーバーはリスクプロファイルに合わせて高度にカスタマイズできます。

セキュリティモード

• strict（デフォルト）：潜在的な脅威が検出された場合、操作を直ちにブロックします。
• advisory：ログと警告を生成しますが、操作は続行できます（初期監査に便利です）。

感度レベル

• high：検出を強化します。信頼できないユーザー入力に適しています。
• medium（デフォルト）：標準的な開発に適したバランスの取れたプロファイルです。
• low：確度の高い既知の攻撃シグネチャのみを検出します。

LLM Guard（任意）

プロンプトインジェクション攻撃への最先端の保護を有効にするには、Meta Llama Prompt Guard 2 を有効にします。

• リクエストで useGuardModel: true を設定します。
• 有効な HuggingFace API トークンが必要です。

---

セキュリティアーキテクチャ

このサーバーには、厳格な脅威検出を維持しながら誤検知をなくすよう設計された、コンテキストを考慮したセキュリティスキャナーが備わっています。

インテリジェントなコンテキスト検出

スキャナーはファイルを分類し、適切な検証方法を判断します。

ファイルの種類	拡張子	スキャン方法	理由
ソースコード	.ts、.py、.go	スキップ	ソースコードの構文（セミコロン、パイプ）は攻撃パターンに似ているためです。
テンプレート	.hbs、.jinja2	構文を考慮	標準的なテンプレートトークンを許可しつつ、使用方法を検証します。
設定	.json、.yaml	最小限	標準的な設定文字列を許可します。
実行時入力	（なし）	厳格	悪意のあるペイロードを正規表現とヒューリスティックで全面的にスキャンします。

行単位のフィルタリング

解析対象のファイルでは、エンジンが次の要素をインテリジェントに無視します。

• コメント：//、/*、#
• インポート：import、require
• 定義：interface、type、class

これにより、コメントやテストファイルでセキュリティ上の脆弱性を記述しても誤検知は発生せず、悪意のあるペイロードを実行または受信した場合は確実に検出されます。

---

🔌 クライアントの接続

Claude Desktop

1. 設定ファイルを開きます：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. サーバー定義を追加します：

{
  "mcpServers": {
    "project-scope": {
      "command": "node",
      "args": ["/absolute/path/to/ProjectScopeMCP/dist/index.js"]
    }
  }
}

Claude Code（CLI）

公式の Claude Code CLI は、MCP をネイティブでサポートしています。

1. サーバーを追加します： ターミナルで次のコマンドを実行します：

   claude mcp add project-scope -- npx -y @adityasasidhar/project-scope-mcp
   

2. 確認します： claude を実行し、/mcp と入力して、接続済みのサーバーを確認します。

Codex CLI

Codex CLI（該当する場合）は、TOML 設定を介して MCP をサポートしています。

1. 設定を編集します： ~/.codex/config.toml を開きます。

2. サーバーを追加します：

   [mcp.servers.project-scope]
   command = "npx"
   args = ["-y", "@adityasasidhar/project-scope-mcp"]
   

Gemini CLI

Gemini CLI は、JSON 設定を介して MCP をサポートしています。

1. 設定を編集します： ~/.gemini/settings.json を開きます（存在しない場合は作成してください）。

2. サーバーを追加します：

   {
     "mcpServers": {
       "project-scope": {
         "command": "npx",
         "args": ["-y", "@adityasasidhar/project-scope-mcp"]
       }
     }
   }
   

汎用クライアント

MCP をサポートするその他のクライアント（Windsurf、Smithery、Goose、カスタム実装など）では、標準の stdio 設定を使用します：

npx -y @adityasasidhar/project-scope-mcp

Cursor

1. Cursor Settings（Cmd/Ctrl + Shift + J）を開きます。
2. Features > MCP Servers に移動します。
3. + Add New MCP Server をクリックします。
4. 次のように設定します：
   • Name：project-scope
   • Type：command
   • Command：node /absolute/path/to/ProjectScopeMCP/dist/index.js (または、必要に応じて npm run start を使用します)

GitHub Copilot（VS Code）

1. VS Code で GitHub Copilot Chat を開きます。
2. Attach Context（クリップ）または Tools アイコンをクリックします。
3. Connect to MCP Server... を選択します。
4. Command（または同様の項目）を選択し、次のように入力します：
   • Command：npx
   • Args：-y @adityasasidhar/project-scope-mcp

注：VS Code の設定で GitHub Copilot Agent Mode を有効にする必要があります。

ツールリファレンス

リポジトリの分析

get_repo_structure

.gitignore を尊重して、リポジトリの階層マップを生成します。

• input：{ "path": "/path/to/repo", "format": "tree" }

analyze_impact

AST を使用してすべての参照を検索し、シンボル（関数、変数）の変更による「影響範囲」を予測します。

• input：{ "path": "...", "filePath": "src/utils.ts", "symbolName": "processData", "line": 42 }

セキュリティスキャン

scan_repo_for_threats

リポジトリ全体を監査して、セキュリティリスク（シークレット、インジェクションパターン）を検出します。パフォーマンス向上のため、除外対象のファイルはスキップします。

• input：{ "path": "/path/to/repo", "excludePatterns": ["dist"] }

scan_file_for_threats

コンテキストを考慮するエンジンを使用して、単一のファイルまたは文字列を詳細にスキャンします。

• input：{ "filePath": "/path/to/file.ts", "mode": "strict" }

validate_shell_input

実行前にシェルコマンドを検証し、インジェクションのリスクを確認します。

• input：{ "input": "rm -rf /", "mode": "strict" }

リファクタリング

refactor_rename

プロジェクト全体でシンボルの名前を意味的に変更します。

• input：{ "path": "...", "filePath": "...", "oldName": "foo", "newName": "bar", "apply": false }
• Note：変更をプレビューするため、最初は必ず "apply": false を使用してください。

refactor_extract_function

選択したコード行を新しい関数に抽出します。

• input：{ "path": "...", "filePath": "...", "startLine": 10, "endLine": 20, "functionName": "newFunc" }

Git 操作

エージェント型ワークフロー向けの標準的な Git ツールが含まれています：

• git_status
• git_commit_history
• git_compare_branches
• git_init

---

トラブルシューティング

「リポジトリのスキャンが遅すぎます」

• 大きなディレクトリ（例：vendor、node_modules）をexcludePatternsに追加してください。
• 大きなファイル（>1MB）は自動的にスキップされます。

「リファクタリング時に解析に失敗しました」

• リファクタリングの前に、コードの構文が正しいことを確認してください。Tree-sitterのパーサーで正確なASTを生成するには、通常、有効な構文が必要です。

---

ライセンス

このプロジェクトはISC Licenseの下でライセンスされています。