How ithena-one/mcp-safe-run works
Project type and purpose
• This is a Node.js‑based command‑line application (CLI) called mcp-safe-run.
• Its purpose is to securely resolve and inject secrets (from files, keychain, or env vars) into the environment of a target MCP server process without exposing them on the shell or in version control.
File structure
• Top‑level files (package.json, tsconfig.json, jest.config.cjs) define it as a TypeScript‑built NPM package with tests.
• src/index.ts is the CLI entrypoint.
• src/config-loader.ts + tests: loads & merges configuration (flags, profiles, YAML files).
• src/placeholder-resolver.ts + tests: resolves placeholders (env:, file:, keyring:).
• No frontend or server directories—purely CLI.
README for additional insights
• Describes usage, placeholder types, config file search order, supported OS keychain dependencies (keytar).
Main components and their relationships
a. CLI Layer (Entrypoint)
• Parses flags (--target-env, -c, -p, etc.).
• Kicks off config loading and resolution.
b. Configuration Loader
• Implements search order: direct --target-env JSON → specified config file → default YAML in CWD or ~/.config.
• Outputs a merged target-env map.
c. Placeholder Resolver
• Iterates over each variable in the map.
• For env: placeholders, reads from process.env.
• For file: placeholders, uses Node’s fs to read & trim a file.
• For keyring: placeholders, calls keytar to talk to the OS keychain.
d. Environment Merger
• Combines resolved values with any literal values and shell‑inherited vars (lowest precedence).
e. Process Spawner
• Uses Node’s child_process.spawn (or exec) to launch the target command (e.g. npx -y @modelcontextprotocol/server-github) with the sanitized environment.
f. External Dependencies
• File system (secrets directory)
• OS keychain (via keytar)
• Shell environment
Architectural patterns and design principles
• Single‑responsibility modules: each TS file handles one concern (CLI, config, resolution).
• Strategy‑pattern–like placeholder resolution: new placeholder types plug in easily.
• Clear precedence rules (flags > config profiles > shell env).
• Separation of CLI parsing vs. core logic vs. external side‑effects.