mcp-nervous-system 1.11.0 → 1.12.0

package/README.md

@@ -1,239 +1,32 @@
-# The Nervous System
+# Agent Manifests
 
-**LLM Behavioral Enforcement Framework**
+The following manifest files define governance settings for each agent:
 
-## Quick Start (2 minutes)
+- `tamara.manifest.yaml` - Oversees multi-agent operations with elevated permissions and reliability controls.
+- `lily.manifest.yaml` - Guides users with public-facing coaching plans and motivational feedback.
+- `kris.manifest.yaml` - Analyzes business credit signals and flags potential financial risk patterns.
+- `aram.manifest.yaml` - Provides legal guidance under strict escalation and compliance boundaries.
+- `harry.manifest.yaml` - Handles strict financial data workflows for bookkeeping and reconciliations.
+- `harout.manifest.yaml` - Supports client-facing real estate workflows for listings and buyer matching.
+- `roman.manifest.yaml` - Creates educational content and lesson structures for clear learning outcomes.
+- `lou.manifest.yaml` - Finds grant opportunities and synthesizes eligibility and deadline requirements.
+- `spartak.manifest.yaml` - Translates multilingual content accurately while preserving tone and intent.
+- `nick.manifest.yaml` - Delivers advanced training workflows with restricted data and access controls.
+- `corona.manifest.yaml` - Develops creative real estate concepts, campaigns, and positioning strategies.
+- `soriano.manifest.yaml` - Designs youth empowerment programs with supportive coaching and resource guidance.
+- `lady.manifest.yaml` - Executes parallel workstreams across five lanes with synchronized delivery control.
 
-```bash
-npx mcp-nervous-system
-# Server starts on port 3475
-```
+## Governance lint + paid x402 API
 
-Add to Claude Code:
-```bash
-claude mcp add nervous-system npx mcp-nervous-system
-```
+The Nervous System is an external governance layer for agent systems: governance, attribution, and coordination across vendors.
 
-Add to Cursor / Windsurf / Cline - use the hosted endpoint (no install):
-```
-https://api.100levelup.com/mcp-ns/
-```
+### Free, local tool: `audit_mcp_config`
+Deterministic governance lint for MCP server configurations. Pass the config JSON (e.g. `claude_desktop_config.json`) as `config` (object) or `config_json` (string). It checks for plaintext secrets in `env`, unpinned packages, auto-install flags, broad filesystem scopes, shell wrappers, non-TLS remote transports, and unpinned docker tags, then returns findings with severities and a 0-100 score. Zero dependencies, fully offline, never throws.
 
-That's it. You now have 32 governance tools: preflight checks, audit trails, drift detection, security scans, and a kill switch.
+### Hosted x402 API (pay-per-call)
+For CI/agent use, the same checks plus audit-chain verification are available as pay-per-call HTTP endpoints priced in USDC on Base (x402):
 
----
+- `POST https://api.100levelup.com/x402/audit-mcp` - governance lint ($0.05 USDC)
+- `GET  https://api.100levelup.com/x402/verify-audit` - audit-chain verification ($0.005 USDC)
 
-7 mechanically enforced rules that prevent the most common failure modes when LLMs have access to real infrastructure: context loss, silent failures, file damage, goal drift, and overreach.
-
-Built by [Arthur Palyan](https://www.levelsofself.com) at Palyan Family AI System. 30 tools including configuration drift detection, emergency kill switch, usage monitoring, and bot compliance auditing. Battle-tested on a 13-agent AI family running 28 processes 24/7 on a $300/month infrastructure (7.8GB RAM, 154GB SSD). SAM.gov registered (CAGE 19R10). 35 partners across 10 countries. 99+ violations caught, 0 bypassed.
-
-## The Problem
-
-When you give an LLM access to your file system, bash, and production infrastructure, it will eventually:
-
-- Edit a file it shouldn't touch
-- Lose context between sessions and start over
-- Drift from the original objective during long tasks
-- Fail silently when a session times out
-- Make logic changes without asking
-- Disappear into debug loops
-
-The Nervous System solves all of these with rules enforced by external mechanisms the LLM cannot override.
-
-## Install
-
-### Claude Desktop
-
-Add to your `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "nervous-system": {
-      "command": "npx",
-      "args": ["-y", "mcp-nervous-system"]
-    }
-  }
-}
-```
-
-### Claude Code
-
-```bash
-claude mcp add nervous-system npx mcp-nervous-system
-```
-
-### Direct
-
-```bash
-npx mcp-nervous-system
-```
-
-Server starts on port 3475 with SSE, HTTP, and health endpoints.
-
-### Hosted (No Install)
-
-The server is live and ready to use:
-
-```
-URL: https://api.100levelup.com/mcp-ns/
-Protocol: MCP 2024-11-05 (Streamable HTTP + SSE)
-Authentication: None required
-```
-
-## NEW in v1.9.3
-
-**Platform Integration Guides** - Working examples for governing multi-agent systems on the 3 biggest platforms plus any MCP client. Each guide gets you to governed agents in under 10 minutes.
-
-- [Ruflo (claude-flow)](./integrations/ruflo/) - Queen-Worker hive mind governance with preflight checks, drift audits, and violation logging to swarm_state
-- [Hivemind](./integrations/hivemind/) - Team chat agent governance with tool interception, heartbeat drift audits, and session handoffs
-- [Anthropic Agent Teams](./integrations/agent-teams/) - Parallel agent governance via CLAUDE.md propagation with shared untouchable lists and unified audit trails
-- [Generic MCP](./integrations/generic-mcp/) - 5-minute setup for any MCP client (Claude Desktop, Claude Code, Cursor, Windsurf, Cline)
-
-## v1.9.3
-
-**Tamara Reference Implementation + Case Study** (2 new resources)
-Production reference implementation of an autonomous AI operations manager built on the Nervous System. Includes full architecture documentation, build-your-own guide, and case study with real metrics from managing 13 agents across 5 platforms.
-
-## v1.9.3
-
-**drift_audit** (free tier)
-Configuration drift detection across 5 scopes: roles, versions, files, processes, and website. Scans source-of-truth files (family-roles.json, package.json, UNTOUCHABLE_FILES.txt) against all downstream references - HTML pages, JSON configs, markdown docs, and running PM2 processes. Change one file, drift_audit tells you everywhere else that needs updating. The closed loop that keeps your entire system consistent.
-
-**Positioning: Auto mode decides what Claude CAN do. The Nervous System governs HOW it behaves while doing it.**
-
-## The 7 Rules
-
-| # | Rule | What It Prevents |
-|---|------|-----------------|
-| 1 | **Dispatch Don't Do** | Debug loops, rabbit holes. Tasks > 2 messages get dispatched. |
-| 2 | **Untouchable** | File damage. Protected files mechanically blocked from editing. |
-| 3 | **Write Progress** | Silent failures. Progress noted before each action. |
-| 4 | **Step Back Every 4** | Goal drift. Forced reflection every 4 messages. |
-| 5 | **Delegate and Return** | Invisible work. Background tasks reported immediately. |
-| 6 | **Ask Before Touching** | Unauthorized changes. Logic changes need human approval. |
-| 7 | **Hand Off** | Context loss. Written handoffs every 3-4 exchanges. |
-
-## MCP Tools (21)
-
-| Tool | Description |
-|------|------------|
-| `get_framework` | Complete framework: all rules, permission protocol, enforcement patterns |
-| `guardrail_rules` | The 7 core rules with triggers, enforcement, and failure modes |
-| `preflight_check` | File protection system: shell script blocks edits to protected files |
-| `session_handoff` | Context preservation: templates for handoff documents |
-| `worklog` | Progress documentation pattern |
-| `violation_logging` | Audit trail: timestamp, type, context for every violation |
-| `step_back_check` | Forced reflection system |
-| `get_nervous_system_info` | System overview and operational stats |
-| `emergency_kill_switch` | Emergency shutdown of all PM2 processes. Requires kill switch secret. Logs to tamper-evident audit trail |
-| `verify_audit_chain` | Walks the SHA-256 hash-chained audit log and verifies every entry. Returns chain integrity status |
-| `dispatch_to_llm` | Spawns a background LLM agent to handle a task. Checks RAM, enforces max 2 concurrent dispatches |
-| `drift_audit` | Configuration drift detection across roles, versions, files, processes, and website. Finds stale values everywhere. |
-
-## Kill Switch
-
-The `emergency_kill_switch` tool provides an emergency shutdown capability. Send a POST request to `/kill` with the kill switch secret to immediately stop all PM2 processes. Every activation is logged to the tamper-evident audit trail with SHA-256 hash chaining, so kill switch events cannot be hidden or altered after the fact.
-
-- Requires authentication (kill switch secret)
-- Logs to hash-chained audit trail
-- Returns confirmation with affected process count
-
-## Tamper-Evident Audit Trail
-
-Every guardrail violation, kill switch activation, and dispatch event is recorded in a SHA-256 hash-chained audit log. Each entry includes the hash of the previous entry, making it cryptographically impossible to alter or delete past records without breaking the chain.
-
-- Use `verify_audit_chain` to walk the entire chain and verify integrity
-- Returns: valid/invalid status, entry count, and break point if tampered
-- 99+ violations caught, 0 bypassed, 0 chain breaks
-
-## Dispatch to LLM
-
-The `dispatch_to_llm` tool enables a brain + agents architecture. Instead of one LLM session doing everything, complex tasks get dispatched to background agents that run independently under the same 7 rules.
-
-- Checks available RAM (requires 500MB+)
-- Enforces max 2 concurrent dispatches
-- Returns PID and log file path for monitoring
-- Every dispatched agent runs under the same nervous system guardrails
-
-## EU AI Act Compliance
-
-The Nervous System provides practical compliance tools for the EU AI Act. See the full compliance page at:
-
-https://api.100levelup.com/family/eu-ai-act.html
-
-## Production Reference: Tamara
-
-Tamara is an autonomous AI operations manager built on the Nervous System framework. She manages 13 AI agents across 5 platforms, serving 175+ countries accessible from a $12/month VPS - without dedicated DevOps staff.
-
-Tamara is the proof that the Nervous System works in production. She runs 60-minute autonomous check cycles, detects configuration drift, dispatches remediation agents, and reports to the human operator only when judgment is needed.
-
-- **Case Study**: Use the `nervous-system://case-study` resource for full production metrics
-- **Reference Implementation**: Use the `nervous-system://tamara-reference` resource for architecture details and build-your-own guide
-- **Enterprise Support**: For organizations deploying AI agent fleets at scale, implementation consulting is available at wa.me/18184399770
-- **Blog**: [Meet Tamara](https://api.100levelup.com/family/blog/meet-tamara.md) | [Why AI Agent Management Is the Next Infrastructure Layer](https://api.100levelup.com/family/blog/ai-agent-management.md)
-
-## Resources (7)
-
-- `nervous-system://framework` - The complete framework
-- `nervous-system://quick-start` - Quick start guide
-- `nervous-system://rules` - The 7 core rules
-- `nervous-system://templates` - Templates for handoffs, worklogs, preflight
-- `nervous-system://drift-audit` - Configuration drift detection
-- `nervous-system://tamara-reference` - Tamara autonomous ops manager reference implementation
-- `nervous-system://case-study` - Palyan Family AI System production case study
-
-## Production Stats
-
-From the live Palyan Family AI System deployment (Feb 28 - Mar 5, 2026):
-
-- **58+** violations caught
-- **29** edits blocked by preflight
-- **100** files protected
-- **0** rules bypassed
-- **27** processes monitored
-- **5** days continuous operation
-
-## Live Demo
-
-Try it yourself (no login required):
-
-- **[Interactive Demo](https://api.100levelup.com/family/arthur.html?guest=1)** - Talk to a governed LLM and try to break the rules
-- **[Audit Dashboard](https://api.100levelup.com/family/audit.html)** - See real violation history with timeline
-- **[System Status](https://api.100levelup.com/family/status.html)** - Live health checks
-- **[API Documentation](https://api.100levelup.com/family/api-docs.html)** - Full tool and resource reference
-- **[Case Study](https://api.100levelup.com/family/case-study.html)** - Production deployment data
-- **[Plain English Rules](https://api.100levelup.com/family/rules-plain.html)** - For non-technical stakeholders
-- **[Incident Response](https://api.100levelup.com/family/incident-response.html)** - Detection, containment, resolution
-- **[EU AI Act Compliance](https://api.100levelup.com/family/eu-ai-act.html)** - Practical EU AI Act compliance tools
-
-## Integrations
-
-Works with the major multi-agent platforms and any MCP client:
-
-| Platform | Integration | Setup Time |
-|----------|------------|------------|
-| **[Ruflo (claude-flow)](./integrations/ruflo/)** | Plugin hooks into Queen-Worker pipeline | 10 min |
-| **[Hivemind](./integrations/hivemind/)** | MCP connector with tool interception | 10 min |
-| **[Anthropic Agent Teams](./integrations/agent-teams/)** | CLAUDE.md governance propagation | 10 min |
-| **[Any MCP Client](./integrations/generic-mcp/)** | 3 lines of config | 5 min |
-
-Each integration includes working code, example configs, and a step-by-step README.
-
-## Agent Skills
-
-The Nervous System is also available as an Agent Skill following the open [Agent Skills standard](https://agentskills.io). Install the governance skill to teach any AI agent (Claude, Codex, Cursor, Copilot, VS Code) how to enforce behavioral guardrails in multi-agent systems.
-
-See `skills/multi-agent-governance/SKILL.md` for the full skill definition.
-
-## Philosophy
-
-> "LLMs can't reliably self-enforce promises. Guardrails work via preflight.sh, violation logs, and catching drift. Build enforcement systems, don't make promises."
-
-If a guardrail can be violated by the thing it guards, it is not a guardrail. It is a suggestion.
-
-Every rule in the Nervous System is enforced by an external mechanism: a shell script, a timer, a separate monitoring process. The LLM cannot override, circumvent, or ignore them.
-
-## License
-
-MIT
+Discovery: [`/openapi.json`](https://api.100levelup.com/openapi.json) and [`/llms.txt`](https://api.100levelup.com/llms.txt).

package/aram.manifest.yaml

@@ -0,0 +1,22 @@
+agent_id: "aram"
+role: "legal counsel"
+version: "1.0.0"
+description: "Provides legal guidance under strict escalation and compliance boundaries."
+capabilities:
+  - "policy_interpretation"
+  - "compliance_review"
+  - "escalation_routing"
+required_tools:
+  - "policy_engine"
+  - "citation_retriever"
+  - "approval_gate"
+policy: "/root/levels-os/governance/policies/agents/aram.yaml"
+memory_access:
+  global_read: true
+  agent_read: true
+  agent_write: false
+max_runtime_minutes: 30
+model_preference: "ollama-qwen3"
+fallback_model: "claude-sonnet"
+cost_limit_usd: 1.0
+heartbeat_interval_sec: 30

package/corona.manifest.yaml

@@ -0,0 +1,22 @@
+agent_id: "corona"
+role: "creative real estate"
+version: "1.0.0"
+description: "Develops creative real estate concepts, campaigns, and positioning strategies."
+capabilities:
+  - "campaign_concepting"
+  - "property_storytelling"
+  - "market_positioning"
+required_tools:
+  - "content_editor"
+  - "media_planner"
+  - "listing_database"
+policy: "/root/levels-os/governance/policies/agents/corona.yaml"
+memory_access:
+  global_read: true
+  agent_read: true
+  agent_write: true
+max_runtime_minutes: 60
+model_preference: "ollama-qwen3"
+fallback_model: "claude-sonnet"
+cost_limit_usd: 2.0
+heartbeat_interval_sec: 30

package/harout.manifest.yaml

@@ -0,0 +1,22 @@
+agent_id: "harout"
+role: "realtor"
+version: "1.0.0"
+description: "Supports client-facing real estate workflows for listings and buyer matching."
+capabilities:
+  - "listing_analysis"
+  - "client_communication"
+  - "market_comparison"
+required_tools:
+  - "listing_database"
+  - "crm_connector"
+  - "calendar_scheduler"
+policy: "/root/levels-os/governance/policies/agents/harout.yaml"
+memory_access:
+  global_read: true
+  agent_read: true
+  agent_write: true
+max_runtime_minutes: 60
+model_preference: "ollama-qwen3"
+fallback_model: "claude-sonnet"
+cost_limit_usd: 2.0
+heartbeat_interval_sec: 30

package/harry.manifest.yaml

@@ -0,0 +1,22 @@
+agent_id: "harry"
+role: "accountant"
+version: "1.0.0"
+description: "Handles strict financial data workflows for bookkeeping and reconciliations."
+capabilities:
+  - "ledger_reconciliation"
+  - "expense_classification"
+  - "financial_reporting"
+required_tools:
+  - "ledger_reader"
+  - "calculator"
+  - "audit_logger"
+policy: "/root/levels-os/governance/policies/agents/harry.yaml"
+memory_access:
+  global_read: true
+  agent_read: true
+  agent_write: false
+max_runtime_minutes: 30
+model_preference: "ollama-qwen3"
+fallback_model: "claude-sonnet"
+cost_limit_usd: 1.0
+heartbeat_interval_sec: 30

package/index.js

@@ -538,7 +538,7 @@ const NERVOUS_SYSTEM_INFO = {
     ]
   },
   origin_story: {
-    context: 'Arthur Palyan runs a startup with 12 AI family members, each with distinct roles. The entire operation runs on a $24/month VPS with a $200/month LLM subscription.',
+    context: 'Arthur Palyan runs a startup with 12 AI family members, each with distinct roles. The entire operation runs on a ~$48/month VPS with a $200/month LLM subscription, about $375/month all in.',
     problem_discovered: 'After months of building, patterns emerged: LLMs would break working systems while trying to improve them. They would loop on debugging instead of dispatching. They would silently fail when sessions timed out. They would lose all context between sessions.',
     solution_built: 'Arthur built the nervous system - not by changing the LLM model, but by wrapping it in behavioral rules enforced through scripts, file checks, and prompt engineering. The LLM itself became the enforcement mechanism, trained to check before acting.',
     philosophy: 'The brain (LLM) is powerful but needs a nervous system to keep it from hurting itself. Just like a human nervous system sends pain signals before you touch a hot stove, this system sends BLOCKED/PROTECTED signals before the LLM edits a critical file.',
@@ -570,7 +570,7 @@ const NERVOUS_SYSTEM_INFO = {
     reflection_trigger: 'Every 4 messages',
     processes_managed: '22+ autonomous PM2 processes',
     family_members: 12,
-    monthly_cost: 'Under $300/month total infrastructure',
+    monthly_cost: 'Under $500/month total infrastructure (about $375 actual)',
     uptime: '24/7 autonomous operation',
     deployment: 'Single VPS, single LLM subscription'
   }
@@ -895,7 +895,7 @@ const RESOURCES = [
   { uri: 'nervous-system://templates', name: 'Templates', description: 'Ready-to-use templates for handoffs, worklogs, preflight, and untouchable lists', mimeType: 'text/plain' },
   { uri: 'nervous-system://drift-audit', name: 'Drift Audit', description: 'Configuration drift detection - checks roles, versions, file references, and running processes against source-of-truth files', mimeType: 'text/plain' },
   { uri: 'nervous-system://tamara-reference', name: 'Tamara Reference Implementation', description: 'Autonomous AI operations manager - reference implementation for managing AI agent fleets using the Nervous System framework', mimeType: 'text/plain' },
-  { uri: 'nervous-system://case-study', name: 'Palyan Family AI System Case Study', description: 'Production case study: 13 agents, 5 platforms, 175 countries, $24/month - autonomous AI operations at scale', mimeType: 'text/plain' },
+  { uri: 'nervous-system://case-study', name: 'Palyan Family AI System Case Study', description: 'Production case study: 13 agents, 5 platforms, 175 countries, under $500/month - autonomous AI operations at scale', mimeType: 'text/plain' },
 ];
 
 // ============================================================
@@ -3875,7 +3875,7 @@ PRODUCTION RESULTS
 - 13 AI agents managed autonomously
 - 5 platforms (Telegram, Instagram, Facebook, Web, Bot Builder)
 - 175 countries served
-- $24/month total infrastructure cost
+- Under $500/month total infrastructure cost (about $375 actual)
 - Zero dedicated DevOps staff
 - 99+ protected files with automated enforcement
 - Autonomous operation for weeks without human intervention
@@ -3900,7 +3900,7 @@ Open source: npmjs.com/package/mcp-nervous-system`;
 Autonomous AI Operations at Scale
 
 OVERVIEW
-The Palyan Family AI System is a production deployment of 13 specialized AI agents serving users across 175 countries through 5 platforms. The entire operation runs on a single 4GB VPS for $24/month, managed autonomously by Tamara - an AI operations manager built on the Nervous System framework.
+The Palyan Family AI System is a production deployment of 13 specialized AI agents serving users across 175 countries through 5 platforms. The entire operation runs on a single 4GB VPS for about $48/month, managed autonomously by Tamara - an AI operations manager built on the Nervous System framework.
 
 This is not a demo. This is a live system that has been running continuously since February 2026, processing real user interactions, managing real infrastructure, and operating without dedicated DevOps staff.
 
@@ -3923,7 +3923,7 @@ INFRASTRUCTURE
 - Server: 4GB VPS (Ubuntu)
 - Process Manager: PM2 (29 registered processes, 19+ online)
 - LLM Access: Anthropic Max subscription
-- Total Monthly Cost: $24 (VPS $12 + domain/misc $12)
+- Total Monthly Cost: ~$375 (VPS ~$48 + LLM ~$200 + Vercel/insurance/tools)
 - Platforms: Telegram, Instagram, Facebook Messenger, Web, Bot Builder SaaS
 
 GOVERNANCE LAYER

package/kris.manifest.yaml

@@ -0,0 +1,22 @@
+agent_id: "kris"
+role: "business credit scanner"
+version: "1.0.0"
+description: "Analyzes business credit signals and flags potential financial risk patterns."
+capabilities:
+  - "credit_profile_scan"
+  - "risk_scoring"
+  - "report_generation"
+required_tools:
+  - "data_fetcher"
+  - "risk_engine"
+  - "report_writer"
+policy: "/root/levels-os/governance/policies/agents/kris.yaml"
+memory_access:
+  global_read: true
+  agent_read: true
+  agent_write: true
+max_runtime_minutes: 60
+model_preference: "ollama-qwen3"
+fallback_model: "claude-sonnet"
+cost_limit_usd: 2.0
+heartbeat_interval_sec: 30

package/lady.manifest.yaml

@@ -0,0 +1,24 @@
+agent_id: "lady"
+role: "5-lane executor"
+version: "1.0.0"
+description: "Executes parallel workstreams across five lanes with synchronized delivery control."
+capabilities:
+  - "parallel_execution"
+  - "priority_routing"
+  - "status_synchronization"
+  - "handoff_coordination"
+required_tools:
+  - "lane_orchestrator"
+  - "task_dispatcher"
+  - "status_board"
+  - "audit_logger"
+policy: "/root/levels-os/governance/policies/agents/lady.yaml"
+memory_access:
+  global_read: true
+  agent_read: true
+  agent_write: true
+max_runtime_minutes: 60
+model_preference: "ollama-qwen3"
+fallback_model: "claude-sonnet"
+cost_limit_usd: 2.0
+heartbeat_interval_sec: 30

package/lib/mcp-audit.js

@@ -0,0 +1,184 @@
+'use strict';
+// mcp-audit.js - deterministic governance lint for MCP server configurations.
+// Zero deps, pure Node. Powers the paid POST /audit-mcp SKU in x402-app.js.
+//
+//   auditMcpConfig(input) -> { score:0-100, findings:[...], summary:{...} }   (never throws)
+//   Malformed input                       -> { error, hint }  (no throw)
+//
+// Input is PARSED JSON, either:
+//   Claude-Desktop shape  { "mcpServers": { "<name>": {command,args,env,...} } }
+//   or a single server    { command, args, env, ... }
+//
+// Each finding: { severity:'error'|'warn'|'info', code, server, message, hint }
+// Score: start 100; -25 per error, -10 per warn, -2 per info; floor 0.
+
+// Recognized keys (typo detection). Anything else -> UNKNOWN_TOP_FIELDS (info).
+const KNOWN_TOP_KEYS = new Set(['mcpServers']);
+const KNOWN_SERVER_KEYS = new Set([
+  'command', 'args', 'env', 'url', 'transport', 'type', 'cwd', 'name',
+  'disabled', 'enabled', 'autoApprove', 'alwaysAllow', 'timeout', 'headers', 'description'
+]);
+// Flags that consume the following token as their value (so it is NOT the docker image / package).
+const VALUE_FLAGS = new Set([
+  '-e', '--env', '-v', '--volume', '-p', '--publish', '--name', '-w', '--workdir',
+  '--network', '-u', '--user', '--mount', '--label', '-l', '--entrypoint'
+]);
+
+function baseName(cmd) {
+  if (typeof cmd !== 'string') return '';
+  const parts = cmd.replace(/\\/g, '/').split('/');
+  return parts[parts.length - 1].toLowerCase();
+}
+
+function isEnvRef(v) {
+  // ${VAR} / $VAR / plain reference -> not an inline secret.
+  return /^\$\{?[A-Za-z_][A-Za-z0-9_]*\}?$/.test(String(v).trim());
+}
+
+function looksHighEntropy(v) {
+  // 20+ chars, token-like charset, mixes letters AND digits -> probably a real credential.
+  return v.length >= 20 && /^[A-Za-z0-9+/=_.\-]{20,}$/.test(v) && /[0-9]/.test(v) && /[A-Za-z]/.test(v);
+}
+
+function firstNonFlagArg(args) {
+  for (const a of args) { if (typeof a === 'string' && !a.startsWith('-')) return a; }
+  return null;
+}
+
+// Best-effort docker image extraction: first bare token after `run`, skipping flags + their values.
+function dockerImage(args) {
+  const i = args.indexOf('run');
+  if (i < 0) return null;
+  for (let j = i + 1; j < args.length; j++) {
+    const a = args[j];
+    if (typeof a !== 'string') continue;
+    if (a.startsWith('-')) { if (VALUE_FLAGS.has(a)) j++; continue; } // skip flag (and its value)
+    return a; // first bare token = the image reference
+  }
+  return null;
+}
+
+function checkServer(name, srv, findings) {
+  const push = (severity, code, message, hint) => findings.push({ severity, code, server: name, message, hint });
+  if (!srv || typeof srv !== 'object' || Array.isArray(srv)) {
+    push('info', 'UNKNOWN_TOP_FIELDS', 'server entry is not an object', 'Each server must map to an object with command/url + args/env.');
+    return;
+  }
+  const args = Array.isArray(srv.args) ? srv.args : [];
+  const cmd = baseName(srv.command);
+
+  // Unknown server-level keys (typo detection).
+  for (const k of Object.keys(srv)) {
+    if (!KNOWN_SERVER_KEYS.has(k)) {
+      push('info', 'UNKNOWN_TOP_FIELDS', 'unrecognized server field "' + k + '"', 'Check for a typo; expected command/args/env/url/type.');
+    }
+  }
+
+  // SECRET_IN_ENV (error)
+  if (srv.env && typeof srv.env === 'object' && !Array.isArray(srv.env)) {
+    for (const [k, v] of Object.entries(srv.env)) {
+      if (typeof v !== 'string' || v.length === 0 || isEnvRef(v)) continue;
+      const keyMatch = /key|token|secret|password|passwd|pwd|credential|apikey|auth|access[_-]?id|private/i.test(k);
+      if (keyMatch) {
+        push('error', 'SECRET_IN_ENV', 'env "' + k + '" appears to hold an inline credential', 'Reference a secret via ${ENV_VAR} or a secret manager; never inline credentials.');
+      } else if (looksHighEntropy(v)) {
+        push('error', 'SECRET_IN_ENV', 'env "' + k + '" holds a high-entropy value that looks like a secret', 'Reference a secret via ${ENV_VAR} or a secret manager; never inline credentials.');
+      }
+    }
+  }
+
+  // SHELL_WRAPPER (warn) - sh/bash/zsh -c hides the real binary
+  if ((cmd === 'sh' || cmd === 'bash' || cmd === 'zsh') && args.some((a) => a === '-c')) {
+    push('warn', 'SHELL_WRAPPER', 'command wraps the real binary in ' + cmd + ' -c', 'Invoke the real binary directly instead of wrapping in a shell.');
+  }
+
+  // UNPINNED_PACKAGE (warn) + AUTO_INSTALL_FLAG (warn) for npx/uvx/bunx-style runners
+  if (cmd === 'npx' || cmd === 'uvx' || cmd === 'bunx' || cmd === 'pnpm' || cmd === 'yarn') {
+    const pkg = firstNonFlagArg(args);
+    if (pkg) {
+      const body = pkg.startsWith('@') ? pkg.slice(1) : pkg; // strip scope so @scope/x isn't read as a pin
+      if (!body.includes('@')) {
+        push('warn', 'UNPINNED_PACKAGE', 'package "' + pkg + '" is not version-pinned', 'Pin the version (name@1.2.3) to prevent supply-chain drift.');
+      }
+    }
+    if (args.some((a) => a === '-y' || a === '--yes')) {
+      push('warn', 'AUTO_INSTALL_FLAG', cmd + ' auto-installs unreviewed code (-y/--yes)', 'Remove -y/--yes; review packages before first execution.');
+    }
+  }
+
+  // BROAD_FS_SCOPE (warn) - filesystem servers granted / or a home root
+  const joined = (srv.command ? srv.command + ' ' : '') + args.join(' ');
+  const isFs = /filesystem/i.test(joined) || srv.type === 'filesystem' || /(^|[^a-z])fs($|[^a-z])/i.test(String(srv.name || ''));
+  if (isFs) {
+    for (const a of args) {
+      if (typeof a !== 'string') continue;
+      if (/^(\/|~|\$HOME|\/root|\/home\/[^/]+|\/Users\/[^/]+)\/?$/.test(a.trim())) {
+        push('warn', 'BROAD_FS_SCOPE', 'filesystem access granted to broad path "' + a + '"', 'Scope filesystem access to a specific project subdirectory, not / or $HOME.');
+      }
+    }
+  }
+
+  // REMOTE_URL_NO_TLS (error) - http:// to a non-localhost host
+  const urlCandidates = [];
+  if (typeof srv.url === 'string') urlCandidates.push(srv.url);
+  if (srv.transport && typeof srv.transport === 'object' && typeof srv.transport.url === 'string') urlCandidates.push(srv.transport.url);
+  for (const a of args) { if (typeof a === 'string' && /^https?:\/\//i.test(a)) urlCandidates.push(a); }
+  for (const raw of urlCandidates) {
+    let u; try { u = new URL(raw); } catch (e) { continue; }
+    if (u.protocol !== 'http:') continue;
+    const h = u.hostname.toLowerCase();
+    const local = h === 'localhost' || h === '127.0.0.1' || h === '0.0.0.0' || h === '::1' || h.endsWith('.local');
+    if (!local) {
+      push('error', 'REMOTE_URL_NO_TLS', 'remote transport uses plaintext http:// (' + h + ')', 'Use https:// for remote transports.');
+    }
+  }
+
+  // NO_VERSION_PIN_DOCKER (info) - image without a tag or :latest
+  if (cmd === 'docker') {
+    const img = dockerImage(args);
+    if (img) {
+      const tagless = !img.includes('@') && (!img.includes(':') || /:latest$/i.test(img));
+      if (tagless) {
+        push('info', 'NO_VERSION_PIN_DOCKER', 'docker image "' + img + '" has no immutable tag', 'Pin the image to a specific tag or digest, not :latest.');
+      }
+    }
+  }
+}
+
+function auditMcpConfig(input) {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    return { error: 'input must be a JSON object', hint: 'Provide {"mcpServers":{...}} (Claude Desktop) or a single server object {"command":...}.' };
+  }
+
+  const findings = [];
+  let servers;
+
+  if (input.mcpServers && typeof input.mcpServers === 'object' && !Array.isArray(input.mcpServers)) {
+    servers = input.mcpServers;
+    for (const k of Object.keys(input)) {
+      if (!KNOWN_TOP_KEYS.has(k)) {
+        findings.push({ severity: 'info', code: 'UNKNOWN_TOP_FIELDS', server: '(top)', message: 'unrecognized top-level field "' + k + '"', hint: 'Check for a typo; the config root normally holds only "mcpServers".' });
+      }
+    }
+  } else if ('command' in input || 'url' in input || 'args' in input || 'env' in input || 'transport' in input) {
+    servers = { '(root)': input }; // single-server shape
+  } else {
+    return { error: 'no MCP servers found', hint: 'Expected {"mcpServers":{...}} or a server object with a "command" or "url" field.' };
+  }
+
+  const names = Object.keys(servers);
+  for (const name of names) checkServer(name, servers[name], findings);
+
+  let score = 100;
+  let errors = 0, warns = 0, infos = 0;
+  for (const f of findings) {
+    if (f.severity === 'error') { score -= 25; errors++; }
+    else if (f.severity === 'warn') { score -= 10; warns++; }
+    else { score -= 2; infos++; }
+  }
+  if (score < 0) score = 0;
+
+  return { score, findings, summary: { servers: names.length, errors, warns, infos } };
+}
+
+module.exports = { auditMcpConfig };