Vybog 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:

cd /Users/chiragpatel/Projects/vybog/fts-mcp

2. Install dependencies:

npm install

3. Create .env file from template:

cp .env.example .env

4. Configure your environment:

BACKEND_URL=http://localhost:2000
[email protected]
ADMIN_PASSWORD=admin123

Running the Server

Development mode (with auto-reload):

npm run dev

Production mode:

npm start

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

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
• update_deal - Update deal information
• delete_deal - Delete a deal

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 Example

When invoked by Claude, you can ask it to:

"Create a borrower entity for TechStart Solutions LLC"
"List all unmapped entities"
"Create 5 borrowers with sample data"
"List all active deals"
"Create a new deal between borrower XYZ and investor ABC"
"Update the status of deal 123 to completed"
"Create bulk investors from this list: [...]"

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:

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:

cd /Users/chiragpatel/Projects/vybog/fts-be
npm run dev

2. Ensure MySQL is running (or start Docker container):

docker start mysql-vybog

If Docker container doesn't exist, create it:

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