Rbanh/schemeta
1
0
Fork 0
Code Issues 11 Pull Requests Actions 1 Packages Projects Releases Wiki Activity

MCP/API productionization: versioned contracts, auth model, and operational docs #9

New Issue
Closed
opened 2026-02-16 21:47:36 -05:00 by Rbanh · 6 comments
Rbanh commented 2026-02-16 21:47:36 -05:00
Owner
Copy Link

Problem

Schemeta has MCP + REST surfaces, but production adoption needs explicit versioning, auth/permissions boundaries, and operator guidance.

Goal

Make API/MCP integration reliable and enterprise-ready.

Scope

  • Define versioned schema/API compatibility policy.
  • Add authentication/authorization strategy for hosted deployments.
  • Add rate limiting and request size safeguards.
  • Add operational docs: deployment, backup, incident/debug playbook.
  • Add API contract tests for compile/analyze/mcp tool outputs.

Acceptance Criteria

  • Clear API versioning and compatibility guarantees documented.
  • Hosted mode security controls defined and validated.
  • MCP tool outputs validated via automated contract tests.
  • Operator runbook available in repository docs.
## Problem Schemeta has MCP + REST surfaces, but production adoption needs explicit versioning, auth/permissions boundaries, and operator guidance. ## Goal Make API/MCP integration reliable and enterprise-ready. ## Scope - Define versioned schema/API compatibility policy. - Add authentication/authorization strategy for hosted deployments. - Add rate limiting and request size safeguards. - Add operational docs: deployment, backup, incident/debug playbook. - Add API contract tests for compile/analyze/mcp tool outputs. ## Acceptance Criteria - Clear API versioning and compatibility guarantees documented. - Hosted mode security controls defined and validated. - MCP tool outputs validated via automated contract tests. - Operator runbook available in repository docs.
Rbanh added this to the Phase 2 - Production Polish milestone 2026-02-16 21:47:42 -05:00
Rbanh commented 2026-02-16 22:08:59 -05:00
Author
Owner
Copy Link

Implemented first productionization slice for Issue #9 in commit 3cb6fee.

Shipped

  • Added explicit envelope version metadata for REST responses:
    • api_version
    • schema_version
  • Added same version metadata for MCP tool outputs (schemeta_compile, schemeta_analyze, schemeta_ui_bundle).
  • Added version metadata to /health and /mcp/ui-bundle endpoints.
  • Documented current version values and compatibility note in README.

Validation

  • Syntax checks pass.
  • Existing tests pass.

Remaining for Issue #9

  • AuthN/AuthZ model for hosted deployments.
  • Rate limiting + request safeguards beyond max body bytes.
  • Contract test suite for API/MCP response envelopes and backward compatibility policy enforcement.
Implemented first productionization slice for Issue #9 in commit `3cb6fee`. ### Shipped - Added explicit envelope version metadata for REST responses: - `api_version` - `schema_version` - Added same version metadata for MCP tool outputs (`schemeta_compile`, `schemeta_analyze`, `schemeta_ui_bundle`). - Added version metadata to `/health` and `/mcp/ui-bundle` endpoints. - Documented current version values and compatibility note in README. ### Validation - Syntax checks pass. - Existing tests pass. ### Remaining for Issue #9 - AuthN/AuthZ model for hosted deployments. - Rate limiting + request safeguards beyond max body bytes. - Contract test suite for API/MCP response envelopes and backward compatibility policy enforcement.
Rbanh commented 2026-02-17 00:47:15 -05:00
Author
Owner
Copy Link

Implemented another Issue #9 hardening slice in commit 9ee97ff.

Shipped

  • Added per-client POST request throttling in src/server.js for:
    • /compile
    • /analyze
    • /layout/auto
    • /layout/tidy
  • Added configurable env var:
    • MAX_REQUESTS_PER_MINUTE (default 120)
  • Added 429 rate_limited response envelope on limit exceed.
  • Documented operational limits in README (MAX_BODY_BYTES, MAX_REQUESTS_PER_MINUTE).

Validation

  • Syntax checks pass.
  • Existing tests pass.

Remaining for Issue #9

  • AuthN/AuthZ strategy for hosted mode.
  • API/MCP contract tests for envelope and compatibility behavior.
  • Operator runbook details (incident/debug procedures).
Implemented another Issue #9 hardening slice in commit `9ee97ff`. ### Shipped - Added per-client POST request throttling in `src/server.js` for: - `/compile` - `/analyze` - `/layout/auto` - `/layout/tidy` - Added configurable env var: - `MAX_REQUESTS_PER_MINUTE` (default `120`) - Added `429 rate_limited` response envelope on limit exceed. - Documented operational limits in README (`MAX_BODY_BYTES`, `MAX_REQUESTS_PER_MINUTE`). ### Validation - Syntax checks pass. - Existing tests pass. ### Remaining for Issue #9 - AuthN/AuthZ strategy for hosted mode. - API/MCP contract tests for envelope and compatibility behavior. - Operator runbook details (incident/debug procedures).
Rbanh commented 2026-02-18 20:37:59 -05:00
Author
Owner
Copy Link

Operations slice delivered in main via commit 7b6b176.

Delivered:

  • Added docs/operations-runbook.md with runtime/env vars, endpoint checks, incident playbook, release/rollback steps, and observability recommendations.
  • README now points to ops docs.

This complements the server-side API/schema metadata + rate-limiting hardening already shipped for #9.

Operations slice delivered in `main` via commit `7b6b176`. Delivered: - Added `docs/operations-runbook.md` with runtime/env vars, endpoint checks, incident playbook, release/rollback steps, and observability recommendations. - README now points to ops docs. This complements the server-side API/schema metadata + rate-limiting hardening already shipped for #9.
Rbanh commented 2026-02-18 20:41:10 -05:00
Author
Owner
Copy Link

Contract-test slice completed in main via commit 925f807.

Delivered:

  • Added tests/api-contract.test.js covering stable REST/MCP contract envelopes.
  • Added assertions for compile/analyze contract shape, version metadata, and stable error envelope fields.
  • Added MCP contract checks for schemeta_compile, schemeta_analyze, schemeta_ui_bundle, and tool listing.
  • Refactored src/server.js and src/mcp-server.js to be import-safe for tests (no side effects when imported).

Result: npm test now validates both compile behavior and API/MCP contract stability.

Contract-test slice completed in `main` via commit `925f807`. Delivered: - Added `tests/api-contract.test.js` covering stable REST/MCP contract envelopes. - Added assertions for compile/analyze contract shape, version metadata, and stable error envelope fields. - Added MCP contract checks for `schemeta_compile`, `schemeta_analyze`, `schemeta_ui_bundle`, and tool listing. - Refactored `src/server.js` and `src/mcp-server.js` to be import-safe for tests (no side effects when imported). Result: `npm test` now validates both compile behavior and API/MCP contract stability.
Rbanh commented 2026-02-18 20:59:31 -05:00
Author
Owner
Copy Link

Hosted-mode auth controls are now implemented in main via commit bfb8275.

Delivered:

  • Added optional API token enforcement via SCHEMETA_AUTH_TOKEN.
  • When configured, all POST API routes require one of:
    • Authorization: Bearer <token>
    • x-api-key: <token>
  • Unauthorized requests return 401 with WWW-Authenticate: Bearer and stable error envelope.
  • Added automated auth tests in tests/auth.test.js.
  • Updated README + operations/release docs with auth env/configuration and validation steps.

Validation: npm test passes (includes auth coverage).

Hosted-mode auth controls are now implemented in `main` via commit `bfb8275`. Delivered: - Added optional API token enforcement via `SCHEMETA_AUTH_TOKEN`. - When configured, all POST API routes require one of: - `Authorization: Bearer <token>` - `x-api-key: <token>` - Unauthorized requests return `401` with `WWW-Authenticate: Bearer` and stable error envelope. - Added automated auth tests in `tests/auth.test.js`. - Updated README + operations/release docs with auth env/configuration and validation steps. Validation: `npm test` passes (includes auth coverage).
Rbanh commented 2026-02-18 21:02:52 -05:00
Author
Owner
Copy Link

Final closure summary:

  • API/MCP responses include versioned contract metadata (api_version, schema_version).
  • Added request-size limits, rate limiting, and optional hosted auth token enforcement (SCHEMETA_AUTH_TOKEN).
  • Added import-safe API/MCP contract tests and auth tests.
  • Added operations runbook + release checklist docs.

Key commits: 3cb6fee, 9ee97ff, 7b6b176, 925f807, bfb8275.

Final closure summary: - API/MCP responses include versioned contract metadata (`api_version`, `schema_version`). - Added request-size limits, rate limiting, and optional hosted auth token enforcement (`SCHEMETA_AUTH_TOKEN`). - Added import-safe API/MCP contract tests and auth tests. - Added operations runbook + release checklist docs. Key commits: `3cb6fee`, `9ee97ff`, `7b6b176`, `925f807`, `bfb8275`.
Rbanh closed this issue 2026-02-18 21:03:41 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
No items
No Label
Milestone
Clear milestone
No items
No Milestone
Phase 2 - Production Polish
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: Rbanh/schemeta#9
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?