# What Distribution Formats Are Available for kcmd?

> Explore the four kcmd distribution formats: npm package, PyPI library, standalone CLI, and embedded MCP server. Choose the best option for your project needs.

- Repository: [Google Cloud Platform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)
- Tags: api-reference
- Published: 2026-07-15

---

**`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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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:

```bash
npm install kcmd

```

### Usage Example

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

```typescript
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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/package.json) under the script:

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

```

This command compiles [`src/tool/main.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/src/tool/main.ts) into a single executable file at `dist/kcmd`. The entry point at [`toolbox/mdcode/src/tool/main.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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:

```bash

# 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:

```bash

# Start the MCP server in the background

kcmd mcp &

```

As documented in [`toolbox/mdcode/docs/design.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/./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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/package.json). The [`README.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/README.md) in the `toolbox/mdcode` directory provides installation instructions and usage examples for the npm package.