Components on Mergeway

Specification component

Mon, 01 Jan 0001 00:00:00 +0000

Specification component

The Mergeway specification defines how configuration, entity schemas, records, identifiers, references, and validation fit together in a file-based database. It is the contract shared by the CLI, Python SDK, Diff, MCP, LSP, and editor integrations.

Who it is for

Schema authors, tool integrators, and maintainers use the specification when they need exact repository behavior rather than a workflow. Most first-time users should begin with the tutorial or repository-model explanation.

CLI

Mon, 01 Jan 0001 00:00:00 +0000

CLI

mergeway-cli is the general-purpose command-line interface for creating and inspecting records, validating and formatting repositories, and exporting repository data. It implements the Mergeway specification and supplies the validation foundation used by other components.

Who it is for

Repository maintainers, data and platform engineers, schema authors, and automation use the CLI for direct repository operations.

Purpose and boundaries

The CLI creates, reads, updates, and deletes records; inspects entities and files; formats and validates repositories; and exports data. It is not an interactive editor, semantic Git diff engine, MCP server, language server, or Python API; the other components cover those roles.

Diff

Mon, 01 Jan 0001 00:00:00 +0000

Diff

mergeway-diff compares two repository snapshots and reports semantic record changes. It builds on the same repository model as the CLI so reviewers and automation can reason about added, modified, and removed data rather than only changed lines.

Who it is for

Reviewers, repository maintainers, and CI authors use Diff when a text diff does not clearly express the logical data change.

Purpose and boundaries

Diff compares committed revisions or a revision and working-tree state, then describes record-level additions, modifications, and removals. It does not modify records, replace repository validation, or serve as a general text-diff tool.

Python SDK

Mon, 01 Jan 0001 00:00:00 +0000

Python SDK

mergeway-python is the Python automation layer for Mergeway repositories. The published mergeway package on PyPI wraps mergeway-cli, uses the CLI’s JSON output as its data boundary, and can generate typed Python models from a repository schema.

Who it is for

Python application developers, data engineers, and automation authors use the SDK when shelling out to the CLI directly would make typed application code difficult to maintain.

Purpose and boundaries

The SDK can read, create, update, and delete records; validate and format a repository; export repository data; and generate Python dataclasses from mergeway.yaml. It is an automation wrapper, not a separate storage engine or independent implementation of the repository specification.

MCP

Mon, 01 Jan 0001 00:00:00 +0000

MCP

mergeway-mcp is a Model Context Protocol server for read-only inspection of a Mergeway repository. It lets compatible clients discover entities and records while using the suite’s shared loading and validation behavior.

Who it is for

AI-tool users and client integrators use MCP when a compatible client needs structured, controlled access to repository data.

Purpose and boundaries

The server exposes read-only discovery and inspection through MCP over stdio or HTTP. Entity allow-listing can narrow the visible model. It does not create, update, or delete records, and read-only tools do not by themselves make an untrusted transport or client safe.

LSP

Mon, 01 Jan 0001 00:00:00 +0000

LSP

mergeway-lsp is a Language Server Protocol server that gives editors repository-aware diagnostics and navigation. It reuses Mergeway’s configuration, data, and validation behavior so editor feedback aligns with command-line validation.

Who it is for

Repository authors who want feedback while editing and editor/plugin authors who need a standards-based integration use LSP.

Purpose and boundaries

The server provides diagnostics and repository-aware navigation over stdio. It is not a standalone terminal UI, does not replace final CLI validation, and does not install or configure an editor integration by itself. Standard output is reserved for protocol traffic.

VS Code

Mon, 01 Jan 0001 00:00:00 +0000

VS Code

The Mergeway VS Code extension connects Visual Studio Code to mergeway-lsp. It is the suite’s editor-specific integration and depends on the language server for diagnostics and navigation.

Who it is for

VS Code users are the intended audience for the extension. Extension contributors can build and test it from this repository.

Purpose and boundaries

The extension connects editor documents and user actions to Mergeway language features. It does not define repository behavior and does not bundle the language server. The CLI remains the explicit final validation and automation interface.