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

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). 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, 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, which contains CatalogManifest, CatalogSnapshot, and CatalogSync. Google Cloud client integration lives in toolbox/mdcode/src/libts/gcp.ts, providing the ApiContext class. CLI command implementations are defined in toolbox/mdcode/src/tool/commands.ts. The architectural design is documented in toolbox/mdcode/docs/design.md. An example external agent consuming the SDK appears in toolbox/enrichment/src/agent/enrich/agent.ts.

Practical Usage Examples

Initialize a local snapshot from a BigQuery dataset:

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

Programmatic usage in 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:

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.

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