How CLI Mode Exposes All MCP Tools for Direct Invocation in codebase-memory-mcp

The Python CLI shim in codebase-memory-mcp works as a transparent wrapper that downloads the native binary and forwards all arguments directly to it, automatically exposing every MCP tool without reimplementation.

The codebase-memory-mcp repository provides a Python package that serves as a thin shim around a native compiled binary. This architecture allows the CLI mode to expose all MCP tools for direct invocation by delegating execution to the core engine, eliminating the need to duplicate command logic in Python while ensuring users always have access to the latest native toolset.

Entry Point and Module Execution

The package defines a minimal entry point in pkg/pypi/src/codebase_memory_mcp/__main__.py that simply imports and calls codebase_memory_mcp._cli.main(). This four-line module enables both console script execution and module-style invocation:

python -m codebase_memory_mcp init --path ./my/project

When executed as a module, the same initialization flow occurs as when using the installed console script entry point.

Binary Download and Caching Mechanism

The pkg/pypi/src/codebase_memory_mcp/_cli.py file implements the core logic for managing the native binary. On first run, the shim determines the current version using importlib.metadata.version with a fallback to "0.8.1", then constructs a platform-specific cache directory appropriate for Linux, macOS, or Windows.

If the binary for the detected version is missing, the _download() function constructs the correct release URL based on platform, architecture, and optional UI variant. The implementation enforces security by validating that the URL uses only HTTPS, then downloads the archive, verifies its SHA-256 checksum, and extracts the binary safely to the cache directory.

Argument Forwarding and Process Replacement

After guaranteeing the binary is present locally, the main() function builds a new argument list:

args = [str(bin_path)] + sys.argv[1:]

This construction preserves the exact command-line arguments passed by the user. On Unix-like systems, the shim uses os.execv to replace the current Python process entirely with the native binary, preserving the exact argument vector and process semantics. On Windows, it spawns a subprocess and exits with the binary's return code, ensuring consistent behavior across platforms.

Because the native binary implements all MCP sub-commands—including init, search, index, serve, run, and others—the Python wrapper automatically exposes the complete toolset without maintaining command-specific logic.

Available MCP Tools Through the CLI

The native binary accessed through the CLI wrapper provides the full suite of codebase memory operations:

• init – Initialize a new memory index for a project
• search – Query the indexed codebase using semantic or keyword search
• index – Update or rebuild the codebase index (supports --full for complete reindexing)
• serve – Start an MCP server instance (supports --port configuration)
• run – Execute specific MCP operations

All commands accept their native flags and arguments, passing directly through the Python shim unmodified.

Installation and Usage Examples

Install the package to add the CLI shim to your environment:

pip install codebase-memory-mcp

First run triggers the binary download and caching process:

codebase-memory-mcp init --path ./myrepo

# Downloads v0.8.1 (or latest) for your OS/arch, verifies checksum,

# extracts binary, then runs `init`.

Subsequent invocations use the cached binary directly:

codebase-memory-mcp search "machine learning"
codebase-memory-mcp index --full
codebase-memory-mcp serve --port 8080

Using the module form provides identical behavior:

python -m codebase_memory_mcp serve --port 9090

Security and Verification

The CLI implementation includes multiple safety mechanisms. The _download() function validates that all release URLs use HTTPS before requesting resources. Each downloaded archive undergoes SHA-256 checksum verification before extraction, preventing execution of corrupted or tampered binaries. The cache directory permissions follow OS-appropriate conventions, isolating the binary per user when possible.

Summary

• The CLI mode in codebase-memory-mcp functions as a transparent proxy to the native MCP binary, exposing all tools through argument forwarding.
• The __main__.py entry point and _cli.py module handle binary lifecycle management, including platform detection, caching, and secure downloads.
• Argument forwarding uses os.execv on Unix and subprocess spawning on Windows to delegate execution while preserving the exact command vector.
• Security features include HTTPS URL validation, SHA-256 checksum verification, and safe extraction to platform-appropriate cache directories.
• Users access the complete MCP toolset (init, search, index, serve, etc.) through standard pip installation without manual binary management.

Frequently Asked Questions

What happens if the binary is already cached?

When the binary exists in the cache directory for the detected version, the _cli.py module skips the download phase entirely and directly executes the cached executable. This eliminates network latency on subsequent runs while ensuring the binary is only downloaded once per version update.

Is the CLI wrapper cross-platform?

Yes, the implementation explicitly handles Linux, macOS, and Windows through platform detection in pkg/pypi/src/codebase_memory_mcp/_cli.py. It constructs OS-appropriate cache paths and uses os.execv for Unix-like systems while falling back to subprocess execution on Windows, ensuring consistent behavior across development environments.

How does the shim handle different versions?

The CLI determines the target version using importlib.metadata.version with a hardcoded fallback of "0.8.1". It organizes the cache directory by version, allowing multiple versions to coexist. When the package updates, the shim automatically fetches the corresponding new binary while preserving previous versions in the cache.

Can I use the CLI without installing via pip?

While the Python package requires installation to provide the entry point console script, the underlying native binary can be downloaded directly from the repository's releases page. However, using the pip installation provides automatic binary management, checksum verification, and seamless updates that manual binary management would lack.

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