@contextstream/mcp-server 0.4.2 → 0.4.4

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 (3) hide show
  1. package/README.md +195 -183
  2. package/dist/index.js +172 -228
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,113 +1,149 @@
1
1
  # ContextStream MCP Server
2
2
 
3
- Persistent memory, semantic search, and code intelligence for any MCP-compatible AI tool.
3
+ Persistent memory, semantic search, and code intelligence for any MCP-compatible AI tool (Cursor, Claude Code, Windsurf, VS Code, Claude Desktop, Codex CLI, etc.).
4
4
 
5
- ContextStream is a shared "brain" for your AI workflows. It stores decisions, preferences, and lessons, and lets your AI tools search and analyze your codebase with consistent context across sessions.
5
+ ContextStream is a shared "brain" for AI-assisted development. It stores decisions, preferences, lessons, tasks, and project context — and lets your AI tools search and analyze your codebase with consistent context across sessions.
6
6
 
7
- ## Just Ask
7
+ **v0.4.x:** Consolidated domain tools (~11 tools) for **~75% lower tool-registry token overhead** vs previous versions.
8
+
9
+ ---
8
10
 
9
- **You don't need to memorize tool names.** Just describe what you want and your AI uses the right ContextStream tools automatically:
11
+ ## Just Ask
10
12
 
11
- | You say... | ContextStream does... |
12
- |------------|----------------------|
13
- | "session summary" | Gets a summary of your workspace context |
14
- | "what did we decide about auth?" | Recalls past decisions about authentication |
15
- | "remember we're using PostgreSQL" | Saves this to memory for future sessions |
16
- | "search for payment code" | Searches your codebase semantically |
17
- | "what depends on UserService?" | Analyzes code dependencies |
13
+ **You don't need to memorize tool names.** Describe what you want and your AI will call the right ContextStream tools:
18
14
 
19
- No special syntax. No commands to learn. Just ask.
15
+ | You say… | ContextStream does… |
16
+ |----------|---------------------|
17
+ | "session summary" | Summarizes current workspace/project context |
18
+ | "what did we decide about auth?" | Recalls decisions related to authentication |
19
+ | "remember we're using PostgreSQL" | Captures that fact for future sessions |
20
+ | "search for payment code" | Searches your codebase semantically/hybrid/keyword |
21
+ | "what depends on UserService?" | Analyzes dependency graph & impact |
20
22
 
21
- > **Tip:** For best results, add the [recommended editor rules](https://contextstream.io/docs/quickstart) so your AI consistently calls `session_init` / `context_smart` automatically.
23
+ > **Tip:** For best results, add the **recommended editor rules** so your AI reliably calls `session_init` / `context_smart` when appropriate:
24
+ > https://contextstream.io/docs/quickstart
22
25
 
23
26
  ![ContextStream in action](compare1.gif)
24
27
 
28
+ ---
29
+
30
+ ## Choose Your Mode (Token Footprint)
31
+
32
+ MCP clients often inject the tool catalog into the model context. v0.4.x is designed to keep that overhead small.
33
+
34
+ | Mode | What it exposes | Best for | Enable |
35
+ |------|-----------------|----------|--------|
36
+ | **Consolidated** (default) | ~11 domain tools with `action` / `mode` dispatch | Most users (recommended) | `CONTEXTSTREAM_CONSOLIDATED=true` |
37
+ | **Router** (extreme minimization) | ~2 meta-tools (`contextstream`, `contextstream_help`) | Tight context budgets / many MCP servers | `CONTEXTSTREAM_PROGRESSIVE_MODE=true` |
38
+ | **Legacy** (granular tools) | Older `light/standard/complete` toolsets | Back-compat / old prompts | `CONTEXTSTREAM_CONSOLIDATED=false` |
39
+
40
+ > **Note:** The env var name for Router mode is `CONTEXTSTREAM_PROGRESSIVE_MODE` (historical naming). It enables the ~2-tool "router" surface.
41
+
42
+ ---
43
+
25
44
  ## Features
26
45
 
46
+ - **Consolidated domain tools** (v0.4.x): short tool list with action/mode dispatch
27
47
  - Session-aware context loading (`session_init`, `context_smart`)
28
- - Memory capture and recall (decisions, preferences, tasks, bugs, lessons)
48
+ - Memory capture + recall (decisions, preferences, lessons, tasks, bugs)
29
49
  - Code search (semantic, hybrid, keyword, pattern)
30
- - Knowledge graph and code analysis (dependencies, impact, call paths, circular deps, unused code)
31
- - Graph ingestion for full graph builds (`graph_ingest`)
32
- - Local repo ingestion for indexing (`projects_ingest_local`)
33
- - Auto-context: on the first tool call in a new session, the server can auto-initialize context
50
+ - Knowledge graph + code analysis (dependencies, impact, call paths, circular deps, unused code)
51
+ - Graph ingestion for full graph builds (`graph(action="ingest")`)
52
+ - Local repo ingestion for indexing (`project(action="ingest_local")`)
53
+ - Auto-context: on first tool call in a new session, the server can auto-initialize context
34
54
 
35
- ## Graph tiers
55
+ ---
36
56
 
37
- - **Pro (Graph-Lite):** module-level import graph, dependencies, and 1-hop impact
38
- - **Elite/Team (Full Graph):** module + call + dataflow + type layers, plus `graph_ingest`
57
+ ## Graph Tiers
58
+
59
+ | Tier | Capabilities |
60
+ |------|--------------|
61
+ | **Pro (Graph-Lite)** | Module-level import graph, dependencies, and 1-hop impact |
62
+ | **Elite/Team (Full Graph)** | Module + call + dataflow + type layers, plus full graph ingestion |
63
+
64
+ ---
39
65
 
40
66
  ## Requirements
41
67
 
42
- - Node.js 18+
43
- - A ContextStream account and either an API key or a JWT
68
+ - **Node.js 18+**
69
+ - A **ContextStream account**
70
+ - Auth via **API key** or **JWT**
71
+
72
+ Default API URL: `https://api.contextstream.io`
73
+
74
+ ---
44
75
 
45
- ## Quickstart
76
+ ## Quickstart (2 minutes)
46
77
 
47
- ### Setup wizard (recommended)
78
+ ### 1) Run the Setup Wizard (recommended)
48
79
 
49
- This interactive wizard sets up authentication, installs editor rules, and writes MCP config files for the tools you select.
80
+ The wizard:
81
+ - Authenticates (browser/device login by default)
82
+ - Creates/stores an API key
83
+ - Installs recommended editor rules (optional)
84
+ - Writes MCP config files for supported tools
50
85
 
51
86
  ```bash
52
87
  npx -y @contextstream/mcp-server setup
53
88
  ```
54
89
 
55
- Notes:
56
- - Uses browser/device login by default and creates an API key for you.
57
- - Prompts for **toolset selection**: `light` (~30 tools), `standard` (default, ~50 tools), or `complete` (~86 tools including workspaces, projects, search, memory, graph, AI, and integrations).
58
- - To avoid re-auth prompts on subsequent runs, the wizard saves that API key to `~/.contextstream/credentials.json` (and also writes it into the MCP config files it generates). Delete that file to force a fresh login.
59
- - Codex CLI MCP config is global-only (`~/.codex/config.toml`), so the wizard will always write Codex config globally when selected.
60
- - Some tools still require UI/CLI-based MCP setup (the wizard will tell you when it can't write a config).
61
- - Preview changes without writing files: `npx -y @contextstream/mcp-server setup --dry-run`
90
+ **Useful flags:**
62
91
 
63
- ### Run the server
92
+ | Flag | Description |
93
+ |------|-------------|
94
+ | `--dry-run` | Preview without writing files |
64
95
 
65
- Run directly (recommended for MCP configs):
96
+ **Notes:**
97
+ - The wizard stores credentials at `~/.contextstream/credentials.json` for convenience. Delete it to force a fresh login.
98
+ - Codex CLI MCP config is global-only (`~/.codex/config.toml`), so the wizard writes Codex config globally when selected.
99
+ - Some tools still require UI/CLI setup (the wizard will tell you when it can't write a config).
100
+
101
+ ### 2) Run the MCP Server
102
+
103
+ **Recommended** (works well with MCP configs):
66
104
 
67
105
  ```bash
68
106
  npx -y @contextstream/mcp-server
69
107
  ```
70
108
 
71
- Or install globally:
109
+ **Or install globally:**
72
110
 
73
111
  ```bash
74
112
  npm install -g @contextstream/mcp-server
75
113
  contextstream-mcp
76
114
  ```
77
115
 
78
- ### Keeping updated
116
+ ### 3) Keeping Updated
79
117
 
80
- To get the latest features and bug fixes, update periodically:
118
+ **If you use `npx`:** Restart your AI tool/editor and run ContextStream again
119
+ (or pin the version: `npx -y @contextstream/mcp-server@0.4.3`)
120
+
121
+ **If you installed globally:**
81
122
 
82
123
  ```bash
83
124
  npm update -g @contextstream/mcp-server
84
125
  ```
85
126
 
86
- The MCP server will warn you when a newer version is available. After updating, restart your AI tool to use the new version.
87
-
88
- ## Configure your MCP client
127
+ After updating, restart your AI tool/editor so it reloads the tool catalog.
89
128
 
90
- ### Manual setup
129
+ ---
91
130
 
92
- If you ran the [setup wizard](#setup-wizard-recommended), you can usually skip this section.
131
+ ## Configure Your MCP Client (Manual)
93
132
 
94
- If you prefer to configure things by hand (or your tool can't be auto-configured), add the ContextStream MCP server to your client using one of the examples below.
95
-
96
- **Toolset**: By default, the server exposes the `standard` toolset (~50 tools). Use `CONTEXTSTREAM_TOOLSET=light` to reduce tool count (~30 tools), or `CONTEXTSTREAM_TOOLSET=complete` to expose all ~86 tools (workspaces, projects, search, memory, graph, AI, integrations). See the [full tool catalog](https://contextstream.io/docs/mcp/tools).
133
+ > If you ran the setup wizard, you can usually skip this.
97
134
 
98
135
  ### Cursor / Windsurf / Claude Desktop (JSON)
99
136
 
100
- These clients use the `mcpServers` JSON schema:
101
-
102
- - Cursor: `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project)
103
- - Windsurf: `~/.codeium/windsurf/mcp_config.json`
104
- - Claude Desktop:
105
- - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
106
- - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`
137
+ These clients use an `mcpServers` JSON config:
107
138
 
108
- Many other MCP JSON clients also use this same `mcpServers` shape (including Claude Code project scope via `.mcp.json`).
139
+ | Client | Config path |
140
+ |--------|-------------|
141
+ | **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) |
142
+ | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
143
+ | **Claude Desktop (macOS)** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
144
+ | **Claude Desktop (Windows)** | `%APPDATA%\Claude\claude_desktop_config.json` |
109
145
 
110
- **Standard toolset (default, ~50 tools):**
146
+ **Consolidated (default):**
111
147
 
112
148
  ```json
113
149
  {
@@ -117,14 +153,14 @@ Many other MCP JSON clients also use this same `mcpServers` shape (including Cla
117
153
  "args": ["-y", "@contextstream/mcp-server"],
118
154
  "env": {
119
155
  "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
120
- "CONTEXTSTREAM_API_KEY": "your_api_key"
156
+ "CONTEXTSTREAM_API_KEY": "YOUR_API_KEY"
121
157
  }
122
158
  }
123
159
  }
124
160
  }
125
161
  ```
126
162
 
127
- **Complete toolset (~86 tools):**
163
+ **Router mode (~2 meta-tools):**
128
164
 
129
165
  ```json
130
166
  {
@@ -134,8 +170,8 @@ Many other MCP JSON clients also use this same `mcpServers` shape (including Cla
134
170
  "args": ["-y", "@contextstream/mcp-server"],
135
171
  "env": {
136
172
  "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
137
- "CONTEXTSTREAM_API_KEY": "your_api_key",
138
- "CONTEXTSTREAM_TOOLSET": "complete"
173
+ "CONTEXTSTREAM_API_KEY": "YOUR_API_KEY",
174
+ "CONTEXTSTREAM_PROGRESSIVE_MODE": "true"
139
175
  }
140
176
  }
141
177
  }
@@ -144,27 +180,7 @@ Many other MCP JSON clients also use this same `mcpServers` shape (including Cla
144
180
 
145
181
  ### VS Code (`.vscode/mcp.json`)
146
182
 
147
- VS Code uses a different schema with a top-level `servers` map:
148
-
149
- **Core toolset (default):**
150
-
151
- ```json
152
- {
153
- "servers": {
154
- "contextstream": {
155
- "type": "stdio",
156
- "command": "npx",
157
- "args": ["-y", "@contextstream/mcp-server"],
158
- "env": {
159
- "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
160
- "CONTEXTSTREAM_API_KEY": "your_api_key"
161
- }
162
- }
163
- }
164
- }
165
- ```
166
-
167
- **Complete toolset (~86 tools):**
183
+ VS Code uses a top-level `servers` map:
168
184
 
169
185
  ```json
170
186
  {
@@ -175,15 +191,14 @@ VS Code uses a different schema with a top-level `servers` map:
175
191
  "args": ["-y", "@contextstream/mcp-server"],
176
192
  "env": {
177
193
  "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
178
- "CONTEXTSTREAM_API_KEY": "your_api_key",
179
- "CONTEXTSTREAM_TOOLSET": "complete"
194
+ "CONTEXTSTREAM_API_KEY": "YOUR_API_KEY"
180
195
  }
181
196
  }
182
197
  }
183
198
  }
184
199
  ```
185
200
 
186
- Strong recommendation: VS Code supports `inputs` so you don’t have to hardcode secrets in a committed file:
201
+ **Strong recommendation:** Use `inputs` so you don't commit secrets:
187
202
 
188
203
  ```json
189
204
  {
@@ -211,9 +226,7 @@ Strong recommendation: VS Code supports `inputs` so you don’t have to hardcode
211
226
 
212
227
  ### Claude Code (CLI)
213
228
 
214
- User scope (all projects):
215
-
216
- **Standard toolset (default):**
229
+ **User scope (all projects):**
217
230
 
218
231
  ```bash
219
232
  claude mcp add --transport stdio contextstream --scope user \
@@ -222,38 +235,20 @@ claude mcp add --transport stdio contextstream --scope user \
222
235
  -- npx -y @contextstream/mcp-server
223
236
  ```
224
237
 
225
- **Complete toolset (~86 tools):**
238
+ **Router mode:**
226
239
 
227
240
  ```bash
228
241
  claude mcp add --transport stdio contextstream --scope user \
229
242
  --env CONTEXTSTREAM_API_URL=https://api.contextstream.io \
230
243
  --env CONTEXTSTREAM_API_KEY=YOUR_KEY \
231
- --env CONTEXTSTREAM_TOOLSET=complete \
244
+ --env CONTEXTSTREAM_PROGRESSIVE_MODE=true \
232
245
  -- npx -y @contextstream/mcp-server
233
246
  ```
234
247
 
235
- Note: Claude Code may warn about large tool contexts when using `complete`. The default is `standard` (~50 tools). Use `light` for fewer tools.
236
-
237
- Windows caveat (native Windows, not WSL): if `npx` isn't found, use `cmd /c npx -y @contextstream/mcp-server` after `--`.
238
-
239
- **Alternative (JSON form):**
240
-
241
- Standard:
242
- ```bash
243
- claude mcp add-json contextstream \
244
- '{"type":"stdio","command":"npx","args":["-y","@contextstream/mcp-server"],"env":{"CONTEXTSTREAM_API_URL":"https://api.contextstream.io","CONTEXTSTREAM_API_KEY":"your_api_key"}}'
245
- ```
246
-
247
- Complete:
248
- ```bash
249
- claude mcp add-json contextstream \
250
- '{"type":"stdio","command":"npx","args":["-y","@contextstream/mcp-server"],"env":{"CONTEXTSTREAM_API_URL":"https://api.contextstream.io","CONTEXTSTREAM_API_KEY":"your_api_key","CONTEXTSTREAM_TOOLSET":"complete"}}'
251
- ```
248
+ > **Windows caveat** (native Windows, not WSL): if `npx` isn't found, use `cmd /c npx -y @contextstream/mcp-server` after `--`.
252
249
 
253
250
  ### Codex CLI (`~/.codex/config.toml`)
254
251
 
255
- **Standard toolset (default):**
256
-
257
252
  ```toml
258
253
  [mcp_servers.contextstream]
259
254
  command = "npx"
@@ -261,110 +256,120 @@ args = ["-y", "@contextstream/mcp-server"]
261
256
 
262
257
  [mcp_servers.contextstream.env]
263
258
  CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
264
- CONTEXTSTREAM_API_KEY = "your_api_key"
259
+ CONTEXTSTREAM_API_KEY = "YOUR_API_KEY"
265
260
  ```
266
261
 
267
- **Complete toolset (~86 tools):**
262
+ ---
268
263
 
269
- ```toml
270
- [mcp_servers.contextstream]
271
- command = "npx"
272
- args = ["-y", "@contextstream/mcp-server"]
264
+ ## Tool Overview (v0.4.x Consolidated)
273
265
 
274
- [mcp_servers.contextstream.env]
275
- CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
276
- CONTEXTSTREAM_API_KEY = "your_api_key"
277
- CONTEXTSTREAM_TOOLSET = "complete"
278
- ```
266
+ In consolidated mode, you call **domain tools** with `action` / `mode`:
279
267
 
280
- After editing, restart your MCP client so it reloads the server configuration.
268
+ ### Core
281
269
 
282
- ## Authentication
270
+ | Tool | Description |
271
+ |------|-------------|
272
+ | `session_init` | Initialize workspace/project context |
273
+ | `context_smart` | Retrieve the best bounded context for the current message |
283
274
 
284
- You can authenticate using either:
275
+ ### Domain Tools
285
276
 
286
- - `CONTEXTSTREAM_API_KEY` (recommended for local/dev)
287
- - `CONTEXTSTREAM_JWT` (useful for hosted or user-session flows)
277
+ | Tool | Description |
278
+ |------|-------------|
279
+ | `search` | `mode=semantic\|hybrid\|keyword\|pattern` |
280
+ | `session` | `action=capture\|recall\|remember\|get_lessons\|capture_lesson\|...` |
281
+ | `memory` | Events + nodes CRUD, decisions, lessons, etc. |
282
+ | `graph` | Dependencies, impact, call_path, ingest, etc. |
283
+ | `project` | Indexing, ingest_local, stats, files, etc. |
284
+ | `workspace` | List, get, associate, bootstrap |
285
+ | `reminder` | List, create, snooze, complete, dismiss |
286
+ | `integration` | `provider=slack\|github`, search, activity, etc. |
287
+ | `help` | Tools, auth, version, editor_rules |
288
288
 
289
- ## Environment variables
289
+ ### Examples
290
290
 
291
- | Variable | Required | Description |
292
- |----------|----------|-------------|
293
- | `CONTEXTSTREAM_API_URL` | Yes | Base API URL (e.g. `https://api.contextstream.io`) |
294
- | `CONTEXTSTREAM_API_KEY` | Yes* | API key (*required unless `CONTEXTSTREAM_JWT` is set) |
295
- | `CONTEXTSTREAM_JWT` | Yes* | JWT (*required unless `CONTEXTSTREAM_API_KEY` is set) |
296
- | `CONTEXTSTREAM_WORKSPACE_ID` | No | Default workspace ID fallback |
297
- | `CONTEXTSTREAM_PROJECT_ID` | No | Default project ID fallback |
298
- | `CONTEXTSTREAM_USER_AGENT` | No | Custom user agent string |
299
- | `CONTEXTSTREAM_TOOLSET` | No | Tool bundle to expose: `light` (~30 tools), `standard` (default, ~50 tools), or `complete` (~86 tools). Claude Code/Desktop may warn about large tool contexts with `complete`. |
300
- | `CONTEXTSTREAM_TOOL_ALLOWLIST` | No | Comma-separated tool names to expose (overrides toolset) |
301
- | `CONTEXTSTREAM_PRO_TOOLS` | No | Comma-separated tool names treated as PRO (default: `ai_context,ai_enhanced_context,ai_context_budget,ai_embeddings,ai_plan,ai_tasks`) |
302
- | `CONTEXTSTREAM_UPGRADE_URL` | No | Upgrade link shown when Free users call PRO tools (default: `https://contextstream.io/pricing`) |
291
+ ```
292
+ search(mode="semantic", query="auth middleware")
293
+ memory(action="create_node", node_type="decision", title="Auth strategy", content="...")
294
+ graph(action="impact", target="UserService")
295
+ ```
303
296
 
304
- ### Server-side environment variables (API)
297
+ **Full tool catalog:** https://contextstream.io/docs/mcp/tools
305
298
 
306
- The following environment variables are configured on the ContextStream API server (not in your MCP client config):
299
+ ---
307
300
 
308
- | Variable | Required | Description |
309
- |----------|----------|-------------|
310
- | `QA_FILE_WRITE_ROOT` | No | Server-side root directory for `write_to_disk` file writes. When set, the API allows the `projects_ingest_local` tool to write ingested files to disk for testing/QA purposes. Files are written under `<QA_FILE_WRITE_ROOT>/<project_id>/<relative_path>`. If not set, `write_to_disk` requests are rejected. |
301
+ ## Authentication
311
302
 
312
- #### File write parameters for `projects_ingest_local`
303
+ Set **one** of:
313
304
 
314
- The `projects_ingest_local` tool accepts two optional parameters for QA/testing scenarios:
305
+ | Variable | Use case |
306
+ |----------|----------|
307
+ | `CONTEXTSTREAM_API_KEY` | Recommended for local/dev |
308
+ | `CONTEXTSTREAM_JWT` | Useful for hosted/user-session flows |
315
309
 
316
- | Parameter | Type | Default | Description |
317
- |-----------|------|---------|-------------|
318
- | `write_to_disk` | boolean | `false` | When `true`, writes ingested files to disk on the API server under `QA_FILE_WRITE_ROOT` before indexing. Requires the API to have `QA_FILE_WRITE_ROOT` configured. |
319
- | `overwrite` | boolean | `false` | When `true` (and `write_to_disk` is enabled), allows overwriting existing files. Otherwise, existing files are skipped. |
310
+ ---
320
311
 
321
- **Example usage:**
322
- ```json
323
- {
324
- "path": "/path/to/local/project",
325
- "write_to_disk": true,
326
- "overwrite": false
327
- }
328
- ```
312
+ ## Environment Variables
329
313
 
330
- **Note:** The `write_to_disk` feature is intended for testing, QA, and development scenarios where you need to materialize files on a test server. In production, `QA_FILE_WRITE_ROOT` should typically be unset to disable file writes.
314
+ ### Required
331
315
 
332
- ## Usage patterns
316
+ | Variable | Description |
317
+ |----------|-------------|
318
+ | `CONTEXTSTREAM_API_URL` | Base API URL (default `https://api.contextstream.io`) |
319
+ | `CONTEXTSTREAM_API_KEY` | API key (unless using JWT) |
320
+ | `CONTEXTSTREAM_JWT` | JWT (unless using API key) |
333
321
 
334
- ### Recommended flow for AI tools
322
+ ### Token + Tool Surface Controls
335
323
 
336
- 1. Start of a conversation: call `session_init(folder_path="...", context_hint="<first user message>")`
337
- 2. Before subsequent responses: call `context_smart(user_message="<current user message>")`
338
- 3. After important outcomes: call `session_capture(...)` or `session_capture_lesson(...)`
324
+ | Variable | Description |
325
+ |----------|-------------|
326
+ | `CONTEXTSTREAM_CONSOLIDATED` | `true` (default in v0.4.x) uses consolidated domain tools |
327
+ | `CONTEXTSTREAM_PROGRESSIVE_MODE` | Enables Router mode (~2 meta-tools) |
328
+ | `CONTEXTSTREAM_TOOLSET` | Legacy granular tool bundle: `light` / `standard` / `complete` (only when consolidated is off) |
329
+ | `CONTEXTSTREAM_TOOL_ALLOWLIST` | Comma-separated tool names to expose (legacy granular mode) |
330
+ | `CONTEXTSTREAM_SCHEMA_MODE` | Reduce schema verbosity; e.g., `compact` |
331
+ | `CONTEXTSTREAM_OUTPUT_FORMAT` | Output formatting; e.g., `compact` / `pretty` |
339
332
 
340
- ### Omit workspace/project IDs (recommended)
333
+ ### Optional Defaults
341
334
 
342
- Most tools accept omitted `workspace_id` / `project_id` and will use the current session defaults.
335
+ | Variable | Description |
336
+ |----------|-------------|
337
+ | `CONTEXTSTREAM_WORKSPACE_ID` | Default workspace fallback |
338
+ | `CONTEXTSTREAM_PROJECT_ID` | Default project ID fallback |
339
+ | `CONTEXTSTREAM_USER_AGENT` | Custom user agent string |
340
+ | `CONTEXTSTREAM_PRO_TOOLS` | Comma-separated tool names treated as PRO |
341
+ | `CONTEXTSTREAM_UPGRADE_URL` | Upgrade link for Free users calling PRO tools |
343
342
 
344
- - If you see “workspace_id is required”, call `session_init` first (or pass the ID explicitly).
345
- - If you regularly work in the same repo, use `workspace_associate` once so the server can auto-select the right workspace for that folder.
343
+ ---
346
344
 
347
- ### First-time setup (no workspaces yet)
345
+ ## Migration Notes (pre-0.4.x → 0.4.x)
348
346
 
349
- If your account has no workspaces, ContextStream will prompt your AI assistant to ask you for a workspace name.
347
+ Most workflows **just work**, but tool names change in consolidated mode.
350
348
 
351
- - Provide a workspace name (e.g., your company/team/product)
352
- - The current folder is created as a project inside that workspace
353
- - Recommended: call `workspace_bootstrap(workspace_name="...", folder_path="...")`
349
+ | Before (granular) | After (consolidated) |
350
+ |-------------------|----------------------|
351
+ | `search_semantic(query="auth")` | `search(mode="semantic", query="auth")` |
352
+ | `session_capture(...)` | `session(action="capture", ...)` |
353
+ | `graph_dependencies(...)` | `graph(action="dependencies", ...)` |
354
354
 
355
- ## Free vs PRO tools
355
+ If you rely on granular tool names, you can temporarily set:
356
356
 
357
- Tools are labeled as `(Free)` or `(PRO)` in the MCP tool list.
357
+ ```bash
358
+ CONTEXTSTREAM_CONSOLIDATED=false
359
+ ```
358
360
 
359
- - Default PRO tools: `ai_context`, `ai_enhanced_context`, `ai_context_budget`, `ai_embeddings`, `ai_plan`, `ai_tasks`
360
- - If a Free-plan user calls a PRO tool, the server returns an upgrade message with a link.
361
- - Override the PRO list via `CONTEXTSTREAM_PRO_TOOLS` and the upgrade link via `CONTEXTSTREAM_UPGRADE_URL`.
361
+ ---
362
362
 
363
363
  ## Troubleshooting
364
364
 
365
- - Tools not appearing: restart the client after editing MCP config; confirm Node 18+ is available to the client runtime.
366
- - Unauthorized errors: verify `CONTEXTSTREAM_API_URL` and `CONTEXTSTREAM_API_KEY` (or `CONTEXTSTREAM_JWT`).
367
- - Wrong workspace/project: use `workspace_associate` to map the current repo folder to the correct workspace.
365
+ | Issue | Solution |
366
+ |-------|----------|
367
+ | **Tools not appearing** | Restart the client after editing MCP config; confirm Node 18+ is available in the client runtime |
368
+ | **Unauthorized / 401** | Verify `CONTEXTSTREAM_API_URL` + `CONTEXTSTREAM_API_KEY` (or JWT) |
369
+ | **Wrong workspace/project** | Run `session_init` and/or associate your folder with the correct workspace |
370
+ | **Client warns about tool context size** | Use Router mode (`CONTEXTSTREAM_PROGRESSIVE_MODE=true`), or keep consolidated mode and reduce schema/output verbosity |
371
+
372
+ ---
368
373
 
369
374
  ## Development
370
375
 
@@ -377,13 +382,20 @@ npm run typecheck
377
382
  npm run build
378
383
  ```
379
384
 
385
+ ---
386
+
380
387
  ## Links
381
388
 
382
- - Website: https://contextstream.io
383
- - Docs: https://contextstream.io/docs/mcp
384
- - Pricing: https://contextstream.io/pricing
385
- - npm: https://www.npmjs.com/package/@contextstream/mcp-server
386
- - GitHub: https://github.com/contextstream/mcp-server
389
+ | Resource | URL |
390
+ |----------|-----|
391
+ | **Website** | https://contextstream.io |
392
+ | **Docs** | https://contextstream.io/docs/mcp |
393
+ | **Tool Catalog** | https://contextstream.io/docs/mcp/tools |
394
+ | **Pricing** | https://contextstream.io/pricing |
395
+ | **npm** | https://www.npmjs.com/package/@contextstream/mcp-server |
396
+ | **GitHub** | https://github.com/contextstream/mcp-server |
397
+
398
+ ---
387
399
 
388
400
  ## License
389
401
 
package/dist/index.js CHANGED
@@ -7289,116 +7289,29 @@ import * as path4 from "node:path";
7289
7289
  // src/rules-templates.ts
7290
7290
  var DEFAULT_CLAUDE_MCP_SERVER_NAME = "contextstream";
7291
7291
  var CONTEXTSTREAM_TOOL_NAMES = [
7292
- // Session/Context (standard)
7292
+ // Standalone tools (always present)
7293
7293
  "session_init",
7294
7294
  "context_smart",
7295
7295
  "context_feedback",
7296
- "session_summary",
7297
- "session_capture",
7298
- "session_capture_lesson",
7299
- "session_get_lessons",
7300
- "session_recall",
7301
- "session_remember",
7302
- "session_get_user_context",
7303
- "session_smart_search",
7304
- "session_compress",
7305
- "session_delta",
7306
- // Editor Rules
7307
- "generate_editor_rules",
7308
- // Workspaces
7309
- "workspace_associate",
7310
- "workspace_bootstrap",
7311
- "workspaces_list",
7312
- "workspaces_create",
7313
- "workspaces_update",
7314
- "workspaces_delete",
7315
- "workspaces_get",
7316
- "workspaces_overview",
7317
- "workspaces_analytics",
7318
- "workspaces_content",
7319
- // Projects
7320
- "projects_list",
7321
- "projects_create",
7322
- "projects_update",
7323
- "projects_delete",
7324
- "projects_get",
7325
- "projects_overview",
7326
- "projects_statistics",
7327
- "projects_files",
7328
- "projects_index",
7329
- "projects_index_status",
7330
- "projects_ingest_local",
7331
- // Search
7332
- "search_semantic",
7333
- "search_hybrid",
7334
- "search_keyword",
7335
- "search_pattern",
7336
- "search_suggestions",
7337
- // Memory
7338
- "memory_create_event",
7339
- "memory_bulk_ingest",
7340
- "memory_list_events",
7341
- "memory_create_node",
7342
- "memory_list_nodes",
7343
- "memory_search",
7344
- "memory_decisions",
7345
- "decision_trace",
7346
- "memory_get_event",
7347
- "memory_update_event",
7348
- "memory_delete_event",
7349
- "memory_distill_event",
7350
- "memory_get_node",
7351
- "memory_update_node",
7352
- "memory_delete_node",
7353
- "memory_supersede_node",
7354
- "memory_timeline",
7355
- "memory_summary",
7356
- // Graph
7357
- "graph_related",
7358
- "graph_path",
7359
- "graph_decisions",
7360
- "graph_dependencies",
7361
- "graph_call_path",
7362
- "graph_impact",
7363
- "graph_circular_dependencies",
7364
- "graph_unused_code",
7365
- "graph_ingest",
7366
- "graph_contradictions",
7367
- // AI (PRO)
7368
- "ai_context",
7369
- "ai_enhanced_context",
7370
- "ai_context_budget",
7371
- "ai_embeddings",
7372
- "ai_plan",
7373
- "ai_tasks",
7374
- // GitHub Integration (PRO)
7375
- "github_stats",
7376
- "github_repos",
7377
- "github_contributors",
7378
- "github_activity",
7379
- "github_issues",
7380
- "github_search",
7381
- // Slack Integration (PRO)
7382
- "slack_stats",
7383
- "slack_channels",
7384
- "slack_contributors",
7385
- "slack_activity",
7386
- "slack_discussions",
7387
- "slack_search",
7388
- "slack_sync_users",
7389
- "slack_knowledge",
7390
- "slack_summary",
7391
- // GitHub additional
7392
- "github_knowledge",
7393
- "github_summary",
7394
- // Cross-source integrations
7395
- "integrations_status",
7396
- "integrations_search",
7397
- "integrations_summary",
7398
- "integrations_knowledge",
7399
- // Auth/Meta
7400
- "auth_me",
7401
- "mcp_server_version"
7296
+ // Consolidated domain tools (v0.4.x default)
7297
+ "search",
7298
+ // Modes: semantic, hybrid, keyword, pattern
7299
+ "session",
7300
+ // Actions: capture, capture_lesson, get_lessons, recall, remember, user_context, summary, compress, delta, smart_search, decision_trace
7301
+ "memory",
7302
+ // Actions: create_event, get_event, update_event, delete_event, list_events, distill_event, create_node, get_node, update_node, delete_node, list_nodes, supersede_node, search, decisions, timeline, summary
7303
+ "graph",
7304
+ // Actions: dependencies, impact, call_path, related, path, decisions, ingest, circular_dependencies, unused_code, contradictions
7305
+ "project",
7306
+ // Actions: list, get, create, update, index, overview, statistics, files, index_status, ingest_local
7307
+ "workspace",
7308
+ // Actions: list, get, associate, bootstrap
7309
+ "reminder",
7310
+ // Actions: list, active, create, snooze, complete, dismiss
7311
+ "integration",
7312
+ // Provider: slack, github, all; Actions: status, search, stats, activity, contributors, knowledge, summary, channels, discussions, sync_users, repos, issues
7313
+ "help"
7314
+ // Actions: tools, auth, version, editor_rules, enable_bundle
7402
7315
  ];
7403
7316
  function applyMcpToolPrefix(markdown, toolPrefix) {
7404
7317
  const toolPattern = CONTEXTSTREAM_TOOL_NAMES.join("|");
@@ -7406,9 +7319,10 @@ function applyMcpToolPrefix(markdown, toolPrefix) {
7406
7319
  return markdown.replace(toolRegex, `${toolPrefix}$1`);
7407
7320
  }
7408
7321
  var CONTEXTSTREAM_RULES_FULL = `
7409
- ## ContextStream Integration (Enhanced)
7322
+ ## ContextStream v0.4.x Integration (Enhanced)
7410
7323
 
7411
7324
  You have access to ContextStream MCP tools for persistent memory and context.
7325
+ v0.4.x uses **~11 consolidated domain tools** for ~75% token reduction vs previous versions.
7412
7326
 
7413
7327
  ## TL;DR - REQUIRED EVERY MESSAGE
7414
7328
 
@@ -7416,15 +7330,39 @@ You have access to ContextStream MCP tools for persistent memory and context.
7416
7330
  |---------|--------------|
7417
7331
  | **1st message** | \`session_init(folder_path="...", context_hint="<user's message>")\` |
7418
7332
  | **2nd+ messages** | \`context_smart(user_message="<user's message>", format="minified", max_tokens=400)\` |
7419
- | **Before risky/non-trivial work** | \`session_get_lessons(query="<topic>")\` |
7420
- | **After completing task** | \`session_capture(...)\` - MUST capture decisions/insights |
7421
- | **User frustration/correction** | \`session_capture_lesson(...)\` - MUST capture lessons |
7422
- | **Command/tool error + fix** | \`session_capture_lesson(...)\` - MUST capture lessons |
7333
+ | **Before risky/non-trivial work** | \`session(action="get_lessons", query="<topic>")\` |
7334
+ | **After completing task** | \`session(action="capture", event_type="decision", ...)\` - MUST capture |
7335
+ | **User frustration/correction** | \`session(action="capture_lesson", ...)\` - MUST capture lessons |
7336
+ | **Command/tool error + fix** | \`session(action="capture_lesson", ...)\` - MUST capture lessons |
7423
7337
 
7424
7338
  **NO EXCEPTIONS.** Do not skip even if you think you have enough context.
7425
7339
 
7426
7340
  ---
7427
7341
 
7342
+ ## Consolidated Domain Tools Architecture
7343
+
7344
+ v0.4.x consolidates ~58 individual tools into ~11 domain tools with action/mode dispatch:
7345
+
7346
+ ### Standalone Tools (Always Call)
7347
+ - **\`session_init\`** - Initialize session with workspace detection + context
7348
+ - **\`context_smart\`** - Semantic search for relevant context (CALL EVERY MESSAGE)
7349
+
7350
+ ### Domain Tools (Use action/mode parameter)
7351
+
7352
+ | Domain | Actions/Modes | Example |
7353
+ |--------|---------------|---------|
7354
+ | **\`search\`** | mode: semantic, hybrid, keyword, pattern | \`search(mode="hybrid", query="auth implementation")\` |
7355
+ | **\`session\`** | action: capture, capture_lesson, get_lessons, recall, remember, user_context, summary, compress, delta, smart_search, decision_trace | \`session(action="capture", event_type="decision", title="Use JWT", content="...")\` |
7356
+ | **\`memory\`** | action: create_event, get_event, update_event, delete_event, list_events, distill_event, create_node, get_node, update_node, delete_node, list_nodes, supersede_node, search, decisions, timeline, summary | \`memory(action="list_events", limit=10)\` |
7357
+ | **\`graph\`** | action: dependencies, impact, call_path, related, path, decisions, ingest, circular_dependencies, unused_code, contradictions | \`graph(action="impact", symbol_name="AuthService")\` |
7358
+ | **\`project\`** | action: list, get, create, update, index, overview, statistics, files, index_status, ingest_local | \`project(action="statistics")\` |
7359
+ | **\`workspace\`** | action: list, get, associate, bootstrap | \`workspace(action="list")\` |
7360
+ | **\`reminder\`** | action: list, active, create, snooze, complete, dismiss | \`reminder(action="active")\` |
7361
+ | **\`integration\`** | provider: slack/github/all; action: status, search, stats, activity, contributors, knowledge, summary, channels, discussions, sync_users, repos, issues | \`integration(provider="github", action="search", query="...")\` |
7362
+ | **\`help\`** | action: tools, auth, version, editor_rules, enable_bundle | \`help(action="tools")\` |
7363
+
7364
+ ---
7365
+
7428
7366
  ### Why context_smart is Required (Even After session_init)
7429
7367
 
7430
7368
  **Common mistake:** "session_init already gave me context, I don't need context_smart"
@@ -7447,126 +7385,124 @@ You have access to ContextStream MCP tools for persistent memory and context.
7447
7385
 
7448
7386
  - For trivial/local edits: \`context_smart(..., max_tokens=200)\`
7449
7387
  - Default: \`context_smart(..., max_tokens=400)\`
7450
- - Deep debugging/architecture or heavy "what did we decide?": \`context_smart(..., max_tokens=800)\`
7451
- - Keep \`format="minified"\` (default) unless you're debugging tool output
7388
+ - Deep debugging/architecture: \`context_smart(..., max_tokens=800)\`
7389
+ - Keep \`format="minified"\` (default) unless debugging
7452
7390
 
7453
- If context still feels missing, increase \`max_tokens\` and/or call \`session_recall\` for a focused deep lookup.
7391
+ If context still feels missing, use \`session(action="recall", query="...")\` for focused deep lookup.
7454
7392
 
7455
7393
  ---
7456
7394
 
7457
7395
  ### Preferences & Lessons (Use Early)
7458
7396
 
7459
- - If preferences or style matter, call \`session_get_user_context\`.
7460
- - Before risky changes or when past mistakes may apply, call \`session_get_lessons(query="<topic>")\`.
7461
- - When frustration, corrections, or tool mistakes occur, immediately call \`session_capture_lesson\`.
7397
+ - If preferences/style matter: \`session(action="user_context")\`
7398
+ - Before risky changes: \`session(action="get_lessons", query="<topic>")\`
7399
+ - On frustration/corrections: \`session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")\`
7462
7400
 
7463
7401
  ---
7464
7402
 
7465
- ### Search, Graphs, and Code Intelligence (ContextStream-first)
7403
+ ### Search & Code Intelligence (ContextStream-first)
7466
7404
 
7467
- - Default order: \`session_smart_search\` -> \`search_hybrid\`/\`search_keyword\`/\`search_semantic\` -> graph tools -> local repo scans (rg/ls/find) only if ContextStream returns no results.
7468
- - Use \`session_smart_search\` before scanning the repo or grepping.
7469
- - Use \`search_semantic\`/\`search_hybrid\`/\`search_keyword\` for targeted queries.
7470
- - For dependencies/impact/call paths, use \`graph_dependencies\`, \`graph_impact\`, and \`graph_call_path\`.
7471
- - If the toolset is complete (Elite), prefer \`graph_call_path\` and \`graph_path\` for call relationships instead of manual searches.
7472
- - If the graph is missing or stale, run \`graph_ingest\` (async by default with \`wait: false\`). Tell the user it can take a few minutes; optionally call \`projects_statistics\` to estimate time.
7405
+ **Search order:**
7406
+ 1. \`session(action="smart_search", query="...")\` - context-enriched
7407
+ 2. \`search(mode="hybrid", query="...")\` - semantic + keyword
7408
+ 3. \`graph(action="dependencies", ...)\` - code structure
7409
+ 4. Local repo scans (rg/ls/find) - only if ContextStream returns no results
7410
+
7411
+ **Code Analysis:**
7412
+ - Dependencies: \`graph(action="dependencies", file_path="...")\`
7413
+ - Change impact: \`graph(action="impact", symbol_name="...")\`
7414
+ - Call path: \`graph(action="call_path", from_symbol="...", to_symbol="...")\`
7415
+ - Build graph: \`graph(action="ingest")\` - async, can take a few minutes
7473
7416
 
7474
7417
  ---
7475
7418
 
7476
7419
  ### Distillation & Memory Hygiene
7477
7420
 
7478
- - Use \`session_summary\` for a fast workspace snapshot.
7479
- - Use \`session_compress\` when the chat is long or context limits are near.
7480
- - Use \`memory_summary\` for recent work summaries and \`memory_distill_event\` to condense noisy memory entries.
7421
+ - Quick context: \`session(action="summary")\`
7422
+ - Long chat: \`session(action="compress", content="...")\`
7423
+ - Memory summary: \`memory(action="summary")\`
7424
+ - Condense noisy entries: \`memory(action="distill_event", event_id="...")\`
7481
7425
 
7482
7426
  ---
7483
7427
 
7484
7428
  ### When to Capture (MANDATORY)
7485
7429
 
7486
- | When | Tool | Example |
7430
+ | When | Call | Example |
7487
7431
  |------|------|---------|
7488
- | User makes a decision | \`session_capture\` | "Let's use PostgreSQL" -> capture as decision |
7489
- | User states preference | \`session_capture\` | "I prefer TypeScript" -> capture as preference |
7490
- | You complete a task | \`session_capture\` | Capture what was done, decisions made |
7491
- | Need past context | \`session_recall\` | "What did we decide about X?" |
7432
+ | User makes decision | \`session(action="capture", event_type="decision", ...)\` | "Let's use PostgreSQL" |
7433
+ | User states preference | \`session(action="capture", event_type="preference", ...)\` | "I prefer TypeScript" |
7434
+ | You complete a task | \`session(action="capture", event_type="task", ...)\` | Capture what was done |
7435
+ | Need past context | \`session(action="recall", query="...")\` | "What did we decide about X?" |
7492
7436
 
7493
7437
  **You MUST capture after completing any significant task.** This ensures future sessions have context.
7494
7438
 
7495
7439
  ---
7496
7440
 
7497
- ### Full Tool Catalog
7498
-
7499
- To expose all tools below, set \`CONTEXTSTREAM_TOOLSET=complete\` in your MCP config. The default (\`standard\`) includes the essential session, search, memory, and graph tools above.
7500
-
7501
- **To enable the complete toolset in your MCP config:**
7502
- \`\`\`json
7503
- {
7504
- "env": {
7505
- "CONTEXTSTREAM_TOOLSET": "complete"
7506
- }
7507
- }
7508
- \`\`\`
7509
-
7510
- **Available tool categories (when \`CONTEXTSTREAM_TOOLSET=complete\`):**
7511
-
7512
- **Session/Context** (included in standard):
7513
- \`session_init\`, \`context_smart\`, \`context_feedback\`, \`session_summary\`, \`session_capture\`, \`session_capture_lesson\`, \`session_get_lessons\`, \`session_recall\`, \`session_remember\`, \`session_get_user_context\`, \`session_smart_search\`, \`session_compress\`, \`session_delta\`, \`generate_editor_rules\`, \`workspace_associate\`, \`workspace_bootstrap\`
7514
-
7515
- **Workspaces**:
7516
- \`workspaces_list\`, \`workspaces_create\`, \`workspaces_update\`, \`workspaces_delete\`, \`workspaces_get\`, \`workspaces_overview\`, \`workspaces_analytics\`, \`workspaces_content\`
7517
-
7518
- **Projects**:
7519
- \`projects_list\`, \`projects_create\`, \`projects_update\`, \`projects_delete\`, \`projects_get\`, \`projects_overview\`, \`projects_statistics\`, \`projects_files\`, \`projects_index\`, \`projects_index_status\`, \`projects_ingest_local\`
7520
-
7521
- **Search**:
7522
- \`search_semantic\`, \`search_hybrid\`, \`search_keyword\`, \`search_pattern\`, \`search_suggestions\`
7523
-
7524
- **Memory**:
7525
- \`memory_create_event\`, \`memory_bulk_ingest\`, \`memory_list_events\`, \`memory_create_node\`, \`memory_list_nodes\`, \`memory_search\`, \`memory_decisions\`, \`decision_trace\`, \`memory_get_event\`, \`memory_update_event\`, \`memory_delete_event\`, \`memory_distill_event\`, \`memory_get_node\`, \`memory_update_node\`, \`memory_delete_node\`, \`memory_supersede_node\`, \`memory_timeline\`, \`memory_summary\`
7526
-
7527
- **Graph** (code analysis):
7528
- \`graph_related\`, \`graph_path\`, \`graph_decisions\`, \`graph_dependencies\`, \`graph_call_path\`, \`graph_impact\`, \`graph_circular_dependencies\`, \`graph_unused_code\`, \`graph_ingest\`, \`graph_contradictions\`
7529
-
7530
- **AI** (PRO):
7531
- \`ai_context\`, \`ai_enhanced_context\`, \`ai_context_budget\`, \`ai_embeddings\`, \`ai_plan\`, \`ai_tasks\`
7532
-
7533
- **GitHub Integration** (PRO):
7534
- \`github_stats\`, \`github_repos\`, \`github_contributors\`, \`github_activity\`, \`github_issues\`, \`github_search\`, \`github_knowledge\`, \`github_summary\`
7535
-
7536
- **Slack Integration** (PRO):
7537
- \`slack_stats\`, \`slack_channels\`, \`slack_contributors\`, \`slack_activity\`, \`slack_discussions\`, \`slack_search\`, \`slack_sync_users\`, \`slack_knowledge\`, \`slack_summary\`
7538
-
7539
- **Cross-Source Integrations** (PRO):
7540
- \`integrations_status\`, \`integrations_search\`, \`integrations_summary\`, \`integrations_knowledge\`
7441
+ ### Complete Action Reference
7442
+
7443
+ **session actions:**
7444
+ - \`capture\` - Save decision/insight/task (requires: event_type, title, content)
7445
+ - \`capture_lesson\` - Save lesson from mistake (requires: title, category, trigger, impact, prevention)
7446
+ - \`get_lessons\` - Retrieve relevant lessons (optional: query, category, severity)
7447
+ - \`recall\` - Natural language memory recall (requires: query)
7448
+ - \`remember\` - Quick save to memory (requires: content)
7449
+ - \`user_context\` - Get user preferences/style
7450
+ - \`summary\` - Workspace summary
7451
+ - \`compress\` - Compress long conversation
7452
+ - \`delta\` - Changes since timestamp
7453
+ - \`smart_search\` - Context-enriched search
7454
+ - \`decision_trace\` - Trace decision provenance
7455
+
7456
+ **memory actions:**
7457
+ - Event CRUD: \`create_event\`, \`get_event\`, \`update_event\`, \`delete_event\`, \`list_events\`, \`distill_event\`
7458
+ - Node CRUD: \`create_node\`, \`get_node\`, \`update_node\`, \`delete_node\`, \`list_nodes\`, \`supersede_node\`
7459
+ - Query: \`search\`, \`decisions\`, \`timeline\`, \`summary\`
7460
+
7461
+ **graph actions:**
7462
+ - Analysis: \`dependencies\`, \`impact\`, \`call_path\`, \`related\`, \`path\`
7463
+ - Quality: \`circular_dependencies\`, \`unused_code\`, \`contradictions\`
7464
+ - Management: \`ingest\`, \`decisions\`
7541
7465
 
7542
7466
  See full documentation: https://contextstream.io/docs/mcp/tools
7543
7467
  `.trim();
7544
7468
  var CONTEXTSTREAM_RULES_MINIMAL = `
7545
- ## ContextStream (Standard)
7546
-
7547
- - First user message: \`session_init(folder_path="<cwd>", context_hint="<user_message>")\`, then answer.
7548
- - Every user message: \`context_smart(user_message="<user_message>", format="minified", max_tokens=400)\` BEFORE answering.
7549
- - Use \`max_tokens=200\` for trivial/local edits, \`max_tokens=800\` for deep debugging/architecture.
7550
- - Before risky/non-trivial work: check \`session_get_lessons(query="<topic>")\`; use \`session_get_user_context\` when preferences/style matter.
7551
- - For discovery: use \`session_smart_search\` first; use \`search_semantic\`/\`search_hybrid\`/\`search_keyword\` for targeted lookups; avoid local scans until ContextStream returns no results.
7552
- - For code intelligence: use \`graph_dependencies\`/\`graph_impact\`/\`graph_call_path\`; if the toolset is complete (Elite), prefer \`graph_call_path\`/\`graph_path\` for call relationships; run \`graph_ingest\` if the graph is missing (async by default, can take a few minutes).
7553
- - For distillation: use \`session_summary\` for quick context; use \`session_compress\` for long chats; use \`memory_summary\` or \`memory_distill_event\` to condense memory.
7554
- - After meaningful work/decisions/preferences: \`session_capture(event_type=decision|preference|task|insight, title="...", content="...")\`.
7555
- - On frustration/corrections/tool mistakes: \`session_capture_lesson(...)\`.
7556
-
7557
- ### Tool Catalog
7469
+ ## ContextStream v0.4.x (Consolidated Domain Tools)
7558
7470
 
7559
- By default, the MCP server exposes the **standard** toolset (~58 tools). To expose fewer tools, set \`CONTEXTSTREAM_TOOLSET=light\`. To expose everything (~86 tools), set \`CONTEXTSTREAM_TOOLSET=complete\` in your MCP config:
7471
+ v0.4.x uses ~11 consolidated domain tools for ~75% token reduction vs previous versions.
7560
7472
 
7561
- \`\`\`json
7562
- {
7563
- "env": {
7564
- "CONTEXTSTREAM_TOOLSET": "complete"
7565
- }
7566
- }
7567
- \`\`\`
7473
+ ### Required Every Message
7568
7474
 
7569
- Full tool reference: https://contextstream.io/docs/mcp/tools
7475
+ | Message | What to Call |
7476
+ |---------|--------------|
7477
+ | **1st message** | \`session_init(folder_path="<cwd>", context_hint="<user_message>")\` |
7478
+ | **2nd+ messages** | \`context_smart(user_message="<user_message>", format="minified", max_tokens=400)\` |
7479
+ | **Capture decisions** | \`session(action="capture", event_type="decision", title="...", content="...")\` |
7480
+ | **Before risky work** | \`session(action="get_lessons", query="<topic>")\` |
7481
+ | **On user frustration** | \`session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")\` |
7482
+
7483
+ ### Quick Reference: Domain Tools
7484
+
7485
+ | Tool | Common Usage |
7486
+ |------|--------------|
7487
+ | \`search\` | \`search(mode="semantic", query="...")\` \u2014 modes: semantic, hybrid, keyword, pattern |
7488
+ | \`session\` | \`session(action="capture", ...)\` \u2014 actions: capture, capture_lesson, get_lessons, recall, remember, user_context, summary, compress, delta, smart_search |
7489
+ | \`memory\` | \`memory(action="list_events", ...)\` \u2014 CRUD for events/nodes, search, decisions, timeline, summary |
7490
+ | \`graph\` | \`graph(action="dependencies", ...)\` \u2014 dependencies, impact, call_path, related, ingest |
7491
+ | \`project\` | \`project(action="list", ...)\` \u2014 list, get, create, update, index, statistics |
7492
+ | \`workspace\` | \`workspace(action="list", ...)\` \u2014 list, get, associate, bootstrap |
7493
+ | \`integration\` | \`integration(provider="github", action="search", ...)\` \u2014 GitHub/Slack integration |
7494
+ | \`help\` | \`help(action="tools")\` \u2014 tools, auth, version, editor_rules |
7495
+
7496
+ ### Behavior Rules
7497
+
7498
+ - **First message**: Always call \`session_init\` with context_hint
7499
+ - **Every message after**: Always call \`context_smart\` BEFORE responding (semantic search for relevant context)
7500
+ - **For discovery**: Use \`session(action="smart_search")\` or \`search(mode="hybrid")\` before local repo scans
7501
+ - **For code analysis**: Use \`graph(action="dependencies")\` or \`graph(action="impact")\` for call/dependency analysis
7502
+ - **After completing work**: Always capture decisions/insights with \`session(action="capture")\`
7503
+ - **On mistakes/corrections**: Immediately capture lessons with \`session(action="capture_lesson")\`
7504
+
7505
+ Full docs: https://contextstream.io/docs/mcp/tools
7570
7506
  `.trim();
7571
7507
  var TEMPLATES = {
7572
7508
  codex: {
@@ -9141,7 +9077,12 @@ Upgrade: ${upgradeUrl2}` : "";
9141
9077
  } catch {
9142
9078
  }
9143
9079
  console.error(`[ContextStream] Bundle '${bundleName}' enabled with ${toolsEnabled} tools.`);
9144
- return { success: true, message: `Enabled bundle '${bundleName}' with ${toolsEnabled} tools.`, toolsEnabled };
9080
+ return {
9081
+ success: true,
9082
+ message: `Enabled bundle '${bundleName}' with ${toolsEnabled} tools.`,
9083
+ toolsEnabled,
9084
+ hint: "If your client doesn't auto-refresh tools, restart the MCP connection to see new tools."
9085
+ };
9145
9086
  }
9146
9087
  const ROUTER_DIRECT_TOOLS = /* @__PURE__ */ new Set(["contextstream", "contextstream_help"]);
9147
9088
  function registerTool(name, config, handler) {
@@ -10562,6 +10503,13 @@ This does semantic search on the first message. You only need context_smart on s
10562
10503
  console.error("[ContextStream] Failed to check integration status in session_init:", error);
10563
10504
  }
10564
10505
  }
10506
+ result.modes = {
10507
+ consolidated: CONSOLIDATED_MODE,
10508
+ progressive: PROGRESSIVE_MODE,
10509
+ router: ROUTER_MODE,
10510
+ auto_hide_integrations: AUTO_HIDE_INTEGRATIONS,
10511
+ bundles: PROGRESSIVE_MODE ? getBundleInfo() : void 0
10512
+ };
10565
10513
  const status = typeof result.status === "string" ? result.status : "";
10566
10514
  const workspaceWarning = typeof result.workspace_warning === "string" ? result.workspace_warning : "";
10567
10515
  let text = formatContent(result);
@@ -15215,8 +15163,8 @@ function buildContextStreamMcpServer(params) {
15215
15163
  CONTEXTSTREAM_API_URL: params.apiUrl,
15216
15164
  CONTEXTSTREAM_API_KEY: params.apiKey
15217
15165
  };
15218
- if (params.toolset) {
15219
- env.CONTEXTSTREAM_TOOLSET = params.toolset;
15166
+ if (params.toolset === "router") {
15167
+ env.CONTEXTSTREAM_PROGRESSIVE_MODE = "true";
15220
15168
  }
15221
15169
  return {
15222
15170
  command: "npx",
@@ -15229,8 +15177,8 @@ function buildContextStreamVsCodeServer(params) {
15229
15177
  CONTEXTSTREAM_API_URL: params.apiUrl,
15230
15178
  CONTEXTSTREAM_API_KEY: params.apiKey
15231
15179
  };
15232
- if (params.toolset) {
15233
- env.CONTEXTSTREAM_TOOLSET = params.toolset;
15180
+ if (params.toolset === "router") {
15181
+ env.CONTEXTSTREAM_PROGRESSIVE_MODE = "true";
15234
15182
  }
15235
15183
  return {
15236
15184
  type: "stdio",
@@ -15312,7 +15260,7 @@ async function upsertCodexTomlConfig(filePath, params) {
15312
15260
  const existing = exists ? await fs5.readFile(filePath, "utf8").catch(() => "") : "";
15313
15261
  const marker = "[mcp_servers.contextstream]";
15314
15262
  const envMarker = "[mcp_servers.contextstream.env]";
15315
- const toolsetLine = params.toolset ? `CONTEXTSTREAM_TOOLSET = "${params.toolset}"
15263
+ const toolsetLine = params.toolset === "router" ? `CONTEXTSTREAM_PROGRESSIVE_MODE = "true"
15316
15264
  ` : "";
15317
15265
  const block = `
15318
15266
 
@@ -15602,19 +15550,16 @@ Created API key: ${maskedNewKey}
15602
15550
  console.log(`
15603
15551
  Detected plan: ${planLabel} (graph: ${graphTierLabel})`);
15604
15552
  console.log("\nMCP toolset (which tools to expose to the AI):");
15605
- console.log(" 1) Light \u2014 core session, project, and basic memory/graph tools (~31 tools)");
15606
- console.log(" Best for: Claude Code, faster responses, token-constrained environments");
15607
- console.log(" 2) Standard (recommended) \u2014 adds workspace, memory CRUD, graph analysis, search (~58 tools)");
15608
- console.log(" Best for: most users, full development workflow with memory + code analysis");
15609
- console.log(" 3) Complete \u2014 all tools including full graph + AI, GitHub, Slack integrations (~86 tools)");
15610
- console.log(" Best for: Elite users or power users needing full graph + integrations");
15553
+ console.log(" 1) Standard (recommended) \u2014 consolidated domain tools (~11 tools, ~75% token reduction)");
15554
+ console.log(" Best for: all users, full functionality with minimal token overhead");
15555
+ console.log(" Includes: session_init, context_smart + 9 domain tools (search, session, memory, graph, etc.)");
15556
+ console.log(" 2) Router \u2014 ultra-minimal with AI routing (~2 meta-tools)");
15557
+ console.log(" Best for: experimental, routes requests through session_init + context_smart only");
15611
15558
  console.log("");
15612
- console.log(" Note: Slack/GitHub tools are auto-hidden until you connect those integrations.");
15613
- console.log(" Tip: Elite users should choose Complete to unlock full graph tools.");
15614
- console.log(" Tip: Change later by setting CONTEXTSTREAM_TOOLSET=light|standard|complete");
15615
- const toolsetDefault = detectedGraphTier === "full" ? "3" : "2";
15616
- const toolsetChoice = normalizeInput(await rl.question(`Choose [1/2/3] (default ${toolsetDefault}): `)) || toolsetDefault;
15617
- const toolset = toolsetChoice === "1" ? "light" : toolsetChoice === "3" ? "complete" : "standard";
15559
+ console.log(" Note: v0.4.x uses consolidated domain tools by default for ~75% token reduction.");
15560
+ console.log(" Tip: Change later by setting CONTEXTSTREAM_CONSOLIDATED=true|false");
15561
+ const toolsetChoice = normalizeInput(await rl.question("Choose [1/2] (default 1): ")) || "1";
15562
+ const toolset = toolsetChoice === "2" ? "router" : "consolidated";
15618
15563
  const editors = ["codex", "claude", "cursor", "windsurf", "cline", "kilo", "roo", "aider"];
15619
15564
  console.log('\nSelect editors to configure (comma-separated numbers, or "all"):');
15620
15565
  editors.forEach((e, i) => console.log(` ${i + 1}) ${EDITOR_LABELS[e]}`));
@@ -15671,9 +15616,9 @@ Detected plan: ${planLabel} (graph: ${graphTierLabel})`);
15671
15616
  const mcpChoiceDefault = hasCodex && !hasProjectMcpEditors ? "1" : "3";
15672
15617
  const mcpChoice = normalizeInput(await rl.question(`Choose [${hasCodex && !hasProjectMcpEditors ? "1/2" : "1/2/3/4"}] (default ${mcpChoiceDefault}): `)) || mcpChoiceDefault;
15673
15618
  const mcpScope = mcpChoice === "2" && hasCodex && !hasProjectMcpEditors ? "skip" : mcpChoice === "4" ? "skip" : mcpChoice === "1" ? "global" : mcpChoice === "2" ? "project" : "both";
15674
- const mcpServer = toolset === "complete" ? buildContextStreamMcpServer({ apiUrl, apiKey, toolset: "complete" }) : buildContextStreamMcpServer({ apiUrl, apiKey });
15619
+ const mcpServer = buildContextStreamMcpServer({ apiUrl, apiKey, toolset });
15675
15620
  const mcpServerClaude = buildContextStreamMcpServer({ apiUrl, apiKey, toolset });
15676
- const vsCodeServer = toolset === "complete" ? buildContextStreamVsCodeServer({ apiUrl, apiKey, toolset: "complete" }) : buildContextStreamVsCodeServer({ apiUrl, apiKey });
15621
+ const vsCodeServer = buildContextStreamVsCodeServer({ apiUrl, apiKey, toolset });
15677
15622
  const needsGlobalMcpConfig = mcpScope === "global" || mcpScope === "both" || mcpScope === "project" && hasCodex;
15678
15623
  if (needsGlobalMcpConfig) {
15679
15624
  console.log("\nInstalling global MCP config...");
@@ -15687,8 +15632,7 @@ Detected plan: ${planLabel} (graph: ${graphTierLabel})`);
15687
15632
  console.log(`- ${EDITOR_LABELS[editor]}: would update ${filePath}`);
15688
15633
  continue;
15689
15634
  }
15690
- const codexParams = toolset === "complete" ? { apiUrl, apiKey, toolset: "complete" } : { apiUrl, apiKey };
15691
- const status = await upsertCodexTomlConfig(filePath, codexParams);
15635
+ const status = await upsertCodexTomlConfig(filePath, { apiUrl, apiKey, toolset });
15692
15636
  writeActions.push({ kind: "mcp-config", target: filePath, status });
15693
15637
  console.log(`- ${EDITOR_LABELS[editor]}: ${status} ${filePath}`);
15694
15638
  continue;
@@ -15721,7 +15665,8 @@ Detected plan: ${planLabel} (graph: ${graphTierLabel})`);
15721
15665
  }
15722
15666
  }
15723
15667
  console.log("- Claude Code: global MCP config is best done via `claude mcp add --transport stdio ...` (see docs).");
15724
- console.log(` macOS/Linux: claude mcp add --transport stdio contextstream --scope user --env CONTEXTSTREAM_API_URL=... --env CONTEXTSTREAM_API_KEY=... --env CONTEXTSTREAM_TOOLSET=${toolset} -- npx -y @contextstream/mcp-server`);
15668
+ const envHint = toolset === "router" ? " --env CONTEXTSTREAM_PROGRESSIVE_MODE=true" : "";
15669
+ console.log(` macOS/Linux: claude mcp add --transport stdio contextstream --scope user --env CONTEXTSTREAM_API_URL=... --env CONTEXTSTREAM_API_KEY=...${envHint} -- npx -y @contextstream/mcp-server`);
15725
15670
  console.log(" Windows (native): use `cmd /c npx -y @contextstream/mcp-server` after `--` if `npx` is not found.");
15726
15671
  continue;
15727
15672
  }
@@ -15925,17 +15870,16 @@ Applying to ${projects.length} project(s)...`);
15925
15870
  const skipped = writeActions.filter((a) => a.status === "skipped").length;
15926
15871
  const dry = writeActions.filter((a) => a.status === "dry-run").length;
15927
15872
  console.log(`Summary: ${created} created, ${updated} updated, ${appended} appended, ${skipped} skipped, ${dry} dry-run.`);
15928
- const toolsetDesc = toolset === "light" ? "~31 tools" : toolset === "complete" ? "~86 tools" : "~58 tools";
15873
+ const toolsetDesc = toolset === "router" ? "~2 meta-tools (router mode)" : "~11 domain tools (consolidated)";
15929
15874
  console.log(`Toolset: ${toolset} (${toolsetDesc})`);
15930
- console.log(`Auto-hide: Slack/GitHub tools hidden until integrations connected.`);
15875
+ console.log(`Token reduction: ~75% compared to previous versions.`);
15931
15876
  }
15932
15877
  console.log("\nNext steps:");
15933
15878
  console.log("- Restart your editor/CLI after changing MCP config or rules.");
15934
- console.log("- Prefer ContextStream search first: use session_smart_search (or mcp__contextstream__session_smart_search) before raw repo scans (rg/ls/find).");
15879
+ console.log("- v0.4.x uses consolidated domain tools by default (~11 tools vs ~58 in v0.3.x).");
15935
15880
  console.log("- If any tools require UI-based MCP setup (e.g. Cline/Kilo/Roo global), follow https://contextstream.io/docs/mcp.");
15936
- if (toolset === "complete") {
15937
- console.log("- For full graph tools, run graph_ingest once per project (async; can take a few minutes).");
15938
- console.log("- Note: Claude Code/Desktop may warn about large tool contexts. This is expected with the complete toolset.");
15881
+ if (toolset === "router") {
15882
+ console.log("- Router mode uses 2 meta-tools (session_init + context_smart) for ultra-minimal token usage.");
15939
15883
  }
15940
15884
  } finally {
15941
15885
  rl.close();
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@contextstream/mcp-server",
3
3
  "mcpName": "io.github.contextstreamio/mcp-server",
4
- "version": "0.4.2",
5
- "description": "MCP server exposing ContextStream public API - code context, memory, search, and AI tools for developers",
4
+ "version": "0.4.4",
5
+ "description": "ContextStream MCP server - v0.4.x with consolidated domain tools (~11 tools, ~75% token reduction). Code context, memory, search, and AI tools.",
6
6
  "type": "module",
7
7
  "license": "MIT",
8
8
  "main": "dist/index.js",