Metadata-Version: 2.4
Name: nubra-mcp
Version: 0.1.1
Summary: Nubra MCP server for Codex and other MCP clients
Author: Nubra MCP Maintainers
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: fastapi<0.136,>=0.135.1
Requires-Dist: mcp<1.27,>=1.26.0
Requires-Dist: matplotlib<3.11,>=3.10.0
Requires-Dist: nubra-sdk==0.4.0
Requires-Dist: pandas<3.1,>=2.2.0
Requires-Dist: pydantic<2.13,>=2.12.5
Requires-Dist: requests<3,>=2.31.0
Requires-Dist: TA-Lib==0.6.8
Requires-Dist: uvicorn<0.43,>=0.42.0
Provides-Extra: indicators
Requires-Dist: nubra-talib==0.1.4; extra == "indicators"
Provides-Extra: backtest
Requires-Dist: vectorbt<0.29,>=0.28.4; extra == "backtest"
Provides-Extra: full
Requires-Dist: nubra-talib==0.1.4; extra == "full"
Requires-Dist: vectorbt<0.29,>=0.28.4; extra == "full"

# Nubra MCP Server

A Python MCP server for Nubra built on `FastMCP`.

This repo is designed to let MCP clients such as Codex connect to Nubra for:

- authentication
- instrument lookup and ref-id resolution
- quotes and historical data
- option-chain and derivatives analysis
- holdings, funds, positions, and portfolio reporting
- TA/indicator scans via `nubra-talib`
- backtesting via `vectorbt`
- local report and CSV export workflows
- UAT-only trading actions with strict environment guardrails

## What This MCP Supports

### Read-only workflows

- auth state and session checks
- cash, futures, and options instrument discovery
- quotes, current price, and previous-close change
- historical OHLCV fetch and CSV export
- options analytics and chain summaries
- portfolio summary, holdings, positions, and funds
- HTML and image-based portfolio reports
- watchlist scanning and strategy helper tools
- trade journal summaries
- backtest reports and equity curve exports

### Trading workflows

Trading is intentionally limited:

- order placement is allowed only in `UAT`
- order modification is allowed only in `UAT`
- order cancellation is allowed only in `UAT`
- square-off is allowed only in `UAT`
- options strategy execution is allowed only in `UAT`
- all trading actions are blocked in `PROD`

The guardrail exists in both the MCP tool layer and the service layer.

## Safety Model

This repo is meant to be public-safe if used correctly.

What should be committed:

- source code
- `.env.example`
- `.mcp.json`
- docs
- tests

What should never be committed:

- `.env`
- `auth_state.json`
- personal phone numbers
- MPIN values
- OTPs
- generated reports and exports

Each user of this MCP should create their own local `.env` and log in with their own Nubra account.

## Project Structure

- [server.py](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\server.py): MCP entrypoint and tool registration
- [config.py](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\config.py): environment-driven settings
- [nubra_client.py](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\nubra_client.py): Nubra client and high-level service layer
- [tools](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\tools): MCP tool modules
- [tests](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\tests): local unit tests
- [bootstrap.ps1](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\bootstrap.ps1): local environment setup
- [run_stdio.ps1](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\run_stdio.ps1): stdio launcher for MCP clients
- [run_http.ps1](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\run_http.ps1): HTTP launcher for manual testing

## Requirements

- Windows with PowerShell
- Python 3.12 recommended
- Nubra account access
- internet access for Nubra APIs

Installed dependencies include:

- `nubra-sdk`
- `nubra-talib`
- `TA-Lib`
- `pandas`
- `matplotlib`
- `vectorbt`
- `FastMCP` stack

## Setup

### 1. Clone the repo

```powershell
git clone https://github.com/socials-zanskar/nubra-mcp-server.git
cd nubra-mcp-server
```

### 2. Bootstrap the local environment

```powershell
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1
```

This script:

- creates `.venv`
- installs dependencies
- creates `.env` from `.env.example` if missing

### Alternative: install from pip

This repo also supports package-based install so users can run:

```powershell
pip install nubra-mcp
```

After install, the user gets a `nubra-mcp` command.

Important caveat:

- `nubra-sdk` installs from PyPI
- `nubra-talib` is not included in the base published package yet
- `vectorbt` is not included in the base published package yet
- indicator tools that depend on `nubra-talib` are optional in package mode for now
- backtest tools that depend on `vectorbt` are optional in package mode for now
- the repo/bootstrap flow still installs the full indicator and backtest stack for local development

Optional package installs:

```powershell
pip install "nubra-mcp[indicators]"
pip install "nubra-mcp[backtest]"
pip install "nubra-mcp[full]"
```

### 3. Fill in your local `.env`

Use [`.env.example`](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\.env.example) as the template.

Example:

```env
PHONE=
MPIN=
NUBRA_ENV=UAT
NUBRA_DEFAULT_EXCHANGE=NSE
LOG_LEVEL=INFO
HOST=127.0.0.1
PORT=8000
MCP_PATH=/mcp
AUTH_STATE_FILE=auth_state.json
```

Important:

- keep `NUBRA_ENV=UAT` while testing trading features
- do not commit your real `.env`
- do not share `auth_state.json`

## Running the MCP

### Packaged command

If installed as a package, the command is:

```powershell
nubra-mcp
```

That defaults to stdio mode so Codex can launch it directly as an MCP server.

Optional helper:

```powershell
nubra-mcp init
```

`init` is not required. It only creates a local user config template under the user's home folder for convenience.

### Recommended for MCP clients

```powershell
powershell -ExecutionPolicy Bypass -File .\run_stdio.ps1
```

### Recommended for HTTP testing

```powershell
powershell -ExecutionPolicy Bypass -File .\run_http.ps1
```

### Direct Python entrypoints

stdio:

```powershell
.\.venv\Scripts\python.exe .\server.py --transport stdio
```

streamable HTTP:

```powershell
.\.venv\Scripts\python.exe .\server.py --transport streamable-http
```

SSE:

```powershell
.\.venv\Scripts\python.exe .\server.py --transport sse
```

Default local endpoints for HTTP mode:

- health: `http://127.0.0.1:8000/health`
- mcp: `http://127.0.0.1:8000/mcp`

## Codex / MCP Client Integration

This repo includes [`.mcp.json`](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\.mcp.json), so repo-aware MCP clients can discover it automatically.

Typical local flow:

1. Open the repo folder in the MCP client.
2. Run bootstrap once.
3. Fill `.env`.
4. Reload or reopen the workspace.
5. Let the client launch [run_stdio.ps1](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\run_stdio.ps1).

If the client does not detect the server immediately, reload the workspace or restart the app.

### Codex desktop app flow for GitHub/repo users

1. Clone the repo.
2. Run bootstrap.
3. Fill `.env`.
4. Open the repo folder in Codex desktop.
5. Reload the workspace so Codex reads `.mcp.json`.
6. Start chatting with:
   - `Use nubra mcp and check auth status`

### Codex desktop app flow for pip users

1. Install the package:

```powershell
pip install nubra-mcp
```

2. Optionally create a user-home config template:

```powershell
nubra-mcp init
```

3. In Codex desktop, add a global MCP server entry using:
   - name: `nubra-mcp`
   - type: `stdio`
   - command: `nubra-mcp`
4. Reload or restart Codex desktop.
5. In a new chat, start with:
   - `Use nubra mcp and check auth status`

### Codex CLI flow for pip users

1. Install the package:

```powershell
pip install nubra-mcp
```

2. Register it with Codex CLI:

```powershell
codex mcp add nubra-mcp --command nubra-mcp
```

3. Verify registration:

```powershell
codex mcp list
```

4. Start Codex:

```powershell
codex
```

5. In chat, start with:
   - `Use nubra mcp and check auth status`

### Where pip users put credentials

`nubra-mcp init` is optional, not mandatory.

If the user does not run `init`, they can still connect and log in interactively through chat:

1. call `auth_status`
2. enter phone number when asked
3. enter OTP when asked
4. enter MPIN when asked

If the user does run `nubra-mcp init`, it creates a local config file under:

- `C:\Users\<username>\.nubra-mcp\.env`

That file is local only and should not be shared.

## Authentication Flow

The intended auth flow is:

1. call `auth_status`
2. if login is required, ask for phone number
3. call `begin_auth_flow` or `send_otp`
4. ask for OTP
5. call `verify_otp`
6. ask for MPIN
7. call `verify_mpin`

The authenticated session is stored locally in `auth_state.json` and reused until Nubra expires it or the user logs out.

## UAT Trading Guardrails

Trading tools are UAT-only.

Allowed only in `UAT`:

- `preview_uat_order`
- `place_uat_order`
- `modify_uat_order`
- `cancel_uat_order`
- `square_off_uat_position`
- `place_uat_options_strategy`
- `place_uat_named_option_strategy`

Blocked in `PROD`:

- all order placement
- all modify/cancel actions
- all square-off actions
- all strategy execution actions

Recommended trading flow:

1. use `preview_uat_order`
2. show the clean preview table to the user
3. confirm the order details
4. place the order with `place_uat_order`

The preview includes:

- environment
- symbol
- ref id
- side
- quantity
- order type
- price type
- order price
- product
- validity
- current price
- warnings if the limit is marketable

## Export and Report Features

This MCP can save artifacts locally on the user’s machine.

Examples:

- historical CSV exports
- HTML portfolio reports
- PNG portfolio dashboards
- HTML backtest reports
- PNG backtest equity curves

Exports are written under:

- [artifacts](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\artifacts)

For small outputs, tools can also return:

- `preview_rows`
- `preview_columns`
- `preview_mode`

That lets the chat render a small table inline while still providing a full downloadable file path.

## Indicator and Backtest Features

### `nubra-talib`

Indicator tools use `nubra-talib`.

In repo mode, it is installed through [requirements.txt](C:\Users\suboth sundar\Desktop\Nubra_API_Full_context\nubra-mcp-server\requirements.txt).

In package mode, `nubra-talib` is currently optional and not bundled into the base `pip install nubra-mcp` path yet.

Example uses:

- summarize indicators for one symbol
- scan multiple symbols for RSI thresholds
- scan EMA/SMA crossovers

### `vectorbt`

Backtesting tools use `vectorbt`.

In package mode, `vectorbt` is currently optional and not bundled into the base `pip install nubra-mcp` path yet.

Currently supported examples:

- moving average crossover backtest
- RSI backtest
- HTML backtest export
- equity curve image export

## Example Prompts

### Auth

- `Check auth status`
- `Start authentication for phone 9965514793`
- `Verify OTP 123456`
- `Verify MPIN 2004`

### Quotes and history

- `Get quote for RELIANCE`
- `Export historical data as CSV for RELIANCE on 1d candles from 2026-02-01 to 2026-03-01`
- `Give me a historical chart summary for RELIANCE on 1d candles`

### Portfolio

- `Generate a portfolio report`
- `Export my portfolio report as HTML`
- `Export my portfolio report as an image dashboard`

### Indicators

- `Summarize symbol indicators for RELIANCE on 1d candles with RSI 14 and EMA 20`
- `Scan indicator threshold for RELIANCE, TCS, INFY with RSI >= 60`

### Backtesting

- `Run a moving average crossover backtest for RELIANCE on 1d candles with fast_window 20 and slow_window 50`
- `Export a backtest report as HTML for RELIANCE using strategy_type ma_crossover`

### UAT trading

- `Preview a UAT order for RELIANCE with quantity 1, limit price 1500, and CNC`
- `Place a UAT order for RELIANCE with quantity 1, limit price 1500, and CNC`
- `Modify UAT order 12345 with a new price`
- `Cancel UAT order 12345`

## Local Validation

### Import smoke test

```powershell
.\.venv\Scripts\python.exe -c "import server; print('server-import-ok')"
```

### Run tests

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
```

## Public Release Checklist

Before pushing this repo publicly:

1. make sure `.env` is not committed
2. make sure `auth_state.json` is not committed
3. make sure `artifacts/` is ignored
4. make sure your real credentials are removed from local screenshots, logs, and examples
5. verify `NUBRA_ENV` defaults to `UAT` in examples
6. test `preview_uat_order` and `place_uat_order`
7. verify `PROD` trading is still blocked

## Notes

- Start with `UAT` while validating the tool surface.
- If a client says trading is disabled, it may be reading an older workspace or worktree copy of the repo.
- The main intended repo path should be used, not a stale Codex worktree, when testing the latest changes.
- This repo is designed to be extended; the tool surface is intentionally modular.
