Skip to content

DELIVERY.md

Latest commit

 

History

History
295 lines (256 loc) · 9.18 KB

DELIVERY.md

File metadata and controls

295 lines (256 loc) · 9.18 KB

SecureMCP-Lite Delivery

Final File Tree

Source-controlled project tree. dist/ is generated by npm run build and intentionally excluded from git.

.
├── .github/
│   └── workflows/
│       └── ci.yml
├── .gitignore
├── apps/
│   └── frontend/
│       ├── app/
│       ├── components/
│       ├── lib/
│       ├── package.json
│       ├── scripts/
│       ├── tsconfig.json
│       └── next.config.ts
├── CONTRIBUTING.md
├── DELIVERY.md
├── LICENSE
├── OSS_READINESS_ID.md
├── README.md
├── SECURITY.md
├── TEST_REPORT_ID.md
├── docs/
│   ├── assets/
│   │   └── securemcp-lite-logo.svg
│   ├── compatibility-matrix.md
│   ├── demo-playbook.md
│   ├── feature-overview.md
│   ├── getting-started.md
│   ├── integrations.md
│   ├── integrations/
│   │   ├── anthropic-messages-api.md
│   │   ├── antigravity.md
│   │   ├── chatgpt-developer-mode.md
│   │   ├── claude-code.md
│   │   ├── codex.md
│   │   ├── cursor.md
│   │   ├── custom-local-agents.md
│   │   ├── github-copilot-chat.md
│   │   └── github-copilot-cli.md
│   ├── release-notes-v0.1.0.md
│   ├── threat-scenarios.md
│   └── use-cases.md
├── eslint.config.mjs
├── examples/
│   ├── ai-safe-filesystem.yml
│   ├── ai-safe-shell.yml
│   ├── ai-safe-sql.yml
│   ├── copilot-cli.mcp-config.json
│   ├── cursor.mcp.json
│   ├── secure-mcp.yml
│   ├── strict-secure-mcp.yml
│   └── vscode.mcp.json
├── package-lock.json
├── package.json
├── scripts/
│   ├── demo-allowed-call.mjs
│   ├── demo-blocked-call.mjs
│   ├── demo-lib.mjs
│   └── demo-mcp-session.mjs
├── src/
│   ├── cli/
│   │   └── index.ts
│   ├── config/
│   │   ├── configAdvisories.ts
│   │   ├── defaultConfig.ts
│   │   ├── loadConfig.ts
│   │   └── schema.ts
│   ├── errors/
│   │   └── jsonRpcErrors.ts
│   ├── index.ts
│   ├── logger/
│   │   └── createLogger.ts
│   ├── policy/
│   │   ├── policyEngine.ts
│   │   └── rateLimiter.ts
│   ├── proxy/
│   │   └── secureProxy.ts
│   ├── transports/
│   │   ├── stdioClientTransport.ts
│   │   ├── stdioServerTransport.ts
│   │   └── streamChannel.ts
│   └── types/
│       ├── config.ts
│       └── jsonrpc.ts
├── test/
│   ├── cli.smoke.test.ts
│   ├── config.test.ts
│   ├── configAdvisories.test.ts
│   ├── fixtures/
│   │   ├── broken-target.sh
│   │   ├── echo-target.js
│   │   └── mcp-fixture-server.sh
│   ├── policyEngine.test.ts
│   ├── secureProxy.test.ts
│   ├── stdioClientTransport.test.ts
│   └── streamChannel.test.ts
├── tsconfig.json
└── vitest.config.ts

Summary of What Changed

This delivery tightens the original MVP into a more credible public OSS release candidate.

Main changes:

  • added local parse and invalid-request JSON-RPC handling for malformed client input
  • added pending-request tracking and local target-unavailable responses when the target exits early
  • fixed half-close behavior so blocked requests and fallback errors are not lost during stdin shutdown
  • improved target start sequencing and start-failure handling
  • added config advisories plus validate-config --strict
  • cleaned build output before compile so deleted artifacts are not leaked into publish tarballs
  • expanded the automated suite with transport, proxy, config-advisory, and CLI smoke coverage
  • rebuilt README around public adoption and compatibility clarity
  • added a polished Next.js docs website under apps/frontend
  • added step-by-step integration docs for Claude Code, Codex, Cursor, Copilot, Antigravity, and custom local agents
  • strengthened SECURITY, CONTRIBUTING, release notes, examples, and launch-readiness reports

Major Technical Improvements

  • src/types/jsonrpc.ts: explicit parse and invalid-request classification with JSON-RPC error codes
  • src/transports/streamChannel.ts: cleaner stream framing, protocol-error surfacing, and safer stdio writes
  • src/transports/stdioServerTransport.ts: preserves response delivery after client stdin closes
  • src/transports/stdioClientTransport.ts: better child startup failure handling
  • src/proxy/secureProxy.ts: pending-request tracking, local fallback errors, and safer session shutdown
  • src/config/configAdvisories.ts: operational warnings for risky configs
  • src/cli/index.ts: stricter validation UX and safer config initialization
  • package.json: build hygiene for publish correctness

Key Files Created or Updated

  • README.md
  • apps/frontend/*
  • CONTRIBUTING.md
  • SECURITY.md
  • docs/getting-started.md
  • docs/feature-overview.md
  • docs/compatibility-matrix.md
  • docs/demo-playbook.md
  • docs/integrations.md
  • docs/integrations/claude-code.md
  • docs/integrations/codex.md
  • docs/integrations/cursor.md
  • docs/integrations/github-copilot-chat.md
  • docs/integrations/github-copilot-cli.md
  • docs/integrations/custom-local-agents.md
  • docs/integrations/antigravity.md
  • docs/integrations/chatgpt-developer-mode.md
  • docs/integrations/anthropic-messages-api.md
  • docs/use-cases.md
  • docs/release-notes-v0.1.0.md
  • examples/ai-safe-filesystem.yml
  • examples/ai-safe-shell.yml
  • examples/ai-safe-sql.yml
  • examples/cursor.mcp.json
  • examples/copilot-cli.mcp-config.json
  • examples/vscode.mcp.json
  • scripts/demo-blocked-call.mjs
  • scripts/demo-allowed-call.mjs
  • scripts/demo-mcp-session.mjs
  • src/config/configAdvisories.ts
  • src/errors/jsonRpcErrors.ts
  • src/proxy/secureProxy.ts
  • src/transports/streamChannel.ts
  • src/transports/stdioClientTransport.ts
  • src/transports/stdioServerTransport.ts
  • test/cli.smoke.test.ts
  • test/configAdvisories.test.ts
  • test/secureProxy.test.ts
  • test/streamChannel.test.ts
  • OSS_READINESS_ID.md
  • TEST_REPORT_ID.md

Main Commands

npm install
npm run lint
npm run build
npm run test -- --run
npm run site:build
npm run site:dev
npm pack --dry-run

Example Usage Commands

Initialize a config:

npx securemcp-lite init

Validate a config:

npx securemcp-lite validate-config --config ./secure-mcp.yml

Validate strictly:

npx securemcp-lite validate-config --config ./secure-mcp.yml --strict

Start the proxy:

npx securemcp-lite start --target "npx -y @modelcontextprotocol/server-filesystem ." --config ./secure-mcp.yml

Blocked-call demo:

tmpdir=$(mktemp -d)
cat > "$tmpdir/secure-mcp.yml" <<'EOF'
tools:
  allow:
    - read_file
EOF

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"delete_file","arguments":{"path":"/tmp/demo"}}}' \
  | node dist/cli/index.js start --target "cat" --config "$tmpdir/secure-mcp.yml"

Test Summary

Current automated suite:

  • 7 test files
  • 23 passing tests
  • unit, regression, and shell-smoke coverage

Covered areas:

  • config parsing and validation failures
  • config advisory generation
  • allowlist enforcement
  • regex argument checks
  • malformed JSON input
  • invalid tools/call parameters
  • rate limiting
  • blocked request isolation
  • allowed request forwarding
  • concurrent request handling
  • malformed target output
  • end-to-end multi-message MCP fixture session
  • stdout versus stderr separation
  • target start failure
  • target close with pending requests

Verification Summary

Verified successfully:

  • npm run lint
  • npm run build
  • npm run test -- --run
  • npm run site:build
  • npm run demo:all
  • npm pack --dry-run
  • node dist/cli/index.js init --config <tempfile>
  • node dist/cli/index.js validate-config --config <tempfile>
  • blocked-call smoke test via shell pipe

Additional behavior checked:

  • validate-config --strict fails when advisories are present
  • the publish tarball no longer contains stale deleted build artifacts
  • blocked local JSON-RPC responses remain on stdout while logs stay on stderr

Known Limitations

  • stdio only
  • regex rules are intentionally simple and not schema-aware per MCP tool
  • rate limiting is process-local and in-memory
  • no Windows CLI smoke coverage in CI because the smoke tests use bash and timeout
  • target stderr relay should be treated as best-effort operational visibility, not audit-grade evidence
  • the docs site is static and intentionally documentation-only, not an operational dashboard or approval UI
  • there is still no proof of real-world adoption or downstream dependency value

Next Recommended Steps

  1. Test against multiple real MCP servers, not just shell fixtures.
  2. Publish an initial GitHub release and npm package.
  3. Document a compatibility matrix for tested MCP clients and servers.
  4. Collect early user feedback and concrete usage examples.
  5. Add at least one end-to-end regression case against a real filesystem-style MCP server.