How ithena-one/mcp-safe-run works
<explanation>
1. Identify the 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.
2. Analyze the 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.
3. Examine the README for additional insights
- Describes usage, placeholder types, config file search order, supported OS keychain dependencies (keytar).
- No existing architecture diagram; emphasis on secure resolution and process spawning.
4. 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
5. 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.
6. How to draw the system design diagram
a. Components (boxes):
- “mcp-safe-run CLI”
- “Config Loader”
- “Placeholder Resolver”
- “Environment Merger”
- “Process Spawner”
b. External services (cylinders or cloud shapes):
- File System (./secrets/*.txt)
- OS Keychain (Keytar → OS secret store)
- Shell Environment
c. Data flows (directional arrows):
1. User invokes CLI → arrow to CLI box.
2. CLI → Config Loader (passes flags).
3. Config Loader → Config File or default YAML (reads).
4. CLI → Placeholder Resolver (target-env map).
5. Resolver → File System or Keychain or process.env (reads).
6. Resolver → Environment Merger (resolved values).
7. Merger → Process Spawner (final env map).
8. Spawner → Target MCP Server process.
d. Color coding / shapes:
- Blue rectangles for internal modules.
- Green cylinders for storage (filesystem, keychain).
- Gray cloud for shell env.
- Thick arrow for the final spawn of target process.
e. Labels:
- On each arrow, annotate “read config,” “resolve file:,” “resolve keyring:,” “spawn process.”
- On modules, list key tech (e.g., “Placeholder Resolver (TypeScript, keytar, fs)”).
7. Tailor the diagram for this CLI‑tool project
- No frontend/backend split—focus on CLI pipeline.
- Emphasize secure‑resolution flow: config → placeholders → env → spawn.
- Show plugin‑style extensibility: adding new placeholder types merely extends placeholder-resolver.ts.
8. Diagramming guidelines for the principal engineer
- Use clear, consistent shapes: rectangles for code modules, cylinders for storage, cloud icon for shell.
- Color‑code by component type.
- Label every arrow with the action or data passed.
- Show search‑order path in the Config Loader (e.g., numbered arrows).
- Group related modules in a “Core Logic” container, and external systems outside that.
- Include a legend for colors/shapes.
By mapping these components and flows, your architecture diagram will accurately and exhaustively reflect how mcp-safe-run securely loads secrets and delegates execution to the target MCP server.