# Vybog MCP Server

A standalone Model Context Protocol (MCP) server for the Fund Tracking System. This server enables agents to create, read, update, and delete lending business data (entities, borrowers, investors, deals, referrals) through a standardized interface.

## Features

- **Entity Management** for borrower entities used by borrowers and deals
- **Full CRUD Operations** on all resources (Entities, Borrowers, Investors, Deals, Referrals)
- **Bulk Operations** for creating multiple records at once
- **Authentication** using admin credentials
- **MCP Protocol** for seamless integration with Claude and other AI agents
- **Error Handling** and validation

## Installation

1. Navigate to the server directory:
```bash
cd /Users/chiragpatel/Projects/vybog/fts-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Create `.env` file from template:
```bash
cp .env.example .env
```

4. Configure your environment:
```env
BACKEND_URL=http://localhost:2000
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=admin123
```

## Running the Server

**Development mode** (with auto-reload):
```bash
npm run dev
```

**Production mode**:
```bash
npm start
```

The server communicates via stdio and is designed to be invoked by Claude or other MCP clients.

## Cloud AI Agent (OpenAI-Compatible + MCP)

You can run this agent using a cloud LLM with an OpenAI-compatible API.

### 1) Configure cloud LLM credentials

Set environment variables:

```bash
export OPENAI_API_KEY=your_api_key_here
export OPENAI_MODEL=gpt-4o-mini
# Optional custom endpoint
# export OPENAI_BASE_URL=https://api.openai.com/v1
```

### 2) Configure backend credentials

Set up `.env` in this project (same values used by MCP server):

```env
BACKEND_URL=http://localhost:2000
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=admin123
```

### 3) Run the agent

Interactive mode:

```bash
npm run agent
```

One-shot mode:

```bash
npm run agent -- "list all investors"
```

Optional environment variables:

- `OPENAI_API_KEY` (required)
- `OPENAI_MODEL` (default: `gpt-4o-mini`)
- `OPENAI_BASE_URL` (default: `https://api.openai.com/v1`)
- `OPENAI_TIMEOUT_MS` (default: `45000`)

Example:

```bash
OPENAI_API_KEY=your_api_key OPENAI_MODEL=gpt-4o-mini npm run agent
```

### 4) What it does

The agent runs from `src/agent` and connects to `src/index.js` through MCP stdio.
It plans tool calls from natural language and executes CRUD using existing tools such as:

- `create_borrower`, `list_borrowers`, `get_borrower`, `update_borrower`, `delete_borrower`
- `create_investor`, `list_investors`, `get_investor`, `update_investor`, `delete_investor`
- `create_deal`, `list_deals`, `get_deal`, `update_deal`, `delete_deal`
- `create_referral`, `list_referrals`, `get_referral`, `update_referral`, `delete_referral`
- `create_entity`, `list_entities`, `get_entity`, `update_entity`
- `add_invest_amount`, `link_investor_to_deal`
- `replace_investor_on_deal`
- `add_origination_fee_to_deal`, `add_monthly_interest_to_deal`, `add_daily_interest_to_deal`
- `add_borrower_payment_to_deal`, `add_borrower_disbursement_to_deal`, `add_referral_to_deal`

## Available Tools

### Borrowers
- `create_borrower` - Create a new borrower
- `list_borrowers` - List all borrowers with pagination
- `get_borrower` - Get borrower details
- `update_borrower` - Update borrower information
- `delete_borrower` - Delete a borrower
- `bulk_create_borrowers` - Create multiple borrowers at once

### Entities
- `create_entity` - Create a borrower entity
- `list_entities` - List all borrower entities
- `list_unmapped_entities` - List entities not currently mapped to borrowers or deals
- `get_entity` - Get entity details
- `update_entity` - Update entity information

### Investors
- `create_investor` - Create a new investor
- `list_investors` - List all investors
- `get_investor` - Get investor details
- `update_investor` - Update investor information
- `delete_investor` - Delete an investor
- `bulk_create_investors` - Create multiple investors at once

### Deals
- `create_deal` - Create a new lending deal
- `list_deals` - List all deals (filterable by status)
- `get_deal` - Get deal details
- `get_deal_financial_summary` - Get Financial Summary metrics for a deal (same section as deal view)
- `get_deal_payoff_calculation` - Get Payoff Calculator values for a deal
- `update_deal` - Update deal information
- `delete_deal` - Delete a deal
- `link_investor_to_deal` - Link an investor to a deal with amount, interest, and start date
- `replace_investor_on_deal` - Close out existing investor and replace with new investor funding
- `add_origination_fee_to_deal` - Add origination fee schedule to a deal
- `add_monthly_interest_to_deal` - Add monthly interest schedule to a deal
- `add_daily_interest_to_deal` - Add daily interest schedule to a deal
- `add_borrower_payment_to_deal` - Add a borrower payment received on a deal
- `add_borrower_disbursement_to_deal` - Add borrower disbursement (Holdback, Initial Amount, Topoff)
- `add_referral_to_deal` - Add referral detail to a deal using amount or rate

### Referrals
- `create_referral` - Create a referral
- `list_referrals` - List all referrals
- `get_referral` - Get referral details
- `update_referral` - Update referral
- `delete_referral` - Delete a referral

## Usage Examples

When invoked by Claude, you can ask it to:

```
"Create a borrower entity for TechStart Solutions LLC"
"Add investor William Scott to deal Aerospace dynamic"
"Add 100 billion contribution amount to Grace Evans"
"Link investor William Scott to deal Aerospace Dynamics with invested amount 250000, interest 8%, start date 2026-06-01"
"On deal Aerospace Dynamics, close out investor William Scott and replace with Sophia Martinez for amount 250000, start date 2026-07-01"
"On deal AeroSpace Dynamics R&D, close out Grace Evans and replace with Sophia Turner for amount 2000000, start date 2026-05-25"
"Replace Grace Evans with Sophia Turner on deal AeroSpace Dynamics R&D"  # agent should ask for amount and start date
"Add referral Maya Singh to deal Aerospace Dynamics at 6% rate"
"Add referral Maya Singh to deal Aerospace Dynamics with 15000 amount"
"Add borrower payment received on deal Aerospace Dynamics: amount 25000, payment type partial, date 2026-05-25"
"Add borrower disbursement to deal Aerospace Dynamics: target date 2026-06-15, type Holdback, amount 50000"
"Add borrower disbursement to deal Aerospace Dynamics: target date 2026-06-20, type Topoff, amount 25000"
"Add origination fee 8% to deal Aerospace Dynamics"
"Add monthly interest 1.5% to deal Aerospace Dynamics"
"Add monthly interest to deal Aerospace Dynamics"  # agent should ask for interest rate
"Add daily interest 12% APR to deal Aerospace Dynamics"
"Add daily interest to deal Aerospace Dynamics"  # agent should ask for interest rate
"Show financial summary for deal AeroSpace Dynamics R&D"
"Give me summary on deal AeroSpace Dynamics R&D"
"Get financial summary for deal id 83"
"Give me the payoff calculation on deal AeroSpace Dynamics R&D"
"Show payoff calculator values for deal id 83"
"List all active deals"
"Create a new deal between borrower XYZ and investor ABC"
"Update the status of deal 123 to completed"
```

For deal payment/schedule actions, the agent now validates required values before execution:

- Link investor to deal: invested amount, interest %, and start date
- Replace investor on deal: existing investor name, replacement investor name, amount, and start date
	(replacement investor must have sufficient available balance for the requested amount)
- Deal financial summary: deal name or deal id
- Deal payoff calculation: deal name or deal id
- Add origination fee: split interest value
- Add monthly interest: interest rate %
- Add daily interest: interest rate %
- Add borrower payment: amount, payment type, and date (YYYY-MM-DD)
- Add borrower disbursement: target date, disbursement type (Holdback, Initial Amount, Topoff), and amount
	(Topoff is normalized to backend type Topup)
- Add referral: referral name and either referral amount or interest rate

## Seeding

The MCP seed script now creates entities first, then creates borrowers and links each borrower to its matching entity ID when available.

Run it with:

```bash
npm run seed
```

Seeded data currently includes 10 entities, 10 borrowers, 10 investors, 10 deals, and 10 referrals.

## Architecture

```
vybog-mcp-server/
├── src/
│   ├── index.js           # Main MCP server implementation
│   └── api-client.js      # HTTP client for backend API
├── package.json
├── .env.example
└── README.md
```

## Backend Dependencies

This MCP server requires the **fts-be** backend service to be running:

1. Start the backend:
```bash
cd /Users/chiragpatel/Projects/vybog/fts-be
npm run dev
```

2. Ensure MySQL is running (or start Docker container):
```bash
docker start mysql-vybog
```

If Docker container doesn't exist, create it:
```bash
docker run --name mysql-vybog -e MYSQL_ROOT_PASSWORD=root -e MYSQL_DATABASE=vybog_db -p 3306:3306 -d mysql:8.0
```

## Integration with Claude

To use this MCP server with Claude in VS Code:

1. Configure the MCP server connection in VS Code settings
2. Point to this server's `src/index.js`
3. Provide environment variables via `.env`

See: https://modelcontextprotocol.io/

## Error Handling

The server includes comprehensive error handling:
- Authentication failures are caught and reported
- API errors from the backend are passed through with context
- Bulk operations report partial success/failure

## Development Notes

- The server uses stdio for MCP communication (stdin/stdout)
- JWT tokens are automatically obtained and refreshed
- All operations require admin authentication
- The API client is a singleton pattern for token reuse
- Entity tools map to the backend borrower entity routes under `/api/v2/borrower-entity`