{
  "markdown": "# StackHawk MCP Server\n\n**Current Version: 1.2.5**\n_Requires Python 3.10 or higher_\n\nA Model Context Protocol (MCP) server for integrating with StackHawk's security scanning platform. Helps developers set up StackHawk, run security scans, and triage findings to fix vulnerabilities — all from within an LLM-powered IDE or chat.\n\n---\n\n## Table of Contents\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Available Tools](#available-tools)\n- [Testing & Development](#testing--development)\n- [Example Configurations](#example-configurations)\n- [Integrating with LLMs and IDEs](#integrating-with-llms-and-ides)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Features\n- **Setup:** Detect your project, create a StackHawk application, and generate a ready-to-scan `stackhawk.yml`\n- **Scan:** Run StackHawk scans directly from your IDE or chat (with install help if the CLI is missing)\n- **Triage:** Get actionable findings at or above your failure threshold for remediation\n- **Validate:** Check YAML configs against the official schema and validate field paths to prevent hallucination\n- **Custom User-Agent:** All API calls include a versioned `User-Agent` header\n\n---\n\n## Installation\n\n1. **Install via pip (make sure you have write permission to your current python environment):**\n   ```bash\n   > pip install stackhawk-mcp\n   # Requires Python 3.10 or higher\n   ```\n**Or Install via pip in a virtual env:**\n   ```bash\n   > python3 -m venv ~/.virtualenvs/mcp\n   > source ~/.virtualenvs/mcp/bin/activate\n   > (mcp) pip install stackhawk-mcp\n   # Requires Python 3.10 or higher\n   ```\n**Or Install via pip using pyenv:**\n   ```bash\n   > pyenv shell 3.10.11\n   > pip install stackhawk-mcp\n   # Requires Python 3.10 or higher\n   ```   \n**Or Install locally from this repo:**\n   ```bash\n   > pip install --user .\n   # Run this command from the root of the cloned repository\n   ```\n2. **Set your StackHawk API key:**\n   ```bash\n   > export STACKHAWK_API_KEY=\"your-api-key-here\"\n   ```\n\n---\n\n## Usage\n\n### Running the MCP Server\n```bash\npython -m stackhawk_mcp.server\n```\n\n### Running the HTTP Server (FastAPI)\n```bash\npython -m stackhawk_mcp.http_server\n```\n\n### Running Tests\n```bash\npytest\n```\n\n### Integrating with LLMs and IDEs\n\nStackHawk MCP can be used as a tool provider for AI coding assistants and LLM-powered developer environments, enabling security scanning setup, YAML validation, and vulnerability triage directly in your workflow.\n\n#### Cursor (AI Coding Editor)\n- **Setup:**\n  - Follow the installation instructions above to install `stackhawk-mcp` in your python environment.\n  - In Cursor, go to `Cursor Settings->Tools & Integrations->MCP Tools`\n  - Add a \"New MCP Server\" with the following json, depending on your setup:\n    - Using a virtual env at `~/.virtualenvs/mcp`:\n      ```json\n      {\n        \"mcpServers\": {\n          \"stackhawk\": {\n            \"command\": \"/home/bobby/.virtualenvs/mcp/bin/python\",\n            \"args\": [\"-m\", \"stackhawk_mcp.server\"],\n            \"env\": {\n              \"STACKHAWK_API_KEY\": \"${env:STACKHAWK_API_KEY}\"\n            },\n            \"disabled\": false\n          }\n        }\n      }\n      ```\n    - Using pyenv:\n      ```json\n      {\n        \"mcpServers\": {\n          \"stackhawk\": {\n            \"command\": \"/home/bobby/.pyenv/versions/3.10.11/bin/python3\",\n            \"args\": [\"-m\", \"stackhawk_mcp.server\"],\n            \"env\": {\n              \"STACKHAWK_API_KEY\": \"${env:STACKHAWK_API_KEY}\"\n            },\n            \"disabled\": false\n          }\n        }\n      }\n      ```\n    - Or use python directly:\n      ```json\n      {\n        \"mcpServers\": {\n          \"stackhawk\": {\n            \"command\": \"python3\",\n            \"args\": [\"-m\", \"stackhawk_mcp.server\"],\n            \"env\": {\n              \"STACKHAWK_API_KEY\": \"${env:STACKHAWK_API_KEY}\"\n            }\n          }\n        }\n      }\n      ```\n    - Then make sure the \"stackhawk\" MCP Tool is enabled\n- **Usage:**\n  - Use Cursor's tool invocation to call StackHawk MCP tools (e.g., vulnerability search, YAML validation).\n  - Example prompt: `Validate this StackHawk YAML config for errors.`\n\n#### OpenAI, Anthropic, and Other LLMs\n- **Setup:**\n  - Deploy the MCP HTTP server and expose it to your LLM system (local or cloud).\n  - Use the LLM's tool-calling or function-calling API to connect to the MCP endpoint.\n  - Pass the required arguments (e.g., org_id, yaml_content) as specified in the tool schemas.\n- **Example API Call:**\n  ```json\n  {\n    \"method\": \"tools/call\",\n    \"params\": {\n      \"name\": \"validate_stackhawk_config\",\n      \"arguments\": {\"yaml_content\": \"...\"}\n    }\n  }\n  ```\n- **Best Practices:**\n  - Use anti-hallucination tools to validate field names and schema compliance.\n  - Always check the tool's output for warnings or suggestions.\n\n#### IDEs like Windsurf\n- **Setup:**\n  - Add StackHawk MCP as a tool provider or extension in your IDE, pointing to the local or remote MCP server endpoint.\n  - Configure environment variables as needed.\n- **Usage:**\n  - Invoke setup, scanning, validation, and triage tools directly from the IDE's command palette or tool integration panel.\n\n#### General Tips\n- Ensure the MCP server is running and accessible from your LLM or IDE environment.\n- Review the [Available Tools & API](#available-tools--api) section for supported operations.\n- For advanced integration, see the example tool usage in this README or explore the codebase for custom workflows.\n\n### GitHub Copilot Agents\n\nStackHawk can be added to the GitHub Coding Agent as an MCP server or as its own GitHub Custom Agent.\n\n#### Add to GitHub Coding Agent\n\nYou can add StackHawk MCP to the GitHub Copilot Coding Agent. This gives the agent all the `stackhawk/` tools.\n\n**StackHawk MCP installation into the Coding Agent**\n\n[General instructions on GitHub](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp#adding-an-mcp-configuration-to-your-repository)\n\nFor StackHawk MCP, the MCP Configuration JSON should look something like this:\n\n```yaml\n{\n  \"mcpServers\": {\n    \"stackhawk\": {\n      \"type\": \"local\",\n      \"tools\": [\n        \"*\"\n      ],\n      \"command\": \"uvx\",\n      \"args\": [\n        \"stackhawk-mcp\"\n      ],\n      \"env\": {\n        \"STACKHAWK_API_KEY\": \"COPILOT_MCP_STACKHAWK_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nThen in the Repository's `Settings->Environments->copilot->Environment Secrets`, add `COPILOT_MCP_STACKHAWK_API_KEY` with your StackHawk API Key.\n\n[Installation verification instructions](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp#validating-your-mcp-configuration)\n\n#### StackHawk Onboarding Agent as a GitHub Copilot Custom Agent\n\nYou can the StackHawk Onboarding Agent as a custom agent at the enterprise, organization, or repository level in GitHub.  When added, the StackHawk Onboarding Agent becomes a selectable option in the Copilot Agent Chat with context to help with onboarding, plus it installs `stackhawk-mcp` so the agent has access to all of those tools.\n\n**StackHawk Onboarding Agent installation**\n\nThe general approach is to take the [StackHawk Onboarding Agent defintion](https://github.com/github/awesome-copilot/blob/main/agents/stackhawk-security-onboarding.agent.md) and apply it to either the desired repository, enterprise, or organization in GitHub.\n\n- [Instructions for installing into a repository on GitHub](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents#creating-a-custom-agent-profile-for-a-repository)\n- [Instructions for installing into an enterprise on GitHub](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents)\n- [Instructions for installing into an organization GitHub](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents)\n\nNote that the `mcp-servers` block in the StackHawk Onboarding Agent definition references an environment variable called `COPILOT_MCP_STACKHAWK_API_KEY`. Go to the Repository's `Settings->Environments->copilot->Environment Secrets`, add `COPILOT_MCP_STACKHAWK_API_KEY` with your StackHawk API Key.\n\n---\n\n## Configuration\n\n- All HTTP requests include a custom `User-Agent` header:\n  ```\n  User-Agent: StackHawk-MCP/{version}\n  ```\n- The version is set in `stackhawk_mcp/server.py` as `STACKHAWK_MCP_VERSION`.\n- Set your API key via the `STACKHAWK_API_KEY` environment variable.\n\n---\n\n## Available Tools\n\nThe MCP server exposes 7 tools organized around the developer workflow:\n\n| Phase | Tool | Description |\n|-------|------|-------------|\n| **Discover** | `get_organization_info` | Get org details, teams, and applications |\n| **Discover** | `list_applications` | List applications in an organization |\n| **Setup** | `setup_stackhawk_for_project` | Detect language, find/create app, generate `stackhawk.yml` |\n| **Validate** | `validate_stackhawk_config` | Validate YAML against the official StackHawk schema |\n| **Validate** | `validate_field_exists` | Check if a field path is valid in the schema (anti-hallucination) |\n| **Scan** | `run_stackhawk_scan` | Run a StackHawk scan via the CLI (returns install help if CLI is missing) |\n| **Triage** | `get_app_findings_for_triage` | Get findings at/above the configured failure threshold |\n\n### Example Tool Usage\n```python\n# Set up StackHawk for a project\nresult = await server.call_tool(\"setup_stackhawk_for_project\", {\"host\": \"http://localhost:3000\"})\n\n# Validate a YAML config\nresult = await server.call_tool(\"validate_stackhawk_config\", {\"yaml_content\": \"...\"})\n\n# Run a scan\nresult = await server.call_tool(\"run_stackhawk_scan\", {})\n\n# Get findings to triage\nresult = await server.call_tool(\"get_app_findings_for_triage\", {})\n```\n\n**Official Schema URL:** [https://download.stackhawk.com/hawk/jsonschema/hawkconfig.json](https://download.stackhawk.com/hawk/jsonschema/hawkconfig.json)\n\n---\n\n## Testing & Development\n\n### Running All Tests\n```bash\npytest\n```\n\n### Running Individual Tests\n```bash\npytest tests/test_ux_improvements.py\npytest tests/test_user_scenarios.py\n```\n\n### Code Formatting\n```bash\nblack stackhawk_mcp/\n```\n\n### Type Checking\n```bash\nmypy stackhawk_mcp/\n```\n\n---\n\n## Example Configurations\n\n### Basic Configuration\n```yaml\napp:\n  applicationId: \"12345678-1234-1234-1234-123456789012\"\n  env: \"dev\"\n  host: \"http://localhost:3000\"\n  name: \"Development App\"\n  description: \"Local development environment\"\n```\n\n### Production Configuration with Authentication\n```yaml\napp:\n  applicationId: \"87654321-4321-4321-4321-210987654321\"\n  env: \"prod\"\n  host: \"https://myapp.com\"\n  name: \"Production App\"\n  description: \"Production environment\"\n  authentication:\n    type: \"form\"\n    username: \"your-username\"\n    password: \"your-password\"\n    loginUrl: \"https://myapp.com/login\"\n    usernameField: \"username\"\n    passwordField: \"password\"\n\nhawk:\n  spider:\n    base: true\n    ajax: false\n    maxDurationMinutes: 30\n  scan:\n    maxDurationMinutes: 60\n    threads: 10\n  startupTimeoutMinutes: 5\n  failureThreshold: \"high\"\n\ntags:\n  - name: \"environment\"\n    value: \"production\"\n  - name: \"application\"\n    value: \"myapp\"\n```\n\n---\n\n## Contributing\n\nContributions are welcome! Please open issues or pull requests for bug fixes, new features, or documentation improvements.\n\n---\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE) for details.\n\n## Release and Version Bumping\n\nVersion bumps are managed via the \"Prepare Release\" GitHub Actions workflow.\nWhen triggering this workflow, you can select whether to bump the minor or major version.\nThe workflow will automatically update version files, commit, and push the changes to main.\n\n> **Note:** The workflow is protected against infinite loops caused by automated version bump commits.\n\n## GitHub Actions Authentication\n\nAll CI/CD git operations use a GitHub App token for authentication.\nThe git user and email are set from the repository secrets `HAWKY_APP_USER` and `HAWKY_APP_USER_EMAIL`.\n\n## Workflow Protections\n\nWorkflows are designed to skip jobs if the latest commit is an automated version bump, preventing workflow loops.\n\n## How to Trigger a Release\n\n1. Go to the \"Actions\" tab on GitHub.\n2. Select the \"Prepare Release\" workflow.\n3. Click \"Run workflow\" and choose the desired bump type (minor or major).\n4. The workflow will handle the rest!\n\n<!-- mcp-name: com.stackhawk/stackhawk -->\n",
  "bytes": 12565,
  "sha": "b7d4ac3991a9d0674df5ab3021c5b86692a6e8a0b5a0c683ee2ba2df578e0f71",
  "repo_slug": "stackhawk/stackhawk-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_stackhawk_stackhawk_ae9be735/readme"
}