{"_id":"@adityasasidhar/project-scope-mcp","name":"@adityasasidhar/project-scope-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@adityasasidhar/project-scope-mcp","version":"1.0.0","description":"MCP server for repository analysis, Git operations, and code refactoring tools","main":"dist/index.js","bin":{"project-scope":"dist/index.js"},"scripts":{"build":"tsc","dev":"tsx src/index.ts","prepare":"npm run build"},"devDependencies":{"@types/node":"^25.0.3","tsx":"^4.21.0","typescript":"^5.9.3"},"keywords":["mcp","model-context-protocol","git","refactoring","code-analysis"],"author":{"name":"adityasasidhar"},"license":"ISC","repository":{"type":"git","url":"git+https://github.com/adityasasidhar/Project-Scope-MCP.git"},"type":"module","dependencies":{"@huggingface/inference":"^4.13.5","@modelcontextprotocol/sdk":"^1.25.1","fast-glob":"^3.3.3","ignore":"^7.0.5","simple-git":"^3.30.0","tree-sitter":"^0.25.0","tree-sitter-css":"^0.25.0","tree-sitter-go":"^0.25.0","tree-sitter-html":"^0.23.2","tree-sitter-java":"^0.23.5","tree-sitter-javascript":"^0.25.0","tree-sitter-python":"^0.25.0","tree-sitter-typescript":"^0.23.2"},"gitHead":"26c05312ff2b82328964b50c1ed422541042763b","_id":"@adityasasidhar/project-scope-mcp@1.0.0","bugs":{"url":"https://github.com/adityasasidhar/Project-Scope-MCP/issues"},"homepage":"https://github.com/adityasasidhar/Project-Scope-MCP#readme","_nodeVersion":"22.21.1","_npmVersion":"11.6.4","dist":{"integrity":"sha512-Ypw9Bz1uUGDk5DNukt+BhVidvyvGBQ2Za1dL0Dy5GhZhMbonOObgixv8ISK84ssWc75V9oXJcKMLXTVBa6qP2Q==","shasum":"37ff7f3eb7a853f9026d0ceef2e734cd45f7948a","tarball":"https://registry.npmjs.org/@adityasasidhar/project-scope-mcp/-/project-scope-mcp-1.0.0.tgz","fileCount":34,"unpackedSize":303838,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDYhZ8FHTxzv5cOUe/T3IJZJE1x0bi3KhxVEaCtcHEexAiEA43cLi8cG/SgOhtcpBZ8z29pWXUz8O8eigXO7WavQZZc="}]},"_npmUser":{"name":"adityasasidhar","email":"telikicherlaadityasasidhar@gmail.com"},"directories":{},"maintainers":[{"name":"adityasasidhar","email":"telikicherlaadityasasidhar@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/project-scope-mcp_1.0.0_1767795767061_0.6414234946701372"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-07T14:22:46.979Z","1.0.0":"2026-01-07T14:22:47.269Z","modified":"2026-01-07T14:22:47.748Z"},"maintainers":[{"name":"adityasasidhar","email":"telikicherlaadityasasidhar@gmail.com"}],"description":"MCP server for repository analysis, Git operations, and code refactoring tools","homepage":"https://github.com/adityasasidhar/Project-Scope-MCP#readme","keywords":["mcp","model-context-protocol","git","refactoring","code-analysis"],"repository":{"type":"git","url":"git+https://github.com/adityasasidhar/Project-Scope-MCP.git"},"author":{"name":"adityasasidhar"},"bugs":{"url":"https://github.com/adityasasidhar/Project-Scope-MCP/issues"},"license":"ISC","readme":"# Project Scope MCP Server\n\n**A robust, production-ready Model Context Protocol (MCP) server empowering AI agents with deep semantic understanding and safe manipulation of software repositories.**\n\n---\n\n## Overview\n\nProject Scope moves beyond simple file reading to provide **semantic analysis**, **AST-based refactoring**, **Git integration**, and **defense-in-depth security validation**. It allows Large Language Models (LLMs) to interact with codebases reliably and safely, bridging the gap between chat interfaces and complex development workflows.\n\n## Key Features\n\n- **Semantic Repository Analysis**: Parse and understand code structure, dependencies, and relationships using Tree-sitter.\n- **Context-Aware Security**: Advanced scanner with zero false positives on source code, detecting SQLi, XSS, and RCE attempts in runtime inputs.\n- **Safe Refactoring**: AST-based renaming and extraction tools with \"preview first\" capabilities to prevent syntax errors.\n- **Git Integration**: Comprehensive version control management including history, diffing, and branch operations.\n- **Defense-in-Depth**: Multi-layered protection including Prompt Injection detection (Regex + LLM Guard), input validation, and file access controls.\n\n---\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Security Architecture](#security-architecture)\n- [Connecting Clients](#connecting-clients)\n- [Tool Reference](#tool-reference)\n  - [Repository Analysis](#repository-analysis)\n  - [Security Scanning](#security-scanning)\n  - [Refactoring](#refactoring)\n  - [Git Operations](#git-operations)\n- [Troubleshooting](#troubleshooting)\n- [License](#license)\n\n---\n\n## Installation\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\n---\n\n## Configuration\n\nSecurity is a primary focus of Project Scope. The server is highly customizable to match your risk profile.\n\n### Security Modes\n- **`strict`** (default): Blocks operations immediately if a potential threat is detected.\n- **`advisory`**: Logs and warnings are generated, but operations are allowed to proceed (useful for initial audits).\n\n### Sensitivity Levels\n- **`high`**: Aggressive detection, useful for untrusted user inputs.\n- **`medium`** (default): Balanced profile for standard development.\n- **`low`**: Only flags high-confidence known attack signatures.\n\n### LLM Guard (Optional)\nFor state-of-the-art protection against prompt injection attacks, enable **Meta Llama Prompt Guard 2**:\n- Set `useGuardModel: true` in your requests.\n- Requires a valid HuggingFace API token.\n\n---\n\n## Security Architecture\n\nThe server features a **Context-Aware Security Scanner** designed to eliminate false positives while maintaining rigorous threat detection.\n\n## Intelligent Context Detection\n\nThe scanner uses file categorization to determine the appropriate validation strategy:\n\n| File Type | Extension | Scanning Strategy | Reason |\n|-----------|-----------|-------------------|--------|\n| **Source Code** | `.ts`, `.py`, `.go` | **Skipped** | Source code syntax (semi-colons, pipes) mimics attack patterns. |\n| **Templates** | `.hbs`, `.jinja2` | **Syntax-Aware** | Validates usage but allows standard template tokens. |\n| **Config** | `.json`, `.yaml` | **Minimal** | Allows standard configuration strings. |\n| **Runtime Input** | (None) | **Strict** | Full regex and heuristic scanning for malicious payloads. |\n\n### Line-Level Filtering\n\nWithin analyzed files, the engine intelligently ignores:\n- **Comments**: `//`, `/*`, `#`\n- **Imports**: `import`, `require`\n- **Definitions**: `interface`, `type`, `class`\n\nThis ensures that *documenting* a security vulnerability in a comment or test file does not trigger a false alarm, while *executing* or *receiving* a malicious payload is caught.\n\n---\n\n## 🔌 Connecting Clients\n\n### Claude Desktop\n\n1. Open your configuration file:\n   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n2. Add the server definition:\n```json\n{\n  \"mcpServers\": {\n    \"project-scope\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/ProjectScopeMCP/dist/index.js\"]\n    }\n  }\n}\n```\n\n### Claude Code (CLI)\n\nThe official [Claude Code CLI](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) supports MCP natively.\n\n1.  **Add the server:**\n    Run the following command in your terminal:\n    ```bash\n    claude mcp add project-scope -- npx -y @adityasasidhar/project-scope-mcp\n    ```\n\n2.  **Verify:**\n    Run `claude` and type `/mcp` to see the connected servers.\n\n### Codex CLI\n\n[Codex CLI](https://github.com/openai/codex-cli) (if applicable) supports MCP via its TOML configuration.\n\n1.  **Edit Configuration:**\n    Open `~/.codex/config.toml`.\n\n2.  **Add Server:**\n    ```toml\n    [mcp.servers.project-scope]\n    command = \"npx\"\n    args = [\"-y\", \"@adityasasidhar/project-scope-mcp\"]\n    ```\n\n### Gemini CLI\n\n[Gemini CLI](https://github.com/google/gemini-cli) supports MCP via its JSON configuration.\n\n1.  **Edit Configuration:**\n    Open `~/.gemini/settings.json` (create if it doesn't exist).\n\n2.  **Add Server:**\n    ```json\n    {\n      \"mcpServers\": {\n        \"project-scope\": {\n          \"command\": \"npx\",\n          \"args\": [\"-y\", \"@adityasasidhar/project-scope-mcp\"]\n        }\n      }\n    }\n    ```\n\n### Generic Clients\n\nFor any other client that supports MCP (like **Windsurf**, **Smithery**, **Goose**, or custom implementations), use the standard stdio configuration:\n\n```bash\nnpx -y @adityasasidhar/project-scope-mcp\n```\n\n### Cursor\n\n1. Open **Cursor Settings** (Cmd/Ctrl + Shift + J).\n2. Navigate to **Features** > **MCP Servers**.\n3. Click **+ Add New MCP Server**.\n4. Configure:\n   - **Name**: `project-scope`\n   - **Type**: `command`\n   - **Command**: `node /absolute/path/to/ProjectScopeMCP/dist/index.js`\n   *(Or use `npm run start` if preferred)*\n\n\n### GitHub Copilot (VS Code)\n\n1.  Open **GitHub Copilot Chat** in VS Code.\n2.  Click the **Attach Context** (paperclip) or **Tools** icons.\n3.  Select **Connect to MCP Server...**\n4.  Choose **Command** (or similar) and enter:\n    - **Command**: `npx`\n    - **Args**: `-y @adityasasidhar/project-scope-mcp`\n\n*Note: Requires GitHub Copilot Agent Mode enabled in VS Code settings.*\n---\n\n##  Tool Reference\n\n### Repository Analysis\n\n#### `get_repo_structure`\nGenerates a hierarchical map of the repository, respecting `.gitignore`.\n- **input**: `{ \"path\": \"/path/to/repo\", \"format\": \"tree\" }`\n\n#### `analyze_impact`\nPredicts the \"blast radius\" of changing a symbol (function, variable) by finding all references via AST.\n- **input**: `{ \"path\": \"...\", \"filePath\": \"src/utils.ts\", \"symbolName\": \"processData\", \"line\": 42 }`\n\n### Security Scanning\n\n#### `scan_repo_for_threats`\nAudits the entire repository for security risks (secrets, injection patterns). Skips ignored files for performance.\n- **input**: `{ \"path\": \"/path/to/repo\", \"excludePatterns\": [\"dist\"] }`\n\n#### `scan_file_for_threats`\nDeep-scans a single file or string with the context-aware engine.\n- **input**: `{ \"filePath\": \"/path/to/file.ts\", \"mode\": \"strict\" }`\n\n#### `validate_shell_input`\nValidates shell commands for injection risks before execution.\n- **input**: `{ \"input\": \"rm -rf /\", \"mode\": \"strict\" }`\n\n### Refactoring\n\n#### `refactor_rename`\nSemantically renames a symbol across the project.\n- **input**: `{ \"path\": \"...\", \"filePath\": \"...\", \"oldName\": \"foo\", \"newName\": \"bar\", \"apply\": false }`\n- **Note**: Always use `\"apply\": false` first to preview changes.\n\n#### `refactor_extract_function`\nExtracts selected lines of code into a new function.\n- **input**: `{ \"path\": \"...\", \"filePath\": \"...\", \"startLine\": 10, \"endLine\": 20, \"functionName\": \"newFunc\" }`\n\n### Git Operations\n\nIncludes standard Git tools for agentic workflows:\n- `git_status`\n- `git_commit_history`\n- `git_compare_branches`\n- `git_init`\n\n---\n\n## Troubleshooting\n\n**\"Repo Scan Too Slow\"**\n- Add large directories (e.g., `vendor`, `node_modules`) to `excludePatterns`. \n- Large files (>1MB) are automatically skipped.\n\n**\"Refactoring Failed to Parse\"**\n- Ensure the code is syntactically valid before refactoring. Tree-sitter parsers typically require valid syntax to generate accurate ASTs.\n\n---\n\n## License\n\nThis project is licensed under the **ISC License**.\n","readmeFilename":"README.md","_rev":"1-80de94b4fa21ddbc984cbfac5f1fd11d"}