@sparrowai/sparrow-mcp 1.0.3

package/LICENSE

@@ -0,0 +1,189 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2025 All Rights Reserved
+
+NOTICE: This software and associated documentation files (the "Software") are 
+the proprietary and confidential property of the copyright holder. Unauthorized 
+copying, modification, distribution, or use of this Software, via any medium, 
+is strictly prohibited and may result in severe civil and criminal penalties.
+
+TERMS AND CONDITIONS:
+
+1. OWNERSHIP
+   The Software is protected by copyright laws and international copyright 
+   treaties, as well as other intellectual property laws and treaties. All 
+   rights, title, and interest in and to the Software remain with the copyright 
+   holder.
+
+2. RESTRICTIONS ON USE
+   You are granted a limited, non-exclusive, non-transferable license to use 
+   the Software solely for the purposes authorized by the copyright holder. 
+   You may NOT:
+   
+   a) Copy, reproduce, or duplicate the Software in any form;
+   b) Modify, adapt, alter, translate, or create derivative works based upon 
+      the Software;
+   c) Reverse engineer, decompile, disassemble, or otherwise attempt to derive 
+      the source code of the Software;
+   d) Remove, alter, or obscure any proprietary notices, labels, or marks on 
+      the Software;
+   e) Distribute, sublicense, lease, rent, loan, or otherwise transfer the 
+      Software to any third party;
+   f) Use the Software for any purpose other than that for which it was 
+      expressly provided;
+   g) Share, publish, or make available the Software or any portion thereof 
+      through any means, including but not limited to file sharing, cloud 
+      storage, or public repositories.
+
+3. NO REDISTRIBUTION
+   Redistribution of this Software, in whole or in part, in any form or by any 
+   means, is STRICTLY PROHIBITED. This includes, but is not limited to:
+   - Distribution via software repositories
+   - Distribution via package managers
+   - Distribution via file sharing services
+   - Distribution via cloud storage services
+   - Distribution via any public or private network
+   - Distribution as part of another software product
+   - Distribution in modified or unmodified form
+
+4. NO MODIFICATION
+   Modification, alteration, or tampering with this Software, in whole or in 
+   part, is STRICTLY PROHIBITED. This includes, but is not limited to:
+   - Changing any code, configuration, or documentation
+   - Removing or altering copyright notices
+   - Adding or removing features
+   - Creating derivative works
+   - Obfuscating or attempting to hide modifications
+
+5. CONFIDENTIALITY
+   The Software contains proprietary and confidential information. You agree to 
+   maintain the confidentiality of the Software and not to disclose it to any 
+   third party without the express written consent of the copyright holder.
+
+6. TERMINATION
+   This license is effective until terminated. Your rights under this license 
+   will terminate automatically without notice if you fail to comply with any 
+   of its terms. Upon termination, you must immediately destroy all copies of 
+   the Software in your possession.
+
+7. NO WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
+   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 
+   IN THE SOFTWARE.
+
+8. ENFORCEMENT
+   Any violation of these terms may result in legal action. The copyright 
+   holder reserves the right to pursue all available legal remedies, including 
+   but not limited to injunctive relief and monetary damages.
+
+9. GOVERNING LAW
+   This license shall be governed by and construed in accordance with the laws 
+   of the jurisdiction in which the copyright holder is located, without regard 
+   to its conflict of law provisions.
+
+10. SEVERABILITY
+    If any provision of this license is found to be unenforceable or invalid, 
+    that provision shall be limited or eliminated to the minimum extent 
+    necessary so that this license shall otherwise remain in full force and 
+    effect.
+
+BY USING THIS SOFTWARE, YOU ACKNOWLEDGE THAT YOU HAVE READ THIS LICENSE, 
+UNDERSTAND IT, AND AGREE TO BE BOUND BY ITS TERMS AND CONDITIONS. IF YOU DO 
+NOT AGREE TO THESE TERMS, DO NOT USE THE SOFTWARE AND DESTROY ALL COPIES IN 
+YOUR POSSESSION.
+
+---
+
+사유 소프트웨어 라이선스
+
+저작권 (c) 2025 모든 권리 보유
+
+주의: 본 소프트웨어 및 관련 문서 파일(이하 "소프트웨어")은 저작권 보유자의 
+독점적이고 기밀인 재산입니다. 본 소프트웨어의 무단 복사, 수정, 배포 또는 
+사용은 어떤 매체를 통해서든 엄격히 금지되며, 심각한 민사 및 형사 처벌을 
+받을 수 있습니다.
+
+이용 약관:
+
+1. 소유권
+   본 소프트웨어는 저작권법 및 국제 저작권 조약뿐만 아니라 기타 지적 재산권 
+   법률 및 조약에 의해 보호됩니다. 소프트웨어에 대한 모든 권리, 소유권 및 
+   이익은 저작권 보유자에게 있습니다.
+
+2. 사용 제한
+   귀하는 저작권 보유자가 승인한 목적으로만 소프트웨어를 사용할 수 있는 
+   제한적이고 비독점적이며 양도 불가능한 라이선스를 부여받습니다. 
+   귀하는 다음을 수행할 수 없습니다:
+   
+   a) 소프트웨어를 어떤 형태로든 복사, 재생산 또는 복제;
+   b) 소프트웨어를 기반으로 수정, 적응, 변경, 번역 또는 파생 작품 생성;
+   c) 소프트웨어의 소스 코드를 역공학, 역컴파일, 디어셈블 또는 기타 방법으로 
+      도출하려는 시도;
+   d) 소프트웨어의 모든 독점 고지, 라벨 또는 표시를 제거, 변경 또는 모호하게 
+      만드는 행위;
+   e) 소프트웨어를 제3자에게 배포, 재라이선스, 임대, 대여, 대출 또는 기타 
+      방법으로 양도;
+   f) 소프트웨어가 명시적으로 제공된 목적 이외의 목적으로 사용;
+   g) 파일 공유, 클라우드 스토리지 또는 공개 저장소를 포함하되 이에 국한되지 
+      않는 모든 수단을 통해 소프트웨어 또는 그 일부를 공유, 게시 또는 제공
+
+3. 재배포 금지
+   본 소프트웨어의 전부 또는 일부를 어떤 형태로든 어떤 수단을 통해서든 
+   재배포하는 것은 엄격히 금지됩니다. 여기에는 다음이 포함되지만 이에 
+   국한되지 않습니다:
+   - 소프트웨어 저장소를 통한 배포
+   - 패키지 관리자를 통한 배포
+   - 파일 공유 서비스를 통한 배포
+   - 클라우드 스토리지 서비스를 통한 배포
+   - 공개 또는 사설 네트워크를 통한 배포
+   - 다른 소프트웨어 제품의 일부로 배포
+   - 수정되거나 수정되지 않은 형태로 배포
+
+4. 변조 금지
+   본 소프트웨어의 전부 또는 일부를 수정, 변경 또는 변조하는 것은 엄격히 
+   금지됩니다. 여기에는 다음이 포함되지만 이에 국한되지 않습니다:
+   - 모든 코드, 구성 또는 문서 변경
+   - 저작권 고지 제거 또는 변경
+   - 기능 추가 또는 제거
+   - 파생 작품 생성
+   - 수정 사항을 난독화하거나 숨기려는 시도
+
+5. 기밀 유지
+   소프트웨어에는 독점적이고 기밀인 정보가 포함되어 있습니다. 귀하는 
+   소프트웨어의 기밀을 유지하고 저작권 보유자의 명시적 서면 동의 없이 
+   제3자에게 공개하지 않기로 동의합니다.
+
+6. 종료
+   본 라이선스는 종료될 때까지 유효합니다. 귀하가 본 약관의 조항을 준수하지 
+   않으면 통지 없이 자동으로 종료됩니다. 종료 시 귀하는 즉시 보유하고 있는 
+   소프트웨어의 모든 사본을 파기해야 합니다.
+
+7. 보증 없음
+   소프트웨어는 "있는 그대로" 제공되며, 상품성, 특정 목적에의 적합성 및 
+   비침해에 대한 보증을 포함하되 이에 국한되지 않는 모든 명시적 또는 묵시적 
+   보증 없이 제공됩니다. 저자 또는 저작권 보유자는 계약, 불법 행위 또는 
+   기타 행위에 따른 소프트웨어 또는 사용 또는 기타 거래와 관련하여 발생하는 
+   모든 청구, 손해 또는 기타 책임에 대해 책임을 지지 않습니다.
+
+8. 집행
+   본 약관의 위반은 법적 조치를 초래할 수 있습니다. 저작권 보유자는 금지 
+   명령 및 금전적 손해를 포함하되 이에 국한되지 않는 모든 이용 가능한 법적 
+   구제책을 추구할 권리를 보유합니다.
+
+9. 준거법
+   본 라이선스는 저작권 보유자가 위치한 관할권의 법률에 따라 해석되고 
+   적용되며, 법률 충돌 조항을 고려하지 않습니다.
+
+10. 분리 가능성
+     본 라이선스의 조항이 시행 불가능하거나 무효한 것으로 판단되는 경우, 
+     해당 조항은 본 라이선스가 그 외에는 완전한 효력을 유지하도록 최소한의 
+     범위로 제한되거나 제거됩니다.
+
+본 소프트웨어를 사용함으로써 귀하는 본 라이선스를 읽고 이해하며 그 약관과 
+조건에 구속되는 것에 동의합니다. 본 약관에 동의하지 않는 경우 소프트웨어를 
+사용하지 말고 보유하고 있는 모든 사본을 파기하십시오.
+

package/README.md

@@ -0,0 +1,361 @@
+# Sparrow MCP - Security Code Analysis Server
+
+A Model Context Protocol (MCP) server that automatically analyzes security vulnerabilities in your code and generates secure code alternatives. This server integrates with Cursor IDE to provide real-time security analysis and secure code generation capabilities.
+
+## ✨ Features
+
+- **File Security Analysis**: Automatically analyze security vulnerabilities in Java code
+- **AI-Powered Briefing**: Get easy-to-understand explanations of analysis results
+- **Secure Code Generation**: Automatically generate secure code that fixes discovered vulnerabilities
+- **Diff Generation**: Visualize differences between original and secure code
+- **Real-time Status Monitoring**: Track analysis progress in real-time
+- **Multi-file Analysis**: Analyze multiple files, folders, or ZIP archives at once
+- **Progress Tracking**: Monitor analysis progress with detailed notifications
+
+## 🛠️ Technology Stack
+
+- **TypeScript**: Main development language
+- **MCP SDK**: Model Context Protocol implementation
+- **Ollama**: LLM integration (gemma2:27b model)
+- **Sparrow OnDemand API**: SAST security analysis
+- **Winston**: Logging
+
+## 📦 Installation
+
+### Prerequisites
+
+- Node.js 18+ and npm
+- Sparrow OnDemand API key
+- (Optional) Ollama for LLM features
+
+### Install from npm
+
+```bash
+npm install -g @sparrowai/sparrow-mcp
+```
+
+Or install locally in your project:
+
+```bash
+npm install @sparrowai/sparrow-mcp
+```
+
+### Verify Installation
+
+After installation, verify that the package is installed correctly by checking if the server file exists:
+
+**For local installation:**
+```bash
+# Check if the package is installed
+ls node_modules/@sparrowai/sparrow-mcp/dist/server.js
+
+# Or verify the package version
+npm list @sparrowai/sparrow-mcp
+```
+
+**For global installation:**
+```bash
+# Check if the package is installed globally
+npm list -g @sparrowai/sparrow-mcp
+
+# Find the exact global installation path
+npm root -g
+
+# Verify the server file exists (path may vary by system)
+# Windows: %APPDATA%\npm\node_modules\@sparrowai\sparrow-mcp\dist\server.js
+#   (typically: C:\Users\<username>\AppData\Roaming\npm\node_modules\@sparrowai\sparrow-mcp\dist\server.js)
+# macOS/Linux: /usr/local/lib/node_modules/@sparrowai/sparrow-mcp/dist/server.js
+#   (or ~/.npm-global/lib/node_modules/@sparrowai/sparrow-mcp/dist/server.js if using custom prefix)
+```
+
+**Note**: This package is an MCP server, not a CLI tool. It doesn't provide a direct command-line executable. The server is meant to be run by Cursor IDE through the MCP configuration (see Cursor IDE Configuration section below).
+
+## ⚙️ Configuration
+
+### Sparrow OnDemand API Setup
+
+1. Sign up for Sparrow OnDemand service
+2. Obtain your API key from the dashboard
+3. Set the `SPARROW_API_KEY` environment variable in your MCP configuration (see below)
+
+## 🔧 Cursor IDE Configuration
+
+Configure the MCP server in Cursor IDE. The server requires environment variables to be set in the MCP configuration:
+
+**Location**: `~/.cursor/mcp.json` (macOS/Linux) or `%APPDATA%\Cursor\mcp.json` (Windows)
+
+### For Local Installation
+
+If you installed the package locally in your project:
+
+```json
+{
+  "mcpServers": {
+    "sparrow-mcp": {
+      "command": "node",
+      "args": ["./node_modules/@sparrowai/sparrow-mcp/dist/server.js"],
+      "env": {
+        "SPARROW_API_KEY": "your-ondemand-token",
+        "SPARROW_API_URL": "https://ondemand.sparrowcloud.ai",
+        "OLLAMA_BASE_URL": "http://localhost:11434",
+        "OLLAMA_MODEL": "gpt-oss:20b",
+        "NODE_ENV": "development"
+      }
+    }
+  }
+}
+```
+
+### For Global Installation
+
+If you installed the package globally with `npm install -g`, use the absolute path. First, find your global installation path:
+
+```bash
+npm root -g
+```
+
+Then use the full path in your configuration:
+
+**Windows example:**
+```json
+{
+  "mcpServers": {
+    "sparrow-mcp": {
+      "command": "node",
+      "args": ["C:\\Users\\<username>\\AppData\\Roaming\\npm\\node_modules\\@sparrowai\\sparrow-mcp\\dist\\server.js"],
+      "env": {
+        "SPARROW_API_KEY": "your-ondemand-token",
+        "SPARROW_API_URL": "https://ondemand.sparrowcloud.ai",
+        "OLLAMA_BASE_URL": "http://localhost:11434",
+        "OLLAMA_MODEL": "gpt-oss:20b",
+        "NODE_ENV": "development"
+      }
+    }
+  }
+}
+```
+
+**macOS/Linux example:**
+```json
+{
+  "mcpServers": {
+    "sparrow-mcp": {
+      "command": "node",
+      "args": ["/usr/local/lib/node_modules/@sparrowai/sparrow-mcp/dist/server.js"],
+      "env": {
+        "SPARROW_API_KEY": "your-ondemand-token",
+        "SPARROW_API_URL": "https://ondemand.sparrowcloud.ai",
+        "OLLAMA_BASE_URL": "http://localhost:11434",
+        "OLLAMA_MODEL": "gpt-oss:20b",
+        "NODE_ENV": "development"
+      }
+    }
+  }
+}
+```
+
+**Note**: 
+- If you're using a local development build, replace `./node_modules/@sparrowai/sparrow-mcp/dist/server.js` with `dist/server.js` and add `"cwd"` pointing to your project root.
+- Replace `"OLLAMA_BASE_URL"` with your actual Ollama server URL (e.g., `http://192.168.30.169:11434` for remote servers).
+- Replace `"your-ondemand-token"` with your actual Sparrow OnDemand API key.
+- For global installation, replace `<username>` in the Windows path with your actual username, or use `npm root -g` to get the exact path.
+
+### Restart Cursor
+
+After updating the MCP configuration:
+
+1. Save the `mcp.json` file
+2. Restart Cursor IDE completely
+3. The MCP server should connect automatically
+
+### Verify Connection
+
+To verify that the MCP server is connected:
+
+1. Open Cursor IDE
+2. Check the MCP server status in the status bar or settings
+3. Try using one of the MCP tools (see Usage section below)
+
+## 🚀 Usage
+
+### Available MCP Tools
+
+The server provides the following MCP tools:
+
+#### 1. `analyze_file_security`
+
+Analyze a single file for security vulnerabilities.
+
+**Parameters:**
+- `fileContent` (string): The content of the file to analyze
+- `fileName` (string): The name of the file
+
+**Returns:**
+- `analysisId`: Unique identifier for the analysis
+- `status`: Current analysis status
+
+**Example Usage in Cursor:**
+```
+Analyze this file for security vulnerabilities:
+[file content]
+```
+
+#### 2. `get_analysis_status`
+
+Check the progress of an ongoing analysis.
+
+**Parameters:**
+- `analysisId` (string): The analysis ID returned from `analyze_file_security`
+
+**Returns:**
+- `status`: Current status (pending, processing, completed, failed)
+- `progress`: Progress percentage (0-100)
+- `message`: Status message
+
+#### 3. `get_analysis_results`
+
+Get detailed results from a completed analysis.
+
+**Parameters:**
+- `analysisId` (string): The analysis ID
+- `fileContent` (string): The original file content
+
+**Returns:**
+- `vulnerabilities`: List of discovered vulnerabilities
+- `analysisBrief`: AI-generated analysis briefing
+- `secureCode`: Generated secure code
+- `secureCodeBrief`: Explanation of the secure code
+- `diff`: Unified diff showing changes
+
+#### 4. `analyze_files_security`
+
+Analyze multiple files at once. Files are automatically zipped and analyzed.
+
+**Parameters:**
+- `filePaths` (array of strings): List of file paths to analyze (absolute or relative to working directory)
+- `zipFileName` (optional string): Name for the generated ZIP file
+
+**Returns:**
+- `analysisId`: Unique identifier for the analysis
+- `status`: Current analysis status
+- `filePathCount`: Number of files being analyzed
+
+#### 5. `analyze_zip_security`
+
+Analyze a ZIP file for security vulnerabilities.
+
+**Parameters:**
+- `zipFilePath` (string): Path to the ZIP file to analyze
+- `zipFileName` (optional string): Name for the ZIP file
+
+**Returns:**
+- `analysisId`: Unique identifier for the analysis
+- `status`: Current analysis status
+
+#### 6. `analyze_folder_security`
+
+Analyze an entire folder for security vulnerabilities. The folder is automatically zipped before analysis.
+
+**Parameters:**
+- `folderPath` (string): Path to the folder to analyze
+- `zipFileName` (optional string): Name for the generated ZIP file
+
+**Returns:**
+- `analysisId`: Unique identifier for the analysis
+- `status`: Current analysis status
+
+#### 7. `track_analysis_progress`
+
+Track the progress of an analysis with real-time notifications.
+
+**Parameters:**
+- `analysisId` (string): The analysis ID
+- `intervalMs` (optional number): Status check interval in milliseconds (default: 3000)
+
+**Returns:**
+- Progress notifications sent via MCP progress notifications
+- Final status when analysis completes
+
+**Analysis Stages:**
+- `INIT`: Initialization
+- `READY`: Ready to start
+- `PRE_PROCESS`: Pre-processing
+- `ANALYSIS`: Analysis in progress (progress percentage available)
+- `POST_PROCESS`: Post-processing
+- `COMPLETE`: Analysis complete
+
+### Typical Workflow
+
+1. **Write Code**: Write your Java code in Cursor
+2. **Request Analysis**: Use the `analyze_file_security` tool to request analysis
+3. **Track Progress**: Use `track_analysis_progress` to monitor the analysis
+4. **Get Results**: Use `get_analysis_results` to retrieve detailed results
+5. **Review**: Review the vulnerabilities, secure code, and diff
+6. **Apply Changes**: Apply the suggested secure code changes
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+#### 1. MCP Server Not Connecting
+
+**Symptoms**: The MCP server doesn't appear in Cursor or shows as disconnected.
+
+**Solutions**:
+- Verify the `mcp.json` file is in the correct location
+- Check that all environment variables are set correctly
+- Ensure Node.js is installed and accessible in PATH
+- Restart Cursor IDE completely
+- Check Cursor's MCP server logs for error messages
+
+#### 2. Ollama Connection Failed
+
+**Symptoms**: LLM features are not working, errors about Ollama connection.
+
+**Solutions**:
+- Verify Ollama is installed and running: `ollama serve`
+- Check that `OLLAMA_BASE_URL` is correct (default: `http://localhost:11434`)
+- Verify the model is downloaded: `ollama list`
+- Check firewall settings if using a remote Ollama instance
+
+#### 3. Sparrow API Errors
+
+**Symptoms**: Analysis requests fail with API errors.
+
+**Solutions**:
+- Verify `SPARROW_API_KEY` is correct and not expired
+- Check `SPARROW_API_URL` is correct
+- Verify your API key has sufficient permissions
+- Check network connectivity to Sparrow API
+
+#### 4. Analysis Timeout
+
+**Symptoms**: Analysis takes too long or times out.
+
+**Solutions**:
+- Large files may take longer to analyze
+- Check network connectivity
+- Verify Sparrow API service status
+- Consider analyzing smaller files or folders separately
+
+### Logging
+
+The server logs to both console and log files:
+
+- **Console**: Real-time logs during development
+- **Log Files**: 
+  - `logs/combined.log`: All logs
+  - `logs/error.log`: Error logs only
+
+To enable more detailed logging, add `"LOG_LEVEL": "debug"` to the `"env"` section in your MCP configuration.
+
+## 📝 License
+
+ISC
+
+## 🔗 Related Links
+
+- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
+- [Cursor IDE Documentation](https://cursor.sh/docs)
+- [Sparrow OnDemand API Documentation](https://ondemand.sparrowcloud.ai/docs)
+- [Ollama Documentation](https://ollama.com/docs)