CommitGuard

Model Context Protocol (MCP) server for commitment-time operational risk: it aggregates production capacity, supplier reliability, workforce constraints, and contract terms, then simulates breach probability, expected value, and alternative scenarios (baseline, optional overtime, split delivery). A commitment_assistant prompt enforces simulate-then-analyze-then-optional-commit; commit_decision is confirmation-gated. Built with NitroStack; domain data is in-memory per module (*.data.ts); Zod on every tool; structured logging; Next.js widget at src/widgets/app/commit-review/.

Summary

CommitGuardModule (orchestration) plus ProductionModule, SupplierModule, WorkforceModule, and FinanceModule expose six tools — two on CommitGuard (simulate_commitment, commit_decision) and four read tools (get_current_capacity, get_supplier_reliability, get_workforce_constraints, get_contract_terms). No application @Resource handlers are defined under src/modules (the NitroStack runtime may still expose framework-level MCP resources such as health or widget examples—see Studio). One prompt (commitment_assistant) encodes a mandatory tool sequence and stateless parameter rules. One production widget is bound via @Widget on simulate_commitment → commit-review (scaffold pizza-* pages may remain under src/widgets/app/ from the NitroStack template; they are not wired to CommitGuard tools). dotenv is loaded at bootstrap; ConfigModule is registered on the app. simulate_commitment calls the four domain services internally, then CommitGuardService for breach/EV math and scenario selection. No database in this repo. No custom health module in src/; server logging is set in app.module.ts. Unit tests: not present in this tree; add beside modules (e.g. src/modules/**/__tests__/) when you introduce them.

Tech stack

Layer	Technology
Runtime	Node.js 20.x LTS recommended (or 18.x per NitroStack docs)
Language	TypeScript (ESM)
Framework	NitroStack MCP (@nitrostack/core, @nitrostack/cli)
State	In-memory domain services — production.data.ts, supplier.data.ts, workforce.data.ts, finance.data.ts (swap implementations for live APIs)
Validation	Zod
Config	dotenv + ConfigModule — optional .env at project root
UI	Next.js widgets under src/widgets/app/; CommitGuard uses commit-review

Business pain point

Operations and commercial teams struggle when:

• Signals are siloed — capacity in MES/ERP, supplier performance in another system, workforce and overtime in HRIS, penalties in contract/CRM, so no single view at decision time.
• Commitment math is repeated by hand — breach risk, penalty exposure, and “what if we split the order or run overtime” are rebuilt in spreadsheets for every deal.
• Assistants need one contract — not four dashboards — to run a consistent evaluate → compare scenarios → log intent flow.

CommitGuard exposes one MCP surface so NitroStudio (or any MCP client) can drive one orchestrated simulation (simulate_commitment) with a widget-backed review and an optional in-process decision log response from commit_decision (not persisted to disk or a database unless you add that).

Why NitroStack

Theme	Detail
Focused surface	Six tools, one prompt, one primary widget; clear Zod contracts and @Widget('commit-review') on the simulation tool.
Safety	Input schemas on tools; ctx.logger.info on handlers; no raw SQL; static demo data isolated in *.data.ts.
Orchestration	simulate_commitment aggregates four injected services before risk math — clients get one call for the full evaluation.
Less plumbing	NitroStack handles MCP wiring, modules, and lifecycle; domain logic stays in services and CommitGuardService.

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Client: NitroStudio or any MCP-capable client               │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│  NitroStack MCP server — `commitguard` (v1.0.0)            │
│  ├── Root: `AppModule` — ConfigModule, logging              │
│  ├── Production — `get_current_capacity`                    │
│  ├── Supplier   — `get_supplier_reliability`                │
│  ├── Workforce  — `get_workforce_constraints`               │
│  ├── Finance    — `get_contract_terms`                      │
│  └── CommitGuard — `simulate_commitment`, `commit_decision`   │
│                    + `commitment_assistant` prompt            │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│  UI: Next.js — `commit-review` (`src/widgets/app/…`)       │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│  Data: in-memory `*.data.ts`; decision log is in-process    │
│  only (lost on restart) unless you add persistence          │
└─────────────────────────────────────────────────────────────┘

Tools: simulate_commitment, commit_decision, get_current_capacity, get_supplier_reliability, get_workforce_constraints, get_contract_terms · Resources: no app-defined @Resource in src/modules · Prompts: commitment_assistant

Widgets (MCP-bound): commit-review — plus optional scaffold routes under src/widgets/app/ not registered to CommitGuard tools.

Manifest: src/widgets/widget-manifest.json (may still list template examples; align URIs and names with active @Widget routes before publishing.)

Data

No database is required for local development. Add a .env when you connect real APIs. Sample customer/supplier IDs are defined in the domain *.data.ts files (e.g. use in tool examples and simulations).

Data layer

Feature	Implementation
Domain reads	ProductionService, SupplierService, WorkforceService, FinanceService backed by *.data.ts — replace with ERP, risk, HRIS, and contract APIs in production.
Orchestration	simulate_commitment pulls all four domains, computes revenue, then CommitGuardService.simulateCommitment() for breach probability, scenarios, recommendedScenario, guardrailStatus, riskSeverity.
Overtime branch	“Approve Overtime” appears only when workforce.overtimeAvailable === true.
Decision logging	commit_decision requires confirmationToken === 'CONFIRMED_BY_USER'; logDecision returns a structured payload (in-memory only).

Prerequisites

• Node.js 20.x LTS (or 18.x per NitroStack docs)
• npm 9+ (see NitroStack Quick Start)
• Optional: npm i -g tsx for ad-hoc scripts

Setup

CLI

npm install -g @nitrostack/cli
nitrostack-cli --version

New project (Quick Start)

npx @nitrostack/cli init my-server
cd my-server
nitrostack-cli install

This repository

If you cloned a parent monorepo folder, cd into the project that contains package.json (often CommitGuard/). Otherwise run from the repo root.

cd CommitGuard
npm install
npm run install:all

No database URI is required. Add .env when wiring external systems. This repo may not ship .env.example.

NitroStudio

Open nitrostack.ai/studio and point Studio at the folder that contains this project’s package.json and src/ (the CommitGuard project root).

Optional sample data

Use inline examples on the retrieval tools and the IDs in src/modules/production/production.data.ts, src/modules/supplier/supplier.data.ts, src/modules/workforce/workforce.data.ts, and src/modules/finance/finance.data.ts. There are no MongoDB seed scripts.

Run

Development

Prefer NitroStudio with the project root above.

Or from the CommitGuard directory:

npm run dev

(nitrostack-cli dev in package.json.)

Production

npm run build
npm start

Skip forced rebuild:

npm run start:prod

Environment variables

Variable	Description	Notes
(optional) .env	Secrets for future integrations	Add when replacing *.data.ts with live APIs
NODE_ENV	development / production	Typical Node/NitroStack behavior
Logging	logging.level in app.module.ts	Default info

No MONGODB_URI — persistence is in-memory unless you extend the codebase.

Deployment

• Build: npm run build
• Configure: place .env at project root if using external APIs
• Run: npm start or npm run start:prod (keep cwd stable for .env resolution under PM2/systemd)
• Client: point NitroStudio (or other MCP client) at this directory (package.json + src/), not a parent folder

Troubleshooting

MCP connection / Studio

If Studio fails to connect: ensure the project path is this repo’s CommitGuard root (the folder with package.json), not a parent directory.

Check .mcp-bootstrap-error.log in the project root if present.

cd /path/to/CommitGuard
npm run dev

Watch stderr for missing deps or port conflicts. After src/ changes, rebuild or restart dev and reconnect Studio.

Empty widget / tool errors

For commit-review: open the tool trace in Studio; verify inputs match Zod (customerId, supplierId, quantity, unitPrice for simulate_commitment). For retrieval tools, use IDs present in the corresponding *.data.ts.

Decision logging

commit_decision rejects calls unless confirmationToken is exactly CONFIRMED_BY_USER.

Demo state

Domain demo values come from static *.data.ts modules (same on every process start). There is no server-side store for past commit_decision results—only the tool response in the current session. Set expectations for demos accordingly.

Testing

• Manual: exercise flows in NitroStudio using the Example interactions below and the domain data files.
• Automated: add unit tests beside modules (e.g. CommitGuardService breach/EV math); none are committed in this snapshot.

Tools reference

Tool	Description
simulate_commitment	Aggregates four domains, runs risk/scenario engine, returns evaluationId, scenarios, recommendation, guardrails · widget commit-review
commit_decision	Logs chosen scenario with guardrail context; requires CONFIRMED_BY_USER
get_current_capacity	capacityUtilization and bufferCapacityPercent (from productionState)
get_supplier_reliability	Delay probability and risk level for supplierId
get_workforce_constraints	Overtime availability and cost
get_contract_terms	customerTier, penaltyPercent, breachTolerance for customerId (defaults if unknown ID)

About

CommitGuard is a NitroStack MCP server for supply-chain-style commitment evaluation: multi-domain aggregation, quantified breach and expected value, scenario comparison, prompt-enforced workflow, and a review widget — with in-memory demo data and optional .env for real integrations.

Resources

Resource	Link
NitroStack (GitHub)	github.com/nitrocloudofficial/nitrostack
Docs	Quick Start · Install
CLI	Install · Init · Dev

Learning path

1. src/app.module.ts → imports Production, Supplier, Workforce, Finance, CommitGuard
2. commitguard.tools.ts — @Tool, @Widget('commit-review'), Zod
3. commitguard.service.ts — breach model, scenarios, logDecision
4. commitguard.prompts.ts — commitment_assistant sequence and parameter rules
5. Domain *.tools.ts / *.service.ts / *.data.ts — swap data layer for APIs
6. Match src/widgets/app/commit-review/ to widget name commit-review

Project structure

src/
├── index.ts
├── app.module.ts                 # commitguard MCP app
└── modules/
    ├── commitguard/
    │   └── commitguard.{module,tools,prompts,service,data}.ts
    ├── production/
    │   └── production.{module,tools,service,data}.ts
    ├── supplier/
    │   └── supplier.{module,tools,service,data}.ts
    ├── workforce/
    │   └── workforce.{module,tools,service,data}.ts
    └── finance/
        └── finance.{module,tools,service,data}.ts
src/widgets/
├── widget-manifest.json
└── app/
    └── commit-review/   … primary CommitGuard widget …

Resources & prompts

Kind	Names
Resources	no app-defined @Resource in src/modules (framework may add others)
Prompts	commitment_assistant

Health & observability

No custom @HealthCheck module ships under src/. Logging is configured on @McpApp in app.module.ts (level: 'info'). Use NitroStudio traces and server logs for operational visibility.

Example interactions

Full simulation

User: “Evaluate commitment for customer CUST-001, supplier SUP-ACME, 500 units at $200.”

→ simulate_commitment with all four parameters in the current message → commit-review widget with scenarios and recommendation.

Retrieval tools

User: “What’s our current capacity?” → get_current_capacity

User: “Supplier reliability for SUP-ACME?” → get_supplier_reliability

Decision log (after explicit confirmation)

→ commit_decision with confirmationToken: "CONFIRMED_BY_USER" and fields from the latest simulation output.

Code map

Area	File
Orchestration tools	src/modules/commitguard/commitguard.tools.ts
Risk / scenarios	src/modules/commitguard/commitguard.service.ts
Prompt	src/modules/commitguard/commitguard.prompts.ts
Domain tools	src/modules/production/production.tools.ts, supplier/supplier.tools.ts, workforce/workforce.tools.ts, finance/finance.tools.ts
Modules	*.module.ts under each folder
Root	app.module.ts

Extend & next steps

• Persist logDecision to PostgreSQL/SQLite for audit trails
• Replace *.data.ts with authenticated ERP, supplier-risk, HRIS, and contract APIs
• Add Vitest (or similar) for CommitGuardService and tool schemas
• Align widget-manifest.json with @Widget('commit-review') and remove unused scaffold entries if you drop template widgets

Tips

• Restarting the server resets in-memory data — document for demos
• Use commitment_assistant for consistent simulate-first behavior; keep tool examples updated for model steering
• Treat commitguard.data.ts as template artifact unless wired into tools

Roadmap

• Durable audit store for decisions
• Live integrations and auth for enterprise deployments
• Stronger governance (disclaimers, jurisdiction) on advisory outputs
• Automated test suite and CI
• Optional HTTP transport (see NitroStack deployment docs)

Contributing

Issues and PRs welcome for substantial changes. Preserve: Zod tool schemas, CommitGuardService semantics, @Widget name aligned with src/widgets/app/commit-review/, and clear logging — update this README when behavior changes.

Conclusion

CommitGuard is an MCP server for commitment-time risk arbitration across production, supplier, workforce, and contract signals — with NitroStack modules, in-memory demo data, optional .env for future APIs, a prompt-driven workflow, and a commit-review widget. Use it standalone, with NitroStudio, or as a reference for multi-domain orchestration MCP surfaces.

NitroStack: nitrostack.ai · Docs