@contextstream/mcp-server 0.3.67 → 0.3.68

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 ContextStream
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 ContextStream
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,390 +1,390 @@
-# ContextStream MCP Server
-
-Persistent memory, semantic search, and code intelligence for any MCP-compatible AI tool.
-
-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.
-
-## Just Ask
-
-**You don't need to memorize tool names.** Just describe what you want and your AI uses the right ContextStream tools automatically:
-
-| You say... | ContextStream does... |
-|------------|----------------------|
-| "session summary" | Gets a summary of your workspace context |
-| "what did we decide about auth?" | Recalls past decisions about authentication |
-| "remember we're using PostgreSQL" | Saves this to memory for future sessions |
-| "search for payment code" | Searches your codebase semantically |
-| "what depends on UserService?" | Analyzes code dependencies |
-
-No special syntax. No commands to learn. Just ask.
-
-> **Tip:** For best results, add the [recommended editor rules](https://contextstream.io/docs/quickstart) so your AI consistently calls `session_init` / `context_smart` automatically.
-
-![ContextStream in action](compare1.gif)
-
-## Features
-
-- Session-aware context loading (`session_init`, `context_smart`)
-- Memory capture and recall (decisions, preferences, tasks, bugs, lessons)
-- Code search (semantic, hybrid, keyword, pattern)
-- Knowledge graph and code analysis (dependencies, impact, call paths, circular deps, unused code)
-- Graph ingestion for full graph builds (`graph_ingest`)
-- Local repo ingestion for indexing (`projects_ingest_local`)
-- Auto-context: on the first tool call in a new session, the server can auto-initialize context
-
-## Graph tiers
-
-- **Pro (Graph-Lite):** module-level import graph, dependencies, and 1-hop impact
-- **Elite/Team (Full Graph):** module + call + dataflow + type layers, plus `graph_ingest`
-
-## Requirements
-
-- Node.js 18+
-- A ContextStream account and either an API key or a JWT
-
-## Quickstart
-
-### Setup wizard (recommended)
-
-This interactive wizard sets up authentication, installs editor rules, and writes MCP config files for the tools you select.
-
-```bash
-npx -y @contextstream/mcp-server setup
-```
-
-Notes:
-- Uses browser/device login by default and creates an API key for you.
-- Prompts for **toolset selection**: `light` (~30 tools), `standard` (default, ~50 tools), or `complete` (~86 tools including workspaces, projects, search, memory, graph, AI, and integrations).
-- 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.
-- Codex CLI MCP config is global-only (`~/.codex/config.toml`), so the wizard will always write Codex config globally when selected.
-- Some tools still require UI/CLI-based MCP setup (the wizard will tell you when it can't write a config).
-- Preview changes without writing files: `npx -y @contextstream/mcp-server setup --dry-run`
-
-### Run the server
-
-Run directly (recommended for MCP configs):
-
-```bash
-npx -y @contextstream/mcp-server
-```
-
-Or install globally:
-
-```bash
-npm install -g @contextstream/mcp-server
-contextstream-mcp
-```
-
-### Keeping updated
-
-To get the latest features and bug fixes, update periodically:
-
-```bash
-npm update -g @contextstream/mcp-server
-```
-
-The MCP server will warn you when a newer version is available. After updating, restart your AI tool to use the new version.
-
-## Configure your MCP client
-
-### Manual setup
-
-If you ran the [setup wizard](#setup-wizard-recommended), you can usually skip this section.
-
-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.
-
-**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).
-
-### Cursor / Windsurf / Claude Desktop (JSON)
-
-These clients use the `mcpServers` JSON schema:
-
-- Cursor: `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project)
-- Windsurf: `~/.codeium/windsurf/mcp_config.json`
-- Claude Desktop:
-  - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-  - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`
-
-Many other MCP JSON clients also use this same `mcpServers` shape (including Claude Code project scope via `.mcp.json`).
-
-**Standard toolset (default, ~50 tools):**
-
-```json
-{
-  "mcpServers": {
-    "contextstream": {
-      "command": "npx",
-      "args": ["-y", "@contextstream/mcp-server"],
-      "env": {
-        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
-        "CONTEXTSTREAM_API_KEY": "your_api_key"
-      }
-    }
-  }
-}
-```
-
-**Complete toolset (~86 tools):**
-
-```json
-{
-  "mcpServers": {
-    "contextstream": {
-      "command": "npx",
-      "args": ["-y", "@contextstream/mcp-server"],
-      "env": {
-        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
-        "CONTEXTSTREAM_API_KEY": "your_api_key",
-        "CONTEXTSTREAM_TOOLSET": "complete"
-      }
-    }
-  }
-}
-```
-
-### VS Code (`.vscode/mcp.json`)
-
-VS Code uses a different schema with a top-level `servers` map:
-
-**Core toolset (default):**
-
-```json
-{
-  "servers": {
-    "contextstream": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@contextstream/mcp-server"],
-      "env": {
-        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
-        "CONTEXTSTREAM_API_KEY": "your_api_key"
-      }
-    }
-  }
-}
-```
-
-**Complete toolset (~86 tools):**
-
-```json
-{
-  "servers": {
-    "contextstream": {
-      "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"
-      }
-    }
-  }
-}
-```
-
-Strong recommendation: VS Code supports `inputs` so you don’t have to hardcode secrets in a committed file:
-
-```json
-{
-  "servers": {
-    "contextstream": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@contextstream/mcp-server"],
-      "env": {
-        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
-        "CONTEXTSTREAM_API_KEY": "${input:contextstreamApiKey}"
-      }
-    }
-  },
-  "inputs": [
-    {
-      "id": "contextstreamApiKey",
-      "type": "promptString",
-      "description": "ContextStream API Key",
-      "password": true
-    }
-  ]
-}
-```
-
-### Claude Code (CLI)
-
-User scope (all projects):
-
-**Standard toolset (default):**
-
-```bash
-claude mcp add --transport stdio contextstream --scope user \
-  --env CONTEXTSTREAM_API_URL=https://api.contextstream.io \
-  --env CONTEXTSTREAM_API_KEY=YOUR_KEY \
-  -- npx -y @contextstream/mcp-server
-```
-
-**Complete toolset (~86 tools):**
-
-```bash
-claude mcp add --transport stdio contextstream --scope user \
-  --env CONTEXTSTREAM_API_URL=https://api.contextstream.io \
-  --env CONTEXTSTREAM_API_KEY=YOUR_KEY \
-  --env CONTEXTSTREAM_TOOLSET=complete \
-  -- npx -y @contextstream/mcp-server
-```
-
-Note: Claude Code may warn about large tool contexts when using `complete`. The default is `standard` (~50 tools). Use `light` for fewer tools.
-
-Windows caveat (native Windows, not WSL): if `npx` isn't found, use `cmd /c npx -y @contextstream/mcp-server` after `--`.
-
-**Alternative (JSON form):**
-
-Standard:
-```bash
-claude mcp add-json contextstream \
-'{"type":"stdio","command":"npx","args":["-y","@contextstream/mcp-server"],"env":{"CONTEXTSTREAM_API_URL":"https://api.contextstream.io","CONTEXTSTREAM_API_KEY":"your_api_key"}}'
-```
-
-Complete:
-```bash
-claude mcp add-json contextstream \
-'{"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"}}'
-```
-
-### Codex CLI (`~/.codex/config.toml`)
-
-**Standard toolset (default):**
-
-```toml
-[mcp_servers.contextstream]
-command = "npx"
-args = ["-y", "@contextstream/mcp-server"]
-
-[mcp_servers.contextstream.env]
-CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
-CONTEXTSTREAM_API_KEY = "your_api_key"
-```
-
-**Complete toolset (~86 tools):**
-
-```toml
-[mcp_servers.contextstream]
-command = "npx"
-args = ["-y", "@contextstream/mcp-server"]
-
-[mcp_servers.contextstream.env]
-CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
-CONTEXTSTREAM_API_KEY = "your_api_key"
-CONTEXTSTREAM_TOOLSET = "complete"
-```
-
-After editing, restart your MCP client so it reloads the server configuration.
-
-## Authentication
-
-You can authenticate using either:
-
-- `CONTEXTSTREAM_API_KEY` (recommended for local/dev)
-- `CONTEXTSTREAM_JWT` (useful for hosted or user-session flows)
-
-## Environment variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `CONTEXTSTREAM_API_URL` | Yes | Base API URL (e.g. `https://api.contextstream.io`) |
-| `CONTEXTSTREAM_API_KEY` | Yes* | API key (*required unless `CONTEXTSTREAM_JWT` is set) |
-| `CONTEXTSTREAM_JWT` | Yes* | JWT (*required unless `CONTEXTSTREAM_API_KEY` is set) |
-| `CONTEXTSTREAM_WORKSPACE_ID` | No | Default workspace ID fallback |
-| `CONTEXTSTREAM_PROJECT_ID` | No | Default project ID fallback |
-| `CONTEXTSTREAM_USER_AGENT` | No | Custom user agent string |
-| `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`. |
-| `CONTEXTSTREAM_TOOL_ALLOWLIST` | No | Comma-separated tool names to expose (overrides toolset) |
-| `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`) |
-| `CONTEXTSTREAM_UPGRADE_URL` | No | Upgrade link shown when Free users call PRO tools (default: `https://contextstream.io/pricing`) |
-
-### Server-side environment variables (API)
-
-The following environment variables are configured on the ContextStream API server (not in your MCP client config):
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `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. |
-
-#### File write parameters for `projects_ingest_local`
-
-The `projects_ingest_local` tool accepts two optional parameters for QA/testing scenarios:
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `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. |
-| `overwrite` | boolean | `false` | When `true` (and `write_to_disk` is enabled), allows overwriting existing files. Otherwise, existing files are skipped. |
-
-**Example usage:**
-```json
-{
-  "path": "/path/to/local/project",
-  "write_to_disk": true,
-  "overwrite": false
-}
-```
-
-**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.
-
-## Usage patterns
-
-### Recommended flow for AI tools
-
-1. Start of a conversation: call `session_init(folder_path="...", context_hint="<first user message>")`
-2. Before subsequent responses: call `context_smart(user_message="<current user message>")`
-3. After important outcomes: call `session_capture(...)` or `session_capture_lesson(...)`
-
-### Omit workspace/project IDs (recommended)
-
-Most tools accept omitted `workspace_id` / `project_id` and will use the current session defaults.
-
-- If you see “workspace_id is required”, call `session_init` first (or pass the ID explicitly).
-- If you regularly work in the same repo, use `workspace_associate` once so the server can auto-select the right workspace for that folder.
-
-### First-time setup (no workspaces yet)
-
-If your account has no workspaces, ContextStream will prompt your AI assistant to ask you for a workspace name.
-
-- Provide a workspace name (e.g., your company/team/product)
-- The current folder is created as a project inside that workspace
-- Recommended: call `workspace_bootstrap(workspace_name="...", folder_path="...")`
-
-## Free vs PRO tools
-
-Tools are labeled as `(Free)` or `(PRO)` in the MCP tool list.
-
-- Default PRO tools: `ai_context`, `ai_enhanced_context`, `ai_context_budget`, `ai_embeddings`, `ai_plan`, `ai_tasks`
-- If a Free-plan user calls a PRO tool, the server returns an upgrade message with a link.
-- Override the PRO list via `CONTEXTSTREAM_PRO_TOOLS` and the upgrade link via `CONTEXTSTREAM_UPGRADE_URL`.
-
-## Troubleshooting
-
-- Tools not appearing: restart the client after editing MCP config; confirm Node 18+ is available to the client runtime.
-- Unauthorized errors: verify `CONTEXTSTREAM_API_URL` and `CONTEXTSTREAM_API_KEY` (or `CONTEXTSTREAM_JWT`).
-- Wrong workspace/project: use `workspace_associate` to map the current repo folder to the correct workspace.
-
-## Development
-
-```bash
-git clone https://github.com/contextstream/mcp-server.git
-cd mcp-server
-npm install
-npm run dev
-npm run typecheck
-npm run build
-```
-
-## Links
-
-- Website: https://contextstream.io
-- Docs: https://contextstream.io/docs/mcp
-- Pricing: https://contextstream.io/pricing
-- npm: https://www.npmjs.com/package/@contextstream/mcp-server
-- GitHub: https://github.com/contextstream/mcp-server
-
-## License
-
-MIT
+# ContextStream MCP Server
+
+Persistent memory, semantic search, and code intelligence for any MCP-compatible AI tool.
+
+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.
+
+## Just Ask
+
+**You don't need to memorize tool names.** Just describe what you want and your AI uses the right ContextStream tools automatically:
+
+| You say... | ContextStream does... |
+|------------|----------------------|
+| "session summary" | Gets a summary of your workspace context |
+| "what did we decide about auth?" | Recalls past decisions about authentication |
+| "remember we're using PostgreSQL" | Saves this to memory for future sessions |
+| "search for payment code" | Searches your codebase semantically |
+| "what depends on UserService?" | Analyzes code dependencies |
+
+No special syntax. No commands to learn. Just ask.
+
+> **Tip:** For best results, add the [recommended editor rules](https://contextstream.io/docs/quickstart) so your AI consistently calls `session_init` / `context_smart` automatically.
+
+![ContextStream in action](compare1.gif)
+
+## Features
+
+- Session-aware context loading (`session_init`, `context_smart`)
+- Memory capture and recall (decisions, preferences, tasks, bugs, lessons)
+- Code search (semantic, hybrid, keyword, pattern)
+- Knowledge graph and code analysis (dependencies, impact, call paths, circular deps, unused code)
+- Graph ingestion for full graph builds (`graph_ingest`)
+- Local repo ingestion for indexing (`projects_ingest_local`)
+- Auto-context: on the first tool call in a new session, the server can auto-initialize context
+
+## Graph tiers
+
+- **Pro (Graph-Lite):** module-level import graph, dependencies, and 1-hop impact
+- **Elite/Team (Full Graph):** module + call + dataflow + type layers, plus `graph_ingest`
+
+## Requirements
+
+- Node.js 18+
+- A ContextStream account and either an API key or a JWT
+
+## Quickstart
+
+### Setup wizard (recommended)
+
+This interactive wizard sets up authentication, installs editor rules, and writes MCP config files for the tools you select.
+
+```bash
+npx -y @contextstream/mcp-server setup
+```
+
+Notes:
+- Uses browser/device login by default and creates an API key for you.
+- Prompts for **toolset selection**: `light` (~30 tools), `standard` (default, ~50 tools), or `complete` (~86 tools including workspaces, projects, search, memory, graph, AI, and integrations).
+- 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.
+- Codex CLI MCP config is global-only (`~/.codex/config.toml`), so the wizard will always write Codex config globally when selected.
+- Some tools still require UI/CLI-based MCP setup (the wizard will tell you when it can't write a config).
+- Preview changes without writing files: `npx -y @contextstream/mcp-server setup --dry-run`
+
+### Run the server
+
+Run directly (recommended for MCP configs):
+
+```bash
+npx -y @contextstream/mcp-server
+```
+
+Or install globally:
+
+```bash
+npm install -g @contextstream/mcp-server
+contextstream-mcp
+```
+
+### Keeping updated
+
+To get the latest features and bug fixes, update periodically:
+
+```bash
+npm update -g @contextstream/mcp-server
+```
+
+The MCP server will warn you when a newer version is available. After updating, restart your AI tool to use the new version.
+
+## Configure your MCP client
+
+### Manual setup
+
+If you ran the [setup wizard](#setup-wizard-recommended), you can usually skip this section.
+
+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.
+
+**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).
+
+### Cursor / Windsurf / Claude Desktop (JSON)
+
+These clients use the `mcpServers` JSON schema:
+
+- Cursor: `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project)
+- Windsurf: `~/.codeium/windsurf/mcp_config.json`
+- Claude Desktop:
+  - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+  - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`
+
+Many other MCP JSON clients also use this same `mcpServers` shape (including Claude Code project scope via `.mcp.json`).
+
+**Standard toolset (default, ~50 tools):**
+
+```json
+{
+  "mcpServers": {
+    "contextstream": {
+      "command": "npx",
+      "args": ["-y", "@contextstream/mcp-server"],
+      "env": {
+        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
+        "CONTEXTSTREAM_API_KEY": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+**Complete toolset (~86 tools):**
+
+```json
+{
+  "mcpServers": {
+    "contextstream": {
+      "command": "npx",
+      "args": ["-y", "@contextstream/mcp-server"],
+      "env": {
+        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
+        "CONTEXTSTREAM_API_KEY": "your_api_key",
+        "CONTEXTSTREAM_TOOLSET": "complete"
+      }
+    }
+  }
+}
+```
+
+### VS Code (`.vscode/mcp.json`)
+
+VS Code uses a different schema with a top-level `servers` map:
+
+**Core toolset (default):**
+
+```json
+{
+  "servers": {
+    "contextstream": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@contextstream/mcp-server"],
+      "env": {
+        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
+        "CONTEXTSTREAM_API_KEY": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+**Complete toolset (~86 tools):**
+
+```json
+{
+  "servers": {
+    "contextstream": {
+      "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"
+      }
+    }
+  }
+}
+```
+
+Strong recommendation: VS Code supports `inputs` so you don’t have to hardcode secrets in a committed file:
+
+```json
+{
+  "servers": {
+    "contextstream": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@contextstream/mcp-server"],
+      "env": {
+        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
+        "CONTEXTSTREAM_API_KEY": "${input:contextstreamApiKey}"
+      }
+    }
+  },
+  "inputs": [
+    {
+      "id": "contextstreamApiKey",
+      "type": "promptString",
+      "description": "ContextStream API Key",
+      "password": true
+    }
+  ]
+}
+```
+
+### Claude Code (CLI)
+
+User scope (all projects):
+
+**Standard toolset (default):**
+
+```bash
+claude mcp add --transport stdio contextstream --scope user \
+  --env CONTEXTSTREAM_API_URL=https://api.contextstream.io \
+  --env CONTEXTSTREAM_API_KEY=YOUR_KEY \
+  -- npx -y @contextstream/mcp-server
+```
+
+**Complete toolset (~86 tools):**
+
+```bash
+claude mcp add --transport stdio contextstream --scope user \
+  --env CONTEXTSTREAM_API_URL=https://api.contextstream.io \
+  --env CONTEXTSTREAM_API_KEY=YOUR_KEY \
+  --env CONTEXTSTREAM_TOOLSET=complete \
+  -- npx -y @contextstream/mcp-server
+```
+
+Note: Claude Code may warn about large tool contexts when using `complete`. The default is `standard` (~50 tools). Use `light` for fewer tools.
+
+Windows caveat (native Windows, not WSL): if `npx` isn't found, use `cmd /c npx -y @contextstream/mcp-server` after `--`.
+
+**Alternative (JSON form):**
+
+Standard:
+```bash
+claude mcp add-json contextstream \
+'{"type":"stdio","command":"npx","args":["-y","@contextstream/mcp-server"],"env":{"CONTEXTSTREAM_API_URL":"https://api.contextstream.io","CONTEXTSTREAM_API_KEY":"your_api_key"}}'
+```
+
+Complete:
+```bash
+claude mcp add-json contextstream \
+'{"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"}}'
+```
+
+### Codex CLI (`~/.codex/config.toml`)
+
+**Standard toolset (default):**
+
+```toml
+[mcp_servers.contextstream]
+command = "npx"
+args = ["-y", "@contextstream/mcp-server"]
+
+[mcp_servers.contextstream.env]
+CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
+CONTEXTSTREAM_API_KEY = "your_api_key"
+```
+
+**Complete toolset (~86 tools):**
+
+```toml
+[mcp_servers.contextstream]
+command = "npx"
+args = ["-y", "@contextstream/mcp-server"]
+
+[mcp_servers.contextstream.env]
+CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
+CONTEXTSTREAM_API_KEY = "your_api_key"
+CONTEXTSTREAM_TOOLSET = "complete"
+```
+
+After editing, restart your MCP client so it reloads the server configuration.
+
+## Authentication
+
+You can authenticate using either:
+
+- `CONTEXTSTREAM_API_KEY` (recommended for local/dev)
+- `CONTEXTSTREAM_JWT` (useful for hosted or user-session flows)
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CONTEXTSTREAM_API_URL` | Yes | Base API URL (e.g. `https://api.contextstream.io`) |
+| `CONTEXTSTREAM_API_KEY` | Yes* | API key (*required unless `CONTEXTSTREAM_JWT` is set) |
+| `CONTEXTSTREAM_JWT` | Yes* | JWT (*required unless `CONTEXTSTREAM_API_KEY` is set) |
+| `CONTEXTSTREAM_WORKSPACE_ID` | No | Default workspace ID fallback |
+| `CONTEXTSTREAM_PROJECT_ID` | No | Default project ID fallback |
+| `CONTEXTSTREAM_USER_AGENT` | No | Custom user agent string |
+| `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`. |
+| `CONTEXTSTREAM_TOOL_ALLOWLIST` | No | Comma-separated tool names to expose (overrides toolset) |
+| `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`) |
+| `CONTEXTSTREAM_UPGRADE_URL` | No | Upgrade link shown when Free users call PRO tools (default: `https://contextstream.io/pricing`) |
+
+### Server-side environment variables (API)
+
+The following environment variables are configured on the ContextStream API server (not in your MCP client config):
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `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. |
+
+#### File write parameters for `projects_ingest_local`
+
+The `projects_ingest_local` tool accepts two optional parameters for QA/testing scenarios:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `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. |
+| `overwrite` | boolean | `false` | When `true` (and `write_to_disk` is enabled), allows overwriting existing files. Otherwise, existing files are skipped. |
+
+**Example usage:**
+```json
+{
+  "path": "/path/to/local/project",
+  "write_to_disk": true,
+  "overwrite": false
+}
+```
+
+**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.
+
+## Usage patterns
+
+### Recommended flow for AI tools
+
+1. Start of a conversation: call `session_init(folder_path="...", context_hint="<first user message>")`
+2. Before subsequent responses: call `context_smart(user_message="<current user message>")`
+3. After important outcomes: call `session_capture(...)` or `session_capture_lesson(...)`
+
+### Omit workspace/project IDs (recommended)
+
+Most tools accept omitted `workspace_id` / `project_id` and will use the current session defaults.
+
+- If you see “workspace_id is required”, call `session_init` first (or pass the ID explicitly).
+- If you regularly work in the same repo, use `workspace_associate` once so the server can auto-select the right workspace for that folder.
+
+### First-time setup (no workspaces yet)
+
+If your account has no workspaces, ContextStream will prompt your AI assistant to ask you for a workspace name.
+
+- Provide a workspace name (e.g., your company/team/product)
+- The current folder is created as a project inside that workspace
+- Recommended: call `workspace_bootstrap(workspace_name="...", folder_path="...")`
+
+## Free vs PRO tools
+
+Tools are labeled as `(Free)` or `(PRO)` in the MCP tool list.
+
+- Default PRO tools: `ai_context`, `ai_enhanced_context`, `ai_context_budget`, `ai_embeddings`, `ai_plan`, `ai_tasks`
+- If a Free-plan user calls a PRO tool, the server returns an upgrade message with a link.
+- Override the PRO list via `CONTEXTSTREAM_PRO_TOOLS` and the upgrade link via `CONTEXTSTREAM_UPGRADE_URL`.
+
+## Troubleshooting
+
+- Tools not appearing: restart the client after editing MCP config; confirm Node 18+ is available to the client runtime.
+- Unauthorized errors: verify `CONTEXTSTREAM_API_URL` and `CONTEXTSTREAM_API_KEY` (or `CONTEXTSTREAM_JWT`).
+- Wrong workspace/project: use `workspace_associate` to map the current repo folder to the correct workspace.
+
+## Development
+
+```bash
+git clone https://github.com/contextstream/mcp-server.git
+cd mcp-server
+npm install
+npm run dev
+npm run typecheck
+npm run build
+```
+
+## Links
+
+- Website: https://contextstream.io
+- Docs: https://contextstream.io/docs/mcp
+- Pricing: https://contextstream.io/pricing
+- npm: https://www.npmjs.com/package/@contextstream/mcp-server
+- GitHub: https://github.com/contextstream/mcp-server
+
+## License
+
+MIT

package/dist/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+'#!/usr/bin/env node' 
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -6018,6 +6018,8 @@ var ContextStreamClient = class {
       event_type: apiEventType,
       title: params.title,
       content: params.content,
+      provenance: params.provenance,
+      code_refs: params.code_refs,
       metadata: {
         original_type: params.event_type,
         session_id: params.session_id,
@@ -6028,6 +6030,14 @@ var ContextStreamClient = class {
       }
     });
   }
+  submitContextFeedback(body) {
+    return request(this.config, "/context/smart/feedback", { body: this.withDefaults(body) });
+  }
+  decisionTrace(body) {
+    return request(this.config, "/memory/search/decisions/trace", {
+      body: this.withDefaults(body)
+    });
+  }
   /**
    * Remember something using the session/remember endpoint.
    * This is a simpler interface than captureContext and supports await_indexing.
@@ -7282,6 +7292,7 @@ var CONTEXTSTREAM_TOOL_NAMES = [
   // Session/Context (standard)
   "session_init",
   "context_smart",
+  "context_feedback",
   "session_summary",
   "session_capture",
   "session_capture_lesson",
@@ -7331,6 +7342,7 @@ var CONTEXTSTREAM_TOOL_NAMES = [
   "memory_list_nodes",
   "memory_search",
   "memory_decisions",
+  "decision_trace",
   "memory_get_event",
   "memory_update_event",
   "memory_delete_event",
@@ -7498,7 +7510,7 @@ To expose all tools below, set \`CONTEXTSTREAM_TOOLSET=complete\` in your MCP co
 **Available tool categories (when \`CONTEXTSTREAM_TOOLSET=complete\`):**
 
 **Session/Context** (included in standard):
-\`session_init\`, \`context_smart\`, \`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\`
+\`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\`
 
 **Workspaces**:
 \`workspaces_list\`, \`workspaces_create\`, \`workspaces_update\`, \`workspaces_delete\`, \`workspaces_get\`, \`workspaces_overview\`, \`workspaces_analytics\`, \`workspaces_content\`
@@ -7510,7 +7522,7 @@ To expose all tools below, set \`CONTEXTSTREAM_TOOLSET=complete\` in your MCP co
 \`search_semantic\`, \`search_hybrid\`, \`search_keyword\`, \`search_pattern\`, \`search_suggestions\`
 
 **Memory**:
-\`memory_create_event\`, \`memory_bulk_ingest\`, \`memory_list_events\`, \`memory_create_node\`, \`memory_list_nodes\`, \`memory_search\`, \`memory_decisions\`, \`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\`
+\`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\`
 
 **Graph** (code analysis):
 \`graph_related\`, \`graph_path\`, \`graph_decisions\`, \`graph_dependencies\`, \`graph_call_path\`, \`graph_impact\`, \`graph_circular_dependencies\`, \`graph_unused_code\`, \`graph_ingest\`, \`graph_contradictions\`
@@ -7862,6 +7874,7 @@ var WRITE_VERBS = /* @__PURE__ */ new Set([
   "add",
   "remove",
   "revoke",
+  "feedback",
   "upload",
   "compress",
   "init"
@@ -7885,6 +7898,7 @@ var READ_ONLY_OVERRIDES = /* @__PURE__ */ new Set([
   "workspaces_get",
   "memory_search",
   "memory_decisions",
+  "decision_trace",
   "memory_get_event",
   "memory_list_events",
   "memory_list_nodes",
@@ -8028,6 +8042,7 @@ var LIGHT_TOOLSET = /* @__PURE__ */ new Set([
   "session_init",
   "session_tools",
   "context_smart",
+  "context_feedback",
   "session_summary",
   "session_capture",
   "session_capture_lesson",
@@ -8104,6 +8119,7 @@ var STANDARD_TOOLSET = /* @__PURE__ */ new Set([
   // Memory events (9)
   "memory_search",
   "memory_decisions",
+  "decision_trace",
   "memory_create_event",
   "memory_list_events",
   "memory_get_event",
@@ -8807,7 +8823,22 @@ Access: Free`,
         event_type: external_exports.string(),
         title: external_exports.string(),
         content: external_exports.string(),
-        metadata: external_exports.record(external_exports.any()).optional()
+        metadata: external_exports.record(external_exports.any()).optional(),
+        provenance: external_exports.object({
+          repo: external_exports.string().optional(),
+          branch: external_exports.string().optional(),
+          commit_sha: external_exports.string().optional(),
+          pr_url: external_exports.string().url().optional(),
+          issue_url: external_exports.string().url().optional(),
+          slack_thread_url: external_exports.string().url().optional()
+        }).optional(),
+        code_refs: external_exports.array(
+          external_exports.object({
+            file_path: external_exports.string(),
+            symbol_id: external_exports.string().optional(),
+            symbol_name: external_exports.string().optional()
+          })
+        ).optional()
       })
     },
     async (input) => {
@@ -8921,6 +8952,24 @@ Access: Free`,
       return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
     }
   );
+  registerTool(
+    "decision_trace",
+    {
+      title: "Decision trace",
+      description: "Trace decisions to provenance, code references, and impact",
+      inputSchema: external_exports.object({
+        query: external_exports.string(),
+        workspace_id: external_exports.string().uuid().optional(),
+        project_id: external_exports.string().uuid().optional(),
+        limit: external_exports.number().optional(),
+        include_impact: external_exports.boolean().optional().describe("Include impact analysis when graph data is available")
+      })
+    },
+    async (input) => {
+      const result = await client.decisionTrace(input);
+      return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
+    }
+  );
   registerTool(
     "graph_related",
     {
@@ -9942,7 +9991,22 @@ Use this to persist decisions, insights, preferences, or important information.`
         title: external_exports.string().describe("Brief title for the captured context"),
         content: external_exports.string().describe("Full content/details to capture"),
         tags: external_exports.array(external_exports.string()).optional().describe("Tags for categorization"),
-        importance: external_exports.enum(["low", "medium", "high", "critical"]).optional().describe("Importance level")
+        importance: external_exports.enum(["low", "medium", "high", "critical"]).optional().describe("Importance level"),
+        provenance: external_exports.object({
+          repo: external_exports.string().optional(),
+          branch: external_exports.string().optional(),
+          commit_sha: external_exports.string().optional(),
+          pr_url: external_exports.string().url().optional(),
+          issue_url: external_exports.string().url().optional(),
+          slack_thread_url: external_exports.string().url().optional()
+        }).optional(),
+        code_refs: external_exports.array(
+          external_exports.object({
+            file_path: external_exports.string(),
+            symbol_id: external_exports.string().optional(),
+            symbol_name: external_exports.string().optional()
+          })
+        ).optional()
       })
     },
     async (input) => {
@@ -10604,6 +10668,42 @@ This saves ~80% tokens compared to including full chat history.`,
       };
     }
   );
+  registerTool(
+    "context_feedback",
+    {
+      title: "Submit smart context feedback",
+      description: "Send relevance feedback (relevant/irrelevant/pin) for context_smart items.",
+      inputSchema: external_exports.object({
+        workspace_id: external_exports.string().uuid().optional(),
+        project_id: external_exports.string().uuid().optional(),
+        item_id: external_exports.string().describe("Item ID returned by context_smart"),
+        item_type: external_exports.enum(["memory_event", "knowledge_node", "code_chunk"]),
+        feedback_type: external_exports.enum(["relevant", "irrelevant", "pin"]),
+        query_text: external_exports.string().optional(),
+        metadata: external_exports.record(external_exports.any()).optional()
+      })
+    },
+    async (input) => {
+      let workspaceId = input.workspace_id;
+      let projectId = input.project_id;
+      if (!workspaceId && sessionManager) {
+        const ctx = sessionManager.getContext();
+        if (ctx) {
+          workspaceId = ctx.workspace_id;
+          projectId = projectId || ctx.project_id;
+        }
+      }
+      const result = await client.submitContextFeedback({
+        ...input,
+        workspace_id: workspaceId,
+        project_id: projectId
+      });
+      return {
+        content: [{ type: "text", text: formatContent(result) }],
+        structuredContent: toStructured(result)
+      };
+    }
+  );
   registerTool(
     "slack_stats",
     {

package/package.json

@@ -1,57 +1,57 @@
-{
-  "name": "@contextstream/mcp-server",
-  "mcpName": "io.github.contextstreamio/mcp-server",
-  "version": "0.3.67",
-  "description": "MCP server exposing ContextStream public API - code context, memory, search, and AI tools for developers",
-  "type": "module",
-  "license": "MIT",
-  "main": "dist/index.js",
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "bin": {
-    "contextstream-mcp": "dist/index.js"
-  },
-  "scripts": {
-    "dev": "tsx src/index.ts",
-    "build": "esbuild src/index.ts --bundle --platform=node --target=node18 --outfile=dist/index.js --format=esm --external:@modelcontextprotocol/sdk && echo '#!/usr/bin/env node' | cat - dist/index.js > dist/index.tmp && mv dist/index.tmp dist/index.js && esbuild src/test-server.ts --bundle --platform=node --target=node18 --outfile=dist/test-server.js --format=esm --external:@modelcontextprotocol/sdk",
-    "start": "node dist/index.js",
-    "test-server": "tsx src/test-server.ts",
-    "test-server:start": "node dist/test-server.js",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.22.0",
-    "zod": "^3.23.8"
-  },
-  "devDependencies": {
-    "@types/node": "^20.10.0",
-    "esbuild": "^0.27.0",
-    "tsx": "^4.15.4",
-    "typescript": "^5.6.3"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "contextstream",
-    "ai",
-    "code-context",
-    "memory",
-    "knowledge-graph"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/contextstream/mcp-server.git"
-  },
-  "homepage": "https://contextstream.io/docs/mcp",
-  "bugs": {
-    "url": "https://github.com/contextstream/mcp-server/issues"
-  },
-  "overrides": {
-    "qs": "6.14.1"
-  }
-}
+{
+  "name": "@contextstream/mcp-server",
+  "mcpName": "io.github.contextstreamio/mcp-server",
+  "version": "0.3.68",
+  "description": "MCP server exposing ContextStream public API - code context, memory, search, and AI tools for developers",
+  "type": "module",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "bin": {
+    "contextstream-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "esbuild src/index.ts --bundle --platform=node --target=node18 --outfile=dist/index.js --format=esm --external:@modelcontextprotocol/sdk && echo '#!/usr/bin/env node' | cat - dist/index.js > dist/index.tmp && mv dist/index.tmp dist/index.js && esbuild src/test-server.ts --bundle --platform=node --target=node18 --outfile=dist/test-server.js --format=esm --external:@modelcontextprotocol/sdk",
+    "start": "node dist/index.js",
+    "test-server": "tsx src/test-server.ts",
+    "test-server:start": "node dist/test-server.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.22.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "esbuild": "^0.27.0",
+    "tsx": "^4.15.4",
+    "typescript": "^5.6.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "contextstream",
+    "ai",
+    "code-context",
+    "memory",
+    "knowledge-graph"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contextstream/mcp-server.git"
+  },
+  "homepage": "https://contextstream.io/docs/mcp",
+  "bugs": {
+    "url": "https://github.com/contextstream/mcp-server/issues"
+  },
+  "overrides": {
+    "qs": "6.14.1"
+  }
+}