4d-mcp-toolkit

A robust, flexible solution for exposing and registering your 4D database functions as tools for a MCP server. Eliminate manual, verbose code with a simple JSON manifest file—streamlining your development workflow.

📑 Table of Contents

• 🚀 Project Overview
• 📁 Project Structure
• 🛠️ Getting Started
  • Installation
  • Configuration
  • The manifest.json File
  • Using the parseTools Function
  • Running the Provided Examples
• 🔬 Scripts & Development
• 🧩 Advanced Configuration & Customization
• 📦 Example 4D Function
• 🧪 Testing
• 🔒 Notes
• 🤝 Contributing
• 📄 License

🚀 Project Overview

This project provides a modern, extensible MCP server for 4D databases, allowing you to expose your 4D functions as tools via a manifest-driven approach. The core logic is built in TypeScript and leverages the Model Context Protocol SDK for robust server and transport handling.

Key Features:

• Manifest-driven tool registration for rapid development.
• Custom tool support for advanced workflows.
• Express.js HTTP server with CORS and stateless transport.
• Type-safe input validation using Zod.
• Environment-based configuration for secure deployments.
• Ready-to-run examples for both HTTP and stdio transports.

📁 Project Structure

.
├── .env.example
├── .gitignore
├── 4d-mcp-toolkit-1.0.0.tgz
├── babel.config.cjs
├── jest.config.js
├── package-lock.json
├── package.json
├── README.md
├── tsconfig.json
├── tsconfig.tsbuildinfo
├── src/
│   ├── Client_4D.ts
│   ├── config.ts
│   ├── customTools.ts
│   ├── http-server.ts
│   ├── index.ts
│   ├── manifest.json
│   ├── parseTools.ts
│   ├── start-http-server.ts
│   ├── start-stdio-server.ts
│   ├── stdio_server.ts
│   ├── stdioClient.ts
│   ├── Types.ts
├── test/
│   ├── Client_4D.test.ts
│   ├── parseTools.test.ts

🛠️ Getting Started

Installation

1. Clone the repository:

   git clone <your-repo-url>

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Configuration

• Create a .env file in the project root with the following variables:

  BASE_URL=<your-4d-rest-api-base-url>
  ACESS_KEY=<your-4d-access-key>
  MCP_PORT=3000 # (optional, default: 3000)

• The src/config.ts file loads these variables using dotenv.

The manifest.json File

This JSON file defines the tools (4D functions) to expose. See the Advanced Configuration section for schema details.

Using the parseTools Function

The parseTools function reads your manifest, builds input schemas, and registers tools on the MCP server. It supports custom tool registration and dynamic parameter validation.

const server = await parseTools(
  tools,
  new Client_4D(config.baseUrl, config.acessKey),
  {
    beforeReturn: customTools,
    afterRegister: ar,
    excludeTools: [],
    info: { name: "TestServer" }
  }
);

Running the Provided Examples

• HTTP Server (Express):

  npm run build
  npm start

  The server will listen on the port specified by MCP_PORT (default: 3000).

• Stdio Transport:

  ts-node src/index_stdio.ts

🔬 Scripts & Development

Common scripts (see package.json):

• npm run build — Compile TypeScript and copy manifest and .env to build directory.
• npm test — Run tests with Jest.
• npm run test:watch — Run tests with Jest in watch mode.
• npm run test:coverage — Run tests with coverage report.
• npm run start-http-server — Start the HTTP server from the build output.
• npm run start-stdio-server — Start the stdio server from the build output.
• npm run inspect — Run the MCP inspector tool.

🧩 Advanced Configuration & Customization

Registering Custom Tools

You can register custom tools (e.g., CheckDataStore) in src/index.ts using the MCP server API. This enables dynamic HTTP method selection and catalog inspection.

Flexible manifest.json Schema

• Attributes for Data Retrieval:
  Specify which attributes to retrieve for each table to optimize performance.

  {
    "name": "vectorSearch",
    "attributes": {
      "TableName": ["attribute1", "attribute2"]
    }
  }

• Enums for Parameter Control:
  Restrict parameters to predefined values.

  {
    "name": "TableName",
    "type": "string",
    "enum": ["users", "Employee"],
    "description": "The name of the table to perform the search on."
  }

• Dynamic Parameters with enumMap and dependsOn:
  Make parameter options depend on other parameter values.

  {
    "name": "EmbeddingKey",
    "type": "string",
    "dependsOn": "TableName",
    "enumMap": {
      "users": ["vector"],
      "Employee": ["vector", "embedding"]
    },
    "description": "The name of the vector/embedding column to use for the search. The valid options depend on the selected TableName."
  }

📦 Example 4D Function

Below is an example of a 4D function designed for vector search that can be exposed on the REST API. This function must be exposed as a DataStore method.

// Exposed as a DataStore method, for example, by extending the DataStore Class
#DECLARE($querry : Text; $maxResults : Integer; $TableName : Text; $embeddingKey : Text; $similarity : Text)->$similarities : cs.EntitySelection

// initialisation de openai embeddings
var $client:=cs.AIKit.OpenAI.new("YOUR_OPEN_API_API_KEY")
var $result:=$client.embeddings.create($querry; "text-embedding-3-large"; cs.AIKit.OpenAIEmbeddingsParameters.new({dimensions: 1536}))
var $vector : 4D.Vector:=$result.vector



// Récupération des données : 

$entries:=ds[$TableName].all()

// Création du vecteur de recherche
var $SearchVector : 4D.Vector
$SearchVector:=$vector

// Initialisation de la collection des similarités
$similarities:=ds[$tableName].newSelection()

// Déclaration des variables
var $entry : cs.Entity
var $VectorField : 4D.Vector
var $cs : Real
var $csArray:=[]
var $item : Object

// Boucle sur chaque employé
For each ($entry; $entries)
	
	$VectorField:=$entry[$embeddingKey]
	
	Case of 
		: ($similarity="cosineSimilarity")
			$cs:=$VectorField.cosineSimilarity($SearchVector)
		: ($similarity="dotSimilarity")
			$cs:=$VectorField.dotSimilarity($SearchVector)
		: ($similarity="euclideanDistance")
			$cs:=$VectorField.euclideanDistance($SearchVector)
			
	End case 
	
	$csArray.push(New object("similarity"; $cs; "key"; $entry.getKey())
End for each 



var $output:=[]

Case of 
	: ($similarity="euclideanDistance")
		$csArray:=$csArray.orderBy("similarity asc")
	Else 
		$csArray:=$csArray.orderBy("similarity desc")
End case 

$csArray:=$csArray.slice(0; $maxResults)

For each ($item; $csArray)
	$similarities.add(ds[$tableName].get($item.key))
End for each 

🧪 Testing

• Tests are written using Jest.
• Test files are located in the test/ directory.
• To run all tests:

  npm test

• To run with coverage:

  npm run test:coverage

🔒 Notes

• Ensure your 4D database REST API is accessible and the access key is set.
• The project uses strict TypeScript settings for reliability.
• For more details, see the code and comments in src/index.ts and src/parseTools.ts.

🤝 Contributing

Contributions are welcome! Please open issues or submit pull requests for improvements and bug fixes.

📄 License

This project is licensed under the ISC License. See the LICENSE file for details.