# NOMA

NOMA is an open-source, read-only MCP gateway foundation for Korean public
data. It is designed to expose carefully bounded public-data capabilities to
MCP clients while keeping provider boundaries, licensing, security, and
operational behavior explicit.

The repository now contains the M1 public foundation, M2 secret/config
runtime, M3 provider applications, the M4 catalog/remote gateway and
digest-only key lifecycle, and the M5 setup CLI. The setup CLI configures all
four supported clients through a packaged stdio bridge; it does not claim
native remote/OAuth setup or external hosted deployment.

M7 adds executable release-acceptance harnesses for clean-clone installation,
self-hosted Streamable HTTP, security cases, Compose in CI, and an explicitly
authenticated hosted endpoint. Hosted/public registry verification remains an
external gate when its endpoint and access key are not available locally.
The local validator reports only `localBlockingContractViolations`; it does
not inspect GitHub issues or claim the final blocking-issues count is zero.

## Principles

- Read-only by contract: no mutation or destructive provider operation is part
  of the public gateway surface.
- Public boundary first: only clearly publishable material belongs here.
- Explicit provider isolation: each future provider is independently bounded,
  documented, and testable.
- Honest status: a directory or document boundary is not presented as a
  working provider or hosted service.

## Repository map

| Path | Responsibility | Status |
| --- | --- | --- |
| `apps/` | Runnable provider, catalog, and remote MCP applications | M3–M4 active |
| `packages/setup-cli/` | Client setup adapters and stdio-to-HTTP bridge | M5 active |
| `packages/` | Provider, catalog, gateway, and key lifecycle packages | M2–M4 active |
| `config/` | Future safe configuration contracts | Boundary only |
| `providers/` | Provider manifests and ownership boundaries | M3–M4 active |
| `deploy/` | Docker/Compose/systemd distribution contracts | M6 active |
| `evaluation/` | Future evaluation and acceptance contracts | Boundary only |
| `docs/architecture/` | Public architecture and boundary decisions | Active |
| `docs/providers/` | Provider onboarding, keys, and data-source contract | Active |
| `docs/release/` | Release and compatibility policy | Active |
| `scripts/` | Repository-level structural checks | Active |
| `test/` | Executable repository and M3/M4 validation tests | Active |

## Development

Requirements: Node.js 20 or newer and npm 10 or newer.

```sh
npm ci
npm run lint
npm run build
npm test
npm run verify:readonly
npm run verify:secrets
node scripts/validate-workflows.mjs
node scripts/validate-distribution.mjs
node scripts/contract-check.mjs
node scripts/validate-repository.mjs
git diff --check
npm audit --audit-level=high
npm run verify:m7
npm run verify:e2e:self-host
npm run verify:fresh
```

The commands validate the repository foundation, provider contracts, runtime
tests, gateway authentication, bounded shutdown, and secret/read-only
boundaries. Hosted deployment and external production connectivity are not
claimed by these local checks. `npm run verify:e2e:hosted` requires an
operator-provided HTTPS endpoint and access key through environment variables.

## Contributing and security

Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a change. Security
reports belong in the process described by [SECURITY.md](SECURITY.md). All
contributors are expected to follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

## License

NOMA is available under the [Apache License 2.0](LICENSE). Attribution and
third-party obligations are described in [NOTICE](NOTICE) and
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).