@contextstream/mcp-server 0.3.57 → 0.3.59

package/README.md

@@ -54,7 +54,7 @@ npx -y @contextstream/mcp-server setup
 
 Notes:
 - Uses browser/device login by default and creates an API key for you.
-- Prompts for **toolset selection**: `core` (default, ~17 essential tools) or `full` (~86 tools including workspaces, projects, search, memory, graph, AI, and integrations).
+- 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).
@@ -93,7 +93,7 @@ If you ran the [setup wizard](#setup-wizard-recommended), you can usually skip t
 
 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 `core` tools (~17 essential session/context tools). To expose all ~86 tools (workspaces, projects, search, memory, graph, AI, integrations), add `"CONTEXTSTREAM_TOOLSET": "full"` to the `env` block. See the [full tool catalog](https://contextstream.io/docs/mcp/tools).
+**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)
 
@@ -107,7 +107,7 @@ These clients use the `mcpServers` JSON schema:
 
 Many other MCP JSON clients also use this same `mcpServers` shape (including Claude Code project scope via `.mcp.json`).
 
-**Core toolset (default, ~17 tools):**
+**Standard toolset (default, ~50 tools):**
 
 ```json
 {
@@ -124,7 +124,7 @@ Many other MCP JSON clients also use this same `mcpServers` shape (including Cla
 }
 ```
 
-**Full toolset (~86 tools):**
+**Complete toolset (~86 tools):**
 
 ```json
 {
@@ -135,7 +135,7 @@ Many other MCP JSON clients also use this same `mcpServers` shape (including Cla
       "env": {
         "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
         "CONTEXTSTREAM_API_KEY": "your_api_key",
-        "CONTEXTSTREAM_TOOLSET": "full"
+        "CONTEXTSTREAM_TOOLSET": "complete"
       }
     }
   }
@@ -164,7 +164,7 @@ VS Code uses a different schema with a top-level `servers` map:
 }
 ```
 
-**Full toolset (~86 tools):**
+**Complete toolset (~86 tools):**
 
 ```json
 {
@@ -176,7 +176,7 @@ VS Code uses a different schema with a top-level `servers` map:
       "env": {
         "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
         "CONTEXTSTREAM_API_KEY": "your_api_key",
-        "CONTEXTSTREAM_TOOLSET": "full"
+        "CONTEXTSTREAM_TOOLSET": "complete"
       }
     }
   }
@@ -213,7 +213,7 @@ Strong recommendation: VS Code supports `inputs` so you don’t have to hardcode
 
 User scope (all projects):
 
-**Core toolset (recommended for Claude Code):**
+**Standard toolset (default):**
 
 ```bash
 claude mcp add --transport stdio contextstream --scope user \
@@ -222,37 +222,37 @@ claude mcp add --transport stdio contextstream --scope user \
   -- npx -y @contextstream/mcp-server
 ```
 
-**Full toolset (~86 tools):**
+**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=full \
+  --env CONTEXTSTREAM_TOOLSET=complete \
   -- npx -y @contextstream/mcp-server
 ```
 
-Note: Claude Code may warn about large tool contexts when using `full`. The default is `core` (~17 tools).
+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):**
 
-Core:
+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"}}'
 ```
 
-Full:
+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":"full"}}'
+'{"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`)
 
-**Core toolset (default):**
+**Standard toolset (default):**
 
 ```toml
 [mcp_servers.contextstream]
@@ -264,7 +264,7 @@ CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
 CONTEXTSTREAM_API_KEY = "your_api_key"
 ```
 
-**Full toolset (~86 tools):**
+**Complete toolset (~86 tools):**
 
 ```toml
 [mcp_servers.contextstream]
@@ -274,7 +274,7 @@ args = ["-y", "@contextstream/mcp-server"]
 [mcp_servers.contextstream.env]
 CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
 CONTEXTSTREAM_API_KEY = "your_api_key"
-CONTEXTSTREAM_TOOLSET = "full"
+CONTEXTSTREAM_TOOLSET = "complete"
 ```
 
 After editing, restart your MCP client so it reloads the server configuration.
@@ -296,7 +296,7 @@ You can authenticate using either:
 | `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: `core` (default, ~17 tools) or `full` (~86 tools). Claude Code/Desktop may warn about large tool contexts with `full`. |
+| `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`) |

package/dist/index.js

@@ -7253,7 +7253,7 @@ import * as path4 from "node:path";
 // src/rules-templates.ts
 var DEFAULT_CLAUDE_MCP_SERVER_NAME = "contextstream";
 var CONTEXTSTREAM_TOOL_NAMES = [
-  // Session/Context (core)
+  // Session/Context (standard)
   "session_init",
   "context_smart",
   "session_summary",
@@ -7368,7 +7368,7 @@ function applyMcpToolPrefix(markdown, toolPrefix) {
   return markdown.replace(toolRegex, `${toolPrefix}$1`);
 }
 var CONTEXTSTREAM_RULES_FULL = `
-## ContextStream Integration
+## ContextStream Integration (Enhanced)
 
 You have access to ContextStream MCP tools for persistent memory and context.
 
@@ -7377,7 +7377,8 @@ You have access to ContextStream MCP tools for persistent memory and context.
 | Message | What to Call |
 |---------|--------------|
 | **1st message** | \`session_init(folder_path="...", context_hint="<user's message>")\` |
-| **2nd+ messages** | \`context_smart(user_message="<user's message>", max_tokens=400)\` |
+| **2nd+ messages** | \`context_smart(user_message="<user's message>", format="minified", max_tokens=400)\` |
+| **Before risky/non-trivial work** | \`session_get_lessons(query="<topic>")\` |
 | **After completing task** | \`session_capture(...)\` - MUST capture decisions/insights |
 | **User frustration/correction** | \`session_capture_lesson(...)\` - MUST capture lessons |
 | **Command/tool error + fix** | \`session_capture_lesson(...)\` - MUST capture lessons |
@@ -7386,7 +7387,7 @@ You have access to ContextStream MCP tools for persistent memory and context.
 
 ---
 
-### \u26A0\uFE0F Why context_smart is Required (Even After session_init)
+### Why context_smart is Required (Even After session_init)
 
 **Common mistake:** "session_init already gave me context, I don't need context_smart"
 
@@ -7397,8 +7398,8 @@ You have access to ContextStream MCP tools for persistent memory and context.
 **Example failure:**
 - User asks: "how should I implement authentication?"
 - Auth decisions were made 20 conversations ago
-- \u274C \`session_init\` won't have it (too old, not in recent 10)
-- \u2705 \`context_smart\` FINDS it via semantic search
+- \`session_init\` won't have it (too old, not in recent 10)
+- \`context_smart\` FINDS it via semantic search
 
 **Without context_smart, you WILL miss relevant older context.**
 
@@ -7408,138 +7409,67 @@ You have access to ContextStream MCP tools for persistent memory and context.
 
 - For trivial/local edits: \`context_smart(..., max_tokens=200)\`
 - Default: \`context_smart(..., max_tokens=400)\`
-- Deep debugging/architecture or heavy \u201Cwhat did we decide?\u201D: \`context_smart(..., max_tokens=800)\`
-- Keep \`format="minified"\` (default) unless you\u2019re actively debugging tool output
+- Deep debugging/architecture or heavy "what did we decide?": \`context_smart(..., max_tokens=800)\`
+- Keep \`format="minified"\` (default) unless you're debugging tool output
 
 If context still feels missing, increase \`max_tokens\` and/or call \`session_recall\` for a focused deep lookup.
 
 ---
 
-### When to Capture (MANDATORY)
+### Preferences & Lessons (Use Early)
 
-| When | Tool | Example |
-|------|------|---------|
-| User makes a decision | \`session_capture\` | "Let's use PostgreSQL" \u2192 capture as decision |
-| User states preference | \`session_capture\` | "I prefer TypeScript" \u2192 capture as preference |
-| You complete a task | \`session_capture\` | Capture what was done, decisions made |
-| Need past context | \`session_recall\` | "What did we decide about X?" |
-
-**You MUST capture after completing any significant task.** This ensures future sessions have context.
+- If preferences or style matter, call \`session_get_user_context\`.
+- Before risky changes or when past mistakes may apply, call \`session_get_lessons(query="<topic>")\`.
+- When frustration, corrections, or tool mistakes occur, immediately call \`session_capture_lesson\`.
 
 ---
 
-### Behavior Rules
-
-**First message of conversation:**
-1. Call \`session_init(folder_path="<cwd>", context_hint="<user's message>")\`
-2. Then respond
-
-**Every subsequent message:**
-1. Call \`context_smart(user_message="<user's message>")\` FIRST
-2. Then respond
+### Search, Graphs, and Code Intelligence (ContextStream-first)
 
-**After completing a task:**
-1. Call \`session_capture\` to save decisions, preferences, or insights
-2. This is NOT optional
-
-**When user asks about past decisions:**
-- Use \`session_recall\` - do NOT ask user to repeat themselves
-
----
-
-### Search (ContextStream-first)
-
-- Before scanning the repo or grepping, use \`session_smart_search\` to locate relevant files, patterns, and prior context.
-- Follow up with \`session_recall\` if you need deeper history on a specific topic.
-- Only fall back to raw file scans (\`rg\`, \`ls\`, \`find\`) when ContextStream search doesn't surface what you need.
+- Use \`session_smart_search\` before scanning the repo or grepping.
+- Use \`search_semantic\`/\`search_hybrid\`/\`search_keyword\` for targeted queries.
+- For dependencies/impact/call paths, use \`graph_dependencies\`, \`graph_impact\`, and \`graph_call_path\`.
+- If the graph is missing or stale, run \`graph_ingest\` (async by default with \`wait: false\`). Tell the user it can take a few minutes; optionally call \`projects_statistics\` to estimate time.
 
 ---
 
-### Lesson Capture (MANDATORY)
-
-When:
-1. **Expresses frustration** (caps, profanity, "COME ON", "WTF", repeated corrections)
-2. **Corrects you** ("No, you should...", "That's wrong", "Fix this")
-3. **Points out a mistake** (broken code, wrong approach, production issue)
-4. **A command/tool call fails and you learn the correct fix** (even if the user didn\u2019t explicitly correct you)
-
-You MUST immediately call \`session_capture_lesson\` with:
-
-| Field | Description | Example |
-|-------|-------------|---------|
-| \`title\` | What to remember | "Verify assets in git before pushing" |
-| \`severity\` | \`critical\`/\`high\`/\`medium\`/\`low\` | \`critical\` for production issues |
-| \`category\` | \`workflow\`/\`code_quality\`/\`verification\`/\`communication\`/\`project_specific\` | \`workflow\` |
-| \`trigger\` | What action caused the problem | "Pushed code referencing images without committing them" |
-| \`impact\` | What went wrong | "Production 404 errors - broken landing page" |
-| \`prevention\` | How to prevent in future | "Run git status to check untracked files before pushing" |
-| \`keywords\` | Keywords for matching | \`["git", "images", "assets", "push"]\` |
+### Distillation & Memory Hygiene
 
-**Example call:**
-\`\`\`json
-{
-  "title": "Always verify assets in git before pushing code references",
-  "severity": "critical",
-  "category": "workflow",
-  "trigger": "Pushed code referencing /screenshots/*.png without committing images",
-  "impact": "Production 404 errors - broken landing page",
-  "prevention": "Run 'git status' to check untracked files before pushing code that references static assets",
-  "keywords": ["git", "images", "assets", "push", "404", "static"]
-}
-\`\`\`
-
-**Why this matters:**
-- Lessons are surfaced automatically in \`session_init\` and \`context_smart\`
-- Future sessions will warn you before repeating the same mistake
-- This prevents production issues and user frustration
-
-**Severity guide:**
-- \`critical\`: Production outages, data loss, security issues
-- \`high\`: Breaking changes, significant user impact
-- \`medium\`: Workflow inefficiencies, minor bugs
-- \`low\`: Style/preference corrections
+- Use \`session_summary\` for a fast workspace snapshot.
+- Use \`session_compress\` when the chat is long or context limits are near.
+- Use \`memory_summary\` for recent work summaries and \`memory_distill_event\` to condense noisy memory entries.
 
 ---
 
-### Quick Examples
-
-\`\`\`
-# First message - user asks about auth
-session_init(folder_path="/path/to/project", context_hint="how should I implement auth?")
-# Returns workspace info + semantically relevant auth decisions from ANY time
-
-# Second message - user asks about database
-context_smart(user_message="what database should I use?", max_tokens=400)
-# Returns: W:Maker|P:myproject|D:Use PostgreSQL|D:No ORMs|M:DB schema at...
-
-# User says "Let's use Redis for caching"
-session_capture(event_type="decision", title="Caching Choice", content="Using Redis for caching layer")
+### When to Capture (MANDATORY)
 
-# After completing implementation
-session_capture(event_type="decision", title="Auth Implementation Complete", content="Implemented JWT auth with refresh tokens...")
+| When | Tool | Example |
+|------|------|---------|
+| User makes a decision | \`session_capture\` | "Let's use PostgreSQL" -> capture as decision |
+| User states preference | \`session_capture\` | "I prefer TypeScript" -> capture as preference |
+| You complete a task | \`session_capture\` | Capture what was done, decisions made |
+| Need past context | \`session_recall\` | "What did we decide about X?" |
 
-# Check past decisions
-session_recall(query="what did we decide about caching?")
-\`\`\`
+**You MUST capture after completing any significant task.** This ensures future sessions have context.
 
 ---
 
 ### Full Tool Catalog
 
-To expose all tools below, set \`CONTEXTSTREAM_TOOLSET=full\` in your MCP config. The default (\`core\`) includes only the essential session/context tools above.
+To expose all tools below, set \`CONTEXTSTREAM_TOOLSET=complete\` in your MCP config. The default (\`standard\`) includes the essential session, search, memory, and graph tools above.
 
-**To enable full toolset in your MCP config:**
+**To enable the complete toolset in your MCP config:**
 \`\`\`json
 {
   "env": {
-    "CONTEXTSTREAM_TOOLSET": "full"
+    "CONTEXTSTREAM_TOOLSET": "complete"
   }
 }
 \`\`\`
 
-**Available tool categories (when \`CONTEXTSTREAM_TOOLSET=full\`):**
+**Available tool categories (when \`CONTEXTSTREAM_TOOLSET=complete\`):**
 
-**Session/Context** (included in core):
+**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\`
 
 **Workspaces**:
@@ -7572,24 +7502,26 @@ To expose all tools below, set \`CONTEXTSTREAM_TOOLSET=full\` in your MCP config
 See full documentation: https://contextstream.io/docs/mcp/tools
 `.trim();
 var CONTEXTSTREAM_RULES_MINIMAL = `
-## ContextStream (Minimal)
+## ContextStream (Standard)
 
 - First user message: \`session_init(folder_path="<cwd>", context_hint="<user_message>")\`, then answer.
 - Every user message: \`context_smart(user_message="<user_message>", format="minified", max_tokens=400)\` BEFORE answering.
   - Use \`max_tokens=200\` for trivial/local edits, \`max_tokens=800\` for deep debugging/architecture.
-- If prior context is missing or user asks past decisions: \`session_recall(query="<question>")\`, then answer.
-- For code/file discovery, use \`session_smart_search\` before raw repo scans (\`rg\`, \`ls\`, \`find\`); fall back only if needed.
-- After meaningful work/decisions/preferences: \`session_capture(event_type=decision|preference|task|insight, title="\u2026", content="\u2026")\`.
+- Before risky/non-trivial work: check \`session_get_lessons(query="<topic>")\`; use \`session_get_user_context\` when preferences/style matter.
+- For discovery: use \`session_smart_search\` first; use \`search_semantic\`/\`search_hybrid\`/\`search_keyword\` for targeted lookups.
+- For code intelligence: use \`graph_dependencies\`/\`graph_impact\`/\`graph_call_path\`; run \`graph_ingest\` if the graph is missing (async by default, can take a few minutes).
+- For distillation: use \`session_summary\` for quick context; use \`session_compress\` for long chats; use \`memory_summary\` or \`memory_distill_event\` to condense memory.
+- After meaningful work/decisions/preferences: \`session_capture(event_type=decision|preference|task|insight, title="...", content="...")\`.
 - On frustration/corrections/tool mistakes: \`session_capture_lesson(...)\`.
 
 ### Tool Catalog
 
-By default, the MCP server exposes **core** tools (~17 essential session/context tools). To expose the **full** catalog (~86 tools including workspaces, projects, search, memory, graph, AI, and integrations), set \`CONTEXTSTREAM_TOOLSET=full\` in your MCP config:
+By default, the MCP server exposes the **standard** toolset (~50 tools). To expose fewer tools, set \`CONTEXTSTREAM_TOOLSET=light\`. To expose everything (~86 tools), set \`CONTEXTSTREAM_TOOLSET=complete\` in your MCP config:
 
 \`\`\`json
 {
   "env": {
-    "CONTEXTSTREAM_TOOLSET": "full"
+    "CONTEXTSTREAM_TOOLSET": "complete"
   }
 }
 \`\`\`
@@ -12030,7 +11962,7 @@ Created API key: ${maskedNewKey}
     }
     console.log("Rules detail level (in the generated rules file):\n");
     console.log("  1) Standard (recommended) \u2014 concise, high-signal (lower token overhead)");
-    console.log("  2) Extended \u2014 more guidance + examples (higher token overhead)");
+    console.log("  2) Enhanced \u2014 more guidance + examples (higher token overhead)");
     const modeChoice = normalizeInput(await rl.question("Choose [1/2] (default 1): ")) || "1";
     const mode = modeChoice === "2" ? "full" : "minimal";
     console.log("\nMCP toolset (which tools to expose to the AI):");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextstream/mcp-server",
-  "version": "0.3.57",
+  "version": "0.3.59",
   "description": "MCP server exposing ContextStream public API - code context, memory, search, and AI tools for developers",
   "type": "module",
   "license": "MIT",