@contextstream/mcp-server 0.4.28 → 0.4.30

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