File size: 4,125 Bytes
786acc3 f8bff51 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 |
---
title: Vulnerability Scanner MCP Server
emoji: 🦀
colorFrom: pink
colorTo: yellow
sdk: gradio
sdk_version: 5.49.0
app_file: app.py
pinned: false
---
Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
# Vulnerability Scanner MCP Server
This repository contains a small Gradio-based MCP server that provides three tools to inspect GitHub repositories using the GitHub REST API:
- Get basic repository information
- Retrieve the decoded content of a single file
- Scan a repository for source code files with specific extensions (returns a list of file paths)
The application is implemented in `app.py` and exposes a Gradio TabbedInterface with three API endpoints: `get_repository_info`, `get_file_content`, and `scan_repository`.
## Requirements
The project uses Python and the dependencies listed in `requirements.txt`. Key requirements used by the app are:
- gradio (with mcp support)
- requests
- python-dotenv
On Windows with PowerShell, create a virtual environment and install requirements:
```powershell
python -m venv .venv; .\.venv\Scripts\Activate.ps1; pip install -r requirements.txt
```
If you prefer cmd.exe use:
```cmd
python -m venv .venv && .\.venv\Scripts\activate.bat && pip install -r requirements.txt
```
## Environment variables
The application requires a GitHub personal access token to access the GitHub API. Create a `.env` file in the project root with the following variable:
```
GITHUB_TOKEN=ghp_...your_token_here
```
The token must have permission to read the repositories you want to inspect (public repos are readable with a token that has no special scopes; private repos require appropriate scopes).
## Running the server
Start the app directly with Python. The Gradio interface will launch and expose the MCP API endpoints:
```powershell
python app.py
```
When run, the app prints startup information and launches Gradio in MCP server mode. By default Gradio will open a local web UI and also expose the MCP API endpoints used by other MCP clients.
## Endpoints and usage
The Gradio interface exposes three tools (functions) via the MCP server and also as interactive UI tabs:
1) get_repository_info
Inputs:
- Repository Owner (e.g. `octocat`)
- Repository Name (e.g. `Hello-World`)
Output: A JSON-like text block containing repository metadata (name, full_name, description, primary_language, size_kb, stars, forks, default_branch, created_date, last_updated, is_private, clone_url).
2) get_file_content
Inputs:
- Repository Owner
- Repository Name
- File Path (e.g. `README.md`)
Output: Decoded file contents as plain text. If the file is binary or cannot be decoded, an error message is returned.
3) scan_repository
Inputs:
- Repository Owner
- Repository Name
- File Extensions (comma-separated, default: `.py,.js,.ts,.php,.java`)
Output: A list of file paths (limited to the first 50 matching files) found in the repository with the given extensions.
Notes and edge-cases:
- The code uses the GitHub REST API and will return HTTP error messages when repositories or files are not found or when the token lacks permissions.
- `get_file_content` decodes base64 file content returned by the GitHub API and will return an error string for binary files.
- `scan_repository` recursively traverses directories and limits results to avoid returning extremely large listings.
## Example
After starting the server, open the Gradio UI. From the UI you can call the three tools. Example programmatic calls are possible via the Gradio API endpoints; however this README focuses on interactive use through the launched UI (the functions are registered with `api_name` values matching their function names).
## Development notes
- The GitHub token is mandatory; the application raises ValueError if `GITHUB_TOKEN` is not present in the environment.
- The app limits recursion results to avoid deep scans; adjust `_scan_directory_sync` if you need more files or different limits.
## License
This project does not include a license file in the repository. Add a LICENSE if you plan to publish or share this code.
|