threatray-mcp 1.0.2__tar.gz

threatray_mcp-1.0.2/.gitignore

@@ -0,0 +1,81 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+tests/coverage/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+

threatray_mcp-1.0.2/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to `threatray-mcp` are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.2] — 2026-06-09
+
+### Overview
+
+`threatray-mcp` is a Model Context Protocol server for the Threatray malware
+analysis and threat intelligence platform. It runs over stdio so MCP-aware
+clients (Claude Code, Claude Desktop, Cursor, Cline, Windsurf, …) can query
+samples, run code-similarity retrohunts, fetch CAPA capabilities and AI
+analyses, aggregate IOCs, and submit files for analysis.
+
+### Tools
+
+28 tools, aligned with the public
+[Threatray API taxonomy](https://docs.threatray.com/reference/overview-api):
+
+- **Search:** `threatray_search`, `threatray_retrohunt_sample`
+- **Samples:** `threatray_get_sample`
+- **Submissions (read):** `threatray_list_submissions`, `threatray_get_task`, `threatray_get_task_by_analysis`, `threatray_list_tasks`
+- **Submissions (write):** `threatray_submit_sample`, `threatray_submit_url`, `threatray_submit_endpoint_scan_archive`, `threatray_submit_minidump`, `threatray_submit_mans_file`
+- **Analyses:** `threatray_get_analysis`, `threatray_get_osint`, `threatray_list_analyses`, `threatray_list_endpoint_scan_analyses`
+- **Files:** `threatray_get_file_metadata`, `threatray_get_strings`, `threatray_download_file`
+- **Functions:** `threatray_list_functions`, `threatray_get_code_detections`, `threatray_retrohunt_functions`, `threatray_diff_functions`
+- **CAPA:** `threatray_get_capa`
+- **AI Analysis:** `threatray_get_ai_analysis`, `threatray_get_ai_analysis_by_id`, `threatray_list_ai_analyses`, `threatray_get_latest_ai_job`
+
+All tools accept `response_format=markdown` (default) or `response_format=json`.
+
+### Configuration
+
+Settings via environment variables (prefix `THREATRAY_`):
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `THREATRAY_API_KEY` | (required) | API key for the realm |
+| `THREATRAY_API_URL` | (required) | API endpoint for the realm your key belongs to |
+| `THREATRAY_LOG_LEVEL` | `WARNING` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
+| `THREATRAY_TRANSPORT` | `stdio` | `stdio` (default) or `http` (standalone server) |
+| `THREATRAY_HOST` | `0.0.0.0` | Bind address when `THREATRAY_TRANSPORT=http` |
+| `THREATRAY_PORT` | `8000` | TCP port when `THREATRAY_TRANSPORT=http` |
+
+### Notable
+
+- **Transports:** stdio (default — JSON-RPC over stdin/stdout, stdout reserved
+  for the protocol, logs to stderr) and streamable HTTP (standalone server on
+  `THREATRAY_HOST:THREATRAY_PORT/mcp`, for containerized deployments where the
+  consuming client cannot spawn the server as a subprocess). No app-level auth
+  on HTTP — restrict ingress at the network layer.
+- **Errors:** typed exception hierarchy surfaced as MCP `tool_error` results so
+  agents see structured failures rather than success-shaped strings.
+- **AI analysis flow:** `threatray_get_ai_analysis` supports a
+  `trigger_only=True` fire-and-forget mode for slow files; the agent can poll
+  later via `threatray_get_latest_ai_job`. Sync wait is configurable
+  (`max_wait_seconds`, default 600s, upper bound 3600s).
+- **Python support:** 3.11, 3.12, 3.13.
+
+### Acknowledgments
+
+- **TiQ Labs** — contributed the streamable HTTP transport (server-side
+  config + dispatch, compose service, integration test) plus a fix for a
+  test-runner bug where Compose-passed empty env vars (`${VAR:-}`) silenced
+  `os.environ.setdefault` defaults.

threatray_mcp-1.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Threatray
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

threatray_mcp-1.0.2/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: threatray-mcp
+Version: 1.0.2
+Summary: MCP server for the Threatray malware analysis and threat intelligence platform
+Project-URL: Homepage, https://www.threatray.com
+Project-URL: Repository, https://github.com/threatray/threatray-mcp
+Project-URL: Issues, https://github.com/threatray/threatray-mcp/issues
+Project-URL: Documentation, https://github.com/threatray/threatray-mcp#readme
+Project-URL: Threatray API reference, https://docs.threatray.com/reference/overview-api
+Author-email: Threatray <operations@threatray.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: capa,ioc,malware,mcp,threat-intelligence,threatray,yara
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: <3.14,>=3.11
+Requires-Dist: fastmcp<4,>=3
+Requires-Dist: httpx~=0.27
+Requires-Dist: pydantic-settings~=2.0
+Requires-Dist: pydantic~=2.0
+Provides-Extra: dev
+Requires-Dist: coverage~=7.6; extra == 'dev'
+Requires-Dist: mypy~=1.11; extra == 'dev'
+Requires-Dist: pyhamcrest~=2.1; extra == 'dev'
+Requires-Dist: pytest~=8.0; extra == 'dev'
+Requires-Dist: requests-mock~=1.12; extra == 'dev'
+Requires-Dist: respx~=0.22; extra == 'dev'
+Requires-Dist: ruff~=0.8; extra == 'dev'
+Requires-Dist: vulture~=2.11; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# threatray-mcp
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+MCP server for the [Threatray](https://www.threatray.com) malware analysis and threat intelligence platform. Lets MCP-aware clients (Claude Code, Claude Desktop, Cursor, Cline, Windsurf, …) query samples, run code-similarity retrohunts, fetch CAPA capabilities, pull AI analyses, and aggregate IOCs through a single uniform tool surface.
+
+## Quick start
+
+Requires a Threatray API key and Python 3.11+. Install from PyPI:
+
+```bash
+uvx threatray-mcp        # run directly, no install
+# or
+pip install threatray-mcp
+```
+
+### Claude Code
+
+```bash
+claude mcp add threatray -s user \
+  -e THREATRAY_API_KEY=YOUR_API_KEY \
+  -e THREATRAY_API_URL=https://api-<your-realm>.analysis.threatray.com \
+  -- uvx threatray-mcp
+
+claude mcp list   # should show "threatray: ... connected"
+```
+
+Both env vars are required — no default URL. Replace `<your-realm>` with the realm your API key belongs to (provided by your Threatray account team).
+
+### Generic MCP client config
+
+Most MCP-aware editors accept the same JSON shape. Drop this block into the relevant config file (paths below):
+
+```json
+{
+  "mcpServers": {
+    "threatray": {
+      "command": "uvx",
+      "args": ["threatray-mcp"],
+      "env": {
+        "THREATRAY_API_KEY": "YOUR_API_KEY",
+        "THREATRAY_API_URL": "https://api-<your-realm>.analysis.threatray.com"
+      }
+    }
+  }
+}
+```
+
+A copy of this snippet is in [`examples/mcp-config.json`](examples/mcp-config.json).
+
+| Client | Config file |
+|---|---|
+| Claude Code | `~/.claude.json` (managed via `claude mcp add ...`) |
+| Claude Desktop | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`. Windows: `%APPDATA%\Claude\claude_desktop_config.json` |
+| Cursor | `~/.cursor/mcp.json` (global) or `<project>/.cursor/mcp.json` (per-project) |
+| Cline (VS Code) | Cline UI → "MCP Servers" → edit JSON, or `~/.cline/mcp_settings.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+
+After editing, restart the client.
+
+## Configuration
+
+All settings via env vars (prefix `THREATRAY_`):
+
+| Variable | Default | Description |
+|---|---|---|
+| `THREATRAY_API_KEY` | (required) | API key from your Threatray realm |
+| `THREATRAY_API_URL` | (required) | API endpoint for the realm your key belongs to (form: `https://api-<your-realm>.analysis.threatray.com`). Pick a wrong realm and you'll just get auth errors — no default. Provided by your Threatray account team. |
+| `THREATRAY_LOG_LEVEL` | `WARNING` | `DEBUG` / `INFO` / `WARNING` / `ERROR` (stderr only, never stdout — stdout carries the JSON-RPC stream) |
+| `THREATRAY_TRANSPORT` | `stdio` | `stdio` (default, server runs as subprocess of an MCP client) or `http` (standalone server, see Deployment below) |
+| `THREATRAY_HOST` | `0.0.0.0` | Bind address, used only when `THREATRAY_TRANSPORT=http` |
+| `THREATRAY_PORT` | `8000` | TCP port, used only when `THREATRAY_TRANSPORT=http` |
+
+Markdown output wraps hashes in clickable links to the Threatray UI; the UI URL is derived automatically from `THREATRAY_API_URL`.
+
+### Deployment
+
+Two transports are supported:
+- **`stdio`** (default) — the MCP client spawns `threatray-mcp` as a subprocess. This is what `uvx threatray-mcp` and `claude mcp add` give you.
+- **`http`** — long-lived standalone server on `THREATRAY_HOST:THREATRAY_PORT/mcp` (streamable HTTP). Use when the consuming client can't spawn the server (containerized clients, network-segmented deployments). Example: `docker compose --profile http up`. **No app-level auth** — restrict ingress at the network layer.
+
+## Tools
+
+Grouped by [Threatray public API taxonomy](https://docs.threatray.com/reference/overview-api). All 28 tools below; see [`src/threatray_mcp/README.md`](src/threatray_mcp/README.md) for per-tool descriptions.
+
+| Section | Tools |
+|---|---|
+| Search | `threatray_search`, `threatray_retrohunt_sample` |
+| Samples | `threatray_get_sample` |
+| Submissions (read) | `threatray_list_submissions`, `threatray_get_task`, `threatray_get_task_by_analysis`, `threatray_list_tasks` |
+| Submissions (write) | `threatray_submit_sample`, `threatray_submit_url`, `threatray_submit_endpoint_scan_archive`, `threatray_submit_minidump`, `threatray_submit_mans_file` |
+| Analyses | `threatray_get_analysis`, `threatray_get_osint`, `threatray_list_analyses`, `threatray_list_endpoint_scan_analyses` |
+| Files | `threatray_get_file_metadata`, `threatray_get_strings`, `threatray_download_file` |
+| Functions | `threatray_list_functions`, `threatray_get_code_detections`, `threatray_retrohunt_functions`, `threatray_diff_functions` |
+| CAPA Analysis | `threatray_get_capa` |
+| AI Analysis | `threatray_get_ai_analysis`, `threatray_get_ai_analysis_by_id`, `threatray_list_ai_analyses`, `threatray_get_latest_ai_job` |
+
+All tools accept `response_format=markdown` (default) or `response_format=json`.
+
+Features not enabled for your account (e.g. AI analysis on some realms) surface as a clean `ThreatrayFeatureUnavailable` tool error rather than an empty result, so the agent gets an actionable signal instead of looping.
+
+## Security
+
+The MCP server runs as a subprocess of your editor under your local user — it inherits read access to every file you can read. The `threatray_submit_*` tools accept a `file_path` argument and upload the file's contents to your configured Threatray realm. Combined with prompt injection (a sample's strings, an OSINT report, a web page rendered in the editor), an attacker could attempt to convince the agent to call e.g. `threatray_submit_sample(file_path="~/.ssh/id_rsa")`.
+
+Mitigations to consider when integrating in a shared or unattended environment:
+
+1. **Don't run the server as a user with read access to secrets** — run it under a least-privilege account or in a sandbox/container without access to your `~`/credentials/git working trees.
+2. **Watch for surprising `threatray_submit_*` tool calls** — Claude Code surfaces every tool call before sending it; pay attention to the `file_path` argument before approving.
+
+The same least-privilege account that protects the read side also bounds where `threatray_download_file` can write — the tool relies on OS file-system permissions, not an application-level directory allowlist.
+
+## Troubleshooting
+
+**MCP server not connecting** — verify with `claude mcp list` (or your client's equivalent). If not connected:
+1. Confirm Python 3.11+ is on `PATH`.
+2. Test the entrypoint directly: `THREATRAY_API_KEY=xxx uvx threatray-mcp` (it'll hang waiting for stdio input — Ctrl-C to exit; absence of an error means startup succeeded).
+3. Set `THREATRAY_LOG_LEVEL=DEBUG` and re-launch via the client; check stderr.
+
+**`ThreatrayAuthError`** — API key missing/invalid, OR your key belongs to a different realm than `THREATRAY_API_URL` points at. The error message includes the URL the server tried — confirm it matches your realm.
+
+**`ThreatrayForbiddenError`** — authenticated but the key lacks the required scope.
+
+**`ThreatrayFeatureUnavailable`** — the feature (AI analysis, function diffing, …) isn't enabled for your account. Contact your Threatray account team.
+
+**Connection errors** — `ThreatrayConnectionError` includes the URL it tried; confirm `THREATRAY_API_URL` is reachable from where the MCP server runs.
+
+## Development
+
+```bash
+git clone https://github.com/threatray/threatray-mcp
+cd threatray-mcp
+pip install -e ".[dev]"
+
+# Run all tests (unit + integration)
+make test
+make unit-tests       # respx-mocked client + formatters + models
+make int-tests        # in-process fastmcp.Client end-to-end
+
+# Lint and type check
+make lint
+make type-check
+
+# Without Docker
+python -m unittest discover tests
+```
+
+For contributor-facing architecture and the per-section package layout, see [`src/threatray_mcp/README.md`](src/threatray_mcp/README.md). Release notes live in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

threatray_mcp-1.0.2/README.md

@@ -0,0 +1,152 @@
+# threatray-mcp
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+MCP server for the [Threatray](https://www.threatray.com) malware analysis and threat intelligence platform. Lets MCP-aware clients (Claude Code, Claude Desktop, Cursor, Cline, Windsurf, …) query samples, run code-similarity retrohunts, fetch CAPA capabilities, pull AI analyses, and aggregate IOCs through a single uniform tool surface.
+
+## Quick start
+
+Requires a Threatray API key and Python 3.11+. Install from PyPI:
+
+```bash
+uvx threatray-mcp        # run directly, no install
+# or
+pip install threatray-mcp
+```
+
+### Claude Code
+
+```bash
+claude mcp add threatray -s user \
+  -e THREATRAY_API_KEY=YOUR_API_KEY \
+  -e THREATRAY_API_URL=https://api-<your-realm>.analysis.threatray.com \
+  -- uvx threatray-mcp
+
+claude mcp list   # should show "threatray: ... connected"
+```
+
+Both env vars are required — no default URL. Replace `<your-realm>` with the realm your API key belongs to (provided by your Threatray account team).
+
+### Generic MCP client config
+
+Most MCP-aware editors accept the same JSON shape. Drop this block into the relevant config file (paths below):
+
+```json
+{
+  "mcpServers": {
+    "threatray": {
+      "command": "uvx",
+      "args": ["threatray-mcp"],
+      "env": {
+        "THREATRAY_API_KEY": "YOUR_API_KEY",
+        "THREATRAY_API_URL": "https://api-<your-realm>.analysis.threatray.com"
+      }
+    }
+  }
+}
+```
+
+A copy of this snippet is in [`examples/mcp-config.json`](examples/mcp-config.json).
+
+| Client | Config file |
+|---|---|
+| Claude Code | `~/.claude.json` (managed via `claude mcp add ...`) |
+| Claude Desktop | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`. Windows: `%APPDATA%\Claude\claude_desktop_config.json` |
+| Cursor | `~/.cursor/mcp.json` (global) or `<project>/.cursor/mcp.json` (per-project) |
+| Cline (VS Code) | Cline UI → "MCP Servers" → edit JSON, or `~/.cline/mcp_settings.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+
+After editing, restart the client.
+
+## Configuration
+
+All settings via env vars (prefix `THREATRAY_`):
+
+| Variable | Default | Description |
+|---|---|---|
+| `THREATRAY_API_KEY` | (required) | API key from your Threatray realm |
+| `THREATRAY_API_URL` | (required) | API endpoint for the realm your key belongs to (form: `https://api-<your-realm>.analysis.threatray.com`). Pick a wrong realm and you'll just get auth errors — no default. Provided by your Threatray account team. |
+| `THREATRAY_LOG_LEVEL` | `WARNING` | `DEBUG` / `INFO` / `WARNING` / `ERROR` (stderr only, never stdout — stdout carries the JSON-RPC stream) |
+| `THREATRAY_TRANSPORT` | `stdio` | `stdio` (default, server runs as subprocess of an MCP client) or `http` (standalone server, see Deployment below) |
+| `THREATRAY_HOST` | `0.0.0.0` | Bind address, used only when `THREATRAY_TRANSPORT=http` |
+| `THREATRAY_PORT` | `8000` | TCP port, used only when `THREATRAY_TRANSPORT=http` |
+
+Markdown output wraps hashes in clickable links to the Threatray UI; the UI URL is derived automatically from `THREATRAY_API_URL`.
+
+### Deployment
+
+Two transports are supported:
+- **`stdio`** (default) — the MCP client spawns `threatray-mcp` as a subprocess. This is what `uvx threatray-mcp` and `claude mcp add` give you.
+- **`http`** — long-lived standalone server on `THREATRAY_HOST:THREATRAY_PORT/mcp` (streamable HTTP). Use when the consuming client can't spawn the server (containerized clients, network-segmented deployments). Example: `docker compose --profile http up`. **No app-level auth** — restrict ingress at the network layer.
+
+## Tools
+
+Grouped by [Threatray public API taxonomy](https://docs.threatray.com/reference/overview-api). All 28 tools below; see [`src/threatray_mcp/README.md`](src/threatray_mcp/README.md) for per-tool descriptions.
+
+| Section | Tools |
+|---|---|
+| Search | `threatray_search`, `threatray_retrohunt_sample` |
+| Samples | `threatray_get_sample` |
+| Submissions (read) | `threatray_list_submissions`, `threatray_get_task`, `threatray_get_task_by_analysis`, `threatray_list_tasks` |
+| Submissions (write) | `threatray_submit_sample`, `threatray_submit_url`, `threatray_submit_endpoint_scan_archive`, `threatray_submit_minidump`, `threatray_submit_mans_file` |
+| Analyses | `threatray_get_analysis`, `threatray_get_osint`, `threatray_list_analyses`, `threatray_list_endpoint_scan_analyses` |
+| Files | `threatray_get_file_metadata`, `threatray_get_strings`, `threatray_download_file` |
+| Functions | `threatray_list_functions`, `threatray_get_code_detections`, `threatray_retrohunt_functions`, `threatray_diff_functions` |
+| CAPA Analysis | `threatray_get_capa` |
+| AI Analysis | `threatray_get_ai_analysis`, `threatray_get_ai_analysis_by_id`, `threatray_list_ai_analyses`, `threatray_get_latest_ai_job` |
+
+All tools accept `response_format=markdown` (default) or `response_format=json`.
+
+Features not enabled for your account (e.g. AI analysis on some realms) surface as a clean `ThreatrayFeatureUnavailable` tool error rather than an empty result, so the agent gets an actionable signal instead of looping.
+
+## Security
+
+The MCP server runs as a subprocess of your editor under your local user — it inherits read access to every file you can read. The `threatray_submit_*` tools accept a `file_path` argument and upload the file's contents to your configured Threatray realm. Combined with prompt injection (a sample's strings, an OSINT report, a web page rendered in the editor), an attacker could attempt to convince the agent to call e.g. `threatray_submit_sample(file_path="~/.ssh/id_rsa")`.
+
+Mitigations to consider when integrating in a shared or unattended environment:
+
+1. **Don't run the server as a user with read access to secrets** — run it under a least-privilege account or in a sandbox/container without access to your `~`/credentials/git working trees.
+2. **Watch for surprising `threatray_submit_*` tool calls** — Claude Code surfaces every tool call before sending it; pay attention to the `file_path` argument before approving.
+
+The same least-privilege account that protects the read side also bounds where `threatray_download_file` can write — the tool relies on OS file-system permissions, not an application-level directory allowlist.
+
+## Troubleshooting
+
+**MCP server not connecting** — verify with `claude mcp list` (or your client's equivalent). If not connected:
+1. Confirm Python 3.11+ is on `PATH`.
+2. Test the entrypoint directly: `THREATRAY_API_KEY=xxx uvx threatray-mcp` (it'll hang waiting for stdio input — Ctrl-C to exit; absence of an error means startup succeeded).
+3. Set `THREATRAY_LOG_LEVEL=DEBUG` and re-launch via the client; check stderr.
+
+**`ThreatrayAuthError`** — API key missing/invalid, OR your key belongs to a different realm than `THREATRAY_API_URL` points at. The error message includes the URL the server tried — confirm it matches your realm.
+
+**`ThreatrayForbiddenError`** — authenticated but the key lacks the required scope.
+
+**`ThreatrayFeatureUnavailable`** — the feature (AI analysis, function diffing, …) isn't enabled for your account. Contact your Threatray account team.
+
+**Connection errors** — `ThreatrayConnectionError` includes the URL it tried; confirm `THREATRAY_API_URL` is reachable from where the MCP server runs.
+
+## Development
+
+```bash
+git clone https://github.com/threatray/threatray-mcp
+cd threatray-mcp
+pip install -e ".[dev]"
+
+# Run all tests (unit + integration)
+make test
+make unit-tests       # respx-mocked client + formatters + models
+make int-tests        # in-process fastmcp.Client end-to-end
+
+# Lint and type check
+make lint
+make type-check
+
+# Without Docker
+python -m unittest discover tests
+```
+
+For contributor-facing architecture and the per-section package layout, see [`src/threatray_mcp/README.md`](src/threatray_mcp/README.md). Release notes live in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

threatray_mcp-1.0.2/pyproject.toml

@@ -0,0 +1,100 @@
+[project]
+name = "threatray-mcp"
+version = "1.0.2"
+description = "MCP server for the Threatray malware analysis and threat intelligence platform"
+authors = [{name = "Threatray", email = "operations@threatray.com"}]
+readme = "README.md"
+requires-python = ">=3.11,<3.14"
+license = "MIT"
+keywords = ["mcp", "threatray", "malware", "threat-intelligence", "yara", "capa", "ioc"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+]
+dependencies = [
+    "fastmcp>=3,<4",
+    "httpx~=0.27",
+    "pydantic~=2.0",
+    "pydantic-settings~=2.0",
+]
+
+[project.urls]
+Homepage = "https://www.threatray.com"
+Repository = "https://github.com/threatray/threatray-mcp"
+Issues = "https://github.com/threatray/threatray-mcp/issues"
+Documentation = "https://github.com/threatray/threatray-mcp#readme"
+"Threatray API reference" = "https://docs.threatray.com/reference/overview-api"
+
+[project.optional-dependencies]
+dev = [
+    "ruff~=0.8",
+    "vulture~=2.11",
+    "coverage~=7.6",
+    "mypy~=1.11",
+    "pytest~=8.0",
+    "PyHamcrest~=2.1",
+    "requests-mock~=1.12",
+    "respx~=0.22",
+]
+
+[project.scripts]
+threatray-mcp = "threatray_mcp.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/threatray_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/threatray_mcp", "README.md", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",     # pycodestyle errors
+    "W",     # pycodestyle warnings
+    "F",     # pyflakes
+    "I",     # isort
+    "PLC",   # pylint convention
+    "PLE",   # pylint error
+    "PLR",   # pylint refactor
+    "PLW",   # pylint warning
+    "RUF",   # Ruff-specific rules
+]
+
+ignore = [
+    "PLR2004",  # magic value comparison
+    "RUF012",   # mutable-class-default
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["PLR2004"]
+"vulture_whitelist.py" = ["ALL"]
+
+[tool.ruff.lint.pylint]
+max-args = 6
+max-branches = 12
+max-returns = 6
+max-statements = 50
+max-nested-blocks = 5
+max-public-methods = 20
+
+[tool.mypy]
+python_version = "3.11"
+ignore_missing_imports = true
+strict = false
+warn_return_any = true
+warn_unused_configs = true