@contextstream/mcp-server 0.4.3 → 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 +13 -1
  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
@@ -9077,7 +9077,12 @@ Upgrade: ${upgradeUrl2}` : "";
9077
9077
  } catch {
9078
9078
  }
9079
9079
  console.error(`[ContextStream] Bundle '${bundleName}' enabled with ${toolsEnabled} tools.`);
9080
- 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
+ };
9081
9086
  }
9082
9087
  const ROUTER_DIRECT_TOOLS = /* @__PURE__ */ new Set(["contextstream", "contextstream_help"]);
9083
9088
  function registerTool(name, config, handler) {
@@ -10498,6 +10503,13 @@ This does semantic search on the first message. You only need context_smart on s
10498
10503
  console.error("[ContextStream] Failed to check integration status in session_init:", error);
10499
10504
  }
10500
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
+ };
10501
10513
  const status = typeof result.status === "string" ? result.status : "";
10502
10514
  const workspaceWarning = typeof result.workspace_warning === "string" ? result.workspace_warning : "";
10503
10515
  let text = formatContent(result);
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.3",
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",