Project Scope

Project Scope MCP Server

一款稳健、可用于生产环境的 Model Context Protocol（MCP）服务，赋能 AI Agent 深入理解并安全地操作软件代码库。

---

概述

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

在执行前验证 shell 命令是否存在注入风险。

• 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 操作

包含适用于 Agent 工作流的标准 Git 工具：

• git_status
• git_commit_history
• git_compare_branches
• git_init

---

故障排除

“仓库扫描过慢”

• 将大型目录（例如 vendor、node_modules）添加到 excludePatterns 中。
• 系统会自动跳过大型文件（>1MB）。

“重构解析失败”

• 重构前，请确保代码语法有效。Tree-sitter 解析器通常需要有效的语法才能生成准确的 AST。

---

许可证

本项目采用 ISC License 许可。