Metadata-Version: 2.4
Name: ttmcp
Version: 0.1.0
Summary: Use the Tradetron MCP from Python — build, backtest, diagnose and report on trading strategies, without an LLM.
Author-email: Tradetron <support@tradetron.tech>
License: MIT
Project-URL: Homepage, https://tradetron.tech
Keywords: tradetron,mcp,algo-trading,trading,backtest,options
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Dynamic: license-file

# ttmcp

Use the [Tradetron](https://tradetron.tech) MCP from Python — build, validate,
backtest, diagnose and report on trading strategies from your own code, with no
LLM in the loop.

Every tool the Tradetron AI assistant uses is available here as a plain Python
method returning a dict. Access is scoped to your own account and enforced
server-side.

```bash
pip install ttmcp
```

## Sign in once

```python
from ttmcp import TradetronMCP

tt = TradetronMCP()          # opens your browser the first time only
```

Your browser opens Tradetron's own login page. The resulting token is cached at
`~/.tradetron/mcp-token.json` (mode 0600) and refreshed automatically, so this
happens once rather than once per run. **Your password never passes through this
library** — it is the standard OAuth 2.1 authorization-code flow with PKCE.

## Then just call things

```python
tt.tt_get_my_profile()
tt.tt_portfolio_report(from_date="2026-07-01", to_date="2026-07-27")
tt.tt_report_template(template="monthly",
                      from_date="2026-01-01", to_date="2026-07-27")

# Read a strategy, then edit it structurally — dry run first.
s = tt.tt_get_strategy(strategy_id=9963334)
patch = [{"op": "replace", "path": "/name", "value": "Renamed"}]
tt.tt_apply_strategy_patch(strategy_id=9963334, patch=patch, dry_run=True)
tt.tt_apply_strategy_patch(strategy_id=9963334, patch=patch, dry_run=False)
```

## Discovering what exists

The server is the source of truth, so ask it rather than guessing:

```python
tt.list_tools()                          # every tool name
tt.describe("tt_apply_strategy_patch")   # its parameters, with types
```

## From the shell

```bash
ttmcp login
ttmcp tools
ttmcp describe tt_report_template
ttmcp call tt_report_template template=monthly from_date=2026-01-01 to_date=2026-07-27
ttmcp logout
```

Values are parsed as JSON when possible, so `dry_run=true` and
`add='["HDFCBANK"]'` both work.

## Errors

```python
from ttmcp import ToolError, AuthError

try:
    tt.tt_deploy_strategy_paper(strategy_id=9963334)
except ToolError as e:
    print(e.payload["error"]["code"])              # e.g. STRATEGY_DEPLOY_NO_PAPER_BROKER
    print(e.payload["error"]["user_facing_hint"])  # usually actionable
```

`AuthError` means the token was rejected — rebuild with
`TradetronMCP(force_login=True)`.

## Worth knowing

- **Report data is T-1.** P&L comes from the post-close reconciliation job, so a
  window ending today will look short. That is expected, not a bug.
- **Deploy is paper only.** `tt_deploy_strategy_paper` forces paper trading
  server-side; there is no live-deploy tool and no parameter that becomes one.
- **Writes are not idempotent.** Retrying a create or a deploy blind makes a
  second one. After an ambiguous failure, read your account back first.
- **Truncation is reported.** Where a result covers only part of your book, the
  payload carries an `omissions` list. Read it — a partial answer that looks
  complete is the expensive kind of wrong.
- **Rate limits** are 60 calls/minute and 1,000/day, plus 10 strategy creates
  and 30 edits per hour, counted per user rather than per client.

## Configuration

| Environment variable | Purpose |
|---|---|
| `TTMCP_URL` | MCP endpoint (default `https://mcp.tradetron.tech/mcp`) |
| `TTMCP_ISSUER` | OIDC issuer |
| `TTMCP_CLIENT_ID` | OAuth client id (default `tt-mcp-cli`) |
| `TTMCP_TOKEN_PATH` | Where the token cache lives |

## Full API documentation

Ask the server — it is always authoritative:

```python
tt.list_tools()
tt.describe("tt_apply_strategy_patch")
```

A written reference is published at <https://tradetron.tech> under Developers.

## Licence

MIT
