BridgeLayer

BridgeLayer is an independent software and AI development project exploring customer-support integrations through MCP. It provides fictional customer lookup and simulated refunds through a TypeScript MCP service, with SQLite persistence and an authenticated HTTP security gateway.

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.

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 current interface is a developer-operated client; no operator UI or LLM agent is implemented.

Related MCP server: mcp-customer-server

Current capabilities

Available Now

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.

Planned

Task 4 remains planned: token limiting/model fallback. Task 3 is implemented and locally verified for common ASCII email patterns with a mock provider; see its walkthrough and validation. The React support console is also planned. Live agents, real customer APIs, and hosted deployment remain separate extension candidates.

Architecture

flowchart LR
    C[HTTP MCP client] -->|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)]

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: both demo clients call them explicitly. See architecture for boundaries and limitations.

Example workflow

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:

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. No live LLM or general-purpose PII detection is implemented.

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. No 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.

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:

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 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.

Testing

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 includes benchmark results. Existing Task 2 CI results below do not establish remote CI success for these new changes.

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 for a744bfd was also confirmed successful. See the Task 2 closeout 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.

See the decision log for pinned SDK framing/error details and the HTTP walkthrough for boundary-level HTTP errors.

Current development status

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. Requests are never automatically retried; aborting a timeout cannot undo a committed refund. Denial auditing has no automated retention policy. There is no hosted deployment, measured production capacity, token budget, or AI workflow. The streaming guardrail covers documented email patterns only and currently uses deterministic mocks.

Roadmap and learning

1. Task 1 — implemented; retain stdio compatibility.

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 — email-only streaming guardrail implemented and locally verified; remote CI remains pending. See the plan and status.

4. Task 4 — planned token budgets/model fallback.

Read the project plan, active scope, and development backlog. Start code discussion with the stdio walkthrough and HTTP walkthrough. VS Code tasks/debugging and the handoff support continuing the explain → agree → implement → demonstrate → practice workflow.