Shared Room MCP

Powered by Adaptive Contract MCP.

Shared Room MCP is the reference application for Adaptive Contract MCP, an open-source trust boundary layer for form-based async state rooms on the agent-native web. It is not a chatroom, messaging app, payment gateway, or auto-booking agent. A host creates a single-direction private task from evidence, the assistant prepares structured review drafts, and invited members only act on their own assigned or selected part.

Live demo: https://shared-room-mcp-next.zeabur.app/

The app is English-first for judging and demo review. A Chinese UI dictionary remains available for local use, but the default page language, initial HTML, README, and submission packet are English.

Core claim: AI prepares the evidence review. Humans approve the commitment. The assistant can read the room, spot missing details, and prepare structured drafts. The host controls publication to members, and each member confirms only their own task/cost state.

Language boundary: WebMCP tool names, schemas, descriptions, and JSON keys stay in English so the browser/sidebar agent receives a stable tool contract. User-provided evidence keeps its original language, so a Chinese group-buy post can still produce Chinese item names in the room.

In the browser sidebar, the assistant uses WebMCP tools from the page itself. Here WebMCP means a page-local state reader and draft generator, not a browser agent that clicks or submits final actions for the user. It inspects the private room state and places draft suggestions on the page for human review.

The intended loop is WebMCP plus Codex as a private task-review layer. Codex can inspect the room, compare the price evidence against the current list, and create a field-fix draft when a price list is read incorrectly, for example when quantity, subtotal, size, or add-on notes are confused with item prices. That draft waits for host review before the member-facing task list changes.

The review layer uses Semantic Visual Anchors: each extracted field keeps its evidence snippet, logical image zone, detected type hint, and review-gate reason so the host can compare the candidate against the source context. Pixel-level crop and bounding-box overlays are reserved in the schema as a roadmap extension; they are not required for the current deterministic integration benchmark.

Semantic Visual Anchor Notice: this system currently implements semantic visual anchoring with hierarchical logical zones (boundingZone) paired with contextual snippets (auditAnchor). Pixel-level spatial boxes (bbox) and crop overlays are reserved protocol fields for a future visual review overlay.

Why This Fits WebMCP

Many real-world commitments now start from messy evidence: creator posts, price images, service forms, booking pages, campaign notes, receipts, copied text, or screenshots. These flows rarely have stable APIs or clean data. The host often has only a screenshot, a public post, or a partial form.

WebMCP is a good fit because the assistant can enter the same private task room as the host, read the current state through page tools, find missing confirmations, and prepare the next review action from structured room state.

Related MCP server: Concord

How We Checked It

The demo is not only a single happy-path recording. Before submission, the room flow was repeated locally and against deployed versions of the app.

The full check summary is in docs/testing/VALIDATION_EVIDENCE.md.

These checks show that the assistant workflow is repeatable and no-key by default. They are not a claim of production-scale database capacity. The default JSON save layer is for a single demo service; production traffic should use Redis or PostgreSQL.

Core Product Boundary

This is a single-direction task room. The host provides evidence and performs the Member-Visibility Release after review; members select or confirm only their own part; final commitment stays behind the host/member review gates.

Shared Room MCP is the demo application and repository slug. Adaptive Contract MCP is the underlying contract, routing, prompt, guardrail, and HITL state-machine layer. The architecture name is used where the project discusses reusable scenario contracts, image-fixture oracles, enterprise submission gates, and anti-pollution review controls.

AI provider keys are optional:

• Pasted text and local rule-based parsing run first.

• Gemini or OpenAI support is only an optional image/text repair example.

• The core WebMCP workflow must work without any paid API key.

• AI output remains evidence review, field repair, proposal drafting, and state guidance.

• WebMCP is the primary agent integration; external model APIs are not required for the agent workflow.

Open Source Tool-Layer Positioning

This repository is intended to be a clean, forkable WebMCP starter project. It does not sell API access, resell model credits, require store integration, or require a fixed OCR provider.

Deployment owners can keep the default no-key flow, remove the optional provider code, or replace it with their own OCR, vision, browser, commerce, spreadsheet, or private-community integrations. The stable part is the shared room workflow and the WebMCP tools, not any paid API.

External developers should be able to fork the template and plug in their own integrations without asking for access to a central service. High-risk commitments stay behind explicit host/member confirmation.

Reviewed rooms can export a local HTML or PDF review record as evidence of the private room decision state.

Future Extension Modules

The group cost room is the first reference use case, not the product boundary. The project is best for workflows where the assistant can prepare a draft and people still need to review it before an irreversible action.

Core extension examples:

• Activity signup draft: collect attendee names, ticket classes, dietary notes, and prepare a registration task proposal.

• Community purchase comparison: summarize options, threshold rules, and member interest before anyone pays.

• Maintenance or warranty request draft: organize receipt text, product model, photos, and contact fields for human review.

• Private community task coordination: turn host-provided evidence into tasks, owners, and review steps.

• Shared booking draft: collect time slots, member availability, room/court/package options, and prepare a booking task proposal.

Possible future integrations:

• Auto repair appointment draft: collect car model, symptoms, preferred time, shop notes, and create a booking task proposal for the owner to confirm.

• Nail, hair salon, clinic, or local service reservation draft: gather service type, preferred time, staff preference, notes, and prepare a reservation task proposal. Service details remain structured notes for the provider, not an in-room conversation channel.

The hackathon demo should focus on the single-direction room workflow: host creates the task, assistant prepares evidence review, invited members act on their own rows, and final confirmation remains human-controlled.

Repository slug: shared-room-mcp.

Commercial Extension Model

The open-source core is the WebMCP room template: room types, shared state, local math, review steps, and assistant-readable tools. Commercialization should happen through replaceable integrations, not hard-coded platform lock-in.

Potential integration categories:

• Booking integrations for auto repair shops, salons, clinics, local services, and venue reservations.

• Commerce integrations for product catalogs, group-buy thresholds, inventory checks, discount rules, and checkout handoff.

• Community integrations for LINE, Discord, Telegram, forums, and private membership spaces.

• Trust integrations for whitelist checks, short-lived invite validation, review logs, and organization policy checks.

• Provider integrations for OCR, vision, translation, summarization, and field repair.

This keeps the template useful for developers and safer for users: the project can support future business workflows while keeping irreversible commitments in purpose-built partner systems and explicit human review gates.

WebMCP Tools

The browser page registers tools with document.modelContext.registerTool() when WebMCP is available.

Implemented tools:

• inspect_room

• get_task_router

• get_claim_audit

• get_formula_contract

• get_trust_layer_contract

• suggest_next_actions

• create_action_proposal

The suggest_next_actions tool is the main way for the assistant to read the room and suggest what should happen next. It points out missing reviews, missing confirmations, and evidence/field mismatches from structured room state.

The create_action_proposal tool creates a host-reviewed draft. Supported drafts include claim review, missing confirmation, evidence review, room type review, activity signup drafts, and field-fix drafts when Codex notices a reading mistake. The page keeps only one pending draft per draft type, so the host sees one clear card for one decision. The host presses the same card button to arm and confirm the review before the room state changes.

Safety Flow

The UI uses plain language, and the code keeps the same order every time: AI prepares a draft, the host reviews the list, the host opens it to invited members, members confirm their own costs, and only then can the host finalize the room summary. Later steps may stop and ask for review, while accepted human decisions remain explicit state transitions.

The project has six fixed safety checks. Each check passes a limited result forward. Later checks may mark something for review, but they cannot silently rewrite earlier choices.

Supported Room Types

The table below describes the room types and what the app can safely calculate today. It is not a claim that every advanced business rule is fully automated. Rules such as hourly rates, deposits, shipping allocation, and tier discounts stay behind manual review until a deployment owner finishes and tests those inputs.

Mermaid Overview

Permission And Review Order

The fixed order is AI/OCR draft first, host review second, group access third, member confirmation fourth, and final settlement last. The host can remove bad OCR rows or fix names, prices, and categories before opening the list to members. After the host opens the list, parsed item editing is locked.

sequenceDiagram
  autonumber
  actor Host as Room Host
  actor Member as Room Member
  participant Page as Shared Room Page
  participant Agent as WebMCP Agent
  participant Server as Server State
  participant Store as JSON Store

  Host->>Page: Create room and upload price evidence
  Page->>Server: Parse image or pasted OCR text
  Server-->>Page: Return item draft plus separated rules
  Server->>Store: Save room state with short write smoothing
  Agent->>Page: Inspect room through read-only WebMCP tools
  Agent->>Page: Create proposal-only draft
  Host->>Page: Edit parsed items or remove bad rows
  Page->>Server: Owner-only parsed item update
  Server->>Store: Save reviewed draft state
  Host->>Server: Open reviewed list to members
  Server-->>Page: Broadcast reviewed item state
  Member->>Page: Join room and choose own items
  Member->>Server: Confirm own cost
  Server->>Store: Save member confirmation
  Host->>Page: Same-card approve or reject agent draft
  Host->>Server: Finalize room after human confirmations
  Server-->>Page: Broadcast local settlement summary
  Server->>Store: Save final room summary
  Host->>Page: Export HTML or PDF review record
  Page-->>Host: Download a local file from the reviewed summary

  Note over Agent,Server: Agent cannot edit items, confirm claims, settle, pay, book, or submit external forms.
  Note over Store: On a hosted demo, use ROOM_STORE_PATH=/data/rooms.json with a mounted volume.

flowchart TD
  A[AI drafts only] --> B[Host reviews parsed rows]
  B --> C[Host opens reviewed list]
  C --> D[Members claim and confirm their own costs]
  D --> E[Host finalizes local room summary]
  E --> F[Human exports review record]
  F --> DONE[Done without payment or external submission]

  A -. blocked .-> X1[AI cannot edit rows]
  A -. blocked .-> X2[AI cannot open group access]
  C -. locked .-> X3[Parsed rows cannot be edited after opening]
  D -. blocked .-> X4[No one confirms for another member]
  E -. blocked .-> X5[No payment, booking, or card handling]
  F -. blocked .-> X6[Exports do not submit forms or change external systems]

  E --> SAVE[Save room state to JSON store]
  F --> HTML[Download HTML]
  F --> PDF[Download PDF]
  F --> PRINT[Print summary]
  SAVE --> VOL[Mounted volume keeps demo rooms after restart]

  OPTIONAL[Optional deployer integrations] -. draft only .-> A

The detailed module, permission, state, and room-transition diagrams are in docs/ai-generated/2026Q3/shared_room_mermaid_module_design_20260831.md.

Environment Variables

Required runtime variables:

HOST=0.0.0.0
PORT=3000
CORS_ORIGIN=
ROOM_TTL_HOURS=12
ROOM_PERSISTENCE=json
ROOM_STORE_PATH=data/rooms.json
GUARDRAIL_MEMORY_PATH=data/guardrail-memory.json
ROOM_PERSIST_DEBOUNCE_MS=35
ROOM_PERSIST_JITTER_MS=120
MAX_IMAGE_MB=8
RATE_LIMIT_WINDOW_MS=60000
API_RATE_LIMIT_MAX=180
ROOM_CREATE_RATE_LIMIT_MAX=20
MENU_PARSE_RATE_LIMIT_MAX=30
LOCAL_OCR_FIRST=true
LOCAL_OCR_MIN_ITEMS=3
LOCAL_OCR_MAX_CHARS=12000
TRUST_LAYER_SPREADSHEET_ID=replace_with_google_sheet_id_for_whitelist_audit_only

Optional AI repair variables:

AI_PROVIDER_ORDER=gemini,openai
GEMINI_API_KEY=
GOOGLE_API_KEY=
GOOGLE_GENERATIVE_AI_API_KEY=
GOOGLE_GEMINI_API_KEY=
GEMINI_KEY=
GEMINI_MODEL=gemini-2.5-flash
GEMINI_MODEL_FALLBACKS=gemini-2.5-flash-lite,gemini-flash-latest
GEMINI_RETRY_ATTEMPTS=2
GEMINI_TIMEOUT_MS=25000
OPENAI_API_KEY=
OPENAI_MODEL=gpt-5.4-mini
OPENAI_MODEL_FALLBACKS=
OPENAI_TIMEOUT_MS=35000
OPENAI_MAX_OUTPUT_TOKENS=16000
OPENAI_IMAGE_DETAIL=high

Do not commit API keys. Set secrets only in the hosting provider's secret manager.

Runtime requires Node.js >=20.9.0 because the image normalization pipeline uses sharp@0.35.x.

Deployment Configuration Guide

The repository provides configuration names only. Each project organizer changes values in the deployment platform, not in source code. Paid provider keys are optional adapters, not part of the required WebMCP demo path.

Recommended open-source deployment order:

1. Copy env.sample variable names into the hosting service variables.

2. Mount a persistent volume at /data and set ROOM_STORE_PATH=/data/rooms.json.

3. For the adaptive review loop, set GUARDRAIL_MEMORY_PATH=/data/guardrail-memory.json so human corrections and blocked approval attempts are retained as guardrail candidates.

4. Run the no-key flow first with manual input or local OCR text.

5. Add a provider key only if the deployment owner wants optional OCR/schema repair.

6. Restart the service and verify /healthz reports the expected provider and persistence flags without exposing secret values.

Enterprise MCP Submit Gate

Future company or third-party MCP templates should enter through a default-deny submit gate before the runtime can load them:

submitted template -> package boundary -> static security gate -> semantic safety gate -> contract schema -> industry routing -> repeat regression -> human approval -> accepted registry

The security gate is split into two mandatory phases. The static gate rejects secrets, over-privileged MCP configs, install hooks, package-runner risks, unsafe public-export payloads, and unbounded filesystem or network scope. The semantic safety gate then reviews prompts, tool descriptions, and agent-readable files for prompt injection, hidden intent, jailbreak patterns, or policy-bypass language before any submitted MCP file is trusted by the parser or runtime.

Enterprise submissions must also declare provenance, permissions, data/privacy class, SBOM/dependency evidence, sandbox policy, human final-action boundaries, revocation path, and audit/SLA metadata. Approved artifacts are promoted into an accepted registry tier; experimental artifacts stay sandboxed.

Local validation entrypoints:

npm run verify:adaptive-contracts
npm run build:image-fixture-manifest
npm run regression:adaptive-parser -- --base-url http://127.0.0.1:4180 --repeat 5

The matching design contract is in config/enterprise-submit-gate.json. The image fixture manifest is a checksum-backed oracle for external image artifacts; the large PNG set can stay outside the main repository while the repo keeps the repeatable runner and expected contract.

Fast Review Sample

For judging or a quick local smoke test, open a new empty room and click Load Sample Room. This creates a small structured sample with shared and personal items, then adds a draft-only proposal for the host to review.

The sample path is intentionally no-key and no-upload:

• It does not call Gemini, OpenAI, Google Sheets, payment, booking, commerce, or social APIs.

• It does not overwrite a room that already has data.

• It creates a draft that waits for host review.

• The host must still confirm the same draft card before the draft status changes.

• Accepting the draft does not settle the bill, submit an external form, write payment data, or change formula rules.

Local Development

npm install
npm run check
npm run audit:tasks
npm start

Open http://localhost:3000.

The app does not automatically load .env. If local AI image parsing is needed, export the key in the shell before starting the server. Use env.sample as the variable-name reference. Without an API key, the room still works with local OCR text when enough candidates are extracted.

Hosted Deployment

1. Connect the public GitHub repository to a Node.js hosting service. The live demo currently runs on Zeabur.

2. Create a Node.js service.

3. Set the required environment variables listed above.

4. Keep AI provider keys empty for a clean WebMCP tool-layer demo, or add optional adapter keys only if OCR/schema repair should call external models.

5. Add a persistent volume and set ROOM_STORE_PATH=/data/rooms.json if rooms must survive service restarts.

6. Keep the public demo on one service instance when using JSON persistence.

7. Use npm install as the install command and npm start as the start command.

Recommended public-demo limits:

RATE_LIMIT_WINDOW_MS=60000
API_RATE_LIMIT_MAX=180
ROOM_CREATE_RATE_LIMIT_MAX=20
MENU_PARSE_RATE_LIMIT_MAX=30

The expensive endpoint is image/OCR parsing, not WebMCP inspection. The public demo allows 30 parse requests per client per minute while retaining basic abuse protection.

Verification

npm run check
npm run audit:tasks
npm run stress:contracts -- --base-url http://127.0.0.1:3000 --rounds 20 --concurrency 4 --output-dir logs/runtime
npm run build:image-fixture-manifest
npm run stress:image-matrix -- --base-url http://127.0.0.1:3000 --mode image-plus-oracle-text --output-dir logs/runtime/image-matrix

For repeated local stress runs, start the local server with test-only rate limits so the test measures state-machine behavior instead of the public-demo throttle:

ROOM_CREATE_RATE_LIMIT_MAX=500 MENU_PARSE_RATE_LIMIT_MAX=500 API_RATE_LIMIT_MAX=1000 npm start

The hosted public demo should keep the lower public-demo limits shown above.

The repeated room-flow check covers 20 non-duplicate Traditional Chinese and English scenarios, with 20 rounds per scenario. It checks room creation, local copied-text OCR parsing, stable room-type selection, draft creation, and the final human approval rule.

The image-matrix runner is a deterministic contract-driven integration benchmark using 115 paired image-oracle artifacts. Each test verifies the image SHA-256, scenario id, language, contract id, archetype, expected member-visible items, rule counts, forbidden member-visible numbers, evidence pointers, and Semantic Visual Anchor fields. image-plus-oracle-text validates the HITL state transition and oracle chain without provider keys. It must not be described as raw OCR accuracy, zero-shot OCR accuracy, or unconstrained vision extraction accuracy; a production image-only run against Zeabur is a separate OCR/provider check and should use the runner's default slow pacing and quarantine output.

Expected audit state:

• room type selection ready

• evidence/OCR review ready

• local calculation rules ready

• member confirmation checks ready

• WebMCP tools ready

• Google Sheets trust option design documented

• submission local package ready

Demo Script

The locked recording flow is:

1. Start on the live Shared Room page with the agent side panel visible.

2. Upload the prepared English Community Workshop Signup image through the visible file picker. Do not use Load Sample Room in the recording.

3. The agent reads the visible evidence, enters only the visible price lines, and calls inspect_room, suggest_next_actions, and create_action_proposal.

4. The agent moves the pointer to the single draft card and tells the host when to click. The host clicks the same card twice: first to mark it reviewed, then to confirm the green approval state.

5. The agent opens the same room in a second tab as Jamie, selects one item, and pauses. Jamie clicks the personal confirmation button once.

6. The agent immediately returns to the owner tab, verifies the member state, and pauses. The owner clicks Owner Finalizes Summary once.

7. The owner clicks Download PDF, then Download HTML. Both files must open successfully before the recording continues.

8. Open a new room, switch to Chinese, and upload the prepared 社區水果免運團購 image. The threshold and shipping lines must remain review context rather than purchasable items.

9. Repeat the same controlled loop quickly: agent prepares, the human approves on one card, a second member confirms their own item, and the owner finalizes.

10. Close by stating that payment, booking submission, and external account actions remain outside the exposed tool set.

Use this spoken line near the start:

"AI prepares the work directly on the page. Humans approve the commitment."

Use this closing line:

"WebMCP lets the agent handle the repetitive work on the page while people keep every commitment. The same pattern can support shared orders, registrations, bookings, and other collaborative tasks without exposing final payment or external submission as an agent tool."

The detailed timed runbook is in docs/submission/WEBMCP_SUBMISSION.md.

Compliance Notes

• No fake account scraping.

• No vendor API reverse engineering.

• No authenticated vendor cookies.

• No payment processing.

• No raw device fingerprinting.

• No raw OCR, images, raw device IDs, payment identifiers, or social account identifiers are written to Google Sheets.

• Google Sheets is only a design-level short-lived hash whitelist and audit-log trust layer in this public core; production check/enroll/revoke adapters are roadmapped extensions.

Known MVP Limits

• Room data is saved to a local JSON file by default. On a hosted service, attach a volume and set ROOM_STORE_PATH=/data/rooms.json; otherwise a platform restart can still clear room state.

• The current save layer is meant for one demo service instance. It smooths short write bursts by merging nearby changes and adding a small millisecond delay before saving, but a hard crash can still lose the latest tiny write window. Production traffic should move to Redis or PostgreSQL.

• Room ownership is demo-grade. Production deployments should add signed sessions or a real login system.

• OCR quality depends on image clarity. If a live provider call times out or produces sparse evidence, the app should fall back to manual review instead of inventing missing fields.

• Advanced rules such as shipping split, hourly venue fee, room minimum, deposit include/exclude, tax/service formulas, and tier discounts route to host review. The current MVP does not claim fully automated complex formula calculation.

• Google Sheets trust-layer check/enroll/revoke adapters are design-level roadmap extensions, not production-ready identity infrastructure in this public core.

• Pixel-level visual crop overlays are reserved in the schema roadmap. The current UI uses semantic anchors and contextual snippets.