mcp-nervous-system 1.5.0 → 1.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +2 -2
  2. package/README.md.bak.1772777593 +172 -0
  3. package/README.md.bak.1772792496 +172 -0
  4. package/README.md.bak.1772792812 +172 -0
  5. package/index.js +182 -11
  6. package/package.json +3 -3
  7. package/package.json.bak.1772792496 +42 -0
  8. package/package.json.bak.1772792812 +42 -0
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  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.
6
6
 
7
- Built by [Arthur Palyan](https://www.levelsofself.com) at Palyan Family AI System. 12 tools including configuration drift detection and emergency kill switch. Battle-tested on an 11-member AI family running 28 processes 24/7 on a single VPS. 58+ violations logged, 0 bypassed.
7
+ Built by [Arthur Palyan](https://www.levelsofself.com) at Palyan Family AI System. 16 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.
8
8
 
9
9
  ## The Problem
10
10
 
@@ -60,7 +60,7 @@ Protocol: MCP 2024-11-05 (Streamable HTTP + SSE)
60
60
  Authentication: None required
61
61
  ```
62
62
 
63
- ## NEW in v1.4.0
63
+ ## NEW in v1.5.1
64
64
 
65
65
  **drift_audit** (free tier)
66
66
  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.1772777593 ADDED
@@ -0,0 +1,172 @@
1
+ # The Nervous System
2
+
3
+ **LLM Behavioral Enforcement Framework**
4
+
5
+ 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.
6
+
7
+ Built by [Arthur Palyan](https://www.levelsofself.com) at Palyan Family AI System. 12 tools including configuration drift detection and emergency kill switch. Battle-tested on an 11-member AI family running 28 processes 24/7 on a single VPS. 58+ violations logged, 0 bypassed.
8
+
9
+ ## The Problem
10
+
11
+ When you give an LLM access to your file system, bash, and production infrastructure, it will eventually:
12
+
13
+ - Edit a file it shouldn't touch
14
+ - Lose context between sessions and start over
15
+ - Drift from the original objective during long tasks
16
+ - Fail silently when a session times out
17
+ - Make logic changes without asking
18
+ - Disappear into debug loops
19
+
20
+ The Nervous System solves all of these with rules enforced by external mechanisms the LLM cannot override.
21
+
22
+ ## Install
23
+
24
+ ### Claude Desktop
25
+
26
+ Add to your `claude_desktop_config.json`:
27
+
28
+ ```json
29
+ {
30
+ "mcpServers": {
31
+ "nervous-system": {
32
+ "command": "npx",
33
+ "args": ["-y", "mcp-nervous-system"]
34
+ }
35
+ }
36
+ }
37
+ ```
38
+
39
+ ### Claude Code
40
+
41
+ ```bash
42
+ claude mcp add nervous-system npx mcp-nervous-system
43
+ ```
44
+
45
+ ### Direct
46
+
47
+ ```bash
48
+ npx mcp-nervous-system
49
+ ```
50
+
51
+ Server starts on port 3475 with SSE, HTTP, and health endpoints.
52
+
53
+ ### Hosted (No Install)
54
+
55
+ The server is live and ready to use:
56
+
57
+ ```
58
+ URL: https://api.100levelup.com/mcp-ns/
59
+ Protocol: MCP 2024-11-05 (Streamable HTTP + SSE)
60
+ Authentication: None required
61
+ ```
62
+
63
+ ## NEW in v1.4.0
64
+
65
+ **drift_audit** (free tier)
66
+ 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.
67
+
68
+ **Positioning: Auto mode decides what Claude CAN do. The Nervous System governs HOW it behaves while doing it.**
69
+
70
+ ## The 7 Rules
71
+
72
+ | # | Rule | What It Prevents |
73
+ |---|------|-----------------|
74
+ | 1 | **Dispatch Don't Do** | Debug loops, rabbit holes. Tasks > 2 messages get dispatched. |
75
+ | 2 | **Untouchable** | File damage. Protected files mechanically blocked from editing. |
76
+ | 3 | **Write Progress** | Silent failures. Progress noted before each action. |
77
+ | 4 | **Step Back Every 4** | Goal drift. Forced reflection every 4 messages. |
78
+ | 5 | **Delegate and Return** | Invisible work. Background tasks reported immediately. |
79
+ | 6 | **Ask Before Touching** | Unauthorized changes. Logic changes need human approval. |
80
+ | 7 | **Hand Off** | Context loss. Written handoffs every 3-4 exchanges. |
81
+
82
+ ## MCP Tools (12)
83
+
84
+ | Tool | Description |
85
+ |------|------------|
86
+ | `get_framework` | Complete framework: all rules, permission protocol, enforcement patterns |
87
+ | `guardrail_rules` | The 7 core rules with triggers, enforcement, and failure modes |
88
+ | `preflight_check` | File protection system: shell script blocks edits to protected files |
89
+ | `session_handoff` | Context preservation: templates for handoff documents |
90
+ | `worklog` | Progress documentation pattern |
91
+ | `violation_logging` | Audit trail: timestamp, type, context for every violation |
92
+ | `step_back_check` | Forced reflection system |
93
+ | `get_nervous_system_info` | System overview and operational stats |
94
+ | `emergency_kill_switch` | Emergency shutdown of all PM2 processes. Requires kill switch secret. Logs to tamper-evident audit trail |
95
+ | `verify_audit_chain` | Walks the SHA-256 hash-chained audit log and verifies every entry. Returns chain integrity status |
96
+ | `dispatch_to_llm` | Spawns a background LLM agent to handle a task. Checks RAM, enforces max 2 concurrent dispatches |
97
+ | `drift_audit` | Configuration drift detection across roles, versions, files, processes, and website. Finds stale values everywhere. |
98
+
99
+ ## Kill Switch
100
+
101
+ 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.
102
+
103
+ - Requires authentication (kill switch secret)
104
+ - Logs to hash-chained audit trail
105
+ - Returns confirmation with affected process count
106
+
107
+ ## Tamper-Evident Audit Trail
108
+
109
+ 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.
110
+
111
+ - Use `verify_audit_chain` to walk the entire chain and verify integrity
112
+ - Returns: valid/invalid status, entry count, and break point if tampered
113
+ - 58+ violations logged, 0 bypassed, 0 chain breaks
114
+
115
+ ## Dispatch to LLM
116
+
117
+ 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.
118
+
119
+ - Checks available RAM (requires 500MB+)
120
+ - Enforces max 2 concurrent dispatches
121
+ - Returns PID and log file path for monitoring
122
+ - Every dispatched agent runs under the same nervous system guardrails
123
+
124
+ ## EU AI Act Compliance
125
+
126
+ The Nervous System provides practical compliance tools for the EU AI Act. See the full compliance page at:
127
+
128
+ https://api.100levelup.com/family/eu-ai-act.html
129
+
130
+ ## Resources (5)
131
+
132
+ - `nervous-system://framework` - The complete framework
133
+ - `nervous-system://quick-start` - Quick start guide
134
+ - `nervous-system://rules` - The 7 core rules
135
+ - `nervous-system://templates` - Templates for handoffs, worklogs, preflight
136
+ - `nervous-system://drift-audit` - Configuration drift detection
137
+
138
+ ## Production Stats
139
+
140
+ From the live Palyan Family AI System deployment (Feb 28 - Mar 5, 2026):
141
+
142
+ - **58+** violations caught
143
+ - **29** edits blocked by preflight
144
+ - **13** unique files protected
145
+ - **0** rules bypassed
146
+ - **28** processes monitored
147
+ - **7** days continuous operation
148
+
149
+ ## Live Demo
150
+
151
+ Try it yourself (no login required):
152
+
153
+ - **[Interactive Demo](https://api.100levelup.com/family/arthur.html?guest=1)** - Talk to a governed LLM and try to break the rules
154
+ - **[Audit Dashboard](https://api.100levelup.com/family/audit.html)** - See real violation history with timeline
155
+ - **[System Status](https://api.100levelup.com/family/status.html)** - Live health checks
156
+ - **[API Documentation](https://api.100levelup.com/family/api-docs.html)** - Full tool and resource reference
157
+ - **[Case Study](https://api.100levelup.com/family/case-study.html)** - Production deployment data
158
+ - **[Plain English Rules](https://api.100levelup.com/family/rules-plain.html)** - For non-technical stakeholders
159
+ - **[Incident Response](https://api.100levelup.com/family/incident-response.html)** - Detection, containment, resolution
160
+ - **[EU AI Act Compliance](https://api.100levelup.com/family/eu-ai-act.html)** - Practical EU AI Act compliance tools
161
+
162
+ ## Philosophy
163
+
164
+ > "LLMs can't reliably self-enforce promises. Guardrails work via preflight.sh, violation logs, and catching drift. Build enforcement systems, don't make promises."
165
+
166
+ If a guardrail can be violated by the thing it guards, it is not a guardrail. It is a suggestion.
167
+
168
+ 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.
169
+
170
+ ## License
171
+
172
+ MIT
package/README.md.bak.1772792496 ADDED
@@ -0,0 +1,172 @@
1
+ # The Nervous System
2
+
3
+ **LLM Behavioral Enforcement Framework**
4
+
5
+ 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.
6
+
7
+ Built by [Arthur Palyan](https://www.levelsofself.com) at Palyan Family AI System. 15 tools including configuration drift detection and emergency kill switch. Battle-tested on an 11-member AI family running 28 processes 24/7 on a single VPS. 58+ violations logged, 0 bypassed.
8
+
9
+ ## The Problem
10
+
11
+ When you give an LLM access to your file system, bash, and production infrastructure, it will eventually:
12
+
13
+ - Edit a file it shouldn't touch
14
+ - Lose context between sessions and start over
15
+ - Drift from the original objective during long tasks
16
+ - Fail silently when a session times out
17
+ - Make logic changes without asking
18
+ - Disappear into debug loops
19
+
20
+ The Nervous System solves all of these with rules enforced by external mechanisms the LLM cannot override.
21
+
22
+ ## Install
23
+
24
+ ### Claude Desktop
25
+
26
+ Add to your `claude_desktop_config.json`:
27
+
28
+ ```json
29
+ {
30
+ "mcpServers": {
31
+ "nervous-system": {
32
+ "command": "npx",
33
+ "args": ["-y", "mcp-nervous-system"]
34
+ }
35
+ }
36
+ }
37
+ ```
38
+
39
+ ### Claude Code
40
+
41
+ ```bash
42
+ claude mcp add nervous-system npx mcp-nervous-system
43
+ ```
44
+
45
+ ### Direct
46
+
47
+ ```bash
48
+ npx mcp-nervous-system
49
+ ```
50
+
51
+ Server starts on port 3475 with SSE, HTTP, and health endpoints.
52
+
53
+ ### Hosted (No Install)
54
+
55
+ The server is live and ready to use:
56
+
57
+ ```
58
+ URL: https://api.100levelup.com/mcp-ns/
59
+ Protocol: MCP 2024-11-05 (Streamable HTTP + SSE)
60
+ Authentication: None required
61
+ ```
62
+
63
+ ## NEW in v1.5.0
64
+
65
+ **drift_audit** (free tier)
66
+ 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.
67
+
68
+ **Positioning: Auto mode decides what Claude CAN do. The Nervous System governs HOW it behaves while doing it.**
69
+
70
+ ## The 7 Rules
71
+
72
+ | # | Rule | What It Prevents |
73
+ |---|------|-----------------|
74
+ | 1 | **Dispatch Don't Do** | Debug loops, rabbit holes. Tasks > 2 messages get dispatched. |
75
+ | 2 | **Untouchable** | File damage. Protected files mechanically blocked from editing. |
76
+ | 3 | **Write Progress** | Silent failures. Progress noted before each action. |
77
+ | 4 | **Step Back Every 4** | Goal drift. Forced reflection every 4 messages. |
78
+ | 5 | **Delegate and Return** | Invisible work. Background tasks reported immediately. |
79
+ | 6 | **Ask Before Touching** | Unauthorized changes. Logic changes need human approval. |
80
+ | 7 | **Hand Off** | Context loss. Written handoffs every 3-4 exchanges. |
81
+
82
+ ## MCP Tools (12)
83
+
84
+ | Tool | Description |
85
+ |------|------------|
86
+ | `get_framework` | Complete framework: all rules, permission protocol, enforcement patterns |
87
+ | `guardrail_rules` | The 7 core rules with triggers, enforcement, and failure modes |
88
+ | `preflight_check` | File protection system: shell script blocks edits to protected files |
89
+ | `session_handoff` | Context preservation: templates for handoff documents |
90
+ | `worklog` | Progress documentation pattern |
91
+ | `violation_logging` | Audit trail: timestamp, type, context for every violation |
92
+ | `step_back_check` | Forced reflection system |
93
+ | `get_nervous_system_info` | System overview and operational stats |
94
+ | `emergency_kill_switch` | Emergency shutdown of all PM2 processes. Requires kill switch secret. Logs to tamper-evident audit trail |
95
+ | `verify_audit_chain` | Walks the SHA-256 hash-chained audit log and verifies every entry. Returns chain integrity status |
96
+ | `dispatch_to_llm` | Spawns a background LLM agent to handle a task. Checks RAM, enforces max 2 concurrent dispatches |
97
+ | `drift_audit` | Configuration drift detection across roles, versions, files, processes, and website. Finds stale values everywhere. |
98
+
99
+ ## Kill Switch
100
+
101
+ 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.
102
+
103
+ - Requires authentication (kill switch secret)
104
+ - Logs to hash-chained audit trail
105
+ - Returns confirmation with affected process count
106
+
107
+ ## Tamper-Evident Audit Trail
108
+
109
+ 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.
110
+
111
+ - Use `verify_audit_chain` to walk the entire chain and verify integrity
112
+ - Returns: valid/invalid status, entry count, and break point if tampered
113
+ - 58+ violations logged, 0 bypassed, 0 chain breaks
114
+
115
+ ## Dispatch to LLM
116
+
117
+ 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.
118
+
119
+ - Checks available RAM (requires 500MB+)
120
+ - Enforces max 2 concurrent dispatches
121
+ - Returns PID and log file path for monitoring
122
+ - Every dispatched agent runs under the same nervous system guardrails
123
+
124
+ ## EU AI Act Compliance
125
+
126
+ The Nervous System provides practical compliance tools for the EU AI Act. See the full compliance page at:
127
+
128
+ https://api.100levelup.com/family/eu-ai-act.html
129
+
130
+ ## Resources (5)
131
+
132
+ - `nervous-system://framework` - The complete framework
133
+ - `nervous-system://quick-start` - Quick start guide
134
+ - `nervous-system://rules` - The 7 core rules
135
+ - `nervous-system://templates` - Templates for handoffs, worklogs, preflight
136
+ - `nervous-system://drift-audit` - Configuration drift detection
137
+
138
+ ## Production Stats
139
+
140
+ From the live Palyan Family AI System deployment (Feb 28 - Mar 5, 2026):
141
+
142
+ - **58+** violations caught
143
+ - **29** edits blocked by preflight
144
+ - **13** unique files protected
145
+ - **0** rules bypassed
146
+ - **28** processes monitored
147
+ - **7** days continuous operation
148
+
149
+ ## Live Demo
150
+
151
+ Try it yourself (no login required):
152
+
153
+ - **[Interactive Demo](https://api.100levelup.com/family/arthur.html?guest=1)** - Talk to a governed LLM and try to break the rules
154
+ - **[Audit Dashboard](https://api.100levelup.com/family/audit.html)** - See real violation history with timeline
155
+ - **[System Status](https://api.100levelup.com/family/status.html)** - Live health checks
156
+ - **[API Documentation](https://api.100levelup.com/family/api-docs.html)** - Full tool and resource reference
157
+ - **[Case Study](https://api.100levelup.com/family/case-study.html)** - Production deployment data
158
+ - **[Plain English Rules](https://api.100levelup.com/family/rules-plain.html)** - For non-technical stakeholders
159
+ - **[Incident Response](https://api.100levelup.com/family/incident-response.html)** - Detection, containment, resolution
160
+ - **[EU AI Act Compliance](https://api.100levelup.com/family/eu-ai-act.html)** - Practical EU AI Act compliance tools
161
+
162
+ ## Philosophy
163
+
164
+ > "LLMs can't reliably self-enforce promises. Guardrails work via preflight.sh, violation logs, and catching drift. Build enforcement systems, don't make promises."
165
+
166
+ If a guardrail can be violated by the thing it guards, it is not a guardrail. It is a suggestion.
167
+
168
+ 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.
169
+
170
+ ## License
171
+
172
+ MIT
package/README.md.bak.1772792812 ADDED
@@ -0,0 +1,172 @@
1
+ # The Nervous System
2
+
3
+ **LLM Behavioral Enforcement Framework**
4
+
5
+ 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.
6
+
7
+ Built by [Arthur Palyan](https://www.levelsofself.com) at Palyan Family AI System. 15 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.
8
+
9
+ ## The Problem
10
+
11
+ When you give an LLM access to your file system, bash, and production infrastructure, it will eventually:
12
+
13
+ - Edit a file it shouldn't touch
14
+ - Lose context between sessions and start over
15
+ - Drift from the original objective during long tasks
16
+ - Fail silently when a session times out
17
+ - Make logic changes without asking
18
+ - Disappear into debug loops
19
+
20
+ The Nervous System solves all of these with rules enforced by external mechanisms the LLM cannot override.
21
+
22
+ ## Install
23
+
24
+ ### Claude Desktop
25
+
26
+ Add to your `claude_desktop_config.json`:
27
+
28
+ ```json
29
+ {
30
+ "mcpServers": {
31
+ "nervous-system": {
32
+ "command": "npx",
33
+ "args": ["-y", "mcp-nervous-system"]
34
+ }
35
+ }
36
+ }
37
+ ```
38
+
39
+ ### Claude Code
40
+
41
+ ```bash
42
+ claude mcp add nervous-system npx mcp-nervous-system
43
+ ```
44
+
45
+ ### Direct
46
+
47
+ ```bash
48
+ npx mcp-nervous-system
49
+ ```
50
+
51
+ Server starts on port 3475 with SSE, HTTP, and health endpoints.
52
+
53
+ ### Hosted (No Install)
54
+
55
+ The server is live and ready to use:
56
+
57
+ ```
58
+ URL: https://api.100levelup.com/mcp-ns/
59
+ Protocol: MCP 2024-11-05 (Streamable HTTP + SSE)
60
+ Authentication: None required
61
+ ```
62
+
63
+ ## NEW in v1.5.0
64
+
65
+ **drift_audit** (free tier)
66
+ 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.
67
+
68
+ **Positioning: Auto mode decides what Claude CAN do. The Nervous System governs HOW it behaves while doing it.**
69
+
70
+ ## The 7 Rules
71
+
72
+ | # | Rule | What It Prevents |
73
+ |---|------|-----------------|
74
+ | 1 | **Dispatch Don't Do** | Debug loops, rabbit holes. Tasks > 2 messages get dispatched. |
75
+ | 2 | **Untouchable** | File damage. Protected files mechanically blocked from editing. |
76
+ | 3 | **Write Progress** | Silent failures. Progress noted before each action. |
77
+ | 4 | **Step Back Every 4** | Goal drift. Forced reflection every 4 messages. |
78
+ | 5 | **Delegate and Return** | Invisible work. Background tasks reported immediately. |
79
+ | 6 | **Ask Before Touching** | Unauthorized changes. Logic changes need human approval. |
80
+ | 7 | **Hand Off** | Context loss. Written handoffs every 3-4 exchanges. |
81
+
82
+ ## MCP Tools (12)
83
+
84
+ | Tool | Description |
85
+ |------|------------|
86
+ | `get_framework` | Complete framework: all rules, permission protocol, enforcement patterns |
87
+ | `guardrail_rules` | The 7 core rules with triggers, enforcement, and failure modes |
88
+ | `preflight_check` | File protection system: shell script blocks edits to protected files |
89
+ | `session_handoff` | Context preservation: templates for handoff documents |
90
+ | `worklog` | Progress documentation pattern |
91
+ | `violation_logging` | Audit trail: timestamp, type, context for every violation |
92
+ | `step_back_check` | Forced reflection system |
93
+ | `get_nervous_system_info` | System overview and operational stats |
94
+ | `emergency_kill_switch` | Emergency shutdown of all PM2 processes. Requires kill switch secret. Logs to tamper-evident audit trail |
95
+ | `verify_audit_chain` | Walks the SHA-256 hash-chained audit log and verifies every entry. Returns chain integrity status |
96
+ | `dispatch_to_llm` | Spawns a background LLM agent to handle a task. Checks RAM, enforces max 2 concurrent dispatches |
97
+ | `drift_audit` | Configuration drift detection across roles, versions, files, processes, and website. Finds stale values everywhere. |
98
+
99
+ ## Kill Switch
100
+
101
+ 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.
102
+
103
+ - Requires authentication (kill switch secret)
104
+ - Logs to hash-chained audit trail
105
+ - Returns confirmation with affected process count
106
+
107
+ ## Tamper-Evident Audit Trail
108
+
109
+ 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.
110
+
111
+ - Use `verify_audit_chain` to walk the entire chain and verify integrity
112
+ - Returns: valid/invalid status, entry count, and break point if tampered
113
+ - 58+ violations logged, 0 bypassed, 0 chain breaks
114
+
115
+ ## Dispatch to LLM
116
+
117
+ 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.
118
+
119
+ - Checks available RAM (requires 500MB+)
120
+ - Enforces max 2 concurrent dispatches
121
+ - Returns PID and log file path for monitoring
122
+ - Every dispatched agent runs under the same nervous system guardrails
123
+
124
+ ## EU AI Act Compliance
125
+
126
+ The Nervous System provides practical compliance tools for the EU AI Act. See the full compliance page at:
127
+
128
+ https://api.100levelup.com/family/eu-ai-act.html
129
+
130
+ ## Resources (5)
131
+
132
+ - `nervous-system://framework` - The complete framework
133
+ - `nervous-system://quick-start` - Quick start guide
134
+ - `nervous-system://rules` - The 7 core rules
135
+ - `nervous-system://templates` - Templates for handoffs, worklogs, preflight
136
+ - `nervous-system://drift-audit` - Configuration drift detection
137
+
138
+ ## Production Stats
139
+
140
+ From the live Palyan Family AI System deployment (Feb 28 - Mar 5, 2026):
141
+
142
+ - **58+** violations caught
143
+ - **29** edits blocked by preflight
144
+ - **13** unique files protected
145
+ - **0** rules bypassed
146
+ - **28** processes monitored
147
+ - **7** days continuous operation
148
+
149
+ ## Live Demo
150
+
151
+ Try it yourself (no login required):
152
+
153
+ - **[Interactive Demo](https://api.100levelup.com/family/arthur.html?guest=1)** - Talk to a governed LLM and try to break the rules
154
+ - **[Audit Dashboard](https://api.100levelup.com/family/audit.html)** - See real violation history with timeline
155
+ - **[System Status](https://api.100levelup.com/family/status.html)** - Live health checks
156
+ - **[API Documentation](https://api.100levelup.com/family/api-docs.html)** - Full tool and resource reference
157
+ - **[Case Study](https://api.100levelup.com/family/case-study.html)** - Production deployment data
158
+ - **[Plain English Rules](https://api.100levelup.com/family/rules-plain.html)** - For non-technical stakeholders
159
+ - **[Incident Response](https://api.100levelup.com/family/incident-response.html)** - Detection, containment, resolution
160
+ - **[EU AI Act Compliance](https://api.100levelup.com/family/eu-ai-act.html)** - Practical EU AI Act compliance tools
161
+
162
+ ## Philosophy
163
+
164
+ > "LLMs can't reliably self-enforce promises. Guardrails work via preflight.sh, violation logs, and catching drift. Build enforcement systems, don't make promises."
165
+
166
+ If a guardrail can be violated by the thing it guards, it is not a guardrail. It is a suggestion.
167
+
168
+ 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.
169
+
170
+ ## License
171
+
172
+ MIT
package/index.js CHANGED
@@ -129,7 +129,7 @@ const MCP_VERSION = '2024-11-05';
129
129
  // Server info
130
130
  const SERVER_INFO = {
131
131
  name: 'nervous-system',
132
- version: '1.5.0'
132
+ version: '1.5.1'
133
133
  };
134
134
 
135
135
  // ============================================================
@@ -138,7 +138,7 @@ const SERVER_INFO = {
138
138
 
139
139
  const FRAMEWORK = {
140
140
  name: 'The Nervous System',
141
- version: '1.5.0',
141
+ version: '1.5.1',
142
142
  author: 'Arthur Palyan',
143
143
  tagline: 'Anthropic built the brain. Arthur built the nervous system that keeps it from hurting itself.',
144
144
  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.',
@@ -475,7 +475,7 @@ const NERVOUS_SYSTEM_INFO = {
475
475
  ]
476
476
  },
477
477
  origin_story: {
478
- context: 'Arthur Palyan runs a startup with 12 AI family members, each with distinct roles. The entire operation runs on a $12/month VPS with a $300/month LLM subscription.',
478
+ 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.',
479
479
  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.',
480
480
  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.',
481
481
  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.',
@@ -507,7 +507,7 @@ const NERVOUS_SYSTEM_INFO = {
507
507
  reflection_trigger: 'Every 4 messages',
508
508
  processes_managed: '22+ autonomous PM2 processes',
509
509
  family_members: 12,
510
- monthly_cost: '$352/month total infrastructure',
510
+ monthly_cost: 'Under $300/month total infrastructure',
511
511
  uptime: '24/7 autonomous operation',
512
512
  deployment: 'Single VPS, single LLM subscription'
513
513
  }
@@ -637,6 +637,18 @@ const TOOLS = [
637
637
  annotations: { title: 'Session Close', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
638
638
  description: 'One-call session close. Runs drift_audit scope=full, then all 3 propagators. Returns combined results. The end-of-session button.',
639
639
  inputSchema: { type: 'object', properties: {} }
640
+ },
641
+ // NEW: Page Health
642
+ {
643
+ name: 'page_health',
644
+ annotations: { title: 'Page Health Check', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
645
+ description: 'Checks HTML pages in /root/family-home/ for broken links, broken fetches, missing mobile nav, placeholder text, missing images, stale links, missing OG tags, missing favicon, JS syntax issues, and empty sections. Catches what drift_audit does not - actual page functionality and UX issues.',
646
+ inputSchema: {
647
+ type: 'object',
648
+ properties: {
649
+ page: { type: 'string', description: "Specific page to check (e.g. 'gateway.html'), or 'all' for everything" }
650
+ }
651
+ }
640
652
  }
641
653
  ];
642
654
 
@@ -1216,15 +1228,11 @@ function runSecurityAudit() {
1216
1228
  // 1. Scan HTML files for hardcoded passwords/secrets
1217
1229
  const htmlDir = '/root/family-home/';
1218
1230
  const secretPatterns = [
1219
- /Liarzhek1\$/g,
1220
- /Levelsofself1\$/g,
1221
1231
  /\d{10}:AA[A-Za-z0-9_-]{30,}/g,
1222
1232
  /sk-ant-[a-zA-Z0-9_-]+/g,
1223
1233
  /npm_[A-Za-z0-9]{20,}/g,
1224
1234
  /ghp_[A-Za-z0-9]{20,}/g,
1225
1235
  /BOT_TOKEN\s*[:=]\s*['"][^'"]+['"]/gi,
1226
- /PAPA_FULL\s*[:=]\s*['"][^'"]+['"]/gi,
1227
- /PAPA_READ\s*[:=]\s*['"][^'"]+['"]/gi
1228
1236
  ];
1229
1237
  try {
1230
1238
  const htmlFiles = fs.readdirSync(htmlDir).filter(f => f.endsWith('.html'));
@@ -1376,6 +1384,165 @@ function runAutoPropagators() {
1376
1384
  };
1377
1385
  }
1378
1386
 
1387
+ // ============================================================
1388
+ // PAGE HEALTH ENGINE
1389
+ // ============================================================
1390
+
1391
+ function runPageHealth(page) {
1392
+ const FAMILY_HOME = '/root/family-home';
1393
+ const issues = [];
1394
+
1395
+ let htmlFiles;
1396
+ if (page && page !== 'all') {
1397
+ const target = page.endsWith('.html') ? page : page + '.html';
1398
+ const fullPath = `${FAMILY_HOME}/${target}`;
1399
+ if (!fs.existsSync(fullPath)) return { status: 'error', error: `File not found: ${target}` };
1400
+ htmlFiles = [target];
1401
+ } else {
1402
+ try {
1403
+ htmlFiles = fs.readdirSync(FAMILY_HOME).filter(f => f.endsWith('.html'));
1404
+ } catch (e) {
1405
+ return { status: 'error', error: `Cannot read ${FAMILY_HOME}: ${e.message}` };
1406
+ }
1407
+ }
1408
+
1409
+ for (const file of htmlFiles) {
1410
+ const filePath = `${FAMILY_HOME}/${file}`;
1411
+ let content;
1412
+ try { content = fs.readFileSync(filePath, 'utf8'); } catch (e) { continue; }
1413
+
1414
+ // 1. BROKEN LINKS - local href/src that don't exist
1415
+ const localRefs = [];
1416
+ const hrefMatches = content.matchAll(/(?:href|src)=["'](?!https?:\/\/|mailto:|tel:|#|javascript:|data:)([^"'#?]+)/gi);
1417
+ for (const m of hrefMatches) {
1418
+ const ref = m[1].trim();
1419
+ if (!ref || ref.startsWith('//') || ref.startsWith('{')) continue;
1420
+ localRefs.push(ref);
1421
+ }
1422
+ for (const ref of localRefs) {
1423
+ const resolved = ref.startsWith('/') ? ref : `${FAMILY_HOME}/${ref}`;
1424
+ if (!fs.existsSync(resolved)) {
1425
+ issues.push({ page: file, type: 'broken_link', detail: `Local reference "${ref}" - file not found` });
1426
+ }
1427
+ }
1428
+
1429
+ // 2. BROKEN FETCHES - check fetch() endpoints respond on localhost
1430
+ const fetchMatches = content.matchAll(/fetch\s*\(\s*['"`]([^'"`]+)['"`]/g);
1431
+ for (const m of fetchMatches) {
1432
+ const url = m[1];
1433
+ if (url.includes('${')) continue; // skip template literals with variables
1434
+ if (url.startsWith('http://localhost') || url.startsWith('http://127.0.0.1') || url.startsWith('/')) {
1435
+ let testUrl = url;
1436
+ if (url.startsWith('/')) {
1437
+ // Try to figure out port from context, default to common ports
1438
+ testUrl = `http://localhost:3000${url}`;
1439
+ }
1440
+ try {
1441
+ execSync(`curl -s -o /dev/null -w "%{http_code}" --max-time 2 "${testUrl}"`, { encoding: 'utf8', timeout: 3000 });
1442
+ } catch (e) {
1443
+ issues.push({ page: file, type: 'broken_fetch', detail: `fetch("${url}") - endpoint not responding` });
1444
+ }
1445
+ }
1446
+ }
1447
+
1448
+ // 3. MOBILE NAV - has nav-links but no hamburger/mobile menu
1449
+ const hasNavLinks = /class=["'][^"']*nav-links/i.test(content) || /<nav[\s>]/i.test(content);
1450
+ const hasHamburger = /hamburger|mobile-menu|menu-toggle|nav-toggle|burger/i.test(content) || /class=["'][^"']*toggle/i.test(content);
1451
+ if (hasNavLinks && !hasHamburger) {
1452
+ issues.push({ page: file, type: 'no_mobile_menu', detail: 'nav-links found but no hamburger toggle for mobile' });
1453
+ }
1454
+
1455
+ // 4. PLACEHOLDER TEXT - "--" as default in stat/value elements
1456
+ const placeholderMatches = content.matchAll(/id=["']([^"']+)["'][^>]*>\s*--\s*</g);
1457
+ for (const m of placeholderMatches) {
1458
+ issues.push({ page: file, type: 'placeholder_text', detail: `Element "${m[1]}" shows "--" (live data not loading)` });
1459
+ }
1460
+ // Also check spans/divs with class containing stat/value/count
1461
+ const statPlaceholders = content.matchAll(/class=["'][^"']*(?:stat|value|count|metric)[^"']*["'][^>]*>\s*--\s*</gi);
1462
+ for (const m of statPlaceholders) {
1463
+ issues.push({ page: file, type: 'placeholder_text', detail: 'Stat/value element shows "--" (live data not loading)' });
1464
+ }
1465
+
1466
+ // 5. MISSING IMAGES - img src referencing local files that don't exist
1467
+ const imgMatches = content.matchAll(/<img[^>]+src=["'](?!https?:\/\/|data:)([^"']+)["']/gi);
1468
+ for (const m of imgMatches) {
1469
+ const src = m[1].trim();
1470
+ if (!src || src.startsWith('{')) continue;
1471
+ const resolved = src.startsWith('/') ? src : `${FAMILY_HOME}/${src}`;
1472
+ if (!fs.existsSync(resolved)) {
1473
+ issues.push({ page: file, type: 'missing_image', detail: `Image "${src}" not found` });
1474
+ }
1475
+ }
1476
+
1477
+ // 6. STALE LINKS - external links to app stores, npm, github format check
1478
+ const extLinkMatches = content.matchAll(/href=["'](https?:\/\/[^"']+)["']/gi);
1479
+ for (const m of extLinkMatches) {
1480
+ const url = m[1];
1481
+ if (/play\.google\.com/.test(url) && !/play\.google\.com\/store\/apps\/details\?id=/.test(url)) {
1482
+ issues.push({ page: file, type: 'stale_link', detail: `Malformed Play Store link: ${url}` });
1483
+ }
1484
+ if (/apps\.apple\.com/.test(url) && !/apps\.apple\.com\/.*\/app\//.test(url)) {
1485
+ issues.push({ page: file, type: 'stale_link', detail: `Malformed App Store link: ${url}` });
1486
+ }
1487
+ if (/npmjs\.com/.test(url) && !/npmjs\.com\/package\//.test(url)) {
1488
+ issues.push({ page: file, type: 'stale_link', detail: `Malformed npm link: ${url}` });
1489
+ }
1490
+ if (/github\.com/.test(url) && /github\.com\/?["']/.test(url)) {
1491
+ issues.push({ page: file, type: 'stale_link', detail: `Generic GitHub link (no repo): ${url}` });
1492
+ }
1493
+ }
1494
+
1495
+ // 7. MISSING OG TAGS
1496
+ const ogTags = ['og:title', 'og:description', 'og:image'];
1497
+ for (const tag of ogTags) {
1498
+ if (!content.includes(`property="${tag}"`) && !content.includes(`property='${tag}'`)) {
1499
+ issues.push({ page: file, type: 'missing_og_tag', detail: `Missing ${tag} meta tag` });
1500
+ }
1501
+ }
1502
+
1503
+ // 8. MISSING FAVICON
1504
+ if (!/rel=["'](?:icon|shortcut icon)["']/i.test(content)) {
1505
+ issues.push({ page: file, type: 'missing_favicon', detail: 'No favicon link tag found' });
1506
+ }
1507
+
1508
+ // 9. CONSOLE ERRORS - JS syntax issues (unclosed tags, mismatched brackets)
1509
+ const scriptBlocks = content.matchAll(/<script[^>]*>([\s\S]*?)<\/script>/gi);
1510
+ for (const m of scriptBlocks) {
1511
+ const js = m[1].trim();
1512
+ if (!js) continue;
1513
+ // Check bracket balance
1514
+ let parens = 0, braces = 0, brackets = 0;
1515
+ for (const ch of js) {
1516
+ if (ch === '(') parens++;
1517
+ else if (ch === ')') parens--;
1518
+ else if (ch === '{') braces++;
1519
+ else if (ch === '}') braces--;
1520
+ else if (ch === '[') brackets++;
1521
+ else if (ch === ']') brackets--;
1522
+ }
1523
+ if (parens !== 0) issues.push({ page: file, type: 'js_syntax', detail: `Mismatched parentheses in script block (balance: ${parens})` });
1524
+ if (braces !== 0) issues.push({ page: file, type: 'js_syntax', detail: `Mismatched braces in script block (balance: ${braces})` });
1525
+ if (brackets !== 0) issues.push({ page: file, type: 'js_syntax', detail: `Mismatched brackets in script block (balance: ${brackets})` });
1526
+ }
1527
+
1528
+ // 10. EMPTY SECTIONS
1529
+ const sectionMatches = content.matchAll(/<section[^>]*>([\s\S]*?)<\/section>/gi);
1530
+ for (const m of sectionMatches) {
1531
+ const inner = m[1].replace(/<!--[\s\S]*?-->/g, '').replace(/<[^>]+>/g, '').trim();
1532
+ if (!inner) {
1533
+ issues.push({ page: file, type: 'empty_section', detail: 'Section tag with no visible content' });
1534
+ }
1535
+ }
1536
+ }
1537
+
1538
+ return {
1539
+ status: issues.length === 0 ? 'healthy' : 'issues_found',
1540
+ pages_checked: htmlFiles.length,
1541
+ issue_count: issues.length,
1542
+ issues
1543
+ };
1544
+ }
1545
+
1379
1546
  // ============================================================
1380
1547
  // Handle tool calls
1381
1548
  // ============================================================
@@ -1497,6 +1664,10 @@ function handleToolCall(name, args) {
1497
1664
  };
1498
1665
  }
1499
1666
 
1667
+ case 'page_health': {
1668
+ return runPageHealth(args.page || 'all');
1669
+ }
1670
+
1500
1671
  default:
1501
1672
  return { error: 'Unknown tool' };
1502
1673
  }
@@ -1735,7 +1906,7 @@ const server = http.createServer((req, res) => {
1735
1906
  res.writeHead(200, { 'Content-Type': 'application/json' });
1736
1907
  res.end(JSON.stringify({
1737
1908
  name: 'The Nervous System MCP Server',
1738
- version: '1.5.0',
1909
+ version: '1.5.1',
1739
1910
  protocol: MCP_VERSION,
1740
1911
  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.',
1741
1912
  endpoints: {
@@ -1757,8 +1928,8 @@ const server = http.createServer((req, res) => {
1757
1928
  migrateExistingViolations();
1758
1929
 
1759
1930
  server.listen(PORT, '127.0.0.1', () => {
1760
- console.error(`[MCP Server] Nervous System v1.5.0 running on port ${PORT}`);
1931
+ console.error(`[MCP Server] Nervous System v1.5.1 running on port ${PORT}`);
1761
1932
  console.error(`[MCP Server] SSE: /sse | HTTP: /mcp | Health: /health | Kill: POST /kill | Audit: GET /audit/verify | Dispatches: GET /dispatches`);
1762
1933
  console.error(`[MCP Server] Protocol: ${MCP_VERSION}`);
1763
- console.error(`[MCP Server] Tools: ${TOOLS.length} (including kill switch, audit chain, dispatch, drift audit)`);
1934
+ console.error(`[MCP Server] Tools: ${TOOLS.length} (including kill switch, audit chain, dispatch, drift audit, page health)`);
1764
1935
  });
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "mcp-nervous-system",
3
- "version": "1.5.0",
4
- "description": "The Nervous System - LLM Behavioral Enforcement Framework. 7 mechanically enforced rules, 15 tools including kill switch, audit chain, dispatch, drift audit, security audit, and session close. MCP server for Claude Desktop, Claude Code, and any MCP-compatible client.",
3
+ "version": "1.5.2",
4
+ "description": "The Nervous System - LLM Behavioral Enforcement Framework. 7 mechanically enforced rules, 16 tools including kill switch, audit chain, dispatch, drift audit, security audit, page health, and session close. MCP server for Claude Desktop, Claude Code, and any MCP-compatible client.",
5
5
  "main": "server.js",
6
6
  "bin": {
7
7
  "mcp-nervous-system": "./stdio.js"
@@ -39,4 +39,4 @@
39
39
  "dependencies": {
40
40
  "@modelcontextprotocol/sdk": "^1.0.0"
41
41
  }
42
- }
42
+ }
package/package.json.bak.1772792496 ADDED
@@ -0,0 +1,42 @@
1
+ {
2
+ "name": "mcp-nervous-system",
3
+ "version": "1.5.1",
4
+ "description": "The Nervous System - LLM Behavioral Enforcement Framework. 7 mechanically enforced rules, 16 tools including kill switch, audit chain, dispatch, drift audit, security audit, page health, and session close. MCP server for Claude Desktop, Claude Code, and any MCP-compatible client.",
5
+ "main": "server.js",
6
+ "bin": {
7
+ "mcp-nervous-system": "./stdio.js"
8
+ },
9
+ "scripts": {
10
+ "start": "node server.js"
11
+ },
12
+ "keywords": [
13
+ "mcp",
14
+ "model-context-protocol",
15
+ "llm",
16
+ "ai-safety",
17
+ "ai-governance",
18
+ "behavioral-enforcement",
19
+ "guardrails",
20
+ "claude",
21
+ "anthropic",
22
+ "nervous-system",
23
+ "kill-switch",
24
+ "audit-trail"
25
+ ],
26
+ "author": "Arthur Palyan <palyanai@gmail.com>",
27
+ "license": "MIT",
28
+ "repository": {
29
+ "type": "git",
30
+ "url": "https://github.com/levelsofself/mcp-nervous-system"
31
+ },
32
+ "homepage": "https://api.100levelup.com/family/gateway.html",
33
+ "bugs": {
34
+ "url": "https://github.com/levelsofself/mcp-nervous-system/issues"
35
+ },
36
+ "engines": {
37
+ "node": ">=18.0.0"
38
+ },
39
+ "dependencies": {
40
+ "@modelcontextprotocol/sdk": "^1.0.0"
41
+ }
42
+ }
package/package.json.bak.1772792812 ADDED
@@ -0,0 +1,42 @@
1
+ {
2
+ "name": "mcp-nervous-system",
3
+ "version": "1.5.0",
4
+ "description": "The Nervous System - LLM Behavioral Enforcement Framework. 7 mechanically enforced rules, 16 tools including kill switch, audit chain, dispatch, drift audit, security audit, page health, and session close. MCP server for Claude Desktop, Claude Code, and any MCP-compatible client.",
5
+ "main": "server.js",
6
+ "bin": {
7
+ "mcp-nervous-system": "./stdio.js"
8
+ },
9
+ "scripts": {
10
+ "start": "node server.js"
11
+ },
12
+ "keywords": [
13
+ "mcp",
14
+ "model-context-protocol",
15
+ "llm",
16
+ "ai-safety",
17
+ "ai-governance",
18
+ "behavioral-enforcement",
19
+ "guardrails",
20
+ "claude",
21
+ "anthropic",
22
+ "nervous-system",
23
+ "kill-switch",
24
+ "audit-trail"
25
+ ],
26
+ "author": "Arthur Palyan <palyanai@gmail.com>",
27
+ "license": "MIT",
28
+ "repository": {
29
+ "type": "git",
30
+ "url": "https://github.com/levelsofself/mcp-nervous-system"
31
+ },
32
+ "homepage": "https://api.100levelup.com/family/gateway.html",
33
+ "bugs": {
34
+ "url": "https://github.com/levelsofself/mcp-nervous-system/issues"
35
+ },
36
+ "engines": {
37
+ "node": ">=18.0.0"
38
+ },
39
+ "dependencies": {
40
+ "@modelcontextprotocol/sdk": "^1.0.0"
41
+ }
42
+ }