Sys8 MCP Server

Sys8 is a comprehensive Model Context Protocol (MCP) server that provides system information and developer utilities: date/time, OS version, math calculations, random data generation (UUID, hex, base64), hashing, text formatting, data validation (including JSON), encoding/decoding, and more.

Features

System Information

• Get Current DateTime: Get the current date and time in all available formats (UTC, date string, time string, datetime string, Unix timestamps, human-readable formats)

• Get OS Version: Retrieve operating system version, platform information, and current user information

Calculations & Security

• Calculate Math Expression: Safely evaluate mathematical expressions

• Generate Random: Generate random data (UUID v4, hex strings, base64 strings, or raw bytes)

• Hash String: Generate hashes for strings (useful for .env file keys)

Developer Utilities (New in v0.4.0)

• Encode/Decode Base64: Encode and decode strings to/from Base64 format

• Encode/Decode URL: URL encoding and decoding for query strings and paths

• Format Text Case: Convert text to different case formats (camelCase, PascalCase, kebab-case, snake_case, CONSTANT_CASE, Title Case, lowercase, UPPERCASE)

• Generate Slug: Generate URL-friendly slugs from text

• Validate Data: Validate data against various formats (email, url, ipv4, ipv6, domain, phone, credit-card, uuid, hex, base64, json)

• Format JSON: Format, validate, minify, or prettify JSON strings

• Generate Password: Generate secure passwords with customizable options (length, character types, exclude similar)

• Format Bytes: Format bytes to human-readable format (binary or decimal)

• Format Number: Format numbers (currency, percentage, thousands separator, decimal)

• Convert Color: Convert between color formats (hex, RGB, HSL)

• Convert Timezone: Convert datetime between timezones

• Analyze Logs: Analyze text for errors and warnings in logs (compilation, npm, Docker, runtime, etc.)

• Analyze Language: Analyze text for language distribution and character types (English, Chinese, Russian, Ukrainian, Vietnamese, Japanese, Turkish, Spanish, digits, punctuation, symbols)

Why MCP? Project Philosophy

Why Use MCP Instead of LLM Agents?

This MCP server provides deterministic, reliable system utilities that should never be delegated to AI agents. Here's why:

🎯 Accuracy & Reliability

• AI agents make mistakes: LLMs frequently hallucinate, miscalculate, and produce inconsistent results when handling mathematical operations, date/time conversions, or data validation

• Deterministic algorithms: These functions use proven, tested algorithms that always produce correct results

• No ambiguity: System information, calculations, and validations require precision that AI cannot guarantee

💰 Cost Efficiency

• Token savings: Instead of sending complex calculations or validation logic to expensive LLM APIs, execute them locally via MCP

• Reduced API calls: One MCP tool call replaces multiple LLM reasoning steps

• Faster responses: Direct function execution is orders of magnitude faster than LLM processing

🔒 Security & Privacy

• Local execution: Sensitive operations (hashing, password generation) run locally, not in cloud LLM services

• No data leakage: System information, calculations, and validations stay on your machine

• Auditable code: You can review and verify the exact algorithms being used

⚡ Performance

• Instant results: Mathematical calculations, date/time operations, and validations execute in milliseconds

• No network latency: All operations run locally without API round-trips

• Scalable: Handle thousands of operations per second without rate limits

✅ Best Practices

• Separation of concerns: Let AI handle reasoning and creativity; let algorithms handle computation and validation

• Right tool for the job: Use deterministic functions for deterministic tasks

• Reliability: Critical operations (UUID generation, password hashing, data validation) must be 100% reliable

Example: Instead of asking an LLM "What's the current time in UTC?", use get_current_datetime - it's faster, cheaper, and always accurate.

Prerequisites

System Requirements

For Local Installation

• Node.js >= 24.0.0 (required)

  • Used for: All server functionality, UUID generation (via crypto module), date/time operations

• npm or compatible package manager (required)

  • Used for: Installing dependencies and building the project

• openssl (required for generate_random with hex/base64/bytes types)

  • Usually pre-installed on macOS and Linux

  • Windows: Install via OpenSSL for Windows or use WSL

  • Used for: Cryptographically secure random string generation

  • Note: UUID generation via generate_random with type: 'uuid' does NOT require openssl (uses Node.js crypto.randomUUID())

For Docker Installation

• Docker (required)

  • The Dockerfile automatically installs openssl in the container

  • Base image: node:lts (includes Node.js and npm)

  • Production image: node:lts-slim with openssl installed

NPM Dependencies

The following packages are automatically installed via npm install:

• @modelcontextprotocol/sdk (v0.6.0)

  • Required for: MCP protocol implementation, server/client communication

• expr-eval (v2.0.2)

  • Required for: Safe mathematical expression evaluation in calculate_math_expression

  • Provides: Secure expression parsing without eval() security risks

System Libraries Used

• Node.js Built-in Modules (no installation needed):

  • crypto - UUID generation, hashing (hash_string)

  • os - OS information (get_os_version)

  • util - Promise utilities for async operations

  • child_process - Executing openssl commands

  • Buffer - Base64 encoding/decoding, binary operations

• System Commands:

  • openssl - Random string generation (hex, base64, bytes)

    • Command: openssl rand --hex <length>

    • Command: openssl rand <length> | openssl base64

Installation

Local Installation

1. Navigate to the sys8 directory:

2. Install dependencies:

3. Build the server:

Quick Start: MCP Configuration

After cloning and building the repository, configure sys8 in your MCP client.

Option 1: Local Installation (Recommended)

Example for macOS/Linux:

Example for Windows:

Option 2: Relative Path (Project-Specific Configuration)

If sys8 is located in your project:

Complete Configuration Examples

For detailed installation and configuration instructions for all MCP clients (Cursor AI, Claude Desktop, Windsurf, Docker), see the Complete Installation Guide.

Docker Installation

The sys8 MCP server is containerized and can be run using Docker.

Docker Dependencies (automatically installed in container):

• Node.js LTS (from node:lts base image)

• openssl (installed via apt-get install openssl in production stage)

• All npm dependencies from package.json

Building the Docker Image

Running the Container

The sys8 MCP server uses stdio protocol for communication, so it should be run interactively:

Using with Docker Desktop MCP Toolkit

The sys8 server is designed to be used with Docker Desktop MCP Toolkit. After building the image, you can configure it in Docker Desktop's MCP settings.

Note: For production use in Docker Registry, the server will be available through Docker Desktop MCP Toolkit after publication.

Viewing Docker Logs

The MCP server outputs detailed logs to stderr (standard error), which allows you to monitor all MCP operations in Docker. Here's how to view them:

Option 1: Run container and see logs directly

Option 2: Run container in detached mode (for production)

⚠️ Common Issue: Empty Logs

If docker logs sys8-server shows nothing, it means the container was started with a different command (like sleep infinity) instead of running the MCP server.

Solution:

To check if server is running:

Option 2: Run container and see logs immediately

Option 3: Test MCP methods and see logs

Log Format: All logs are prefixed with timestamps and log levels:

What gets logged:

• Server startup information (version, transport)

• ListTools requests (when client requests available tools)

• All tool calls (name, arguments, success/failure status)

• Errors (with detailed error messages)

Note: When the server is used via MCP client (like Cursor AI), logs are automatically visible in the client's output. For Docker containers running in detached mode, use docker logs to view them.

Usage

Available Tools

1. get_current_datetime

Get the current date and time in all available formats.

Parameters: None

Example:

Response:

Response Fields:

• utc: ISO 8601 UTC datetime string

• date: Date string in YYYY-MM-DD format

• time: Time string in HH:mm:ss format

• datetime: Combined date and time string

• unix_timestamp_seconds: Unix timestamp in seconds

• unix_timestamp_milliseconds: Unix timestamp in milliseconds

• human_readable_utc0: Human-readable format in UTC+0 (DD/MM/YYYY, HH:MM:SS)

• human_readable_utc2: Human-readable format in UTC+2 (DD/MM/YYYY, HH:MM:SS)

• human_readable_utc3: Human-readable format in UTC+3 (DD/MM/YYYY, HH:MM:SS)

2. get_os_version

Get the operating system version, platform information, and current user information.

Parameters: None

Example:

Response:

Response Fields:

• platform: Platform identifier (darwin, win32, linux)

• release: OS release version

• architecture: CPU architecture

• type: OS type

• hostname: System hostname

• username: Current user name

• homedir: User home directory

• platformName: Human-readable platform name (macOS, Windows, Linux)

• uid: User ID (Unix systems only)

• gid: Group ID (Unix systems only)

3. calculate_math_expression

Calculate a mathematical expression safely.

Parameters:

• expression (required, string): Mathematical expression to evaluate (e.g., "2 + 2", "(10 + 5) * 3 / 2", "sqrt(16)")

Supported Operations:

• Arithmetic: +, -, *, /, % (modulo), ^ (power)

• Functions: abs, ceil, floor, round, max, min, sqrt, sin, cos, tan, asin, acos, atan, log, exp

• Constants: PI, E

• Parentheses: Full support for grouping expressions

• Precedence: Standard mathematical operator precedence

Example:

Response:

More Examples:

• Simple arithmetic: "2 + 2" → 4

• Complex expression: "(10 + 5) * 3 / 2" → 22.5

• Decimal operations: "3.14 * 2" → 6.28

• Negative numbers: "-5 + 3" → -2

• Functions: "sqrt(16)" → 4, "sin(PI/2)" → 1

• Power: "2^3" → 8

Error Handling:

• Invalid syntax: Returns error with clear message

• Division by zero: Returns error "Division by zero is not allowed"

• Empty expression: Returns error "Expression cannot be empty or whitespace-only"

• Invalid operations: Returns error with description

4. generate_random

Generate random data: UUID v4, hex strings, base64 strings, or raw bytes.

Parameters:

• type (string, required): Type of random data - 'uuid' | 'hex' | 'base64' | 'bytes'

• length (number, optional): Length in bytes for hex/base64/bytes (8-128, default: generates all standard lengths)

• format (string, optional): Format for UUID only - 'standard' | 'uppercase' | 'without-dashes' (default: returns all formats)

Example (UUID):

Response (UUID):

Example (Hex - all lengths):

Response (Hex - all lengths):

Example (Base64 - specific length):

Response (Base64 - specific length):

Note:

• UUID generation uses Node.js crypto and doesn't require openssl

• Hex, base64, and bytes generation require openssl to be installed

• If openssl is not available, hex/base64/bytes generation will return an error

5. hash_string

Generate hash for a string (useful for .env file keys).

Parameters:

• input (required, string): String to hash

Example:

Response:

Response Fields:

• input: Original input string

• sha256_hex: SHA256 hash in hexadecimal format (64 characters)

• sha256_base64: SHA256 hash in base64 format

• sha512_hex: SHA512 hash in hexadecimal format (128 characters)

• sha512_base64: SHA512 hash in base64 format

Error Handling:

• Empty input: Returns error "Input string cannot be empty or whitespace-only"

6. analyze_logs

Analyze text for errors and warnings in logs. Detects common error patterns including compilation errors, npm errors, Docker errors, runtime errors, and warnings.

Parameters:

• text (required, string): Text content to analyze for errors and warnings

Example:

Response:

Response Fields:

• error_count: Number of errors found in the text

• warning_count: Number of warnings found in the text

• errors: Array of error objects with:

  • line: Line number where error was found

  • message: Error message (truncated to 200 characters)

  • type: Error type (compilation, npm, docker, runtime, etc.)

• warnings: Array of warning objects with:

  • line: Line number where warning was found

  • message: Warning message (truncated to 200 characters)

  • type: Warning type (npm, deprecated, security, etc.)

Detected Error Types:

• Compilation errors (TypeScript, syntax, type errors)

• npm errors (EACCES, ENOENT, installation failures)

• Docker errors (build failures, image not found, container errors)

• Runtime errors (exceptions, fatal errors, stack overflow)

• Network errors (connection refused, timeout, HTTP errors)

• File system errors (ENOENT, EACCES, permission denied)

• Database errors (SQL errors, connection failures)

• Authentication errors (unauthorized, invalid token)

Detected Warning Types:

• npm warnings (deprecated packages, peer dependencies)

• Compilation warnings (unused variables, type safety)

• Docker warnings

• Security warnings (vulnerabilities, insecure configurations)

• Performance warnings (slow queries, memory leaks)

• Deprecated API warnings

Error Handling:

• Empty text: Returns zero counts and empty arrays

7. analyze_language

Analyze text for language distribution and character types. Detects characters from multiple languages (English, Chinese, Russian, Ukrainian, Vietnamese, Japanese, Turkish, Spanish) and categorizes other characters (digits, punctuation, symbols, whitespace).

Parameters:

• text (required, string): Text content to analyze for language and character distribution

Example:

Response:

Response Fields:

• total_characters: Total number of characters in the text

• encoding: Detected encoding (UTF-8, UTF-16, etc.) if determinable

• languages: Object with language-specific counts and percentages:

  • english: English letters (A-Z, a-z)

  • chinese: Chinese characters (CJK Unified Ideographs)

  • russian: Russian Cyrillic characters

  • ukrainian: Ukrainian Cyrillic characters (distinguished by specific characters like і, ї, є)

  • vietnamese: Vietnamese Latin characters with diacritics

  • japanese: Japanese characters (Hiragana, Katakana, Kanji)

  • turkish: Turkish Latin characters with specific characters (İ, ı, Ş, ş, Ğ, ğ, Ç, ç, Ö, ö, Ü, ü)

  • spanish: Spanish Latin characters with specific characters (á, é, í, ó, ú, ñ, ü)

• categories: Object with character category counts and percentages:

  • digits: Numeric digits (0-9)

  • punctuation: Punctuation marks

  • symbols: Mathematical and other symbols

  • whitespace: Whitespace characters (spaces, tabs, newlines)

  • other: Unclassified characters

Language Detection:

• Uses Unicode ranges to identify characters from different languages

• Distinguishes between Russian and Ukrainian by detecting Ukrainian-specific characters (і, ї, є)

• Detects language-specific characters for Vietnamese, Turkish, and Spanish

• Percentages are calculated with 2 decimal places precision

Encoding Detection:

• Attempts to detect encoding (UTF-8, UTF-16, UTF-8 BOM, etc.)

• Uses heuristics based on BOM markers and character patterns

• Returns encoding information if determinable, otherwise may be undefined

Error Handling:

• Empty text: Returns zero counts and percentages for all languages and categories

8. encode_base64

Encode string to Base64 format.

Parameters:

• input (required, string): String to encode

• encoding (optional, string): Input encoding - utf8, hex, or binary (default: utf8)

Example:

Response:

9. decode_base64

Decode Base64 string.

Parameters:

• input (required, string): Base64 string to decode

• encoding (optional, string): Output encoding - utf8, hex, or binary (default: utf8)

Example:

Response:

10. encode_url

Encode string for URL (URL encoding).

Parameters:

• input (required, string): String to encode

• component (optional, string): Component type - full, path, or query (default: full)

Example:

Response:

11. decode_url

Decode URL-encoded string.

Parameters:

• input (required, string): URL-encoded string to decode

• component (optional, string): Component type - full, path, or query (default: full)

Example:

Response:

12. format_text_case

Convert text to different case formats.

Parameters:

• input (required, string): Text to convert

• format (optional, string): Target format - camelCase, PascalCase, kebab-case, snake_case, CONSTANT_CASE, Title Case, lowercase, or UPPERCASE (if omitted, returns all formats)

Example:

Response:

13. generate_slug

Generate URL-friendly slug from text.

Parameters:

• input (required, string): Text to convert to slug

• separator (optional, string): Separator character (default: -)

• lowercase (optional, boolean): Convert to lowercase (default: true)

Example:

Response:

14. validate_data

Validate data against various formats.

Parameters:

• input (required, string): Data to validate

• type (required, string): Validation type - email, url, ipv4, ipv6, domain, phone, credit-card, uuid, hex, base64, or json

Example:

Response:

Supported Validation Types:

• email: Email address validation

• url: URL validation (must start with http:// or https://)

• ipv4: IPv4 address validation

• ipv6: IPv6 address validation

• domain: Domain name validation

• phone: Phone number validation (international format)

• credit-card: Credit card number validation (13-19 digits)

• uuid: UUID v4 validation

• hex: Hexadecimal string validation

• base64: Base64 string validation

• json: JSON string validation (parsing)

15. format_json

Format, validate, minify, or prettify JSON.

Parameters:

• input (required, string): JSON string to process

• action (required, string): Action to perform - format, validate, minify, or prettify

• indent (optional, number): Number of spaces for indentation (0-10, default: 2)

Example:

Response:

Actions:

• validate: Validate JSON and return formatted version

• format: Format JSON with specified indentation

• prettify: Same as format (pretty print)

• minify: Remove all whitespace from JSON

16. generate_password

Generate secure passwords with customizable options.

Parameters:

• length (optional, number): Password length (8-128, default: 16)

• include_uppercase (optional, boolean): Include uppercase letters (default: true)

• include_lowercase (optional, boolean): Include lowercase letters (default: true)

• include_numbers (optional, boolean): Include numbers (default: true)

• include_symbols (optional, boolean): Include symbols (default: true)

• exclude_similar (optional, boolean): Exclude similar characters (il1Lo0O) (default: false)

Example:

Response:

Password Strength Levels:

• weak: Low entropy (< 50)

• medium: Medium entropy (50-70)

• strong: High entropy (70-90)

• very-strong: Very high entropy (> 90)

17. format_bytes

Format bytes to human-readable format.

Parameters:

• bytes (required, number): Number of bytes to format

• format (optional, string): Format type - binary (1024-based) or decimal (1000-based) (default: binary)

• precision (optional, number): Number of decimal places (0-10, default: 2)

Example:

Response:

18. format_number

Format numbers (currency, percentage, thousands separator, decimal).

Parameters:

• number (required, number): Number to format

• format (required, string): Format type - currency, percentage, thousands, or decimal

• locale (optional, string): Locale (default: en-US)

• currency (optional, string): Currency code for currency format (default: USD)

• minimum_fraction_digits (optional, number): Minimum fraction digits (0-20)

• maximum_fraction_digits (optional, number): Maximum fraction digits (0-20)

Example:

Response:

Format Types:

• currency: Format as currency (e.g., $1,234.56)

• percentage: Format as percentage (e.g., 12.34%)

• thousands: Format with thousands separator (e.g., 1,234.56)

• decimal: Format with decimal point (e.g., 1234.56)

19. convert_color

Convert between color formats (hex, RGB, HSL).

Parameters:

• input (required, string): Color value to convert

• from (required, string): Source color format - hex, rgb, or hsl

• to (required, string): Target color format - hex, rgb, or hsl

Example:

Response:

Note: Returns all formats (hex, RGB, HSL) regardless of requested conversion for convenience.

20. convert_timezone

Convert datetime between timezones.

Parameters:

• datetime (required, string): Datetime string to convert

• from_timezone (optional, string): Source timezone (default: UTC)

• to_timezone (required, string): Target timezone

• format (optional, string): Output format (optional)

Example:

Response:

Installation & Configuration

Quick Start

Choose your environment below for installation instructions:

• Cursor AI - Recommended for AI-powered code editing

• Claude Desktop - For Anthropic's Claude Desktop app

• Windsurf - For Windsurf IDE

• Standalone/CLI - Run as standalone server or CLI tool

Cursor AI

Global Configuration (All Users and Projects) - Recommended

To configure this MCP server for use in Cursor AI globally (for all users and projects), you need to add it to the global MCP configuration file.

Option 1: Using tsx (Recommended for Development)

This approach runs TypeScript directly without compilation, similar to other MCP servers. It's more convenient during development.

macOS/Linux:

1. Create or edit the global MCP configuration file:

Or alternatively:

2. Add the following configuration:

Windows:

Important: Replace the path with the absolute path to your src/index.ts file.

Option 2: Using Compiled JavaScript (Production)

This approach uses the compiled JavaScript file. Requires running npm run build after code changes.

macOS/Linux:

1. Create or edit the global MCP configuration file:

2. Add the following configuration:

Important: Replace /Users/ug/code/AI/mcp/sys8/build/index.js with the absolute path to your build/index.js file.

Linux

1. Create or edit the global MCP configuration file:

Or alternatively:

2. Add the configuration as shown above for macOS.

Windows

1. Create or edit the global MCP configuration file:

Or alternatively:

2. Add the following configuration (use Windows path format):

Note: Use double backslashes (\\) or forward slashes (/) in Windows paths.

Project-Specific Configuration

If you prefer to configure it per-project, create or edit .cursor/mcp.json file in your project root:

Example: If your project is at /Users/ug/code/AI/mcp, you can use:

Alternative: Using npm link (For Development)

If you want to use the server from anywhere without specifying the full path:

1. In the sys8 directory:

2. Then in the configuration, use:

Verifying Configuration

After adding the configuration:

1. Restart Cursor AI

2. The MCP server should be automatically loaded

3. You can verify it's working by using the tools in Cursor AI chat

Example Configuration File

See cursor-mcp-config-example.json in this directory for a complete example configuration.

Testing

Automated Tests

Run the automated test suite to verify all functions:

This will test all 20 tools:

• get_current_datetime - all available formats

• get_os_version - OS information and user details

• calculate_math_expression - simple arithmetic, complex expressions, functions, and error cases

• hash_string - SHA256 and SHA512 hashes in hex and base64 formats

• generate_random - UUID v4, hex strings, base64 strings, or raw bytes generation

• encode_base64 / decode_base64 - Base64 encoding/decoding

• encode_url / decode_url - URL encoding/decoding

• format_text_case - text case conversion (camelCase, kebab-case, etc.)

• generate_slug - URL-friendly slug generation

• validate_data - data validation (email, URL, IP, JSON, etc.)

• format_json - JSON formatting, validation, and minification

• generate_password - secure password generation with customizable options

• format_bytes - bytes formatting to human-readable format (binary/decimal)

• format_number - number formatting (currency, percentage, thousands, decimal)

• convert_color - color conversion (hex, RGB, HSL)

• convert_timezone - timezone conversion

• analyze_logs - analyze text for errors and warnings in logs

• analyze_language - analyze text for language distribution and character types

• analyze_language - analyze text for language distribution and character types

MCP Inspector

Test the server interactively using the MCP Inspector:

This opens an interactive interface where you can test each tool manually.

Manual Testing

You can also run the server directly:

Or using tsx:

Development

• Watch mode: npm run watch - Automatically rebuilds on file changes

• Build: npm run build - Compiles TypeScript to JavaScript

• Inspector: npm run inspector - Runs MCP Inspector for testing

Limitations & Requirements

System Dependencies

• openssl: Required for generate_random with type: 'hex', type: 'base64', or type: 'bytes'

  • Must be installed and accessible in system PATH

  • Usually pre-installed on macOS and Linux

  • Windows: Install separately or use WSL

  • UUID generation (generate_random with type: 'uuid') does NOT require openssl (uses Node.js crypto.randomUUID())

• Node.js >= 24.0.0: Required for all functionality

  • Provides built-in crypto module for UUID and hashing

  • Provides os module for system information

  • Provides Buffer for encoding/decoding operations

Functional Limitations

• OS version information: Based on Node.js os module capabilities (may vary by platform)

• Date/time information:

  • get_current_datetime returns all formats in UTC timezone

  • Uses system timezone settings for conversions

• Mathematical expressions: Limited to operations supported by expr-eval library

  • Supports: arithmetic, trigonometry, logarithms, power operations

  • Does NOT support: complex numbers, matrix operations, symbolic math

  • Security: Uses safe parser configuration to prevent code injection (no variables, logical operators, or comparison operators)

• Hashing algorithms: Only SHA256 and SHA512 available (via hash_string)

  • Other algorithms (MD5, SHA1, etc.) not provided for security reasons

License

Private project - not for distribution.