{"_id":"4d-mcp-tool-kit","name":"4d-mcp-tool-kit","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"4d-mcp-tool-kit","version":"1.0.0","description":"![Version](https://img.shields.io/badge/version-1.0.0-blue) ![Node.js](https://img.shields.io/badge/Node.js-18%2B-green?logo=node.js) ![License](https://img.shields.io/badge/license-ISC-blue.svg) ![Platform](https://img.shields.io/badge/platform-4D%20Data","main":"build/index.js","types":"build/index.d.ts","scripts":{"build":"tsc && cp src/manifest.json build/ && cp .env build/","test":"jest ","test:watch":"jest --watch","test:coverage":"jest --coverage","start-http-server":"node  build/start-http-server.js","start-stdio-server":"node  build/start-stdio-server.js && chmod 755 build/start-stdio-server.js","inspect":"npx @modelcontextprotocol/inspector "},"keywords":[],"author":"","license":"ISC","type":"module","dependencies":{"@modelcontextprotocol/sdk":"^1.17.1","axios":"^1.11.0","axios-cookiejar-support":"^6.0.4","dotenv":"^17.2.1","express":"^5.1.0","lodash":"^4.17.21","mcp-jest":"^1.0.12","tough-cookie":"^5.1.2","zod":"^3.25.76"},"bin":{"weather":"build/index.js"},"devDependencies":{"@babel/preset-env":"^7.28.0","@babel/preset-typescript":"^7.27.1","@jest/globals":"^30.0.5","@types/axios":"^0.9.36","@types/cors":"^2.8.19","@types/dotenv":"^6.1.1","@types/express":"^5.0.3","@types/jest":"^30.0.0","@types/lodash":"^4.17.20","@types/node":"^24.1.0","jest":"^30.0.5","jest-html-reporter":"^4.3.0","jest-junit":"^16.0.0","ts-jest":"^29.4.0","typescript":"^5.8.3"},"_id":"4d-mcp-tool-kit@1.0.0","gitHead":"85e3e2550fe310b4b8e6404d8a94729bf7d24327","_nodeVersion":"24.4.1","_npmVersion":"11.5.2","dist":{"integrity":"sha512-RL8yoXatkaZjq8gxnYW9/irSnJKQs6oTz43PZru61MLJj+1wooEMo98A206pC4Hd9lKzL12WF0ZlT1xr//MYFA==","shasum":"342ac6d70a71fe96e3089d4035254315f0524993","tarball":"https://registry.npmjs.org/4d-mcp-tool-kit/-/4d-mcp-tool-kit-1.0.0.tgz","fileCount":25,"unpackedSize":45349,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFnSGNrcTtwj9RU3SX18kcgFvwp/4Wo0wg1KFJHQJQAPAiA3EcpYoSg3yDzoqNcgtCkStD2sBL4nfgCqAyuhihf15A=="}]},"_npmUser":{"name":"yassine_mbk","email":"mohammedyassine808@gmail.com"},"directories":{},"maintainers":[{"name":"yassine_mbk","email":"mohammedyassine808@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/4d-mcp-tool-kit_1.0.0_1756561316914_0.7356921663558653"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-30T13:41:56.913Z","1.0.0":"2025-08-30T13:41:57.096Z","modified":"2025-08-30T13:41:57.366Z"},"maintainers":[{"name":"yassine_mbk","email":"mohammedyassine808@gmail.com"}],"description":"![Version](https://img.shields.io/badge/version-1.0.0-blue) ![Node.js](https://img.shields.io/badge/Node.js-18%2B-green?logo=node.js) ![License](https://img.shields.io/badge/license-ISC-blue.svg) ![Platform](https://img.shields.io/badge/platform-4D%20Data","keywords":[],"license":"ISC","readme":"# 4d-mcp-toolkit\n\n![Version](https://img.shields.io/badge/version-1.0.0-blue)\n![Node.js](https://img.shields.io/badge/Node.js-18%2B-green?logo=node.js)\n![License](https://img.shields.io/badge/license-ISC-blue.svg)\n![Platform](https://img.shields.io/badge/platform-4D%20Database-blueviolet)\n![TypeScript](https://img.shields.io/badge/TypeScript-5.8.3-blue?logo=typescript)\n![Build](https://img.shields.io/badge/build-passing-brightgreen)\n<!-- Add more badges as needed -->\n\n---\n\nA 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.\n\n---\n\n## 📑 Table of Contents\n\n- [🚀 Project Overview](#-project-overview)\n- [📁 Project Structure](#-project-structure)\n- [🛠️ Getting Started](#-getting-started)\n  - [Installation](#installation)\n  - [Configuration](#configuration)\n  - [The `manifest.json` File](#the-manifestjson-file)\n  - [Using the `parseTools` Function](#using-the-parsetools-function)\n  - [Running the Provided Examples](#running-the-provided-examples)\n- [🔬 Scripts & Development](#-scripts--development)\n- [🧩 Advanced Configuration & Customization](#-advanced-configuration--customization)\n- [📦 Example 4D Function](#-example-4d-function)\n- [🧪 Testing](#-testing)\n- [🔒 Notes](#-notes)\n- [🤝 Contributing](#-contributing)\n- [📄 License](#-license)\n\n---\n\n## 🚀 Project Overview\n\nThis 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.\n\n**Key Features:**\n- **Manifest-driven tool registration** for rapid development.\n- **Custom tool support** for advanced workflows.\n- **Express.js HTTP server** with CORS and stateless transport.\n- **Type-safe input validation** using Zod.\n- **Environment-based configuration** for secure deployments.\n- **Ready-to-run examples** for both HTTP and stdio transports.\n\n---\n\n## 📁 Project Structure\n\n```\n.\n├── .env.example\n├── .gitignore\n├── 4d-mcp-toolkit-1.0.0.tgz\n├── babel.config.cjs\n├── jest.config.js\n├── package-lock.json\n├── package.json\n├── README.md\n├── tsconfig.json\n├── tsconfig.tsbuildinfo\n├── src/\n│   ├── Client_4D.ts\n│   ├── config.ts\n│   ├── customTools.ts\n│   ├── http-server.ts\n│   ├── index.ts\n│   ├── manifest.json\n│   ├── parseTools.ts\n│   ├── start-http-server.ts\n│   ├── start-stdio-server.ts\n│   ├── stdio_server.ts\n│   ├── stdioClient.ts\n│   ├── Types.ts\n├── test/\n│   ├── Client_4D.test.ts\n│   ├── parseTools.test.ts\n```\n\n---\n\n## 🛠️ Getting Started\n\n### Installation\n\n1. **Clone the repository:**\n   ```sh\n   git clone <your-repo-url>\n   ```\n\n2. **Install dependencies:**\n   ```sh\n   npm install\n   ```\n\n3. **Build the project:**\n   ```sh\n   npm run build\n   ```\n\n### Configuration\n\n- Create a `.env` file in the project root with the following variables:\n  ```\n  BASE_URL=<your-4d-rest-api-base-url>\n  ACESS_KEY=<your-4d-access-key>\n  MCP_PORT=3000 # (optional, default: 3000)\n  ```\n\n- The [`src/config.ts`](src/config.ts) file loads these variables using `dotenv`.\n\n### The `manifest.json` File\n\nThis JSON file defines the tools (4D functions) to expose. See the [Advanced Configuration](#-advanced-configuration--customization) section for schema details.\n\n### Using the `parseTools` Function\n\nThe [`parseTools`](src/parseTools.ts) function reads your manifest, builds input schemas, and registers tools on the MCP server. It supports custom tool registration and dynamic parameter validation.\n\n```ts\nconst server = await parseTools(\n  tools,\n  new Client_4D(config.baseUrl, config.acessKey),\n  {\n    beforeReturn: customTools,\n    afterRegister: ar,\n    excludeTools: [],\n    info: { name: \"TestServer\" }\n  }\n);\n```\n\n### Running the Provided Examples\n\n- **HTTP Server (Express):**\n  ```sh\n  npm run build\n  npm start\n  ```\n  The server will listen on the port specified by `MCP_PORT` (default: 3000).\n\n- **Stdio Transport:**\n  ```sh\n  ts-node src/index_stdio.ts\n  ```\n\n---\n\n## 🔬 Scripts & Development\n\nCommon scripts (see [`package.json`](package.json)):\n\n- `npm run build` — Compile TypeScript and copy manifest and .env to build directory.\n- `npm test` — Run tests with Jest.\n- `npm run test:watch` — Run tests with Jest in watch mode.\n- `npm run test:coverage` — Run tests with coverage report.\n- `npm run start-http-server` — Start the HTTP server from the build output.\n- `npm run start-stdio-server` — Start the stdio server from the build output.\n- `npm run inspect` — Run the MCP inspector tool.\n\n---\n\n## 🧩 Advanced Configuration & Customization\n\n### Registering Custom Tools\n\nYou can register custom tools (e.g., `CheckDataStore`) in [`src/index.ts`](src/index.ts) using the MCP server API. This enables dynamic HTTP method selection and catalog inspection.\n\n### Flexible `manifest.json` Schema\n\n- **Attributes for Data Retrieval:**  \n  Specify which attributes to retrieve for each table to optimize performance.\n  ```json\n  {\n    \"name\": \"vectorSearch\",\n    \"attributes\": {\n      \"TableName\": [\"attribute1\", \"attribute2\"]\n    }\n  }\n  ```\n\n- **Enums for Parameter Control:**  \n  Restrict parameters to predefined values.\n  ```json\n  {\n    \"name\": \"TableName\",\n    \"type\": \"string\",\n    \"enum\": [\"users\", \"Employee\"],\n    \"description\": \"The name of the table to perform the search on.\"\n  }\n  ```\n\n- **Dynamic Parameters with `enumMap` and `dependsOn`:**  \n  Make parameter options depend on other parameter values.\n  ```json\n  {\n    \"name\": \"EmbeddingKey\",\n    \"type\": \"string\",\n    \"dependsOn\": \"TableName\",\n    \"enumMap\": {\n      \"users\": [\"vector\"],\n      \"Employee\": [\"vector\", \"embedding\"]\n    },\n    \"description\": \"The name of the vector/embedding column to use for the search. The valid options depend on the selected TableName.\"\n  }\n  ```\n\n---\n\n## 📦 Example 4D Function\n\nBelow 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.\n\n```4d\n// Exposed as a DataStore method, for example, by extending the DataStore Class\n#DECLARE($querry : Text; $maxResults : Integer; $TableName : Text; $embeddingKey : Text; $similarity : Text)->$similarities : cs.EntitySelection\n\n// initialisation de openai embeddings\nvar $client:=cs.AIKit.OpenAI.new(\"YOUR_OPEN_API_API_KEY\")\nvar $result:=$client.embeddings.create($querry; \"text-embedding-3-large\"; cs.AIKit.OpenAIEmbeddingsParameters.new({dimensions: 1536}))\nvar $vector : 4D.Vector:=$result.vector\n\n\n\n// Récupération des données : \n\n$entries:=ds[$TableName].all()\n\n// Création du vecteur de recherche\nvar $SearchVector : 4D.Vector\n$SearchVector:=$vector\n\n// Initialisation de la collection des similarités\n$similarities:=ds[$tableName].newSelection()\n\n// Déclaration des variables\nvar $entry : cs.Entity\nvar $VectorField : 4D.Vector\nvar $cs : Real\nvar $csArray:=[]\nvar $item : Object\n\n// Boucle sur chaque employé\nFor each ($entry; $entries)\n\t\n\t$VectorField:=$entry[$embeddingKey]\n\t\n\tCase of \n\t\t: ($similarity=\"cosineSimilarity\")\n\t\t\t$cs:=$VectorField.cosineSimilarity($SearchVector)\n\t\t: ($similarity=\"dotSimilarity\")\n\t\t\t$cs:=$VectorField.dotSimilarity($SearchVector)\n\t\t: ($similarity=\"euclideanDistance\")\n\t\t\t$cs:=$VectorField.euclideanDistance($SearchVector)\n\t\t\t\n\tEnd case \n\t\n\t$csArray.push(New object(\"similarity\"; $cs; \"key\"; $entry.getKey())\nEnd for each \n\n\n\nvar $output:=[]\n\nCase of \n\t: ($similarity=\"euclideanDistance\")\n\t\t$csArray:=$csArray.orderBy(\"similarity asc\")\n\tElse \n\t\t$csArray:=$csArray.orderBy(\"similarity desc\")\nEnd case \n\n$csArray:=$csArray.slice(0; $maxResults)\n\nFor each ($item; $csArray)\n\t$similarities.add(ds[$tableName].get($item.key))\nEnd for each \n\n```\n\n---\n\n## 🧪 Testing\n\n- Tests are written using [Jest](https://jestjs.io/).\n- Test files are located in the [`test/`](test/) directory.\n- To run all tests:\n  ```sh\n  npm test\n  ```\n- To run with coverage:\n  ```sh\n  npm run test:coverage\n  ```\n\n---\n\n## 🔒 Notes\n\n- Ensure your 4D database REST API is accessible and the access key is set.\n- The project uses strict TypeScript settings for reliability.\n- For more details, see the code and comments in [`src/index.ts`](src/index.ts) and [`src/parseTools.ts`](src/parseTools.ts).\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please open issues or submit pull requests for improvements and bug fixes.\n\n---\n\n## 📄 License\n\nThis project is licensed under the ISC License. See the [LICENSE](LICENSE) file for details.\n\n---\n","readmeFilename":"README.md","_rev":"1-1439d1661c8265b62cf0c1b426694947"}