secure-command-processor-mcp-gateway

The Model Context Protocol service layer dedicated to the safeguarded invocation of authorized system directives.

🎥 Demonstration

https://github.com/user-attachments/assets/ed763a12-b685-4e0b-b9a5-bc948a590f51

✨ Core Capabilities

• Security-focused directive deployment governed by an explicit whitelist
• Adjustable parameters for permitted routines via environment variables
• Implemented leveraging TypeScript and the MCP SDK framework
• Inter-process communication established over standard input/output (stdio)
• Comprehensive exception handling and stringent validation mechanisms
• Streaming of resultant operational feedback as it is generated

🚀 Initialization Procedure

Acquire necessary dependencies: bash npm install

Compile the server artifact: bash npm run build

For iterative refinement with automated compilation: bash npm run watch

⚙️ System Parameters

🔒 Whitelisted Directives

By default, the following system calls are permitted: - git - ls - mkdir - cd - npm - npx - python

You retain the ability to modify this permissible set by assigning values to the ALLOWED_COMMANDS environmental parameter:

bash export ALLOWED_COMMANDS=git,ls,mkdir,python

🔌 Integration with Claude Desktop

To establish connectivity with the Claude Desktop client, augment the server configuration file:

For Darwin systems: bash ~/Library/Application Support/Claude/claude_desktop_config.json

For Windows operating systems:

%APPDATA%/Claude/claude_desktop_config.json

Illustrative configuration snippet:

{ "mcpServers": { "command-executor": { "command": "/path/to/command-executor/build/index.js" } } }

🛡️ Security Posture

The command-processor server enforces multiple layers of defense:

1. Explicit Directive Authorization List
2. Only specified routines are eligible for execution
3. The default compilation is inherently restrictive and security-oriented

4. Routines undergo validation based on their initial string segment to thwart injection vectors

5. Routine Validation Protocol

6. Prefix validation mechanisms neutralize potential command injection exploits
7. Direct shell interpretation is deliberately bypassed for enhanced security posture

8. Environmental variables are subjected to rigorous scrubbing and sanitization processes

9. Exception Management Framework

10. Detailed error reporting for unauthorized invocation attempts
11. Provision of unambiguous diagnostic messages

12. Failures during operational execution do not precipitate server cessation

13. Operational Environment Partitioning

14. The service operates within an isolated process boundary
15. External environmental parameters are subject to explicit administrative control
16. System resource access is intentionally constrained

💻 Development Lifecycle

📁 Artifact Organization

command-executor/ ├─ src/ │ └─ index.ts # Core server logic module ├─ build/ │ └─ index.js # Transpiled JavaScript output ├─ assets/ │ └─ header.svg # Project banner graphic └─ package.json # Project metadata manifest

🐛 Diagnostics

Debugging interactions over stdio can present complexities. We advise utilization of the official MCP Inspector:

bash npm run inspector

The Inspector utility will generate a resolvable Uniform Resource Locator for accessing browser-based diagnostic interfaces.

🛠️ Gateway Operation Interface

The server exposes a singular interface method:

execute_command

Initiates the running of an authorized system directive.

Parameters: - command (string, mandatory): The specific system call string to be processed

Invocation Example:

{ "name": "execute_command", "arguments": { "command": "git status" } }

Successful Reply Format:

{ "content": [ { "type": "text", "text": "On branch main\nNothing to commit, working tree clean" } ] }

Failure Reply Format:

{ "content": [ { "type": "text", "text": "Command execution failed: Command not allowed" } ], "isError": true }

❌ Exception Reporting Details

The service furnishes granular diagnostic text for numerous failure states:

1. Unauthorized Routine Invocation

{ "code": "InvalidParams", "message": "Command not allowed: [command]. Allowed commands: git, ls, mkdir, cd, npm, npx, python" }

1. Execution Runtime Faults

{ "content": [ { "type": "text", "text": "Command execution failed: [error message]" } ], "isError": true }

🤝 Collaboration Guidelines

1. Branch off the primary repository
2. Establish a dedicated feature branch
3. Commit your modifications
4. Push changes to your fork/branch
5. Submit a formal Pull Request

📄 Licensing Information

This software is distributed under the terms of the MIT License; refer to the LICENSE file for comprehensive specifics.