Metadata-Version: 2.4
Name: mcp-meroshare
Version: 0.6.8
Summary: MCP server for MeroShare (CDSC Nepal) — IPO/FPO applications, portfolio, and share management
Author-email: Tek Prasad Chapagain <tekchapagain1@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/tekchapagain1/mcp-meroshare
Project-URL: Repository, https://github.com/tekchapagain1/mcp-meroshare
Project-URL: Issues, https://github.com/tekchapagain1/mcp-meroshare/issues
Keywords: mcp,meroshare,nepal,cdsc,ipo,stock,nepse
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.27.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.24; extra == "test"
Requires-Dist: respx>=0.22; extra == "test"
Requires-Dist: httpx>=0.27.0; extra == "test"

# mcp-meroshare

MCP (Model Context Protocol) server for [MeroShare](https://meroshare.cdsc.com.np) — Nepal's online share application system by CDSC Nepal.

Use it through opencode or any MCP-compatible client to manage IPO/FPO applications, portfolio, and share transactions directly from your AI tools.

## Features

- **IPO/FPO Application** — view open issues, apply with dry-run support
- **Portfolio** — check your holdings and transaction history
- **Account** — view DP list, own details, linked bank accounts
- **Multiple Accounts** — switch between profiles (e.g. personal, family, office)
- **Safety** — credential files locked to `chmod 600`, auto-retry on transient failures, session expiry

## Tools

| Tool | Description |
|---|---|
| `meroshare_get_dp_list` | List all DPs with their code numbers (call this first) |
| `meroshare_setup` | Save credentials permanently for a profile |
| `meroshare_login` | Log in to an account profile |
| `meroshare_logout` | Clear session |
| `meroshare_get_current_issues` | Open IPO/FPO/Rights issues |
| `meroshare_apply_ipo` | Apply for an issue (with `dry_run` preview) |
| `meroshare_get_bank_details` | Linked bank account info |
| `meroshare_get_own_detail` | Your profile (BOID, demat, email) |
| `meroshare_get_transactions` | Share transaction history |

## Installation

```bash
pip install mcp-meroshare
```

## Quick Start

### 1. Find your DP

Call `meroshare_get_dp_list` to see available Depository Participants. Note the **code number** in parentheses (e.g. `10400` for NABIL INVESTMENT BANKING LTD.).

### 2. Save your credentials

```json
meroshare_setup dpid: 10400, username: "your_boid", password: "...", crn_number: "...", transaction_pin: "..."
```

Your credentials are saved to `~/.meroshare/config.default.json` (locked to `chmod 600`). The DP code is automatically resolved to the internal client ID.

### 3. Log in

```
meroshare_login
```

### 4. Apply for an IPO

```json
meroshare_get_current_issues
meroshare_apply_ipo company_share_id: 123, applied_kitta: 10, demat: "...", boid: "...", bank_id: 1, account_branch_id: 1, account_number: "...", account_type_id: 1, customer_id: 1
```

Use `dry_run: true` to preview the application without submitting.

## Multiple Accounts (Profiles)

Use the `profile` argument to manage multiple accounts:

```json
meroshare_setup profile: "family", dpid: 10400, username: "...", password: "...", crn_number: "...", transaction_pin: "..."
meroshare_setup profile: "office", dpid: 10500, username: "...", password: "...", crn_number: "...", transaction_pin: "..."
meroshare_login profile: "family"
meroshare_login profile: "office"
```

Each profile stores credentials in `~/.meroshare/config.{profile}.json`. The default profile name is `default`.

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `MERO_SHARE_SESSION_TIMEOUT` | `900` (15 min) | Session idle timeout in seconds |
| `MERO_SHARE_MAX_RETRIES` | `2` | Number of retries on 5xx/network errors |
| `MERO_SHARE_CLIENT_ID` | — | Fallback if not set in profile config |
| `MERO_SHARE_USERNAME` | — | Fallback if not set in profile config |
| `MERO_SHARE_PASSWORD` | — | Fallback if not set in profile config |
| `MERO_SHARE_CRN_NUMBER` | — | Fallback if not set in profile config |
| `MERO_SHARE_TRANSACTION_PIN` | — | Fallback if not set in profile config |

Credentials are resolved in this order: explicit arguments → profile config file → environment variables.

## CLI Flags

```
mcp-meroshare                Run the MCP server
mcp-meroshare --debug        Run with debug logging
mcp-meroshare --version      Show version
```

## Security

**Credentials are stored in plaintext** in `~/.meroshare/config.{profile}.json`. This is a convenience trade-off to avoid re-entering credentials on every use.

### Mitigations

- On **macOS/Linux**: files are locked to `chmod 600` (owner read/write only)
- On **Windows**: file permissions are set to owner-only where supported; the file lives under `%USERPROFILE%` which is user-private by default
- Credentials are **never** logged or passed as tool arguments after setup
- Session auto-expires after 15 minutes of inactivity
- Retry logic with exponential backoff for transient failures

### Alternative: Environment Variables (Recommended for Shared Machines)

For better security on shared machines, skip `meroshare_setup` and use environment variables instead:

```bash
export MERO_SHARE_CLIENT_ID=17300
export MERO_SHARE_USERNAME=your_boid
export MERO_SHARE_PASSWORD=your_password
export MERO_SHARE_CRN_NUMBER=your_crn
export MERO_SHARE_TRANSACTION_PIN=your_pin
meroshare_login
```

No file is written to disk, and credentials live only in the process memory for the session duration. Note: your shell history may capture these — use a `.env` file or your MCP client's secret store for production. See [Environment Variables](#environment-variables) for details.

## License

MIT
