Microsoft GitHub Advisory MCP Server

MCP server for querying GitHub Security Advisories from a local cloned advisory database.

Architecture

Two-Tier Design:

┌─────────────────────────────────────┐
│ MCP Server (stdio or HTTP)          │  Port: 18006 (HTTP mode)
│  - list_advisories tool             │
│  - get_advisory tool                │
└──────────┬──────────────────────────┘
           │ calls internally
┌──────────▼──────────────────────────┐
│ Local Express REST API              │  Port: 18005
│  GET /health                        │
│  GET /advisories                    │
│  GET /advisories/:ghsa_id           │
│  GET /search?q=<query>              │
└──────────┬──────────────────────────┘
           │ reads from
┌──────────▼──────────────────────────┐
│ LocalRepositoryDataSource           │
│  Reads JSON files from:             │
│  external/advisory-database/        │
└─────────────────────────────────────┘

Quick Start (VS Code + GitHub Copilot)

For users who just want to use the MCP server in VS Code:

Clone and Setup:

git clone https://github.com/microsoft/github-advisory-mcp.git
cd github-advisory-mcp
npm install
npm run build

The .vscode/mcp.json is pre-configured:

{
  "servers": {
    "advisory": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "type": "stdio",
      "env": {
        "ADVISORY_REPO_PATH": "${workspaceFolder}/external/advisory-database"
      }
    }
  }
}

Reload VS Code - Copilot will automatically:
- Clone the advisory database (~370K advisory files; ~35K github-reviewed served) on first use
- Enable MCP tools: list_advisories, get_advisory
Test in Copilot Chat:

@workspace Find high-severity npm advisories related to express

Done! The MCP server runs automatically when Copilot needs it.

Setup (Advanced)

1. Install Dependencies

npm install
npm run build

2. Database Setup (Optional - Auto-clones on first use)

# Linux/Mac (manual pre-clone)
./scripts/setup-advisory-database.sh

# Windows (manual pre-clone)
git clone --depth=1 https://github.com/github/advisory-database.git external/advisory-database

The database will auto-clone on first MCP tool call if not present.

Usage

Start Server (HTTP Streaming Mode)

Windows:

.\Start.ps1
# or with custom ports:
.\Start.ps1 -McpPort 18006 -ApiPort 18005

Manual Start:

$env:ADVISORY_REPO_PATH = "C:\path\to\advisory-database"
$env:MCP_PORT = "18006"
$env:ADVISORY_API_PORT = "18005"
node dist\http-server.js

Start Server (stdio Mode)

ADVISORY_REPO_PATH=/path/to/advisory-database node dist/index.js

Guides

Correlating advisories with code — use the advisory server together with a code-search MCP to locate and triage vulnerable code paths.

Testing

Quick Test (Copilot Chat)

After setup, test in VS Code Copilot Chat:

@workspace /tests What tools does the advisory MCP server provide?

Or query advisories directly:

@workspace Find critical npm advisories from 2024
@workspace Get details for GHSA-jc85-fpwf-qm7x

Automated Tests

npx vitest run test/unit   # fast, hermetic unit tests (this is what `npm test` runs)
npm run test:e2e           # end-to-end MCP tests (needs the advisory database)

Health Checks

# MCP Server Health
Invoke-RestMethod http://localhost:18006/health

# Local API Health
Invoke-RestMethod http://localhost:18005/health

Test the REST API and MCP protocol directly

Low-level REST and raw MCP JSON-RPC request recipes (health checks, session initialize, tools/list, tools/call) live in docs/http-api.md.

Environment Variables

Variable	Default	Description
`ADVISORY_REPO_PATH`	`./external/advisory-database`	Path to cloned advisory-database repository
`MCP_PORT`	`18006`	Port for MCP HTTP server
`ADVISORY_API_PORT`	`18005`	Port for local REST API
`ADVISORY_API_HOST`	`127.0.0.1`	Host for local REST API
`ADVISORY_API_BASE`	`http://localhost:18005`	Base URL for MCP tools to call local API

MCP Tools

list_advisories

List security advisories with optional filters.

Parameters:

ghsa_id (string): GHSA identifier
cve_id (string): CVE identifier
ecosystem (enum): Package ecosystem (npm, pip, maven, etc.)
severity (enum): Severity level (low, medium, high, critical, unknown)
cwes (string): Comma-separated CWE identifiers
is_withdrawn (boolean): Filter withdrawn advisories
affects (string): Package name filter
published (string): Published date filter
updated (string): Updated date filter
per_page (number): Results per page (max 100)
direction (enum): Sort direction (asc, desc)
sort (enum): Sort field (updated, published)

Example:

{
  "ecosystem": "npm",
  "severity": "critical",
  "per_page": 10
}

get_advisory

Get detailed information about a specific advisory.

Parameters:

ghsa_id (string, required): GHSA identifier (e.g., GHSA-xxxx-xxxx-xxxx)

Example:

{
  "ghsa_id": "GHSA-jc85-fpwf-qm7x"
}

Security & Validation

Input Validation

All MCP tool parameters are validated using Zod schemas:

list_advisories validation:

ecosystem: Enum of valid ecosystems (npm, pip, maven, etc.) - prevents injection
severity: Enum (low, medium, high, critical, unknown) - prevents injection
per_page: Number constrained to 1-100 max - prevents resource exhaustion
cwes: String pattern matching for CWE identifiers - validates format
Date filters: ISO 8601 format validation

get_advisory validation:

ghsa_id: Pattern match GHSA-xxxx-xxxx-xxxx - prevents path traversal
Required field enforcement - rejects empty/null values

File System Protection:

Path validation: Script execution paths validated against known safe scripts
No user-supplied paths accepted - prevents directory traversal
Read-only database access - no write operations exposed

Rate Limiting

Current: No rate limiting (stdio transport = single local user)

Considerations:

stdio mode: Single-process, single-user - no rate limiting needed
HTTP mode: Consider adding rate limiting if exposed beyond localhost
Database queries: Inherently rate-limited by disk I/O (hundreds of thousands of files)

Future (HTTP mode): add rate limiting if you expose the server beyond localhost — see docs/integration.md.

Session Security

Timeout: 30-minute automatic session cleanup
Isolation: Each MCP session isolated (no shared state)
Transport: stdio (local) or HTTP (localhost-only by default)

Known Security Measures

✅ Path validation for script execution (prevents command injection)
✅ Zod schema validation (prevents type confusion attacks)
✅ Session timeout (prevents resource leaks)
✅ Read-only database access (no write exposure)
✅ Enum validation for critical parameters (prevents injection)
⚠️ No rate limiting (stdio mode = trusted local user)
⚠️ No authentication (stdio mode = local process trust model)

Integration with Orchestrator

The stdio MCP server can be driven from any MCP client. A Python client example and an HTTP rate-limiting snippet are in docs/integration.md.

Port Allocation

18005: Local REST API (Express server)
18006: MCP HTTP streaming endpoint

Troubleshooting

Database Clone Failures

Issue: git clone fails for advisory-database

fatal: unable to access 'https://github.com/github/advisory-database.git/': Could not resolve host

Solutions:

Check network connectivity: ping github.com
Use VPN if behind corporate firewall
Pre-download database: git clone --depth=1 https://github.com/github/advisory-database.git external/advisory-database
Point to existing database: export ADVISORY_REPO_PATH=/path/to/existing/advisory-database

Timing: Initial clone takes 2-5 minutes (hundreds of thousands of files)

Server Won't Start

Issue: Error: EADDRINUSE: address already in use

Solution:

# Check what's using the port
lsof -i :18005  # Local API
lsof -i :18006  # MCP server

# Kill process
kill -9 <PID>

Windows-Specific Issues

Issue: Bash script fails on Windows

./scripts/setup-advisory-database.sh
# bash: ./scripts/setup-advisory-database.sh: No such file or directory

Solution: Use Git Bash or WSL, or manual clone:

git clone --depth=1 https://github.com/github/advisory-database.git external/advisory-database

MCP Tools Not Available in Copilot

Issue: Copilot doesn't see advisory MCP tools

Solution:

Verify .vscode/mcp.json exists in workspace root
Reload VS Code: Ctrl+Shift+P → "Developer: Reload Window"
Check build: npm run build and verify dist/index.js exists
Check Copilot logs: Ctrl+Shift+P → "Developer: Open Logs Folder"

Query Performance Issues

Symptom: Slow advisory queries (>5 seconds)

Solutions:

First query always slower (loads database index into memory)
Use per_page parameter to limit results: per_page: 10
Filter by ecosystem to reduce search space: ecosystem: "npm"
Check disk I/O: the advisory database is hundreds of thousands of files

Performance Benchmarks:

First query (cold start): builds the in-memory index (slower)
Subsequent queries: fast (index cached in memory)
Database size: ~370K advisory JSON files (~35K github-reviewed served by default)

Database Update Strategy

Automated Updates: The advisory database auto-updates on server start via git pull in setup script.

Manual Update:

cd external/advisory-database
git pull origin main

Update Frequency: GitHub updates advisory-database multiple times daily

Known Issues

Windows

The bash script setup-advisory-database.sh doesn't work on Windows
Workaround: Manually clone database or use existing one via ADVISORY_REPO_PATH
Use Start.ps1 script for convenient startup

Database Size

The advisory-database is ~370K advisory JSON files (~35K github-reviewed)
Shallow clone (--depth=1) recommended
First query loads entire index into memory (lazy loading)
Subsequent queries are fast (cached)

Development

CI/CD Pipeline

GitHub Actions Workflows:

Build and Test (.github/workflows/build.yml)
- Triggers: Push to main, PRs to main
- Matrix: Node.js 20.x, 22.x on Ubuntu latest
- Steps: Checkout → Setup Node → npm ci → build → verify artifacts → unit tests with coverage. End-to-end tests run on the main branch.
Copilot PR Review (.github/workflows/copilot-review.yml)
- Triggers: PR opened or synchronized
- Action: Automatically requests Copilot code review
- Permissions: pull-requests: write, contents: read

Watch Mode:

npm run dev

Clean Build:

npm run clean
npm run build

File Structure:

services/mcp/advisory/
├── src/
│   ├── index.ts              # stdio entry point
│   ├── http-server.ts        # HTTP streaming server
│   ├── server.ts             # MCP server factory
│   ├── local-server.ts       # Express REST API
│   ├── datasources/
│   │   └── local-repository.ts  # LocalRepositoryDataSource
│   ├── tools/
│   │   └── advisories.ts     # MCP tools (list/get)
│   └── types/
│       └── data-source.ts    # TypeScript interfaces
├── dist/                     # Compiled JavaScript
├── external/
│   └── advisory-database/    # Git submodule (cloned)
├── scripts/
│   └── setup-advisory-database.sh
├── package.json
├── tsconfig.json
├── Start.ps1                 # Windows startup script
└── README.md

Testing Status

✅ Working:

TypeScript compilation
HTTP server startup (port 18006)
Local REST API (port 18005)
Health endpoints
Advisory listing with filters
Getting specific advisory by GHSA ID
Ecosystem filtering (npm, pip, etc.)
Pagination

⏳ Not Yet Tested:

MCP tool calls (list_advisories, get_advisory)
Session management
stdio mode
Multiple concurrent sessions
Search functionality

Contributing

This project does not accept external contributions (pull requests) at this time. Only verified committers from the Microsoft GitHub organization may contribute code.

If you would like to get involved:

Report bugs or request features by opening an issue
Reach out to the maintainers at opencode@microsoft.com

See CONTRIBUTING.md for details.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
docs		docs
scripts		scripts
src		src
test		test
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
Start.ps1		Start.ps1
package-lock.json		package-lock.json
package.json		package.json
start.sh		start.sh
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Microsoft GitHub Advisory MCP Server

Architecture

Quick Start (VS Code + GitHub Copilot)

Setup (Advanced)

1. Install Dependencies

2. Database Setup (Optional - Auto-clones on first use)

Usage

Start Server (HTTP Streaming Mode)

Start Server (stdio Mode)

Guides

Testing

Quick Test (Copilot Chat)

Automated Tests

Health Checks

Test the REST API and MCP protocol directly

Environment Variables

MCP Tools

list_advisories

get_advisory

Security & Validation

Input Validation

Rate Limiting

Session Security

Known Security Measures

Integration with Orchestrator

Port Allocation

Troubleshooting

Database Clone Failures

Server Won't Start

Windows-Specific Issues

MCP Tools Not Available in Copilot

Query Performance Issues

Database Update Strategy

Known Issues

Windows

Database Size

Development

CI/CD Pipeline

Testing Status

Contributing

Trademarks

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages