# Perseus MCP Server

MCP (Model Context Protocol) server for integrating Plaid financial data with Perseus.

## Installation

Install the Perseus MCP server via NPM:

```bash
npx --yes @onbreeze/perseus-mcp@latest
```

## Configuration

### MCP Client Setup (Cursor/Claude Desktop)

Add the following configuration to your MCP client settings:

```json
{
  "mcpServers": {
    "perseus": {
      "command": "npx",
      "args": ["--yes", "@onbreeze/perseus-mcp@latest"],
      "env": {
        "PERSEUS_API_URL": "https://your-perseus-deployment.com/api",
        "PERSEUS_API_KEY": "your-api-key-from-perseus-dashboard"
      }
    }
  }
}
```

### Environment Variables

The MCP server requires two environment variables:

- **`PERSEUS_API_URL`**: The URL of your Perseus web API endpoint (e.g., `https://perseus.example.com/api`)
- **`PERSEUS_API_KEY`**: Your personal API key from the Perseus dashboard

## Available Tools

The Perseus MCP server provides three tools for interacting with Plaid financial data:

### 1. `connect_bank`

Initiates the Plaid Link flow to connect a new bank account.

**Input Parameters:**
- `redirectHint` (optional): Hint about where to redirect after linking

**Example:**
```json
{
  "tool": "connect_bank",
  "arguments": {
    "redirectHint": "dashboard"
  }
}
```

### 2. `get_balances`

Retrieves account balances from connected bank accounts.

**Input Parameters:**
- `itemId` (optional): Specific item ID to get balances for
- `accountIds` (optional): Array of specific account IDs to get balances for

**Example:**
```json
{
  "tool": "get_balances",
  "arguments": {
    "itemId": "item_123abc"
  }
}
```

### 3. `get_transactions`

Fetches transactions from connected bank accounts.

**Input Parameters:**
- `mode` (optional): Either `"snapshot"` (default) or `"date_range"`
- `startDate` (optional): Start date for date_range mode (YYYY-MM-DD format)
- `endDate` (optional): End date for date_range mode (YYYY-MM-DD format)

**Example:**
```json
{
  "tool": "get_transactions",
  "arguments": {
    "mode": "date_range",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  }
}
```

## Getting Started

1. **Set up Perseus Web**: Deploy the Perseus web application and obtain your API key from the dashboard
2. **Configure MCP Client**: Add the Perseus MCP server to your MCP client configuration
3. **Connect Bank Account**: Use the `connect_bank` tool to link your first bank account
4. **Access Financial Data**: Use `get_balances` and `get_transactions` to retrieve your financial information

## Development

To run the MCP server locally for development:

```bash
# Clone the repository
git clone https://github.com/mikeOnBreeze/obz-perseus.git
cd obz-perseus/perseus-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev
```

## License

MIT

## Support

For issues and questions, please visit: https://github.com/mikeOnBreeze/obz-perseus/issues