hoolix 0.0.1-beta.19

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 (263) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +337 -0
  3. package/STABILITY.md +109 -0
  4. package/bin/hoolix.js +50 -0
  5. package/bin/mcp-portal.js +12 -0
  6. package/bin/postinstall.js +61 -0
  7. package/dist/app/contracts.d.ts +105 -0
  8. package/dist/app/contracts.d.ts.map +1 -0
  9. package/dist/app/contracts.js +2 -0
  10. package/dist/app/contracts.js.map +1 -0
  11. package/dist/app/events.d.ts +13 -0
  12. package/dist/app/events.d.ts.map +1 -0
  13. package/dist/app/events.js +13 -0
  14. package/dist/app/events.js.map +1 -0
  15. package/dist/app/services/analytics.d.ts +42 -0
  16. package/dist/app/services/analytics.d.ts.map +1 -0
  17. package/dist/app/services/analytics.js +106 -0
  18. package/dist/app/services/analytics.js.map +1 -0
  19. package/dist/app/services/catalog.d.ts +14 -0
  20. package/dist/app/services/catalog.d.ts.map +1 -0
  21. package/dist/app/services/catalog.js +26 -0
  22. package/dist/app/services/catalog.js.map +1 -0
  23. package/dist/app/services/credentials.d.ts +42 -0
  24. package/dist/app/services/credentials.d.ts.map +1 -0
  25. package/dist/app/services/credentials.js +143 -0
  26. package/dist/app/services/credentials.js.map +1 -0
  27. package/dist/app/services/servers.d.ts +15 -0
  28. package/dist/app/services/servers.d.ts.map +1 -0
  29. package/dist/app/services/servers.js +445 -0
  30. package/dist/app/services/servers.js.map +1 -0
  31. package/dist/catalog/community.d.ts +19 -0
  32. package/dist/catalog/community.d.ts.map +1 -0
  33. package/dist/catalog/community.js +53 -0
  34. package/dist/catalog/community.js.map +1 -0
  35. package/dist/catalog/templates.d.ts +436 -0
  36. package/dist/catalog/templates.d.ts.map +1 -0
  37. package/dist/catalog/templates.js +489 -0
  38. package/dist/catalog/templates.js.map +1 -0
  39. package/dist/commands/audit.d.ts +2 -0
  40. package/dist/commands/audit.d.ts.map +1 -0
  41. package/dist/commands/audit.js +122 -0
  42. package/dist/commands/audit.js.map +1 -0
  43. package/dist/commands/bundle.d.ts +11 -0
  44. package/dist/commands/bundle.d.ts.map +1 -0
  45. package/dist/commands/bundle.js +299 -0
  46. package/dist/commands/bundle.js.map +1 -0
  47. package/dist/commands/clients.d.ts +6 -0
  48. package/dist/commands/clients.d.ts.map +1 -0
  49. package/dist/commands/clients.js +242 -0
  50. package/dist/commands/clients.js.map +1 -0
  51. package/dist/commands/completion.d.ts +18 -0
  52. package/dist/commands/completion.d.ts.map +1 -0
  53. package/dist/commands/completion.js +495 -0
  54. package/dist/commands/completion.js.map +1 -0
  55. package/dist/commands/connect.d.ts +10 -0
  56. package/dist/commands/connect.d.ts.map +1 -0
  57. package/dist/commands/connect.js +463 -0
  58. package/dist/commands/connect.js.map +1 -0
  59. package/dist/commands/create.d.ts +2 -0
  60. package/dist/commands/create.d.ts.map +1 -0
  61. package/dist/commands/create.js +607 -0
  62. package/dist/commands/create.js.map +1 -0
  63. package/dist/commands/delete.d.ts +2 -0
  64. package/dist/commands/delete.d.ts.map +1 -0
  65. package/dist/commands/delete.js +44 -0
  66. package/dist/commands/delete.js.map +1 -0
  67. package/dist/commands/doctor.d.ts +2 -0
  68. package/dist/commands/doctor.d.ts.map +1 -0
  69. package/dist/commands/doctor.js +259 -0
  70. package/dist/commands/doctor.js.map +1 -0
  71. package/dist/commands/export.d.ts +2 -0
  72. package/dist/commands/export.d.ts.map +1 -0
  73. package/dist/commands/export.js +93 -0
  74. package/dist/commands/export.js.map +1 -0
  75. package/dist/commands/gui.d.ts +2 -0
  76. package/dist/commands/gui.d.ts.map +1 -0
  77. package/dist/commands/gui.js +19 -0
  78. package/dist/commands/gui.js.map +1 -0
  79. package/dist/commands/import.d.ts +2 -0
  80. package/dist/commands/import.d.ts.map +1 -0
  81. package/dist/commands/import.js +102 -0
  82. package/dist/commands/import.js.map +1 -0
  83. package/dist/commands/info.d.ts +2 -0
  84. package/dist/commands/info.d.ts.map +1 -0
  85. package/dist/commands/info.js +151 -0
  86. package/dist/commands/info.js.map +1 -0
  87. package/dist/commands/list.d.ts +2 -0
  88. package/dist/commands/list.d.ts.map +1 -0
  89. package/dist/commands/list.js +90 -0
  90. package/dist/commands/list.js.map +1 -0
  91. package/dist/commands/reindex.d.ts +2 -0
  92. package/dist/commands/reindex.d.ts.map +1 -0
  93. package/dist/commands/reindex.js +186 -0
  94. package/dist/commands/reindex.js.map +1 -0
  95. package/dist/commands/rotate.d.ts +2 -0
  96. package/dist/commands/rotate.d.ts.map +1 -0
  97. package/dist/commands/rotate.js +67 -0
  98. package/dist/commands/rotate.js.map +1 -0
  99. package/dist/commands/secrets.d.ts +10 -0
  100. package/dist/commands/secrets.d.ts.map +1 -0
  101. package/dist/commands/secrets.js +293 -0
  102. package/dist/commands/secrets.js.map +1 -0
  103. package/dist/commands/start.d.ts +2 -0
  104. package/dist/commands/start.d.ts.map +1 -0
  105. package/dist/commands/start.js +234 -0
  106. package/dist/commands/start.js.map +1 -0
  107. package/dist/commands/stats.d.ts +2 -0
  108. package/dist/commands/stats.d.ts.map +1 -0
  109. package/dist/commands/stats.js +220 -0
  110. package/dist/commands/stats.js.map +1 -0
  111. package/dist/commands/stop.d.ts +2 -0
  112. package/dist/commands/stop.d.ts.map +1 -0
  113. package/dist/commands/stop.js +24 -0
  114. package/dist/commands/stop.js.map +1 -0
  115. package/dist/commands/templates.d.ts +2 -0
  116. package/dist/commands/templates.d.ts.map +1 -0
  117. package/dist/commands/templates.js +168 -0
  118. package/dist/commands/templates.js.map +1 -0
  119. package/dist/commands/trial.d.ts +2 -0
  120. package/dist/commands/trial.d.ts.map +1 -0
  121. package/dist/commands/trial.js +61 -0
  122. package/dist/commands/trial.js.map +1 -0
  123. package/dist/commands/uninstall.d.ts +2 -0
  124. package/dist/commands/uninstall.d.ts.map +1 -0
  125. package/dist/commands/uninstall.js +114 -0
  126. package/dist/commands/uninstall.js.map +1 -0
  127. package/dist/commands/update.d.ts +2 -0
  128. package/dist/commands/update.d.ts.map +1 -0
  129. package/dist/commands/update.js +104 -0
  130. package/dist/commands/update.js.map +1 -0
  131. package/dist/commands/verify.d.ts +2 -0
  132. package/dist/commands/verify.d.ts.map +1 -0
  133. package/dist/commands/verify.js +301 -0
  134. package/dist/commands/verify.js.map +1 -0
  135. package/dist/core/config.d.ts +25 -0
  136. package/dist/core/config.d.ts.map +1 -0
  137. package/dist/core/config.js +54 -0
  138. package/dist/core/config.js.map +1 -0
  139. package/dist/core/errors.d.ts +25 -0
  140. package/dist/core/errors.d.ts.map +1 -0
  141. package/dist/core/errors.js +53 -0
  142. package/dist/core/errors.js.map +1 -0
  143. package/dist/core/logger.d.ts +3 -0
  144. package/dist/core/logger.d.ts.map +1 -0
  145. package/dist/core/logger.js +12 -0
  146. package/dist/core/logger.js.map +1 -0
  147. package/dist/core/paths.d.ts +15 -0
  148. package/dist/core/paths.d.ts.map +1 -0
  149. package/dist/core/paths.js +51 -0
  150. package/dist/core/paths.js.map +1 -0
  151. package/dist/core/registry.d.ts +474 -0
  152. package/dist/core/registry.d.ts.map +1 -0
  153. package/dist/core/registry.js +186 -0
  154. package/dist/core/registry.js.map +1 -0
  155. package/dist/core/updater.d.ts +16 -0
  156. package/dist/core/updater.d.ts.map +1 -0
  157. package/dist/core/updater.js +317 -0
  158. package/dist/core/updater.js.map +1 -0
  159. package/dist/core/version.d.ts +2 -0
  160. package/dist/core/version.d.ts.map +1 -0
  161. package/dist/core/version.js +3 -0
  162. package/dist/core/version.js.map +1 -0
  163. package/dist/index.d.ts +13 -0
  164. package/dist/index.d.ts.map +1 -0
  165. package/dist/index.js +270 -0
  166. package/dist/index.js.map +1 -0
  167. package/dist/ingestion/chunker.d.ts +13 -0
  168. package/dist/ingestion/chunker.d.ts.map +1 -0
  169. package/dist/ingestion/chunker.js +107 -0
  170. package/dist/ingestion/chunker.js.map +1 -0
  171. package/dist/ingestion/cleaners.d.ts +10 -0
  172. package/dist/ingestion/cleaners.d.ts.map +1 -0
  173. package/dist/ingestion/cleaners.js +61 -0
  174. package/dist/ingestion/cleaners.js.map +1 -0
  175. package/dist/ingestion/detectors.d.ts +5 -0
  176. package/dist/ingestion/detectors.d.ts.map +1 -0
  177. package/dist/ingestion/detectors.js +25 -0
  178. package/dist/ingestion/detectors.js.map +1 -0
  179. package/dist/ingestion/fetchers.d.ts +38 -0
  180. package/dist/ingestion/fetchers.d.ts.map +1 -0
  181. package/dist/ingestion/fetchers.js +296 -0
  182. package/dist/ingestion/fetchers.js.map +1 -0
  183. package/dist/ingestion/github.d.ts +60 -0
  184. package/dist/ingestion/github.d.ts.map +1 -0
  185. package/dist/ingestion/github.js +314 -0
  186. package/dist/ingestion/github.js.map +1 -0
  187. package/dist/ingestion/pipeline.d.ts +3 -0
  188. package/dist/ingestion/pipeline.d.ts.map +1 -0
  189. package/dist/ingestion/pipeline.js +160 -0
  190. package/dist/ingestion/pipeline.js.map +1 -0
  191. package/dist/ingestion/types.d.ts +51 -0
  192. package/dist/ingestion/types.d.ts.map +1 -0
  193. package/dist/ingestion/types.js +2 -0
  194. package/dist/ingestion/types.js.map +1 -0
  195. package/dist/lib/auth.d.ts +2 -0
  196. package/dist/lib/auth.d.ts.map +1 -0
  197. package/dist/lib/auth.js +6 -0
  198. package/dist/lib/auth.js.map +1 -0
  199. package/dist/lib/embedding.d.ts +10 -0
  200. package/dist/lib/embedding.d.ts.map +1 -0
  201. package/dist/lib/embedding.js +21 -0
  202. package/dist/lib/embedding.js.map +1 -0
  203. package/dist/mcp/host.d.ts +16 -0
  204. package/dist/mcp/host.d.ts.map +1 -0
  205. package/dist/mcp/host.js +307 -0
  206. package/dist/mcp/host.js.map +1 -0
  207. package/dist/mcp/proxy-host.d.ts +25 -0
  208. package/dist/mcp/proxy-host.d.ts.map +1 -0
  209. package/dist/mcp/proxy-host.js +393 -0
  210. package/dist/mcp/proxy-host.js.map +1 -0
  211. package/dist/mcp/stdio-host.d.ts +19 -0
  212. package/dist/mcp/stdio-host.d.ts.map +1 -0
  213. package/dist/mcp/stdio-host.js +175 -0
  214. package/dist/mcp/stdio-host.js.map +1 -0
  215. package/dist/process/manager.d.ts +74 -0
  216. package/dist/process/manager.d.ts.map +1 -0
  217. package/dist/process/manager.js +322 -0
  218. package/dist/process/manager.js.map +1 -0
  219. package/dist/rag/models.d.ts +30 -0
  220. package/dist/rag/models.d.ts.map +1 -0
  221. package/dist/rag/models.js +30 -0
  222. package/dist/rag/models.js.map +1 -0
  223. package/dist/rag/store.d.ts +63 -0
  224. package/dist/rag/store.d.ts.map +1 -0
  225. package/dist/rag/store.js +505 -0
  226. package/dist/rag/store.js.map +1 -0
  227. package/dist/rag/types.d.ts +56 -0
  228. package/dist/rag/types.d.ts.map +1 -0
  229. package/dist/rag/types.js +2 -0
  230. package/dist/rag/types.js.map +1 -0
  231. package/dist/sources/plugins.d.ts +25 -0
  232. package/dist/sources/plugins.d.ts.map +1 -0
  233. package/dist/sources/plugins.js +55 -0
  234. package/dist/sources/plugins.js.map +1 -0
  235. package/dist/sources/registry.d.ts +19 -0
  236. package/dist/sources/registry.d.ts.map +1 -0
  237. package/dist/sources/registry.js +183 -0
  238. package/dist/sources/registry.js.map +1 -0
  239. package/dist/sources/types.d.ts +361 -0
  240. package/dist/sources/types.d.ts.map +1 -0
  241. package/dist/sources/types.js +59 -0
  242. package/dist/sources/types.js.map +1 -0
  243. package/dist/tui/index.d.ts +22 -0
  244. package/dist/tui/index.d.ts.map +1 -0
  245. package/dist/tui/index.js +711 -0
  246. package/dist/tui/index.js.map +1 -0
  247. package/dist/ui/format.d.ts +27 -0
  248. package/dist/ui/format.d.ts.map +1 -0
  249. package/dist/ui/format.js +80 -0
  250. package/dist/ui/format.js.map +1 -0
  251. package/dist/ui/help.d.ts +2 -0
  252. package/dist/ui/help.d.ts.map +1 -0
  253. package/dist/ui/help.js +106 -0
  254. package/dist/ui/help.js.map +1 -0
  255. package/dist/web/assets.d.ts +2 -0
  256. package/dist/web/assets.d.ts.map +1 -0
  257. package/dist/web/assets.js +659 -0
  258. package/dist/web/assets.js.map +1 -0
  259. package/dist/web/server.d.ts +9 -0
  260. package/dist/web/server.d.ts.map +1 -0
  261. package/dist/web/server.js +349 -0
  262. package/dist/web/server.js.map +1 -0
  263. package/package.json +105 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hoolix contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,337 @@
1
+ # Hoolix
2
+
3
+ **Hoolix is your MCP home base.** Turn documentation sites, `llms.txt`, GitHub repositories, templates, and private knowledge sources into secure, source-grounded MCP servers your agents can trust.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/hoolix?color=blue)](https://www.npmjs.com/package/hoolix)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
+ [![Build](https://img.shields.io/github/actions/workflow/status/JayLLM/hoolix/release.yml?branch=main)](https://github.com/JayLLM/hoolix/actions)
8
+ [![Docs](https://img.shields.io/badge/docs-Docusaurus-25c2a0?logo=docusaurus)](https://jayllm.github.io/hoolix/)
9
+
10
+ > Forge docs, repos, and internal knowledge into production-grade MCP servers with a beautiful TUI, a scriptable CLI, and a lightweight GUI.
11
+
12
+ Hoolix helps developers and teams create high-quality RAG-backed MCP servers from real sources. It keeps every answer grounded with source URLs, supports Streamable HTTP and stdio transports, and gives you the daily tools you need: create, verify, start, connect, reindex, monitor, export, and share.
13
+
14
+ ## Why Hoolix?
15
+
16
+ Agents are only as useful as the context they can reliably reach. Copy-pasted docs go stale, ad hoc MCP servers are hard to verify, and hosted RAG often adds privacy and cost concerns. Hoolix gives you a local-first, open-source path:
17
+
18
+ | You need | Hoolix gives you |
19
+ | --- | --- |
20
+ | Fast first run | `hoolix` opens the TUI; `hoolix trial` creates a demo server in one command |
21
+ | Trustworthy retrieval | Source-grounded search, page reads, table of contents, and `verify` health checks |
22
+ | Flexible source models | Single URLs, multi-source definitions, GitHub repos, private docs, templates, and custom source plugins |
23
+ | Real MCP hosting | Authenticated Streamable HTTP plus stdio for local client workflows |
24
+ | Team workflows | Usage stats, audit logs, sanitized exports, and importable bundles |
25
+ | Power-user automation | `--json` across machine-friendly commands, scheduled reindexing, token budgets, and scriptable lifecycle commands |
26
+
27
+ ## Installation
28
+
29
+ Prebuilt binaries are the recommended path. They are fast, self-contained, and do not require Node, Bun, `tsx`, or source files after installation.
30
+
31
+ ### macOS / Linux
32
+
33
+ ```bash
34
+ curl -fsSL https://raw.githubusercontent.com/JayLLM/Hoolix/main/install.sh | bash
35
+ ```
36
+
37
+ ### Windows PowerShell
38
+
39
+ ```powershell
40
+ iex (irm https://raw.githubusercontent.com/JayLLM/Hoolix/main/install.ps1)
41
+ ```
42
+
43
+ The installer verifies the binary and prints PATH guidance if your current terminal needs to be refreshed.
44
+
45
+ ### Try Without Installing
46
+
47
+ ```bash
48
+ npx hoolix trial
49
+ ```
50
+
51
+ This is the easiest way to prove the flow on a new machine or in a demo. The full install is still best for daily use.
52
+
53
+ ## Quick Start
54
+
55
+ ### 1. Open The TUI
56
+
57
+ ```bash
58
+ hoolix
59
+ ```
60
+
61
+ Running `hoolix` with no arguments opens the terminal dashboard. From there you can create servers, start or stop them, verify retrieval quality, copy client configs, launch template flows, and inspect recent logs. It is the friendliest way to learn the product.
62
+
63
+ If your terminal is non-interactive, Hoolix gracefully falls back to CLI help.
64
+
65
+ ### 2. Create A Trial Server
66
+
67
+ ```bash
68
+ hoolix trial
69
+ hoolix verify hoolix-trial
70
+ hoolix start hoolix-trial
71
+ ```
72
+
73
+ `trial` creates a public demo server from known-good sources, so you can test MCP tools before choosing your own docs.
74
+
75
+ ### 3. Connect Your MCP Client
76
+
77
+ ```bash
78
+ hoolix connect hoolix-trial --client cursor
79
+ ```
80
+
81
+ Supported client targets include Cursor, Claude Desktop, Windsurf, Continue, Cline, Grok Build, and generic JSON output. `connect` creates backups before editing client config files and prints the next step for your client.
82
+
83
+ ### 4. Ask Your Agent
84
+
85
+ Try:
86
+
87
+ ```text
88
+ Use search_documentation to find installation instructions, then cite the source URL.
89
+ ```
90
+
91
+ Every Hoolix search/read result includes grounding URLs so the agent can show where the answer came from.
92
+
93
+ ## Create Servers
94
+
95
+ ### Single Source
96
+
97
+ Old syntax remains fully supported:
98
+
99
+ ```bash
100
+ hoolix create "React Docs" --url https://react.dev/llms.txt --yes
101
+ ```
102
+
103
+ Use `--url` for a single documentation URL, `llms.txt`, `llms-full.txt`, GitHub URL, or regular docs page.
104
+
105
+ ### Multi-Source
106
+
107
+ Use additive `--source` flags when one MCP server should combine multiple knowledge bases:
108
+
109
+ ```bash
110
+ hoolix create "Frontend Stack" \
111
+ --source docs:https://react.dev/llms.txt \
112
+ --source github:vercel/next.js \
113
+ --yes
114
+ ```
115
+
116
+ Each source is stored in the server definition and preserved through reindex, verify, export, import, TUI, and GUI views.
117
+
118
+ ### Template-Backed
119
+
120
+ Templates are curated starting points for common MCP servers:
121
+
122
+ ```bash
123
+ hoolix templates list
124
+ hoolix templates info terraform-aws-docs
125
+ hoolix create "Terraform AWS" --template terraform-aws-docs --yes
126
+ ```
127
+
128
+ Templates can still accept normal inputs such as `--url`, `--header`, `--cookie`, `--hybrid`, and schedules when the template supports them.
129
+
130
+ ### Private Or Authenticated Sources
131
+
132
+ ```bash
133
+ hoolix create "Private Docs" \
134
+ --url https://docs.example.com/llms.txt \
135
+ --header "Authorization: Bearer $DOCS_TOKEN" \
136
+ --cookie "session=$DOCS_SESSION" \
137
+ --yes
138
+ ```
139
+
140
+ For private GitHub repositories, set `GITHUB_TOKEN` before creating or reindexing.
141
+
142
+ ## Core Concepts
143
+
144
+ | Concept | Meaning |
145
+ | --- | --- |
146
+ | Server | A named MCP server with its own slug, index, auth key, audit log, stats, and lifecycle |
147
+ | Source | A piece of knowledge to ingest, such as `docs:<url>`, `github:owner/repo`, `llms:<url>`, `web:<url>`, or `custom:<provider>:<value>` |
148
+ | Server Definition | The validated, portable model that records sources, template backing, auth hints, schedules, and options |
149
+ | Template | An official catalog entry that creates a known-good server shape |
150
+ | Transport | How clients talk to the server: authenticated Streamable HTTP or local stdio |
151
+ | Verification | Hoolix health checks for chunks, samples, grounding, source status, and retrieval quality |
152
+ | Bundle | A `.hoolix.json` export that can be imported elsewhere, optionally stripped of secrets for teams |
153
+
154
+ ## Common Commands
155
+
156
+ | Command | What it does |
157
+ | --- | --- |
158
+ | `hoolix` | Open the TUI dashboard |
159
+ | `hoolix trial` | Create a one-click demo server |
160
+ | `hoolix create "Name" --url <url>` | Create from one source |
161
+ | `hoolix create "Name" --source docs:<url> --source github:owner/repo` | Create from multiple sources |
162
+ | `hoolix create "Name" --template <id>` | Create from an official template |
163
+ | `hoolix templates list` | Browse official templates |
164
+ | `hoolix list` / `hoolix info <slug>` | Inspect registered servers |
165
+ | `hoolix verify <slug>` | Check source, index, grounding, and retrieval health |
166
+ | `hoolix start <slug>` | Start authenticated Streamable HTTP MCP hosting |
167
+ | `hoolix start <slug> --transport stdio --json` | Print stdio MCP launch config |
168
+ | `hoolix connect <slug> --client cursor` | Wire the server into an MCP client |
169
+ | `hoolix reindex <slug>` | Incrementally refresh sources and rebuild the index |
170
+ | `hoolix reindex <slug> --schedule daily` | Enable scheduled auto-reindex metadata |
171
+ | `hoolix reindex --due --json` | Run servers whose schedule is due |
172
+ | `hoolix stats <slug>` | Show usage analytics and top queries |
173
+ | `hoolix audit <slug>` | Query raw audit entries |
174
+ | `hoolix export <slug> --team --strip-key` | Create a team-safe bundle |
175
+ | `hoolix import --file server.hoolix.json` | Import a bundle |
176
+ | `hoolix gui` | Open the local web dashboard |
177
+ | `hoolix doctor` | Diagnose install, paths, config, runtime, plugins, and source health |
178
+
179
+ Machine-friendly commands support `--json` so Hoolix works cleanly in scripts and CI.
180
+
181
+ ## MCP Tools
182
+
183
+ Every hosted Hoolix server exposes:
184
+
185
+ | Tool | Purpose |
186
+ | --- | --- |
187
+ | `search_documentation` | Search the indexed sources with keyword, hybrid, and optional token/context budgeting |
188
+ | `read_documentation_page` | Read a grounded page or chunk by URL/title |
189
+ | `get_table_of_contents` | Explore indexed structure and source sections |
190
+
191
+ Tool responses include source URLs. Search tools accept token-aware options such as `maxTokens` and `contextWindowTokens` so clients can request appropriately sized context.
192
+
193
+ ## Transports
194
+
195
+ ### Streamable HTTP
196
+
197
+ ```bash
198
+ hoolix start react-docs
199
+ ```
200
+
201
+ HTTP hosting is authenticated with a per-server bearer key and includes rate limiting, timeouts, and audit logging.
202
+
203
+ ### Stdio
204
+
205
+ ```bash
206
+ hoolix start react-docs --transport stdio --json
207
+ ```
208
+
209
+ Use stdio for clients that prefer local process transports. The JSON output is designed to be copied into client configuration or consumed by automation.
210
+
211
+ ## TUI And GUI
212
+
213
+ - `hoolix` launches the TUI by default.
214
+ - `hoolix gui` launches a token-protected local dashboard.
215
+ - CLI, TUI, and GUI share the same app services, definitions, catalog, verification, analytics, and server lifecycle logic.
216
+
217
+ Use the TUI for fast daily work, the CLI for scripts and repeatability, and the GUI for visual management, catalog browsing, stats, and playground testing.
218
+
219
+ ## Reliability And Security
220
+
221
+ - Per-server auth keys with `hoolix rotate`
222
+ - Tool timeouts and response guards
223
+ - Persistent rate limiting for HTTP hosts
224
+ - Append-only audit logs
225
+ - Usage analytics via `hoolix stats`
226
+ - Incremental reindexing and schedule metadata
227
+ - Private source headers and cookies
228
+ - Team-safe exports with `--strip-key`
229
+ - `doctor` and `verify` health cards for fast diagnosis
230
+
231
+ ## Custom Source Plugins
232
+
233
+ Hoolix can discover simple source plugin manifests from your data directory or `HOOLIX_SOURCE_PLUGIN_DIR`.
234
+
235
+ ```bash
236
+ hoolix create "Internal Handbook" \
237
+ --source custom:handbook:getting-started \
238
+ --yes
239
+ ```
240
+
241
+ Plugins map custom source identifiers to supported source kinds such as docs, web, llms, or GitHub. This keeps Hoolix extensible without forcing every team source into core.
242
+
243
+ ## Examples
244
+
245
+ ```bash
246
+ # TUI-first daily workflow
247
+ hoolix
248
+
249
+ # One-click first run
250
+ hoolix trial
251
+ hoolix connect hoolix-trial --client cursor
252
+
253
+ # Single-source docs server
254
+ hoolix create "Astro Docs" --url https://docs.astro.build/llms.txt --yes
255
+ hoolix verify astro-docs
256
+
257
+ # Multi-source project server
258
+ hoolix create "Company Platform" \
259
+ --source docs:https://docs.example.com/llms.txt \
260
+ --source github:example/platform \
261
+ --source web:https://status.example.com/docs \
262
+ --yes
263
+
264
+ # Template-backed server
265
+ hoolix create "Hoolix Docs" --template hoolix-docs --yes
266
+
267
+ # Private docs
268
+ hoolix create "Private API" \
269
+ --url https://docs.example.com/private/llms.txt \
270
+ --header "Authorization: Bearer $DOCS_TOKEN" \
271
+ --yes
272
+
273
+ # Scheduled maintenance
274
+ hoolix reindex company-platform --schedule daily --yes
275
+ hoolix reindex --due --json
276
+
277
+ # Team-safe sharing
278
+ hoolix export company-platform --team --strip-key --file company-platform.hoolix.json
279
+ hoolix import --file company-platform.hoolix.json --slug company-platform-copy --yes
280
+ ```
281
+
282
+ ## Future Vision
283
+
284
+ Hoolix is growing toward the definitive application for MCP operations: official server catalogs, richer team libraries, deeper plugin hooks, managed deployment targets, policy-aware source access, and a shared experience across CLI, TUI, GUI, and hosted workflows.
285
+
286
+ The north star is simple: when a team asks, "How do we make this knowledge available to agents safely?", the answer should be Hoolix.
287
+
288
+ ## Development
289
+
290
+ ```bash
291
+ bun install
292
+
293
+ # Run from source
294
+ bun run dev
295
+
296
+ # Type check
297
+ npm run typecheck
298
+
299
+ # Tests
300
+ npm test
301
+ npm run test:e2e
302
+
303
+ # Build native binary
304
+ bun run build:binary
305
+
306
+ # Documentation site
307
+ cd docs
308
+ npm install
309
+ npm start
310
+ ```
311
+
312
+ See [AGENTS.md](./AGENTS.md) for architecture rules, contribution expectations, testing guidance, and documentation requirements.
313
+
314
+ ## Limitations
315
+
316
+ - Hoolix is local-first today. Production public hosting is expected to sit behind your reverse proxy or future hosted deployment path.
317
+ - Hybrid semantic search is optional and lazy-loaded. The default index stays fast and lightweight.
318
+ - Heavily protected sites may require `--header`, `--cookie`, direct `llms.txt`, or GitHub token access.
319
+ - Template and plugin ecosystems are intentionally conservative while the catalog matures.
320
+
321
+ ## Contributing
322
+
323
+ Contributions are welcome. Please open an issue for substantial changes, keep PRs focused, run tests, and update documentation alongside behavior changes.
324
+
325
+ ## Releasing
326
+
327
+ Release automation uses `release-it` and GitHub Actions. See [docs/RELEASING.md](./docs/RELEASING.md) for the release checklist and binary publishing workflow.
328
+
329
+ ## License
330
+
331
+ MIT © Hoolix contributors
332
+
333
+ ---
334
+
335
+ **Links**: [GitHub](https://github.com/JayLLM/Hoolix) · [Issues](https://github.com/JayLLM/Hoolix/issues) · [Releases](https://github.com/JayLLM/Hoolix/releases)
336
+
337
+ Made for developers who want agents to find the right paragraph, cite the right URL, and get back to work.
package/STABILITY.md ADDED
@@ -0,0 +1,109 @@
1
+ # Hoolix Stability & Versioning Promises
2
+
3
+ **Current stable version: 1.0.0 (released 2026-06-04)**
4
+
5
+ This document describes what is stable, what may change, and the versioning policy for Hoolix v1.0 and beyond.
6
+
7
+ ## Installation (recommended)
8
+
9
+ ```bash
10
+ npm install -g hoolix # recommended — provenance-verified
11
+ ```
12
+
13
+ Standalone binary (Linux/macOS):
14
+ ```bash
15
+ curl -fsSL https://raw.githubusercontent.com/JayLLM/hoolix/main/install.sh | bash
16
+ ```
17
+
18
+ Standalone binary (Windows):
19
+ ```powershell
20
+ iwr -useb https://raw.githubusercontent.com/JayLLM/hoolix/main/install.ps1 | iex
21
+ ```
22
+
23
+ ---
24
+
25
+ ## Versioning (Semantic Versioning)
26
+
27
+ Hoolix follows [Semantic Versioning](https://semver.org) `MAJOR.MINOR.PATCH`:
28
+
29
+ | Change type | Version bump |
30
+ |---|---|
31
+ | Breaking change to stable CLI or data format | **MAJOR** |
32
+ | New command, new template, new flag | **MINOR** |
33
+ | Bug fix, performance, or non-breaking behaviour | **PATCH** |
34
+
35
+ Pre-releases (`0.0.1-beta.*`) carry **no stability guarantees**. Once v1.0.0 ships, the promises below apply.
36
+
37
+ ---
38
+
39
+ ## What is stable in v1.0
40
+
41
+ ### CLI commands and flags
42
+ All commands listed in `hoolix --help` are considered **stable**. Their positional arguments, named flags, and exit codes will not change in a breaking way within a MAJOR version.
43
+
44
+ | Command | Stable? | Notes |
45
+ |---|---|---|
46
+ | `hoolix create / install` | ✅ | Positional syntax and flag names locked |
47
+ | `hoolix list / info / delete` | ✅ | Output columns stable in human mode; `--json` schema stable |
48
+ | `hoolix start / stop` | ✅ | `--proxy` flag and HTTP config format stable |
49
+ | `hoolix connect` | ✅ | Per-client config format follows official MCP client schemas |
50
+ | `hoolix secrets *` | ✅ | |
51
+ | `hoolix export / import` | ✅ | Bundle format `version: 2` stable |
52
+ | `hoolix bundle export/import` | ✅ | Multi-server bundle format `version: 1` stable |
53
+ | `hoolix templates *` | ✅ | |
54
+ | `hoolix completion` | ✅ | Script output may improve; sourcing pattern unchanged |
55
+ | `hoolix doctor` | ✅ | Check names stable; JSON keys stable |
56
+ | `hoolix stats / audit` | ✅ | |
57
+ | `hoolix rotate` | ✅ | |
58
+ | `hoolix gui` | ✅ | Web dashboard local-only; no auth changes without notice |
59
+ | `hoolix update / uninstall` | ✅ | |
60
+ | `hoolix trial` | ✅ | Template used may change; flags stable |
61
+
62
+ ### JSON output (`--json`)
63
+ When `--json` is passed, the top-level object shape is **stable**. New keys may be added (non-breaking). Keys will not be removed or renamed within a MAJOR version.
64
+
65
+ ### Data files on disk
66
+ | File | Path | Stability |
67
+ |---|---|---|
68
+ | `metadata.json` | `~/.local/share/hoolix/servers/<slug>/` | Stable — new keys may be added |
69
+ | `credentials.json` | Same directory, mode 0600 | Stable |
70
+ | `.runtime.json` | Same directory | Stable (new keys may be added) |
71
+ | `audit.log` | Same directory | Newline-delimited JSON; schema stable |
72
+ | `chunks.json` | `data/` subdirectory | Stable |
73
+ | Bundle format | `.hoolix.json` | `version: 2` (single) and `version: 1` (multi) stable |
74
+
75
+ ### Template IDs
76
+ Official template IDs (e.g. `filesystem`, `github-api`, `postgres`) will not be removed or renamed in a MINOR bump. New templates are always additive.
77
+
78
+ ---
79
+
80
+ ## What may change (no stability promise)
81
+
82
+ | Area | Status |
83
+ |---|---|
84
+ | TUI layout and key bindings | **Unstable** — may change in any MINOR |
85
+ | Internal `__internal-host` / `__internal-proxy` flags | **Internal** — never call directly |
86
+ | Web GUI (`hoolix gui`) API routes | **Unstable** until v1.1 |
87
+ | Community template format | Stable schema; directory path may change before v1.0 |
88
+ | SSE streaming in proxy mode | Phase 1 only; full SSE streaming is planned for a future MINOR |
89
+ | `hoolix verify` scoring rubric | May improve; exact scores may change |
90
+
91
+ ---
92
+
93
+ ## Upgrade policy
94
+
95
+ - **PATCH** → safe to upgrade immediately; no action needed.
96
+ - **MINOR** → safe to upgrade; new features available. Read the CHANGELOG.
97
+ - **MAJOR** → migration guide published with the release. Existing data files are migrated automatically where possible; breaking CLI changes are listed explicitly.
98
+
99
+ ---
100
+
101
+ ## Long-term support (LTS)
102
+
103
+ v1.x will receive security fixes for a minimum of **24 months** after release. v2.0 will be announced with at least 6 months notice.
104
+
105
+ ---
106
+
107
+ ## Filing stability issues
108
+
109
+ If you find a behaviour that violates these promises (a command flag removed, a JSON key renamed, a data file broken), please [open an issue](https://github.com/JayLLM/hoolix/issues) with the label `stability`.
package/bin/hoolix.js ADDED
@@ -0,0 +1,50 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * Hoolix CLI — npm global package entry point.
5
+ *
6
+ * Production path (dist/index.js exists after `npm install -g hoolix`):
7
+ * Loads compiled JS via dynamic import *in the same process*.
8
+ * This gives correct signal handling (Ctrl+C in TUI), faster startup,
9
+ * and avoids the subprocess overhead of the old spawnSync approach.
10
+ *
11
+ * Development path (dist/ absent, src/ present):
12
+ * Falls back to tsx via spawnSync for TypeScript source execution.
13
+ *
14
+ * Note: this file is intentionally plain JS (not TS) so it runs without
15
+ * any compilation step. It uses top-level await which requires Node ≥ 14.8
16
+ * and ESM ("type":"module" in package.json).
17
+ */
18
+
19
+ import { existsSync } from 'node:fs';
20
+ import { fileURLToPath } from 'node:url';
21
+ import { dirname, join } from 'node:path';
22
+
23
+ const __dirname = dirname(fileURLToPath(import.meta.url));
24
+ const distEntry = join(__dirname, '..', 'dist', 'index.js');
25
+ const srcEntry = join(__dirname, '..', 'src', 'index.ts');
26
+
27
+ if (existsSync(distEntry)) {
28
+ // ── Production / npm global install ──────────────────────────────────────
29
+ // Import compiled JS directly into this process. process.argv is already set
30
+ // correctly (node bins/hoolix.js [...args]), so src/index.ts reads args normally.
31
+ // Signals (SIGTERM, SIGINT/Ctrl+C, etc.) are handled by src/index.ts directly
32
+ // without needing to propagate through a subprocess.
33
+ await import(distEntry);
34
+ } else {
35
+ // ── Development fallback ──────────────────────────────────────────────────
36
+ // dist/ not built — use tsx to run TypeScript source directly.
37
+ const { spawnSync } = await import('node:child_process');
38
+
39
+ const tsx = join(__dirname, '..', 'node_modules', '.bin', 'tsx');
40
+ if (!existsSync(tsx)) {
41
+ console.error('[hoolix] Development mode requires tsx. Run: npm install');
42
+ process.exit(1);
43
+ }
44
+
45
+ const { status } = spawnSync(tsx, [srcEntry, ...process.argv.slice(2)], {
46
+ stdio: 'inherit',
47
+ env: process.env,
48
+ });
49
+ process.exit(status ?? 1);
50
+ }
@@ -0,0 +1,12 @@
1
+ #!/usr/bin/env node
2
+
3
+ console.warn('Deprecated: Please use the `hoolix` binary instead of `hoolix`.');
4
+ try {
5
+ // Try to exec the new binary if present
6
+ const { spawnSync } = require('child_process');
7
+ const result = spawnSync('hoolix', process.argv.slice(2), { stdio: 'inherit' });
8
+ process.exit(result.status ?? 1);
9
+ } catch (e) {
10
+ console.error('`hoolix` binary not found in PATH. Install using the installer scripts or run `npm run build` and use the dist binary.');
11
+ process.exit(1);
12
+ }
@@ -0,0 +1,61 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Postinstall hint — shown once after `npm install -g hoolix`.
4
+ *
5
+ * Intentionally plain CJS with no imports so it runs on any Node ≥ 14 without
6
+ * compilation or ESM resolution. The script always exits 0.
7
+ *
8
+ * Skips output when:
9
+ * - Running in CI (CI=1)
10
+ * - Explicitly suppressed (HOOLIX_NO_POSTINSTALL=1)
11
+ * - stdout is not a TTY (piped / scripted install)
12
+ * - The install looks like a local dev install (no npm_config_global set
13
+ * and node_modules/.bin/tsx exists next to us, indicating a dev checkout)
14
+ */
15
+
16
+ 'use strict';
17
+
18
+ // Always exit 0 — postinstall must never fail or block the install.
19
+ process.on('uncaughtException', () => process.exit(0));
20
+
21
+ (function run() {
22
+ // Skip in CI or when explicitly suppressed
23
+ if (process.env.CI || process.env.HOOLIX_NO_POSTINSTALL === '1') return;
24
+
25
+ // Skip when output is not a terminal (e.g. npm install piped into a script)
26
+ if (!process.stdout.isTTY) return;
27
+
28
+ // Skip if this looks like a dev checkout: check for the presence of src/
29
+ // (i.e. we're running postinstall because someone ran `npm install` in the repo)
30
+ const path = require('node:path');
31
+ const fs = require('node:fs');
32
+ const dir = path.resolve(__dirname, '..');
33
+ if (fs.existsSync(path.join(dir, 'src', 'index.ts'))) return;
34
+
35
+ const c = {
36
+ cyan: '\x1b[36m',
37
+ green: '\x1b[32m',
38
+ yellow:'\x1b[33m',
39
+ bold: '\x1b[1m',
40
+ dim: '\x1b[2m',
41
+ reset: '\x1b[0m',
42
+ };
43
+
44
+ process.stdout.write([
45
+ '',
46
+ ` ${c.cyan}${c.bold}◆ hoolix installed!${c.reset}`,
47
+ '',
48
+ ` ${c.green}✓${c.reset} Run ${c.cyan}hoolix doctor${c.reset} to verify your installation.`,
49
+ ` ${c.green}✓${c.reset} Run ${c.cyan}hoolix templates list${c.reset} to browse 14 official templates.`,
50
+ ` ${c.green}✓${c.reset} Run ${c.cyan}hoolix install filesystem /path/to/project --yes${c.reset} to get started.`,
51
+ '',
52
+ ` ${c.yellow}Shell completions:${c.reset}`,
53
+ ` ${c.dim}bash:${c.reset} eval "$(hoolix completion bash)"`,
54
+ ` ${c.dim}zsh:${c.reset} eval "$(hoolix completion zsh)"`,
55
+ ` ${c.dim}fish:${c.reset} hoolix completion fish | source`,
56
+ ` ${c.dim}powershell:${c.reset} hoolix completion powershell | Invoke-Expression`,
57
+ '',
58
+ ` ${c.dim}Full docs: https://github.com/JayLLM/hoolix${c.reset}`,
59
+ '',
60
+ ].join('\n'));
61
+ }());