purchase-mcp-server/README.md

Purchase and budget management server handling requisitions, purchase orders, expenses, budgets, and vendor management with ERP access for data extraction

# Purchase MCP Server

A TypeScript-based Model Context Protocol (MCP) server for comprehensive vessel purchase management, budget analysis, and financial reporting with advanced Typesense search capabilities.

## Features

- **Universal Search System**: Advanced Typesense-powered search across purchase, budget, and expense data
- **Financial Analysis**: Monthly OPEX budget variance, committed cost tracking, and YTD summaries
- **Purchase Management**: Purchase order tracking, forwarder management, and requisition lifecycle
- **Vendor Management**: Intelligent vendor search and comprehensive contact information
- **Data Export**: Complete dataset exports for analysis and reporting
- **Fleet Operations**: Multi-vessel purchase activity and budget monitoring
- **Security**: IMO-based access control and company-specific data filtering

## Prerequisites

- Node.js (v18 or higher)
- MongoDB (Primary and Secondary databases)
- Typesense search server
- SIYA API access (JWT token and snapshot URL)

## Configuration

Configure the server using environment variables in a `.env` file in the root directory:

```env
# MongoDB Configuration
MONGO_URI=mongodb://your-primary-mongo-uri
DB_NAME=your-primary-db-name
SECONDARY_MONGO_URI=mongodb://your-secondary-mongo-uri
SECONDARY_DB_NAME=your-secondary-db-name
MONGODB_ETL_DEV_DATA_URI=mongodb://your-etl-mongo-uri
MONGODB_ETL_DEV_DATA_DB_NAME=your-etl-db-name

# Typesense Configuration
TYPESENSE_HOST=your-typesense-host
TYPESENSE_PORT=443
TYPESENSE_PROTOCOL=https
TYPESENSE_API_KEY=your-typesense-api-key

# SIYA API Configuration
SNAPSHOT_URL=https://dev-api.siya.com/v1.0/vessel-info/qna-snapshot
JWT_TOKEN=your-jwt-token

# Company Configuration
COMPANY_NAME=Your Company Name
companyName=Your Company Name

```

## Installation

1. Clone the repository:
```bash
git clone https://github.com/yourusername/purchase_mcp_server.git
cd purchase_mcp_server
```

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

3. Build the project:
```bash
npm run build
```

4. Start the server:
```bash
npm start
```

## Quick Start for Agent Integration

1. **Add to your MCP configuration:**
```json
{
  "mcpServers": {
    "purchase_mcp_server": {
      "command": "node",
      "args": ["path/to/purchase_mcp_server/dist/index.js"],
      "env": {
        "COMPANY_NAME": "Your Company Name",
        "MONGO_URI": "mongodb://your-primary-mongo-uri",
        "DB_NAME": "your-primary-db-name",
        "SECONDARY_MONGO_URI": "mongodb://your-secondary-mongo-uri",
        "SECONDARY_DB_NAME": "your-secondary-db-name",
        "MONGODB_ETL_DEV_DATA_URI": "mongodb://your-etl-mongo-uri",
        "MONGODB_ETL_DEV_DATA_DB_NAME": "your-etl-db-name",
        "TYPESENSE_HOST": "your-typesense-host",
        "TYPESENSE_PORT": "443",
        "TYPESENSE_PROTOCOL": "https",
        "TYPESENSE_API_KEY": "your-typesense-api-key",
        "SNAPSHOT_URL": "https://dev-api.siya.com/v1.0/vessel-info/qna-snapshot",
        "JWT_TOKEN": "your-jwt-token"
      }
    }
  }
}
```

2. **Test the connection:**
Use the `universal_purchase_search` tool with your vessel's IMO to verify connectivity.

3. **Start with basic queries:**
Begin with simple search operations before using advanced filtering and analysis tools.

## MCP Tools and Resources

### Universal Search Tools
- `universal_purchase_search`: Advanced purchase requisition and order search with comprehensive filtering, sorting, and faceted search capabilities
- `universal_budget_search`: Advanced vessel budget search with category, group, and period filtering
- `universal_expense_search`: Advanced vessel expense search with classification and amount filtering

### Budget Analysis Tools
- `get_monthly_opex_budget_variance`: Monthly OPEX budget variance analysis highlighting overspending categories
- `get_current_year_committed_cost`: Current year committed costs with percentage against YTD OPEX budget
- `get_budget_status_summary_ytd`: Year-to-date OPEX variance summary with fund status and key overspending areas

### Purchase Management Tools
- `get_purchase_orders_with_forwarders`: List of purchase orders available with forwarders ready for vessel connection
- `purchase_orders_open_more_than_180_days`: Purchase orders that have been open for more than 180 days

### Vendor Management Tools
- `find_relevant_vendors`: Search for vendors by query with optional category filtering
- `get_vendor_contact_details`: Retrieve detailed vendor contact information

### Data Export Tools
- `get_complete_vessel_budget_data`: Export complete budget records for comprehensive financial analysis
- `get_complete_vessel_purchase_requisition_data`: Export complete purchase requisition history for analysis
- `get_complete_vessel_expense_data`: Export complete expense records for financial audit and analysis

### Fleet Management Tools
- `get_fleet_purchase_log_table`: Purchase log information for all vessels in the fleet
- `get_fleet_purchase_activities`: Purchase activities overview across the fleet
- `get_fleet_budget_overviews`: Budget overview information for all fleet vessels

## Using the MCP Server

### Integration with Your Agent

Add this MCP server to your agent configuration to access vessel purchase management capabilities. The server provides tools for:

- **Financial Analysis**: Budget variance analysis, committed cost tracking
- **Purchase Management**: Search purchase orders, track requisitions
- **Vendor Operations**: Find and contact relevant vendors
- **Data Export**: Bulk export of financial data for analysis
- **Fleet Management**: Multi-vessel operations and oversight

### Tool Categories Available

1. **Universal Search Tools** - Advanced search across purchase, budget, and expense data
2. **Budget Analysis Tools** - Financial variance analysis and reporting
3. **Purchase Management Tools** - Order tracking and management
4. **Vendor Management Tools** - Vendor search and contact information
5. **Data Export Tools** - Complete dataset exports for analysis
6. **Fleet Management Tools** - Multi-vessel operations

### Security & Access Control

- All tools require valid IMO numbers for vessel identification
- Company-specific data filtering ensures access only to authorized vessel data
- IMO validation prevents unauthorized access to other companies' data

## Tool Usage Examples

### Universal Search Tools

**Search Purchase Orders:**
```json
{
  "name": "universal_purchase_search",
  "arguments": {
    "query_by": "vesselName,prDescription",
    "q": "engine parts",
    "filter_by": "purchaseRequisitionStatus:APPROVED",
    "sort_by": "purchaseRequisitionDate:desc",
    "per_page": 50
  }
}
```

**Search Budget Data:**
```json
{
  "name": "universal_budget_search",
  "arguments": {
    "filter_by": "imo:9123456 && group:OPEX",
    "sort_by": "budgetAmount:desc"
  }
}
```

### Budget Analysis Tools

**Get Monthly Budget Variance:**
```json
{
  "name": "get_monthly_opex_budget_variance",
  "arguments": {
    "imo": "9123456"
  }
}
```

**Check Committed Costs:**
```json
{
  "name": "get_current_year_committed_cost",
  "arguments": {
    "imo": "9123456"
  }
}
```

### Purchase Management

**Find Purchase Orders with Forwarders:**
```json
{
  "name": "get_purchase_orders_with_forwarders",
  "arguments": {
    "imo": "9123456"
  }
}
```

### Data Export

**Export Complete Purchase Data:**
```json
{
  "name": "get_complete_vessel_purchase_requisition_data",
  "arguments": {
    "imo": "9123456",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
  }
}
```



## Common Error Messages

### IMO Validation Errors
```
Error: IMO number 9999999 is not associated with the current company. 
Please provide a valid IMO number. Available IMO numbers: 9123456, 9234567, 9345678
```
**Solution**: Use one of the provided valid IMO numbers for your company.

### Date Format Errors
```
Invalid date format. Please use yyyy-mm-dd format.
```
**Solution**: Ensure all dates are in `yyyy-mm-dd` format (e.g., `2024-01-01`).

### Search Query Errors
```
Invalid field name in query_by parameter.
```
**Solution**: Check the tool documentation for valid field names in the `query_by` parameter.

## Troubleshooting

### No Results Returned
- Verify the IMO number is correct and associated with your company
- Check date ranges are valid and not in the future
- Ensure filter syntax uses correct field names and Typesense operators

### Performance Issues
- Use specific filters to narrow down results
- Reduce `per_page` parameter for large datasets
- Use date ranges to limit search scope

### Access Denied
- Confirm your company configuration includes the vessel IMO
- Check that the IMO number format is correct (numeric string)