vt-mcp 0.8.3__tar.gz

vt_mcp-0.8.3/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

vt_mcp-0.8.3/LICENSES/MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vt-mcp contributors
+
+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.

vt_mcp-0.8.3/NOTICE

@@ -0,0 +1,11 @@
+vt-mcp
+Copyright (c) 2026 vt-mcp contributors
+
+This release is licensed under the Apache License, Version 2.0.
+
+Versions up to and including 0.8.0 were released under the MIT License.
+LICENSES/MIT.txt preserves the original copyright and permission notice for
+pre-existing material carried forward from those versions. It does not offer
+new contributions under an alternative MIT license.
+
+Dependencies are distributed separately under their respective licenses.

vt_mcp-0.8.3/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: vt-mcp
+Version: 0.8.3
+Summary: VirusTotal intelligence for MCP clients, powered by VTAI
+Author: VirusTotal
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: LICENSES/MIT.txt
+License-File: NOTICE
+Requires-Dist: anyio>=4.15.1,<5
+Requires-Dist: httpx>=0.28.1,<0.29
+Requires-Dist: mcp==2.1.1
+Requires-Dist: pydantic>=2.13.5,<3
+Requires-Python: >=3.12
+Project-URL: Homepage, https://ai.virustotal.com
+Project-URL: Documentation, https://ai.virustotal.com/install.md
+Project-URL: Repository, https://github.com/VirusTotal/virustotal-mcp
+Project-URL: Issues, https://github.com/VirusTotal/virustotal-mcp/issues
+Description-Content-Type: text/markdown
+
+# VirusTotal MCP
+
+<!-- mcp-name: io.github.VirusTotal/virustotal-mcp -->
+
+Give your agent VirusTotal intelligence before it opens a link, runs a downloaded file or investigates suspicious infrastructure. **vt-mcp** connects MCP clients to [VTAI](https://ai.virustotal.com), with reports for files, URLs, domains and IP addresses, file submission and analysis recovery.
+
+Use the free VTAI service with its current access limits. You need a **VTAI token**, available from [connection setup](https://ai.virustotal.com/connect/mcp); you do not need your own VirusTotal API key. Both local and remote connections use the same account rights and quotas.
+
+## Install for local stdio
+
+For local stdio, install [uv](https://docs.astral.sh/uv/getting-started/installation/) and run:
+
+```bash
+uv tool install --python 3.12 --default-index https://pypi.org/simple 'vt-mcp==0.8.3'
+vt-mcp --version
+```
+
+The command installs the package from the official PyPI index in an isolated tool environment. Python 3.12 or newer is required. Keep `vt-mcp` on the MCP client's PATH, or use its absolute executable path. The package does not modify client configuration.
+
+For a connection without a local Python process, use **`https://ai.virustotal.com/mcp`** with a supported HTTP client. Supply the VTAI token through either `Authorization: Bearer` or `x-apikey`, using the client's protected credential settings. Send only one authentication header. This is static token authentication; clients that require OAuth need a separate integration.
+
+## Connect your client
+
+1. Reuse your existing VTAI access or [create a token](https://ai.virustotal.com/connect/mcp).
+2. For stdio, save the token in a file readable only by your user, such as `~/.config/vt-mcp/token`. Set the MCP server's environment variable `VTAI_TOKEN_FILE` to that path and its command to `vt-mcp`. The file contains only the token; never put the token itself in chat, command arguments or project files.
+3. Follow the client-specific setup, restart or reconnect the client, and inspect its available tools.
+
+| Client | Setup |
+|---|---|
+| Antigravity CLI (`agy`) | [Local stdio](https://ai.virustotal.com/connect/mcp?client=agy&transport=stdio) |
+| Claude Code | [HTTP](https://ai.virustotal.com/connect/mcp?client=claude&transport=http) or [local stdio](https://ai.virustotal.com/connect/mcp?client=claude&transport=stdio) |
+| Codex | [HTTP](https://ai.virustotal.com/connect/mcp?client=codex&transport=http) or [local stdio](https://ai.virustotal.com/connect/mcp?client=codex&transport=stdio) |
+| Cursor | [HTTP recipe](https://ai.virustotal.com/connect/mcp?client=cursor&transport=http) |
+| VS Code with GitHub Copilot | [HTTP recipe](https://ai.virustotal.com/connect/mcp?client=vscode&transport=http) |
+| GitHub Copilot CLI | [Local stdio recipe](https://ai.virustotal.com/connect/mcp?client=copilot&transport=stdio) |
+| Devin Local | [Local stdio recipe](https://ai.virustotal.com/connect/mcp?client=devin&transport=stdio) |
+| Windsurf / Devin Desktop | [Cascade HTTP recipe](https://ai.virustotal.com/connect/mcp?client=cascade&transport=http) |
+| Antigravity IDE | [Local stdio configuration](#antigravity-ide) |
+
+The [client guide](https://ai.virustotal.com/install.md) distinguishes documented configuration, local transport checks and workflows exercised with a model. A recipe is not a claim of full validation in every client. Other agents can use the same MCP endpoint or the [VTAI API directly](https://ai.virustotal.com/skills/BASIC.md).
+
+For a first query, ask your agent:
+
+> Use VirusTotal to look up the SHA-256 hash e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. Explain the source, analysis date, coverage and limitations.
+
+This is the empty-file hash. A report lookup does not read or upload local files. A missing report remains unknown, and zero detections do not establish safety.
+
+## Antigravity IDE
+
+In the agent panel, open **MCP Servers → Manage MCP Servers → View raw config** and merge this entry with your existing configuration:
+
+```json
+{
+  "mcpServers": {
+    "virustotal": {
+      "command": "vt-mcp",
+      "args": [],
+      "env": {
+        "VTAI_TOKEN_FILE": "~/.config/vt-mcp/token"
+      }
+    }
+  }
+}
+```
+
+Use an absolute executable path if the IDE cannot find `vt-mcp`, then reload and inspect the tools. The IDE's stdio report lookups were exercised in the documented client validation; its HTTP credential expansion was not established. See [Antigravity MCP configuration](https://antigravity.google/docs/mcp).
+
+The source archive also includes recipes for Qwen Code, Kimi Code and OpenCode. Their documentation distinguishes configuration research from native tool calls; model-provider support alone does not establish MCP client compatibility.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `get_file_report(hash)` | Retrieve an existing report by MD5, SHA-1 or SHA-256. |
+| `get_url_report(url)` | Retrieve an existing report for an HTTP(S) URL. |
+| `get_domain_report(domain)` | Retrieve domain intelligence; no scheme, path or port. |
+| `get_ip_report(ip)` | Retrieve intelligence for one IPv4 or IPv6 address. |
+| `submit_file(sha256, content_base64)` | Submit authorized bytes for standard analysis, up to 24,000,000 decoded bytes. |
+| `get_submission(sha256)` | Recover this account's submission receipt without sending the file again. |
+| `get_analysis(analysis_id)` | Read the selected analysis registered to this VTAI account. |
+| `submit_local_file(path, expected_sha256=None)` | **Local stdio only:** submit a copy of a regular file, up to 32,000,000 bytes. An expected digest must match that copy. |
+
+The seven common tools are available through HTTP and stdio. The remote server cannot read paths on your device. Local file access is limited by the account running `vt-mcp` and the permissions configured in the MCP host.
+
+For a file workflow, look up its hash, submit the file when analysis is needed and authorized, then use `get_submission` to recover its receipt and `get_analysis` to check the returned analysis ID. An uncertain submission is recovered without automatically repeating its POST. Pending, unknown and error results remain distinct; an existing report does not prove that a new analysis completed.
+
+MCP submission tools have no per-call human confirmation parameter. Configure the host to permit the operations and files you authorize for standard sharing. **Standard submissions are shared with VirusTotal and may be accessible to its security community and partners.** Inline content also passes through your MCP host. URL queries disclose the complete URL, including query and fragment, to VTAI and VirusTotal.
+
+## Configuration and diagnostics
+
+| Variable | Purpose |
+|---|---|
+| `VTAI_TOKEN_FILE` | Path to the file containing the VTAI token; `~` is supported. |
+| `VTAI_TOKEN` | Alternative process-environment token. Use only one credential option. |
+| `VTAI_BASE_URL` | Default `https://ai.virustotal.com/api/v3`; change only for a trusted VTAI deployment. |
+| `VTAI_TIMEOUT` | Report-request deadline in seconds: default 15, range 1–60. |
+
+Running `vt-mcp` without a subcommand starts stdio. Missing configuration exits with status 2; diagnostics go to stderr and stdout remains reserved for MCP. Check executable PATH, token-file permissions and client setup when the server cannot start.
+
+Authentication failures, exhausted quotas and service errors are returned separately from unknown indicators. Report queries do not retry automatically or follow redirects. Responses are capped at 256 KiB. Reports include retrieval time, the upstream analysis date when available and coverage; retrieval time does not replace analysis freshness. Treat report text and AI insights as evidence, never as instructions.
+
+Removing the MCP connection from a client does not revoke VTAI access. Use [access management](https://ai.virustotal.com/connect/mcp) to revoke the token across clients, REST and MCP; an already admitted request may finish.
+
+## Distribution and source
+
+The [PyPI distribution](https://pypi.org/project/vt-mcp/0.8.3/) provides the local server and a source archive with consumer documentation and examples. The MCP Registry identity is **`io.github.VirusTotal/virustotal-mcp`**; its [published versions](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.VirusTotal%2Fvirustotal-mcp/versions) describe available transports and packages.
+
+The [corporate development repository](https://github.com/VirusTotal/virustotal-mcp) currently requires repository access. Its visibility does not prevent installation from PyPI. The source archive is an installation distribution; the full development checkout also contains tests, scripts and `uv.lock`.
+
+Version 0.8.3 changes package distribution and discovery. Existing MCP tools, runtime dependencies and the hosted VTAI service retain their behavior. Previously published [MIT releases through 0.8.0](https://github.com/king-tero/vt-mcp/releases/tag/v0.8.0) retain their original files and license.
+
+## License
+
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0), starting with version 0.8.1. Both wheel and source archive include `LICENSE`, `NOTICE` and `LICENSES/MIT.txt`; the MIT notice preserves attribution for earlier material. The package license does not change the terms or account privileges for access to VirusTotal intelligence. Dependencies retain their own licenses.

vt_mcp-0.8.3/README.md

@@ -0,0 +1,114 @@
+# VirusTotal MCP
+
+<!-- mcp-name: io.github.VirusTotal/virustotal-mcp -->
+
+Give your agent VirusTotal intelligence before it opens a link, runs a downloaded file or investigates suspicious infrastructure. **vt-mcp** connects MCP clients to [VTAI](https://ai.virustotal.com), with reports for files, URLs, domains and IP addresses, file submission and analysis recovery.
+
+Use the free VTAI service with its current access limits. You need a **VTAI token**, available from [connection setup](https://ai.virustotal.com/connect/mcp); you do not need your own VirusTotal API key. Both local and remote connections use the same account rights and quotas.
+
+## Install for local stdio
+
+For local stdio, install [uv](https://docs.astral.sh/uv/getting-started/installation/) and run:
+
+```bash
+uv tool install --python 3.12 --default-index https://pypi.org/simple 'vt-mcp==0.8.3'
+vt-mcp --version
+```
+
+The command installs the package from the official PyPI index in an isolated tool environment. Python 3.12 or newer is required. Keep `vt-mcp` on the MCP client's PATH, or use its absolute executable path. The package does not modify client configuration.
+
+For a connection without a local Python process, use **`https://ai.virustotal.com/mcp`** with a supported HTTP client. Supply the VTAI token through either `Authorization: Bearer` or `x-apikey`, using the client's protected credential settings. Send only one authentication header. This is static token authentication; clients that require OAuth need a separate integration.
+
+## Connect your client
+
+1. Reuse your existing VTAI access or [create a token](https://ai.virustotal.com/connect/mcp).
+2. For stdio, save the token in a file readable only by your user, such as `~/.config/vt-mcp/token`. Set the MCP server's environment variable `VTAI_TOKEN_FILE` to that path and its command to `vt-mcp`. The file contains only the token; never put the token itself in chat, command arguments or project files.
+3. Follow the client-specific setup, restart or reconnect the client, and inspect its available tools.
+
+| Client | Setup |
+|---|---|
+| Antigravity CLI (`agy`) | [Local stdio](https://ai.virustotal.com/connect/mcp?client=agy&transport=stdio) |
+| Claude Code | [HTTP](https://ai.virustotal.com/connect/mcp?client=claude&transport=http) or [local stdio](https://ai.virustotal.com/connect/mcp?client=claude&transport=stdio) |
+| Codex | [HTTP](https://ai.virustotal.com/connect/mcp?client=codex&transport=http) or [local stdio](https://ai.virustotal.com/connect/mcp?client=codex&transport=stdio) |
+| Cursor | [HTTP recipe](https://ai.virustotal.com/connect/mcp?client=cursor&transport=http) |
+| VS Code with GitHub Copilot | [HTTP recipe](https://ai.virustotal.com/connect/mcp?client=vscode&transport=http) |
+| GitHub Copilot CLI | [Local stdio recipe](https://ai.virustotal.com/connect/mcp?client=copilot&transport=stdio) |
+| Devin Local | [Local stdio recipe](https://ai.virustotal.com/connect/mcp?client=devin&transport=stdio) |
+| Windsurf / Devin Desktop | [Cascade HTTP recipe](https://ai.virustotal.com/connect/mcp?client=cascade&transport=http) |
+| Antigravity IDE | [Local stdio configuration](#antigravity-ide) |
+
+The [client guide](https://ai.virustotal.com/install.md) distinguishes documented configuration, local transport checks and workflows exercised with a model. A recipe is not a claim of full validation in every client. Other agents can use the same MCP endpoint or the [VTAI API directly](https://ai.virustotal.com/skills/BASIC.md).
+
+For a first query, ask your agent:
+
+> Use VirusTotal to look up the SHA-256 hash e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. Explain the source, analysis date, coverage and limitations.
+
+This is the empty-file hash. A report lookup does not read or upload local files. A missing report remains unknown, and zero detections do not establish safety.
+
+## Antigravity IDE
+
+In the agent panel, open **MCP Servers → Manage MCP Servers → View raw config** and merge this entry with your existing configuration:
+
+```json
+{
+  "mcpServers": {
+    "virustotal": {
+      "command": "vt-mcp",
+      "args": [],
+      "env": {
+        "VTAI_TOKEN_FILE": "~/.config/vt-mcp/token"
+      }
+    }
+  }
+}
+```
+
+Use an absolute executable path if the IDE cannot find `vt-mcp`, then reload and inspect the tools. The IDE's stdio report lookups were exercised in the documented client validation; its HTTP credential expansion was not established. See [Antigravity MCP configuration](https://antigravity.google/docs/mcp).
+
+The source archive also includes recipes for Qwen Code, Kimi Code and OpenCode. Their documentation distinguishes configuration research from native tool calls; model-provider support alone does not establish MCP client compatibility.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `get_file_report(hash)` | Retrieve an existing report by MD5, SHA-1 or SHA-256. |
+| `get_url_report(url)` | Retrieve an existing report for an HTTP(S) URL. |
+| `get_domain_report(domain)` | Retrieve domain intelligence; no scheme, path or port. |
+| `get_ip_report(ip)` | Retrieve intelligence for one IPv4 or IPv6 address. |
+| `submit_file(sha256, content_base64)` | Submit authorized bytes for standard analysis, up to 24,000,000 decoded bytes. |
+| `get_submission(sha256)` | Recover this account's submission receipt without sending the file again. |
+| `get_analysis(analysis_id)` | Read the selected analysis registered to this VTAI account. |
+| `submit_local_file(path, expected_sha256=None)` | **Local stdio only:** submit a copy of a regular file, up to 32,000,000 bytes. An expected digest must match that copy. |
+
+The seven common tools are available through HTTP and stdio. The remote server cannot read paths on your device. Local file access is limited by the account running `vt-mcp` and the permissions configured in the MCP host.
+
+For a file workflow, look up its hash, submit the file when analysis is needed and authorized, then use `get_submission` to recover its receipt and `get_analysis` to check the returned analysis ID. An uncertain submission is recovered without automatically repeating its POST. Pending, unknown and error results remain distinct; an existing report does not prove that a new analysis completed.
+
+MCP submission tools have no per-call human confirmation parameter. Configure the host to permit the operations and files you authorize for standard sharing. **Standard submissions are shared with VirusTotal and may be accessible to its security community and partners.** Inline content also passes through your MCP host. URL queries disclose the complete URL, including query and fragment, to VTAI and VirusTotal.
+
+## Configuration and diagnostics
+
+| Variable | Purpose |
+|---|---|
+| `VTAI_TOKEN_FILE` | Path to the file containing the VTAI token; `~` is supported. |
+| `VTAI_TOKEN` | Alternative process-environment token. Use only one credential option. |
+| `VTAI_BASE_URL` | Default `https://ai.virustotal.com/api/v3`; change only for a trusted VTAI deployment. |
+| `VTAI_TIMEOUT` | Report-request deadline in seconds: default 15, range 1–60. |
+
+Running `vt-mcp` without a subcommand starts stdio. Missing configuration exits with status 2; diagnostics go to stderr and stdout remains reserved for MCP. Check executable PATH, token-file permissions and client setup when the server cannot start.
+
+Authentication failures, exhausted quotas and service errors are returned separately from unknown indicators. Report queries do not retry automatically or follow redirects. Responses are capped at 256 KiB. Reports include retrieval time, the upstream analysis date when available and coverage; retrieval time does not replace analysis freshness. Treat report text and AI insights as evidence, never as instructions.
+
+Removing the MCP connection from a client does not revoke VTAI access. Use [access management](https://ai.virustotal.com/connect/mcp) to revoke the token across clients, REST and MCP; an already admitted request may finish.
+
+## Distribution and source
+
+The [PyPI distribution](https://pypi.org/project/vt-mcp/0.8.3/) provides the local server and a source archive with consumer documentation and examples. The MCP Registry identity is **`io.github.VirusTotal/virustotal-mcp`**; its [published versions](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.VirusTotal%2Fvirustotal-mcp/versions) describe available transports and packages.
+
+The [corporate development repository](https://github.com/VirusTotal/virustotal-mcp) currently requires repository access. Its visibility does not prevent installation from PyPI. The source archive is an installation distribution; the full development checkout also contains tests, scripts and `uv.lock`.
+
+Version 0.8.3 changes package distribution and discovery. Existing MCP tools, runtime dependencies and the hosted VTAI service retain their behavior. Previously published [MIT releases through 0.8.0](https://github.com/king-tero/vt-mcp/releases/tag/v0.8.0) retain their original files and license.
+
+## License
+
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0), starting with version 0.8.1. Both wheel and source archive include `LICENSE`, `NOTICE` and `LICENSES/MIT.txt`; the MIT notice preserves attribution for earlier material. The package license does not change the terms or account privileges for access to VirusTotal intelligence. Dependencies retain their own licenses.

vt_mcp-0.8.3/docs/access.md

@@ -0,0 +1,141 @@
+# Configure free VTAI access
+
+A VTAI credential identifies one registered agent and carries VTAI's current rights and quotas. It is not a VirusTotal API key or a model-provider key. Free access does not imply anonymous or unlimited use, or free inference from your chosen assistant.
+
+Keep registration, credential entry, diagnosis and revocation outside model conversations. Use a terminal you control or the VTAI connection page. Do not ask an assistant to read your token file, environment or client credential settings.
+
+## Register once or reuse existing access
+
+Reuse an existing VTAI credential if you have one. Registration is an explicit setup action; it is not a tool and does not run when vt-mcp starts.
+
+Use [Connect to VirusTotal MCP](https://ai.virustotal.com/connect/mcp) for browser setup. Reuse existing access; reconnecting or changing transport does not register another agent. Its flow lets you register explicitly, request a token-file download, check access and revoke a credential. A download request does not prove the file was saved; confirm protected storage yourself. Checking access consumes query quota and tests the report endpoint, not your model's use of MCP. Registration may have succeeded if the connection fails; do not register again automatically.
+
+The [browser acceptance table](clients.md#distribution-and-browser-acceptance) records the real flow through a route pinned to the production candidate, separately from ordinary public navigation and package release acceptance. If the page is unavailable, check the exact endpoint/prefix and [service validation](clients.md#service-and-workflow-validation). For a terminal setup, the explicit API example below is an alternative; opening the API URL alone does not register an agent.
+
+For local setup, this terminal script calls the existing registration API and writes the credential without printing it. It refuses an existing path and uses owner-only permissions on POSIX. Run it only once; if the request times out after registration, registration may have succeeded. Diagnose that uncertainty before creating another agent.
+
+```bash
+python3 - <<'PY'
+import json
+import os
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+class NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+path = Path.home() / ".config" / "vt-mcp" / "token"
+path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+path.parent.chmod(0o700)
+if path.exists() or path.is_symlink():
+    raise SystemExit("An existing credential path is already configured.")
+request = Request(
+    "https://ai.virustotal.com/api/v3/agents/register",
+    data=json.dumps({"agent_family": "vt-mcp", "agent_version": "0.8.3"}).encode(),
+    headers={"Content-Type": "application/json"},
+    method="POST",
+)
+try:
+    with build_opener(NoRedirect).open(request, timeout=20) as response:
+        raw = response.read(65537)
+        if len(raw) > 65536:
+            raise ValueError("response limit")
+        token = json.loads(raw)["agent_token"]
+    if not isinstance(token, str) or not token.startswith("vtai_"):
+        raise ValueError("credential format")
+    if not 6 <= len(token) <= 256 or any(not 33 <= ord(c) <= 126 for c in token):
+        raise ValueError("credential format")
+except (HTTPError, URLError, TimeoutError, ValueError, KeyError, TypeError):
+    raise SystemExit("Registration was not confirmed. No credential was saved.") from None
+try:
+    with os.fdopen(os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), "w") as output:
+        output.write(token)
+except OSError:
+    raise SystemExit("Registration returned access, but saving failed. Resolve local storage before retrying.") from None
+print("VTAI credential saved. Registration is not needed at each startup.")
+PY
+```
+
+An existing credential can instead be saved using a trusted editor or password manager to `~/.config/vt-mcp/token`, as a single value. Do not put it in a shell command or a project file. On POSIX, protect the directory with mode `0700` and the file with mode `0600`. If you downloaded a token, a browser does not guarantee those permissions: move it to protected storage and remove the extra download after verifying storage. Windows needs equivalent user-only file access; the POSIX instructions are not Windows validation.
+
+## Local stdio
+
+Install the wheel using the [README](../README.md), then add your client using [client setup](clients.md). Configure only the file path:
+
+```text
+VTAI_TOKEN_FILE=~/.config/vt-mcp/token
+```
+
+vt-mcp reads the file at startup and uses `x-apikey` for its VTAI requests. Restart its client process after replacing the file. `VTAI_TOKEN` is an alternative for direct process configuration; setting both credential options is an error.
+
+## Remote client environment
+
+Remote MCP uses `https://ai.virustotal.com/mcp`, not the REST URL ending `/api/v3`. Existing clients can keep using **`x-apikey`**. VTAI 0.8.1 additionally accepts the same VTAI credential in **`Authorization: Bearer`** on protected REST routes and MCP. This backend option does not require a vt-mcp 0.8.0 package upgrade.
+
+Use the host's supported environment-header reference from the [configuration fragments](../examples/client-configs/README.md). `VTAI_MCP_TOKEN` is an arbitrary host-side variable name, chosen to avoid conflict with a stdio server's `VTAI_TOKEN_FILE`.
+
+For Antigravity CLI (`agy`) 1.1.27, use the [stdio token-file setup](clients.md#antigravity-cli-agy); tested HTTP header variables were sent literally. Claude Code and Codex support the remote configurations described here.
+
+### Choose one authentication header
+
+Configure **one** credential method per connection: `x-apikey` or `Authorization: Bearer`. Both identify the same VTAI agent and share its rights, quotas and revocation. Sending both is rejected, even if their values match; an invalid Bearer does not fall back to `x-apikey`. Tokens in URLs, query parameters or request bodies do not authenticate a request.
+
+For the Bearer alternative, use the host's protected environment reference: [Claude Code](clients.md#claude-code) expands `Bearer ${VTAI_MCP_TOKEN}` in its Authorization header, and [Codex](clients.md#codex-cli--remote-http) supports `bearer_token_env_var = "VTAI_MCP_TOKEN"`. Remove any `x-apikey` mapping from that server entry when selecting Bearer. The examples contain a variable name, never a credential value. See the [scoped native Bearer checks and deployment status](clients.md#bearer-authentication-validation); earlier HTTP workflow evidence used `x-apikey`.
+
+This is a static VTAI Agent Token, not a VirusTotal API key, Google access token or model-provider login. VTAI does not implement OAuth login, refresh or OAuth discovery. A `WWW-Authenticate: Bearer` challenge does not establish an OAuth authorization server or hosted-connector compatibility. Do not run `codex mcp login` to obtain this token; reuse or explicitly register VTAI access as described above.
+
+The Bearer scheme is case insensitive and the token is case sensitive. The configured header must use spaces between the scheme and token, without quotes, surrounding whitespace, tabs or comma-separated credentials. The examples below load the token for either supported header mapping.
+
+In a human-controlled Bash terminal, load the file without printing its value, then launch the client:
+
+```bash
+(
+  set +x
+  unset VTAI_MCP_TOKEN
+  IFS= read -r VTAI_MCP_TOKEN < "$HOME/.config/vt-mcp/token" || test -n "$VTAI_MCP_TOKEN" || exit 1
+  test -n "$VTAI_MCP_TOKEN" || exit 1
+  export VTAI_MCP_TOKEN
+  exec claude
+)
+```
+
+Use `exec codex` instead for Codex, with its matching header configuration. A nonempty first line works with or without a trailing newline; a missing file or empty first line prevents launch. The subshell does not leave a new export in the parent shell. The variable lasts for that client process, and a previously opened GUI will not inherit it. Do not use a header flag containing an expanded credential: it can put the secret in process arguments and saved configuration. File and environment storage avoid normal disclosure in prompts; they do not isolate credentials from software with permission to read them.
+
+## Diagnose the right layer
+
+1. Check the installed client version and `vt-mcp --version` for stdio. Confirm the executable PATH and file access without displaying the credential.
+2. Inspect the client's MCP status. A configuration parser or `tools/list` result proves only that layer. In stdio, discovery does not authenticate a VTAI request.
+3. Make one explicit report query through the client. Use the empty-file SHA-256 `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`, or `example.com`. This consumes an admitted query and does not upload or start a scan. Check source, analysis date, coverage and report link.
+4. Confirm that the assistant actually called a tool and used its result. A generic SDK test or successful connection does not establish a model workflow in another client.
+
+| Observation | Meaning / action |
+|---|---|
+| 400 / Bearer `invalid_request` | Malformed or repeated Bearer authentication, or both credential methods sent together. Keep exactly one valid header mapping. |
+| 401 | No supported credential, or an invalid, unknown, expired or revoked Bearer token. Check the mapping and environment source without displaying the value. |
+| 403 / `access_denied` | Legacy `x-apikey` was rejected, or the operation was denied after authentication. Check the structured error and current access. |
+| 429 / `rate_limited` | Wait for a supplied retry delay; repeated retries consume resources. |
+| Tool result `not_found` | No report was found; this is not a safety verdict. |
+| HTTP 404 for `/mcp` or `/connect/mcp` | Check endpoint, prefix and deployment flags; this is not an unknown indicator result. |
+| Timeout / service error | A failed lookup is not a clean report. Check service status; do not silently submit a sample. |
+
+REST and MCP share VTAI admission and quotas. Unknown reports and upstream failures still consume an admitted query. The stdio wrapper defaults to a 15-second total request deadline; the backend lookup has its own 35-second limit. A client timeout can happen first, and an already admitted request may complete later. Show only sanitized errors to the model; never paste raw auth headers or debug logs into chat.
+
+VTAI 0.8.1 authentication failures use `Cache-Control: no-store`. Missing credentials receive a plain `Bearer realm="VTAI"` challenge; rejected Bearer tokens add `error="invalid_token"`, and malformed Bearer requests add `error="invalid_request"`. Legacy `x-apikey` rejections retain 403 without a challenge. Access-storage unavailability remains 503. Permission, quota and tool errors after authentication keep their existing contracts.
+
+## Disconnect and reconnect
+
+Remove or disable the `virustotal` entry in the client and restart/reload it. [Client setup](clients.md) lists removal commands. Verify that its tools disappear. This removes that connection; it does not revoke VTAI access or delete VTAI history.
+
+Do not remove a credential file shared by other clients unless you intend to remove their local access too. After a local disconnect, a still-valid credential can be used to reconnect without registering again.
+
+## Revoke access
+
+Use the revocation form at [the VTAI connection page](https://ai.virustotal.com/connect/mcp) when its deployment enables revocation. Enter the credential in that human-facing form and confirm the action. Its API is `DELETE /api/v3/agents/me/token`, authenticated with `x-apikey` or, on VTAI 0.8.1, the alternative Bearer header; this is an advanced setup operation, not an MCP tool.
+
+A confirmed revocation returns 204. A timeout or service error does not confirm success; retain protected access to the credential so you can diagnose or retry. A 401/403 means it was not accepted, not proof that this particular action revoked it.
+
+VTAI currently has one credential per agent. Revocation disables that agent across clients, REST and MCP; records remain, and a lookup admitted before revocation may finish. Remove the connection from every affected client afterward. To obtain access after revocation, explicitly register a new agent. This is not rotation of the old agent's credential.
+
+A subsequent request using the revoked token receives 401 with Bearer or 403 with legacy `x-apikey`; the two headers do not create separate credentials.