mcp-nervous-system 1.7.0 → 1.7.2

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. 17 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. 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
 
@@ -60,7 +60,7 @@ Protocol: MCP 2024-11-05 (Streamable HTTP + SSE)
 Authentication: None required
 ```
 
-## NEW in v1.6.0
+## NEW in v1.7.1
 
 **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.1772811377

@@ -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. 17 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.6.0
+
+**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

@@ -180,7 +180,7 @@ const MCP_VERSION = '2024-11-05';
 // Server info
 const SERVER_INFO = {
   name: 'nervous-system',
-  version: '1.6.0'
+  version: '1.7.1'
 };
 
 // ============================================================
@@ -189,7 +189,7 @@ const SERVER_INFO = {
 
 const FRAMEWORK = {
   name: 'The Nervous System',
-  version: '1.6.0',
+  version: '1.7.1',
   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.',
@@ -1921,7 +1921,6 @@ function runMCPAnalyzer(mode, outputPath) {
   const result = {
     timestamp: new Date().toISOString(),
     mode: mode || 'analyze',
-    project: {},
     recommended_tools: [],
     claude_md: null,
     config_suggestions: null
@@ -2028,7 +2027,9 @@ function runMCPAnalyzer(mode, outputPath) {
     characteristics.project_type = 'general';
   }
 
-  result.project = characteristics;
+  // Don't expose raw project internals - just use them for recommendations
+  result.project_type = characteristics.project_type;
+  result.has_config = characteristics.has_config;
 
   // Step 2: Recommend tools based on project type
   const recommendations = [];
@@ -2060,7 +2061,7 @@ function runMCPAnalyzer(mode, outputPath) {
     recommendations.push({
       tool: 'guardrail_rules',
       priority: 'high',
-      reason: 'You have ' + (characteristics.protected_count || 'multiple') + ' protected files. These rules enforce discipline.'
+      reason: 'Protected files detected. These rules enforce discipline around file edits.'
     });
   }
 
@@ -2073,7 +2074,7 @@ function runMCPAnalyzer(mode, outputPath) {
     recommendations.push({
       tool: 'security_audit',
       priority: 'high',
-      reason: 'Production system with ' + characteristics.file_count + ' files. Security audit catches exposed secrets and misconfigurations.'
+      reason: 'Production system detected. Security audit catches exposed secrets and misconfigurations.'
     });
     recommendations.push({
       tool: 'emergency_kill_switch',
@@ -2198,23 +2199,17 @@ function runMCPAnalyzer(mode, outputPath) {
     claudeMd += '- Kill switch is available for emergencies\n\n';
   }
 
-  result.claude_md = claudeMd;
+  // Only include CLAUDE.md content in write/reload mode, not analyze
+  if (mode === 'write' || mode === 'reload') {
+    result.claude_md_generated = true;
+  }
 
   // Step 4: Config suggestions (if no config exists)
   if (!characteristics.has_config) {
-    result.config_suggestions = {
-      message: 'No nervous-system.config.json found. Create one to enable full audit capabilities.',
-      suggested_config: {
-        project_root: projectRoot,
-        data_dir: path.join(projectRoot, 'data'),
-        logs_dir: path.join(projectRoot, 'logs'),
-        html_dir: characteristics.has_html_pages ? path.join(projectRoot, 'public') : null,
-        protected_files_list: path.join(projectRoot, 'PROTECTED_FILES.txt'),
-        config_file: path.join(projectRoot, 'system-config.json'),
-        pm2_managed: characteristics.has_pm2,
-        docs_to_audit: []
-      }
-    };
+    result.setup_needed = true;
+    result.setup_message = 'No nervous-system.config.json found. Run with mode=write to create one and generate a tailored CLAUDE.md for your project.';
+  } else {
+    result.setup_needed = false;
   }
 
   // Step 5: If mode is 'reload' or 'write', write the CLAUDE.md
@@ -2356,7 +2351,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.6.0', protocol: MCP_VERSION }));
+    res.end(JSON.stringify({ status: 'ok', service: 'nervous-system-mcp', version: '1.7.1', protocol: MCP_VERSION }));
     return;
   }
 
@@ -2473,7 +2468,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.6.0',
+      version: '1.7.1',
       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.0",
+  "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": {