Sys8 MCP Server
MCP server for system information and developer utilities
Version: 0.4.0 | License: MIT
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
cryptomodule), date/time operations
- Used for: All server functionality, UUID generation (via
- npm or compatible package manager (required)
- Used for: Installing dependencies and building the project
- openssl (required for
generate_randomwith 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_randomwithtype: 'uuid'does NOT require openssl (uses Node.jscrypto.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-slimwith 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
- Required for: Safe mathematical expression evaluation in
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 operationschild_process- Executing openssl commandsBuffer- 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
- Command:
Installation
Local Installation
- Navigate to the sys8 directory:
cd sys8
- Install dependencies:
npm install
- Build the server:
npm run build
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:
{
"command": "node",
"args": ["/home/user/mcp-sys8/build/index.js"]
}
Example for Windows:
{
"command": "node",
"args": ["C:\\Users\\user\\mcp-sys8\\build\\index.js"]
}
Option 2: Relative Path (Project-Specific Configuration)
If sys8 is located in your project:
{
"command": "node",
"args": ["./sys8/build/index.js"]
}
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:ltsbase image) - openssl (installed via
apt-get install opensslin production stage) - All npm dependencies from
package.json
Building the Docker Image
cd sys8
docker build -t sys8:latest .
Running the Container
The sys8 MCP server uses stdio protocol for communication, so it should be run interactively:
docker run --rm -i sys8:latest
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
# Run container and see all logs immediately
docker run --rm sys8:latest node test-server.mjs
# This will show:
# - Server startup logs
# - All MCP tool calls
# - Success/failure status for each call
Option 2: Run container in detached mode (for production)
# IMPORTANT: Run container with default CMD (MCP server will start automatically)
docker run -d --name sys8-server sys8:latest
# View logs (server startup and all MCP operations)
docker logs sys8-server
# View logs in real-time (follow mode)
docker logs -f sys8-server
# View last 50 lines
docker logs --tail 50 sys8-server
# View logs with timestamps
docker logs -f -t sys8-server
# Stop and remove container
docker rm -f sys8-server
⚠️ 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:
# Stop and remove the container
docker stop sys8-server
docker rm sys8-server
# Start with correct command (MCP server will run automatically)
docker run -d --name sys8-server sys8:latest
# Now logs will be visible
docker logs -f sys8-server
To check if server is running:
# Check container status
docker ps | grep sys8-server
# Check if MCP server process is running (should show node process)
docker exec sys8-server sh -c "pgrep -f 'node.*build/index.js' || echo 'Server not running - container may be using sleep command'"
Option 2: Run container and see logs immediately
# Run container and see all output (including logs)
docker run --rm sys8:latest node test-server.mjs
Option 3: Test MCP methods and see logs
# Build image
docker build -t sys8-server:latest .
# Run tests inside container (logs will be visible)
docker run --rm sys8-server:latest node test-server.mjs
Log Format: All logs are prefixed with timestamps and log levels:
[2025-12-07T04:33:44.379Z] [INFO] ========================================
[2025-12-07T04:33:44.379Z] [INFO] Sys8 MCP Server started
[2025-12-07T04:33:44.379Z] [INFO] Version: 0.4.0
[2025-12-07T04:33:44.379Z] [INFO] Transport: stdio
[2025-12-07T04:33:44.379Z] [INFO] ========================================
[2025-12-07T04:33:44.383Z] [INFO] Tool call received: get_current_datetime
[2025-12-07T04:33:44.391Z] [INFO] Tool call: get_current_datetime | Args: {} | Status: SUCCESS
[2025-12-07T04:33:44.392Z] [INFO] Tool call received: get_os_version
[2025-12-07T04:33:44.392Z] [INFO] Tool call: get_os_version | Args: {} | Status: SUCCESS
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:
{
"name": "get_current_datetime",
"arguments": {}
}
Response:
{
"utc": "2025-11-30T10:27:35.291Z",
"date": "2025-11-30",
"time": "10:27:35",
"datetime": "2025-11-30 10:27:35",
"unix_timestamp_seconds": 1764498455,
"unix_timestamp_milliseconds": 1764498455291,
"human_readable_utc0": "30/11/2025, 10:27:35",
"human_readable_utc2": "30/11/2025, 12:27:35",
"human_readable_utc3": "30/11/2025, 13:27:35"
}
Response Fields:
utc: ISO 8601 UTC datetime stringdate: Date string in YYYY-MM-DD formattime: Time string in HH:mm:ss formatdatetime: Combined date and time stringunix_timestamp_seconds: Unix timestamp in secondsunix_timestamp_milliseconds: Unix timestamp in millisecondshuman_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:
{
"name": "get_os_version",
"arguments": {}
}
Response:
{
"platform": "darwin",
"release": "25.1.0",
"architecture": "arm64",
"type": "Darwin",
"hostname": "mac.local",
"username": "ug",
"homedir": "/Users/ug",
"platformName": "macOS",
"uid": 501,
"gid": 20
}
Response Fields:
platform: Platform identifier (darwin, win32, linux)release: OS release versionarchitecture: CPU architecturetype: OS typehostname: System hostnameusername: Current user namehomedir: User home directoryplatformName: 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:
{
"name": "calculate_math_expression",
"arguments": {
"expression": "2 + 2"
}
}
Response:
{
"result": 4,
"expression": "2 + 2"
}
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):
{
"name": "generate_random",
"arguments": {
"type": "uuid"
}
}
Response (UUID):
{
"type": "uuid",
"value": "550e8400-e29b-41d4-a716-446655440000",
"uuid": {
"standard": "550e8400-e29b-41d4-a716-446655440000",
"uppercase": "550E8400-E29B-41D4-A716-446655440000",
"without_dashes": "550e8400e29b41d4a716446655440000"
}
}
Example (Hex - all lengths):
{
"name": "generate_random",
"arguments": {
"type": "hex"
}
}
Response (Hex - all lengths):
{
"type": "hex",
"value": "84A7B45B6BD20D97",
"hex": {
"hex_8_uppercase": "84A7B45B6BD20D97",
"hex_16_uppercase": "4F76E8D72DFC73D01697F31B65910C19",
"hex_32_uppercase": "57FCAA273E858F6CA7A467A8E233727F913C799E8B51E8B27EF04B90BBD4C2F4",
"hex_64_uppercase": "5F2DCD116CEF205127445A5134D8008E3556CBDCC4759E89DA540C043E3B68B34A20A55587D375069BC38A97404E12C3FCEB42C8BB09E4C7651059107B2B9EFD"
}
}
Example (Base64 - specific length):
{
"name": "generate_random",
"arguments": {
"type": "base64",
"length": 32
}
}
Response (Base64 - specific length):
{
"type": "base64",
"value": "Yf1uDqalYr67AEtjTR/LxWj2zza/b7iUyHGNRpXPUAA=",
"base64": {
"base64_32": "Yf1uDqalYr67AEtjTR/LxWj2zza/b7iUyHGNRpXPUAA="
}
}
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:
{
"name": "hash_string",
"arguments": {
"input": "my-secret-key"
}
}
Response:
{
"input": "my-secret-key",
"sha256_hex": "d5579c46dfcc7f18207013e65b44e4cb4e2c2298f4ac457ba8f82743f31e930b",
"sha256_base64": "1VecRt/MfxggcBPmW0Tky04sIpj0rEV7qPgnQ/Mekws=",
"sha512_hex": "10e6d647af44624442f388c2c14a787ff8b17e6165b83d767ec047768d8cbcb71a1a3226e7cc7816bc79c0427d94a9da688c41a3992c7bf5e4d7cc3e0be5dbac",
"sha512_base64": "EObWR69EYkRC84jCwUp4f/ixfmFluD12fsBHdo2MvLcaGjIm58x4Frx5wEJ9lKnaaIxBo5kse/Xk18w+C+XbrA=="
}
Response Fields:
input: Original input stringsha256_hex: SHA256 hash in hexadecimal format (64 characters)sha256_base64: SHA256 hash in base64 formatsha512_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:
{
"name": "analyze_logs",
"arguments": {
"text": "npm ERR! code EACCES\nnpm ERR! permission denied\nerror TS2304: Cannot find name 'undefined'.\nnpm WARN deprecated package@1.0.0"
}
}
Response:
{
"error_count": 3,
"warning_count": 1,
"errors": [
{
"line": 1,
"message": "npm ERR! code EACCES",
"type": "npm"
},
{
"line": 2,
"message": "npm ERR! permission denied",
"type": "npm"
},
{
"line": 3,
"message": "error TS2304: Cannot find name 'undefined'.",
"type": "compilation"
}
],
"warnings": [
{
"line": 4,
"message": "npm WARN deprecated package@1.0.0",
"type": "npm"
}
]
}
Response Fields:
error_count: Number of errors found in the textwarning_count: Number of warnings found in the texterrors: Array of error objects with:line: Line number where error was foundmessage: 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 foundmessage: 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:
{
"name": "analyze_language",
"arguments": {
"text": "Hello 你好 Привет こんにちは 123!"
}
}
Response:
{
"total_characters": 20,
"encoding": "UTF-16 (JavaScript default)",
"languages": {
"english": {
"count": 5,
"percentage": 25.0
},
"chinese": {
"count": 2,
"percentage": 10.0
},
"russian": {
"count": 6,
"percentage": 30.0
},
"ukrainian": {
"count": 0,
"percentage": 0.0
},
"vietnamese": {
"count": 0,
"percentage": 0.0
},
"japanese": {
"count": 5,
"percentage": 25.0
},
"turkish": {
"count": 0,
"percentage": 0.0
},
"spanish": {
"count": 0,
"percentage": 0.0
}
},
"categories": {
"digits": {
"count": 3,
"percentage": 15.0
},
"punctuation": {
"count": 1,
"percentage": 5.0
},
"symbols": {
"count": 0,
"percentage": 0.0
},
"whitespace": {
"count": 3,
"percentage": 15.0
},
"other": {
"count": 0,
"percentage": 0.0
}
}
}
Response Fields:
total_characters: Total number of characters in the textencoding: Detected encoding (UTF-8, UTF-16, etc.) if determinablelanguages: Object with language-specific counts and percentages:english: English letters (A-Z, a-z)chinese: Chinese characters (CJK Unified Ideographs)russian: Russian Cyrillic charactersukrainian: Ukrainian Cyrillic characters (distinguished by specific characters like і, ї, є)vietnamese: Vietnamese Latin characters with diacriticsjapanese: 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 markssymbols: Mathematical and other symbolswhitespace: 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 encodeencoding(optional, string): Input encoding -utf8,hex, orbinary(default:utf8)
Example:
{
"name": "encode_base64",
"arguments": {
"input": "Hello World!",
"encoding": "utf8"
}
}
Response:
{
"encoded": "SGVsbG8gV29ybGQh",
"input": "Hello World!",
"encoding": "utf8"
}
9. decode_base64
Decode Base64 string.
Parameters:
input(required, string): Base64 string to decodeencoding(optional, string): Output encoding -utf8,hex, orbinary(default:utf8)
Example:
{
"name": "decode_base64",
"arguments": {
"input": "SGVsbG8gV29ybGQh",
"encoding": "utf8"
}
}
Response:
{
"decoded": "Hello World!",
"input": "SGVsbG8gV29ybGQh",
"encoding": "utf8"
}
10. encode_url
Encode string for URL (URL encoding).
Parameters:
input(required, string): String to encodecomponent(optional, string): Component type -full,path, orquery(default:full)
Example:
{
"name": "encode_url",
"arguments": {
"input": "Hello World!",
"component": "full"
}
}
Response:
{
"encoded": "Hello%20World%21",
"input": "Hello World!",
"component": "full"
}
11. decode_url
Decode URL-encoded string.
Parameters:
input(required, string): URL-encoded string to decodecomponent(optional, string): Component type -full,path, orquery(default:full)
Example:
{
"name": "decode_url",
"arguments": {
"input": "Hello%20World%21",
"component": "full"
}
}
Response:
{
"decoded": "Hello World!",
"input": "Hello%20World%21",
"component": "full"
}
12. format_text_case
Convert text to different case formats.
Parameters:
input(required, string): Text to convertformat(optional, string): Target format -camelCase,PascalCase,kebab-case,snake_case,CONSTANT_CASE,Title Case,lowercase, orUPPERCASE(if omitted, returns all formats)
Example:
{
"name": "format_text_case",
"arguments": {
"input": "hello world example"
}
}
Response:
{
"input": "hello world example",
"camelCase": "helloWorldExample",
"PascalCase": "HelloWorldExample",
"kebab-case": "hello-world-example",
"snake_case": "hello_world_example",
"CONSTANT_CASE": "HELLO_WORLD_EXAMPLE",
"Title Case": "Hello World Example",
"lowercase": "hello world example",
"UPPERCASE": "HELLO WORLD EXAMPLE"
}
13. generate_slug
Generate URL-friendly slug from text.
Parameters:
input(required, string): Text to convert to slugseparator(optional, string): Separator character (default:-)lowercase(optional, boolean): Convert to lowercase (default:true)
Example:
{
"name": "generate_slug",
"arguments": {
"input": "Hello World Example!",
"separator": "-",
"lowercase": true
}
}
Response:
{
"input": "Hello World Example!",
"slug": "hello-world-example",
"separator": "-"
}
14. validate_data
Validate data against various formats.
Parameters:
input(required, string): Data to validatetype(required, string): Validation type -email,url,ipv4,ipv6,domain,phone,credit-card,uuid,hex,base64, orjson
Example:
{
"name": "validate_data",
"arguments": {
"input": "user@example.com",
"type": "email"
}
}
Response:
{
"input": "user@example.com",
"type": "email",
"valid": true,
"normalized": "user@example.com"
}
Supported Validation Types:
email: Email address validationurl: URL validation (must start with http:// or https://)ipv4: IPv4 address validationipv6: IPv6 address validationdomain: Domain name validationphone: Phone number validation (international format)credit-card: Credit card number validation (13-19 digits)uuid: UUID v4 validationhex: Hexadecimal string validationbase64: Base64 string validationjson: JSON string validation (parsing)
15. format_json
Format, validate, minify, or prettify JSON.
Parameters:
input(required, string): JSON string to processaction(required, string): Action to perform -format,validate,minify, orprettifyindent(optional, number): Number of spaces for indentation (0-10, default: 2)
Example:
{
"name": "format_json",
"arguments": {
"input": "{\"name\":\"test\",\"value\":123}",
"action": "prettify",
"indent": 2
}
}
Response:
{
"valid": true,
"formatted": "{\n \"name\": \"test\",\n \"value\": 123\n}",
"minified": "{\"name\":\"test\",\"value\":123}"
}
Actions:
validate: Validate JSON and return formatted versionformat: Format JSON with specified indentationprettify: 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:
{
"name": "generate_password",
"arguments": {
"length": 16,
"include_uppercase": true,
"include_lowercase": true,
"include_numbers": true,
"include_symbols": true,
"exclude_similar": false
}
}
Response:
{
"password": "Kx9#mP2$vL8@nQ4!",
"length": 16,
"strength": "strong",
"entropy": 95.24,
"character_set_size": 94
}
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 formatformat(optional, string): Format type -binary(1024-based) ordecimal(1000-based) (default:binary)precision(optional, number): Number of decimal places (0-10, default: 2)
Example:
{
"name": "format_bytes",
"arguments": {
"bytes": 1048576,
"format": "binary",
"precision": 2
}
}
Response:
{
"bytes": 1048576,
"formatted": "1.00 MB",
"formatted_decimal": "1.05 MB",
"kilobytes": 1024,
"megabytes": 1,
"gigabytes": 0.0009765625,
"terabytes": 9.5367431640625e-7,
"petabytes": 9.313225746154785e-10
}
18. format_number
Format numbers (currency, percentage, thousands separator, decimal).
Parameters:
number(required, number): Number to formatformat(required, string): Format type -currency,percentage,thousands, ordecimallocale(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:
{
"name": "format_number",
"arguments": {
"number": 1234.56,
"format": "currency",
"locale": "en-US",
"currency": "USD"
}
}
Response:
{
"input": 1234.56,
"formatted": "$1,234.56",
"format": "currency",
"locale": "en-US",
"currency": "USD"
}
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 convertfrom(required, string): Source color format -hex,rgb, orhslto(required, string): Target color format -hex,rgb, orhsl
Example:
{
"name": "convert_color",
"arguments": {
"input": "#FF5733",
"from": "hex",
"to": "rgb"
}
}
Response:
{
"input": "#FF5733",
"from": "hex",
"to": "rgb",
"hex": "#FF5733",
"rgb": "rgb(255, 87, 51)",
"hsl": "hsl(9, 100%, 60%)",
"rgb_array": [255, 87, 51],
"hsl_array": [9, 100, 60]
}
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 convertfrom_timezone(optional, string): Source timezone (default:UTC)to_timezone(required, string): Target timezoneformat(optional, string): Output format (optional)
Example:
{
"name": "convert_timezone",
"arguments": {
"datetime": "2025-12-07T12:00:00Z",
"from_timezone": "UTC",
"to_timezone": "America/New_York"
}
}
Response:
{
"input_datetime": "2025-12-07T12:00:00Z",
"from_timezone": "UTC",
"to_timezone": "America/New_York",
"converted_datetime": "2025-12-07 07:00:00",
"iso_string": "2025-12-07T07:00:00-05:00",
"unix_timestamp": 1733580000,
"formatted": "2025-12-07 07:00:00"
}
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:
- Create or edit the global MCP configuration file:
mkdir -p ~/Library/Application\ Support/Cursor/User/globalStorage
nano ~/Library/Application\ Support/Cursor/User/globalStorage/mcp.json
Or alternatively:
mkdir -p ~/.cursor
nano ~/.cursor/mcp.json
- Add the following configuration:
{
"mcpServers": {
"sys8": {
"command": "npx",
"args": ["tsx", "/Users/ug/code/AI/mcp/sys8/src/index.ts"]
}
}
}
Windows:
{
"mcpServers": {
"sys8": {
"command": "npx",
"args": ["tsx", "C:\\path\\to\\mcp\\sys8\\src\\index.ts"]
}
}
}
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:
- Create or edit the global MCP configuration file:
mkdir -p ~/Library/Application\ Support/Cursor/User/globalStorage
nano ~/Library/Application\ Support/Cursor/User/globalStorage/mcp.json
- Add the following configuration:
{
"mcpServers": {
"sys8": {
"command": "node",
"args": ["/Users/ug/code/AI/mcp/sys8/build/index.js"]
}
}
}
Important: Replace /Users/ug/code/AI/mcp/sys8/build/index.js with the absolute path to your build/index.js file.
Linux
- Create or edit the global MCP configuration file:
mkdir -p ~/.config/Cursor/User/globalStorage
nano ~/.config/Cursor/User/globalStorage/mcp.json
Or alternatively:
mkdir -p ~/.cursor
nano ~/.cursor/mcp.json
- Add the configuration as shown above for macOS.
Windows
- Create or edit the global MCP configuration file:
%APPDATA%\Cursor\User\globalStorage\mcp.json
Or alternatively:
%USERPROFILE%\.cursor\mcp.json
- Add the following configuration (use Windows path format):
{
"mcpServers": {
"sys8": {
"command": "node",
"args": ["C:\\path\\to\\mcp\\sys8\\build\\index.js"]
}
}
}
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:
{
"mcpServers": {
"sys8": {
"command": "node",
"args": ["/absolute/path/to/sys8/build/index.js"]
}
}
}
Example: If your project is at /Users/ug/code/AI/mcp, you can use:
{
"mcpServers": {
"sys8": {
"command": "node",
"args": ["./sys8/build/index.js"]
}
}
}
Alternative: Using npm link (For Development)
If you want to use the server from anywhere without specifying the full path:
- In the sys8 directory:
npm link
- Then in the configuration, use:
{
"mcpServers": {
"sys8": {
"command": "sys8"
}
}
}
Verifying Configuration
After adding the configuration:
- Restart Cursor AI
- The MCP server should be automatically loaded
- 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:
npm test
This will test all 20 tools:
get_current_datetime- all available formatsget_os_version- OS information and user detailscalculate_math_expression- simple arithmetic, complex expressions, functions, and error caseshash_string- SHA256 and SHA512 hashes in hex and base64 formatsgenerate_random- UUID v4, hex strings, base64 strings, or raw bytes generationencode_base64/decode_base64- Base64 encoding/decodingencode_url/decode_url- URL encoding/decodingformat_text_case- text case conversion (camelCase, kebab-case, etc.)generate_slug- URL-friendly slug generationvalidate_data- data validation (email, URL, IP, JSON, etc.)format_json- JSON formatting, validation, and minificationgenerate_password- secure password generation with customizable optionsformat_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 conversionanalyze_logs- analyze text for errors and warnings in logsanalyze_language- analyze text for language distribution and character typesanalyze_language- analyze text for language distribution and character types
MCP Inspector
Test the server interactively using the MCP Inspector:
npm run inspector
This opens an interactive interface where you can test each tool manually.
Manual Testing
You can also run the server directly:
node build/index.js
Or using tsx:
npx tsx src/index.ts
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_randomwithtype: 'hex',type: 'base64', ortype: '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_randomwithtype: 'uuid') does NOT require openssl (uses Node.jscrypto.randomUUID())
- Node.js >= 24.0.0: Required for all functionality
- Provides built-in
cryptomodule for UUID and hashing - Provides
osmodule for system information - Provides
Bufferfor encoding/decoding operations
- Provides built-in
Functional Limitations
- OS version information: Based on Node.js
osmodule capabilities (may vary by platform) - Date/time information:
get_current_datetimereturns all formats in UTC timezone- Uses system timezone settings for conversions
- Mathematical expressions: Limited to operations supported by
expr-evallibrary- 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.