@hyperfixi/mcp-server 2.7.2 → 2.9.0

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 (5) hide show
  1. package/CHANGELOG.md +156 -0
  2. package/README.md +71 -16
  3. package/dist/{esm-YPGJSQ36.js → esm-7SV6EOOG.js} +312 -289
  4. package/dist/index.js +151 -18
  5. package/package.json +40 -39
package/CHANGELOG.md ADDED
@@ -0,0 +1,156 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@hyperfixi/mcp-server` will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ### Fixed
11
+
12
+ - **Dispatch:** `execute_lse`, `validate_lse`, and `translate_lse` were advertised
13
+ in `ListTools` and implemented in `handleLsePipelineTool`, but the `CallTool`
14
+ router only forwarded two of the five LSE-pipeline tools — the three LSE 2.0
15
+ tools returned `Unknown tool` when called. All five now route.
16
+ - **Server version:** the MCP `serverInfo.version` was hardcoded to `1.0.0` for
17
+ the entire 2.x line; it now reads from `package.json`, so it can't drift on
18
+ release bumps.
19
+
20
+ ### Changed
21
+
22
+ - README refreshed to match the implementation: tool count 80 → **107**,
23
+ resources 5 → **9**, prompts 3 → **9**, domains 8 → **9** (adds `learn`),
24
+ corrected per-domain language tiers, and documented previously-omitted tool
25
+ families (debug, inventory, training-data, feedback, LSE pipeline/correction,
26
+ and the three additional IR/envelope tools).
27
+
28
+ ## [2.7.2] - 2026-07-08
29
+
30
+ Consolidated summary of the 2.x line (2.0.0 shipped 2026-02-11). Patch releases
31
+ tracked the monorepo-wide version; the highlights relevant to this package:
32
+
33
+ ### Added
34
+
35
+ - **GRAIL workflow tools (5)** — `grail_check` / `grail_plan` / `grail_run` /
36
+ `grail_info` / `grail_list` for Claude-native workflow orchestration.
37
+ - **LSE round-trip pipeline** — `lse_from_hyperscript`, `lse_to_hyperscript`,
38
+ plus the LSE 2.0 LLM-native tools `execute_lse` / `validate_lse` /
39
+ `translate_lse` (#624).
40
+ - **`learn` domain** — 9th domain DSL (language-learning sentence patterns),
41
+ bringing generated domain tools to 36.
42
+ - **Cross-domain dispatch** — `detect_domain`, `compile_auto`, `parse_composite`,
43
+ `compile_composite`.
44
+ - **AI-assisted debugging** (`debug_*`), **template inventory**
45
+ (`scan_inventory` / `query_inventory`), and **training-data** / **feedback-loop**
46
+ tools.
47
+ - IR/envelope tools `validate_protocol`, `to_envelope`, `from_envelope`.
48
+
49
+ ### Changed
50
+
51
+ - Domain language coverage widened to the 11-language "bridge" set for
52
+ sql/jsx/todo/llm/flow/voice (bdd/behaviorspec remain 8, learn is 10) via the
53
+ bridge arc (#615).
54
+ - Domain registration extracted to the shared `@lokascript/domain-config`
55
+ package; `domain-registry-setup.ts` is now a re-export shim.
56
+ - Package scope settled as `@hyperfixi/mcp-server` (engine packages publish under
57
+ `@hyperfixi/*`, multilingual packages under `@lokascript/*`).
58
+
59
+ Tool count grew from 22 (1.0.0) to **107** across this line.
60
+
61
+ ## [1.0.0] - 2025-01-19
62
+
63
+ ### Added
64
+
65
+ - Model Context Protocol server for LLM integration
66
+ - 22 tools for hyperscript development assistance
67
+ - 5 resources for documentation and examples
68
+ - Full multilingual support (23 languages)
69
+ - LSP-compatible features (diagnostics, completions, hover info)
70
+ - Code analysis and complexity metrics
71
+ - Pattern database search and lookup
72
+ - Semantic parsing and translation
73
+ - Schema validation for command designs
74
+ - Language profile management
75
+ - Expression documentation
76
+ - Command documentation with usage examples
77
+ - Keyword translation lookup across languages
78
+ - Auto-fix suggestions for common errors
79
+ - Best practices recommendations
80
+ - Natural language intent recognition
81
+
82
+ ### Tools Provided
83
+
84
+ 1. `analyze_complexity` - Calculate cyclomatic, cognitive, Halstead metrics
85
+ 2. `analyze_metrics` - Comprehensive code quality analysis
86
+ 3. `explain_code` - Natural language explanations (beginner/intermediate/expert)
87
+ 4. `recognize_intent` - Understand code purpose and classify patterns
88
+ 5. `get_examples` - Few-shot learning examples for tasks
89
+ 6. `search_patterns` - Pattern database queries
90
+ 7. `translate_hyperscript` - Between-language translation
91
+ 8. `get_pattern_stats` - Database statistics
92
+ 9. `validate_hyperscript` - Syntax validation
93
+ 10. `validate_schema` - Command schema validation
94
+ 11. `suggest_command` - Best command recommendations
95
+ 12. `get_bundle_config` - vite-plugin configuration
96
+ 13. `parse_multilingual` - Parse any supported language
97
+ 14. `translate_to_english` - Essential for LLM understanding
98
+ 15. `explain_in_language` - Detailed explanations in target language
99
+ 16. `get_code_fixes` - Auto-fix suggestions
100
+ 17. `get_diagnostics` - LSP-compatible diagnostics
101
+ 18. `get_completions` - Context-aware code completions
102
+ 19. `get_hover_info` - Hover documentation
103
+ 20. `get_document_symbols` - Extract symbols for outline view
104
+ 21. `get_command_docs` - Command documentation
105
+ 22. `get_expression_docs` - Expression documentation
106
+
107
+ ### Resources Provided
108
+
109
+ 1. Command registry - All available commands
110
+ 2. Expression types - All expression types
111
+ 3. Language elements - Searchable language features
112
+ 4. Language profiles - Complete grammar rules
113
+ 5. Supported languages - Metadata for 23 languages
114
+
115
+ ### Usage
116
+
117
+ ```bash
118
+ # Start server
119
+ npx @lokascript/mcp-server
120
+
121
+ # Configure in Claude Desktop
122
+ {
123
+ "mcpServers": {
124
+ "lokascript": {
125
+ "command": "npx",
126
+ "args": ["@lokascript/mcp-server"]
127
+ }
128
+ }
129
+ }
130
+ ```
131
+
132
+ ### Features
133
+
134
+ - Fully typed with TypeScript
135
+ - Comprehensive error handling
136
+ - Detailed logging for debugging
137
+ - LaunchAgent support for macOS
138
+ - Works with Claude Desktop, VSCode, and other MCP clients
139
+
140
+ ### Performance
141
+
142
+ - Fast response times (< 100ms for most operations)
143
+ - In-memory pattern database for quick lookup
144
+ - Efficient semantic parsing with caching
145
+
146
+ ### Compatibility
147
+
148
+ - MCP SDK 1.25+
149
+ - Node.js 18+
150
+ - Works with all MCP-compatible clients
151
+
152
+ ### Notes
153
+
154
+ - This is the first stable 1.0 release
155
+ - API is stable and production-ready
156
+ - Used extensively in LokaScript development workflow
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @hyperfixi/mcp-server
2
2
 
3
- MCP (Model Context Protocol) server for hyperscript and multilingual DSL development. Provides **80 tools**, 5 resources, and 3 prompts across 11 categories: validation, compilation, analysis, patterns, LSP bridge, language profiles, code generation, route extraction, 8 domain DSLs, IR conversion, and MCP sampling.
3
+ MCP (Model Context Protocol) server for hyperscript and multilingual DSL development. Provides **107 tools**, **9 resources**, and **9 prompts** spanning: GRAIL workflow orchestration, validation, compilation, analysis, patterns, LSP bridge, language profiles, code generation, route extraction, 9 domain DSLs, IR conversion, cross-domain dispatch, MCP sampling, AI-assisted debugging, template inventory, and the LSE round-trip pipeline.
4
4
 
5
5
  ## Installation
6
6
 
@@ -59,7 +59,9 @@ Or if installed globally:
59
59
 
60
60
  See **[GRAIL.md](GRAIL.md)** for full documentation, schema reference, and examples.
61
61
 
62
- ## Available Tools (80)
62
+ ## Available Tools
63
+
64
+ The **102** tools below, plus the **5** GRAIL tools above, total **107**.
63
65
 
64
66
  ### Validation & Semantic Tools (8)
65
67
 
@@ -131,12 +133,15 @@ See **[GRAIL.md](GRAIL.md)** for full documentation, schema reference, and examp
131
133
  | `get_role_markers` | Role markers (destination, source, patient, etc.) |
132
134
  | `compare_language_profiles` | Find translation gaps between languages |
133
135
 
134
- ### IR Conversion (2)
136
+ ### IR Conversion (5)
135
137
 
136
138
  | Tool | Description |
137
139
  | ------------------- | ---------------------------------------------------- |
138
140
  | `convert_format` | Convert between explicit bracket syntax and LLM JSON |
139
141
  | `validate_explicit` | Validate bracket syntax without compilation (fast) |
142
+ | `validate_protocol` | Validate protocol JSON against the LSE 2.0 schema |
143
+ | `to_envelope` | Wrap a node/protocol in a transport envelope |
144
+ | `from_envelope` | Unwrap an envelope back to a node/protocol |
140
145
 
141
146
  ### Route Extraction (2)
142
147
 
@@ -164,20 +169,70 @@ See **[GRAIL.md](GRAIL.md)** for full documentation, schema reference, and examp
164
169
  | `translate_content` | Translate text between natural languages |
165
170
  | `execute_llm` | Execute LLM command in natural language (8 languages) |
166
171
 
167
- ### Domain DSL Tools (32)
172
+ ### AI-Assisted Debugging (4)
173
+
174
+ | Tool | Description |
175
+ | ------------------------ | --------------------------------------------------------------------- |
176
+ | `debug_analyze_snapshot` | Explain the current paused debugger state and predict the next step |
177
+ | `debug_explain_handler` | Break down an event handler step-by-step; flag issues and breakpoints |
178
+ | `debug_suggest_fix` | Analyze a snapshot where something went wrong; suggest causes + fixes |
179
+ | `debug_trace_variable` | Trace how a variable changed across an execution-history snapshot set |
180
+
181
+ ### Template Inventory (2)
182
+
183
+ | Tool | Description |
184
+ | ----------------- | --------------------------------------------------------------------- |
185
+ | `scan_inventory` | Scan a directory for hyperscript (`_=`), htmx (`hx-*`), fixi (`fx-*`) |
186
+ | `query_inventory` | Search and filter within previously scanned inventory results |
187
+
188
+ ### Training Data (1)
189
+
190
+ | Tool | Description |
191
+ | ------------------------ | -------------------------------------------------------------- |
192
+ | `generate_training_data` | Synthesize (natural language, LSE) pairs from schemas as JSONL |
193
+
194
+ ### Feedback Loop (2)
195
+
196
+ | Tool | Description |
197
+ | --------------------------- | ----------------------------------------------------------------- |
198
+ | `lse_validate_and_feedback` | Validate LSE and return machine-actionable correction hints |
199
+ | `lse_pattern_stats` | Pattern hit-rate stats: success by command/language, top failures |
200
+
201
+ ### LSE Pipeline (5)
202
+
203
+ | Tool | Description |
204
+ | ---------------------- | --------------------------------------------------------------- |
205
+ | `lse_from_hyperscript` | Parse hyperscript (24 languages) to LSE bracket + protocol JSON |
206
+ | `lse_to_hyperscript` | Validate/compile LSE or protocol JSON returned by an LLM |
207
+ | `execute_lse` | Parse LSE, compile to JS, and return the execution result |
208
+ | `validate_lse` | Validate LSE or protocol JSON without executing (pre-flight) |
209
+ | `translate_lse` | Translate LSE bracket syntax to natural language (24 languages) |
210
+
211
+ ### LSE Correction (1)
212
+
213
+ | Tool | Description |
214
+ | ------------------------------ | --------------------------------------------------------------- |
215
+ | `lse_generate_with_correction` | Stateless LSE generation + self-correction loop (prompt/schema) |
216
+
217
+ ### Domain DSL Tools (36)
218
+
219
+ Each of the 9 domains exposes `parse_`, `compile_`, `validate_`, and `translate_` tools (9 × 4 = 36). Language coverage comes in three tiers:
168
220
 
169
- 8 domains, each with `parse_`, `compile_`, `validate_`, `translate_` tools:
221
+ - **Bridge (11):** en, es, ja, ar, ko, zh, tr, fr, de, pt, ru
222
+ - **Classic (8):** en, es, ja, ar, ko, zh, tr, fr
223
+ - **Learn (10):** Bridge minus ru
170
224
 
171
- | Domain | Languages | compile Output |
172
- | -------------- | ------------------------------ | --------------------------------- |
173
- | `sql` | en, es, ja, ar, ko, zh, tr, fr | SQL query string |
174
- | `bdd` | en, es, ja, ar | Playwright test (Given/When/Then) |
175
- | `jsx` | en, es, ja, ar, ko, zh, tr, fr | JSX/React markup |
176
- | `todo` | en, es, ja, ar, ko, zh, tr, fr | Structured operation object |
177
- | `behaviorspec` | en, es, ja, ar, ko, zh, tr, fr | Playwright interaction test |
178
- | `llm` | en, es, ja, ar, ko, zh, tr, fr | LLMPromptSpec JSON |
179
- | `flow` | en, es, ja, ar, ko, zh, tr, fr | Reactive data flow JS |
180
- | `voice` | en, es, ja, ar, ko, zh, tr, fr | DOM interaction command |
225
+ | Domain | Languages | compile Output |
226
+ | -------------- | ----------- | --------------------------------- |
227
+ | `sql` | Bridge (11) | SQL query string |
228
+ | `bdd` | Classic (8) | Playwright test (Given/When/Then) |
229
+ | `jsx` | Bridge (11) | JSX/React markup |
230
+ | `todo` | Bridge (11) | Structured operation object |
231
+ | `behaviorspec` | Classic (8) | Playwright interaction test |
232
+ | `llm` | Bridge (11) | LLMPromptSpec JSON |
233
+ | `flow` | Bridge (11) | Reactive data flow JS |
234
+ | `voice` | Bridge (11) | DOM interaction command |
235
+ | `learn` | Learn (10) | Rendered sentence w/ morphology |
181
236
 
182
237
  ## Available Resources (5)
183
238
 
@@ -209,7 +264,7 @@ See **[GRAIL.md](GRAIL.md)** for full documentation, schema reference, and examp
209
264
 
210
265
  ```bash
211
266
  npm run dev # Development mode
212
- npm test # Run tests (375 tests)
267
+ npm test # Run tests (420 tests)
213
268
  npm run typecheck # TypeScript validation
214
269
  npm run build # Build
215
270
  ```