{"_id":"@armos/mcp","name":"@armos/mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@armos/mcp","version":"0.1.0","description":"Automatic PII masking for Claude Code via the armos proxy","type":"module","bin":{"armos-mcp":"dist/index.js"},"scripts":{"build":"tsc && node -e \"import('fs').then(({readFileSync,writeFileSync,chmodSync})=>{const f='dist/index.js';writeFileSync(f,'#!/usr/bin/env node\\n'+readFileSync(f,'utf8'));chmodSync(f,'755')})\"","dev":"tsx src/index.ts","start":"node dist/index.js","typecheck":"tsc --noEmit"},"publishConfig":{"access":"public"},"engines":{"node":">=18"},"dependencies":{"@hono/node-server":"^2.0.4","@modelcontextprotocol/sdk":"^1.29.0","hono":"^4.7.10","undici":"^7.10.0"},"devDependencies":{"@types/node":"^22.0.0","tsx":"^4.0.0","typescript":"^5.0.0"},"keywords":["armos","mcp","pii","privacy","claude"],"license":"Apache-2.0","gitHead":"c819094fc0f1d30a52a58dcc4a520d9cf84c02ce","_id":"@armos/mcp@0.1.0","_nodeVersion":"18.16.1","_npmVersion":"9.5.1","dist":{"integrity":"sha512-kUneJ/2oL+I52b9AsbmAIeYNzIciMKPxMJ6dfvi5ohbGDfFiRbnfMxT34M+S4NiMIfWQX9trSYT6Anl90y3QIQ==","shasum":"d59caea7d8d0a8e677077747a5657554b8103adf","tarball":"https://registry.npmjs.org/@armos/mcp/-/mcp-0.1.0.tgz","fileCount":14,"unpackedSize":16829,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFdm7/Z/7e1DT0rs0V8VdaVhXv/y3YMoWQNgzU9c2Z2UAiBo6irE/UmRf0ykDJWl3f6+/He04/y2TDPtmZM1bhxqWQ=="}]},"_npmUser":{"name":"armos-ai","email":"dhroov@armos.dev"},"directories":{},"maintainers":[{"name":"armos-ai","email":"dhroov@armos.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.1.0_1781201811678_0.16671525593680547"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-11T18:16:51.519Z","0.1.0":"2026-06-11T18:16:51.821Z","modified":"2026-06-11T18:16:52.342Z"},"maintainers":[{"name":"armos-ai","email":"dhroov@armos.dev"}],"description":"Automatic PII masking for Claude Code via the armos proxy","keywords":["armos","mcp","pii","privacy","claude"],"license":"Apache-2.0","readme":"# armos-mcp\n\nAutomatic PII masking for Claude Code. Every prompt you send gets scanned for personally identifiable information — emails, phone numbers, names, addresses, SSNs — and those values are replaced with tokens before leaving your machine. The real values are restored in the response, so Claude Code works normally while your sensitive data never reaches Anthropic.\n\n## How it works\n\n```\nClaude Code → localhost:3939 (armos-mcp proxy)\n                    ↓ PII replaced with tokens\n             proxy.armos.dev (armos cloud)\n                    ↓ masked request forwarded\n             api.anthropic.com\n                    ↓ response with tokens\n             proxy.armos.dev (tokens → real values)\n                    ↓ demasked response\nClaude Code ← localhost:3939\n```\n\nTwo components run as a single subprocess launched by Claude Code:\n- **HTTP proxy** (port 3939) — intercepts API calls and handles masking/demasking\n- **MCP server** (stdio) — exposes status and session management tools\n\n## Prerequisites\n\n- Node.js 18+\n- An armos account and API key — [armos.dev](https://armos.dev)\n- Claude Code CLI\n\n## Setup\n\n**1. Get your armos API key**\n\nSign up at [armos.dev](https://armos.dev), create an app, and copy the API key.\n\n**2. Register the MCP with Claude Code**\n\n```bash\nclaude mcp add armos npx @armos/mcp \\\n  -e ARMOS_API_KEY=arm_live_your_key_here \\\n  -e ARMOS_PROXY_URL=https://proxy.armos.dev \\\n  -e ARMOS_FAIL_MODE=open \\\n  -e ARMOS_PORT=3939\n```\n\n> **Note:** MCPs must be added via `claude mcp add`. Adding `mcpServers` to `~/.claude/settings.json` does not work — Claude Code reads MCPs from `~/.claude.json`.\n\n**3. Route Claude Code traffic through the proxy**\n\nAdd this to your `~/.zshrc` (or `~/.bashrc`):\n\n```bash\nexport ANTHROPIC_BASE_URL=http://localhost:3939\n```\n\nReload your shell and restart Claude Code:\n\n```bash\nsource ~/.zshrc\nclaude\n```\n\n## Verify it's working\n\nSend a prompt containing an email address:\n\n```\nWhat is the domain of the email john.smith@acme.com? Just the part after the @.\n```\n\nIf armos is active, Claude will respond saying it sees a PII token rather than the actual email — confirming the value never reached Anthropic.\n\nYou can also check session stats at any time by running the `armos_status` tool from `/mcp` in Claude Code.\n\n## MCP tools\n\n### `armos_status`\n\nReturns the current session state:\n\n```json\n{\n  \"conv_id\": \"3f8a1c2d-...\",\n  \"entities_masked_this_session\": 4,\n  \"fail_mode\": \"open\",\n  \"proxy_url\": \"https://proxy.armos.dev\",\n  \"local_port\": 3939\n}\n```\n\n### `armos_clear_session`\n\nRotates the conversation ID and resets the entity counter. Use this when starting a new sensitive conversation to ensure PII from prior turns can't be referenced in the new vault scope.\n\n## Configuration\n\n| Environment variable | Default | Description |\n|---|---|---|\n| `ARMOS_API_KEY` | — | Your armos API key (required) |\n| `ARMOS_PROXY_URL` | `https://proxy.armos.dev` | Armos proxy endpoint |\n| `ARMOS_FAIL_MODE` | `open` | `open` passes requests through unmasked if proxy is unreachable; `closed` blocks them |\n| `ARMOS_PORT` | `3939` | Local proxy port |\n\n## Fail modes\n\n**`open` (default)** — if the armos proxy is unreachable, requests are forwarded directly to Anthropic without masking. Claude Code keeps working; PII protection is silently bypassed.\n\n**`closed`** — if the armos proxy is unreachable, requests are blocked with a 503. Use this when unmasked requests are unacceptable (e.g. compliance environments).\n\n## What gets masked\n\n- Email addresses\n- Phone numbers\n- Person names\n- Physical addresses\n- Social Security Numbers\n- Credit card numbers\n- Custom entity types configured in your armos app\n\n## Building from source\n\n```bash\nnpm install\nnpm run build\n```\n\nThen register the local build instead of the npm package:\n\n```bash\nclaude mcp add armos node /path/to/armos-mcp/dist/index.js \\\n  -e ARMOS_API_KEY=arm_live_your_key_here \\\n  -e ARMOS_PROXY_URL=https://proxy.armos.dev \\\n  -e ARMOS_FAIL_MODE=open \\\n  -e ARMOS_PORT=3939\n```\n","readmeFilename":"README.md","_rev":"1-f02c299d5b06732f8b26228cb950738b"}