Metadata-Version: 2.4
Name: mcp-meroshare
Version: 1.4.1
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
Requires-Dist: keyring>=25.0.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.

## Security

**Credentials are stored in your OS keychain** — the AI model cannot read them.

The project ships with an `opencode.json` config containing **permission rules** that block the model from accessing credentials through any bash command. The model is denied from:

- Reading the OS keychain (`keyring.get_password`, `security find-generic-password`)
- Reading environment variables (`MERO_SHARE_*`)
- Running arbitrary `python3` or `python` commands

The only Python commands allowed are pre-approved subcommands: `python3 -m pytest`, `python3 -m build`, `python3 -m mcp_meroshare`, and `pip` operations.

| OS | Backend |
|---|---|
| macOS | Keychain (Security Framework) |
| Windows | Windows Credential Manager |
| Linux | Secret Service (gnome-keyring / KDE Wallet) |

If no keychain backend is available (e.g. headless Linux), the server falls back to a JSON config file at `~/.meroshare/config.{profile}.json` with a warning. The `opencode.json` rules also block the model from reading these fallback files.

## 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)
- **Security** — credentials stored in OS keychain, never pass through the AI model

## Tools

| Tool | Description |
|---|---|
| `meroshare_get_dp_list` | List all DPs with their code numbers (call this first) |
| `meroshare_login` | Log in to an account profile (reads from keychain) |
| `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** (e.g. `10400` for NABIL INVESTMENT BANKING LTD.).

### 2. Add a profile (terminal, not through AI)

```bash
mcp-meroshare add
```

You'll be prompted for:
- DP code (from step 1)
- Username (your BOID)
- Password
- CRN number
- Transaction PIN (optional)

Credentials are saved to your **OS keychain** — the AI model never sees them.

### 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)

```bash
mcp-meroshare add --profile <username>
mcp-meroshare add --profile aayansh
```

Then in your AI client:
```
"Apply 10 kitta for the recent ipo using aayansh login"
```

Each profile stores a separate entry in the OS keychain under service `mcp-meroshare`. 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` | — | DP client ID (resolved from DP code during configure) |
| `MERO_SHARE_USERNAME` | — | MeroShare username / BOID |
| `MERO_SHARE_PASSWORD` | — | Account password |
| `MERO_SHARE_CRN_NUMBER` | — | CASBA registration number |
| `MERO_SHARE_TRANSACTION_PIN` | — | Transaction PIN |

**Resolution order:** OS keychain → environment variables → JSON config file (legacy fallback).

Set any of these to override the keychain value for a session.

## CLI Flags

```
mcp-meroshare                   Run the MCP server (default)
mcp-meroshare add               Interactive credential setup (saves to OS keychain)
mcp-meroshare add --profile user_name     Set up a specific profile
mcp-meroshare remove --profile default Remove a profile from keychain
mcp-meroshare list              Show all configured profiles
mcp-meroshare --debug           Run with debug logging
mcp-meroshare --version         Show version
```

## License

MIT
