{"_id":"@acr-js/meta-mcp","name":"@acr-js/meta-mcp","dist-tags":{"latest":"0.8.2"},"versions":{"0.8.2":{"name":"@acr-js/meta-mcp","version":"0.8.2","description":"ACR Meta-MCP Forward Proxy: Policy-governed multi-server aggregation, sandboxing, and projection","type":"module","main":"dist/apps/control-plane-api/src/index.js","types":"dist/apps/control-plane-api/src/index.d.ts","bin":{"acr-meta-mcp":"dist/apps/cli/src/index.js"},"scripts":{"build":"tsc -b","test":"node --test dist/**/*.test.js || tsx --test packages/**/*.test.ts apps/**/*.test.ts","start":"node dist/apps/control-plane-api/src/index.js","dev":"tsx apps/control-plane-api/src/index.ts"},"keywords":["acr","mcp","meta-mcp","model-context-protocol","proxy","sandbox","policy","security"],"author":{"name":"@acr-js"},"license":"Apache-2.0","devDependencies":{"@types/node":"^22.20.1","tsx":"^4.19.0","typescript":"^5.9.3"},"gitHead":"6257a7e0b1100691dcbf78774d619383d359d0e0","_id":"@acr-js/meta-mcp@0.8.2","_nodeVersion":"26.7.0","_npmVersion":"12.0.2","dist":{"integrity":"sha512-16HQ7l1mlDWgiywVCYxC8Ok5jgrTT+Q2FYoGoFB+MC/AG255MdVH48NXcWbl2cXEJCubIo9kc0PNPu8Aazh+Cg==","shasum":"36eb4db5cf044fe9da0715315bc0c6616e8c5b86","tarball":"https://registry.npmjs.org/@acr-js/meta-mcp/-/meta-mcp-0.8.2.tgz","fileCount":166,"unpackedSize":277552,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDRe8yEhAQRIbUjfK5fH3tkWb0GCfAepsu3w9shoABnRwIhAMrb6F77v8mBYoY9qyoMC2UtJ/Db2TiS1tmQbrwyozb3"}]},"_npmUser":{"name":"acr-js","email":"dev@agentchatrooms.dev"},"directories":{},"maintainers":[{"name":"acr-js","email":"dev@agentchatrooms.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/meta-mcp_0.8.2_1788295788030_0.6321767716027495"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-01T20:49:47.816Z","0.8.2":"2026-09-01T20:49:48.186Z","modified":"2026-09-01T20:49:48.847Z"},"maintainers":[{"name":"acr-js","email":"dev@agentchatrooms.dev"}],"description":"ACR Meta-MCP Forward Proxy: Policy-governed multi-server aggregation, sandboxing, and projection","keywords":["acr","mcp","meta-mcp","model-context-protocol","proxy","sandbox","policy","security"],"author":{"name":"@acr-js"},"license":"Apache-2.0","readme":"# ACR Meta-MCP Forward Proxy & Governance Control Plane\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![NPM Organization](https://img.shields.io/badge/npm-%40acr--js-red.svg)](https://www.npmjs.com/org/acr-js)\n[![Tests: 30 Passing](https://img.shields.io/badge/tests-30%20passing-brightgreen.svg)]()\n[![TypeScript: Strict](https://img.shields.io/badge/TypeScript-Strict%20NodeNext-blue.svg)]()\n\nThe **ACR Meta-MCP Forward Proxy** is an enterprise-grade Model Context Protocol (MCP) reverse and forward proxy, sandbox runtime, and dual-consent governance engine. It implements the dual-layer MCP architecture for the Agentic Chat Rooms (ACR) ecosystem: a **native/master MCP layer** for internal platform orchestration and a **governed Meta-MCP fabric** for proxying, sandboxing, credential vaulting, and policy-controlling third-party MCP servers (stdio, SSE, Streamable HTTP).\n\n---\n\n## Architecture Overview\n\n```\n                          ┌────────────────────────────────────────────────────────┐\n                          │               ACR Native / Master Layer                │\n                          │        (Agent Trust Ledger, JetStream Bus, DIDs)       │\n                          └───────────────────────────┬────────────────────────────┘\n                                                      │ Dual-Consent Gate\n┌─────────────────────────────────────────────────────▼─────────────────────────────────────────────────────┐\n│                                       ACR Meta-MCP Forward Proxy (Port 20445)                             │\n│                                                                                                           │\n│  ┌───────────────────────┐   ┌────────────────────────┐   ┌────────────────────────────────────────────┐  │\n│  │ Config Ingestion      │   │ Policy Engine          │   │ Auth Vault (SQLite3MultipleCiphers)        │  │\n│  │ • Schema Validation   │   │ • Role & Room Scoping  │   │ • AES-256-GCM / ChaCha20-Poly1305 / CBC   │  │\n│  │ • Secret Redaction    │   │ • Quarantine Control   │   │ • PBKDF2-HMAC-SHA512 (256,000 iters)       │  │\n│  │ • SHA-256 Fingerprint │   │ • Escalation Hooks     │   │ • Multi-Domain Isolation (Personal/Org)    │  │\n│  └───────────┬───────────┘   └───────────┬────────────┘   └─────────────────────┬──────────────────────┘  │\n│              │                           │                                      │                         │\n│              └───────────────────────────┼──────────────────────────────────────┘                         │\n│                                          │                                                                │\n│                        ┌─────────────────▼──────────────────┐                                             │\n│                        │      3-Tier Catalog Projector      │                                             │\n│                        │  Raw -> Policy -> Projected View   │                                             │\n│                        └─────────────────┬──────────────────┘                                             │\n│                                          │                                                                │\n│  ┌───────────────────────────────────────▼─────────────────────────────────────────────────────────────┐  │\n│  │                                Transport Bridge & Sandbox Execution                                 │  │\n│  │  • Stdio Child Process (ToolHive Sandbox: no-network | egress-allowlist | workspace-scoped)          │  │\n│  │  • Streamable HTTP JSON-RPC 2.0 Endpoint (POST /mcp)                                                │  │\n│  │  • Server-Sent Events (SSE) Multiplexed Tunneling                                                   │  │\n│  └─────────────────────────────────────────────────────────────────────────────────────────────────────┘  │\n└───────────────────────────────────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Key Modules & Capabilities\n\n### 1. Config Ingestion (`packages/config-parser`)\n- Ingests standard `mcp_config.json` containing stdio (`command`/`args`/`env`) and remote (`url`/`headers`) server definitions.\n- Automatically redacts inline credentials and tokens into deterministic reference placeholders (`sec_ref_<server>_<key>`).\n- Generates canonical SHA-256 fingerprints for immutable `InstallManifest` versioning.\n\n### 2. Multi-Cipher Auth Vault (`packages/auth-vault`)\n- Fuses the cryptographic designs of **`utelle/SQLite3MultipleCiphers`** and **`sqlcipher/sqlcipher`**.\n- Encrypted at rest (`vault.db`) with 64-byte authenticated magic header `ACR_MCDB_V1`.\n- **Supported Ciphers**:\n  - `aes-256-gcm` (NIST SP 800-38D AEAD)\n  - `chacha20-poly1305` (RFC 8439 AEAD)\n  - `sqlcipher-v4` (AES-256-CBC + HMAC-SHA512 per record)\n- **Key Derivation**: PBKDF2-HMAC-SHA512 (256,000 iterations default) with per-database random salts.\n- **Domain Boundaries**: `personal`, `org`, `enterprise`, `ephemeral`.\n- **Master Passphrase Rotation**: Atomic re-encryption of all database records.\n\n### 3. ToolHive-Inspired Sandbox Containment (`packages/sandbox-runtime`)\n- Isolates untrusted stdio processes using 4 containment profiles:\n  - `no-network`: Prohibits external network calls; scrubs proxy settings.\n  - `egress-allowlist`: Allows outbound HTTP/HTTPS exclusively to verified endpoints (e.g. `api.github.com`, `gitee.com`).\n  - `filesystem-readonly`: Blocks write operations outside ephemeral runtime `/tmp`.\n  - `workspace-scoped`: Restricts disk access strictly to designated project directories.\n- Host environment variable sanitization and execution timeout bounds.\n\n### 4. Dual-Consent Policy Engine (`packages/policy-engine`)\n- Enforces access control at both the Master Layer and Meta-MCP Proxy Layer.\n- Scopes tool accessibility by caller role (`admin`, `agent`, `human_operator`, `guest`) and active room deliberation context.\n- Instant server quarantine mechanism (`toggleQuarantine`).\n- Human operator confirmation hooks (`REQUIRE_HUMAN_CONFIRMATION`).\n\n### 5. 3-Tier Catalog Projector (`packages/catalog-projector`)\n- **Raw Catalog**: All tools discovered from downstream servers with prefix namespacing (`${serverId}__${toolName}`).\n- **Policy Catalog**: Tools that pass server health, non-quarantine, and policy permission checks.\n- **Projected Catalog**: Persona-filtered tool view tailored to the requesting agent DID and permissions.\n\n### 6. Control Plane API & Streamable Gateway (`apps/control-plane-api`)\n- Native HTTP daemon running on port `20445`.\n- Private Network Access (PNA) and CORS compliant (`Access-Control-Allow-Private-Network: true`).\n- Streamable HTTP JSON-RPC 2.0 gateway at `POST /mcp`.\n- Replay audit logging with sub-millisecond precision.\n\n---\n\n## Environment Variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `ACR_META_MCP_PORT` | `20445` | HTTP listen port for Control Plane and MCP Gateway |\n| `ACR_META_MCP_HOST` | `0.0.0.0` | Listen host interface |\n| `ACR_VAULT_PATH` | (in-memory) | File path to encrypted MultipleCiphers database (`vault.db`) |\n| `ACR_VAULT_SECRET` | (generated) | Master encryption secret for Auth Vault |\n| `CONTEXT7_API_KEY` | (optional) | Dynamic API key for Context7 real-time library docs MCP |\n\n---\n\n## REST API Reference\n\n| Method | Endpoint | Description |\n|---|---|---|\n| `GET` | `/health` | Daemon status, version, server count, uptime |\n| `GET` | `/api/v1/meta-mcp/servers` | List registered downstream MCP servers |\n| `POST` | `/api/v1/meta-mcp/servers/import` | Import and compile standard `mcp_config.json` |\n| `POST` | `/api/v1/meta-mcp/servers/:id/toggle` | Enable or disable a registered server |\n| `POST` | `/api/v1/meta-mcp/servers/:id/quarantine` | Toggle quarantine status for a server |\n| `GET` | `/api/v1/meta-mcp/tools` | Query tool catalog (`?view=raw\\|policy\\|projected`) |\n| `POST` | `/api/v1/meta-mcp/tools/call` | Invoke a governed tool execution |\n| `GET` | `/api/v1/meta-mcp/vault/secrets` | List vaulted secret refs with domain & cipher info |\n| `POST` | `/api/v1/meta-mcp/vault/secrets` | Store an encrypted secret in the MultipleCiphers DB |\n| `DELETE` | `/api/v1/meta-mcp/vault/secrets/:refId` | Purge a secret from the encrypted DB |\n| `POST` | `/api/v1/meta-mcp/vault/rotate` | Rotate master passphrase & re-encrypt DB |\n| `GET` | `/api/v1/meta-mcp/audit` | Replay cryptographic audit trail logs |\n| `POST` | `/mcp` | Streamable HTTP JSON-RPC 2.0 MCP Gateway |\n\n---\n\n## CLI Usage\n\n### Standalone Node CLI (`@acr-js/meta-mcp`)\n```bash\n# Check daemon health\nacr-meta-mcp health\n\n# List registered servers\nacr-meta-mcp list\n\n# Import mcp_config.json\nacr-meta-mcp import ./path/to/mcp_config.json\n\n# Query tools catalog\nacr-meta-mcp tools projected\n\n# Call governed tool\nacr-meta-mcp call context7__query-docs '{\"libraryId\":\"/vercel/next.js\",\"query\":\"App Router\"}'\n\n# Manage encrypted Auth Vault\nacr-meta-mcp vault list\nacr-meta-mcp vault set context7 CONTEXT7_API_KEY \"ctx7sk_...\" personal chacha20-poly1305\nacr-meta-mcp vault rotate \"new-secure-passphrase\"\nacr-meta-mcp vault delete sec_ref_context7_context7_api_key\n\n# Manage and test dynamic port bindings\nacr-meta-mcp ports list\nacr-meta-mcp ports set acr-meta-mcp 20495\nacr-meta-mcp ports test\nacr-meta-mcp ports export\n\n# View audit logs\nacr-meta-mcp audit\n```\n\n### Native Dart CLI (`acr-cli`)\n```bash\nacr meta-mcp list\nacr meta-mcp import ./mcp_config.json\nacr meta-mcp tools --view=projected\nacr meta-mcp call context7__resolve-library-id '{\"libraryName\":\"React\"}'\nacr meta-mcp vault list\nacr meta-mcp vault set --server=github --key=GITHUB_TOKEN --value=\"ghp_...\"\nacr ports list\nacr ports set acr-meta-mcp 20495\nacr ports test\nacr meta-mcp audit\n```\n\n---\n\n## Integration with MCP Clients\n\nAdd the ACR Meta-MCP Forward Proxy to any standard MCP client (`claude_desktop_config.json`, `~/.cursor/mcp.json`, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"acr-meta-mcp\": {\n      \"url\": \"http://localhost:20445/mcp\"\n    }\n  }\n}\n```\n\nAll downstream tools (Context7, GitHub, Gitee, filesystem sandbox, custom agents) will be dynamically projected, sandboxed, and governed under dual-consent policy rules.\n\n---\n\n## Test Suite Execution\n\n```bash\nnpm install\nnpm test\n```\n\n```\n✔ Meta-MCP Control Plane API & JSON-RPC Gateway (8 tests passed)\n✔ Context7 Real MCP Tool E2E Integration & QA Test (7 tests passed)\n✔ Auth Vault (SQLite3MultipleCiphers & SQLCipher Engine) (5 tests passed)\n✔ Catalog Projector (3-Tier Catalog Pipeline) (2 tests passed)\n✔ Config Parser & Manifest Compiler (2 tests passed)\n✔ Policy Engine & Dual Consent (3 tests passed)\n✔ Registry Core (State Machine & Server Persistence) (1 test passed)\n✔ Sandbox Runtime (Containment Engine) (2 tests passed)\n\n30 tests passed, 0 failed (971ms)\n```\n","readmeFilename":"README.md","_rev":"1-787b82da0f5162dba2a66b8e6da8c349"}