# Stochastic Deputy MCP

Structural tenant isolation for tool-using Model Context Protocol (MCP) agents.

[![CI](https://github.com/Mirza-Samad-Ahmed-Baig/Stochastic-deputy-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Mirza-Samad-Ahmed-Baig/Stochastic-deputy-mcp/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

This repository is the maintained reference implementation and reproducibility
companion for _The Stochastic Deputy: Structural Tenant Isolation for Tool-Using
LLM Agents_.

## Paper

_The Stochastic Deputy: Structural Tenant Isolation for Tool-Using LLM Agents_
is being released as an arXiv preprint by Mirza Samad Ahmed Baig, Syeda Anshrah
Gillani, Asher Ali, and Muhammad Hamzah Siddiqui. The primary arXiv category is
`cs.CR` (Cryptography and Security), with `cs.AI` as a cross-list.

The arXiv identifier and abstract-page link will be added here immediately after
announcement. Until then, use the paper metadata in [`CITATION.cff`](CITATION.cff)
when citing this work. The paper reports only aggregate operational measurements;
this repository contains the fully synthetic runnable reference implementation.

The paper and its sanitized aggregate ancillary artifact are released under
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Sharing or adapting
either requires the attribution specified by that license. In a scholarly
publication, provide attribution by citing the paper through
[`CITATION.cff`](CITATION.cff).

## Security property

The model can filter reservations by date and status, but it cannot name a
tenant, property, hotel, organization, or authorization scope. Tenant scope is
verified before MCP tool dispatch and passed to the server as trusted context.
Every query applies that scope, and one egress mapping removes internal IDs and
PII-like fields.

```text
verified credential -> immutable scope -> MCP server -> scoped query -> redacted output
                                          ^
                                          |
                                no tenant argument exists
```

The included datastore is entirely synthetic. No company database, operational
schema, endpoint, credential, record, identifier, or exact business cardinality
belongs in this repository.

## Current implementation

- TypeScript on Node.js 20 or later
- Official MCP TypeScript SDK v2
- MCP stdio server with a tenant-parameter-free tool schema
- Demonstration HMAC scope token with expiry and audience validation
- HTTP MCP resource server with Keycloak JWT verification
- MySQL repository that joins every query to the credential-bound tenant set
- Disposable Docker Compose stack with entirely synthetic multi-tenant data
- Egress minimization for internal identifiers and PII-like fields
- Unit, authorization, live integration, schema-regression, and privacy checks

The demonstration HMAC token is intentionally small and inspectable. It is not
a production identity system. Production deployments should verify issuer,
audience, signature, expiry, and authorization claims through their established
OIDC/OAuth resource-server boundary and inject only the verified scope.

## Quick start

Install exact dependencies and run the checks:

```bash
npm ci
npm run check
```

Create local demonstration credentials in PowerShell:

```powershell
$env:SDM_DEMO_HMAC_KEY = node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))"
$env:SDM_DEMO_TOKEN = npm run --silent mint-token -- tenant-alpha
npm run dev
```

The server uses stdout exclusively for MCP. Diagnostic messages go to stderr.

To inspect the built server:

```bash
npm run build
npx @modelcontextprotocol/inspector node dist/src/index.js
```

## Live Keycloak and MySQL demonstration

Docker is required for the live demonstration. Start the disposable
infrastructure, then start the HTTP MCP resource server:

```bash
npm run demo:infra:up
npm run demo:server
```

In another terminal, run the end-to-end verification and then stop the stack:

```bash
npm run demo:e2e
npm run demo:infra:down
```

The test obtains client-credentials tokens for two synthetic identities and
checks independent tenant confinement, JWT signature validation, audience and
expiry enforcement, rejection of injected tenant arguments, and output
minimization. It also checks that missing and tampered tokens receive HTTP 401.

The committed usernames and secrets are intentionally obvious local-demo
values. Services bind only to loopback (`3000`, `3307`, and `8180`), MySQL uses
temporary storage, and no production endpoint, account, schema, or credential
is required. Do not reuse any demo value outside this disposable stack.

## MCP tool

`list_reservations` accepts only:

- `from`: optional earliest arrival date
- `to`: optional latest departure date
- `status`: optional reservation status
- `limit`: optional result limit

Unknown arguments are rejected. In particular, an injected `tenantId` argument
fails schema validation before the handler runs.

## Repository boundaries

Safe to maintain here:

- Synthetic fixtures and generators
- Generic authorization adapters
- MCP schemas and enforcement tests
- Aggregate research results
- Figure and table reproduction code

Never commit:

- Production source or configuration copied from an internal deployment
- Database dumps, row-level extracts, raw prompts, traces, or tool outputs
- Credentials, tokens, private keys, certificates, endpoints, or private IPs
- Operational table/column names, tenant IDs, reservation IDs, or property names
- Exact company database size or business cardinalities

See [PRIVACY.md](PRIVACY.md), [SECURITY.md](SECURITY.md), and
[docs/architecture.md](docs/architecture.md) before contributing.

## Preprint and releases

The repository is public alongside the author-identified preprint. After arXiv
assigns an identifier, the README and `CITATION.cff` will be updated with the
permanent preprint URL. Versioned software archives and their persistent
identifiers will be linked here when available.

## Project status and licensing

The code is an early research reference implementation released under the
[Apache License 2.0](LICENSE). The paper and sanitized aggregate research
artifact are separately licensed under CC BY 4.0. If this software contributes
to a scholarly publication, cite the associated paper using
[`CITATION.cff`](CITATION.cff). The `private` package flag prevents accidental
npm publication; it does not restrict the open-source license.