mcp-nervous-system 1.7.3 → 1.7.4

package/README.md

@@ -4,7 +4,7 @@
 
 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. 18 tools including configuration drift detection and emergency kill switch. Battle-tested on an 11-member AI family running 30 processes 24/7 on a single VPS. 58+ violations logged, 0 bypassed.
+Built by [Arthur Palyan](https://www.levelsofself.com) at Palyan Family AI System. 19 tools including configuration drift detection and emergency kill switch. Battle-tested on an 11-member AI family running 30 processes 24/7 on a single VPS. 58+ violations logged, 0 bypassed.
 
 ## The Problem
 
@@ -60,7 +60,7 @@ Protocol: MCP 2024-11-05 (Streamable HTTP + SSE)
 Authentication: None required
 ```
 
-## NEW in v1.7.2
+## NEW in v1.7.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.

package/README.md.bak.1772814975

@@ -0,0 +1,172 @@
+# The Nervous System
+
+**LLM Behavioral Enforcement Framework**
+
+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. 18 tools including configuration drift detection and emergency kill switch. Battle-tested on an 11-member AI family running 30 processes 24/7 on a single VPS. 58+ violations logged, 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.7.2
+
+**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 (12)
+
+| 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
+- 58+ violations logged, 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
+
+## Resources (5)
+
+- `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
+
+## Production Stats
+
+From the live Palyan Family AI System deployment (Feb 28 - Mar 5, 2026):
+
+- **58+** violations caught
+- **29** edits blocked by preflight
+- **13** unique files protected
+- **0** rules bypassed
+- **28** processes monitored
+- **7** 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
+
+## 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

package/index.js

@@ -151,7 +151,7 @@ function getFreeMB() {
   } catch (e) { return 0; }
 }
 
-function dispatchToLLM(task, maxTurns) {
+function dispatchToLLM(task, maxTurns, permissions) {
   cleanupDispatches();
   const active = activeDispatches.filter(d => d.status === 'active');
   if (active.length >= MAX_CONCURRENT_DISPATCHES)
@@ -161,6 +161,18 @@ function dispatchToLLM(task, maxTurns) {
   const ts = Date.now();
   const logFile = projectPath('logs_dir') ? `${projectPath('logs_dir')}/dispatch-${ts}.log` : path.join(os.homedir(), '.nervous-system', `dispatch-${ts}.log`);
   const turns = maxTurns || 15;
+  // Write task-level permissions if provided
+  if (permissions && Array.isArray(permissions) && permissions.length > 0) {
+    try {
+      const permData = {
+        permissions: permissions.map(function(fp) {
+          return { file: fp, reason: 'Granted via dispatch_to_llm', granted_at: Date.now() / 1000 };
+        })
+      };
+      fs.writeFileSync('/root/family-data/task-permissions.json', JSON.stringify(permData, null, 2));
+    } catch (e) {}
+  }
+
   try {
     const escaped = task.replace(/"/g, '\\"');
     const child = spawn('bash', ['-c',
@@ -180,7 +192,7 @@ const MCP_VERSION = '2024-11-05';
 // Server info
 const SERVER_INFO = {
   name: 'nervous-system',
-  version: '1.7.2'
+  version: '1.7.4'
 };
 
 // ============================================================
@@ -189,7 +201,7 @@ const SERVER_INFO = {
 
 const FRAMEWORK = {
   name: 'The Nervous System',
-  version: '1.7.2',
+  version: '1.7.4',
   author: 'Arthur Palyan',
   tagline: 'Anthropic built the brain. Arthur built the nervous system that keeps it from hurting itself.',
   problem: 'LLMs lose context between sessions, loop on problems instead of dispatching, silently fail without progress notes, edit protected files, drift from the real problem, and solve instead of asking.',
@@ -647,7 +659,8 @@ const TOOLS = [
       type: 'object',
       properties: {
         task: { type: 'string', description: 'Task description for the background agent.' },
-        max_turns: { type: 'number', description: 'Max turns for the agent. Default: 15.' }
+        max_turns: { type: 'number', description: 'Max turns for the agent. Default: 15.' },
+        permissions: { type: 'array', items: { type: 'string' }, description: 'File paths the agent is allowed to edit (bypasses UNTOUCHABLE for these files). Expires after 24h.' }
       },
       required: ['task']
     }
@@ -1889,7 +1902,7 @@ function handleToolCall(name, args) {
     }
 
     case 'dispatch_to_llm': {
-      return dispatchToLLM(args.task, args.max_turns);
+      return dispatchToLLM(args.task, args.max_turns, args.permissions);
     }
 
     case 'drift_audit': {
@@ -1994,24 +2007,6 @@ function runSelfCheck() {
     });
   } catch (e) {}
 
-  // 3. CHECK: Do our tools expose internal project details?
-  // The mcp_analyzer should not return raw file counts, paths, or structure
-  try {
-    const source = fs.readFileSync(__filename, 'utf8');
-    if (source.includes('result.project = characteristics') || 
-        source.includes('characteristics.file_count') && source.includes('reason:') && !source.includes('// internal only')) {
-      // Check if file counts leak into user-visible output
-      var analyzerSection = source.substring(source.indexOf('runMCPAnalyzer'));
-      if (analyzerSection.includes("characteristics.file_count + '")) {
-        findings.push({
-          type: 'info_leakage',
-          severity: 'medium',
-          message: 'mcp_analyzer exposes raw project scan data (file counts, paths) in its response',
-          fix: 'Return only recommendations and offer to apply them, not raw scan details'
-        });
-      }
-    }
-  } catch (e) {}
 
   // 4. CHECK: Are there hardcoded /root/ paths in code that ships to clients?
   try {
@@ -2515,7 +2510,7 @@ const server = http.createServer((req, res) => {
   // Health check
   if (req.method === 'GET' && url.pathname === '/health') {
     res.writeHead(200, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ status: 'ok', service: 'nervous-system-mcp', version: '1.7.2', protocol: MCP_VERSION }));
+    res.end(JSON.stringify({ status: 'ok', service: 'nervous-system-mcp', version: '1.7.4', protocol: MCP_VERSION }));
     return;
   }
 
@@ -2632,7 +2627,7 @@ const server = http.createServer((req, res) => {
     res.writeHead(200, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({
       name: 'The Nervous System MCP Server',
-      version: '1.7.2',
+      version: '1.7.4',
       protocol: MCP_VERSION,
       description: 'LLM behavioral enforcement framework. 7 core rules, preflight checks, session handoffs, worklogs, violation logging, kill switch, hash-chained audit, and forced reflection cycles. Built by Arthur Palyan.',
       endpoints: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-nervous-system",
-  "version": "1.7.3",
+  "version": "1.7.4",
   "description": "The Nervous System - LLM Behavioral Enforcement Framework. 7 mechanically enforced rules, 17 tools including kill switch, audit chain, dispatch, drift audit, security audit, page health, pre-publish audit, and session close. MCP server for Claude Desktop, Claude Code, and any MCP-compatible client.",
   "main": "server.js",
   "bin": {

package/package.json.bak.1772814645

@@ -0,0 +1,42 @@
+{
+  "name": "mcp-nervous-system",
+  "version": "1.7.3",
+  "description": "The Nervous System - LLM Behavioral Enforcement Framework. 7 mechanically enforced rules, 17 tools including kill switch, audit chain, dispatch, drift audit, security audit, page health, pre-publish audit, and session close. MCP server for Claude Desktop, Claude Code, and any MCP-compatible client.",
+  "main": "server.js",
+  "bin": {
+    "mcp-nervous-system": "./stdio.js"
+  },
+  "scripts": {
+    "start": "node server.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "llm",
+    "ai-safety",
+    "ai-governance",
+    "behavioral-enforcement",
+    "guardrails",
+    "claude",
+    "anthropic",
+    "nervous-system",
+    "kill-switch",
+    "audit-trail"
+  ],
+  "author": "Arthur Palyan <palyanai@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/levelsofself/mcp-nervous-system"
+  },
+  "homepage": "https://api.100levelup.com/family/gateway.html",
+  "bugs": {
+    "url": "https://github.com/levelsofself/mcp-nervous-system/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/package.json.bak.1772814975

@@ -0,0 +1,42 @@
+{
+  "name": "mcp-nervous-system",
+  "version": "1.7.2",
+  "description": "The Nervous System - LLM Behavioral Enforcement Framework. 7 mechanically enforced rules, 17 tools including kill switch, audit chain, dispatch, drift audit, security audit, page health, pre-publish audit, and session close. MCP server for Claude Desktop, Claude Code, and any MCP-compatible client.",
+  "main": "server.js",
+  "bin": {
+    "mcp-nervous-system": "./stdio.js"
+  },
+  "scripts": {
+    "start": "node server.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "llm",
+    "ai-safety",
+    "ai-governance",
+    "behavioral-enforcement",
+    "guardrails",
+    "claude",
+    "anthropic",
+    "nervous-system",
+    "kill-switch",
+    "audit-trail"
+  ],
+  "author": "Arthur Palyan <palyanai@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/levelsofself/mcp-nervous-system"
+  },
+  "homepage": "https://api.100levelup.com/family/gateway.html",
+  "bugs": {
+    "url": "https://github.com/levelsofself/mcp-nervous-system/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}