Installation Methods

This page describes the three methods for installing the simap-mcp server: using npx for on-demand execution, installing globally via npm, or building from source. For instructions on configuring specific clients like Claude Desktop, see Configuring for Claude

Prerequisites

The simap-mcp server requires Node.js version 22 or higher (LTS or newer) package.json47-49 This requirement was bumped from version 20 in v1.3.0 package-lock.json30-31 as Node 20 reached its end-of-life on 2026-04-30. This constraint is enforced via the engines field in the package configuration package.json47-49 The project is built using TypeScript ^6.0.3 package.json65 and relies on the @modelcontextprotocol/sdk for its server implementation package.json55

Verify your local environment:

Sources: package.json47-49 package.json55-65 package-lock.json30-31 README.md34-38

Installation Method Comparison

The project supports three distribution and execution paths, allowing users to choose based on their need for stability versus customization.

Method	Command	Updates	Best For
npx	npx -y @digilac/simap-mcp	Automatic (latest)	Quick setup, standard users
Global Install	npm install -g @digilac/simap-mcp	Manual (npm update -g)	Production stability
Build from Source	npm run build	Manual (git pull)	Development, local forks

Sources: package.json1-69 README.md40-225

Method 1: npx (Recommended)

The npx method is the recommended approach for most users as it avoids global dependency pollution and ensures the latest version is used README.md42-43 The command executes the binary defined in the bin field of package.json, which points to the compiled entry point dist/index.js package.json8-10

npx Execution Flow

This diagram shows how the natural language request to "install" via npx maps to the resolution of code entities in the npm registry.

Sources: package.json2-10 README.md42-60

Method 2: Global npm Install

Global installation places the @digilac/simap-mcp package in the system's global node_modules and creates a symlink for the simap-mcp command in the system PATH package.json8-10 This is useful for environments where network access is restricted or where a specific version must be pinned.

The package distribution is optimized by including only the dist directory in the final npm artifact via the files array package.json33-35

Global Path Mapping

This diagram bridges the system-level command name to the internal entry point used by the MCP SDK.

Sources: package.json8-10 package.json33-35 README.md182-200

Method 3: Build from Source

Building from source is required for development or for using the server in environments where npm registry access is unavailable but git is allowed.

Build Process Implementation

The npm run build script invokes the tsc (TypeScript Compiler) package.json12 The prepublishOnly hook ensures that the build is always refreshed before any package distribution occurs package.json27 Development dependencies like vitest are used to verify the build before deployment package.json67

Sources: package.json11-27 package.json67 README.md202-225

Verification and Diagnostics

Once installed via any method, the server operates as a stateless JSON-RPC service over stdio.

Execution Verification

The server will remain silent upon start as it awaits a standard MCP initialization handshake from a client. If the process exits immediately with an error, check the following:

Issue	Cause	Resolution
Unsupported engine	Node.js version < 22	Upgrade Node.js package.json47-49
Cannot find module 'dist/index.js'	Missing build artifacts	Run npm run build package.json12
Permission denied	Global install restricted	Use sudo or npx README.md42

For troubleshooting, the SIMAP_MCP_DEBUG environment variable can be set to 1 or true to enable verbose logging to stderr.

Sources: package.json12-49 README.md34-40