### Clone sys8 Repository and Install Dependencies Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Installs the sys8 MCP Server by cloning the repository, navigating into the directory, and installing necessary npm dependencies. This is the initial setup phase for the server. ```bash git clone https://github.com/Angry-Robot-Deals/mcp-sys8.git cd sys8 npm install ``` -------------------------------- ### MCP Server Configuration Example (JSON) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Configuration snippet for an MCP client to connect to the mcp-sys8 server. This JSON example shows how to define the server, specifying its command and arguments, which could be a direct executable or a Docker run command. This is used within the MCP client's configuration. ```json { "mcpServers": { "sys8": { "command": "sys8" } } } ``` ```json { "mcpServers": { "sys8": { "command": "docker", "args": ["run", "--rm", "-i", "sys8:latest"] } } } ``` -------------------------------- ### Development Setup with npm link (Bash) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Instructions for setting up the mcp-sys8 project for local development using `npm link`. This involves navigating to the project directory, linking it globally, and then referencing the linked package in your configuration. This is useful for testing changes without publishing them. ```bash cd sys8 npm link ``` -------------------------------- ### Programmatic Usage with MCP SDK (JavaScript) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Demonstrates how to connect to the mcp-sys8 server programmatically using the '@modelcontextprotocol/sdk' in JavaScript. This snippet shows client initialization, transport setup via stdio, connecting to the server, calling a tool (get_current_datetime), and closing the connection. It assumes the SDK is installed and the server is running. ```javascript import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'; const client = new Client({ name: 'my-client', version: '1.0.0', }, { capabilities: {}, }); const transport = new StdioClientTransport({ command: 'node', args: ['/path/to/sys8/build/index.js'], }); await client.connect(transport); // Use tools const result = await client.callTool({ name: 'get_current_datetime', arguments: {}, }); console.log(JSON.parse(result.content[0].text)); await client.close(); ``` -------------------------------- ### Testing mcp-sys8 Installation (Bash) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Command to run the test suite for the mcp-sys8 project. Executing `npm test` in the `sys8` directory will run all defined tests, verifying the functionality of the server and its tools. This is a crucial step after installation or updates. ```bash cd sys8 npm test ``` -------------------------------- ### Local Installation Command - Bash Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md Commands to navigate to the sys8 directory, install npm dependencies, and build the server for local installation. ```bash cd sys8 npm install npm run build ``` -------------------------------- ### Verify sys8 Installation Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Runs the test suite to confirm that all 20 tools within the sys8 MCP Server are functioning correctly after installation and building. This step ensures the integrity of the installation. ```bash npm test ``` -------------------------------- ### Troubleshooting Node.js Path (Bash) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Commands to verify Node.js installation and its presence in the system's PATH. This is a common troubleshooting step for 'Command not found: node' errors, ensuring Node.js version 24.0.0 or higher is correctly installed and accessible. ```bash node --version # Should show v24.0.0 or higher which node # Should show path to node executable ``` -------------------------------- ### MCP Configuration for Local Node.js Server - JSON Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md Example JSON configurations for launching the sys8 Node.js server locally. Includes examples for macOS/Linux and Windows paths, and a relative path option. ```json { "command": "node", "args": ["/home/user/mcp-sys8/build/index.js"] } ``` ```json { "command": "node", "args": ["C:\\Users\\user\\mcp-sys8\\build\\index.js"] } ``` ```json { "command": "node", "args": ["./sys8/build/index.js"] } ``` -------------------------------- ### Build sys8 Server Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Compiles the TypeScript source code into JavaScript, creating the `build/index.js` file and setting executable permissions. This step is crucial for preparing the server for execution. ```bash npm run build ``` -------------------------------- ### Running mcp-sys8 Docker Container (Bash) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Demonstrates various ways to run the mcp-sys8 Docker container. It shows how to run interactively, in detached mode, and how to view container logs. The server communicates using the stdio protocol. ```bash # Run interactively docker run --rm -i sys8:latest # Run in detached mode docker run -d --name sys8-server sys8:latest # View logs docker logs sys8-server docker logs -f sys8-server # Follow mode ``` -------------------------------- ### Troubleshooting Module Not Found (Bash) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Command to resolve the 'Cannot find module '@modelcontextprotocol/sdk'' error. Running `npm install` within the `sys8` directory ensures all project dependencies, including the SDK, are correctly installed. ```bash cd sys8 npm install ``` -------------------------------- ### Configure sys8 for Claude Desktop (Windows) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Integrates sys8 with Claude Desktop on Windows by adding the server configuration to the `claude_desktop_config.json` file, using Windows path conventions. Requires restarting Claude Desktop. ```json { "mcpServers": { "sys8": { "command": "node", "args": ["C:\\path\\to\\sys8\\build\\index.js"] } } } ``` -------------------------------- ### JSON: get_os_version Tool Response Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md Example JSON response from the 'get_os_version' tool. It includes information about the OS platform, release version, architecture, hostname, and current user details. ```json { "platform": "darwin", "release": "25.1.0", "architecture": "arm64", "type": "Darwin", "hostname": "mac.local", "username": "ug", "homedir": "/Users/ug", "platformName": "macOS", "uid": 501, "gid": 20 } ``` -------------------------------- ### Configure sys8 for Cursor AI (Project-Specific) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Sets up sys8 for a specific project within Cursor AI by creating a `.cursor/mcp.json` file in the project's root directory. This allows for project-level configurations of the sys8 server. ```json { "mcpServers": { "sys8": { "command": "node", "args": ["./sys8/build/index.js"] } } } ``` -------------------------------- ### JSON: get_os_version Tool Request Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md An example JSON payload for requesting operating system details using the 'get_os_version' tool. This tool also requires no parameters. ```json { "name": "get_os_version", "arguments": {} } ``` -------------------------------- ### Run sys8 as Standalone Server (Node.js) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Executes the sys8 MCP Server directly using Node.js from the compiled JavaScript build. This allows running the server independently without an integrated client. ```bash node /path/to/sys8/build/index.js ``` -------------------------------- ### Manually Run Server with Node.js Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md Directly executes the compiled JavaScript build of the server using Node.js. This is a straightforward way to start the server for manual testing or debugging purposes. ```bash node build/index.js ``` -------------------------------- ### Docker Image Build (Bash) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Command to build the Docker image for the mcp-sys8 server. This creates a Docker image tagged as `sys8:latest` from the `Dockerfile` in the `sys8` directory. Ensure you are in the `sys8` directory before running this command. ```bash cd sys8 docker build -t sys8:latest . ``` -------------------------------- ### Troubleshooting File Permissions (Bash) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Commands to address 'Permission denied' errors, specifically for the build output. `chmod +x sys8/build/index.js` grants execute permissions to the built file. Alternatively, rebuilding the project (`npm run build`) can also resolve this. ```bash chmod +x sys8/build/index.js ``` ```bash cd sys8 npm run build ``` -------------------------------- ### Development Watch Mode Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md Starts the development server in watch mode. This command automatically recompiles the project whenever source files are changed, streamlining the development workflow. ```bash npm run watch ``` -------------------------------- ### Run sys8 as Standalone Server (TypeScript with tsx) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Runs the sys8 MCP Server directly from its TypeScript source files using `tsx`. This method is convenient for development and testing without a full build step. ```bash npx tsx /path/to/sys8/src/index.ts ``` -------------------------------- ### Log Format: Sys8 MCP Server Logs Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md Example log entries from the Sys8 MCP server, demonstrating the standard format which includes timestamps, log levels (INFO, ERROR), and messages detailing server startup, tool calls, and their status. ```log [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 ``` -------------------------------- ### Sys8 Server Management Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md Commands for stopping, removing, and starting the Sys8 server container. Also includes methods to view logs and check server status. ```APIDOC ## Sys8 Server Management ### Stop and Remove Container ```bash docker stop sys8-server docker rm sys8-server ``` ### Start Container Starts the server in detached mode. Logs can be viewed using `docker logs`. ```bash docker run -d --name sys8-server sys8:latest ``` ### View Logs Follow the logs in real-time. ```bash docker logs -f sys8-server ``` ### Check Server Status #### Check Container Status Verifies if the `sys8-server` container is running. ```bash docker ps | grep sys8-server ``` #### Check MCP Server Process Executes a command inside the container to check if the Node.js process for the MCP server is active. ```bash docker exec sys8-server sh -c "pgrep -f 'node.*build/index.js' || echo 'Server not running - container may be using sleep command'" ``` ### Alternative Run Options #### Option 2: Run Container and See Logs Immediately Runs the container and displays all output directly, including logs. ```bash docker run --rm sys8:latest node test-server.mjs ``` #### Option 3: Test MCP Methods and See Logs Builds the image and runs tests within the container, showing logs. ```bash # 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. Example: ``` [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 - All tool calls (name, arguments, success/failure status) - Errors (with detailed error messages) **Note:** Logs are visible in the MCP client output or via `docker logs` for detached containers. ``` -------------------------------- ### Troubleshooting Build Not Found (Bash) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Command to fix the 'build/index.js not found' error. Running `npm run build` in the `sys8` directory compiles the project's source code, generating the necessary build artifacts. ```bash cd sys8 npm run build ``` -------------------------------- ### Configure sys8 for Cursor AI (Global) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Sets up the sys8 MCP Server for global use within Cursor AI by creating or editing the `mcp.json` file in the global storage directory. This allows Cursor AI to recognize and utilize the sys8 server. ```json { "mcpServers": { "sys8": { "command": "node", "args": ["/absolute/path/to/sys8/build/index.js"] } } } ``` -------------------------------- ### Openssl Random String Generation - Bash Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md Examples of using the openssl command-line tool to generate cryptographically secure random strings in different formats (hex, base64, bytes). ```bash openssl rand --hex ``` ```bash openssl rand | openssl base64 ``` -------------------------------- ### Get Operating System Information Source: https://context7.com/angry-robot-deals/mcp-sys8/llms.txt Retrieves platform details, version, architecture, hostname, and user information including UID/GID on Unix systems. ```APIDOC ## Get Operating System Information ### Description Retrieves platform details, version, architecture, hostname, and user information including UID/GID on Unix systems. ### Method POST ### Endpoint /api/mcp ### Parameters #### Request Body - **name** (string) - Required - The name of the tool to execute, which is `get_os_version`. - **arguments** (object) - Optional - An empty object, as this tool does not require any arguments. ### Request Example ```json { "name": "get_os_version", "arguments": {} } ``` ### Response #### Success Response (200) - **platform** (string) - The operating system platform (e.g., 'linux', 'win32'). - **release** (string) - The operating system release version. - **architecture** (string) - The system architecture (e.g., 'x86_64'). - **type** (string) - The OS type (e.g., 'Linux', 'Windows_NT'). - **hostname** (string) - The system's network hostname. - **username** (string) - The username of the current user. - **homedir** (string) - The home directory of the current user. - **platformName** (string) - A more descriptive name for the operating system platform. - **uid** (integer) - The user ID (on Unix-like systems). - **gid** (integer) - The group ID (on Unix-like systems). #### Response Example ```json { "platform": "linux", "release": "6.12.55-74.119.amzn2023.x86_64", "architecture": "x86_64", "type": "Linux", "hostname": "ip-172-31-45-123", "username": "root", "homedir": "/root", "platformName": "Linux", "uid": 0, "gid": 0 } ``` ``` -------------------------------- ### Docker: Stop, Remove, and Run sys8-server Container Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md Commands to stop and remove an existing sys8-server container, then run a new instance in detached mode. The container will automatically start the MCP server. Logs can be viewed using 'docker logs'. ```bash docker stop sys8-server docker rm sys8-server docker run -d --name sys8-server sys8:latest docker logs -f sys8-server ``` -------------------------------- ### JSON: get_current_datetime Tool Response Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md Example JSON response from the 'get_current_datetime' tool. It provides the current date and time in multiple formats, including ISO 8601 UTC, human-readable strings, and Unix timestamps. ```json { "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" } ``` -------------------------------- ### Get Operating System Information Source: https://context7.com/angry-robot-deals/mcp-sys8/llms.txt Fetches detailed information about the operating system, including platform, release version, architecture, hostname, and user details (UID/GID on Unix systems). This is essential for environment-dependent operations. ```json { "name": "get_os_version", "arguments": {} } ``` ```json { "platform": "linux", "release": "6.12.55-74.119.amzn2023.x86_64", "architecture": "x86_64", "type": "Linux", "hostname": "ip-172-31-45-123", "username": "root", "homedir": "/root", "platformName": "Linux", "uid": 0, "gid": 0 } ``` -------------------------------- ### Docker: Build Image and Test MCP Methods Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md Instructions to build the sys8 Docker image and then run tests within a new container instance. This command also streams logs to the console, allowing immediate observation of test execution and server behavior. ```bash # 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 ``` -------------------------------- ### Configure mcp.json for Windows (Production) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md This snippet demonstrates the configuration for the global MCP configuration file on Windows. It uses a JSON format with Windows-style paths, requiring double backslashes or forward slashes for directories. The 'command' and 'args' specify how to execute the compiled JavaScript. ```json { "mcpServers": { "sys8": { "command": "node", "args": ["C:\\path\\to\\mcp\\sys8\\build\\index.js"] } } } ``` -------------------------------- ### Configure sys8 for Cursor AI (Global - Development) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/INSTALLATION.md Configures sys8 for Cursor AI global use during development, utilizing `tsx` to run the TypeScript source directly. This is useful for faster iteration cycles when developing the server. ```json { "mcpServers": { "sys8": { "command": "npx", "args": ["tsx", "/absolute/path/to/sys8/src/index.ts"] } } } ``` -------------------------------- ### Configure mcp.json for macOS/Linux (Production) Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md This snippet shows how to configure the global MCP configuration file on macOS and Linux for production use. It specifies the command to run and arguments, including the absolute path to the compiled JavaScript file. Ensure the path is correct for your system. ```json { "mcpServers": { "sys8": { "command": "node", "args": ["/Users/ug/code/AI/mcp/sys8/build/index.js"] } } } ``` -------------------------------- ### get_os_version Tool Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md Retrieves information about the operating system, platform, and current user. ```APIDOC ## GET /tools/get_os_version ### Description Get the operating system version, platform information, and current user information. ### Method GET ### Endpoint `/tools/get_os_version` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```json { "name": "get_os_version", "arguments": {} } ``` ### Response #### Success Response (200) - **platform** (string) - Platform identifier (darwin, win32, linux) - **release** (string) - OS release version - **architecture** (string) - CPU architecture - **type** (string) - OS type - **hostname** (string) - System hostname - **username** (string) - Current user name - **homedir** (string) - User home directory - **platformName** (string) - Human-readable platform name (macOS, Windows, Linux) - **uid** (integer) - User ID (Unix systems only) - **gid** (integer) - Group ID (Unix systems only) #### Response Example ```json { "platform": "darwin", "release": "25.1.0", "architecture": "arm64", "type": "Darwin", "hostname": "mac.local", "username": "ug", "homedir": "/Users/ug", "platformName": "macOS", "uid": 501, "gid": 20 } ``` ``` -------------------------------- ### Manually Run Server with tsx Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md Executes the TypeScript source files directly using tsx, bypassing the need for a separate build step. This is convenient for development and quick testing of the source code. ```bash npx tsx src/index.ts ``` -------------------------------- ### JSON: get_current_datetime Tool Request Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md An example JSON payload representing a request to the 'get_current_datetime' tool. This tool requires no parameters and is used to fetch the current date and time in various formats. ```json { "name": "get_current_datetime", "arguments": {} } ``` -------------------------------- ### Get Current Date and Time Source: https://context7.com/angry-robot-deals/mcp-sys8/llms.txt Returns current date and time in multiple formats including ISO 8601, Unix timestamps, and human-readable formats for different timezones. ```APIDOC ## Get Current Date and Time ### Description Returns current date and time in multiple formats including ISO 8601, Unix timestamps, and human-readable formats for different timezones. ### Method POST ### Endpoint /api/mcp ### Parameters #### Request Body - **name** (string) - Required - The name of the tool to execute, which is `get_current_datetime`. - **arguments** (object) - Optional - An empty object, as this tool does not require any arguments. ### Request Example ```json { "name": "get_current_datetime", "arguments": {} } ``` ### Response #### Success Response (200) - **utc** (string) - The current date and time in ISO 8601 format. - **date** (string) - The current date in YYYY-MM-DD format. - **time** (string) - The current time in HH:MM:SS format. - **datetime** (string) - The current date and time in YYYY-MM-DD HH:MM:SS format. - **unix_timestamp_seconds** (integer) - The current Unix timestamp in seconds. - **unix_timestamp_milliseconds** (integer) - The current Unix timestamp in milliseconds. - **human_readable_utc0** (string) - Human-readable date and time in UTC+0. - **human_readable_utc2** (string) - Human-readable date and time in UTC+2. - **human_readable_utc3** (string) - Human-readable date and time in UTC+3. #### Response Example ```json { "utc": "2025-12-14T10:27:35.291Z", "date": "2025-12-14", "time": "10:27:35", "datetime": "2025-12-14 10:27:35", "unix_timestamp_seconds": 1734176855, "unix_timestamp_milliseconds": 1734176855291, "human_readable_utc0": "14/12/2025, 10:27:35", "human_readable_utc2": "14/12/2025, 12:27:35", "human_readable_utc3": "14/12/2025, 13:27:35" } ``` ``` -------------------------------- ### Dockerfile Command Execution for MCP Server Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/DOCKERFILE_COMPLIANCE.md Specifies the default command to run when a container starts. For MCP stdio servers, this typically involves executing a Node.js script. ```dockerfile CMD ["node", "build/index.js"] ``` -------------------------------- ### Docker Build and Run Commands for MCP Server Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/DOCKERFILE_COMPLIANCE.md Provides commands for building a Docker image from a Dockerfile and running it interactively for MCP server testing. It also shows how to view container logs. ```bash # Build image docker build -t sys8:latest . # Run with stdio (interactive mode for MCP) docker run -i --rm sys8:latest # View logs (when server is running) docker logs ``` -------------------------------- ### Docker: Run Container and View Logs Immediately Source: https://github.com/angry-robot-deals/mcp-sys8/blob/main/README.md A command to run the sys8 Docker container and stream all its output, including server logs, directly to the console. The '--rm' flag ensures the container is removed upon exit. ```bash docker run --rm sys8:latest node test-server.mjs ```