Skip to main content
Glama
supportbridge-customer

supportbridge-customer

by willsu42
README.md
# BridgeLayer

BridgeLayer is a local prototype for controlled customer-support tool access and guarded streaming responses. Its Support Copilot workbench looks up fictional customers through MCP and streams editable, email-redacted drafts from deterministic templates or a configured Groq model. The original scripted clients also demonstrate simulated refunds, tool permissions, and a separate streaming route with tenant token budgets and one pre-output backup attempt.

**Tasks 1–4 are complete within the agreed prototype scope as of November 3, 2026.** The additional [Support Copilot Stage A](docs/COPILOT_STAGE_A.md), implemented November 8, adds a local English workbench. [Stage B](docs/COPILOT_STAGE_B.md), implemented November 9, adds optional Groq live generation and token accounting. Real provider validation requires a local API key; no real payment integration is implemented. The [original project closeout](docs/PROJECT_CLOSEOUT.md) retains the four-task scope and evidence.

Developed by **Yu-Chen Su (Will), Independent Software & AI Consultant**. The personal/FDE prototype was previously named SupportBridge and predates the active professional development phase beginning **September 11, 2026**. This is a customer-inspired integration case study, with no evidenced actual client engagement.

The English [product brief and business presentation](docs/business/README.md) introduce the prototype and proposed commercial collaboration for potential customers, investors, and partners.

## Problem being solved

Customer-support integrations need a clear boundary between incoming requests, authenticated callers, permitted operations, business rules, and stored results. BridgeLayer demonstrates those boundaries with discoverable MCP tools and reproducible success/failure cases. The local workbench connects lookup and scripted or live AI drafting in a browser. Tool selection remains deterministic; the model only writes a draft.

## Open the Support Copilot demo

With Node 24 and dependencies installed:

```sh
npm run demo:copilot
```

Open **http://127.0.0.1:3040/**. Select a fictional customer and case, generate a draft, then edit or copy it. Stop generation or reset the demo at any time. The workbench shows actual lookup events and email-redaction metrics. Scripted mode uses fresh in-memory demo data and requires no API key. Press Ctrl+C to stop. See the [Stage A walkthrough](docs/COPILOT_STAGE_A.md) for its architecture, demo script, limits, and validation.

## Enable Groq Live AI (Stage B)

Use a Groq account on the **Free plan**. Copy `.env.example` to `.env` if you do not already have one, then enter `GROQ_API_KEY` locally. The default model is `openai/gpt-oss-20b`. Restart `npm run demo:copilot` and choose **Live AI · Groq** in the workbench. The key stays on the server; never paste it into the browser or commit `.env`.

The app cannot verify your Groq billing plan or guarantee account quota. Keep the account on Free; a paid account can incur charges. There are no automatic retries, model failovers, or automatic plan upgrades. The local budget allows 8,000 tokens per sixty-second settlement window, independently of Groq limits. Usage persists in ignored `data/copilot-budget.sqlite`.

Live mode sends the question and verified customer name/plan to Groq. Customer-record email is excluded, but emails typed in the question are **not masked before sending**. Use fictional inputs. See the [Stage B setup, behavior, and validation](docs/COPILOT_STAGE_B.md).

## Demonstrate failure handling (Stage C)

Choose **Failure simulation** in the workbench, then select **Provider rate limit (429)**, **Provider timeout**, or **Insufficient token budget** and click **Run simulation**. The timeline shows the expected failure and an evidence panel reports local simulated attempts, held allowances, and cancellation. **Switch to Scripted recovery** returns to a working draft flow when you generate again.

These scenarios need no Groq key and make no Groq requests. Each uses a fresh in-memory ledger; the live budget is untouched. They exercise the existing admission, cancellation, and settlement logic. They do not demonstrate live provider fallback or a real Groq outage. See the [Stage C walkthrough and three-minute demo script](docs/COPILOT_STAGE_C.md).

## Current capabilities

### Available Now

| Capability | Implemented behavior |
| --- | --- |
| Support Copilot Stage A | English browser workbench, actual MCP lookup, guarded scripted drafting, editing/copying, cancellation, reset, and request activity. Local Node 24 checks pass with 74 tests/subtests. |
| Task 1: customer MCP service | Original stdio server with strict validation, lookup, simulated refunds, SQLite, and rollback tests. |
| Task 2: HTTP MCP security gateway | Stateless HTTP MCP with signed demo JWTs, role policy, request correlation, and separate downstream credentials. |
| Support Copilot Stage C | Explicit local failure simulations for 429, timeout, and insufficient budget; observed evidence and manual Scripted recovery. |
| Support Copilot Stage B | Optional Groq live drafts, explicit mode selection, provider usage, persistent local token budget, cancellation, and sanitized failures. |
| Task 3: streaming email guardrail | Authenticated `/guardrails/stream` with deterministic mock bytes, bounded incremental redaction, cancellation, and a local demo; local verification and remote Node 22/24 CI are complete. |
| Task 4: token budgets and fallback | SQLite tenant reservations, usage reconciliation, and one pre-output backup attempt over deterministic model mocks; local checks and remote Node 22/24 CI are verified. |
| `get_customer_record` | Takes `customer_id`; returns a fictional record or business error. |
| `trigger_refund` | Takes `customer_id`, `amount`, `reason`; atomically stores a simulated refund and its success audit. |
| `admin_health_check` | HTTP-only harmless admin test tool; returns fixed health information without data changes. |
| Denial audit / diagnostics | Separate SQLite denial records; correlated gateway outcomes and durations; no bearer tokens or tool arguments in diagnostic fields. |
| Verification / demos | 114 tests/subtests pass locally on Node 24, including isolated failure simulations. A minimal real Groq key/stream/usage check passed November 13; full customer-support answer-quality acceptance remains outstanding. |

Customer IDs require five ASCII digits after `CUST-`; extra arguments are rejected. Amounts must be finite positive numbers, with no string coercion; the store additionally requires safely representable whole cents. Reasons are trimmed before the ten-character minimum check. Receipts return integer `amount_cents`, USD currency, and simulated status.

### Optional extensions

All four original tasks are closed. Stages A and B add the local workbench, optional Groq generation, and live token accounting. External customer APIs, hosted deployment, and live provider fallback remain future work. Task 4’s mock fallback demonstration remains independently available.

## Architecture

```mermaid
flowchart LR
    C[Scripted HTTP clients] -->|demo bearer JWT| G[Security gateway]
    G -->|separate service credential| H[Customer HTTP entry point]
    H --> S[Customer handlers / validation / store]
    L[Existing stdio client] --> T[Stdio entry point]
    T --> S
    S --> D[(Customer / refund SQLite)]
    G --> A[(Separate denial SQLite)]
    G -->|/guardrails/stream| M[Mock streaming fixture]
    M --> R[Email guardrail]
    G -->|/resilient/stream| B[Tenant budget and attempt router]
    B <--> Q[(Token ledger)]
    B --> P[Primary or backup mock]
    P --> R
    R --> O[Safe SSE output]
```

Both HTTP listeners bind loopback. The local launcher runs them in one Node process; these are separate HTTP trust boundaries, not OS-process isolation. Each POST has its own SDK transport; there is no shared MCP session state. The original stdio entry point remains available with two tools.

The gateway authenticates every request, leaves authenticated discovery unfiltered, and denies non-admin `admin_` calls before forwarding. Downstream headers are explicitly constructed; the client's bearer token is never passed through.

**No LLM chooses tools:** MCP demo clients call them explicitly. The original streaming routes use predefined provider fixtures and do not invoke customer tools. The additional workbench workflow explicitly looks up one customer before generating its scripted or Groq draft. See [Stage A architecture](docs/COPILOT_STAGE_A.md#request-flow) for that path and [the original architecture](docs/ARCHITECTURE.md) for the earlier routes.

## Example workflow

```sh
npm run demo:http
```

The temporary HTTP demo initializes viewer/admin clients and demonstrates:

1. A viewer discovers all three HTTP tools, including the admin tool.
2. Customer lookup returns fictional Alex Rivera.
3. A simulated refund returns `amount_cents: 1250`.
4. Viewer admin execution fails with `-32001: Unauthorized Tool Call`.
5. Admin execution succeeds.
6. Missing credentials fail with HTTP 401.

It generates temporary credentials/databases, does not print tokens, and cleans up afterward. `npm run demo` still runs the original stdio demonstration.

To exercise the email-only streaming path:

```sh
npm run demo:streaming
npm run bench:streaming
```

It accepts predefined synthetic fixtures rather than arbitrary prompts. Email-containing whitespace tokens are replaced as a whole; punctuation may also be removed. Existing customer MCP responses are not passed through this filter. This fixture route has no live LLM; general-purpose PII detection is not implemented. Groq generation is available separately in the Copilot workbench.

To exercise token accounting and primary/backup behavior:

```sh
npm run demo:resilience
```

This demonstrates per-tenant budgets, a primary 429/timeout followed by one backup, and failure without switching models after output. All token counts are synthetic; no live provider is called. See the [Task 4 walkthrough](docs/04-token-budgets-and-fallback-walkthrough.md).

## Tech stack

Repository pins: TypeScript `7.0.2`, MCP SDK `1.30.0`, Zod `4.5.4`, and `jose` `6.2.12` for JWTs. The application uses Node.js ES modules, built-in HTTP/SQLite, npm, and Node's test runner. The workbench uses HTML/CSS and browser TypeScript compiled with `tsconfig.web.json`. No additional dependency, application HTTP framework, React app, or LLM SDK is introduced.

## Setup

Use Node 24 (`.nvmrc`); the package minimum is Node 22.13.0. Confirm `node --version` reports `v24.x` before installing dependencies.

```sh
npm ci
npm run check
npm run demo:http
```

The demo requires no external API key. For persistent HTTP operation, build, set two different secrets of at least 32 bytes, and run:

```sh
npm run build
export BRIDGELAYER_JWT_SECRET="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))')"
export BRIDGELAYER_SERVICE_KEY="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))')"
npm run start:http
```

Gateway: `http://127.0.0.1:3030/mcp`. Protected customer service: port `3031`. Stop with Ctrl+C. The [Task 2 walkthrough](docs/02-http-gateway-walkthrough.md) covers token issuance, configuration, protocol headers, failures, and audit lifecycle. Tokens issued by the local operator last at most 15 minutes; this is not a full OAuth authorization server.

For persistent stdio operation, use `node dist/src/mcp/stdio.js`. It waits for MCP input, not interactive terminal commands. A host should spawn Node directly; normal npm banners can contaminate protocol stdout.

Naming compatibility: package `supportbridge`, MCP server `supportbridge-customer`, `SUPPORTBRIDGE_DB`, default `data/supportbridge.sqlite`, and `supportbridge.code-workspace` retain their working names. Gateway denials default to `data/gateway-audit.sqlite`. Both database paths are configurable. Task 4 adds `data/token-budget.sqlite`, configurable with `BRIDGELAYER_BUDGET_DB`; the persistent launcher enables `/resilient/stream` on the gateway port.

## Testing

**November 8, 2026:** Support Copilot Stage A passes server/browser type checking, builds, and **74 tests/subtests** on local Node **24.22.1**. Browser checks cover generating, editing, copying, stopping, resetting, error recovery, and mobile layout. See [Stage A validation](docs/COPILOT_STAGE_A.md#validation). The earlier CI evidence below belongs to the four-task implementation, not this new work.

**November 1, 2026:** Task 4 clean installation, local type checking, and **66 tests/subtests** pass on Node **22.23.4** and **24.22.1**; all four demos pass on Node 24. These results include concurrent SQLite admissions and restart/fallback/cancellation cases. **November 3:** the Task 4 implementation revision `dc381fa` was confirmed to pass remote Node 22/24 installation and checks. See [Task 4 closeout and job links](docs/TASK4_CLOSEOUT.md).

**October 28, 2026:** Task 3 local type checking and **42 tests/subtests** pass on Node **22.23.4** and **24.22.1**. All three demos pass on Node 24; the [validation record](docs/TASK3_VALIDATION.md) includes benchmark results. **October 29:** remote Node 22/24 CI for the Task 3 implementation and current revision was verified successful; see the [closeout and run links](docs/TASK3_CLOSEOUT.md).

On **September 15, 2026**, local type checking and **23 tests/subtests** passed on Node `25.5.0`, including the existing six stdio tests and new HTTP integration/failure checks. The HTTP SDK-client demo also completed. The suite now verifies original refund/audit records after a complete server restart.

HTTP coverage includes token validation, direct-service rejection, zero downstream calls after denial, durable denial records, audit failure, Origin/Host checks, invalid/batched/oversize input, credential separation, concurrent identical request IDs, downstream reply validation, timeout, disconnect/shutdown cancellation, and log privacy.

Those September runs used installed dependencies. On **October 27, 2026 (Asia/Taipei)**, a clean dependency installation on Node **24.22.1** / npm **11.19.1**, type checking, all **23 tests/subtests**, and both HTTP/stdio demos passed. The existing [Node 22/24 CI run](https://github.com/willsu42/bridgelayer-mcp/actions/runs/35180116876) for `a744bfd` was also confirmed successful. See the [Task 2 closeout](docs/TASK2_CLOSEOUT.md) for exact installation conditions and evidence. Node may emit a SQLite warning on stderr without breaking protocol behavior.

Earlier recheck on September 16 (America/Chicago): type checking and all 23 tests/subtests passed again after request-cleanup changes; the original stdio demo also completed.

| Failure | Existing response |
| --- | --- |
| Missing/invalid gateway credentials | HTTP 401 with Bearer challenge |
| Non-admin `admin_` call | HTTP 200; JSON-RPC `-32001: Unauthorized Tool Call`, same ID |
| Invalid tool arguments / unknown tool | JSON-RPC `-32602` |
| Customer missing / unsupported money precision | Tool result `isError: true` |
| Unexpected customer-service exception | Sanitized JSON-RPC `-32603` |
| Invalid/unavailable downstream or audit failure | Sanitized HTTP 502 / `-32002` |
| Downstream timeout | HTTP 504 / `-32003`; operation outcome may be unknown |

See the [decision log](docs/decisions.md) for pinned SDK framing/error details and the [HTTP walkthrough](docs/02-http-gateway-walkthrough.md) for boundary-level HTTP errors.

## Current development status

**All four prototype tasks are closed.** The [consolidated closeout](docs/PROJECT_CLOSEOUT.md) records scope, final CI evidence, and optional extensions.

Task 1 predates September 11. Scope/documentation reconciliation belongs to the new phase; Task 2 and the restart regression were implemented and validated in this phase, with final scope acceptance and environment verification completed October 27, 2026. Git history has not been rewritten.

Limits: fictional records are shared, without tenant data isolation. Viewers can create simulated refunds; the admin-prefix rule is not real-payment authorization. Customer tool calls are never automatically replayed; aborting a timeout cannot undo a committed refund. Model-streaming fallback is limited to one eligible backup attempt before output. Denial auditing has no automated retention policy. There is no hosted deployment, measured production capacity, or live AI workflow. Task 4 budgets operate on synthetic provider token reports; they do not measure real model usage. The streaming guardrail covers documented email patterns only and currently uses deterministic mocks.

## Roadmap and learning

1. Task 1 — complete; stdio tool behavior is retained and covered by the final regression suite.
2. Task 2 — complete within the local gateway scope; clean-install/Node 24 checks, demos, and remote Node 22/24 CI are verified.
3. Task 3 — complete within the email-only mock-provider scope; local checks and remote Node 22/24 CI verified. See the [closeout](docs/TASK3_CLOSEOUT.md) and [progress report](docs/TASK3_PROGRESS.md).
4. Task 4 — complete within the deterministic-provider scope; local checks and remote Node 22/24 CI verified. See the [closeout](docs/TASK4_CLOSEOUT.md).

Read the [project plan](docs/PROJECT_PLAN.md), [initial phase scope](docs/PROJECT_SCOPE.md), and [development backlog](docs/DEVELOPMENT_PLAN.md). Start code discussion with the [stdio walkthrough](docs/01-mcp-walkthrough.md) and [HTTP walkthrough](docs/02-http-gateway-walkthrough.md). VS Code tasks/debugging and the [handoff](HANDOFF.md) support continuing the explain → agree → implement → demonstrate → practice workflow.