@contextstream/mcp-server 0.4.81 → 1.0.0

package/NOTICE

@@ -0,0 +1,25 @@
+ContextStream MCP Server
+Copyright (c) 2025-2026 ContextStream
+
+This product is developed and maintained by ContextStream as part of the
+ContextStream platform (https://contextstream.io).
+
+ContextStream is an independently developed cloud service providing persistent
+memory and cross-session context management for AI coding assistants. The
+platform includes proprietary backend services not included in this repository.
+
+This MCP server is a client library that connects to the ContextStream API.
+It requires a ContextStream account and API key to function.
+
+TRADEMARKS
+
+"ContextStream" and the ContextStream logo are trademarks of ContextStream.
+Use of these trademarks requires prior written permission.
+
+THIRD-PARTY LICENSES
+
+This software uses open-source Rust crates recorded in Cargo.lock. The npm
+compatibility launcher has no runtime package dependencies. Release SBOMs and
+license reports provide the exact dependency inventory for each release.
+
+For questions about licensing or trademark usage, contact: legal@contextstream.io

package/README.md

@@ -1,377 +1,126 @@
-<p align="center">
-  <img src="https://contextstream.io/400logo.png" alt="ContextStream — persistent memory and semantic code search for AI coding assistants" width="80" />
-</p>
+<!-- mcp-name: io.github.contextstream/mcp-server -->
 
-<h1 align="center">ContextStream MCP Server</h1>
+# ContextStream MCP Server
 
-<p align="center">
-  <strong>Persistent memory, semantic code search, and team context for Claude Code, Cursor, VS Code Copilot, Windsurf — and every MCP-compatible AI coding assistant.</strong>
-</p>
+This repository is the canonical open-source implementation and release source
+for the ContextStream Rust MCP server. It provides project memory, semantic code
+search, dependency analysis, grounded context, and editor setup over the Model
+Context Protocol.
 
-<p align="center">
-  🏆 <b>90.0% on LongMemEval-S</b> — the full 500-instance suite with the official judge.<br/>
-  Beats supermemory with statistical significance; matches Zep. <a href="https://contextstream.io/benchmarks">See the benchmarks →</a>
-</p>
+The hosted service at `https://mcp.contextstream.io/mcp` is the recommended
+transport. The npm package is a compatibility launcher for clients that require
+stdio: it downloads the binary for the package's exact version from an immutable
+release path, verifies SHA-256, and runs it from a versioned cache.
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/@contextstream/mcp-server"><img src="https://img.shields.io/npm/v/@contextstream/mcp-server.svg" alt="npm version" /></a>
-  <a href="https://www.npmjs.com/package/@contextstream/mcp-server"><img src="https://img.shields.io/npm/dm/@contextstream/mcp-server.svg" alt="npm downloads" /></a>
-  <a href="https://github.com/contextstream/mcp-server/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@contextstream/mcp-server.svg" alt="MIT license" /></a>
-  <img src="https://img.shields.io/node/v/@contextstream/mcp-server.svg" alt="node version" />
-</p>
+## Connect
 
-<p align="center">
-  <a href="https://contextstream.io/docs">Documentation</a> •
-  <a href="https://contextstream.io/pricing">Pricing</a> •
-  <a href="#faq">FAQ</a>
-</p>
-
----
-
-## Try it in 30 seconds
-
-```bash
-npx --prefer-online -y @contextstream/mcp-server@latest setup
-```
-
-That one command detects your AI editors, writes their MCP configs and rules, installs lifecycle hooks where supported, indexes your project in the background, and **verifies everything it just did** — then you restart your editor and your AI has memory. Free tier available.
-
-Automating it? Zero-prompt mode takes every default:
-
-```bash
-npx --prefer-online -y @contextstream/mcp-server@latest setup --yes
-```
-
-<p align="center">
-  <img src="compare1.gif" alt="Side-by-side comparison: an AI coding assistant with ContextStream memory and semantic search vs. without" width="700" />
-</p>
-
----
-
-## We win on memory benchmarks — measured honestly
-
-**ContextStream scores 90.0% on the full LongMemEval-S benchmark**, the standard test of conversational memory over ~115k-token multi-session histories. That's the complete 500-instance suite with the official GPT-4o judge — 450/500 correct (89.6% single-shot, 90.0% with self-consistency k=3; Wilson 95% CI [87.1%, 92.3%]). Published June 14, 2026.
-
-| System | LongMemEval-S | Notes |
-|---|:---:|---|
-| **ContextStream** | **90.0%** | Full 500 instances, official GPT-4o judge |
-| Zep | 90.2% | Vendor-published — a statistical tie (0.2 pt is inside measurement noise) |
-| supermemory | 85.4% | Vendor-published — ContextStream wins with statistical significance |
-
-On **multi-session recall** — the memory that actually matters for a coding agent working across days of sessions — ContextStream scores **81.2% vs Zep's published 57.9%** in the per-family comparison. And on the agentic project-memory benchmark, the same memory raises **agent task success from 58% to 96%**.
-
-Full methodology, per-family breakdowns, and judge-comparability notes (competitor numbers are cited from each vendor's own publications): **[contextstream.io/benchmarks](https://contextstream.io/benchmarks)**
-
----
-
-## What is ContextStream?
-
-**ContextStream is a Model Context Protocol (MCP) server that gives AI coding assistants long-term memory and deep codebase understanding.** It indexes your code for semantic search, records your decisions, lessons, and plans across sessions, maps your dependency graph, and pulls in team knowledge from GitHub, Slack, and Notion — then delivers exactly the right slice of all that to your AI on every message.
-
-It works with any MCP client: Claude Code, Cursor, VS Code + GitHub Copilot, Windsurf, Cline, Roo Code, Kilo Code, Codex CLI, OpenCode, Aider, Antigravity, and Claude Desktop.
-
----
-
-## Why do AI coding assistants forget everything?
-
-Because every conversation starts from zero. Your AI re-reads the same files, re-derives the same architecture, repeats last week's mistake, and loses the thread the moment the context window compacts. ContextStream fixes the whole class of problem:
-
-| Without ContextStream | With ContextStream |
-|--------|-------|
-| AI greps files one-by-one, burning tokens | **Semantic code search** finds code by meaning in milliseconds |
-| Context lost when conversations get long | **Pre-compaction capture** saves critical state before it's gone — and restores it after |
-| Same mistakes repeated across sessions | **Lessons system** surfaces past failures *before* your AI repeats them |
-| "Why did we choose X?" — nobody remembers | **Decisions and plans** persist and resurface when relevant |
-| Team knowledge scattered across tools | **GitHub, Slack, and Notion knowledge**, queried automatically |
-| Generic answers with no project awareness | **Workspace context** on every single message |
-
----
-
-## What your AI can do after setup
-
-### 🔍 Find code by meaning, not keywords
-Ask *"where do we handle authentication?"* and get ranked, snippet-level answers instantly. Hybrid semantic + keyword search with exact-token fusion, so a symbol lookup like `resolveWriteScope` lands the definition — not lookalikes. Search works the moment setup finishes: keyword results come back immediately while the semantic index builds in the background.
-
-### 🧠 Remember everything that matters
-Decisions, lessons, preferences, plans, tasks, docs, runbooks — captured during work and surfaced automatically on later turns, in later sessions, even after context compaction. Every prior session's transcript is indexed and queryable: *"what did we decide about the id format last week?"* just works.
-
-### 💬 Ask the workspace when stuck
-The built-in **Agent Q&A** tool lets your AI ask your workspace's knowledge base — prior decisions, conventions, runbooks, guardrails — and get a grounded answer with citations for every claim.
-
-### 🕸️ See the whole graph
-*"What depends on `UserService`?" "What breaks if I change this function?"* Dependency mapping, impact analysis, circular-dependency and dead-code detection over your whole codebase.
-
-### 📦 Hand off context between agents
-**ContextCapsule** packages project state into a portable, shareable snapshot — bootstrap a fresh agent, hand off to a teammate, or share a token-gated link with an external agent.
-
-### 🛡️ Survive long sessions
-Token pressure is tracked continuously (with thresholds sized to your model's context window). Before compaction hits, critical state is checkpointed; after it, context restores.
-
----
-
-## Which AI editors and agents does it support?
-
-| Editor / Agent | Managed rules | MCP config | Lifecycle hooks |
-|---|:---:|:---:|:---:|
-| Claude Code | ✅ | ✅ | ✅ |
-| Cursor | ✅ (`.cursor/rules/*.mdc`) | ✅ | ✅ |
-| Windsurf | ✅ | ✅ | ✅ |
-| Cline | ✅ | ✅ | ✅ |
-| Roo Code | ✅ | ✅ | ✅ |
-| Kilo Code | ✅ | ✅ | rules-based |
-| VS Code + GitHub Copilot | ✅ | ✅ (incl. hosted OAuth) | rules-based |
-| Codex CLI | ✅ | ✅ | rules-based |
-| OpenCode | ✅ | ✅ | rules-based |
-| Aider | ✅ | ✅ | rules-based |
-| Antigravity | ✅ | ✅ | rules-based |
-| Claude Desktop | — | ✅ | — |
-
-Anything that speaks the Model Context Protocol can connect — the table just shows what the setup wizard configures automatically.
-
----
-
-## The tools your AI gets
-
-36 tools in the default surface, organized as consolidated domains so they cost ~75% fewer tokens than individual registrations:
-
-```
-init / context   → workspace state + the right context on every message
-search           → semantic, hybrid, keyword, pattern, exhaustive, refactor modes
-memory           → events, decisions, docs, runbooks, tasks, todos, diagrams, transcripts
-session          → capture decisions & lessons, recall past sessions, plans, retroactive capture
-qa               → grounded Q&A over your workspace knowledge base, with citations
-graph            → dependencies, impact analysis, circular deps, unused code
-capsule          → portable, shareable context snapshots for agent handoffs
-entity           → tickets, incidents, releases, sprints, OKRs, risks
-project / workspace / skill / media / vcs / reminder / integration / help
-```
-
-Plus focused write tools (`capture_plan`, `memory_create_doc`, …) so agents that display tool names show *what* they're doing. Your AI uses all of this automatically — you just code.
-
----
-
-## CLI commands
-
-```bash
-contextstream-mcp setup            # interactive onboarding wizard
-contextstream-mcp setup --yes      # zero-prompt setup with sane defaults (great for CI/dotfiles)
-contextstream-mcp doctor           # ✓/✗ diagnostics: auth, scope, index health, rules, hooks
-contextstream-mcp index [path]     # index a project folder on demand
-```
-
-`setup --editors=claude,cursor` limits configuration to specific editors; `doctor` tells you exactly what's misconfigured and how to fix it — it runs automatically at the end of every setup.
-
----
-
-## Manual configuration
-
-> Skip this if you ran the setup wizard.
-
-<details>
-<summary><b>Claude Code</b></summary>
-
-```bash
-claude mcp add contextstream -- npx --prefer-online -y @contextstream/mcp-server@latest
-claude mcp update contextstream -e CONTEXTSTREAM_API_URL=https://api.contextstream.io -e CONTEXTSTREAM_API_KEY=your_key
-```
-
-</details>
-
-<details>
-<summary><b>Cursor / Claude Desktop</b></summary>
+Streamable HTTP (recommended):
 
 ```json
 {
   "mcpServers": {
-    "contextstream": {
-      "command": "npx",
-      "args": ["--prefer-online", "-y", "@contextstream/mcp-server@latest"],
-      "env": {
-        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
-        "CONTEXTSTREAM_API_KEY": "your_key"
-      }
-    }
-  }
-}
-```
-
-**Locations:** `~/.cursor/mcp.json` • `~/Library/Application Support/Claude/claude_desktop_config.json`
-
-</details>
-
-<details>
-<summary><b>OpenCode</b></summary>
-
-Local server:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "contextstream": {
-      "type": "local",
-      "command": ["npx", "-y", "contextstream-mcp"],
-      "environment": {
-        "CONTEXTSTREAM_API_KEY": "{env:CONTEXTSTREAM_API_KEY}"
-      },
-      "enabled": true
-    }
-  }
-}
-```
-
-Remote server:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "contextstream": {
-      "type": "remote",
-      "url": "https://mcp.contextstream.com",
-      "enabled": true
-    }
-  }
-}
-```
-
-For the local variant, export `CONTEXTSTREAM_API_KEY` before launching OpenCode.
-
-**Locations:** `./opencode.json` • `~/.config/opencode/opencode.json`
-
-</details>
-
-<details>
-<summary><b>VS Code + GitHub Copilot</b></summary>
-
-The easiest path is the hosted remote MCP with built-in OAuth — no API key in the config file:
-
-```json
-{
-  "servers": {
     "contextstream": {
       "type": "http",
-      "url": "https://mcp.contextstream.io/mcp?default_context_mode=fast"
+      "url": "https://mcp.contextstream.io/mcp"
     }
   }
 }
 ```
 
-`setup` defaults VS Code/Copilot to this hosted remote on the production cloud. To force a local runtime, run setup with `CONTEXTSTREAM_VSCODE_MCP_MODE=local`, or use stdio directly:
-
-```json
-{
-  "servers": {
-    "contextstream": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["--prefer-online", "-y", "@contextstream/mcp-server@latest"],
-      "env": {
-        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
-        "CONTEXTSTREAM_API_KEY": "your_key",
-        "CONTEXTSTREAM_TOOLSET": "complete"
-      }
-    }
-  }
-}
-```
-
-Keep both `~/.copilot/mcp-config.json` (uses `mcpServers`) and `.vscode/mcp.json` (uses `servers`) in sync — setup writes both.
-
-</details>
-
-<details>
-<summary><b>GitHub Copilot CLI</b></summary>
-
-Use `/mcp add` interactively, or add to `~/.copilot/mcp-config.json`:
+npm/stdin compatibility:
 
 ```json
 {
   "mcpServers": {
     "contextstream": {
       "command": "npx",
-      "args": ["--prefer-online", "-y", "@contextstream/mcp-server@latest"],
+      "args": ["-y", "@contextstream/mcp-server@1.0.0"],
       "env": {
-        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
-        "CONTEXTSTREAM_API_KEY": "your_key",
-        "CONTEXTSTREAM_TOOLSET": "complete"
+        "CONTEXTSTREAM_API_KEY": "your-api-key"
       }
     }
   }
 }
 ```
 
-See the [GitHub Copilot CLI documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli) for details.
-
-</details>
+All 1.x releases preserve these npm executables:
 
-<details>
-<summary><b>Unmapped folders (global fallback workspace)</b></summary>
+- `mcp-server`
+- `contextstream-mcp`
+- `contextstream-hook` (forwards to the Rust `hook` subcommand)
 
-Folders that aren't associated with any project (your home directory, ad-hoc scratch dirs) still work: `init` falls back to a hidden catch-all workspace in workspace-only mode, memory/session/context tools keep functioning, and project-bound actions return guided remediation instead of raw errors. The moment you enter a mapped project folder, the real workspace/project takes over.
+Run the setup wizard with:
 
-</details>
-
----
-
-## FAQ
-
-### What is an MCP server?
-
-An MCP (Model Context Protocol) server exposes tools and context to AI assistants over a standard protocol. Claude Code, Cursor, VS Code Copilot, Windsurf, and most modern AI coding tools are MCP clients — install one server, and every client you use gets the same capabilities.
-
-### Does ContextStream work with Claude Code / Cursor / Copilot / Windsurf?
-
-Yes — all of them, plus Cline, Roo Code, Kilo Code, Codex CLI, OpenCode, Aider, Antigravity, and Claude Desktop. The setup wizard configures each editor's MCP config, managed rules, and (where the editor supports them) lifecycle hooks automatically.
-
-### Is my code private?
-
-Your code is private and securely stored, isolated per workspace with no cross-tenant access. You control exclusions with `.contextstream/ignore` (gitignore syntax), and `project(action="purge")` completely de-indexes a project on demand — without touching your captured memory.
-
-### How much does it cost?
-
-There's a free tier to start with. Larger indexes, the full code graph, and team features are on paid plans: see [pricing](https://contextstream.io/pricing).
-
-### How does ContextStream score on memory benchmarks?
+```bash
+npx -y @contextstream/mcp-server@1.0.0 setup
+```
 
-90.0% on the full 500-instance LongMemEval-S suite with the official GPT-4o judge (89.6% single-shot) — beating supermemory's published 85.4% with statistical significance and matching Zep's published 90.2% within the confidence interval. On multi-session recall specifically, ContextStream scores 81.2% vs Zep's published 57.9%. Methodology and per-family breakdowns: [contextstream.io/benchmarks](https://contextstream.io/benchmarks).
+## What setup sends
 
-### How is this different from other AI memory tools?
+Setup prints this disclosure before changing editor configuration:
 
-Most tools store notes. ContextStream combines **memory** (decisions, lessons, plans, session transcripts), **semantic code search** over your indexed codebase, a **dependency/knowledge graph**, **grounded Q&A with citations**, and **team integrations** (GitHub, Slack, Notion) behind one MCP server — and proactively delivers the relevant slice on every message instead of waiting to be asked.
+- Transcript exchange saving and hook transcript saving are enabled by default.
+- A validated project can be indexed; matching source files are sent to the
+  user's ContextStream workspace.
+- Selected supported editors receive managed lifecycle hooks.
+- Local Git capture is enabled by default. It sends event type, commit SHA/time,
+  branch/ref names, aggregate line/file counts, a bounded redacted commit
+  subject, an opaque checkout ID, and a credential-free canonical remote.
+- Absolute filesystem paths, commit bodies, and commit author name/email are not
+  sent by the VCS hook pipeline.
 
-### Can I use it in CI or scripted environments?
+Controls and deletion paths are documented in
+[`docs/data-handling.md`](docs/data-handling.md). These defaults are preserved
+for compatibility; review them before running `setup --yes` in automation.
 
-Yes: `setup --yes` runs the entire wizard with zero prompts (set `CONTEXTSTREAM_API_KEY` in the environment), `--editors=<list>` scopes it, and `contextstream-mcp doctor` gives scriptable ✓/✗ diagnostics.
+## Build
 
-### Do I have to wait for indexing?
+The workspace requires the Rust toolchain pinned in `rust-toolchain.toml`.
 
-No. Project indexing runs in the background — keyword search works immediately, and semantic results fill in as the index builds. Check progress anytime with `contextstream-mcp doctor`.
+```bash
+cargo build --locked -p mcp-server --bin contextstream-mcp
+cargo test --locked --workspace
+cargo build --locked --release -p mcp-server --bin contextstream-mcp \
+  --features remote-acceleration
+```
 
-### How do I uninstall or disable it?
+The public workspace contains seven crates:
 
-Remove the `contextstream` entry from your editor's MCP config, and set `CONTEXTSTREAM_HOOK_ENABLED=false` (or re-run setup) to disable hooks. `project(action="forget_local")` unbinds a folder locally without touching server-side data.
+- `mcp-server`
+- `mcp-tools`
+- `mcp-client`
+- `mcp-session`
+- `mcp-types`
+- `mcp-model-registry`
+- `mcp-acceleration-products`
 
----
+`mcp-acceleration-products` is MongoDB-free. Premium provider implementation,
+production deployment configuration, credentials, and private operator material
+are not part of this repository. Compatibility traits remain no-op in public
+builds so the core protocol surface stays stable.
 
-## Troubleshooting
+## npm launcher behavior
 
-- **Start with `contextstream-mcp doctor`** — it checks auth, API reachability, folder scope, index health, rule files, and hooks, with a fix hint per failure.
-- Remove duplicate ContextStream entries across Workspace/User config scopes.
-- Check `CONTEXTSTREAM_API_URL` and `CONTEXTSTREAM_API_KEY` are set; remove stale version pins like `@contextstream/mcp-server@0.3.xx`.
-- Restart your editor after config changes.
-- **Hosted HTTP OAuth:** the remote transport's OAuth flow routes through `vscode.dev`; where that's blocked (corporate networks), use stdio with an API key instead.
-- **SDK compatibility:** `@modelcontextprotocol/sdk` 1.28.0+ introduces breaking changes; this package pins `>=1.25.1 <1.28.0`. If you see Zod schema errors on startup, check your SDK resolution.
+The dependency-free Node 20 launcher:
 
----
+- selects the package-version/platform artifact;
+- downloads only from `mcp/v<exact-version>/`;
+- verifies `version.json`, `checksums.txt`, and the binary SHA-256;
+- populates the cache under an atomic lock and re-verifies cached bytes;
+- supports `CONTEXTSTREAM_MCP_OFFLINE=1` after a verified first run;
+- executes the cached binary by absolute path, ignoring PATH-shadowing copies;
+- sets `CONTEXTSTREAM_DISABLE_SELF_UPDATE=1`, so the Rust process cannot mutate
+  npm-managed cache state.
 
-## Links
+For test mirrors only, the launcher recognizes
+`CONTEXTSTREAM_MCP_RELEASE_BASE_URL` together with
+`CONTEXTSTREAM_MCP_TEST_ALLOW_HTTP=1`. Production release URLs must use HTTPS.
 
-**Website:** https://contextstream.io • **Docs:** https://contextstream.io/docs • **Changelog:** [CHANGELOG.md](CHANGELOG.md)
+## Contributing and security
 
----
+See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and
+[GOVERNANCE.md](GOVERNANCE.md). By contributing, you certify the Developer
+Certificate of Origin for your commits (`git commit -s`).
 
-<p align="center">
-  <strong>Stop teaching your AI the same things over and over.</strong><br/>
-  <sub>ContextStream makes it brilliant from the first message.</sub>
-</p>
+The code in this repository is MIT licensed. ContextStream trademarks and the
+hosted backend are addressed in [NOTICE](NOTICE).

package/npm/bin/contextstream-hook.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from "../launcher.mjs";
+
+try {
+  await run({ mode: "hook" });
+} catch (error) {
+  console.error(`ContextStream launcher: ${error?.message ?? error}`);
+  process.exitCode = 1;
+}

package/npm/bin/contextstream-mcp.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from "../launcher.mjs";
+
+try {
+  await run({ mode: "server" });
+} catch (error) {
+  console.error(`ContextStream launcher: ${error?.message ?? error}`);
+  process.exitCode = 1;
+}

package/npm/bin/mcp-server.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from "../launcher.mjs";
+
+try {
+  await run({ mode: "server" });
+} catch (error) {
+  console.error(`ContextStream launcher: ${error?.message ?? error}`);
+  process.exitCode = 1;
+}