README.md

metadata

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:

python -m venv .venv; .\.venv\Scripts\Activate.ps1; pip install -r requirements.txt

If you prefer cmd.exe use:

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:

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.