# ERP MCP - AI Ready

Goal: generate ERP full HTML report with live, filtered database data.

BASE_URL auto-derived from current host:

- BASE_URL: https://mcp-server-erp.commitflow.space

## 🔐 API Key (REQUIRED)

All MCP endpoint calls require a valid API key from environment variable.

### Setup

1. Set API key in `.env`:
```env
API_KEY=your-secure-api-key
# Generate: openssl rand -hex 32
```

2. Restart server

### Usage in Requests

**Method 1: Header (Recommended)**
```bash
curl -X POST https://mcp-server-erp.commitflow.space/mcp \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list"}'
```

**Method 2: Query Parameter**
```bash
curl -X POST "https://mcp-server-erp.commitflow.space/mcp?api_key=your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list"}'
```

## 🌐 Standard MCP 2.0 Endpoint (NEW)

**POST https://mcp-server-erp.commitflow.space/mcp** - JSON-RPC 2.0 Handler

### Available Methods:

1. **tools/list** - Get all available tools
2. **tools/call** - Execute a specific tool

### Example:

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list"
}
```

## Discovery

- **GET https://mcp-server-erp.commitflow.space/.well-known/mcp.json** - MCP discovery (STANDARD, public)
- GET https://mcp-server-erp.commitflow.space/tools - Legacy tools endpoint
- GET https://mcp-server-erp.commitflow.space/mcp-manifest.json - Machine-readable manifest (public)

## Required Workflow

1. read_schema_context
2. read_prisma_schema
3. build validated filters
4. generate safe SQL with explicit columns + pagination
5. execute via sql_query
6. render responsive/print-friendly HTML report
7. upload report to S3 and get URL for sharing

## Filter Contract (Recommended)

{"date_from":"YYYY-MM-DD","date_to":"YYYY-MM-DD","branch_id":"string|null","doctor_id":"string|null","limit":100,"offset":0,"timezone":"Asia/Jakarta"}

## Execute

### MCP Standard (NEW):
- **POST https://mcp-server-erp.commitflow.space/mcp** - JSON-RPC 2.0 format
- Body: {"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"<tool>","arguments":{...}}}

### Legacy (Still Supported):
- POST https://mcp-server-erp.commitflow.space/execute
- Body: {"tool":"<name>","input":{...}}

## Tools

### Database & Schema
- sql_query - Execute SQL queries
- read_schema_context - Read ERP schema
- read_prisma_schema - Read Prisma models
- test_connection - Test DB connection

### File Upload (S3/S3-Compatible)
- s3_upload - Upload file to S3 (public-read by default)
- s3_list - List files in S3 bucket
- s3_delete - Delete file from S3
- s3_url - Generate S3 file URL

### Report Generation ✨
- generate_report - Generate dynamic HTML reports with charts, tables, KPIs
  - Support multiple SQL queries
  - Visualizations: bar, line, doughnut charts
  - KPI cards, data tables, filters
  - Tabbed view via `tabs[]`: multiple report pages/domains in one HTML
  - Root `sections[]` can hold global header/filter; each `tabs[].sections[]` can hold its own KPI/chart/table/filter sections
  - Filterable reports should provide `queryTemplates` with tokens for every filter used by KPI/chart/table sections
  - Optional S3 upload & public sharing

### generate_report Tabbed View Contract

Use `tabs` when the user asks for a dashboard with multiple views, modules, or grouped analysis.

```json
{
  "title": "ERP Executive Dashboard",
  "queries": [
    { "name": "sales_summary", "sql": "SELECT ..." },
    { "name": "inventory_summary", "sql": "SELECT ..." }
  ],
  "sections": [
    { "type": "header", "title": "ERP Executive Dashboard" }
  ],
  "tabs": [
    {
      "id": "sales",
      "title": "Penjualan",
      "sections": [
        { "type": "kpi", "query": "sales_summary", "config": { "items": [{ "label": "Omzet", "key": "omzet", "format": "currency" }] } }
      ]
    },
    {
      "id": "inventory",
      "title": "Inventory",
      "sections": [
        { "type": "table", "query": "inventory_summary", "columns": [{ "key": "product_name", "label": "Produk" }] }
      ]
    }
  ],
  "uploadToS3": true
}
```

## Health

- GET https://mcp-server-erp.commitflow.space/health

## 📚 Documentation & Examples

- GET https://mcp-server-erp.commitflow.space/tool-examples - **Complete examples for each tool** (payload format, usage patterns)
- GET https://mcp-server-erp.commitflow.space/ai-ready - This markdown documentation
- GET https://mcp-server-erp.commitflow.space/.well-known/mcp.json - MCP discovery manifest

## AI Agent One-Liner

Use MCP endpoint **https://mcp-server-erp.commitflow.space/mcp** with JSON-RPC 2.0 protocol. Goal: generate ERP full HTML report with live filtered data, upload to S3, and share via public URL. Mandatory flow: read_schema_context -> read_prisma_schema -> validated filters -> safe SQL -> sql_query -> HTML render -> s3_upload -> share URL. **Refer to https://mcp-server-erp.commitflow.space/tool-examples for complete payload examples.**