# Contributing

Thanks for your interest in improving **mcp-gen-ui-gateway**.

## Prerequisites

- Node.js >= 22.5 (the gateway uses the built-in `node:sqlite`).
- pnpm (the repo pins a version via the `packageManager` field; `corepack enable` will pick it up).

## Setup

```bash
pnpm install
pnpm build       # workspace packages must build before typecheck/test resolve cross-package imports
pnpm typecheck
pnpm test
```

Useful scripts:

- `pnpm dev` — run the demo UI.
- `pnpm mcp` — run the stdio MCP server.
- `pnpm schemas` — re-export JSON Schema from the Zod source of truth.

## Project layout

```
packages/schema      Zod schemas (single source of truth) + JSON Schema export
packages/core        repository, recommender, sqlite-store, consistency, tool-service
packages/mcp-server  stdio MCP server exposing the gateway tools
apps/demo-ui         Vite + React renderer (domain JSON → A2UI adapter)
docs/                PRD, host prompts, git workflow, roadmap
```

## Working agreements

- **Schema is the contract.** Change `packages/schema` first, then run `pnpm schemas` and commit the regenerated JSON Schema.
- **Tests assert behavior, not internals.** Keep the suite fixture-first so it runs with no live dependencies.
- **No LLM in the server.** Orchestration belongs to the host.
- **Respect the safety boundary** (see below) in every change.

## Public API and versioning

The supported embedder surface is documented in the root README's Public API
section. Treat `BenefitRepository`, `BenefitToolService`, `SnapshotStore`, and
the Zod/JSON Schema contracts as the stable API within a release line;
`fixtureBenefits` is example data for tests and demos.

This repository uses SemVer, but packages are currently `0.x`: minor releases may
include breaking public API changes before 1.0. Keep patch releases
backward-compatible, and document any breaking 0.x minor in `CHANGELOG.md` and
the relevant README/docs.

## Safety boundary (public-benefit domain)

Do not introduce:

- Storage of sensitive identifiers (resident registration numbers, passwords, certificates, authentication tokens).
- Anything that presents recommendations as definitive legal eligibility.
- Login, identity verification, or form-submission automation.

## Pull requests

See `docs/git-workflow.md`. Branch from `main`, keep changes scoped, ensure
`build` / `typecheck` / `test` pass, and fill in the PR template's safety checklist.
Feature PRs that affect published packages must include a Changesets entry under
`.changeset/` describing the user-visible change and intended semver bump before
review; documentation-only and internal-only changes may omit one when they do not
change package behavior.

## Code of Conduct

This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).

## Attribution

This repository reimplements and maintains a project originally created by Team
KOI (https://github.com/koi2026/mcp-gen-ui-gateway). See `NOTICE`.