# Core Components of the kcmd Architecture: CLI, SDK, and MCP Server Explained

> Understand the core components of the kcmd architecture including CLI, SDK, and MCP Server. Enable interactive use and programmatic integration with Google Cloud Knowledge Catalog.

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

---

**The kcmd architecture comprises five composable layers—the CLI binary, Core SDK, MCP Server, Enrichment Agent, and Build system—that enable both interactive command-line usage and programmatic integration with Google Cloud Knowledge Catalog.**

The kcmd tool serves as the command-line front-end for the Google Cloud Knowledge Catalog SDK. According to the GoogleCloudPlatform/knowledge-catalog source code, its architecture is deliberately split into independent, composable layers so that the same core logic can be reused by the CLI, external agents via the MCP server, and library consumers in TypeScript or Python.

## The Five Core Components of kcmd

### CLI (kcmd Binary)

The CLI is the user-facing entry point built with **Bun** and the **cac** argument parser. It parses sub-commands including `init`, `pull`, `push`, `status`, and `mcp`, instantiates SDK objects like `CatalogManifest` and `CatalogSnapshot`, and handles local I/O operations. When the `mcp` sub-command is invoked, it spawns an HTTP-based MCP server inside the same process rather than executing a catalog operation directly.

### Core SDK (kcmd TypeScript Package)

The Core SDK is the shared library that implements all catalog-related functionality. It exposes four primary classes:

- **CatalogManifest**: Describes the logical view of a Knowledge Catalog, including BigQuery datasets, Dataplex entry groups, and Knowledge Bases.
- **CatalogSnapshot**: Captures a point-in-time local copy of catalog metadata stored in the `.kcmd/` directory.
- **CatalogSync**: Computes diffs between a manifest and snapshot and applies changes during push/pull operations.
- **gcp.ApiContext**: A thin wrapper around Google Cloud authentication and clients used throughout the SDK.

### MCP Server (Metadata-Control-Protocol)

The MCP Server is a lightweight HTTP server that exposes SDK operations as remote endpoints. Running inside the same binary when `kcmd mcp` is invoked, it registers the same operations (`init`, `pull`, `push`, `status`) as HTTP endpoints, typically on `localhost:8080`. This allows external agents to invoke catalog actions via standard HTTP requests rather than importing the library directly.

### Enrichment Agent (Optional)

The Enrichment Agent demonstrates how external processes can drive catalog updates. It imports the `kcmd` library (or communicates with the MCP server) to retrieve a `CatalogSnapshot`, enriches entries with AI-generated summaries, and writes changes back via `CatalogSync`. This illustrates the end-to-end flow: `kcmd init → snapshot → enrichment → kcmd push`.

### Build and Distribution Layer

This layer packages TypeScript sources as both a binary and npm module. It uses **Bun** to compile the CLI into a single executable (`dist/kcmd`) and emits type definitions ([`build/ts/kcmd/index.d.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/build/ts/kcmd/index.d.ts)). The library is published to npm as `kcmd`, enabling consumers to either run the binary directly or import the library via `import * as kcmd from 'kcmd'`.

## How the Components Interact

1. The user runs `kcmd ...` and the CLI parses the command using `cac`.
2. The CLI creates a `gcp.ApiContext` with default credentials and loads a `CatalogManifest` from BigQuery, Dataplex, or Knowledge Base sources.
3. For stateful operations, the CLI reads a `CatalogSnapshot` from the local `.kcmd/` directory.
4. `CatalogSync` computes the diff between the manifest and snapshot, applying create/update/delete operations against the Knowledge Catalog API.
5. When using the `mcp` sub-command, steps 1-4 are wrapped in an HTTP server, allowing remote agents to invoke the same logic via POST requests to endpoints like `http://localhost:8080/push`.

## Key Implementation Files

In [`toolbox/mdcode/src/tool/main.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/main.ts), the entry point sets up the `cac` CLI and dispatches to commands or the MCP server. The core library implementation resides in [`toolbox/mdcode/src/libts/catalog.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/libts/catalog.ts), which contains `CatalogManifest`, `CatalogSnapshot`, and `CatalogSync`. Google Cloud client integration lives in [`toolbox/mdcode/src/libts/gcp.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/libts/gcp.ts), providing the `ApiContext` class. CLI command implementations are defined in [`toolbox/mdcode/src/tool/commands.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/commands.ts). The architectural design is documented in [`toolbox/mdcode/docs/design.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/docs/design.md). An example external agent consuming the SDK appears in [`toolbox/enrichment/src/agent/enrich/agent.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/enrichment/src/agent/enrich/agent.ts).

## Practical Usage Examples

Initialize a local snapshot from a BigQuery dataset:

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

```

Programmatic usage in TypeScript:

```typescript
import * as kcmd from 'kcmd';

// Create an API context using Application Default Credentials
const ctx = kcmd.gcp.ApiContext.default();

// Build a manifest for a BigQuery dataset
const manifest = await kcmd.CatalogManifest.initWithBigQuery(
  ['my-project.my_dataset'],
  ctx,
);

// Load or create a local snapshot
const snapshot = await kcmd.CatalogSnapshot.fromPath('.kcmd', ctx);

// Synchronize changes to push new entries
const sync = new kcmd.CatalogSync(manifest, snapshot);
await sync.apply();

```

Running the MCP server:

```bash
kcmd mcp  # Starts HTTP server on localhost:8080

```

External agents can then POST to `http://localhost:8080/push` to trigger catalog operations without direct library imports.

## Summary

- The kcmd architecture separates concerns into five distinct layers: CLI, Core SDK, MCP Server, Enrichment Agent, and Build system.
- **CatalogManifest**, **CatalogSnapshot**, and **CatalogSync** form the core abstraction layer for managing Knowledge Catalog metadata.
- The MCP server enables language-agnostic integration by exposing SDK functionality via HTTP endpoints.
- Bun compilation produces both a standalone binary and an npm package for TypeScript consumers.
- Source files in `toolbox/mdcode/src/` implement the CLI and SDK logic, while `toolbox/enrichment/` provides integration examples.

## Frequently Asked Questions

### What is the difference between the kcmd CLI and the Core SDK?

The kcmd CLI is a command-line interface built with Bun and cac that provides user-facing commands for interactive catalog management. The Core SDK is the underlying TypeScript library containing the business logic for manifests, snapshots, and synchronization, which the CLI consumes and which can also be imported directly into other TypeScript or Python applications.

### How does the MCP server enable external agent integration?

The MCP server exposes the Core SDK operations as HTTP endpoints, allowing external processes to invoke catalog actions via standard web requests rather than importing the library. When `kcmd mcp` is executed, the server runs on `localhost:8080` and accepts POST requests to endpoints like `/push`, translating these into SDK method calls while maintaining the same authentication and validation logic.

### Can I use kcmd in a Python environment?

Yes, while the Core SDK is implemented in TypeScript, Python applications can interact with kcmd either by installing the npm package and calling it as a subprocess, or more commonly by communicating with the MCP server via HTTP requests. The architecture is designed to be language-agnostic at the integration layer.

### What is the role of CatalogSync in the kcmd architecture?

`CatalogSync` is the orchestration class that computes differences between a `CatalogManifest` (the desired state from BigQuery or Dataplex) and a `CatalogSnapshot` (the local state). It generates and applies the necessary create, update, and delete operations to synchronize the Knowledge Catalog, handling the bidirectional flow of metadata during both push and pull operations.