@uvaresearch/wrapper-mcp

Stdio MCP server for QMS Wrapper. Lets MCP-capable clients (Claude Code, Claude Desktop, Cursor, generic stdio hosts) drive a QMS Wrapper instance over HTTPS using a Personal Access Token (PAT). Communication is JSON-RPC over stdin/stdout; outbound traffic is HTTPS to a single configured origin.

The server is built domain-by-domain. v0.1 ships task management — 8 task tools, 4 lookup / identity resources, 3 task resource templates, 5 prompts. Subsequent versions will expand to additional QMS Wrapper domains (projects, processes, storage, risk, etc.) under the same package and PAT-auth model.

Status: v0.1.0. package.json is private: true so an accidental npm publish cannot ship it. Flip when ready.

Install

Via npx (no install)

Use this in your MCP host configuration (see Step 2 below). npx will download the package on first run and cache it; subsequent runs reuse the cache.

npx -y @uvaresearch/wrapper-mcp

(Once the package is flipped to public on the registry. While private: true is set, only an authenticated registry user with read access can install it.)

Via npm install -g

For users who want wrapper-mcp on PATH:

npm install -g @uvaresearch/wrapper-mcp
wrapper-mcp --help

The binary lands in your global npm bin dir. Find it with:

npm bin -g

On macOS/Linux this is typically /usr/local/bin or ~/.npm-global/bin; on Windows it is %AppData%\npm.

From source (contributors)

git clone https://github.com/uvaresearch/wrapper-mcp.git
cd wrapper-mcp
npm install
npm run build
node dist/index.js --help

Point your MCP host at the absolute path to dist/index.js.

Configure

Step 1: get a Personal Access Token

1. Log in to your QMS Wrapper instance.

2. Go to Profile -> Access Tokens -> Create token.

3. Name it for the device it will live on (e.g. "Claude Desktop laptop").

4. Pick scopes. Defaults cover read/write/create on tasks. Only tick tasks:assign and attachments:upload if you need reassignment and file uploads respectively.

5. Submit and copy the wrapper_<32 chars> plaintext that is shown exactly once. Store it in your OS keychain or a password manager.

Step 2: configure your MCP host

WRAPPER_BASE_URL is the URL you use to sign in to QMS Wrapper in the browser (the user-facing app). For the hosted SaaS that is https://app.qmswrapper.com. Self-hosted instances use their own host.

Claude Code

Either project-scoped (.mcp.json in repo root) or user-scoped (~/.claude.json under the mcpServers key):

{
  "mcpServers": {
    "wrapper": {
      "command": "npx",
      "args": ["-y", "@uvaresearch/wrapper-mcp"],
      "env": {
        "WRAPPER_PAT": "wrapper_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "WRAPPER_BASE_URL": "https://app.qmswrapper.com"
      }
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json (Settings -> Developer -> Edit Config):

{
  "mcpServers": {
    "wrapper": {
      "command": "npx",
      "args": ["-y", "@uvaresearch/wrapper-mcp"],
      "env": {
        "WRAPPER_PAT": "wrapper_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "WRAPPER_BASE_URL": "https://app.qmswrapper.com"
      }
    }
  }
}

Restart Claude Desktop after editing.

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "wrapper": {
      "command": "npx",
      "args": ["-y", "@uvaresearch/wrapper-mcp"],
      "env": {
        "WRAPPER_PAT": "wrapper_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "WRAPPER_BASE_URL": "https://app.qmswrapper.com"
      }
    }
  }
}

Generic stdio MCP client

Spawn wrapper-mcp (or npx -y @uvaresearch/wrapper-mcp) as a subprocess with WRAPPER_PAT and WRAPPER_BASE_URL in the child environment, and speak JSON-RPC over its stdin/stdout. Other hosts (for example GitHub Copilot CLI) generally follow the same shape, but config file locations differ; see https://modelcontextprotocol.io/clients for the current list.

Step 3: verify

In Claude Code, run /mcp and confirm:

• Server wrapper shows status connected.

• Tools: 8. Resources: 4 (plus 3 templates). Prompts: 5.

CLI smoke test (no PAT required):

npx -y @uvaresearch/wrapper-mcp --help
npx -y @uvaresearch/wrapper-mcp --version

If the server fails to start it writes a single-line reason to stderr and exits with code 64.

Environment variables

Tools, resources, prompts at a glance

All v0.1 surfaces live in the task.* namespace. Future domains will use sibling namespaces (project.*, process.*, etc.) without breaking existing tool names.

Task tools (8)

Resources (4 concrete + 3 templates)

Task prompts (5)

Security and threat model

This section reflects what the code in src/ actually enforces. If a claim is not backed by code, it is not made here.

What the client does

• Opens one outbound TCP connection per request to WRAPPER_BASE_URL using Node's built-in fetch.

• Sends Authorization: Bearer <PAT> plus a small set of X-Mcp-* headers (X-Mcp-Session-Id, X-Mcp-Tool-Name, optional X-Mcp-Request-Id) so the backend can audit each call.

• Reads/writes only inside WRAPPER_CACHE_DIR (default ~/.cache/wrapper-mcp, created with mode 0700). The HTTP layer is stateless; the cache dir is reserved for ancillary scratch state.

• For task.attach, reads file paths supplied by the user in the tool arguments and includes their full contents as multipart fields. Reads are restricted to WRAPPER_UPLOAD_DIR.

What the client does NOT do

• No telemetry. No analytics. No usage pings.

• No auto-update. The binary you installed is the code that runs.

• No remote config. All configuration is local env vars and tool args.

• No outbound network calls beyond WRAPPER_BASE_URL. There is no fallback host and no DNS prefetch.

• No filesystem access outside WRAPPER_CACHE_DIR and explicit file paths inside WRAPPER_UPLOAD_DIR passed to task.attach.

What the PAT grants and does not grant

A PAT carries the scopes the user ticked at creation time. With default scopes the bearer can read, write, and create tasks they would normally have access to in the web UI. It is bearer-only: anyone who holds the plaintext value can act as the user until the token is revoked. It does not grant filesystem, OS, or shell access on the QMS Wrapper host. The server scopes the bearer to the issuing user; it does not elevate.

Hardening baked into v0.1.0

1. URL guard (src/security/urlGuard.ts): refuses WRAPPER_BASE_URL that is not https://, except for loopback hosts (localhost, 127.0.0.1, ::1) and *.local. Also rejects userinfo (user:pass@host) and any RFC1918 / link-local / cloud-metadata IP literal. Fails closed at process start before any HTTP call.

2. Response scrubber (src/security/responseScrubber.ts): runs over every tool / resource / error payload before it leaves the process and replaces any wrapper_<32 alnum> substring with [REDACTED]. The check happens on the serialized JSON string, so exotic types cannot bypass. If a match ever fires it also emits a stderr warning so the regression is visible.

3. Safe logger (src/security/safeLog.ts): writes only to stderr (stdout is reserved for JSON-RPC framing). Every line is scrubbed twice: once by the PAT regex and once by literal-replacing the current WRAPPER_PAT env value even if it does not match the regex shape.

4. CLI flag refused: --pat, --token, --bearer, --auth, -p, -t, their =value forms, glued shorts (-pSECRET), case variants, and positional wrapper_<32 alnum> arguments all exit with code 64 before doing anything else. Rationale: command-line tokens land in shell history and ps.

5. Minimal dependency tree: runtime deps are @modelcontextprotocol/sdk and zod. No HTTP client library, no logger framework, no arg parser. Smaller supply-chain attack surface.

6. No telemetry, no auto-update, no remote config (see above).

7. Provenance prep: publishConfig.provenance is true and publishConfig.access is restricted; package.json is private: true for v0.1 so accidental npm publish is blocked. When ready, flip private to false and publish with npm publish --provenance --access public to ship a sigstore attestation.

8. task.attach default-denies. Requires WRAPPER_UPLOAD_DIR env to be set; resolves and bounds every path inside it; rejects symlinks; caps file size at 50 MB by default.

Known limitations

• Cookie jar deferred: the client is Bearer-only. If the backend ever starts requiring a session cookie alongside the PAT, this client will need a cookie store; today it sends no cookies.

• task.attach reads each uploaded file fully into memory before posting. Very large attachments will be bounded by Node's heap.

What users should do

• Issue PATs with the narrowest scope set that gets your work done.

• Rotate PATs periodically; revoke on device loss or job change.

• Prefer HTTPS endpoints. The URL guard will refuse anything else outside of loopback / *.local dev hosts.

• Keep the PAT in the MCP host's env block (which most hosts read from a permissioned config file), not in shell rc files.

• Set WRAPPER_UPLOAD_DIR to a tightly-scoped directory if you need task.attach.

Troubleshooting

Contributing

• Node 20+ (.nvmrc is the source of truth).

• npm install.

• npm run build (strict TypeScript; warnings are errors).

• npm test (vitest).

• Source: https://github.com/uvaresearch/wrapper-mcp.

• Do not land changes that introduce a new runtime dependency without discussion; the minimal-deps property is a security feature, not laziness.

License

MIT. See LICENSE.