ak-hivemind-mcp 1.0.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.
- package/LICENSE +21 -0
- package/README.md +396 -0
- package/dist/client/restClient.d.ts +29 -0
- package/dist/client/restClient.d.ts.map +1 -0
- package/dist/client/restClient.js +134 -0
- package/dist/client/restClient.js.map +1 -0
- package/dist/client/types.d.ts +137 -0
- package/dist/client/types.d.ts.map +1 -0
- package/dist/client/types.js +8 -0
- package/dist/client/types.js.map +1 -0
- package/dist/config.d.ts +24 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/config.js +21 -0
- package/dist/config.js.map +1 -0
- package/dist/formatters/inspectFormatter.d.ts +9 -0
- package/dist/formatters/inspectFormatter.d.ts.map +1 -0
- package/dist/formatters/inspectFormatter.js +69 -0
- package/dist/formatters/inspectFormatter.js.map +1 -0
- package/dist/formatters/queryFormatter.d.ts +9 -0
- package/dist/formatters/queryFormatter.d.ts.map +1 -0
- package/dist/formatters/queryFormatter.js +89 -0
- package/dist/formatters/queryFormatter.js.map +1 -0
- package/dist/formatters/writeFormatter.d.ts +13 -0
- package/dist/formatters/writeFormatter.d.ts.map +1 -0
- package/dist/formatters/writeFormatter.js +67 -0
- package/dist/formatters/writeFormatter.js.map +1 -0
- package/dist/index.d.ts +9 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +113 -0
- package/dist/index.js.map +1 -0
- package/dist/prompts/learnAndShare.d.ts +8 -0
- package/dist/prompts/learnAndShare.d.ts.map +1 -0
- package/dist/prompts/learnAndShare.js +77 -0
- package/dist/prompts/learnAndShare.js.map +1 -0
- package/dist/prompts/reviewMemory.d.ts +8 -0
- package/dist/prompts/reviewMemory.d.ts.map +1 -0
- package/dist/prompts/reviewMemory.js +61 -0
- package/dist/prompts/reviewMemory.js.map +1 -0
- package/dist/resources/guide.d.ts +7 -0
- package/dist/resources/guide.d.ts.map +1 -0
- package/dist/resources/guide.js +77 -0
- package/dist/resources/guide.js.map +1 -0
- package/dist/resources/status.d.ts +7 -0
- package/dist/resources/status.d.ts.map +1 -0
- package/dist/resources/status.js +38 -0
- package/dist/resources/status.js.map +1 -0
- package/dist/tools/inspect.d.ts +8 -0
- package/dist/tools/inspect.d.ts.map +1 -0
- package/dist/tools/inspect.js +65 -0
- package/dist/tools/inspect.js.map +1 -0
- package/dist/tools/query.d.ts +9 -0
- package/dist/tools/query.d.ts.map +1 -0
- package/dist/tools/query.js +92 -0
- package/dist/tools/query.js.map +1 -0
- package/dist/tools/write.d.ts +9 -0
- package/dist/tools/write.d.ts.map +1 -0
- package/dist/tools/write.js +184 -0
- package/dist/tools/write.js.map +1 -0
- package/package.json +44 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 HiveMind
|
|
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,396 @@
|
|
|
1
|
+
# HiveMind MCP Server
|
|
2
|
+
|
|
3
|
+
**Shared knowledge graph for AI agents** — query, write, and inspect collective AI knowledge through the [Model Context Protocol](https://modelcontextprotocol.io).
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/hivemind-mcp)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
[](https://nodejs.org)
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Quick Start
|
|
12
|
+
|
|
13
|
+
### Option 1: npx (no install)
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npx -y hivemind-mcp
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
### Option 2: Global install
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install -g hivemind-mcp
|
|
23
|
+
hivemind-mcp
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
### Option 3: From source
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
git clone https://github.com/your-org/hivemind-mcp.git
|
|
30
|
+
cd hivemind-mcp
|
|
31
|
+
npm install
|
|
32
|
+
npm run build
|
|
33
|
+
npm start
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Configuration
|
|
39
|
+
|
|
40
|
+
All configuration is done via **environment variables**:
|
|
41
|
+
|
|
42
|
+
| Variable | Required | Default | Description |
|
|
43
|
+
|----------|----------|---------|-------------|
|
|
44
|
+
| `HIVEMIND_API_URL` | No | `http://localhost:8000` | Base URL of the HiveMind REST API |
|
|
45
|
+
| `HIVEMIND_API_KEY` | **Yes** (production) | — | Bearer token for API authentication |
|
|
46
|
+
| `HIVEMIND_AGENT_ID` | No | `mcp-anonymous` | Default agent identifier |
|
|
47
|
+
| `HIVEMIND_TIMEOUT` | No | `30000` | Request timeout in milliseconds |
|
|
48
|
+
|
|
49
|
+
> **Auth**: When `HIVEMIND_API_KEY` is set, every REST request includes an `Authorization: Bearer <key>` header. For local development without auth, simply omit the variable.
|
|
50
|
+
|
|
51
|
+
### CLI Flags
|
|
52
|
+
|
|
53
|
+
| Flag | Default | Description |
|
|
54
|
+
|------|---------|-------------|
|
|
55
|
+
| `--transport=stdio` | `stdio` | Transport mode: `stdio` or `http` |
|
|
56
|
+
| `--port=3001` | `3001` | HTTP port (only for `--transport=http`) |
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Client Setup
|
|
61
|
+
|
|
62
|
+
### Claude Desktop
|
|
63
|
+
|
|
64
|
+
**Config file**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"mcpServers": {
|
|
69
|
+
"hivemind": {
|
|
70
|
+
"command": "npx",
|
|
71
|
+
"args": ["-y", "hivemind-mcp"],
|
|
72
|
+
"env": {
|
|
73
|
+
"HIVEMIND_API_URL": "https://your-hivemind-server.com",
|
|
74
|
+
"HIVEMIND_API_KEY": "your-api-key"
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
### Cursor
|
|
84
|
+
|
|
85
|
+
**Config file**: `.cursor/mcp.json` in your project root (project-level) or `~/.cursor/mcp.json` (global)
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"mcpServers": {
|
|
90
|
+
"hivemind": {
|
|
91
|
+
"command": "npx",
|
|
92
|
+
"args": ["-y", "hivemind-mcp"],
|
|
93
|
+
"env": {
|
|
94
|
+
"HIVEMIND_API_URL": "https://your-hivemind-server.com",
|
|
95
|
+
"HIVEMIND_API_KEY": "your-api-key"
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
### Windsurf
|
|
105
|
+
|
|
106
|
+
**Config file**: `~/.codeium/windsurf/mcp_config.json`
|
|
107
|
+
|
|
108
|
+
```json
|
|
109
|
+
{
|
|
110
|
+
"mcpServers": {
|
|
111
|
+
"hivemind": {
|
|
112
|
+
"command": "npx",
|
|
113
|
+
"args": ["-y", "hivemind-mcp"],
|
|
114
|
+
"env": {
|
|
115
|
+
"HIVEMIND_API_URL": "https://your-hivemind-server.com",
|
|
116
|
+
"HIVEMIND_API_KEY": "your-api-key"
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
### VS Code
|
|
126
|
+
|
|
127
|
+
**Config file**: `.vscode/mcp.json` in your project root (project-level) or user `settings.json` (global)
|
|
128
|
+
|
|
129
|
+
#### Project-level (`.vscode/mcp.json`)
|
|
130
|
+
|
|
131
|
+
```json
|
|
132
|
+
{
|
|
133
|
+
"servers": {
|
|
134
|
+
"hivemind": {
|
|
135
|
+
"command": "npx",
|
|
136
|
+
"args": ["-y", "hivemind-mcp"],
|
|
137
|
+
"env": {
|
|
138
|
+
"HIVEMIND_API_URL": "https://your-hivemind-server.com",
|
|
139
|
+
"HIVEMIND_API_KEY": "your-api-key"
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
#### Global (User `settings.json`)
|
|
147
|
+
|
|
148
|
+
```json
|
|
149
|
+
{
|
|
150
|
+
"mcp": {
|
|
151
|
+
"servers": {
|
|
152
|
+
"hivemind": {
|
|
153
|
+
"command": "npx",
|
|
154
|
+
"args": ["-y", "hivemind-mcp"],
|
|
155
|
+
"env": {
|
|
156
|
+
"HIVEMIND_API_URL": "https://your-hivemind-server.com",
|
|
157
|
+
"HIVEMIND_API_KEY": "your-api-key"
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
### Cline (VS Code Extension)
|
|
168
|
+
|
|
169
|
+
**Config file**: Cline's `cline_mcp_settings.json` (accessible via Cline → MCP Servers → Configure)
|
|
170
|
+
|
|
171
|
+
| OS | Path |
|
|
172
|
+
|----|------|
|
|
173
|
+
| macOS | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
|
|
174
|
+
| Windows | `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
|
|
175
|
+
| Linux | `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
|
|
176
|
+
|
|
177
|
+
```json
|
|
178
|
+
{
|
|
179
|
+
"mcpServers": {
|
|
180
|
+
"hivemind": {
|
|
181
|
+
"command": "npx",
|
|
182
|
+
"args": ["-y", "hivemind-mcp"],
|
|
183
|
+
"env": {
|
|
184
|
+
"HIVEMIND_API_URL": "https://your-hivemind-server.com",
|
|
185
|
+
"HIVEMIND_API_KEY": "your-api-key"
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
### Gemini CLI
|
|
195
|
+
|
|
196
|
+
**Config file**: `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project-level)
|
|
197
|
+
|
|
198
|
+
```json
|
|
199
|
+
{
|
|
200
|
+
"mcpServers": {
|
|
201
|
+
"hivemind": {
|
|
202
|
+
"command": "npx",
|
|
203
|
+
"args": ["-y", "hivemind-mcp"],
|
|
204
|
+
"env": {
|
|
205
|
+
"HIVEMIND_API_URL": "https://your-hivemind-server.com",
|
|
206
|
+
"HIVEMIND_API_KEY": "your-api-key"
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
---
|
|
214
|
+
|
|
215
|
+
### OpenAI Agents / ChatGPT
|
|
216
|
+
|
|
217
|
+
For OpenAI-compatible clients that support MCP via stdio:
|
|
218
|
+
|
|
219
|
+
```json
|
|
220
|
+
{
|
|
221
|
+
"mcpServers": {
|
|
222
|
+
"hivemind": {
|
|
223
|
+
"command": "npx",
|
|
224
|
+
"args": ["-y", "hivemind-mcp"],
|
|
225
|
+
"env": {
|
|
226
|
+
"HIVEMIND_API_URL": "https://your-hivemind-server.com",
|
|
227
|
+
"HIVEMIND_API_KEY": "your-api-key"
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
### Any MCP Client (Generic)
|
|
237
|
+
|
|
238
|
+
HiveMind MCP works with **any** MCP-compatible client. The pattern is always the same:
|
|
239
|
+
|
|
240
|
+
```
|
|
241
|
+
command: npx
|
|
242
|
+
args: ["-y", "hivemind-mcp"]
|
|
243
|
+
env:
|
|
244
|
+
HIVEMIND_API_URL: https://your-hivemind-server.com
|
|
245
|
+
HIVEMIND_API_KEY: your-api-key
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
---
|
|
249
|
+
|
|
250
|
+
## Deployment
|
|
251
|
+
|
|
252
|
+
### Local Development (stdio)
|
|
253
|
+
|
|
254
|
+
```bash
|
|
255
|
+
# Set env and run
|
|
256
|
+
export HIVEMIND_API_URL=http://localhost:8000
|
|
257
|
+
export HIVEMIND_API_KEY=dev-token
|
|
258
|
+
npx hivemind-mcp
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
### Remote / Cloud (HTTP transport)
|
|
262
|
+
|
|
263
|
+
For multi-client or cloud deployments, use the HTTP transport:
|
|
264
|
+
|
|
265
|
+
```bash
|
|
266
|
+
export HIVEMIND_API_URL=https://your-hivemind-api.com
|
|
267
|
+
export HIVEMIND_API_KEY=your-api-key
|
|
268
|
+
node dist/index.js --transport=http --port=3001
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Agents then connect to: `http://your-mcp-host:3001/mcp`
|
|
272
|
+
|
|
273
|
+
### Docker
|
|
274
|
+
|
|
275
|
+
```dockerfile
|
|
276
|
+
FROM node:22-alpine
|
|
277
|
+
RUN npm install -g hivemind-mcp
|
|
278
|
+
ENV HIVEMIND_API_URL=https://your-hivemind-api.com
|
|
279
|
+
ENV HIVEMIND_API_KEY=your-api-key
|
|
280
|
+
EXPOSE 3001
|
|
281
|
+
CMD ["hivemind-mcp", "--transport=http", "--port=3001"]
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
```bash
|
|
285
|
+
docker build -t hivemind-mcp .
|
|
286
|
+
docker run -p 3001:3001 \
|
|
287
|
+
-e HIVEMIND_API_URL=https://your-hivemind-api.com \
|
|
288
|
+
-e HIVEMIND_API_KEY=your-api-key \
|
|
289
|
+
hivemind-mcp
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
### Docker Compose
|
|
293
|
+
|
|
294
|
+
```yaml
|
|
295
|
+
services:
|
|
296
|
+
hivemind-mcp:
|
|
297
|
+
image: node:22-alpine
|
|
298
|
+
command: sh -c "npm install -g hivemind-mcp && hivemind-mcp --transport=http --port=3001"
|
|
299
|
+
ports:
|
|
300
|
+
- "3001:3001"
|
|
301
|
+
environment:
|
|
302
|
+
HIVEMIND_API_URL: https://your-hivemind-api.com
|
|
303
|
+
HIVEMIND_API_KEY: ${HIVEMIND_API_KEY}
|
|
304
|
+
restart: unless-stopped
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
---
|
|
308
|
+
|
|
309
|
+
## Tools
|
|
310
|
+
|
|
311
|
+
| Tool | Description |
|
|
312
|
+
|------|-------------|
|
|
313
|
+
| `hivemind_query` | Search the shared knowledge graph for proven instructions, warnings, and disputed pairs |
|
|
314
|
+
| `hivemind_write_instruction` | Share a working approach with all future AI agents |
|
|
315
|
+
| `hivemind_write_mistake` | Warn about a failed approach — mistakes are never deleted |
|
|
316
|
+
| `hivemind_write_update` | Share a factual change (version updates, deprecations, breaking changes) |
|
|
317
|
+
| `hivemind_inspect` | Inspect a memory's full state, evolution scores, and version history |
|
|
318
|
+
|
|
319
|
+
## Resources
|
|
320
|
+
|
|
321
|
+
| URI | Description |
|
|
322
|
+
|-----|-------------|
|
|
323
|
+
| `hivemind://status` | System health, graph connectivity, and memory counts |
|
|
324
|
+
| `hivemind://guide` | Agent onboarding guide — the evolution loop, when to use each tool |
|
|
325
|
+
|
|
326
|
+
## Prompts
|
|
327
|
+
|
|
328
|
+
| Prompt | Description |
|
|
329
|
+
|--------|-------------|
|
|
330
|
+
| `learn_and_share` | Guided workflow: query → try → write → verify |
|
|
331
|
+
| `review_memory` | Memory evaluation: inspect → assess accuracy → correct/supersede |
|
|
332
|
+
|
|
333
|
+
---
|
|
334
|
+
|
|
335
|
+
## Architecture
|
|
336
|
+
|
|
337
|
+
```
|
|
338
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
339
|
+
│ AI AGENTS (Any MCP Client) │
|
|
340
|
+
│ Claude · GPT · Gemini · Cursor · Windsurf · Cline │
|
|
341
|
+
└───────────────────────────┬─────────────────────────────────┘
|
|
342
|
+
│ MCP Protocol (stdio or http)
|
|
343
|
+
▼
|
|
344
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
345
|
+
│ HIVEMIND MCP SERVER (TypeScript) │
|
|
346
|
+
│ │
|
|
347
|
+
│ 5 Tools · 2 Resources · 2 Prompts │
|
|
348
|
+
│ │ │
|
|
349
|
+
│ ┌──────────▼──────────┐ │
|
|
350
|
+
│ │ REST Client │ Authorization: Bearer │
|
|
351
|
+
│ └──────────┬──────────┘ │
|
|
352
|
+
└─────────────────────┼───────────────────────────────────────┘
|
|
353
|
+
│ HTTP + Bearer token
|
|
354
|
+
▼
|
|
355
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
356
|
+
│ HIVEMIND REST API (Python/FastAPI) │
|
|
357
|
+
│ │ │
|
|
358
|
+
│ ┌───────────▼────────────┐ │
|
|
359
|
+
│ │ FalkorDB + Redis │ │
|
|
360
|
+
│ │ (Graph + Vectors) │ │
|
|
361
|
+
│ └────────────────────────┘ │
|
|
362
|
+
└─────────────────────────────────────────────────────────────┘
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
The MCP server is a **thin stateless wrapper**. All business logic lives in the Python REST API.
|
|
366
|
+
|
|
367
|
+
---
|
|
368
|
+
|
|
369
|
+
## Development
|
|
370
|
+
|
|
371
|
+
```bash
|
|
372
|
+
# Watch mode (auto-reload on changes)
|
|
373
|
+
npm run dev
|
|
374
|
+
|
|
375
|
+
# Build TypeScript → dist/
|
|
376
|
+
npm run build
|
|
377
|
+
|
|
378
|
+
# Test with MCP Inspector
|
|
379
|
+
npx @modelcontextprotocol/inspector node dist/index.js
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
## Publishing to npm
|
|
383
|
+
|
|
384
|
+
```bash
|
|
385
|
+
# Build + publish (prepublishOnly auto-runs tsc)
|
|
386
|
+
npm publish
|
|
387
|
+
|
|
388
|
+
# Users can then run:
|
|
389
|
+
npx -y hivemind-mcp
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
---
|
|
393
|
+
|
|
394
|
+
## License
|
|
395
|
+
|
|
396
|
+
MIT
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* HiveMind REST Client
|
|
3
|
+
*
|
|
4
|
+
* Thin fetch-based client for the HiveMind FastAPI core.
|
|
5
|
+
* Uses native fetch (Node 18+) with AbortController timeouts
|
|
6
|
+
* and single-retry for transient failures.
|
|
7
|
+
*/
|
|
8
|
+
import type { QueryParams, QueryResult, WriteParams, WriteResult, MemoryDetail, HealthStatus, MemoryListParams, MemoryListResult } from "./types.js";
|
|
9
|
+
export declare class HiveMindRestClient {
|
|
10
|
+
private readonly baseUrl;
|
|
11
|
+
private readonly timeout;
|
|
12
|
+
private readonly apiKey;
|
|
13
|
+
constructor(baseUrl?: string, timeout?: number, apiKey?: string);
|
|
14
|
+
query(params: QueryParams): Promise<QueryResult>;
|
|
15
|
+
writeMemory(params: WriteParams): Promise<WriteResult>;
|
|
16
|
+
getMemory(memoryId: string): Promise<MemoryDetail>;
|
|
17
|
+
getHealth(): Promise<HealthStatus>;
|
|
18
|
+
listMemories(params?: MemoryListParams): Promise<MemoryListResult>;
|
|
19
|
+
private buildHeaders;
|
|
20
|
+
private post;
|
|
21
|
+
private get;
|
|
22
|
+
private handleResponse;
|
|
23
|
+
private requestWithRetry;
|
|
24
|
+
private isRetryableError;
|
|
25
|
+
private normalizeError;
|
|
26
|
+
}
|
|
27
|
+
/** Singleton REST client instance */
|
|
28
|
+
export declare const restClient: HiveMindRestClient;
|
|
29
|
+
//# sourceMappingURL=restClient.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"restClient.d.ts","sourceRoot":"","sources":["../../src/client/restClient.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACR,WAAW,EACX,WAAW,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EACnB,MAAM,YAAY,CAAC;AAEpB,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;gBAEhC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAQzD,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAIhD,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAItD,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIlD,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC;IAIlC,YAAY,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAaxE,OAAO,CAAC,YAAY;YAaN,IAAI;YAYJ,GAAG;YAUH,cAAc;YAed,gBAAgB;IA+B9B,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,cAAc;CAczB;AAED,qCAAqC;AACrC,eAAO,MAAM,UAAU,oBAA2B,CAAC"}
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* HiveMind REST Client
|
|
3
|
+
*
|
|
4
|
+
* Thin fetch-based client for the HiveMind FastAPI core.
|
|
5
|
+
* Uses native fetch (Node 18+) with AbortController timeouts
|
|
6
|
+
* and single-retry for transient failures.
|
|
7
|
+
*/
|
|
8
|
+
import { config } from "../config.js";
|
|
9
|
+
export class HiveMindRestClient {
|
|
10
|
+
baseUrl;
|
|
11
|
+
timeout;
|
|
12
|
+
apiKey;
|
|
13
|
+
constructor(baseUrl, timeout, apiKey) {
|
|
14
|
+
this.baseUrl = (baseUrl ?? config.apiUrl).replace(/\/+$/, "");
|
|
15
|
+
this.timeout = timeout ?? config.timeout;
|
|
16
|
+
this.apiKey = apiKey ?? config.apiKey;
|
|
17
|
+
}
|
|
18
|
+
// ── Public API ──────────────────────────────────────────────────
|
|
19
|
+
async query(params) {
|
|
20
|
+
return this.post("/v1/query", params);
|
|
21
|
+
}
|
|
22
|
+
async writeMemory(params) {
|
|
23
|
+
return this.post("/v1/memories", params);
|
|
24
|
+
}
|
|
25
|
+
async getMemory(memoryId) {
|
|
26
|
+
return this.get(`/v1/memories/${encodeURIComponent(memoryId)}`);
|
|
27
|
+
}
|
|
28
|
+
async getHealth() {
|
|
29
|
+
return this.get("/health");
|
|
30
|
+
}
|
|
31
|
+
async listMemories(params) {
|
|
32
|
+
const query = new URLSearchParams();
|
|
33
|
+
if (params?.status_filter)
|
|
34
|
+
query.set("status_filter", params.status_filter);
|
|
35
|
+
if (params?.type_filter)
|
|
36
|
+
query.set("type_filter", params.type_filter);
|
|
37
|
+
if (params?.agent_id)
|
|
38
|
+
query.set("agent_id", params.agent_id);
|
|
39
|
+
if (params?.limit !== undefined)
|
|
40
|
+
query.set("limit", String(params.limit));
|
|
41
|
+
const qs = query.toString();
|
|
42
|
+
return this.get(`/v1/memories${qs ? `?${qs}` : ""}`);
|
|
43
|
+
}
|
|
44
|
+
// ── Shared headers ──────────────────────────────────────────────
|
|
45
|
+
buildHeaders(contentType) {
|
|
46
|
+
const headers = {};
|
|
47
|
+
if (contentType) {
|
|
48
|
+
headers["Content-Type"] = contentType;
|
|
49
|
+
}
|
|
50
|
+
if (this.apiKey) {
|
|
51
|
+
headers["Authorization"] = `Bearer ${this.apiKey}`;
|
|
52
|
+
}
|
|
53
|
+
return headers;
|
|
54
|
+
}
|
|
55
|
+
// ── HTTP helpers with retry ─────────────────────────────────────
|
|
56
|
+
async post(path, body) {
|
|
57
|
+
return this.requestWithRetry(async (signal) => {
|
|
58
|
+
const response = await fetch(`${this.baseUrl}${path}`, {
|
|
59
|
+
method: "POST",
|
|
60
|
+
headers: this.buildHeaders("application/json"),
|
|
61
|
+
body: JSON.stringify(body),
|
|
62
|
+
signal,
|
|
63
|
+
});
|
|
64
|
+
return this.handleResponse(response);
|
|
65
|
+
});
|
|
66
|
+
}
|
|
67
|
+
async get(path) {
|
|
68
|
+
return this.requestWithRetry(async (signal) => {
|
|
69
|
+
const response = await fetch(`${this.baseUrl}${path}`, {
|
|
70
|
+
headers: this.buildHeaders(),
|
|
71
|
+
signal,
|
|
72
|
+
});
|
|
73
|
+
return this.handleResponse(response);
|
|
74
|
+
});
|
|
75
|
+
}
|
|
76
|
+
async handleResponse(response) {
|
|
77
|
+
if (!response.ok) {
|
|
78
|
+
const errorBody = await response.text().catch(() => "");
|
|
79
|
+
const message = errorBody || response.statusText;
|
|
80
|
+
const err = new Error(`REST API error (${response.status}): ${message}`);
|
|
81
|
+
err.statusCode = response.status;
|
|
82
|
+
err.body = errorBody;
|
|
83
|
+
throw err;
|
|
84
|
+
}
|
|
85
|
+
return (await response.json());
|
|
86
|
+
}
|
|
87
|
+
async requestWithRetry(fn, retries = 1) {
|
|
88
|
+
for (let attempt = 0; attempt <= retries; attempt++) {
|
|
89
|
+
const controller = new AbortController();
|
|
90
|
+
const timeoutId = setTimeout(() => controller.abort(), this.timeout);
|
|
91
|
+
try {
|
|
92
|
+
const result = await fn(controller.signal);
|
|
93
|
+
return result;
|
|
94
|
+
}
|
|
95
|
+
catch (error) {
|
|
96
|
+
const isLastAttempt = attempt === retries;
|
|
97
|
+
const isRetryable = this.isRetryableError(error);
|
|
98
|
+
if (isLastAttempt || !isRetryable) {
|
|
99
|
+
throw this.normalizeError(error);
|
|
100
|
+
}
|
|
101
|
+
// Exponential backoff: 500ms, 1000ms, ...
|
|
102
|
+
const delay = 500 * Math.pow(2, attempt);
|
|
103
|
+
await new Promise((resolve) => setTimeout(resolve, delay));
|
|
104
|
+
}
|
|
105
|
+
finally {
|
|
106
|
+
clearTimeout(timeoutId);
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
// Unreachable but TypeScript needs it
|
|
110
|
+
throw new Error("Request failed after retries");
|
|
111
|
+
}
|
|
112
|
+
isRetryableError(error) {
|
|
113
|
+
if (error instanceof DOMException && error.name === "AbortError")
|
|
114
|
+
return true;
|
|
115
|
+
if (error instanceof TypeError && error.message.includes("fetch"))
|
|
116
|
+
return true;
|
|
117
|
+
const statusCode = error.statusCode;
|
|
118
|
+
return statusCode !== undefined && statusCode >= 500;
|
|
119
|
+
}
|
|
120
|
+
normalizeError(error) {
|
|
121
|
+
if (error instanceof DOMException && error.name === "AbortError") {
|
|
122
|
+
return new Error(`Request timed out after ${this.timeout}ms. Is HiveMind API running at ${this.baseUrl}?`);
|
|
123
|
+
}
|
|
124
|
+
if (error instanceof TypeError && error.message.includes("fetch")) {
|
|
125
|
+
return new Error(`Cannot connect to HiveMind API at ${this.baseUrl}. Is the server running?`);
|
|
126
|
+
}
|
|
127
|
+
if (error instanceof Error)
|
|
128
|
+
return error;
|
|
129
|
+
return new Error(String(error));
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
/** Singleton REST client instance */
|
|
133
|
+
export const restClient = new HiveMindRestClient();
|
|
134
|
+
//# sourceMappingURL=restClient.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"restClient.js","sourceRoot":"","sources":["../../src/client/restClient.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAYtC,MAAM,OAAO,kBAAkB;IACV,OAAO,CAAS;IAChB,OAAO,CAAS;IAChB,MAAM,CAAqB;IAE5C,YAAY,OAAgB,EAAE,OAAgB,EAAE,MAAe;QAC3D,IAAI,CAAC,OAAO,GAAG,CAAC,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,OAAO,GAAG,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC;QACzC,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC;IAC1C,CAAC;IAED,mEAAmE;IAEnE,KAAK,CAAC,KAAK,CAAC,MAAmB;QAC3B,OAAO,IAAI,CAAC,IAAI,CAAc,WAAW,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,MAAmB;QACjC,OAAO,IAAI,CAAC,IAAI,CAAc,cAAc,EAAE,MAAM,CAAC,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,QAAgB;QAC5B,OAAO,IAAI,CAAC,GAAG,CAAe,gBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,KAAK,CAAC,SAAS;QACX,OAAO,IAAI,CAAC,GAAG,CAAe,SAAS,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,MAAyB;QACxC,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;QACpC,IAAI,MAAM,EAAE,aAAa;YAAE,KAAK,CAAC,GAAG,CAAC,eAAe,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;QAC5E,IAAI,MAAM,EAAE,WAAW;YAAE,KAAK,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;QACtE,IAAI,MAAM,EAAE,QAAQ;YAAE,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC7D,IAAI,MAAM,EAAE,KAAK,KAAK,SAAS;YAAE,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAE1E,MAAM,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC,GAAG,CAAmB,eAAe,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,mEAAmE;IAE3D,YAAY,CAAC,WAAoB;QACrC,MAAM,OAAO,GAA2B,EAAE,CAAC;QAC3C,IAAI,WAAW,EAAE,CAAC;YACd,OAAO,CAAC,cAAc,CAAC,GAAG,WAAW,CAAC;QAC1C,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,IAAI,CAAC,MAAM,EAAE,CAAC;QACvD,CAAC;QACD,OAAO,OAAO,CAAC;IACnB,CAAC;IAED,mEAAmE;IAE3D,KAAK,CAAC,IAAI,CAAI,IAAY,EAAE,IAAa;QAC7C,OAAO,IAAI,CAAC,gBAAgB,CAAI,KAAK,EAAE,MAAM,EAAE,EAAE;YAC7C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;gBACnD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC,kBAAkB,CAAC;gBAC9C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;gBAC1B,MAAM;aACT,CAAC,CAAC;YACH,OAAO,IAAI,CAAC,cAAc,CAAI,QAAQ,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;IACP,CAAC;IAEO,KAAK,CAAC,GAAG,CAAI,IAAY;QAC7B,OAAO,IAAI,CAAC,gBAAgB,CAAI,KAAK,EAAE,MAAM,EAAE,EAAE;YAC7C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;gBACnD,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE;gBAC5B,MAAM;aACT,CAAC,CAAC;YACH,OAAO,IAAI,CAAC,cAAc,CAAI,QAAQ,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;IACP,CAAC;IAEO,KAAK,CAAC,cAAc,CAAI,QAAkB;QAC9C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACf,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACxD,MAAM,OAAO,GAAG,SAAS,IAAI,QAAQ,CAAC,UAAU,CAAC;YACjD,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,mBAAmB,QAAQ,CAAC,MAAM,MAAM,OAAO,EAAE,CAGtE,CAAC;YACF,GAAG,CAAC,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC;YACjC,GAAG,CAAC,IAAI,GAAG,SAAS,CAAC;YACrB,MAAM,GAAG,CAAC;QACd,CAAC;QACD,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAM,CAAC;IACxC,CAAC;IAEO,KAAK,CAAC,gBAAgB,CAC1B,EAAuC,EACvC,OAAO,GAAG,CAAC;QAEX,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;YAClD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;YAErE,IAAI,CAAC;gBACD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;gBAC3C,OAAO,MAAM,CAAC;YAClB,CAAC;YAAC,OAAO,KAAc,EAAE,CAAC;gBACtB,MAAM,aAAa,GAAG,OAAO,KAAK,OAAO,CAAC;gBAC1C,MAAM,WAAW,GAAG,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;gBAEjD,IAAI,aAAa,IAAI,CAAC,WAAW,EAAE,CAAC;oBAChC,MAAM,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;gBACrC,CAAC;gBAED,0CAA0C;gBAC1C,MAAM,KAAK,GAAG,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;gBACzC,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;YAC/D,CAAC;oBAAS,CAAC;gBACP,YAAY,CAAC,SAAS,CAAC,CAAC;YAC5B,CAAC;QACL,CAAC;QAED,sCAAsC;QACtC,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACpD,CAAC;IAEO,gBAAgB,CAAC,KAAc;QACnC,IAAI,KAAK,YAAY,YAAY,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY;YAAE,OAAO,IAAI,CAAC;QAC9E,IAAI,KAAK,YAAY,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QAC/E,MAAM,UAAU,GAAI,KAAiC,CAAC,UAAU,CAAC;QACjE,OAAO,UAAU,KAAK,SAAS,IAAI,UAAU,IAAI,GAAG,CAAC;IACzD,CAAC;IAEO,cAAc,CAAC,KAAc;QACjC,IAAI,KAAK,YAAY,YAAY,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAC/D,OAAO,IAAI,KAAK,CACZ,2BAA2B,IAAI,CAAC,OAAO,kCAAkC,IAAI,CAAC,OAAO,GAAG,CAC3F,CAAC;QACN,CAAC;QACD,IAAI,KAAK,YAAY,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAChE,OAAO,IAAI,KAAK,CACZ,qCAAqC,IAAI,CAAC,OAAO,0BAA0B,CAC9E,CAAC;QACN,CAAC;QACD,IAAI,KAAK,YAAY,KAAK;YAAE,OAAO,KAAK,CAAC;QACzC,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACpC,CAAC;CACJ;AAED,qCAAqC;AACrC,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,kBAAkB,EAAE,CAAC"}
|