@contextstream/mcp-server 0.3.63 → 0.3.64

package/dist/index.js

@@ -7788,6 +7788,198 @@ function getCoreToolsHint() {
 // src/tools.ts
 var LESSON_DEDUP_WINDOW_MS = 2 * 60 * 1e3;
 var recentLessonCaptures = /* @__PURE__ */ new Map();
+var DEFAULT_PARAM_DESCRIPTIONS = {
+  api_key: "ContextStream API key.",
+  apiKey: "ContextStream API key.",
+  jwt: "ContextStream JWT for authentication.",
+  workspace_id: "Workspace ID (UUID).",
+  workspaceId: "Workspace ID (UUID).",
+  project_id: "Project ID (UUID).",
+  projectId: "Project ID (UUID).",
+  node_id: "Node ID (UUID).",
+  event_id: "Event ID (UUID).",
+  reminder_id: "Reminder ID (UUID).",
+  folder_path: "Absolute path to the local folder.",
+  file_path: "Filesystem path to the file.",
+  path: "Filesystem path.",
+  name: "Name for the resource.",
+  title: "Short descriptive title.",
+  description: "Short description.",
+  content: "Full content/body.",
+  query: "Search query string.",
+  limit: "Maximum number of results to return.",
+  page: "Page number for pagination.",
+  page_size: "Results per page.",
+  include_decisions: "Include related decisions.",
+  include_related: "Include related context.",
+  include_transitive: "Include transitive dependencies.",
+  max_depth: "Maximum traversal depth.",
+  since: "ISO 8601 timestamp to query changes since.",
+  remind_at: "ISO 8601 datetime for the reminder.",
+  priority: "Priority level.",
+  recurrence: "Recurrence pattern (daily, weekly, monthly).",
+  keywords: "Keywords for matching.",
+  overwrite: "Allow overwriting existing files on disk.",
+  write_to_disk: "Write ingested files to disk before indexing.",
+  await_indexing: "Wait for indexing to finish before returning.",
+  auto_index: "Automatically index on creation.",
+  session_id: "Session identifier.",
+  context_hint: "User message used to fetch relevant context.",
+  context: "Context to match relevant reminders."
+};
+var WRITE_VERBS = /* @__PURE__ */ new Set([
+  "create",
+  "update",
+  "delete",
+  "ingest",
+  "index",
+  "capture",
+  "remember",
+  "associate",
+  "bootstrap",
+  "snooze",
+  "complete",
+  "dismiss",
+  "generate",
+  "sync",
+  "publish",
+  "set",
+  "add",
+  "remove",
+  "revoke",
+  "upload",
+  "compress",
+  "init"
+]);
+var READ_ONLY_OVERRIDES = /* @__PURE__ */ new Set([
+  "session_tools",
+  "context_smart",
+  "session_summary",
+  "session_recall",
+  "session_get_user_context",
+  "session_get_lessons",
+  "session_smart_search",
+  "session_delta",
+  "projects_list",
+  "projects_get",
+  "projects_overview",
+  "projects_statistics",
+  "projects_files",
+  "projects_index_status",
+  "workspaces_list",
+  "workspaces_get",
+  "memory_search",
+  "memory_decisions",
+  "memory_get_event",
+  "memory_list_events",
+  "memory_list_nodes",
+  "memory_summary",
+  "memory_timeline",
+  "graph_related",
+  "graph_decisions",
+  "graph_path",
+  "graph_dependencies",
+  "graph_call_path",
+  "graph_impact",
+  "graph_circular_dependencies",
+  "graph_unused_code",
+  "search_semantic",
+  "search_hybrid",
+  "search_keyword",
+  "search_pattern",
+  "reminders_list",
+  "reminders_active",
+  "auth_me",
+  "mcp_server_version"
+]);
+var DESTRUCTIVE_VERBS = /* @__PURE__ */ new Set(["delete", "dismiss", "remove", "revoke", "supersede"]);
+var OPEN_WORLD_PREFIXES = /* @__PURE__ */ new Set(["github", "slack", "integrations"]);
+function humanizeKey(raw) {
+  const withSpaces = raw.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/_/g, " ");
+  return withSpaces.toLowerCase();
+}
+function buildParamDescription(key, path7) {
+  const normalized = key in DEFAULT_PARAM_DESCRIPTIONS ? key : key.toLowerCase();
+  const parent = path7[path7.length - 1];
+  if (parent === "target") {
+    if (key === "id") return "Target identifier (module path, function id, etc.).";
+    if (key === "type") return "Target type (module, file, function, type, variable).";
+  }
+  if (parent === "source") {
+    if (key === "id") return "Source identifier (module path, function id, etc.).";
+    if (key === "type") return "Source type (module, file, function, type, variable).";
+  }
+  if (DEFAULT_PARAM_DESCRIPTIONS[normalized]) {
+    return DEFAULT_PARAM_DESCRIPTIONS[normalized];
+  }
+  if (normalized.endsWith("_id")) {
+    return `ID for the ${humanizeKey(normalized.replace(/_id$/, ""))}.`;
+  }
+  if (normalized.startsWith("include_")) {
+    return `Whether to include ${humanizeKey(normalized.replace("include_", ""))}.`;
+  }
+  if (normalized.startsWith("max_")) {
+    return `Maximum ${humanizeKey(normalized.replace("max_", ""))}.`;
+  }
+  if (normalized.startsWith("min_")) {
+    return `Minimum ${humanizeKey(normalized.replace("min_", ""))}.`;
+  }
+  return `Input parameter: ${humanizeKey(normalized)}.`;
+}
+function getDescription(schema) {
+  const def = schema._def;
+  if (def?.description && def.description.trim()) return def.description;
+  return void 0;
+}
+function applyParamDescriptions(schema, path7 = []) {
+  if (!(schema instanceof external_exports.ZodObject)) {
+    return schema;
+  }
+  const shape = schema.shape;
+  let changed = false;
+  const nextShape = {};
+  for (const [key, field] of Object.entries(shape)) {
+    let nextField = field;
+    const existingDescription = getDescription(field);
+    if (field instanceof external_exports.ZodObject) {
+      const nested = applyParamDescriptions(field, [...path7, key]);
+      if (nested !== field) {
+        nextField = nested;
+        changed = true;
+      }
+    }
+    if (existingDescription) {
+      if (!getDescription(nextField)) {
+        nextField = nextField.describe(existingDescription);
+        changed = true;
+      }
+    } else {
+      nextField = nextField.describe(buildParamDescription(key, path7));
+      changed = true;
+    }
+    nextShape[key] = nextField;
+  }
+  if (!changed) return schema;
+  let nextSchema = external_exports.object(nextShape);
+  const def = schema._def;
+  if (def?.catchall) nextSchema = nextSchema.catchall(def.catchall);
+  if (def?.unknownKeys === "passthrough") nextSchema = nextSchema.passthrough();
+  if (def?.unknownKeys === "strict") nextSchema = nextSchema.strict();
+  return nextSchema;
+}
+function inferToolAnnotations(toolName) {
+  const parts = toolName.split("_");
+  const prefix = parts[0] || toolName;
+  const readOnly = READ_ONLY_OVERRIDES.has(toolName) || !parts.some((part) => WRITE_VERBS.has(part));
+  const destructive = readOnly ? false : parts.some((part) => DESTRUCTIVE_VERBS.has(part));
+  const openWorld = OPEN_WORLD_PREFIXES.has(prefix);
+  return {
+    readOnlyHint: readOnly,
+    destructiveHint: readOnly ? false : destructive,
+    idempotentHint: readOnly,
+    openWorldHint: openWorld
+  };
+}
 function normalizeHeaderValue(value) {
   if (!value) return void 0;
   return Array.isArray(value) ? value[0] : value;
@@ -8043,7 +8235,7 @@ function isDuplicateLessonCapture(signature) {
   return false;
 }
 function registerTools(server, client, sessionManager) {
-  const upgradeUrl = process.env.CONTEXTSTREAM_UPGRADE_URL || "https://contextstream.io/pricing";
+  const upgradeUrl2 = process.env.CONTEXTSTREAM_UPGRADE_URL || "https://contextstream.io/pricing";
   const toolFilter = resolveToolFilter();
   const toolAllowlist = toolFilter.allowlist;
   if (toolAllowlist) {
@@ -8099,7 +8291,7 @@ function registerTools(server, client, sessionManager) {
     return errorResult(
       [
         `Access denied: \`${toolName}\` requires ContextStream PRO.`,
-        `Upgrade: ${upgradeUrl}`
+        `Upgrade: ${upgradeUrl2}`
       ].join("\n")
     );
   }
@@ -8127,7 +8319,7 @@ function registerTools(server, client, sessionManager) {
       [
         `Access denied: \`${toolName}\` is limited to Graph-Lite (module-level, 1-hop queries).`,
         detail,
-        `Upgrade to Elite or Team for full graph access: ${upgradeUrl}`
+        `Upgrade to Elite or Team for full graph access: ${upgradeUrl2}`
       ].join("\n")
     );
   }
@@ -8142,7 +8334,7 @@ function registerTools(server, client, sessionManager) {
           [
             `Access denied: \`${toolName}\` requires Elite or Team (Full Graph).`,
             "Pro includes Graph-Lite (module-level dependencies and 1-hop impact only).",
-            `Upgrade: ${upgradeUrl}`
+            `Upgrade: ${upgradeUrl2}`
           ].join("\n")
         );
       }
@@ -8187,7 +8379,7 @@ function registerTools(server, client, sessionManager) {
     return errorResult(
       [
         `Access denied: \`${toolName}\` requires ContextStream Pro (Graph-Lite) or Elite/Team (Full Graph).`,
-        `Upgrade: ${upgradeUrl}`
+        `Upgrade: ${upgradeUrl2}`
       ].join("\n")
     );
   }
@@ -8235,7 +8427,15 @@ function registerTools(server, client, sessionManager) {
       title: `${config.title} (${accessLabel})`,
       description: `${config.description}
 
-Access: ${accessLabel}${showUpgrade ? ` (upgrade: ${upgradeUrl})` : ""}`
+Access: ${accessLabel}${showUpgrade ? ` (upgrade: ${upgradeUrl2})` : ""}`
+    };
+    const annotatedConfig = {
+      ...labeledConfig,
+      inputSchema: labeledConfig.inputSchema ? applyParamDescriptions(labeledConfig.inputSchema) : void 0,
+      annotations: {
+        ...inferToolAnnotations(name),
+        ...labeledConfig.annotations
+      }
     };
     const safeHandler = async (input, extra) => {
       try {
@@ -8248,7 +8448,7 @@ Access: ${accessLabel}${showUpgrade ? ` (upgrade: ${upgradeUrl})` : ""}`
         const errorCode = error?.code || error?.status || "UNKNOWN_ERROR";
         const isPlanLimit = String(errorCode).toUpperCase() === "FORBIDDEN" && String(errorMessage).toLowerCase().includes("plan limit reached");
         const upgradeHint = isPlanLimit ? `
-Upgrade: ${upgradeUrl}` : "";
+Upgrade: ${upgradeUrl2}` : "";
         const errorPayload = {
           success: false,
           error: {
@@ -8267,7 +8467,7 @@ Upgrade: ${upgradeUrl}` : "";
     };
     server.registerTool(
       name,
-      labeledConfig,
+      annotatedConfig,
       wrapWithAutoContext(name, safeHandler)
     );
   }
@@ -11132,10 +11332,33 @@ import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 function wrapText(uri, text) {
   return { contents: [{ uri, text }] };
 }
+function wrapResource(resource) {
+  return { resources: [resource] };
+}
+function extractItems(payload) {
+  if (!payload || typeof payload !== "object") return [];
+  const direct = payload.items;
+  if (Array.isArray(direct)) return direct;
+  const nested = payload.data;
+  if (nested && typeof nested === "object") {
+    const nestedItems = nested.items;
+    if (Array.isArray(nestedItems)) return nestedItems;
+    if (Array.isArray(nested)) return nested;
+  }
+  return [];
+}
 function registerResources(server, client, apiUrl) {
   server.registerResource(
     "contextstream-openapi",
-    new ResourceTemplate("contextstream:openapi", { list: void 0 }),
+    new ResourceTemplate("contextstream:openapi", {
+      list: () => wrapResource({
+        uri: "contextstream:openapi",
+        name: "contextstream-openapi",
+        title: "ContextStream OpenAPI",
+        description: "Machine-readable OpenAPI from the configured API endpoint",
+        mimeType: "application/json"
+      })
+    }),
     {
       title: "ContextStream OpenAPI spec",
       description: "Machine-readable OpenAPI from the configured API endpoint",
@@ -11150,7 +11373,15 @@ function registerResources(server, client, apiUrl) {
   );
   server.registerResource(
     "contextstream-workspaces",
-    new ResourceTemplate("contextstream:workspaces", { list: void 0 }),
+    new ResourceTemplate("contextstream:workspaces", {
+      list: () => wrapResource({
+        uri: "contextstream:workspaces",
+        name: "contextstream-workspaces",
+        title: "Workspaces",
+        description: "List of accessible workspaces",
+        mimeType: "application/json"
+      })
+    }),
     { title: "Workspaces", description: "List of accessible workspaces" },
     async () => {
       const data = await client.listWorkspaces();
@@ -11159,7 +11390,36 @@ function registerResources(server, client, apiUrl) {
   );
   server.registerResource(
     "contextstream-projects",
-    new ResourceTemplate("contextstream:projects/{workspaceId}", { list: void 0 }),
+    new ResourceTemplate("contextstream:projects/{workspaceId}", {
+      list: async () => {
+        try {
+          const workspaces = await client.listWorkspaces({ page_size: 50 });
+          const items = extractItems(workspaces);
+          return {
+            resources: items.map((workspace) => ({
+              uri: `contextstream:projects/${workspace.id}`,
+              name: `contextstream-projects-${workspace.id}`,
+              title: workspace.name ? `Projects in ${workspace.name}` : "Projects in workspace",
+              description: "Projects in the specified workspace",
+              mimeType: "application/json"
+            }))
+          };
+        } catch {
+          return { resources: [] };
+        }
+      },
+      complete: {
+        workspaceId: async () => {
+          try {
+            const workspaces = await client.listWorkspaces({ page_size: 50 });
+            const items = extractItems(workspaces);
+            return items.map((workspace) => workspace.id);
+          } catch {
+            return [];
+          }
+        }
+      }
+    }),
     { title: "Projects for workspace", description: "Projects in the specified workspace" },
     async (uri, { workspaceId }) => {
       const wsId = Array.isArray(workspaceId) ? workspaceId[0] : workspaceId;
@@ -11169,6 +11429,723 @@ function registerResources(server, client, apiUrl) {
   );
 }
 
+// src/prompts.ts
+var ID_NOTES = [
+  "Notes:",
+  "- If ContextStream is not initialized in this conversation, call `session_init` first (omit ids).",
+  "- Do not ask me for `workspace_id`/`project_id` \u2014 use session defaults or IDs returned by `session_init`.",
+  "- Prefer omitting IDs in tool calls when the tool supports defaults."
+];
+var upgradeUrl = process.env.CONTEXTSTREAM_UPGRADE_URL || "https://contextstream.io/pricing";
+var proPrompts = /* @__PURE__ */ new Set([
+  "build-context",
+  "generate-plan",
+  "generate-tasks",
+  "token-budget-context"
+]);
+function promptAccessLabel(promptName) {
+  return proPrompts.has(promptName) ? "PRO" : "Free";
+}
+function registerPrompts(server) {
+  server.registerPrompt(
+    "explore-codebase",
+    {
+      title: `Explore Codebase (${promptAccessLabel("explore-codebase")})`,
+      description: "Get an overview of a project codebase structure and key components"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "I want to understand the current codebase.",
+              "",
+              ...ID_NOTES,
+              "",
+              "Please help me by:",
+              "1. Use `projects_overview` to get a project summary (use session defaults; only pass `project_id` if required).",
+              "2. Use `projects_files` to identify key entry points.",
+              "3. If a focus area is clear from our conversation, prioritize it; otherwise ask me what to focus on.",
+              "4. Use `search_semantic` (and optionally `search_hybrid`) to find the most relevant files.",
+              "5. Summarize the architecture, major modules, and where to start editing."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "capture-decision",
+    {
+      title: `Capture Decision (${promptAccessLabel("capture-decision")})`,
+      description: "Document an architectural or technical decision in workspace memory"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Please capture an architectural/technical decision in ContextStream memory.",
+              "",
+              ...ID_NOTES,
+              "",
+              "Instructions:",
+              "- If the decision is already described in this conversation, extract: title, context, decision, consequences/tradeoffs.",
+              "- If anything is missing, ask me 1\u20133 quick questions to fill the gaps.",
+              "- Then call `session_capture` with:",
+              '  - event_type: "decision"',
+              "  - title: (short ADR title)",
+              "  - content: a well-formatted ADR (Context, Decision, Consequences)",
+              '  - tags: include relevant tags (e.g., "adr", "architecture")',
+              '  - importance: "high"',
+              "",
+              "After capturing, confirm what was saved."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "review-context",
+    {
+      title: `Code Review Context (${promptAccessLabel("review-context")})`,
+      description: "Build context for reviewing code changes"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "I need context to review a set of code changes.",
+              "",
+              ...ID_NOTES,
+              "",
+              "First:",
+              "- If file paths and a short change description are not already in this conversation, ask me for them.",
+              "",
+              "Then build review context by:",
+              "1. Using `graph_dependencies` to find what depends on the changed areas.",
+              "2. Using `graph_impact` to assess potential blast radius.",
+              "3. Using `memory_search` to find related decisions/notes.",
+              "4. Using `search_semantic` to find related code patterns.",
+              "",
+              "Provide:",
+              "- What the files/components do",
+              "- What might be affected",
+              "- Relevant prior decisions/lessons",
+              "- Review checklist + risks to focus on"
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "investigate-bug",
+    {
+      title: `Investigate Bug (${promptAccessLabel("investigate-bug")})`,
+      description: "Build context for debugging an issue"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "I want help investigating a bug.",
+              "",
+              ...ID_NOTES,
+              "",
+              "First:",
+              "- If the error/symptom is not already stated, ask me for the exact error message and what I expected vs what happened.",
+              "- If an affected area/component is not known, ask me where I noticed it.",
+              "",
+              "Then:",
+              "1. Use `search_semantic` to find code related to the error/symptom.",
+              "2. Use `search_pattern` to locate where similar errors are thrown or logged.",
+              "3. If you identify key functions, use `graph_call_path` to trace call flows.",
+              "4. Use `memory_search` to check if we have prior notes/bugs about this area.",
+              "",
+              "Return:",
+              "- Likely origin locations",
+              "- Call flow (if found)",
+              "- Related past context",
+              "- Suggested debugging steps"
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "explore-knowledge",
+    {
+      title: `Explore Knowledge Graph (${promptAccessLabel("explore-knowledge")})`,
+      description: "Navigate and understand the knowledge graph for a workspace"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Help me explore the knowledge captured in this workspace.",
+              "",
+              ...ID_NOTES,
+              "",
+              "Approach:",
+              "1. Use `memory_summary` for a high-level overview.",
+              "2. Use `memory_decisions` to see decision history (titles + a few key details).",
+              "3. Use `memory_list_nodes` to see available knowledge nodes.",
+              "4. If a starting topic is clear from the conversation, use `memory_search` for it.",
+              "5. Use `graph_related` on the most relevant nodes to expand connections.",
+              "",
+              "Provide:",
+              "- Key themes and topics",
+              "- Important decisions + rationale",
+              "- Suggested \u201Cnext nodes\u201D to explore"
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "onboard-to-project",
+    {
+      title: `Project Onboarding (${promptAccessLabel("onboard-to-project")})`,
+      description: "Generate onboarding context for a new team member"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Create an onboarding guide for a new team member joining this project.",
+              "",
+              ...ID_NOTES,
+              "",
+              "First:",
+              "- If the role is not specified, ask me what role they are onboarding into (backend, frontend, fullstack, etc.).",
+              "",
+              "Gather context:",
+              "1. Use `projects_overview` and `projects_statistics` for project summary.",
+              "2. Use `projects_files` to identify key entry points.",
+              "3. Use `memory_timeline` and `memory_decisions` to understand recent changes and architectural choices.",
+              "4. Use `search_semantic` to find READMEs/docs/setup instructions.",
+              "",
+              "Output:",
+              "- Project overview and purpose",
+              "- Tech stack + architecture map",
+              "- Key files/entry points relevant to the role",
+              "- Important decisions + rationale",
+              "- Recent changes/current focus",
+              "- Step-by-step getting started"
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "analyze-refactoring",
+    {
+      title: `Refactoring Analysis (${promptAccessLabel("analyze-refactoring")})`,
+      description: "Analyze a codebase for refactoring opportunities"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Analyze the codebase for refactoring opportunities.",
+              "",
+              ...ID_NOTES,
+              "",
+              "If a target area is obvious from our conversation, focus there; otherwise ask me what area to analyze.",
+              "",
+              "Please investigate:",
+              "1. `graph_circular_dependencies` (circular deps to break)",
+              "2. `graph_unused_code` (dead code to remove)",
+              "3. `search_pattern` (duplication patterns)",
+              "4. `projects_statistics` (high complexity hotspots)",
+              "",
+              "Provide a prioritized list with quick wins vs deeper refactors."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "build-context",
+    {
+      title: `Build LLM Context (${promptAccessLabel("build-context")})`,
+      description: "Build comprehensive context for an LLM task"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Build comprehensive context for the task we are working on.",
+              "",
+              `Access: ${promptAccessLabel("build-context")}${promptAccessLabel("build-context") === "PRO" ? ` (upgrade: ${upgradeUrl})` : ""}`,
+              "",
+              ...ID_NOTES,
+              "",
+              "First:",
+              "- If the \u201Cquery\u201D is clear from the latest user request, use that.",
+              "- Otherwise ask me: \u201CWhat do you need context for?\u201D",
+              "",
+              "Then:",
+              "- Call `ai_enhanced_context` with include_code=true, include_docs=true, include_memory=true (omit IDs unless required).",
+              "- Synthesize the returned context into a short briefing with links/file paths and key decisions/risks."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "smart-search",
+    {
+      title: `Smart Search (${promptAccessLabel("smart-search")})`,
+      description: "Search across memory, decisions, and code for a query"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Find the most relevant context for what I am asking about.",
+              "",
+              ...ID_NOTES,
+              "",
+              "First:",
+              "- If a query is clear from the conversation, use it.",
+              "- Otherwise ask me what I want to find.",
+              "",
+              "Then:",
+              "1. Use `session_smart_search` for the query.",
+              "2. If results are thin, follow up with `search_hybrid` and `memory_search`.",
+              "3. Return the top results with file paths/links and a short synthesis."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "recall-context",
+    {
+      title: `Recall Context (${promptAccessLabel("recall-context")})`,
+      description: "Retrieve relevant past decisions and memory for a query"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Recall relevant past context (decisions, notes, lessons) for what I am asking about.",
+              "",
+              ...ID_NOTES,
+              "",
+              "First:",
+              "- If a recall query is clear from the conversation, use it.",
+              "- Otherwise ask me what topic I want to recall.",
+              "",
+              "Then:",
+              "- Use `session_recall` with the query (omit IDs unless required).",
+              "- Summarize the key points and any relevant decisions/lessons."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "session-summary",
+    {
+      title: `Session Summary (${promptAccessLabel("session-summary")})`,
+      description: "Get a compact summary of workspace/project context"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Generate a compact, token-efficient summary of the current workspace/project context.",
+              "",
+              ...ID_NOTES,
+              "",
+              "Use `session_summary` (default max_tokens=500 unless I specify otherwise).",
+              "Then list:",
+              "- Top decisions (titles only)",
+              "- Any high-priority lessons to watch for"
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "capture-lesson",
+    {
+      title: `Capture Lesson (${promptAccessLabel("capture-lesson")})`,
+      description: "Record a lesson learned from an error or correction"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Capture a lesson learned so it is surfaced in future sessions.",
+              "",
+              ...ID_NOTES,
+              "",
+              "If the lesson details are not fully present in the conversation, ask me for:",
+              "- title (what to remember)",
+              "- severity (low|medium|high|critical, default medium)",
+              "- category (workflow|code_quality|verification|communication|project_specific)",
+              "- trigger (what caused it)",
+              "- impact (what went wrong)",
+              "- prevention (how to prevent it)",
+              "- keywords (optional)",
+              "",
+              "Then call `session_capture_lesson` with those fields and confirm it was saved."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "capture-preference",
+    {
+      title: `Capture Preference (${promptAccessLabel("capture-preference")})`,
+      description: "Save a user preference to memory"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Save a user preference to ContextStream memory.",
+              "",
+              ...ID_NOTES,
+              "",
+              "If the preference is not explicit in the conversation, ask me what to remember.",
+              "",
+              "Then call `session_capture` with:",
+              '- event_type: "preference"',
+              "- title: (short title)",
+              "- content: (preference text)",
+              '- importance: "medium"'
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "capture-task",
+    {
+      title: `Capture Task (${promptAccessLabel("capture-task")})`,
+      description: "Capture an action item into memory"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Capture an action item into ContextStream memory.",
+              "",
+              ...ID_NOTES,
+              "",
+              "If the task is not explicit in the conversation, ask me what to capture.",
+              "",
+              "Then call `session_capture` with:",
+              '- event_type: "task"',
+              "- title: (short title)",
+              "- content: (task details)",
+              '- importance: "medium"'
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "capture-bug",
+    {
+      title: `Capture Bug (${promptAccessLabel("capture-bug")})`,
+      description: "Capture a bug report into workspace memory"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Capture a bug report in ContextStream memory.",
+              "",
+              ...ID_NOTES,
+              "",
+              "If details are missing, ask me for:",
+              "- title",
+              "- description",
+              "- steps to reproduce (optional)",
+              "- expected behavior (optional)",
+              "- actual behavior (optional)",
+              "",
+              "Then call `session_capture` with:",
+              '- event_type: "bug"',
+              "- title: (bug title)",
+              "- content: a well-formatted bug report (include all provided details)",
+              "- tags: component/area tags",
+              '- importance: "high"'
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "capture-feature",
+    {
+      title: `Capture Feature (${promptAccessLabel("capture-feature")})`,
+      description: "Capture a feature request into workspace memory"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Capture a feature request in ContextStream memory.",
+              "",
+              ...ID_NOTES,
+              "",
+              "If details are missing, ask me for:",
+              "- title",
+              "- description",
+              "- rationale (optional)",
+              "- acceptance criteria (optional)",
+              "",
+              "Then call `session_capture` with:",
+              '- event_type: "feature"',
+              "- title: (feature title)",
+              "- content: a well-formatted feature request",
+              "- tags: component/area tags",
+              '- importance: "medium"'
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "generate-plan",
+    {
+      title: `Generate Plan (${promptAccessLabel("generate-plan")})`,
+      description: "Generate a development plan from a description"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Generate a development plan for what I am trying to build/fix.",
+              "",
+              `Access: ${promptAccessLabel("generate-plan")}${promptAccessLabel("generate-plan") === "PRO" ? ` (upgrade: ${upgradeUrl})` : ""}`,
+              "",
+              ...ID_NOTES,
+              "",
+              "Use the most recent user request as the plan description. If unclear, ask me for a one-paragraph description.",
+              "",
+              "Then call `ai_plan` and present the plan as an ordered list with milestones and risks."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "generate-tasks",
+    {
+      title: `Generate Tasks (${promptAccessLabel("generate-tasks")})`,
+      description: "Generate actionable tasks from a plan or description"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Generate actionable tasks for the work we are discussing.",
+              "",
+              `Access: ${promptAccessLabel("generate-tasks")}${promptAccessLabel("generate-tasks") === "PRO" ? ` (upgrade: ${upgradeUrl})` : ""}`,
+              "",
+              ...ID_NOTES,
+              "",
+              "If a plan_id exists in the conversation, use it. Otherwise use the latest user request as the description.",
+              "If granularity is not specified, default to medium.",
+              "",
+              "Call `ai_tasks` and return a checklist of tasks with acceptance criteria for each."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "token-budget-context",
+    {
+      title: `Token-Budget Context (${promptAccessLabel("token-budget-context")})`,
+      description: "Get the most relevant context that fits within a token budget"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Build the most relevant context that fits within a token budget.",
+              "",
+              `Access: ${promptAccessLabel("token-budget-context")}${promptAccessLabel("token-budget-context") === "PRO" ? ` (upgrade: ${upgradeUrl})` : ""}`,
+              "",
+              ...ID_NOTES,
+              "",
+              "First:",
+              "- If a query is clear from the conversation, use it; otherwise ask me for a query.",
+              "- If max_tokens is not specified, ask me for a token budget (e.g., 500/1000/2000).",
+              "",
+              "Then call `ai_context_budget` and return the packed context plus a short note about what was included/excluded."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "find-todos",
+    {
+      title: `Find TODOs (${promptAccessLabel("find-todos")})`,
+      description: "Scan the codebase for TODO/FIXME/HACK notes and summarize"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Scan the codebase for TODO/FIXME/HACK notes and summarize them.",
+              "",
+              ...ID_NOTES,
+              "",
+              "Use `search_pattern` with query `TODO|FIXME|HACK` (or a pattern inferred from the conversation).",
+              "Group results by file path, summarize themes, and propose a small prioritized cleanup list."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "generate-editor-rules",
+    {
+      title: `Generate Editor Rules (${promptAccessLabel("generate-editor-rules")})`,
+      description: "Generate ContextStream AI rule files for your editor"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Generate ContextStream AI rule files for my editor.",
+              "",
+              ...ID_NOTES,
+              "",
+              "First:",
+              "- If you can infer the project folder path from the environment/IDE roots, use it.",
+              "- Otherwise ask me for an absolute folder path.",
+              "- Ask which editor(s) (windsurf,cursor,cline,kilo,roo,claude,aider) or default to all.",
+              "",
+              "Then call `generate_editor_rules` and confirm which files were created/updated."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "index-local-repo",
+    {
+      title: `Index Local Repo (${promptAccessLabel("index-local-repo")})`,
+      description: "Ingest local files into ContextStream for indexing/search"
+    },
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Ingest local files into ContextStream for indexing/search.",
+              "",
+              ...ID_NOTES,
+              "",
+              "First:",
+              "- Ask me for the local directory path to ingest if it is not already specified.",
+              "",
+              "Then:",
+              "- Call `projects_ingest_local` with the path (use session defaults for project, or the `project_id` returned by `session_init`).",
+              "- Explain how to monitor progress via `projects_index_status`."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+}
+
 // src/session-manager.ts
 var SessionManager = class {
   constructor(server, client) {
@@ -11467,6 +12444,12 @@ var PORT = Number.parseInt(process.env.MCP_HTTP_PORT || "8787", 10);
 var MCP_PATH = process.env.MCP_HTTP_PATH || "/mcp";
 var REQUIRE_AUTH = (process.env.MCP_HTTP_REQUIRE_AUTH || "true").toLowerCase() !== "false";
 var ENABLE_JSON_RESPONSE = (process.env.MCP_HTTP_JSON_RESPONSE || "false").toLowerCase() === "true";
+var ENABLE_PROMPTS = (process.env.CONTEXTSTREAM_ENABLE_PROMPTS || "true").toLowerCase() !== "false";
+var WELL_KNOWN_CONFIG_PATH = "/.well-known/mcp-config";
+var WELL_KNOWN_CARD_PATHS = /* @__PURE__ */ new Set([
+  "/.well-known/mcp.json",
+  "/.well-known/mcp-server.json"
+]);
 var sessions = /* @__PURE__ */ new Map();
 function normalizeHeaderValue2(value) {
   if (!value) return void 0;
@@ -11514,6 +12497,105 @@ function attachAuthInfo(req, token, tokenType) {
     extra: { tokenType }
   };
 }
+function getBaseUrl(req) {
+  const host = req.headers.host || "localhost";
+  const forwardedProto = normalizeHeaderValue2(req.headers["x-forwarded-proto"]);
+  const proto = forwardedProto || "http";
+  return `${proto}://${host}`;
+}
+function buildMcpConfigSchema(baseUrl) {
+  return {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    $id: `${baseUrl}${WELL_KNOWN_CONFIG_PATH}`,
+    title: "ContextStream MCP Session Configuration",
+    description: "Configuration for connecting to the ContextStream MCP HTTP gateway.",
+    "x-query-style": "dot+bracket",
+    type: "object",
+    properties: {
+      apiKey: {
+        type: "string",
+        title: "API Key or JWT",
+        description: "ContextStream API key or JWT used for authentication."
+      },
+      workspaceId: {
+        type: "string",
+        title: "Workspace ID",
+        description: "Optional workspace ID to scope requests.",
+        format: "uuid"
+      },
+      projectId: {
+        type: "string",
+        title: "Project ID",
+        description: "Optional project ID to scope requests.",
+        format: "uuid"
+      }
+    },
+    required: ["apiKey"],
+    additionalProperties: false
+  };
+}
+function buildServerCard(baseUrl) {
+  const mcpUrl = `${baseUrl}${MCP_PATH}`;
+  return {
+    $schema: "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+    name: "io.github.contextstreamio/mcp-server",
+    title: "ContextStream MCP Server",
+    description: "ContextStream MCP server for code context, memory, search, and AI tools.",
+    version: VERSION,
+    websiteUrl: "https://contextstream.io/docs/mcp",
+    repository: {
+      url: "https://github.com/contextstream/mcp-server",
+      source: "github"
+    },
+    icons: [
+      {
+        src: "https://contextstream.io/favicon.svg",
+        mimeType: "image/svg+xml",
+        sizes: ["any"]
+      }
+    ],
+    remotes: [
+      {
+        type: "streamable-http",
+        url: mcpUrl,
+        headers: [
+          {
+            name: "Authorization",
+            value: "Bearer {apiKey}",
+            variables: {
+              apiKey: {
+                description: "ContextStream API key or JWT.",
+                isRequired: true,
+                isSecret: true,
+                placeholder: "cbiq_..."
+              }
+            }
+          },
+          {
+            name: "X-ContextStream-Workspace-Id",
+            value: "{workspaceId}",
+            variables: {
+              workspaceId: {
+                description: "Optional workspace ID.",
+                isRequired: false
+              }
+            }
+          },
+          {
+            name: "X-ContextStream-Project-Id",
+            value: "{projectId}",
+            variables: {
+              projectId: {
+                description: "Optional project ID.",
+                isRequired: false
+              }
+            }
+          }
+        ]
+      }
+    ]
+  };
+}
 async function createSession() {
   const config = loadConfig();
   const client = new ContextStreamClient(config);
@@ -11524,6 +12606,9 @@ async function createSession() {
   const sessionManager = new SessionManager(server, client);
   registerTools(server, client, sessionManager);
   registerResources(server, client, config.apiUrl);
+  if (ENABLE_PROMPTS) {
+    registerPrompts(server);
+  }
   const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator: () => randomUUID2(),
     enableJsonResponse: ENABLE_JSON_RESPONSE,
@@ -11595,6 +12680,14 @@ async function runHttpGateway() {
       writeJson(res, 200, { status: "ok", version: VERSION });
       return;
     }
+    if (url.pathname === WELL_KNOWN_CONFIG_PATH) {
+      writeJson(res, 200, buildMcpConfigSchema(getBaseUrl(req)));
+      return;
+    }
+    if (WELL_KNOWN_CARD_PATHS.has(url.pathname)) {
+      writeJson(res, 200, buildServerCard(getBaseUrl(req)));
+      return;
+    }
     if (url.pathname !== MCP_PATH) {
       writeJson(res, 404, { error: "Not found" });
       return;
@@ -12650,6 +13743,7 @@ Applying to ${projects.length} project(s)...`);
 }
 
 // src/index.ts
+var ENABLE_PROMPTS2 = (process.env.CONTEXTSTREAM_ENABLE_PROMPTS || "true").toLowerCase() !== "false";
 function showFirstRunMessage() {
   const configDir = join8(homedir4(), ".contextstream");
   const starShownFile = join8(configDir, ".star-shown");
@@ -12699,6 +13793,7 @@ Environment variables:
   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
+  CONTEXTSTREAM_ENABLE_PROMPTS Enable MCP prompts list (default: true)
   MCP_HTTP_HOST          HTTP gateway host (default: 0.0.0.0)
   MCP_HTTP_PORT          HTTP gateway port (default: 8787)
   MCP_HTTP_PATH          HTTP gateway path (default: /mcp)
@@ -12748,6 +13843,9 @@ async function main() {
   const sessionManager = new SessionManager(server, client);
   registerTools(server, client, sessionManager);
   registerResources(server, client, config.apiUrl);
+  if (ENABLE_PROMPTS2) {
+    registerPrompts(server);
+  }
   console.error(`ContextStream MCP server v${VERSION} starting...`);
   console.error(`API URL: ${config.apiUrl}`);
   console.error(`Auth: ${config.apiKey ? "API Key" : config.jwt ? "JWT" : "None"}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@contextstream/mcp-server",
   "mcpName": "io.github.contextstreamio/mcp-server",
-  "version": "0.3.63",
+  "version": "0.3.64",
   "description": "MCP server exposing ContextStream public API - code context, memory, search, and AI tools for developers",
   "type": "module",
   "license": "MIT",