mcp-remote/implementation_plan.md

Implementation Plan

Here is a plan to transform your Node.js CLI package into a Deno CLI project, focusing on reusing the existing TypeScript code in the src/ directory:

1. Analyze Dependencies:

   • Identify Node.js built-in modules used (e.g., events, process).
   • Identify external npm packages (e.g., @modelcontextprotocol/sdk).

2. Configure deno.json:

   • Update the imports section to map npm packages using npm: specifiers (e.g., "@modelcontextprotocol/sdk/": "npm:@modelcontextprotocol/sdk/").
   • Ensure necessary Deno standard library modules are imported if needed (e.g., std/node for Node compatibility APIs if direct replacement isn't feasible).
   • Update the tasks section to use deno run with appropriate permissions (--allow-net, --allow-read, --allow-env, etc.) targeting src/proxy.ts. Remove --watch from the main start task unless desired.
   • Review compilerOptions. Deno uses these, but ensure they align with Deno's defaults or project needs. Remove "types": ["node"] as Deno handles Node types via node: specifiers.
   • Remove "unstable": ["sloppy-imports"] and plan to add explicit file extensions to imports.

3. Adapt Code in src/:

   • Imports:
     • Prefix all Node.js built-in module imports with node: (e.g., import { EventEmitter } from 'node:events';).
     • Update imports for external npm packages to match the npm: specifiers defined in deno.json or directly use npm: specifiers in the import statement.
     • Append the .ts (or .js if applicable) extension to all relative file imports within the src/ directory (e.g., import { ... } from './lib/utils.ts';).
   • Node Globals/APIs:
     • Replace process.argv with Deno.args. Note that Deno.args does not include the script name, so adjustments to slicing (like .slice(2)) might be needed or removed.
     • Replace process.exit() with Deno.exit().
     • Replace or refactor any other Node-specific APIs that don't have direct Deno equivalents or aren't polyfilled via the node: specifier (e.g., check compatibility of StdioServerTransport if it relies heavily on Node streams internally, although the npm: specifier should handle much of this).

4. Cleanup Project Root:

   • Delete pnpm-lock.yaml and node_modules (if present).
   • Decide whether to keep package.json. It's not used by Deno for dependencies but can be useful for metadata (name, version, description). If kept, ensure it doesn't cause confusion.
   • Remove tsconfig.json if all necessary compiler options are migrated to deno.json. Linters/editors might still pick it up, so consider keeping it for tooling compatibility if needed, but deno.json takes precedence for Deno itself.

5. Testing:

   • Added client.ts as an additional CLI entrypoint
   • Added client task to deno.json
   • Run the main task using deno task proxy:start <args...>.
   • Thoroughly test the CLI's functionality to ensure it behaves identically to the original Node.js version. Pay close attention to areas involving file system access, network requests, environment variables, and process management.

6. Refine Type Safety & Linting:

   • Address remaining any types and other linter warnings identified by deno lint.
   • Improve type definitions, especially for external library interactions (e.g., express request/response types if kept).
   • Run deno fmt to ensure consistent code formatting.

7. Improve Dependency Management:

   • Evaluate replacing npm:express with a native Deno HTTP server solution (e.g., Deno.serve or from std/http).
   • Evaluate replacing npm:open with a Deno equivalent or platform-specific commands.

8. Implement Testing:

   • Add unit tests for key utility functions (e.g., in utils.ts, mcp-auth-config.ts).
   • Add integration tests for the core proxy (proxy.ts) and client (client.ts) functionality.

9. Enhance Documentation:

   • Update README.md with Deno-specific installation, usage, and contribution guidelines.
   • Add comprehensive TSDoc comments to all exported functions, classes, and interfaces.

10. Build & Distribution:

    • Configure deno publish settings if intending to publish to deno.land/x.
    • Explore using deno compile to create standalone executables for different platforms.

This plan prioritizes modifying the existing TypeScript code minimally while adapting the project structure and configuration for Deno. We will start by modifying deno.json and src/proxy.ts.