What Distribution Formats Are Available for kcmd?

kcmd provides four distribution formats: a TypeScript npm package for Node.js projects, a Python PyPI library for pipeline automation, a Bun-compiled standalone CLI binary for command-line workflows, and an embedded MCP server for agent-based RPC integration.

The kcmd tool in the GoogleCloudPlatform/knowledge-catalog repository delivers Knowledge Catalog functionality through multiple distribution formats designed for different consumption patterns. Developers can embed catalog-as-code capabilities directly into applications, run standalone commands, or expose operations via a language-agnostic server interface. Each format shares the same core abstractions—including CatalogManifest, CatalogSnapshot, and synchronization logic—while targeting specific runtime environments.

TypeScript Library Distribution

The TypeScript library is published on npm under the package name kcmd, providing first-class support for Node.js and TypeScript projects.

Installation and Configuration

According to toolbox/mdcode/package.json, the package exposes type definitions via the entry "types": "./build/ts/kcmd/index.d.ts". The compiled JavaScript output resides in dist/kcmd, while the source TypeScript files are located in toolbox/mdcode/src/libts.

Install the package via npm:

npm install kcmd

Usage Example

The library exposes classes such as CatalogManifest, CatalogSnapshot, and CatalogSync for programmatic catalog management:

import * as kcmd from 'kcmd';

// Create a manifest instance
const manifest = new kcmd.CatalogManifest({
  // …manifest configuration…
});

// Load a local snapshot with default GCP context
const snapshot = await kcmd.CatalogSnapshot.fromPath('/path/to/catalog', kcmd.gcp.ApiContext.default());

// Initialize and execute synchronization
const sync = new kcmd.CatalogSync(manifest, snapshot);
await sync.push();

This format is ideal for developers who need to embed catalog-as-code capabilities directly into their Node.js applications.

Python Library Distribution

The Python library is distributed via PyPI and mirrors the TypeScript API, enabling Python-based pipelines to interact with Knowledge Catalog metadata.

Teams building data pipelines or automation agents in Python can import the package to access CatalogManifest, CatalogSnapshot, and related classes. This ensures parity between TypeScript and Python implementations, allowing the same catalog operations across different language stacks.

CLI Binary Distribution

For users who prefer command-line workflows, kcmd ships as a standalone binary executable compiled with Bun.

Build Process

The build configuration is defined in toolbox/mdcode/package.json under the script:

"build:tool": "npx bun build --compile --outfile dist/kcmd src/tool/main.ts"

This command compiles src/tool/main.ts into a single executable file at dist/kcmd. The entry point at toolbox/mdcode/src/tool/main.ts handles CLI argument parsing and dispatches commands to the appropriate handlers.

Core CLI Commands

The binary supports several subcommands for catalog management:

# Initialize a snapshot from a BigQuery dataset

kcmd init --bigquery-dataset my-project.my_dataset

# Review local modifications before syncing

kcmd status

# Push local changes back to the catalog

kcmd push

# Pull remote state to local snapshot

kcmd pull

This distribution format requires no runtime dependencies, making it suitable for CI/CD pipelines and local development environments.

MCP Server Integration

The MCP server is embedded within the same CLI binary and activated via the mcp subcommand.

Running the server exposes Knowledge Catalog operations as tools for external agents over RPC:

# Start the MCP server in the background

kcmd mcp &

As documented in toolbox/mdcode/docs/design.md, this server provides a language-agnostic service endpoint for automation, agents, or long-running services that need to manipulate catalog manifests and snapshots programmatically. The MCP server leverages the same core logic as the TypeScript and Python libraries, ensuring consistent behavior across all distribution formats.

Summary

• TypeScript npm package: Available as kcmd on npm with types at ./build/ts/kcmd/index.d.ts, source in toolbox/mdcode/src/libts, targeting Node.js applications.
• Python PyPI library: Mirrors the TypeScript API for Python-based pipelines and automation scripts.
• CLI binary: Bun-compiled executable at dist/kcmd built from toolbox/mdcode/src/tool/main.ts, supporting init, status, push, pull, and mcp commands.
• MCP server: Embedded RPC server accessible via kcmd mcp, providing language-agnostic access to catalog operations for agents and services.

Frequently Asked Questions

How do I install the kcmd CLI binary from source?

Clone the GoogleCloudPlatform/knowledge-catalog repository and navigate to toolbox/mdcode. Run npm install followed by npm run build:tool, which executes npx bun build --compile --outfile dist/kcmd src/tool/main.ts to generate the standalone binary at dist/kcmd.

Can I use kcmd in a Python project without using the CLI?

Yes. The Python library is available on PyPI and provides the same CatalogManifest, CatalogSnapshot, and synchronization classes as the TypeScript implementation. Import the package directly into your Python scripts to interact with Knowledge Catalog metadata programmatically.

What is the difference between the CLI binary and the MCP server?

The CLI binary is a standalone executable for command-line interactions, while the MCP server is a mode of that same binary activated by the kcmd mcp command. The server runs continuously and exposes catalog operations as RPC tools for external agents, whereas the CLI executes discrete commands like push or status and exits.

Where can I find the API documentation for the TypeScript library?

The TypeScript source code and type definitions are located in toolbox/mdcode/src/libts, with the package entry point configured in toolbox/mdcode/package.json. The README.md in the toolbox/mdcode directory provides installation instructions and usage examples for the npm package.

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