4d-mcp

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:

git clone <repository-url>
cd 4d-mcp
npm install

1. Configure environment variables:

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 ``

1. Build the project:

npm run build

Usage

Development

npm run dev

Production

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:

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):

{
  "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):

{
  "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:

{
  "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