# 4D MCP Server

Model Context Protocol (MCP) server for 4D REST API integration. Provides tools for authentication, data querying, manipulation, and ORDA class function calls.

## Features

- **Authentication**: Login with username/password or hashed password
- **Schema Inspection**: Get database catalog information
- **Data Querying**: Query dataclasses with filtering, sorting, and pagination
- **Data Manipulation**: Create, update, and delete records
- **ORDA Functions**: Call class functions on the 4D server
- **Session Management**: Automatic session cookie handling

## Installation

### For MCP Client Usage

Install globally via npm:
```bash
npm install -g 4d-mcp
```

### For Development

1. Clone and install dependencies:
```bash
git clone <repository-url>
cd 4d-mcp
npm install
```

2. Configure environment variables:
```bash
cp .env.example .env
```

Edit `.env` with your 4D server settings:
```env
FOURD_BASE=https://your-4d-server:port
FOURD_USER=username
FOURD_PASSWORD=password
FOURD_SESSION_MINUTES=60
FOURD_ALLOW_SELF_SIGNED=true  # For development only
```

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

## Usage

### Development
```bash
npm run dev
```

### Production
```bash
npm run build
npm start
```

## Available Tools

### 1. login
Authenticate with the 4D server and establish a session.

Parameters:
- `user` (optional): Username override
- `password` (optional): Password override  
- `hashed` (optional): Whether password is hashed
- `minutes` (optional): Session duration override

### 2. catalog
Get database schema information.

Parameters:
- `all` (optional): Include all catalog details

### 3. query
Query data from a dataclass.

Parameters:
- `dataClass` (required): Dataclass name
- `filter` (optional): 4D query filter
- `orderby` (optional): Sort specification
- `top` (optional): Max records to return
- `skip` (optional): Records to skip (pagination)
- `attributes` (optional): Specific attributes to include
- `expand` (optional): Related attributes to expand

### 4. upsert
Create or update records.

Parameters:
- `dataClass` (required): Dataclass name
- `body` (required): Record data (object or array)

### 5. delete
Delete records from a dataclass.

Parameters:
- `dataClass` (required): Dataclass name
- `key` (optional): Specific record key
- `filter` (optional): Query filter for bulk delete

### 6. callFunction
Call ORDA class functions.

Parameters:
- `target` (required): Interface/dataclass name
- `func` (required): Function name
- `params` (optional): Function parameters array

## 4D Server Requirements

1. **Enable REST Server**: Set "Expose REST server" in 4D settings
2. **Configure Exposure**: Ensure dataclasses and attributes are exposed
3. **HTTPS**: Use HTTPS in production
4. **Authentication**: Configure user authentication as needed

## Error Handling

The server provides detailed error messages for:
- Authentication failures (401 errors)
- Missing session cookies
- Invalid parameters
- 4D server errors

Authentication errors will prompt you to run `login` again.

## Security Notes

- Use HTTPS when sending credentials
- Prefer hashed passwords over plain text
- Limit exposed dataclasses and attributes in production
- Never log passwords or session cookies

## Testing with MCP Inspector

Use the MCP Inspector to test the server:

```bash
npm install -g @modelcontextprotocol/inspector
mcp-inspector
```

Point the inspector to your built server: `node dist/index.js`

## Client Configuration

### Claude Code

Add to your Claude Code configuration file (`~/.claude-code/config.json`):

```json
{
  "mcpServers": {
    "4d": {
      "command": "npx",
      "args": ["4d-mcp"],
      "env": {
        "FOURD_BASE": "https://your-4d-server.com:443",
        "FOURD_USER": "your-username",
        "FOURD_PASSWORD": "your-password",
        "FOURD_SESSION_MINUTES": "60",
        "FOURD_ALLOW_SELF_SIGNED": "false"
      }
    }
  }
}
```

### Cursor

Add to your Cursor settings (`Settings > Extensions > MCP > Edit in settings.json`):

```json
{
  "mcp": {
    "servers": {
      "4d": {
        "command": "npx",
        "args": ["4d-mcp"],
        "env": {
          "FOURD_BASE": "https://your-4d-server.com:443",
          "FOURD_USER": "your-username",
          "FOURD_PASSWORD": "your-password",
          "FOURD_SESSION_MINUTES": "60",
          "FOURD_ALLOW_SELF_SIGNED": "false"
        }
      }
    }
  }
}
```

### Cline (VS Code Extension)

Add to your Cline MCP settings:

```json
{
  "mcpServers": {
    "4d": {
      "command": "npx",
      "args": ["4d-mcp"],
      "env": {
        "FOURD_BASE": "https://your-4d-server.com:443",
        "FOURD_USER": "your-username",
        "FOURD_PASSWORD": "your-password",
        "FOURD_SESSION_MINUTES": "60",
        "FOURD_ALLOW_SELF_SIGNED": "false"
      }
    }
  }
}
```

### Configuration Notes

- Replace placeholder values with your actual 4D server details
- Use HTTPS in production environments
- Set `FOURD_ALLOW_SELF_SIGNED` to `"true"` only for development with self-signed certificates
- Example configuration files are available in the `examples/` directory