# 🔵 Investec OpenAPI MCP Server

[![CI Build Check](https://github.com/Investec-Developer-Community/investec-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/Investec-Developer-Community/investec-mcp-server/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Investec Developer](https://img.shields.io/badge/Investec-Developer-black.svg?logo=bank)](https://developer.investec.com/)
[![MCP Server](https://img.shields.io/badge/MCP-Server-orange.svg)](https://modelcontextprotocol.io/)

A premium, production-ready **Model Context Protocol (MCP) server** that wraps the official Investec OpenAPI. It enables AI coding assistants, developer agents (such as Claude Desktop, Cursor, or custom MCP clients), and automation scripts to interact directly and securely with your Investec personal, business, corporate, and programmable card accounts.

```
██╗███╗   ██╗██╗   ██╗███████╗███████╗████████╗███████╗ ██████╗ 
██║████╗  ██║██║   ██║██╔════╝██╔════╝╚══██╔══╝██╔════╝██╔════╝ 
██║██╔██╗ ██║██║   ██║█████╗  ███████╗   ██║   █████╗  ██║      
██║██║╚██╗██║╚██╗ ██╔╝██╔══╝  ╚════██║   ██║   ██╔══╝  ██║      
██║██║ ╚████║ ╚████╔╝ ███████╗███████║   ██║   ███████╗╚██████╗ 
╚═╝╚═╝  ╚═══╝  ╚═══╝  ╚══════╝╚══════╝   ╚═╝   ╚══════╝ ╚═════╝ 
                      OPENAPI MCP SERVER
```

---

## 🌟 Key Architecture Highlights

*   **🔒 Secure In-Memory Token Management**: Automatically performs the OAuth2 Client Credentials flow, safely caches tokens, and auto-refreshes them proactively before expiration. **No tokens or secrets are ever written to disk or printed in terminal logs.**
*   **🔌 Zero-Config Sandbox Mode**: Connects out-of-the-box using the official Investec public Sandbox credentials. You can test account balances, payments, statements, and transaction listings instantly without registering for an developer account first.
*   **🛠️ Robust Typings**: Exposes strict TypeScript type definitions for all API models, including complex payloads like batch payments (`paymultiple`) and programmable card code compilation.
*   **🚀 Stdio Transport Protocol**: Implements JSON-RPC 2.0 over standard I/O (stdio) compliant with the official Model Context Protocol (MCP) specifications.

---

## 📂 Repository Structure

```
investec-mcp-server/
├── .github/workflows/ci.yml # Automated CI validation pipeline
├── dist/                    # Compiled JavaScript build outputs
├── examples/                # Standalone SDK demo code
│   └── pb-demo.ts           # Demo of InvestecClient standalone usage
├── src/                     # TypeScript source code
│   ├── index.ts             # MCP server declaration and tools router
│   ├── investec-client.ts   # Core HTTP client & token manager
│   └── types.ts             # Strict TypeScript API schemas
├── .env.example             # Configuration settings template
├── CONTRIBUTING.md          # Open-source contribution guide
├── LICENSE                  # Open source MIT License
├── package.json             # Build dependencies and commands
└── tsconfig.json            # TypeScript compilation rules
```

---

## ⚙️ Installation & Setup

### 1. Build from Source
Ensure you have **Node.js** (v18.0.0 or higher) installed on your system.

```bash
# Clone the repository
git clone https://github.com/Investec-Developer-Community/investec-mcp-server.git
cd investec-mcp-server

# Install package dependencies
npm install

# Compile TypeScript to JavaScript
npm run build
```

### 2. Verify Connectivity (Sandbox Mode)
Run the sandbox integration test suite to verify that the server connects to the Investec developer sandbox API, fetches mock accounts, and reads balance sheets:
```bash
npm run test-sandbox
```

---

## 🔧 Environment Configuration

By default, the server runs in `sandbox` mode. To connect to your real live banking data, create a `.env` file in the root of the project (or copy `.env.example` to `.env`):

```ini
# 'production' to access live data, or 'sandbox' for mock accounts
INVESTEC_ENVIRONMENT=production

# Your Investec Developer credentials (obtained from Investec Online)
INVESTEC_CLIENT_ID=your_client_id
INVESTEC_CLIENT_SECRET=your_client_secret
INVESTEC_API_KEY=your_api_key

# Optional: Required for Advisor or Intermediary API scopes
INVESTEC_INTERMEDIARY_ID=your_intermediary_id
```

> [!CAUTION]
> **Keep your credentials secure!** Never commit your `.env` file to public version control. The included `.gitignore` is pre-configured to block `.env` uploads.

---

## 💬 Claude Desktop Integration

To link the MCP server to your local **Claude Desktop** application, edit your `claude_desktop_config.json`:
*   **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
*   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the server specification under `mcpServers`:

```json
{
  "mcpServers": {
    "investec-banking": {
      "command": "node",
      "args": [
        "C:/path/to/investec-mcp-server/dist/index.js"
      ]
    }
  }
}
```
*Note: Make sure to replace `C:/path/to/investec-mcp-server` with the absolute path to your local project directory.*

---

## 🛠️ Standalone SDK Usage

You can also import and use the underlying `InvestecClient` class as a standalone SDK in your own custom Node.js projects, independent of the MCP protocol:

```typescript
import { InvestecClient } from "./src/investec-client";

async function main() {
  // Uses .env variables or falls back to public Sandbox defaults
  const client = new InvestecClient({ environment: "sandbox" });
  
  // List Accounts
  const response = await client.pbListAccounts();
  const accounts = response.data.accounts;
  
  console.log(`Found ${accounts.length} accounts.`);
}
main();
```
*For a complete code demonstration, see [examples/pb-demo.ts](file:///c:/Users/jonel/Downloads/MCP_SERVER/examples/pb-demo.ts).*

---

## 🧰 Exposed Tools Reference

The server registers the following MCP tools:

### 💳 Private Banking (PB)
| Tool Name | Parameters | Description |
|---|---|---|
| `investec_pb_list_accounts` | None | List linked accounts ( cheque, savings, profiles ). |
| `investec_pb_get_account_balance` | `accountId` | Get available, current, and currency balance detail. |
| `investec_pb_get_account_transactions` | `accountId`, `fromDate?`, `toDate?`, `transactionType?`, `includePending?` | Fetch filtered transaction ledger feed. |
| `investec_pb_get_pending_transactions` | `accountId` | List outstanding pending transactions (e.g. card swipes). |
| `investec_pb_list_profiles` | None | List online profiles associated with user identity. |
| `investec_pb_list_profile_accounts` | `profileId` | List accounts associated with specific profile. |
| `investec_pb_list_beneficiaries` | None | Fetch registered payment beneficiaries. |
| `investec_pb_pay_multiple` | `accountId`, `paymentList` | Make batch payments to list of beneficiaries. |
| `investec_pb_transfer_multiple` | `accountId`, `paymentList` | Transfer funds between own accounts. |
| `investec_pb_get_documents` | `accountId`, `fromDate?`, `toDate?` | Retrieve list of statements and tax certificates. |
| `investec_pb_get_document` | `accountId`, `documentType`, `documentDate` | Fetch download link for specific statement PDF. |

### 💻 Programmable Cards
| Tool Name | Parameters | Description |
|---|---|---|
| `investec_card_list_cards` | None | List credit and debit cards linked to account. |
| `investec_card_create_virtual_card` | `accountNumber`, `embossName`, `embossName2?` | Issue virtual cards dynamically. |
| `investec_card_get_code` | `cardKey` | Get draft/working card JS scripts. |
| `investec_card_update_code` | `cardKey`, `code` | Upload new code draft for programmable cards. |
| `investec_card_publish_code` | `cardKey` | Publish and activate code for card swipe authorization. |
| `investec_card_execute_code` | `cardKey`, `authorizationModel` | Simulate card swipe swipe to test custom script logic. |
| `investec_card_get_execution_history`| `cardKey` | Fetch execution history logs of script. |
| `investec_card_get_env_vars` | `cardKey` | Retrieve script environment secrets. |
| `investec_card_update_env_vars` | `cardKey`, `variables` | Update script key-value environment secrets. |
| `investec_card_toggle_programmable` | `cardKey` | Turn programmable features on or off. |

### 🏢 Corporate & Institutional Banking (CIB)
| Tool Name | Parameters | Description |
|---|---|---|
| `investec_cib_list_accounts` | None | List corporate accounts. |
| `investec_cib_get_account_transactions`| `accountId`, `fromDate?`, `toDate?`, `page?` | Get corporate transaction ledger with pagination. |
| `investec_cib_list_companies` | None | List company entities under profile. |
| `investec_cib_get_orders_shipments_report` | `companyName` | Query current shipment and order status data. |

---

## 📄 License
This project is open-source and released under the [MIT License](LICENSE).
Feel free to fork, distribute, and integrate this project in commercial and private setups.
For official API support, consult the [Investec Developer Portal](https://developer.investec.com).