# Tryton Stock MCP

Tryton Stock MCP is a read-only Model Context Protocol server for investigating
product, lot, location and stock-movement history in Tryton 6.x.

It turns questions such as “audit the complete history of product X” into a
structured investigation covering movement states, lots, incoming shipments,
outgoing shipments, internal transfers, locations, official contextual
quantities and derived diagnostic balances.

## Safety model

- The MCP tools expose no create, write, delete or workflow RPC methods.
- Credentials are read only from environment variables.
- Tool logs contain metadata only: tool name, status, duration and error type.
- Record searches are restricted to product and stock-related models.
- `describe_model` may inspect metadata for any model, but it does not read records.
- Derived balances are investigative evidence, not official Tryton stock.

Use a dedicated Tryton account with read-only, least-privilege access. This
project does not make a write-capable account safe. Avoid sending clinical or
personal data to an MCP client unless its privacy properties are acceptable for
your environment.

## Requirements

- Python 3.10 or newer
- Tryton 6.x with JSON-RPC enabled
- Read access to product and stock models

## Recommended installation with pipx

[`pipx`](https://pipx.pypa.io/) installs the MCP in its own isolated Python
environment and exposes the `tryton-stock-mcp` command globally.

If pipx is not installed yet:

```bash
python -m pip install --user pipx
python -m pipx ensurepath
```

Open a new terminal after `ensurepath` so the installed commands are available.

Install directly from GitHub:

```bash
pipx install "git+https://github.com/SamuelBalbas/tryton-stock-mcp.git"
```

Or install from a local clone while developing:

```bash
git clone <your-fork-or-repository-url> tryton-stock-mcp
cd tryton-stock-mcp
pipx install .
```

Run the server:

```bash
tryton-stock-mcp
```

Upgrade or uninstall it:

```bash
pipx upgrade tryton-stock-mcp
pipx uninstall tryton-stock-mcp
```

When a PyPI release becomes available, installation can be shortened to
`pipx install tryton-stock-mcp`.

## Development installation

The repository-local workflow remains available for contributors and
troubleshooting:

```bash
git clone <your-fork-or-repository-url> tryton-stock-mcp
cd tryton-stock-mcp
python -m venv .venv
```

Windows PowerShell:

```powershell
.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
```

Linux or macOS:

```bash
source .venv/bin/activate
python -m pip install -e ".[dev]"
```

## Configure

The server reads its configuration from the process environment. `.env.example`
is a reference file; it is not loaded automatically.

Required variables:

| Variable | Purpose |
|---|---|
| `TRYTON_DATABASE` | Tryton database name |
| `TRYTON_USER` | Dedicated read-only user |
| `TRYTON_PASSWORD` | User password |

Optional variables:

| Variable | Default | Purpose |
|---|---:|---|
| `TRYTON_HOST` | `localhost` | Tryton host |
| `TRYTON_PORT` | `8000` | JSON-RPC port |
| `TRYTON_PROTOCOL` | `http` | `http` or `https` |
| `TRYTON_TIMEOUT` | `30` | Request timeout in seconds |
| `TRYTON_AUDIT_LOG_ENABLED` | `true` | Enable metadata-only local logging |
| `TRYTON_AUDIT_LOG` | `./logs/mcp_actions.jsonl` | Log destination |
| `TRYTON_ALLOW_INSECURE_REMOTE` | `false` | Permit HTTP to a non-local host |

Remote HTTP is rejected unless explicitly enabled. HTTPS is strongly
recommended whenever Tryton is not running on the same machine.

## Run from a development checkout

```bash
python -m tryton_stock_mcp
```

The server uses MCP `stdio`, so normal output must not be written to stdout.

## MCP client configuration

With the recommended pipx installation, the client only needs the installed
command and the Tryton environment variables:

```json
{
  "mcpServers": {
    "tryton-stock": {
      "command": "tryton-stock-mcp",
      "args": [],
      "env": {
        "TRYTON_HOST": "localhost",
        "TRYTON_PORT": "8000",
        "TRYTON_DATABASE": "your_database",
        "TRYTON_USER": "readonly_auditor",
        "TRYTON_PASSWORD": "replace_me",
        "TRYTON_PROTOCOL": "http"
      }
    }
  }
}
```

If the MCP client does not inherit the shell `PATH`, use the absolute path
reported by `pipx environment` or `pipx list`. For a development checkout,
use the virtual environment's absolute Python path with the arguments
`-m tryton_stock_mcp`.

## Guided audit

The main tool is `audit_product_history`.

Inputs:

- `product_query`: product name or code, or
- `product_id`: exact Tryton product variant ID
- `lot_number`: optional lot filter
- `include_cancelled`: include cancelled movements, default `true`

Exactly one of `product_query` or `product_id` is required. When a query matches
multiple products, the tool returns `needs_product_selection` with candidates;
the caller must choose one before the full audit runs. Lots follow the same rule.

The successful result includes:

- every matching movement, retrieved in bounded pages until exhaustion;
- counts for done, draft, staging, assigned, cancelled and other states;
- incoming, outgoing, internal and other workflow counts;
- shipments and origins exposed by `stock.move`;
- registered, missing and cross-product lot evidence;
- pending movements and effective-date inconsistencies;
- official product quantities for internal locations;
- chronological derived balances and first-negative evidence;
- a concise Markdown report plus complete JSON evidence.

## Additional tools

The server also exposes focused tools for searching products, lots, locations
and moves; finding pending moves; reconstructing ledgers; comparing products;
querying official quantities; and generating generic product or move reports.

`search_reference_globally` is intentionally restricted to the approved stock
models. `describe_model` is the only tool that accepts any Tryton model name,
and it returns field metadata only.

## Diagnostic limits

Tryton's official stock calculation depends on context, company, locations and
date. The MCP reports official contextual quantity separately from balances it
reconstructs by adding completed incoming movements and subtracting completed
outgoing movements. Never use a reconstructed balance as an automatic inventory
adjustment.

## Development

```bash
python -m pip install -e ".[dev]"
python -m pytest
```

Tests use synthetic JSON-RPC responses and do not require a live database.

## License

Apache License 2.0. See [LICENSE](LICENSE).