@contextstream/mcp-server 0.3.33 → 0.3.34

package/README.md

@@ -156,17 +156,21 @@ User scope (all projects):
 ```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_API_KEY=YOUR_KEY \
+  --env CONTEXTSTREAM_TOOLSET=core -- \
   npx -y @contextstream/mcp-server
 ```
 
+Tip: Claude Code warns on large tool contexts. The default toolset is `core`.
+Set `CONTEXTSTREAM_TOOLSET=full` to expose everything.
+
 Windows caveat (native Windows, not WSL): if `npx` isn’t found, use `cmd /c npx -y @contextstream/mcp-server` after `--`.
 
 Alternative (JSON form):
 
 ```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"}}'
+'{"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":"core"}}'
 ```
 
 ### Codex CLI (`~/.codex/config.toml`)
@@ -200,9 +204,39 @@ 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, or `full`) |
+| `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

package/dist/index.js

@@ -4136,7 +4136,7 @@ var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504])
 var MAX_RETRIES = 3;
 var BASE_DELAY = 1e3;
 async function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 async function request(config, path7, options = {}) {
   const { apiUrl, apiKey, jwt, userAgent } = config;
@@ -4429,6 +4429,51 @@ async function* readAllFilesInBatches(rootPath, options = {}) {
     yield batch;
   }
 }
+async function countIndexableFiles(rootPath, options = {}) {
+  const maxFiles = options.maxFiles ?? 1;
+  const maxFileSize = options.maxFileSize ?? MAX_FILE_SIZE;
+  let count = 0;
+  let stopped = false;
+  async function walkDir(dir) {
+    if (count >= maxFiles) {
+      stopped = true;
+      return;
+    }
+    let entries;
+    try {
+      entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (count >= maxFiles) {
+        stopped = true;
+        return;
+      }
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (IGNORE_DIRS.has(entry.name)) continue;
+        await walkDir(fullPath);
+      } else if (entry.isFile()) {
+        if (IGNORE_FILES.has(entry.name)) continue;
+        const ext = entry.name.split(".").pop()?.toLowerCase() ?? "";
+        if (!CODE_EXTENSIONS.has(ext)) continue;
+        try {
+          const stat2 = await fs.promises.stat(fullPath);
+          if (stat2.size > maxFileSize) continue;
+          count++;
+          if (count >= maxFiles) {
+            stopped = true;
+            return;
+          }
+        } catch {
+        }
+      }
+    }
+  }
+  await walkDir(rootPath);
+  return { count, stopped };
+}
 
 // src/workspace-config.ts
 import * as fs2 from "fs";
@@ -4964,11 +5009,20 @@ var ContextStreamClient = class {
   /**
    * Ingest files for indexing
    * This uploads files to the API for indexing
+   * @param projectId - Project UUID
+   * @param files - Array of files to ingest
+   * @param options - Optional ingest options
+   * @param options.write_to_disk - When true, write files to disk under QA_FILE_WRITE_ROOT before indexing
+   * @param options.overwrite - Allow overwriting existing files when write_to_disk is enabled
    */
-  ingestFiles(projectId, files) {
+  ingestFiles(projectId, files, options) {
     uuidSchema.parse(projectId);
     return request(this.config, `/projects/${projectId}/files/ingest`, {
-      body: { files }
+      body: {
+        files,
+        ...options?.write_to_disk !== void 0 && { write_to_disk: options.write_to_disk },
+        ...options?.overwrite !== void 0 && { overwrite: options.overwrite }
+      }
     });
   }
   // Workspace extended operations (with caching)
@@ -6567,6 +6621,7 @@ W:${wsHint}
 };
 
 // src/tools.ts
+import * as fs3 from "node:fs";
 import * as path4 from "node:path";
 
 // src/rules-templates.ts
@@ -6862,6 +6917,61 @@ var VERSION = getVersion();
 // src/tools.ts
 var LESSON_DEDUP_WINDOW_MS = 2 * 60 * 1e3;
 var recentLessonCaptures = /* @__PURE__ */ new Map();
+var CORE_TOOLSET = /* @__PURE__ */ new Set([
+  "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",
+  "auth_me",
+  "mcp_server_version"
+]);
+var TOOLSET_ALIASES = {
+  core: CORE_TOOLSET,
+  minimal: CORE_TOOLSET,
+  essential: CORE_TOOLSET
+};
+function parseToolList(raw) {
+  return new Set(
+    raw.split(",").map((tool) => tool.trim()).filter(Boolean)
+  );
+}
+function resolveToolFilter() {
+  const defaultToolset = CORE_TOOLSET;
+  const allowlistRaw = process.env.CONTEXTSTREAM_TOOL_ALLOWLIST;
+  if (allowlistRaw) {
+    const allowlist = parseToolList(allowlistRaw);
+    if (allowlist.size === 0) {
+      console.error("[ContextStream] CONTEXTSTREAM_TOOL_ALLOWLIST is empty; using core tool list.");
+      return { allowlist: defaultToolset, source: "core" };
+    }
+    return { allowlist, source: "allowlist" };
+  }
+  const toolsetRaw = process.env.CONTEXTSTREAM_TOOLSET;
+  if (!toolsetRaw) {
+    return { allowlist: defaultToolset, source: "core" };
+  }
+  const key = toolsetRaw.trim().toLowerCase();
+  if (!key || key === "full" || key === "all") {
+    return { allowlist: null, source: "full" };
+  }
+  const resolved = TOOLSET_ALIASES[key];
+  if (resolved) {
+    return { allowlist: resolved, source: key };
+  }
+  console.error(`[ContextStream] Unknown CONTEXTSTREAM_TOOLSET "${toolsetRaw}". Using core tool list.`);
+  return { allowlist: defaultToolset, source: "core" };
+}
 function formatContent(data) {
   return JSON.stringify(data, null, 2);
 }
@@ -6902,6 +7012,13 @@ function isDuplicateLessonCapture(signature) {
 }
 function registerTools(server, client, sessionManager) {
   const upgradeUrl = process.env.CONTEXTSTREAM_UPGRADE_URL || "https://contextstream.io/pricing";
+  const toolFilter = resolveToolFilter();
+  const toolAllowlist = toolFilter.allowlist;
+  if (toolAllowlist) {
+    const source = toolFilter.source ?? "custom";
+    const hint = source === "core" ? " Set CONTEXTSTREAM_TOOLSET=full to expose all tools." : "";
+    console.error(`[ContextStream] Toolset limited (${source}): ${toolAllowlist.size} tools.${hint}`);
+  }
   const defaultProTools = /* @__PURE__ */ new Set([
     // AI endpoints (typically paid/credit-metered)
     "ai_context",
@@ -6977,6 +7094,9 @@ function registerTools(server, client, sessionManager) {
     };
   }
   function registerTool(name, config, handler) {
+    if (toolAllowlist && !toolAllowlist.has(name)) {
+      return;
+    }
     const accessLabel = getToolAccessLabel(name);
     const labeledConfig = {
       ...config,
@@ -6997,10 +7117,20 @@ Access: ${accessLabel}${accessLabel === "PRO" ? ` (upgrade: ${upgradeUrl})` : ""
         const isPlanLimit = String(errorCode).toUpperCase() === "FORBIDDEN" && String(errorMessage).toLowerCase().includes("plan limit reached");
         const upgradeHint = isPlanLimit ? `
 Upgrade: ${upgradeUrl}` : "";
-        const serializedError = new Error(
-          `[${errorCode}] ${errorMessage}${upgradeHint}${errorDetails ? `: ${JSON.stringify(errorDetails)}` : ""}`
-        );
-        throw serializedError;
+        const errorPayload = {
+          success: false,
+          error: {
+            code: errorCode,
+            message: errorMessage,
+            details: errorDetails
+          }
+        };
+        const errorText = `[${errorCode}] ${errorMessage}${upgradeHint}${errorDetails ? `: ${JSON.stringify(errorDetails)}` : ""}`;
+        return {
+          content: [{ type: "text", text: errorText }],
+          structuredContent: errorPayload,
+          isError: true
+        };
       }
     };
     server.registerTool(
@@ -7025,6 +7155,33 @@ Upgrade: ${upgradeUrl}` : "";
     const ctx = sessionManager?.getContext();
     return typeof ctx?.project_id === "string" ? ctx.project_id : void 0;
   }
+  async function validateReadableDirectory(inputPath) {
+    const resolvedPath = path4.resolve(inputPath);
+    let stats;
+    try {
+      stats = await fs3.promises.stat(resolvedPath);
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        return { ok: false, error: `Error: path does not exist: ${inputPath}` };
+      }
+      return {
+        ok: false,
+        error: `Error: unable to access path: ${inputPath}${error?.message ? ` (${error.message})` : ""}`
+      };
+    }
+    if (!stats.isDirectory()) {
+      return { ok: false, error: `Error: path is not a directory: ${inputPath}` };
+    }
+    try {
+      await fs3.promises.access(resolvedPath, fs3.constants.R_OK | fs3.constants.X_OK);
+    } catch (error) {
+      return {
+        ok: false,
+        error: `Error: path is not readable: ${inputPath}${error?.code ? ` (${error.code})` : ""}`
+      };
+    }
+    return { ok: true, resolvedPath };
+  }
   registerTool(
     "mcp_server_version",
     {
@@ -7053,7 +7210,7 @@ Upgrade: ${upgradeUrl}` : "";
     "workspaces_list",
     {
       title: "List workspaces",
-      description: "List accessible workspaces",
+      description: "List accessible workspaces (paginated list: items, total, page, per_page, has_next, has_prev).",
       inputSchema: external_exports.object({ page: external_exports.number().optional(), page_size: external_exports.number().optional() })
     },
     async (input) => {
@@ -7065,7 +7222,7 @@ Upgrade: ${upgradeUrl}` : "";
     "workspaces_create",
     {
       title: "Create workspace",
-      description: "Create a new workspace",
+      description: "Create a new workspace (returns ApiResponse with created workspace in data).",
       inputSchema: external_exports.object({
         name: external_exports.string(),
         description: external_exports.string().optional(),
@@ -7113,7 +7270,7 @@ Upgrade: ${upgradeUrl}` : "";
     "projects_list",
     {
       title: "List projects",
-      description: "List projects (optionally by workspace)",
+      description: "List projects (optionally by workspace; paginated list: items, total, page, per_page, has_next, has_prev).",
       inputSchema: external_exports.object({ workspace_id: external_exports.string().uuid().optional(), page: external_exports.number().optional(), page_size: external_exports.number().optional() })
     },
     async (input) => {
@@ -7125,7 +7282,7 @@ Upgrade: ${upgradeUrl}` : "";
     "projects_create",
     {
       title: "Create project",
-      description: "Create a project within a workspace",
+      description: "Create a project within a workspace (returns ApiResponse with created project in data).",
       inputSchema: external_exports.object({
         name: external_exports.string(),
         description: external_exports.string().optional(),
@@ -7400,9 +7557,14 @@ Upgrade: ${upgradeUrl}` : "";
     "graph_dependencies",
     {
       title: "Code dependencies",
-      description: "Dependency graph query",
+      description: `Dependency graph query
+
+Access: Free`,
       inputSchema: external_exports.object({
-        target: external_exports.object({ type: external_exports.string(), id: external_exports.string() }),
+        target: external_exports.object({
+          type: external_exports.string().describe("Code element type. Accepted values: module (aliases: file, path), function (alias: method), type (aliases: struct, enum, trait, class), variable (aliases: data, const, constant). For knowledge/memory nodes, use graph_path with UUID ids instead."),
+          id: external_exports.string().describe('Element identifier. For module type, use file path (e.g., "src/auth.rs"). For function/type/variable, use the element id.')
+        }),
         max_depth: external_exports.number().optional(),
         include_transitive: external_exports.boolean().optional()
       })
@@ -7416,10 +7578,18 @@ Upgrade: ${upgradeUrl}` : "";
     "graph_call_path",
     {
       title: "Call path",
-      description: "Find call path between two targets",
+      description: `Find call path between two targets
+
+Access: Free`,
       inputSchema: external_exports.object({
-        source: external_exports.object({ type: external_exports.string(), id: external_exports.string() }),
-        target: external_exports.object({ type: external_exports.string(), id: external_exports.string() }),
+        source: external_exports.object({
+          type: external_exports.string().describe('Must be "function" (alias: method). Only function types are supported for call path analysis. For knowledge/memory nodes, use graph_path with UUID ids instead.'),
+          id: external_exports.string().describe("Source function identifier.")
+        }),
+        target: external_exports.object({
+          type: external_exports.string().describe('Must be "function" (alias: method). Only function types are supported for call path analysis.'),
+          id: external_exports.string().describe("Target function identifier.")
+        }),
         max_depth: external_exports.number().optional()
       })
     },
@@ -7432,8 +7602,16 @@ Upgrade: ${upgradeUrl}` : "";
     "graph_impact",
     {
       title: "Impact analysis",
-      description: "Analyze impact of a target node",
-      inputSchema: external_exports.object({ target: external_exports.object({ type: external_exports.string(), id: external_exports.string() }), max_depth: external_exports.number().optional() })
+      description: `Analyze impact of a target node
+
+Access: Free`,
+      inputSchema: external_exports.object({
+        target: external_exports.object({
+          type: external_exports.string().describe("Code element type. Accepted values: module (aliases: file, path), function (alias: method), type (aliases: struct, enum, trait, class), variable (aliases: data, const, constant). For knowledge/memory nodes, use graph_path with UUID ids instead."),
+          id: external_exports.string().describe('Element identifier. For module type, use file path (e.g., "src/auth.rs"). For function/type/variable, use the element id.')
+        }),
+        max_depth: external_exports.number().optional()
+      })
     },
     async (input) => {
       const result = await client.graphImpact(input);
@@ -7614,7 +7792,9 @@ This indexes your entire project by reading files in batches.
 Automatically detects code files and skips ignored directories like node_modules, target, dist, etc.`,
       inputSchema: external_exports.object({
         project_id: external_exports.string().uuid().optional().describe("Project to ingest files into (defaults to current session project)"),
-        path: external_exports.string().describe("Local directory path to read files from")
+        path: external_exports.string().describe("Local directory path to read files from"),
+        write_to_disk: external_exports.boolean().optional().describe("When true, write files to disk under QA_FILE_WRITE_ROOT before indexing (for testing/QA)"),
+        overwrite: external_exports.boolean().optional().describe("Allow overwriting existing files when write_to_disk is enabled")
       })
     },
     async (input) => {
@@ -7622,13 +7802,27 @@ Automatically detects code files and skips ignored directories like node_modules
       if (!projectId) {
         return errorResult("Error: project_id is required. Please call session_init first or provide project_id explicitly.");
       }
+      const pathCheck = await validateReadableDirectory(input.path);
+      if (!pathCheck.ok) {
+        return errorResult(pathCheck.error);
+      }
+      const fileCheck = await countIndexableFiles(pathCheck.resolvedPath, { maxFiles: 1 });
+      if (fileCheck.count === 0) {
+        return errorResult(
+          `Error: no indexable files found in directory: ${input.path}. The directory may be empty or contain only ignored files/directories. Supported file types include: .ts, .js, .py, .rs, .go, .java, .md, .json, etc.`
+        );
+      }
+      const ingestOptions = {
+        ...input.write_to_disk !== void 0 && { write_to_disk: input.write_to_disk },
+        ...input.overwrite !== void 0 && { overwrite: input.overwrite }
+      };
       (async () => {
         try {
           let totalIndexed = 0;
           let batchCount = 0;
-          console.error(`[ContextStream] Starting background ingestion for project ${projectId} from ${input.path}`);
-          for await (const batch of readAllFilesInBatches(input.path, { batchSize: 50 })) {
-            const result = await client.ingestFiles(projectId, batch);
+          console.error(`[ContextStream] Starting background ingestion for project ${projectId} from ${pathCheck.resolvedPath}`);
+          for await (const batch of readAllFilesInBatches(pathCheck.resolvedPath, { batchSize: 50 })) {
+            const result = await client.ingestFiles(projectId, batch, ingestOptions);
             totalIndexed += result.data?.files_indexed ?? batch.length;
             batchCount++;
           }
@@ -7642,6 +7836,8 @@ Automatically detects code files and skips ignored directories like node_modules
         message: "Ingestion running in background",
         project_id: projectId,
         path: input.path,
+        ...input.write_to_disk && { write_to_disk: input.write_to_disk },
+        ...input.overwrite && { overwrite: input.overwrite },
         note: "Use 'projects_index_status' to monitor progress."
       };
       return {
@@ -7705,7 +7901,7 @@ Automatically detects code files and skips ignored directories like node_modules
     "workspaces_content",
     {
       title: "Workspace content",
-      description: "List content in a workspace",
+      description: "List content in a workspace (paginated list: items, total, page, per_page, has_next, has_prev).",
       inputSchema: external_exports.object({ workspace_id: external_exports.string().uuid().optional() })
     },
     async (input) => {
@@ -8051,7 +8247,7 @@ Optionally generates AI editor rules for automatic ContextStream usage.`,
       const result = await client.associateWorkspace(input);
       let rulesGenerated = [];
       if (input.generate_editor_rules) {
-        const fs5 = await import("fs");
+        const fs6 = await import("fs");
         const path7 = await import("path");
         for (const editor of getAvailableEditors()) {
           const rule = generateRuleContent(editor, {
@@ -8063,14 +8259,14 @@ Optionally generates AI editor rules for automatic ContextStream usage.`,
             try {
               let existingContent = "";
               try {
-                existingContent = fs5.readFileSync(filePath, "utf-8");
+                existingContent = fs6.readFileSync(filePath, "utf-8");
               } catch {
               }
               if (!existingContent) {
-                fs5.writeFileSync(filePath, rule.content);
+                fs6.writeFileSync(filePath, rule.content);
                 rulesGenerated.push(rule.filename);
               } else if (!existingContent.includes("ContextStream Integration")) {
-                fs5.writeFileSync(filePath, existingContent + "\n\n" + rule.content);
+                fs6.writeFileSync(filePath, existingContent + "\n\n" + rule.content);
                 rulesGenerated.push(rule.filename + " (appended)");
               }
             } catch {
@@ -8156,7 +8352,7 @@ Behavior:
       });
       let rulesGenerated = [];
       if (input.generate_editor_rules) {
-        const fs5 = await import("fs");
+        const fs6 = await import("fs");
         const path7 = await import("path");
         for (const editor of getAvailableEditors()) {
           const rule = generateRuleContent(editor, {
@@ -8168,14 +8364,14 @@ Behavior:
           try {
             let existingContent = "";
             try {
-              existingContent = fs5.readFileSync(filePath, "utf-8");
+              existingContent = fs6.readFileSync(filePath, "utf-8");
             } catch {
             }
             if (!existingContent) {
-              fs5.writeFileSync(filePath, rule.content);
+              fs6.writeFileSync(filePath, rule.content);
               rulesGenerated.push(rule.filename);
             } else if (!existingContent.includes("ContextStream Integration")) {
-              fs5.writeFileSync(filePath, existingContent + "\n\n" + rule.content);
+              fs6.writeFileSync(filePath, existingContent + "\n\n" + rule.content);
               rulesGenerated.push(rule.filename + " (appended)");
             }
           } catch {
@@ -8594,7 +8790,7 @@ Supported editors: ${getAvailableEditors().join(", ")}`,
       })
     },
     async (input) => {
-      const fs5 = await import("fs");
+      const fs6 = await import("fs");
       const path7 = await import("path");
       const editors = input.editors?.includes("all") || !input.editors ? getAvailableEditors() : input.editors.filter((e) => e !== "all");
       const results = [];
@@ -8622,15 +8818,15 @@ Supported editors: ${getAvailableEditors().join(", ")}`,
           try {
             let existingContent = "";
             try {
-              existingContent = fs5.readFileSync(filePath, "utf-8");
+              existingContent = fs6.readFileSync(filePath, "utf-8");
             } catch {
             }
             if (existingContent && !existingContent.includes("ContextStream Integration")) {
               const updatedContent = existingContent + "\n\n" + rule.content;
-              fs5.writeFileSync(filePath, updatedContent);
+              fs6.writeFileSync(filePath, updatedContent);
               results.push({ editor, filename: rule.filename, status: "appended to existing" });
             } else {
-              fs5.writeFileSync(filePath, rule.content);
+              fs6.writeFileSync(filePath, rule.content);
               results.push({ editor, filename: rule.filename, status: "created" });
             }
           } catch (err) {
@@ -9368,11 +9564,11 @@ var SessionManager = class {
     }
     if (this.ideRoots.length === 0) {
       const cwd = process.cwd();
-      const fs5 = await import("fs");
+      const fs6 = await import("fs");
       const projectIndicators = [".git", "package.json", "Cargo.toml", "pyproject.toml", ".contextstream"];
       const hasProjectIndicator = projectIndicators.some((f) => {
         try {
-          return fs5.existsSync(`${cwd}/${f}`);
+          return fs6.existsSync(`${cwd}/${f}`);
         } catch {
           return false;
         }
@@ -9554,14 +9750,14 @@ import { homedir as homedir3 } from "os";
 import { join as join6 } from "path";
 
 // src/setup.ts
-import * as fs4 from "node:fs/promises";
+import * as fs5 from "node:fs/promises";
 import * as path6 from "node:path";
 import { homedir as homedir2 } from "node:os";
 import { stdin, stdout } from "node:process";
 import { createInterface } from "node:readline/promises";
 
 // src/credentials.ts
-import * as fs3 from "node:fs/promises";
+import * as fs4 from "node:fs/promises";
 import * as path5 from "node:path";
 import { homedir } from "node:os";
 function normalizeApiUrl(input) {
@@ -9576,7 +9772,7 @@ function isRecord(value) {
 async function readSavedCredentials() {
   const filePath = credentialsFilePath();
   try {
-    const raw = await fs3.readFile(filePath, "utf8");
+    const raw = await fs4.readFile(filePath, "utf8");
     const parsed = JSON.parse(raw);
     if (!isRecord(parsed)) return null;
     const version = parsed.version;
@@ -9602,7 +9798,7 @@ async function readSavedCredentials() {
 }
 async function writeSavedCredentials(input) {
   const filePath = credentialsFilePath();
-  await fs3.mkdir(path5.dirname(filePath), { recursive: true });
+  await fs4.mkdir(path5.dirname(filePath), { recursive: true });
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const existing = await readSavedCredentials();
   const value = {
@@ -9614,9 +9810,9 @@ async function writeSavedCredentials(input) {
     updated_at: now
   };
   const body = JSON.stringify(value, null, 2) + "\n";
-  await fs3.writeFile(filePath, body, { encoding: "utf8", mode: 384 });
+  await fs4.writeFile(filePath, body, { encoding: "utf8", mode: 384 });
   try {
-    await fs3.chmod(filePath, 384);
+    await fs4.chmod(filePath, 384);
   } catch {
   }
   return { path: filePath, value };
@@ -9660,23 +9856,23 @@ function parseNumberList(input, max) {
 }
 async function fileExists(filePath) {
   try {
-    await fs4.stat(filePath);
+    await fs5.stat(filePath);
     return true;
   } catch {
     return false;
   }
 }
 async function upsertTextFile(filePath, content, marker) {
-  await fs4.mkdir(path6.dirname(filePath), { recursive: true });
+  await fs5.mkdir(path6.dirname(filePath), { recursive: true });
   const exists = await fileExists(filePath);
   if (!exists) {
-    await fs4.writeFile(filePath, content, "utf8");
+    await fs5.writeFile(filePath, content, "utf8");
     return "created";
   }
-  const existing = await fs4.readFile(filePath, "utf8").catch(() => "");
+  const existing = await fs5.readFile(filePath, "utf8").catch(() => "");
   if (existing.includes(marker)) return "skipped";
   const joined = existing.trimEnd() + "\n\n" + content.trim() + "\n";
-  await fs4.writeFile(filePath, joined, "utf8");
+  await fs5.writeFile(filePath, joined, "utf8");
   return "appended";
 }
 function globalRulesPathForEditor(editor) {
@@ -9703,24 +9899,32 @@ function globalRulesPathForEditor(editor) {
   }
 }
 function buildContextStreamMcpServer(params) {
+  const env = {
+    CONTEXTSTREAM_API_URL: params.apiUrl,
+    CONTEXTSTREAM_API_KEY: params.apiKey
+  };
+  if (params.toolset) {
+    env.CONTEXTSTREAM_TOOLSET = params.toolset;
+  }
   return {
     command: "npx",
     args: ["-y", "@contextstream/mcp-server"],
-    env: {
-      CONTEXTSTREAM_API_URL: params.apiUrl,
-      CONTEXTSTREAM_API_KEY: params.apiKey
-    }
+    env
   };
 }
 function buildContextStreamVsCodeServer(params) {
+  const env = {
+    CONTEXTSTREAM_API_URL: params.apiUrl,
+    CONTEXTSTREAM_API_KEY: params.apiKey
+  };
+  if (params.toolset) {
+    env.CONTEXTSTREAM_TOOLSET = params.toolset;
+  }
   return {
     type: "stdio",
     command: "npx",
     args: ["-y", "@contextstream/mcp-server"],
-    env: {
-      CONTEXTSTREAM_API_URL: params.apiUrl,
-      CONTEXTSTREAM_API_KEY: params.apiKey
-    }
+    env
   };
 }
 function stripJsonComments(input) {
@@ -9742,11 +9946,11 @@ function tryParseJsonLike(raw) {
   }
 }
 async function upsertJsonMcpConfig(filePath, server) {
-  await fs4.mkdir(path6.dirname(filePath), { recursive: true });
+  await fs5.mkdir(path6.dirname(filePath), { recursive: true });
   const exists = await fileExists(filePath);
   let root = {};
   if (exists) {
-    const raw = await fs4.readFile(filePath, "utf8").catch(() => "");
+    const raw = await fs5.readFile(filePath, "utf8").catch(() => "");
     const parsed = tryParseJsonLike(raw);
     if (!parsed.ok) throw new Error(`Invalid JSON in ${filePath}: ${parsed.error}`);
     root = parsed.value;
@@ -9756,16 +9960,16 @@ async function upsertJsonMcpConfig(filePath, server) {
   const before = JSON.stringify(root.mcpServers.contextstream ?? null);
   root.mcpServers.contextstream = server;
   const after = JSON.stringify(root.mcpServers.contextstream ?? null);
-  await fs4.writeFile(filePath, JSON.stringify(root, null, 2) + "\n", "utf8");
+  await fs5.writeFile(filePath, JSON.stringify(root, null, 2) + "\n", "utf8");
   if (!exists) return "created";
   return before === after ? "skipped" : "updated";
 }
 async function upsertJsonVsCodeMcpConfig(filePath, server) {
-  await fs4.mkdir(path6.dirname(filePath), { recursive: true });
+  await fs5.mkdir(path6.dirname(filePath), { recursive: true });
   const exists = await fileExists(filePath);
   let root = {};
   if (exists) {
-    const raw = await fs4.readFile(filePath, "utf8").catch(() => "");
+    const raw = await fs5.readFile(filePath, "utf8").catch(() => "");
     const parsed = tryParseJsonLike(raw);
     if (!parsed.ok) throw new Error(`Invalid JSON in ${filePath}: ${parsed.error}`);
     root = parsed.value;
@@ -9775,7 +9979,7 @@ async function upsertJsonVsCodeMcpConfig(filePath, server) {
   const before = JSON.stringify(root.servers.contextstream ?? null);
   root.servers.contextstream = server;
   const after = JSON.stringify(root.servers.contextstream ?? null);
-  await fs4.writeFile(filePath, JSON.stringify(root, null, 2) + "\n", "utf8");
+  await fs5.writeFile(filePath, JSON.stringify(root, null, 2) + "\n", "utf8");
   if (!exists) return "created";
   return before === after ? "skipped" : "updated";
 }
@@ -9791,9 +9995,9 @@ function claudeDesktopConfigPath() {
   return null;
 }
 async function upsertCodexTomlConfig(filePath, params) {
-  await fs4.mkdir(path6.dirname(filePath), { recursive: true });
+  await fs5.mkdir(path6.dirname(filePath), { recursive: true });
   const exists = await fileExists(filePath);
-  const existing = exists ? await fs4.readFile(filePath, "utf8").catch(() => "") : "";
+  const existing = exists ? await fs5.readFile(filePath, "utf8").catch(() => "") : "";
   const marker = "[mcp_servers.contextstream]";
   const envMarker = "[mcp_servers.contextstream.env]";
   const block = `
@@ -9808,15 +10012,15 @@ CONTEXTSTREAM_API_URL = "${params.apiUrl}"
 CONTEXTSTREAM_API_KEY = "${params.apiKey}"
 `;
   if (!exists) {
-    await fs4.writeFile(filePath, block.trimStart(), "utf8");
+    await fs5.writeFile(filePath, block.trimStart(), "utf8");
     return "created";
   }
   if (!existing.includes(marker)) {
-    await fs4.writeFile(filePath, existing.trimEnd() + block, "utf8");
+    await fs5.writeFile(filePath, existing.trimEnd() + block, "utf8");
     return "updated";
   }
   if (!existing.includes(envMarker)) {
-    await fs4.writeFile(filePath, existing.trimEnd() + "\n\n" + envMarker + `
+    await fs5.writeFile(filePath, existing.trimEnd() + "\n\n" + envMarker + `
 CONTEXTSTREAM_API_URL = "${params.apiUrl}"
 CONTEXTSTREAM_API_KEY = "${params.apiKey}"
 `, "utf8");
@@ -9857,11 +10061,11 @@ CONTEXTSTREAM_API_KEY = "${params.apiKey}"
   }
   const updated = out.join("\n");
   if (updated === existing) return "skipped";
-  await fs4.writeFile(filePath, updated, "utf8");
+  await fs5.writeFile(filePath, updated, "utf8");
   return "updated";
 }
 async function discoverProjectsUnderFolder(parentFolder) {
-  const entries = await fs4.readdir(parentFolder, { withFileTypes: true });
+  const entries = await fs5.readdir(parentFolder, { withFileTypes: true });
   const candidates = entries.filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => path6.join(parentFolder, e.name));
   const projects = [];
   for (const dir of candidates) {
@@ -9970,10 +10174,10 @@ Code: ${device.user_code}`);
           if (poll && poll.status === "pending") {
             const intervalSeconds = typeof poll.interval === "number" ? poll.interval : 5;
             const waitMs = Math.max(1, intervalSeconds) * 1e3;
-            await new Promise((resolve2) => setTimeout(resolve2, waitMs));
+            await new Promise((resolve3) => setTimeout(resolve3, waitMs));
             continue;
           }
-          await new Promise((resolve2) => setTimeout(resolve2, 1e3));
+          await new Promise((resolve3) => setTimeout(resolve3, 1e3));
         }
         if (!accessToken) {
           throw new Error("Browser login expired or was not approved in time. Please run setup again.");
@@ -10106,6 +10310,7 @@ Created API key: ${maskApiKey(apiKey)}
     const mcpChoice = normalizeInput(await rl.question(`Choose [${hasCodex && !hasProjectMcpEditors ? "1/2" : "1/2/3/4"}] (default ${mcpChoiceDefault}): `)) || mcpChoiceDefault;
     const mcpScope = mcpChoice === "2" && hasCodex && !hasProjectMcpEditors ? "skip" : mcpChoice === "4" ? "skip" : mcpChoice === "1" ? "global" : mcpChoice === "2" ? "project" : "both";
     const mcpServer = buildContextStreamMcpServer({ apiUrl, apiKey });
+    const mcpServerClaude = buildContextStreamMcpServer({ apiUrl, apiKey, toolset: "core" });
     const vsCodeServer = buildContextStreamVsCodeServer({ apiUrl, apiKey });
     const needsGlobalMcpConfig = mcpScope === "global" || mcpScope === "both" || mcpScope === "project" && hasCodex;
     if (needsGlobalMcpConfig) {
@@ -10146,14 +10351,14 @@ Created API key: ${maskApiKey(apiKey)}
                   writeActions.push({ kind: "mcp-config", target: desktopPath, status: "dry-run" });
                   console.log(`- Claude Desktop: would update ${desktopPath}`);
                 } else {
-                  const status = await upsertJsonMcpConfig(desktopPath, mcpServer);
+                  const status = await upsertJsonMcpConfig(desktopPath, mcpServerClaude);
                   writeActions.push({ kind: "mcp-config", target: desktopPath, status });
                   console.log(`- Claude Desktop: ${status} ${desktopPath}`);
                 }
               }
             }
             console.log("- Claude Code: global MCP config is best done via `claude mcp add --transport stdio ...` (see docs).");
-            console.log("  macOS/Linux: claude mcp add --transport stdio contextstream --scope user --env CONTEXTSTREAM_API_URL=... --env CONTEXTSTREAM_API_KEY=... -- npx -y @contextstream/mcp-server");
+            console.log("  macOS/Linux: claude mcp add --transport stdio contextstream --scope user --env CONTEXTSTREAM_API_URL=... --env CONTEXTSTREAM_API_KEY=... --env CONTEXTSTREAM_TOOLSET=core -- npx -y @contextstream/mcp-server");
             console.log("  Windows (native): use `cmd /c npx -y @contextstream/mcp-server` after `--` if `npx` is not found.");
             continue;
           }
@@ -10294,7 +10499,7 @@ Applying to ${projects.length} project(s)...`);
               if (dryRun) {
                 writeActions.push({ kind: "mcp-config", target: mcpPath, status: "dry-run" });
               } else {
-                const status = await upsertJsonMcpConfig(mcpPath, mcpServer);
+                const status = await upsertJsonMcpConfig(mcpPath, mcpServerClaude);
                 writeActions.push({ kind: "mcp-config", target: mcpPath, status });
               }
               continue;
@@ -10408,6 +10613,8 @@ Environment variables:
   CONTEXTSTREAM_JWT       JWT for authentication (alternative to API key)
   CONTEXTSTREAM_WORKSPACE_ID  Optional default workspace ID
   CONTEXTSTREAM_PROJECT_ID    Optional default project ID
+  CONTEXTSTREAM_TOOLSET       Optional tool bundle (core|full). Defaults to core to reduce tool context size.
+  CONTEXTSTREAM_TOOL_ALLOWLIST Optional comma-separated tool names to expose (overrides toolset)
   CONTEXTSTREAM_PRO_TOOLS     Optional comma-separated PRO tool names (default: AI tools)
   CONTEXTSTREAM_UPGRADE_URL   Optional upgrade URL shown for PRO tools on Free plan
 

package/package.json

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