How to Use CLI Mode MCP Tools from the Command Line

The Codebase Memory MCP package provides a Python shim in codebase_memory_mcp/_cli.py that automatically downloads, verifies, and caches the correct native binary for your platform, securely forwarding all command-line arguments to the underlying MCP tools.

The DeusData/codebase-memory-mcp repository delivers a production-ready command-line interface for managing Model Context Protocol (MCP) memory operations. When you use CLI mode MCP tools from the command line, a lightweight Python bootstrap shim handles cross-platform binary distribution, cryptographic verification, and secure execution without requiring manual toolchain management.

Installation and Entry Points

Once installed via pip install codebase-memory-mcp, you can invoke the CLI through two equivalent methods:

• Direct entry point: codebase-memory-mcp --help
• Module execution: python -m codebase_memory_mcp --version

Both routes resolve to the main() function defined in pkg/pypi/src/codebase_memory_mcp/__main__.py, which imports the bootstrap logic from pkg/pypi/src/codebase_memory_mcp/_cli.py.

How the CLI Shim Works

The shim executes an eight-step pipeline to safely provision and run the native MCP binary:

1. Version Detection – Queries importlib.metadata.version for the installed package version, falling back to the bundled _version string if metadata is unavailable.

2. Platform Selection – Inspects sys.platform (linux, darwin, win32) and platform.machine() (arm64, amd64) to construct the download URL targeting https://github.com/DeusData/codebase-memory-mcp/releases/download/v{version}/{archive}.

3. URL Validation – The _validate_url_scheme function enforces https:// exclusively, preventing accidental file or ftp fetches.

4. Binary Download – Uses urllib.request.urlretrieve within a temporary directory, displaying progress messages like codebase-memory-mcp: downloading v0.8.1 for linux/amd64....

5. Checksum Verification – The _verify_checksum function computes the SHA-256 hash of the downloaded archive and validates it against the official checksums.txt published for that release; mismatches trigger immediate abort.

6. Safe Extraction – Archives are processed by _safe_extract_tar and _safe_extract_zip, which sanitize file paths to prevent "zip-slip" directory traversal vulnerabilities.

7. Binary Caching – The extracted executable is copied to the directory returned by _cache_dir (typically <platform-specific>/codebase-memory-mcp/{version}), marked executable, and reused in future invocations.

8. Process Execution – On Unix, the shim uses os.execv to replace the Python process with the native binary; on Windows, it uses subprocess.run. All original sys.argv arguments forward directly without shell interpretation, eliminating injection risks.

Running MCP Commands

After the initial download and caching, you can use CLI mode MCP tools command line operations transparently:

# Analyze a project directory

codebase-memory-mcp analyze --path ./my_project

# Check installed version

codebase-memory-mcp --version

# Alternative module invocation

python -m codebase_memory_mcp analyze --path ./src

First-time initialization displays download progress, while subsequent runs execute instantly from the cache located at paths like $HOME/.cache/codebase-memory-mcp/0.8.1/codebase-memory-mcp.

Summary

• The CLI shim in pkg/pypi/src/codebase_memory_mcp/_cli.py automates platform detection, secure downloading, and binary caching when you use CLI mode MCP tools from the command line.
• Security features include HTTPS-only URL validation (_validate_url_scheme), SHA-256 checksum verification (_verify_checksum), and path-traversal protection during extraction (_safe_extract_tar, _safe_extract_zip).
• Entry points include both the codebase-memory-mcp command and python -m codebase_memory_mcp, both triggering the same bootstrap logic in pkg/pypi/src/codebase_memory_mcp/__main__.py.
• Caching occurs in per-user directories determined by _cache_dir, eliminating redundant network operations across sessions.
• Execution uses os.execv on Unix and subprocess.run on Windows, forwarding arguments directly without shell involvement.

Frequently Asked Questions

Where does the Codebase Memory MCP CLI store downloaded binaries?

The shim caches the native executable in a per-user directory determined by the _cache_dir function, typically resolving to $HOME/.cache/codebase-memory-mcp/{version}/ on Linux, ~/Library/Caches/codebase-memory-mcp/{version}/ on macOS, or %LOCALAPPDATA%\codebase-memory-mcp\{version}\ on Windows. This location is validated on every invocation, allowing subsequent runs to skip the download process entirely.

How does the CLI verify the integrity of downloaded files?

According to the source code in pkg/pypi/src/codebase_memory_mcp/_cli.py, the _verify_checksum function calculates the SHA-256 hash of the downloaded archive and compares it against the expected hash listed in the release's checksums.txt file. If the hashes do not match, the process aborts immediately before extraction, preventing the execution of corrupted or malicious binaries.

Can I run the tool without adding it to my system PATH?

Yes. You can invoke the CLI using Python's module execution syntax: python -m codebase_memory_mcp [arguments]. This method executes the main() function defined in codebase_memory_mcp/__main__.py, which triggers the same download, caching, and execution logic as the direct codebase-memory-mcp entry point, making it ideal for virtual environments or CI pipelines where PATH modification is restricted.

What platforms are supported by the CLI shim?

The shim automatically detects your operating system via sys.platform (linux, darwin, win32) and architecture via platform.machine() (arm64, amd64) to select the appropriate binary from the GitHub releases page. This platform-specific selection ensures you receive a native executable optimized for your system without manual intervention, as implemented in the _download logic of pkg/pypi/src/codebase_memory_mcp/_cli.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}