# Installation Guide - Clean Install and Testing
This guide provides tested, step-by-step instructions for installing the CVE MCP Server on a new computer, running it in Docker, and testing with MCP Inspector.
## Prerequisites
Before starting, ensure you have:
- Docker and Docker Compose installed
- Node.js 18+ (for MCP Inspector)
- Git
## Installation Steps
### Step 1: Clone the Repository
```bash
git clone https://github.com/yourusername/cve-mcp-server.git
cd cve-mcp-server
```
### Step 2: Build Docker Image
```bash
sudo docker build -t cve-mcp-server .
```
**Note**: If you get a "permission denied" error, you need Docker permissions. You have two options:
**Option A - Quick Fix (use sudo for all docker commands):**
```bash
# Use sudo with all docker commands
sudo docker build -t cve-mcp-server .
```
**Option B - Permanent Fix (add user to docker group):**
```bash
# Add your user to docker group
sudo usermod -aG docker $USER
# Log out and log back in, then verify
docker ps
# Now you can use docker without sudo
docker build -t cve-mcp-server .
```
This guide uses `sudo` for all docker commands. Omit `sudo` if you completed Option B.
### Step 3: Start Container
```bash
sudo docker compose up -d
```
### Step 4: Verify Container is Running
```bash
sudo docker ps
```
You should see `cve-mcp-server` in the list of running containers.
### Step 5: Load CVE Data
Load a test dataset of 100 CVEs from 2024:
```bash
sudo docker exec cve-mcp-server python -m src.data_ingestion.loader --year 2024 --limit 100
```
This takes 1-2 minutes. For the full dataset (~240K CVEs, 6-7 minutes):
```bash
sudo docker exec cve-mcp-server python -m src.data_ingestion.loader_optimized
```
### Step 6: Verify Data Loaded
```bash
sudo docker exec cve-mcp-server python -c "
from src.database.db import init_db, get_stats
conn = init_db()
stats = get_stats(conn)
print(f'Total CVEs: {stats[\"total_cves\"]}')
print(f'Date range: {stats[\"oldest_cve\"]} to {stats[\"newest_cve\"]}')
conn.close()
"
```
Expected output: `Total CVEs: 100` (or more if you loaded the full dataset)
## Testing with MCP Inspector
### Step 7: Launch MCP Inspector
```bash
npx @modelcontextprotocol/inspector
```
This will start MCP Inspector and open your browser (usually http://localhost:5173).
### Step 8: Configure Connection
In the MCP Inspector connection settings:
- **Command**: `sudo`
- **Arguments**: `docker exec -i cve-mcp-server python -m src.mcp_server`
- **Environment Variables** (click to add):
- Name: `PYTHONPATH`
- Value: `/app`
### Step 9: Connect
Click the **Connect** button.
**Troubleshooting**: If you get an error like "unknown shorthand flag", restart MCP Inspector:
1. Close the browser tab
2. Press Ctrl+C in the terminal running MCP Inspector
3. Run `npx @modelcontextprotocol/inspector` again
4. Re-enter the configuration
5. Click Connect
### Step 10: Test the Tools
Once connected, you should see three available tools. Test each one:
#### Test 1: get_statistics
- Select the `get_statistics` tool
- Input: `{}`
- Click **Execute**
- Expected: JSON response with total CVEs, date range, and last update
#### Test 2: search_cves
- Select the `search_cves` tool
- Input: `{"keyword": "remote", "limit": 5}`
- Click **Execute**
- Expected: JSON response with array of matching CVEs
#### Test 3: get_cve_details
- Select the `get_cve_details` tool
- Input: `{"cve_id": "CVE-2024-XXXX"}` (use a CVE ID from the search results)
- Click **Execute**
- Expected: JSON response with detailed CVE information
## Cleanup
When you're done testing:
```bash
sudo docker compose down
```
To remove the database and start fresh:
```bash
sudo rm -rf data/cve.db
```
## Common Issues
### Docker Permission Denied
**Error**: `permission denied while trying to connect to the Docker daemon socket`
**Solution**: Use `sudo` with docker commands, or add your user to the docker group (see Step 2, Option B).
### Container Not Running
**Error**: `Error response from daemon: Container cve-mcp-server is not running`
**Solution**: Start the container:
```bash
sudo docker compose up -d
```
### MCP Inspector Connection Failed
**Error**: `unknown shorthand flag` or connection timeout
**Solution**: Restart MCP Inspector completely:
1. Close browser tab
2. Ctrl+C in the terminal
3. Run `npx @modelcontextprotocol/inspector` again
4. Re-enter configuration with `sudo` as the Command
### No CVE Data
**Error**: `Total CVEs: 0`
**Solution**: Load the data:
```bash
sudo docker exec cve-mcp-server python -m src.data_ingestion.loader --year 2024 --limit 100
```
## Next Steps
- Load more CVE data with different years: `--year 2023 --limit 500`
- Load the full dataset: `python -m src.data_ingestion.loader_optimized`
- Explore other testing options in `TESTING.md`
- Read `README.md` for tool documentation and features
- Check `CLAUDE.md` for architecture details
## Verification Checklist
- [ ] Repository cloned successfully
- [ ] Docker image built without errors
- [ ] Container is running (`docker ps` shows it)
- [ ] CVE data loaded (at least 100 CVEs)
- [ ] MCP Inspector connects successfully
- [ ] All three tools execute and return results
If all items are checked, your installation is complete and working correctly!
