docs: update docs for v0.3.0 stack files release

- README: add stack files section with mcpm.yaml example, 4 new commands
  in command table, update agent mode to 9 tools
- ARCHITECTURE: add stack/ module, export/lock/up/diff commands, update
  test count to 812+
- CLAUDE.md: add V1.3 shipped section with all stack file features,
  update tool count and command list
- TODOS: mark #3 (backup) as resolved, add #15 (secret storage)
- Bump version to v0.3.0

Author: m1ngshum

CLAUDE.md

@@ -129,10 +129,11 @@ Build the **open-source, community-owned npm+npm_audit** for MCP:
 - **Local storage**: JSON files in `~/.mcpm/` (servers.json, scans.json, cache/)
 - **Testing**: Vitest + @vitest/coverage-v8 (80% line, 75% branch thresholds)
 - **Build**: tsup (TypeScript → JS)
-- **MCP server**: `mcpm serve` exposes 8 tools via `@modelcontextprotocol/sdk` (stdio transport)
+- **MCP server**: `mcpm serve` exposes 9 tools via `@modelcontextprotocol/sdk` (stdio transport)
 - **Commands**: `mcpm search`, `mcpm install`, `mcpm list`, `mcpm remove`, `mcpm info`,
   `mcpm audit`, `mcpm update`, `mcpm doctor`, `mcpm init`, `mcpm import`, `mcpm serve`,
-  `mcpm disable`, `mcpm enable`, `mcpm alias`, `mcpm completions`
+  `mcpm disable`, `mcpm enable`, `mcpm alias`, `mcpm completions`,
+  `mcpm export`, `mcpm lock`, `mcpm up`, `mcpm diff`
 
 ### Registry API (upstream, not ours)
 
@@ -218,6 +219,27 @@ When community quality signals require a backend (user reviews, aggregated telem
 - [x] Client ID validation before unsafe casts
 - [x] Security hardening: tool path allowlist, health check sandboxing
 
+### V1.3 (stack files — SHIPPED v0.3.0)
+
+- [x] `mcpm export` — dump installed servers to mcpm.yaml stack file format
+- [x] `mcpm lock` — resolve semver ranges from registry, trust assess, write mcpm-lock.yaml
+- [x] `mcpm up` — batch install from mcpm.yaml with trust policy enforcement
+- [x] `mcpm diff` — compare installed state vs declared state (colored output + --json)
+- [x] `mcpm_up` MCP server tool (destructiveHint: true)
+- [x] Stack file Zod schemas (mcpm.yaml + mcpm-lock.yaml) with YAML parse/serialize
+- [x] Semver version resolution (caret + tilde ranges via `semver` package)
+- [x] Trust policy enforcement with normalized percentage comparison
+- [x] .env file parser for env var resolution (process.env → .env → default → prompt)
+- [x] Parallel registry resolution, sequential config writes
+- [x] Single .bak snapshot before batch writes
+- [x] Per-server error isolation (failures collected, others continue)
+- [x] URL server support (Cursor-only, warn for other clients)
+- [x] --dry-run, --ci, --profile, --strict, --yes flags on `mcpm up`
+- [x] --strict --ci requires --yes for unattended server removal
+- [x] Path traversal protection on mcpm_up MCP tool input
+- [x] Prototype poisoning protection in .env parser
+- [x] Shared isEnoent() utility extracted to src/utils/fs.ts
+
 ### V1.5 (community trust)
 
 - [ ] `mcpm publish` — submit to official registry with mandatory security scan gate
@@ -233,7 +255,6 @@ When community quality signals require a backend (user reviews, aggregated telem
 - [ ] Dependency graph (which servers compose well together)
 - [ ] AI-generated docs (Claude reads source → writes human-friendly tool docs)
 - [ ] Compatibility matrix (auto-tested)
-- [ ] Semver-aware version resolution + lock files
 
 ---
 
@@ -289,7 +310,7 @@ the registry concept end-to-end before we launch publicly.
      │
      ├── CLI (terminal)              ├── MCP Server (stdio)
      │   mcpm search/install/...     │   mcpm serve
-     │                               │   8 tools via JSON-RPC
+     │                               │   9 tools via JSON-RPC
      ▼                               ▼
   mcpm core (Node.js, npm: @getmcpm/cli, bin: mcpm)
      │

README.md

@@ -104,6 +104,33 @@ $ mcpm doctor
   [pass] 3 servers installed, 0 with errors
 ```
 
+### Stack files: docker-compose for MCP
+
+Declare your project's MCP servers in `mcpm.yaml`, lock versions with trust snapshots, and let every team member replicate the setup with one command.
+
+```bash
+mcpm export > mcpm.yaml          # dump current setup
+mcpm lock                        # resolve versions + trust snapshot
+mcpm up                          # install everything from mcpm.yaml
+mcpm diff                        # compare installed vs declared state
+```
+
+Stack files include a trust policy. If a server's trust score drops below the threshold, `mcpm up` blocks it.
+
+```yaml
+version: "1"
+policy:
+  minTrustScore: 60
+  blockOnScoreDrop: true
+servers:
+  io.github.domdomegg/filesystem-mcp:
+    version: "^1.0.0"
+  io.github.modelcontextprotocol/servers-github:
+    version: "1.2.3"
+    env:
+      GITHUB_TOKEN: { required: true, secret: true }
+```
+
 ### Starter packs
 
 Get a working MCP setup in one command.
@@ -154,6 +181,10 @@ Without an external scanner installed, the maximum possible score is 80/100. The
 | `mcpm enable <name>` | Re-enable a previously disabled MCP server |
 | `mcpm import` | Import existing MCP servers from client config files |
 | `mcpm alias` | Create short aliases for long MCP server names |
+| `mcpm export` | Export installed servers as an mcpm.yaml stack file |
+| `mcpm lock` | Resolve versions and create mcpm-lock.yaml with trust snapshots |
+| `mcpm up` | Install all servers from mcpm.yaml with trust verification |
+| `mcpm diff` | Compare installed servers against mcpm.yaml and lock file |
 | `mcpm completions <shell>` | Generate shell completion scripts (bash, zsh, fish) |
 | `mcpm serve` | Start mcpm as an MCP server (stdio transport) |
 
@@ -174,7 +205,7 @@ mcpm can run as an MCP server itself, letting AI agents search, install, and aud
 }
 ```
 
-This exposes 8 tools: `mcpm_search`, `mcpm_install`, `mcpm_info`, `mcpm_list`, `mcpm_remove`, `mcpm_audit`, `mcpm_doctor`, and `mcpm_setup`.
+This exposes 9 tools: `mcpm_search`, `mcpm_install`, `mcpm_info`, `mcpm_list`, `mcpm_remove`, `mcpm_audit`, `mcpm_doctor`, `mcpm_setup`, and `mcpm_up`.
 
 The `mcpm_setup` tool takes a natural language description like "filesystem and GitHub" and handles everything: search, trust scoring, install. One tool call to assemble a working MCP toolchain.
 

TODOS.md

@@ -19,11 +19,8 @@
 
 ## Pre-launch
 
-### 3. Config Backup-Before-Write
-**Priority:** P1
-**What:** Before atomic config write, copy existing config to ~/.mcpm/backups/{client}.{timestamp}.json. Keep last 5 backups.
-**Why:** If a config write produces malformed JSON, Claude Desktop/Cursor may fail to parse and lose all MCP server configs. Backup enables recovery.
-**Depends on:** Config adapter implementation.
+### 3. ~~Config Backup-Before-Write~~ DONE (2026-04-06)
+**Resolution:** Implemented in BaseAdapter.writeAtomic (base.ts:49). Writes .bak file before every atomic write. mcpm up takes a single .bak snapshot before batch starts (up.ts:223).
 
 ### 4. Cross-Platform Config Paths
 **Priority:** P1
@@ -63,6 +60,13 @@
 
 ## Post-V1
 
+### 15. Encrypted Secret Storage for Stack Files
+**Priority:** P2
+**What:** Investigate alternatives to plaintext env var storage in client config files. Options: OS keychain integration, encrypted .env files, reference-only storage (pointer to secret manager).
+**Why:** Stack files scale team-wide. Every `mcpm up` writes secrets as plaintext JSON to client configs. With 5+ servers each needing API keys, that's 5+ plaintext secrets per developer per IDE.
+**Context:** Current approach (plaintext + chmod 600) is the npm/pip norm. But mcpm positions as a security tool. Plaintext secrets in 4 config files per machine is inconsistent with that positioning. Not blocking for V1.3 but matters for enterprise adoption.
+**Depends on:** V1.3 stack files (shipped).
+
 ### 14. Optional Anonymous Telemetry
 **Priority:** P2
 **What:** Add opt-in anonymous telemetry (install count, command usage, error types).

docs/ARCHITECTURE.md

@@ -23,7 +23,11 @@ mcpm/
 │   │   ├── enable.ts               — re-enable a disabled server
 │   │   ├── toggle.ts               — shared disable/enable logic
 │   │   ├── completions.ts          — shell completion scripts (bash/zsh/fish)
-│   │   └── alias.ts                — short aliases for server names
+│   │   ├── alias.ts                — short aliases for server names
+│   │   ├── export.ts               — export installed servers as mcpm.yaml
+│   │   ├── lock.ts                 — resolve versions + trust → mcpm-lock.yaml
+│   │   ├── up.ts                   — batch install from mcpm.yaml with trust policy
+│   │   └── diff.ts                 — compare installed vs declared state
 │   ├── server/
 │   │   ├── index.ts                — MCP server setup (registerTool, stdio transport)
 │   │   ├── tools.ts                — Zod input schemas for each tool
@@ -54,11 +58,18 @@ mcpm/
 │   │   ├── servers.ts              — installed server registry
 │   │   ├── cache.ts                — HTTP response cache
 │   │   └── aliases.ts              — server name aliases (~/.mcpm/aliases.json)
+│   ├── stack/
+│   │   ├── schema.ts               — Zod schemas for mcpm.yaml + mcpm-lock.yaml
+│   │   ├── resolve.ts              — semver range resolution
+│   │   ├── policy.ts               — trust policy enforcement
+│   │   ├── env.ts                  — .env file parser
+│   │   └── index.ts                — public API surface
 │   └── utils/
 │       ├── output.ts               — leveled output helpers
 │       ├── confirm.ts              — confirmation prompts
 │       ├── format-entry.ts         — format MCP server config entries
-│       └── format-trust.ts         — format trust score display
+│       ├── format-trust.ts         — format trust score display
+│       └── fs.ts                   — shared filesystem helpers (isEnoent)
 ├── src/__tests__/
 │   ├── commands/                    — 16 command test files
 │   ├── config/                      — adapter + detector + paths tests
@@ -78,8 +89,9 @@ mcpm/
 
 | Module | Purpose |
 |---|---|
-| `commands/` | 15 CLI commands, each a self-contained Commander action |
-| `server/` | MCP server (stdio): 8 tools wrapping CLI logic via injectable handlers |
+| `commands/` | 19 CLI commands, each a self-contained Commander action |
+| `server/` | MCP server (stdio): 9 tools wrapping CLI logic via injectable handlers |
+| `stack/` | Stack file schemas (mcpm.yaml/mcpm-lock.yaml), semver resolution, trust policy, .env parsing |
 | `registry/` | Typed HTTP client for the official MCP Registry API (v0.1 at registry.modelcontextprotocol.io) |
 | `config/` | OS-aware config paths, client detection, and per-client config adapters with atomic writes |
 | `scanner/` | Trust scoring engine: tier 1 (metadata), tier 2 (static pattern analysis), composite score |
@@ -103,6 +115,10 @@ mcpm/
 | `mcpm enable <name>` | Re-enable a previously disabled server |
 | `mcpm import` | Import existing servers from client config files |
 | `mcpm alias` | Create short aliases for long server names |
+| `mcpm export` | Export installed servers as an mcpm.yaml stack file |
+| `mcpm lock` | Resolve versions and create mcpm-lock.yaml with trust snapshots |
+| `mcpm up` | Install all servers from mcpm.yaml with trust verification |
+| `mcpm diff` | Compare installed servers against mcpm.yaml and lock file |
 | `mcpm completions <shell>` | Generate shell completion scripts (bash, zsh, fish) |
 | `mcpm serve` | Start mcpm as an MCP server (stdio transport) |
 
@@ -164,7 +180,7 @@ All config writes use atomic file operations (write to `.tmp`, then `fs.rename`)
 ## Testing
 
 - **Framework**: vitest with `@vitest/coverage-v8`
-- **Test count**: 739+ tests
+- **Test count**: 812+ tests
 - **Coverage thresholds**: lines 80%, branches 75%
 - **Test locations**: `src/__tests__/` (command, config, store tests) + colocated `*.test.ts` (registry, scanner)
 - **Approach**: injectable `fetchImpl` for registry tests (no network calls), temp directories for config adapter tests

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmcpm/cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "mcpName": "io.github.getmcpm/cli",
   "description": "MCP package manager — search, install, and audit MCP servers across Claude Desktop, Cursor, VS Code, and Windsurf",
   "type": "module",