@contextstream/mcp-server 0.4.21 → 0.4.23

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 (4) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +403 -399
  3. package/dist/index.js +212 -49
  4. package/package.json +57 -57
package/README.md CHANGED
@@ -1,403 +1,407 @@
1
- # ContextStream MCP Server
2
-
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
-
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
-
7
- **v0.4.x:** Consolidated domain tools (~11 tools) for **~75% lower tool-registry token overhead** vs previous versions.
8
-
9
- ---
10
-
11
- ## Just Ask
12
-
13
- **You don't need to memorize tool names.** Describe what you want and your AI will call the right ContextStream tools:
14
-
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 |
22
-
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
25
-
26
- ![ContextStream in action](compare1.gif)
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
-
44
- ## Features
45
-
46
- - **Consolidated domain tools** (v0.4.x): short tool list with action/mode dispatch
47
- - Session-aware context loading (`session_init`, `context_smart`)
48
- - Memory capture + recall (decisions, preferences, lessons, tasks, bugs)
49
- - Code search (semantic, hybrid, keyword, pattern)
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
54
-
55
- ---
56
-
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
- ---
65
-
66
- ## Requirements
67
-
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
- ---
75
-
76
- ## Quickstart (2 minutes)
77
-
78
- ### 1) Run the Setup Wizard (recommended)
79
-
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
85
-
86
- ```bash
87
- npx -y @contextstream/mcp-server setup
88
- ```
89
-
90
- **Useful flags:**
91
-
92
- | Flag | Description |
93
- |------|-------------|
94
- | `--dry-run` | Preview without writing files |
95
-
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):
104
-
105
- ```bash
106
- npx -y @contextstream/mcp-server
107
- ```
108
-
109
- **Or install globally:**
110
-
111
- ```bash
112
- npm install -g @contextstream/mcp-server
113
- contextstream-mcp
114
- ```
115
-
116
- ### 3) Keeping Updated
117
-
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:**
122
-
123
- ```bash
124
- npm update -g @contextstream/mcp-server
125
- ```
126
-
127
- After updating, restart your AI tool/editor so it reloads the tool catalog.
128
-
129
- ---
130
-
131
- ## Configure Your MCP Client (Manual)
132
-
133
- > If you ran the setup wizard, you can usually skip this.
134
-
135
- ### Cursor / Windsurf / Claude Desktop (JSON)
136
-
137
- These clients use an `mcpServers` JSON config:
138
-
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` |
145
-
146
- **Consolidated (default):**
147
-
148
- ```json
149
- {
150
- "mcpServers": {
151
- "contextstream": {
152
- "command": "npx",
153
- "args": ["-y", "@contextstream/mcp-server"],
154
- "env": {
155
- "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
156
- "CONTEXTSTREAM_API_KEY": "YOUR_API_KEY"
157
- }
158
- }
159
- }
160
- }
161
- ```
162
-
163
- **Router mode (~2 meta-tools):**
164
-
165
- ```json
166
- {
167
- "mcpServers": {
168
- "contextstream": {
169
- "command": "npx",
170
- "args": ["-y", "@contextstream/mcp-server"],
171
- "env": {
172
- "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
173
- "CONTEXTSTREAM_API_KEY": "YOUR_API_KEY",
174
- "CONTEXTSTREAM_PROGRESSIVE_MODE": "true"
175
- }
176
- }
177
- }
178
- }
179
- ```
180
-
181
- ### VS Code (`.vscode/mcp.json`)
182
-
183
- VS Code uses a top-level `servers` map:
184
-
185
- ```json
186
- {
187
- "servers": {
188
- "contextstream": {
189
- "type": "stdio",
190
- "command": "npx",
191
- "args": ["-y", "@contextstream/mcp-server"],
192
- "env": {
193
- "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
194
- "CONTEXTSTREAM_API_KEY": "YOUR_API_KEY"
195
- }
196
- }
197
- }
198
- }
199
- ```
200
-
201
- **Strong recommendation:** Use `inputs` so you don't commit secrets:
202
-
203
- ```json
204
- {
205
- "servers": {
206
- "contextstream": {
207
- "type": "stdio",
208
- "command": "npx",
209
- "args": ["-y", "@contextstream/mcp-server"],
210
- "env": {
211
- "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
212
- "CONTEXTSTREAM_API_KEY": "${input:contextstreamApiKey}"
213
- }
214
- }
215
- },
216
- "inputs": [
217
- {
218
- "id": "contextstreamApiKey",
219
- "type": "promptString",
220
- "description": "ContextStream API Key",
221
- "password": true
222
- }
223
- ]
224
- }
225
- ```
226
-
227
- ### Claude Code (CLI)
228
-
229
- **User scope (all projects):**
230
-
231
- ```bash
232
- claude mcp add --transport stdio contextstream --scope user \
233
- --env CONTEXTSTREAM_API_URL=https://api.contextstream.io \
234
- --env CONTEXTSTREAM_API_KEY=YOUR_KEY \
235
- -- npx -y @contextstream/mcp-server
236
- ```
237
-
238
- **Router mode:**
239
-
240
- ```bash
241
- claude mcp add --transport stdio contextstream --scope user \
242
- --env CONTEXTSTREAM_API_URL=https://api.contextstream.io \
243
- --env CONTEXTSTREAM_API_KEY=YOUR_KEY \
244
- --env CONTEXTSTREAM_PROGRESSIVE_MODE=true \
245
- -- npx -y @contextstream/mcp-server
246
- ```
247
-
248
- > **Windows caveat** (native Windows, not WSL): if `npx` isn't found, use `cmd /c npx -y @contextstream/mcp-server` after `--`.
249
-
250
- ### Codex CLI (`~/.codex/config.toml`)
251
-
252
- ```toml
253
- [mcp_servers.contextstream]
254
- command = "npx"
255
- args = ["-y", "@contextstream/mcp-server"]
256
-
257
- [mcp_servers.contextstream.env]
258
- CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
259
- CONTEXTSTREAM_API_KEY = "YOUR_API_KEY"
260
- ```
261
-
262
- ---
263
-
264
- ## Tool Overview (v0.4.x Consolidated)
265
-
266
- In consolidated mode, you call **domain tools** with `action` / `mode`:
267
-
268
- ### Core
269
-
270
- | Tool | Description |
271
- |------|-------------|
272
- | `session_init` | Initialize workspace/project context |
273
- | `context_smart` | Retrieve the best bounded context for the current message |
274
-
275
- ### Domain Tools
276
-
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
-
289
- ### Examples
290
-
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
- ```
296
-
297
- **Full tool catalog:** https://contextstream.io/docs/mcp/tools
298
-
299
- ---
300
-
301
- ## Authentication
302
-
303
- Set **one** of:
304
-
305
- | Variable | Use case |
306
- |----------|----------|
307
- | `CONTEXTSTREAM_API_KEY` | Recommended for local/dev |
308
- | `CONTEXTSTREAM_JWT` | Useful for hosted/user-session flows |
309
-
310
- ---
311
-
312
- ## Environment Variables
313
-
314
- ### Required
315
-
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) |
321
-
322
- ### Token + Tool Surface Controls
323
-
324
- | Variable | Description |
325
- |----------|-------------|
1
+ # ContextStream MCP Server
2
+
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
+
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
+
7
+ **v0.4.x:** Consolidated domain tools (~11 tools) for **~75% lower tool-registry token overhead** vs previous versions.
8
+
9
+ ---
10
+
11
+ ## Just Ask
12
+
13
+ **You don't need to memorize tool names.** Describe what you want and your AI will call the right ContextStream tools:
14
+
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 |
22
+
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
25
+
26
+ ![ContextStream in action](compare1.gif)
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
+
44
+ ## Features
45
+
46
+ - **Consolidated domain tools** (v0.4.x): short tool list with action/mode dispatch
47
+ - Session-aware context loading (`session_init`, `context_smart`)
48
+ - Memory capture + recall (decisions, preferences, lessons, tasks, bugs)
49
+ - Code search (semantic, hybrid, keyword, pattern)
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
54
+
55
+ > **⚠️ Search-First Rule:** For best results, your AI should use ContextStream `search(mode="hybrid")` **before** local tools like Glob/Grep/Read. This is enforced via editor rules and `context_smart` responses.
56
+
57
+ ---
58
+
59
+ ## Graph Tiers
60
+
61
+ | Tier | Capabilities |
62
+ |------|--------------|
63
+ | **Pro (Graph-Lite)** | Module-level import graph, dependencies, and 1-hop impact |
64
+ | **Elite/Team (Full Graph)** | Module + call + dataflow + type layers, plus full graph ingestion |
65
+
66
+ ---
67
+
68
+ ## Requirements
69
+
70
+ - **Node.js 18+**
71
+ - A **ContextStream account**
72
+ - Auth via **API key** or **JWT**
73
+
74
+ Default API URL: `https://api.contextstream.io`
75
+
76
+ ---
77
+
78
+ ## Quickstart (2 minutes)
79
+
80
+ ### 1) Run the Setup Wizard (recommended)
81
+
82
+ The wizard:
83
+ - Authenticates (browser/device login by default)
84
+ - Creates/stores an API key
85
+ - Installs recommended editor rules (optional)
86
+ - Writes MCP config files for supported tools
87
+
88
+ ```bash
89
+ npx -y @contextstream/mcp-server setup
90
+ ```
91
+
92
+ **Useful flags:**
93
+
94
+ | Flag | Description |
95
+ |------|-------------|
96
+ | `--dry-run` | Preview without writing files |
97
+
98
+ **Notes:**
99
+ - The wizard stores credentials at `~/.contextstream/credentials.json` for convenience. Delete it to force a fresh login.
100
+ - Codex CLI MCP config is global-only (`~/.codex/config.toml`), so the wizard writes Codex config globally when selected.
101
+ - Some tools still require UI/CLI setup (the wizard will tell you when it can't write a config).
102
+
103
+ ### 2) Run the MCP Server
104
+
105
+ **Recommended** (works well with MCP configs):
106
+
107
+ ```bash
108
+ npx -y @contextstream/mcp-server
109
+ ```
110
+
111
+ **Or install globally:**
112
+
113
+ ```bash
114
+ npm install -g @contextstream/mcp-server
115
+ contextstream-mcp
116
+ ```
117
+
118
+ ### 3) Keeping Updated
119
+
120
+ **If you use `npx`:** Restart your AI tool/editor and run ContextStream again
121
+ (or pin the version: `npx -y @contextstream/mcp-server@0.4.3`)
122
+
123
+ **If you installed globally:**
124
+
125
+ ```bash
126
+ npm update -g @contextstream/mcp-server
127
+ ```
128
+
129
+ After updating, restart your AI tool/editor so it reloads the tool catalog.
130
+
131
+ ---
132
+
133
+ ## Configure Your MCP Client (Manual)
134
+
135
+ > If you ran the setup wizard, you can usually skip this.
136
+
137
+ ### Cursor / Windsurf / Claude Desktop (JSON)
138
+
139
+ These clients use an `mcpServers` JSON config:
140
+
141
+ | Client | Config path |
142
+ |--------|-------------|
143
+ | **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) |
144
+ | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
145
+ | **Claude Desktop (macOS)** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
146
+ | **Claude Desktop (Windows)** | `%APPDATA%\Claude\claude_desktop_config.json` |
147
+
148
+ **Consolidated (default):**
149
+
150
+ ```json
151
+ {
152
+ "mcpServers": {
153
+ "contextstream": {
154
+ "command": "npx",
155
+ "args": ["-y", "@contextstream/mcp-server"],
156
+ "env": {
157
+ "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
158
+ "CONTEXTSTREAM_API_KEY": "YOUR_API_KEY"
159
+ }
160
+ }
161
+ }
162
+ }
163
+ ```
164
+
165
+ **Router mode (~2 meta-tools):**
166
+
167
+ ```json
168
+ {
169
+ "mcpServers": {
170
+ "contextstream": {
171
+ "command": "npx",
172
+ "args": ["-y", "@contextstream/mcp-server"],
173
+ "env": {
174
+ "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
175
+ "CONTEXTSTREAM_API_KEY": "YOUR_API_KEY",
176
+ "CONTEXTSTREAM_PROGRESSIVE_MODE": "true"
177
+ }
178
+ }
179
+ }
180
+ }
181
+ ```
182
+
183
+ ### VS Code (`.vscode/mcp.json`)
184
+
185
+ VS Code uses a top-level `servers` map:
186
+
187
+ ```json
188
+ {
189
+ "servers": {
190
+ "contextstream": {
191
+ "type": "stdio",
192
+ "command": "npx",
193
+ "args": ["-y", "@contextstream/mcp-server"],
194
+ "env": {
195
+ "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
196
+ "CONTEXTSTREAM_API_KEY": "YOUR_API_KEY"
197
+ }
198
+ }
199
+ }
200
+ }
201
+ ```
202
+
203
+ **Strong recommendation:** Use `inputs` so you don't commit secrets:
204
+
205
+ ```json
206
+ {
207
+ "servers": {
208
+ "contextstream": {
209
+ "type": "stdio",
210
+ "command": "npx",
211
+ "args": ["-y", "@contextstream/mcp-server"],
212
+ "env": {
213
+ "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
214
+ "CONTEXTSTREAM_API_KEY": "${input:contextstreamApiKey}"
215
+ }
216
+ }
217
+ },
218
+ "inputs": [
219
+ {
220
+ "id": "contextstreamApiKey",
221
+ "type": "promptString",
222
+ "description": "ContextStream API Key",
223
+ "password": true
224
+ }
225
+ ]
226
+ }
227
+ ```
228
+
229
+ ### Claude Code (CLI)
230
+
231
+ **User scope (all projects):**
232
+
233
+ ```bash
234
+ claude mcp add --transport stdio contextstream --scope user \
235
+ --env CONTEXTSTREAM_API_URL=https://api.contextstream.io \
236
+ --env CONTEXTSTREAM_API_KEY=YOUR_KEY \
237
+ -- npx -y @contextstream/mcp-server
238
+ ```
239
+
240
+ **Router mode:**
241
+
242
+ ```bash
243
+ claude mcp add --transport stdio contextstream --scope user \
244
+ --env CONTEXTSTREAM_API_URL=https://api.contextstream.io \
245
+ --env CONTEXTSTREAM_API_KEY=YOUR_KEY \
246
+ --env CONTEXTSTREAM_PROGRESSIVE_MODE=true \
247
+ -- npx -y @contextstream/mcp-server
248
+ ```
249
+
250
+ > **Windows caveat** (native Windows, not WSL): if `npx` isn't found, use `cmd /c npx -y @contextstream/mcp-server` after `--`.
251
+
252
+ ### Codex CLI (`~/.codex/config.toml`)
253
+
254
+ ```toml
255
+ [mcp_servers.contextstream]
256
+ command = "npx"
257
+ args = ["-y", "@contextstream/mcp-server"]
258
+
259
+ [mcp_servers.contextstream.env]
260
+ CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
261
+ CONTEXTSTREAM_API_KEY = "YOUR_API_KEY"
262
+ ```
263
+
264
+ ---
265
+
266
+ ## Tool Overview (v0.4.x Consolidated)
267
+
268
+ In consolidated mode, you call **domain tools** with `action` / `mode`:
269
+
270
+ ### Core
271
+
272
+ | Tool | Description |
273
+ |------|-------------|
274
+ | `session_init` | Initialize workspace/project context |
275
+ | `context_smart` | Retrieve the best bounded context for the current message |
276
+
277
+ ### Domain Tools
278
+
279
+ | Tool | Description |
280
+ |------|-------------|
281
+ | `search` | `mode=semantic\|hybrid\|keyword\|pattern` |
282
+ | `session` | `action=capture\|recall\|remember\|get_lessons\|capture_lesson\|...` |
283
+ | `memory` | Events + nodes CRUD, decisions, lessons, etc. |
284
+ | `graph` | Dependencies, impact, call_path, ingest, etc. |
285
+ | `project` | Indexing, ingest_local, stats, files, etc. |
286
+ | `workspace` | List, get, associate, bootstrap |
287
+ | `reminder` | List, create, snooze, complete, dismiss |
288
+ | `integration` | `provider=slack\|github`, search, activity, etc. |
289
+ | `help` | Tools, auth, version, editor_rules |
290
+
291
+ ### Examples
292
+
293
+ ```
294
+ search(mode="semantic", query="auth middleware", limit=3)
295
+ memory(action="create_node", node_type="decision", title="Auth strategy", content="...")
296
+ graph(action="impact", target="UserService")
297
+ ```
298
+
299
+ **Full tool catalog:** https://contextstream.io/docs/mcp/tools
300
+
301
+ ---
302
+
303
+ ## Authentication
304
+
305
+ Set **one** of:
306
+
307
+ | Variable | Use case |
308
+ |----------|----------|
309
+ | `CONTEXTSTREAM_API_KEY` | Recommended for local/dev |
310
+ | `CONTEXTSTREAM_JWT` | Useful for hosted/user-session flows |
311
+
312
+ ---
313
+
314
+ ## Environment Variables
315
+
316
+ ### Required
317
+
318
+ | Variable | Description |
319
+ |----------|-------------|
320
+ | `CONTEXTSTREAM_API_URL` | Base API URL (default `https://api.contextstream.io`) |
321
+ | `CONTEXTSTREAM_API_KEY` | API key (unless using JWT) |
322
+ | `CONTEXTSTREAM_JWT` | JWT (unless using API key) |
323
+
324
+ ### Token + Tool Surface Controls
325
+
326
+ | Variable | Description |
327
+ |----------|-------------|
326
328
  | `CONTEXTSTREAM_CONSOLIDATED` | `true` (default in v0.4.x) uses consolidated domain tools |
327
329
  | `CONTEXTSTREAM_PROGRESSIVE_MODE` | Enables Router mode (~2 meta-tools) |
328
330
  | `CONTEXTSTREAM_CONTEXT_PACK` | Enable Context Pack for `context_smart` (code + graph + distill). Defaults to `true` |
329
331
  | `CONTEXTSTREAM_TOOLSET` | Legacy granular tool bundle: `light` / `standard` / `complete` (only when consolidated is off) |
330
- | `CONTEXTSTREAM_TOOL_ALLOWLIST` | Comma-separated tool names to expose (legacy granular mode) |
331
- | `CONTEXTSTREAM_SCHEMA_MODE` | Reduce schema verbosity; e.g., `compact` |
332
- | `CONTEXTSTREAM_OUTPUT_FORMAT` | Output formatting; e.g., `compact` / `pretty` |
333
-
334
- ### Optional Defaults
335
-
336
- | Variable | Description |
337
- |----------|-------------|
338
- | `CONTEXTSTREAM_WORKSPACE_ID` | Default workspace fallback |
339
- | `CONTEXTSTREAM_PROJECT_ID` | Default project ID fallback |
340
- | `CONTEXTSTREAM_USER_AGENT` | Custom user agent string |
341
- | `CONTEXTSTREAM_PRO_TOOLS` | Comma-separated tool names treated as PRO |
342
- | `CONTEXTSTREAM_UPGRADE_URL` | Upgrade link for Free users calling PRO tools |
343
-
344
- ---
345
-
346
- ## Migration Notes (pre-0.4.x → 0.4.x)
347
-
348
- Most workflows **just work**, but tool names change in consolidated mode.
349
-
350
- | Before (granular) | After (consolidated) |
351
- |-------------------|----------------------|
352
- | `search_semantic(query="auth")` | `search(mode="semantic", query="auth")` |
353
- | `session_capture(...)` | `session(action="capture", ...)` |
354
- | `graph_dependencies(...)` | `graph(action="dependencies", ...)` |
355
-
356
- If you rely on granular tool names, you can temporarily set:
357
-
358
- ```bash
359
- CONTEXTSTREAM_CONSOLIDATED=false
360
- ```
361
-
362
- ---
363
-
364
- ## Troubleshooting
365
-
366
- | Issue | Solution |
367
- |-------|----------|
368
- | **Tools not appearing** | Restart the client after editing MCP config; confirm Node 18+ is available in the client runtime |
369
- | **Unauthorized / 401** | Verify `CONTEXTSTREAM_API_URL` + `CONTEXTSTREAM_API_KEY` (or JWT) |
370
- | **Wrong workspace/project** | Run `session_init` and/or associate your folder with the correct workspace |
371
- | **Client warns about tool context size** | Use Router mode (`CONTEXTSTREAM_PROGRESSIVE_MODE=true`), or keep consolidated mode and reduce schema/output verbosity |
372
-
373
- ---
374
-
375
- ## Development
376
-
377
- ```bash
378
- git clone https://github.com/contextstream/mcp-server.git
379
- cd mcp-server
380
- npm install
381
- npm run dev
382
- npm run typecheck
383
- npm run build
384
- ```
385
-
386
- ---
387
-
388
- ## Links
389
-
390
- | Resource | URL |
391
- |----------|-----|
392
- | **Website** | https://contextstream.io |
393
- | **Docs** | https://contextstream.io/docs/mcp |
394
- | **Tool Catalog** | https://contextstream.io/docs/mcp/tools |
395
- | **Pricing** | https://contextstream.io/pricing |
396
- | **npm** | https://www.npmjs.com/package/@contextstream/mcp-server |
397
- | **GitHub** | https://github.com/contextstream/mcp-server |
398
-
399
- ---
400
-
401
- ## License
402
-
403
- MIT
332
+ | `CONTEXTSTREAM_TOOL_ALLOWLIST` | Comma-separated tool names to expose (legacy granular mode) |
333
+ | `CONTEXTSTREAM_SCHEMA_MODE` | Reduce schema verbosity; e.g., `compact` |
334
+ | `CONTEXTSTREAM_OUTPUT_FORMAT` | Output formatting; e.g., `compact` / `pretty` |
335
+ | `CONTEXTSTREAM_SEARCH_LIMIT` | Default MCP search limit (default: 3) |
336
+ | `CONTEXTSTREAM_SEARCH_MAX_CHARS` | Max chars per search result content (default: 400) |
337
+
338
+ ### Optional Defaults
339
+
340
+ | Variable | Description |
341
+ |----------|-------------|
342
+ | `CONTEXTSTREAM_WORKSPACE_ID` | Default workspace fallback |
343
+ | `CONTEXTSTREAM_PROJECT_ID` | Default project ID fallback |
344
+ | `CONTEXTSTREAM_USER_AGENT` | Custom user agent string |
345
+ | `CONTEXTSTREAM_PRO_TOOLS` | Comma-separated tool names treated as PRO |
346
+ | `CONTEXTSTREAM_UPGRADE_URL` | Upgrade link for Free users calling PRO tools |
347
+
348
+ ---
349
+
350
+ ## Migration Notes (pre-0.4.x → 0.4.x)
351
+
352
+ Most workflows **just work**, but tool names change in consolidated mode.
353
+
354
+ | Before (granular) | After (consolidated) |
355
+ |-------------------|----------------------|
356
+ | `search_semantic(query="auth")` | `search(mode="semantic", query="auth")` |
357
+ | `session_capture(...)` | `session(action="capture", ...)` |
358
+ | `graph_dependencies(...)` | `graph(action="dependencies", ...)` |
359
+
360
+ If you rely on granular tool names, you can temporarily set:
361
+
362
+ ```bash
363
+ CONTEXTSTREAM_CONSOLIDATED=false
364
+ ```
365
+
366
+ ---
367
+
368
+ ## Troubleshooting
369
+
370
+ | Issue | Solution |
371
+ |-------|----------|
372
+ | **Tools not appearing** | Restart the client after editing MCP config; confirm Node 18+ is available in the client runtime |
373
+ | **Unauthorized / 401** | Verify `CONTEXTSTREAM_API_URL` + `CONTEXTSTREAM_API_KEY` (or JWT) |
374
+ | **Wrong workspace/project** | Run `session_init` and/or associate your folder with the correct workspace |
375
+ | **Client warns about tool context size** | Use Router mode (`CONTEXTSTREAM_PROGRESSIVE_MODE=true`), or keep consolidated mode and reduce schema/output verbosity |
376
+
377
+ ---
378
+
379
+ ## Development
380
+
381
+ ```bash
382
+ git clone https://github.com/contextstream/mcp-server.git
383
+ cd mcp-server
384
+ npm install
385
+ npm run dev
386
+ npm run typecheck
387
+ npm run build
388
+ ```
389
+
390
+ ---
391
+
392
+ ## Links
393
+
394
+ | Resource | URL |
395
+ |----------|-----|
396
+ | **Website** | https://contextstream.io |
397
+ | **Docs** | https://contextstream.io/docs/mcp |
398
+ | **Tool Catalog** | https://contextstream.io/docs/mcp/tools |
399
+ | **Pricing** | https://contextstream.io/pricing |
400
+ | **npm** | https://www.npmjs.com/package/@contextstream/mcp-server |
401
+ | **GitHub** | https://github.com/contextstream/mcp-server |
402
+
403
+ ---
404
+
405
+ ## License
406
+
407
+ MIT