Content
# Tool List
### Team Lead: Yunjai Lee / Team Members: Taewoo Kim, Jihun Yoon, Minjun Choi
**Vulnerability Analyzer MCP** — A [Model Context Protocol](https://modelcontextprotocol.io/) server that receives API endpoint information, performs vulnerability checks from the perspective of OWASP Top 10, and returns a result report.
Repository: [github.com/KTTechUp-Team304/VA_MCP](https://github.com/KTTechUp-Team304/VA_MCP)
Connect and use with agents that support MCP, such as Cursor·Claude Desktop.
## Provided Functions
| MCP Tool | Description |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `analyze_endpoint` | Endpoint profile analysis → scenario planning → automatic execution of OWASP checks → result summary |
| `list_supported_checks` | List of supported checks |
| `ping` | Server connection confirmation |
| _(individual check tools)_ | `sql_injection`, `idor_bola`, `jwt_validation`, etc. — Can be selected by Planner or called directly |
- **Analysis report for humans**: `reports/{METHOD}_{path}_{timestamp}.md` (repository root)
- **Development and debugging output**: `outputs/runs/<run_id>/`, `outputs/logs/` (when `DUMP_ARTIFACTS=true`)
## Requirements
- **Git**
- **[uv](https://docs.astral.sh/uv/)** (Python package and execution management)
- **Python 3.11+**
- MCP client: [Cursor](https://cursor.com/) or [Claude Desktop](https://claude.ai/download)
```bash
git --version
uv --version
python3 --version
```
## Installation
```bash
git clone https://github.com/KTTechUp-Team304/VA_MCP.git
cd VA_MCP
uv sync
uv tool install .
```
- `uv tool install .` → Register `va-mcp` CLI in `~/.local/bin` (check with `which va-mcp`)
- If `~/.local/bin` is not in PATH, add it to shell configuration and **restart MCP client**.
## MCP Client Integration
### Cursor
This repository includes `.cursor/mcp.json`.
1. Open **VA-MCP folder** in Cursor.
2. Confirm that `va-mcp` server is enabled in **Settings → MCP**.
To use with other projects (e.g., `broken_regist_frontend`), add the same configuration to global `~/.cursor/mcp.json` or add VA-MCP folder to workspace.
```json
{
"mcpServers": {
"va-mcp": {
"command": "va-mcp"
}
}
}
```
### Claude Desktop
For macOS, configuration file: `~/Library/Application Support/Claude/claude_desktop_config.json`
Add `mcpServers` block similarly and **completely restart** Claude Desktop.
## Usage
### 1) Connection Confirmation
Call MCP tool `ping` in agent chat to confirm response.
### 2) Endpoint Check (`analyze_endpoint`)
Provide API method, path, base URL, and (optional) authentication and request/response examples. When agent calls `analyze_endpoint` tool, it internally performs profile parsing, function extraction, scenario planning, and check execution.
Detailed input schema: [docs/endpointProfile.md](docs/endpointProfile.md)
**Example (concept)**
```json
{
"base_url": "http://localhost:4000",
"method": "GET",
"path": "/api/enrollments/me",
"auth_required": true,
"headers": { "Authorization": "Bearer <access_token>" }
}
```
- `status: "analyzed"` — Check completed
- `status: "need_more_context"` — Call again with completed `missing` fields
### 3) Result Confirmation
Results are provided in **two ways**.
#### A. MCP Response (Agent → Chat Window)
Cursor agent reads JSON returned by `analyze_endpoint` and summarizes it in chat. Works without opening files.
| Field | Description |
| ----------------- | ----------------------------------------------------------------------- |
| `status` | `analyzed` / `need_more_context` / `invalid_input` |
| `run_id` | Execution tracking ID (`outputs/runs/` folder name matches) |
| `tool_results` | Check results by tool (status, severity, evidence, recommendations, etc.) |
| `endpoint_report` | Aggregated JSON by OWASP scenario |
| `report_paths` | Stored report file paths (`report_md`, `report_json`, `report_basename`) |
#### B. Human Analysis Report (`reports/`)
Markdown and JSON are stored in `reports/` folder in repository **root**. Use in IDE or share with team.
| File | Description |
| ---------------------------------------------- | ----------------------------------------------- |
| `reports/{METHOD}_{path}_{timestamp}_{suffix}.md` | Readable analysis report (summary table, detailed OWASP) |
| `reports/{METHOD}_{path}_{timestamp}_{suffix}.json` | Structured JSON with same content |
Example: `reports/GET_api_admin_2026-05-20T05-42-56_9ddf04.md`
For MCP connection issues, refer to Cursor **Output → MCP Logs**, and for server internal logs, refer to `outputs/logs/va-mcp.log`.
## Update
```bash
cd VA_MCP
git pull
uv sync
uv tool install --reinstall .
```
Restart MCP client afterward.
## Environment Variables (Optional)
Can be specified in project root `.env` or MCP settings' `env` block.
| Variable | Default Value | Description |
| ---------------- | ----------------------- | -------------------------------------------- |
| `LOG_LEVEL` | `INFO` | Log verbosity (`DEBUG`, etc.) |
| `OUTPUT_DIR` | (auto) `repository/outputs` | Development and debugging output (runs, logs) |
| `REPORTS_DIR` | (auto) `repository/reports` | Human-readable vulnerability analysis reports (.md / .json) |
| `DUMP_ARTIFACTS` | `false` | Dump JSON in `outputs/runs/` when `true` |
## Troubleshooting
| Symptom | Check |
| ----------------------- | ---------------------------------------------------------- |
| MCP server not found | `which va-mcp`, `~/.local/bin` in PATH |
| Empty tool list | Restart Cursor/Claude, MCP settings JSON syntax |
| Communication error during check | Target API (e.g., `localhost:4000`) running? |
| JSON parsing failure | Do not use `print()` in server code — use stdio channel |
## Related Projects
Can be used with vulnerability learning web server for application. When cloned in same parent folder:
- `../broken_regist_backend` — NestJS API (default `http://localhost:4000`)
- `../broken_regist_frontend` — Next.js UI
## Developer Documents
Refer to internal team documents for feature development, branch strategy, and test writing rules.
- [docs/dev_docs/DEV_GUIDE.md](docs/dev_docs/DEV_GUIDE.md) — Development workflow
- [docs/dev_docs/OBSERVABILITY.md](docs/dev_docs/OBSERVABILITY.md) — Log and artifact debugging
- [docs/architecture/](docs/architecture/) — Architecture and implementation guide
## Limitations
- Current deployment form is **local stdio MCP**. Cursor/Claude executes `va-mcp` as a child process.
- Remote HTTP MCP and multi-user hosting will be reviewed in a separate deployment phase.
