---
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.