Metadata-Version: 2.4
Name: neuraldefend-mcp
Version: 1.0.0
Summary: Secure MCP server for the NeuroVerify media authenticity API
Project-URL: Documentation, https://github.com/Neural-Defend/NeuralDefend-SDKs/tree/main/packages/mcp
Project-URL: Issues, https://github.com/Neural-Defend/NeuralDefend-SDKs/issues
Author: Neural Defend
License: MIT License
        
        Copyright (c) 2026 Neural Defend
        
        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.
License-File: LICENSE
Keywords: authenticity,fraud,mcp,media,security
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: anyio<5,>=4
Requires-Dist: mcp<2,>=1.28
Requires-Dist: neuraldefend<2,>=1
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff==0.16.0; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# neuraldefend-mcp

Secure, stdio-only MCP tools for image and video authenticity analysis through the
NeuroVerify Python SDK.

## Install

```bash
python -m pip install neuraldefend-mcp
```

The package provides both `neuraldefend-mcp` and `python -m neuraldefend_mcp`.

## Required security configuration

Set both variables in the MCP server process:

- `NEURALDEFEND_API_KEY`: the NeuralDefend API key. It is read only from the environment
  and is never a tool argument.
- `NEURALDEFEND_MCP_ALLOWED_DIRS`: one or more absolute directories that the server may
  read. Separate directories with the platform path separator: `;` on Windows and `:` on
  macOS/Linux.

The server refuses to start when the allowlist is missing or invalid. Filesystem roots,
file paths, relative paths, empty entries, and roots containing symlinks, junctions, or
reparse points are rejected. At tool invocation time, the requested file must be a regular,
non-empty file below an allowed directory and must not traverse any link or reparse point.

Optional: `NEURALDEFEND_MCP_MAX_CONCURRENCY` is a positive integer from 1 through 32 and
defaults to `2`.

Optional: `NEURALDEFEND_MCP_ENVIRONMENT` selects the API origin. It accepts only
`production` (the default) or `staging`; arbitrary URLs are rejected. Use `staging` for
non-production integration tests.

Only configure directories containing media that users have explicitly authorized for
upload. Media may contain biometric and other sensitive personal data.

## MCP client configuration

Windows example:

```json
{
  "mcpServers": {
    "neuraldefend": {
      "command": "neuraldefend-mcp",
      "env": {
        "NEURALDEFEND_API_KEY": "${NEURALDEFEND_API_KEY}",
        "NEURALDEFEND_MCP_ALLOWED_DIRS": "D:\\Authorized Media;E:\\Review Queue"
      }
    }
  }
}
```

macOS/Linux example:

```json
{
  "mcpServers": {
    "neuraldefend": {
      "command": "neuraldefend-mcp",
      "env": {
        "NEURALDEFEND_API_KEY": "${NEURALDEFEND_API_KEY}",
        "NEURALDEFEND_MCP_ALLOWED_DIRS": "/srv/authorized-media:/home/user/review-queue"
      }
    }
  }
}
```

If the MCP client does not expand `${NEURALDEFEND_API_KEY}`, use its supported secret
injection mechanism. Do not place a real key in a committed configuration file.

## Tools

- `detect_image_authenticity(file_path)` analyzes an image containing one clearly visible
  face.
- `detect_video_authenticity(file_path, max_frames=12)` analyzes video and audio
  independently. `max_frames` must be from 1 through 100.

Business rejections are normal tool results. “Could not score” means the media was
unscorable, not that it was authentic, and a rejected invocation should not be retried
automatically. A high risk result should be escalated for review rather than used as an
automatic rejection. Low risk is not definitive proof of authenticity.

Each tool call can create a new, billable transaction, including some face-policy
rejections. Agents should disclose that possibility before invoking a tool and should
never repeat a call merely to obtain a different score or message.

The Python SDK owns network retry behavior; this MCP layer adds no retries. It opens each
local file once, validates the open handle, and streams that same handle to the SDK without
loading a video into memory. Tool output contains a bounded, versioned field allowlist and
never includes local paths, filenames, media bytes, response headers, or the SDK raw
payload.

## Development

```bash
python -m pip install -e ".[dev]"
pytest
ruff check .
mypy
python -m build
twine check dist/*
```
