# MCP Dashboard

A minimal dashboard for MCP services (local backend + server + tools).

## Features

- Local mock backend and API client utilities
- Services for analytics, wallet, transactions, vendors, and more

## Prerequisites

- Node.js (16+)
- npm or yarn

## Install

```bash
npm install
```

## Run (development)

```bash
npm run dev
```

## Build

```bash
npm run build
```

## Project structure (key files)

- src/: application source
  - src/server.ts - main server
  - src/chatServer.ts - chat server
  - src/localBackend.ts - local backend
- api/axios.ts - axios client
- services/ - business logic services
- tools/ - utility scripts (analytics, dashboard, etc.)

## Notes

- See `package.json` for available npm scripts.
- This README is a starting point — expand sections as needed.
# FinOps AI Copilot MCP Server

A production-quality Model Context Protocol (MCP) server that acts as a secure, read-only AI gateway for fintech operations dashboards. It allows LLMs (such as Cursor, Claude Desktop, or OpenAI-compatible engines) to inspect transactions, vendor performance, wallet balances, and analytics via secure REST APIs instead of exposing the database directly.

## Project Overview

FinOps AI Copilot enables natural language query resolution for operational and financial dashboards. By exposing standardized tools through the Model Context Protocol, the AI assistant can query real-time data securely.

### Architecture

```mermaid
graph TD
    User([User Query]) --> Client[Claude Desktop / Cursor / AI Client]
    Client -->|JSON-RPC via stdio| Server[FinOps MCP Server]
    Server -->|Zod Validation| Services[Service Layer]
    Services -->|Axios REST Calls| Backend[Dashboard Backend REST API]
    Backend --> DB[(MongoDB Database)]
```

## Security Design

1. **Read-Only Enforcement**: The MCP server only exposes query tools (`get*`, `find*`, `compare*`, `summary`). No state-changing endpoints are integrated.
2. **Gateway Pattern**: The AI client *never* directly talks to MongoDB or runs raw queries. All requests pass through the gateway and are validated against strict Zod schemas.
3. **Data Sanitization**: Secrets, customer sensitive credentials, and database keys are never exposed in tool definitions.
4. **Environment Isolation**: API endpoints and credentials are loaded dynamically from environment variables.

---

## Installation

### Prerequisites

- Node.js (v18 or higher)
- npm or yarn

### Setup

1. Clone or navigate to the workspace directory:
   ```bash
   cd "/Users/apple/Desktop/mcp dasboard"
   ```

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

3. Configure Environment Variables:
   Copy `.env.example` to `.env` and fill in the details:
   ```bash
   cp .env.example .env
   ```

---

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Local port for optional server operations | `3000` |
| `BACKEND_API_URL` | Base URL of the existing REST API | `http://localhost:4000/api` |
| `BACKEND_API_KEY` | Bearer Token / API key for REST endpoints | `mock-api-key-12345` |
| `LARGE_TRANSACTION_THRESHOLD` | Threshold to filter large payments | `50000` |

---

## Available Tools

The MCP server registers the following operational tools:

### 1. Dashboard
- `getDashboardMetrics`: High-level business overview (Total processed volume, count, success rate, failed amount, pending transaction count, wallet balance).

### 2. Transactions
- `findTransactionById`: Search transaction details by transaction ID.
- `findTransactions`: Search for transactions using filters like status, vendor, merchant, amount range, and dates.
- `failedTransactions`: Retrieve failed transaction list (supports pagination).
- `pendingTransactions`: Retrieve pending payout/settlement list.
- `largeTransactions`: Retrieve payments exceeding the threshold.
- `retryTransactions`: Retrieve payments that have been retried multiple times.

### 3. Vendors
- `vendorPerformance`: Return success/failure rates, average response times, and volumes for a specific vendor.
- `topVendor`: Get vendor with the highest success rate.
- `worstVendor`: Get vendor with the highest failure rate.
- `vendorComparison`: Side-by-side comparison of two vendors.

### 4. Wallet
- `walletBalance`: Current wallet balance across channels.
- `walletHistory`: Log of credit/debit adjustments and balance history.

### 5. Analytics & AI Summary
- `todayVsYesterday`: Daily comparison of transactions count, amount, and success rates.
- `weeklyAnalytics`: Last 7 days metrics.
- `monthlyAnalytics`: Current month summaries.
- `peakHour`: Identifies busiest transaction hour.
- `merchantAnalytics`: Top merchants by volume and transaction count.
- `dailySummary`: AI-structured daily business performance summary with recommendation.

---

## Claude Desktop Configuration

To link this server with your Claude Desktop client, append the following block to your local configuration file:

### File Paths
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

### Configuration Snippet
```json
{
  "mcpServers": {
    "finops-ai-copilot": {
      "command": "node",
      "args": [
        "/Users/apple/Desktop/mcp dasboard/node_modules/tsx/dist/cli.js",
        "/Users/apple/Desktop/mcp dasboard/src/server.ts"
      ],
      "env": {
        "BACKEND_API_URL": "http://localhost:4000/api",
        "BACKEND_API_KEY": "mock-api-key-12345",
        "LARGE_TRANSACTION_THRESHOLD": "50000"
      }
    }
  }
}
```

---

## Testing locally

To run the mock backend and query the services locally:

1. Start the mock backend REST API (runs on port 4000):
   ```bash
   npx tsx scratch/mock_backend.ts
   ```

2. Run the integration test client:
   ```bash
   npx tsx scratch/test_client.ts
   ```

3. Type check the server code:
   ```bash
   npm run build
   ```

---

## Future Roadmap

- **Anomaly Detection**: Flags sudden drops in success rates.
- **Root Cause Analysis**: Diagnoses why transactions fail (e.g., bank downtime vs. card failure).
- **Fraud Detection**: Identifies velocity spikes or suspicious repeated low-value transactions.
- **Vendor Recommendation**: Dynamic routing recommendations to route traffic away from degrading vendors automatically.
- **Scheduled Reports**: Automatic generation and distribution of daily/weekly reports via email or Slack.
- **Role-Based Access Control (RBAC)**: Fine-grained user/client permissions for different categories of financial metrics.