@contextstream/mcp-server 0.3.11 → 0.3.12

package/README.md

@@ -2,41 +2,46 @@
 
 [![npm version](https://badge.fury.io/js/@contextstream%2Fmcp-server.svg)](https://www.npmjs.com/package/@contextstream/mcp-server)
 
-A powerful Model Context Protocol (MCP) server that provides persistent memory, code context, knowledge graphs, and AI tools. Connect your AI assistant to your codebase's semantic search, memory system, and dependency analysis.
+## 🧠 Your AI's Permanent Brain — Across Every Tool, Every Conversation
+
+**Tired of re-explaining your codebase to AI every single time?**
+
+ContextStream gives your AI persistent memory that follows you everywhere. Decisions remembered. Context preserved. No more repeating yourself.
 
 **Website:** [contextstream.io](https://contextstream.io) | **Docs:** [contextstream.io/docs/mcp](https://contextstream.io/docs/mcp)
 
-## Features
+---
 
-### 🔍 Code Search & Context
-- **Semantic search** — Find code by meaning, not just keywords
-- **Hybrid search** — Combines semantic + keyword for best results
-- **Pattern search** — Regex-based code search
-- **AI context building** — Automatically gather relevant code, docs, and memory
+## ✨ Why ContextStream?
 
-### 🧠 Memory & Knowledge
-- **Memory events** — Store decisions, insights, and context
-- **Knowledge nodes** — Build a graph of connected concepts
-- **Decision tracking** — Never lose architectural decisions
-- **Memory search** — Find relevant past context
+### The Problem
+- Close a chat with Cursor → Open a new one → AI forgot everything
+- Switch from Claude to Windsurf → Start explaining from scratch
+- New team member joins → Days of onboarding conversations
+- "Why did we build it this way?" → No one remembers
 
-### 📊 Code Intelligence
-- **Dependency analysis** — Understand what depends on what
-- **Call path tracing** — Trace execution flows
-- **Impact analysis** — Understand change impact
-- **Circular dependency detection** — Find problematic cycles
-- **Unused code detection** — Identify dead code
+### The Solution
+ContextStream is a **universal memory layer** for AI coding tools. It works with **Cursor, Claude Code, Windsurf, VS Code**, and any MCP-compatible client.
 
-### 🤖 AI Integration
-- **Context building** — Build LLM-ready context from your codebase
-- **Enhanced context** — Deep analysis with memory integration
-- **Plan generation** — AI-powered development planning
-- **Task generation** — Break down work into actionable tasks
+```
+You: "Initialize session and remember we use PostgreSQL with TypeScript strict mode"
+...later, in a NEW conversation...
+You: "What are my preferences for this project?"
+AI: "You prefer TypeScript with strict mode, and you're using PostgreSQL."
+```
+
+**It remembers. Across sessions. Across tools. Forever.**
+
+---
+
+## 🚀 2-Minute Setup
 
-## Installation
+### 1. Get your API key (30 seconds)
+Sign up at [contextstream.io](https://contextstream.io) → Settings → API Keys → Create one.
 
-Add ContextStream to your AI tool's MCP configuration (works with **Cursor**, **VS Code**, **Claude Code**, **Windsurf**, and any MCP-compatible client):
+### 2. Add to your MCP config (60 seconds)
 
+**Cursor / Claude Code / Windsurf / VS Code:**
 ```json
 {
   "mcpServers": {
@@ -52,12 +57,7 @@ Add ContextStream to your AI tool's MCP configuration (works with **Cursor**, **
 }
 ```
 
-Get your API key at [contextstream.io](https://contextstream.io)
-
-### Codex (CLI) configuration
-
-For the Codex CLI, add the MCP server to your `~/.codex/config.toml`:
-
+**Codex CLI:** Add to `~/.codex/config.toml`:
 ```toml
 [mcpServers.contextstream]
 command = "npx"
@@ -68,11 +68,98 @@ CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
 CONTEXTSTREAM_API_KEY = "your_api_key"
 ```
 
-After saving the file, restart Codex. The ContextStream tools and auto-context will then be available in any trusted project that has a `.contextstream/config.json` (or a matching parent mapping in `~/.contextstream-mappings.json`).
+### 3. Try it out (30 seconds)
+Start a chat and say:
+> "Initialize session and remember that I prefer TypeScript with strict mode"
+
+Then start a **brand new conversation** and ask:
+> "What are my preferences?"
+
+✨ **It remembers.**
+
+---
+
+## 🔥 Beyond Memory — That's Just the Beginning
+
+ContextStream isn't just memory storage. It understands your code.
+
+### Impact Analysis
+```
+"What breaks if I change the UserService class?"
+```
+See all dependencies and side effects before refactoring.
+
+### Decision History
+```
+"Why did we choose PostgreSQL over MongoDB?"
+```
+Recall past decisions with full context and reasoning.
+
+### Semantic Code Search
+```
+"Find where we handle rate limiting"
+```
+Search by meaning, not just keywords. Find code by intent.
+
+### Knowledge Graph
+```
+"Show dependencies for the auth module"
+```
+Visualize connections between code, decisions, and docs.
+
+---
+
+## 📊 60+ MCP Tools at Your Fingertips
+
+### 🔍 Code Search & Context
+| Tool | Description |
+|------|-------------|
+| `search_semantic` | Find code by meaning, not just keywords |
+| `search_hybrid` | Combines semantic + keyword for best results |
+| `search_pattern` | Regex-based code search |
+| `ai_context` | Automatically gather relevant code, docs, and memory |
+
+### 🧠 Memory & Knowledge
+| Tool | Description |
+|------|-------------|
+| `session_remember` | Quick natural language memory ("Remember I prefer TypeScript") |
+| `session_recall` | Quick recall ("What were the auth decisions?") |
+| `memory_create_event` | Store decisions, insights, and context |
+| `memory_search` | Find relevant past context |
+| `memory_decisions` | Get decision summaries |
+
+### 📊 Code Intelligence
+| Tool | Description |
+|------|-------------|
+| `graph_dependencies` | Understand what depends on what |
+| `graph_call_path` | Trace execution flows |
+| `graph_impact` | Understand change impact |
+| `graph_circular_dependencies` | Find problematic cycles |
+| `graph_unused_code` | Identify dead code |
+
+### 🤖 AI Integration
+| Tool | Description |
+|------|-------------|
+| `ai_context` | Build LLM-ready context from your codebase |
+| `ai_enhanced_context` | Deep analysis with memory integration |
+| `ai_plan` | AI-powered development planning |
+| `ai_tasks` | Break down work into actionable tasks |
+
+### 🚀 Session Management
+| Tool | Description |
+|------|-------------|
+| `session_init` | Initialize conversation with auto-context |
+| `context_smart` | Get relevant context for any message |
+| `session_capture` | Store context to memory |
+| `session_compress` | Compress chat history to memory |
+
+[See all 60+ tools →](https://contextstream.io/docs/mcp)
+
+---
 
 ## ✨ Auto-Context (v0.3.0+)
 
-Context loads **automatically** on the first tool call of any conversation. No need to manually call `session_init` — your AI assistant gets workspace info, recent memory, and decisions immediately.
+Context loads **automatically** on the first tool call. No manual setup required.
 
 ```
 ═══════════════════════════════════════════
@@ -93,21 +180,45 @@ Context loads **automatically** on the first tool call of any conversation. No n
 
 Works with **all MCP clients** — no client-side changes required.
 
-## Environment Variables
+---
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `CONTEXTSTREAM_API_URL` | Yes | API base URL (`https://api.contextstream.io`) |
-| `CONTEXTSTREAM_API_KEY` | Yes | Your API key from contextstream.io |
+## 🛡️ Privacy & Security
+
+- **Encrypted at rest** — All data encrypted with AES-256
+- **No training on your data** — We never use your code to train AI
+- **You control access** — Workspace permissions & API keys
+- **Self-host option** — Enterprise can self-host for full control
+
+---
 
-## Available Tools
+## 🏆 Why Not Built-in Memory?
+
+| Built-in memory | ContextStream |
+|-----------------|---------------|
+| ✗ Vendor lock-in — switch tools, lose everything | ✓ **Universal** — Cursor, Claude, Windsurf, any MCP tool |
+| ✗ Expires or resets over time | ✓ **Persistent forever** — never lose context (paid plans) |
+| ✗ No semantic search | ✓ **Semantic search** — find anything across all history |
+| ✗ Personal only — teammates start from zero | ✓ **Team memory** — shared context, instant onboarding |
+| ✗ No API access | ✓ **60+ MCP tools** — full API and automation |
+| ✗ Memory isolated from code | ✓ **Knowledge graph** — decisions linked to code |
+| ✗ Clunky to use | ✓ **Natural language** — "remember X", "what did we decide about Y?" |
+
+---
+
+## 📖 Full Tool Reference
+
+<details>
+<summary><strong>Authentication</strong></summary>
 
-### Authentication
 | Tool | Description |
 |------|-------------|
 | `auth_me` | Get current user profile |
 
-### Workspaces
+</details>
+
+<details>
+<summary><strong>Workspaces</strong></summary>
+
 | Tool | Description |
 |------|-------------|
 | `workspaces_list` | List accessible workspaces |
@@ -117,7 +228,11 @@ Works with **all MCP clients** — no client-side changes required.
 | `workspaces_analytics` | Get usage analytics |
 | `workspaces_content` | List workspace content |
 
-### Projects
+</details>
+
+<details>
+<summary><strong>Projects</strong></summary>
+
 | Tool | Description |
 |------|-------------|
 | `projects_list` | List projects (by workspace) |
@@ -129,7 +244,11 @@ Works with **all MCP clients** — no client-side changes required.
 | `projects_index` | Trigger re-indexing |
 | `projects_index_status` | Check indexing status |
 
-### Search
+</details>
+
+<details>
+<summary><strong>Search</strong></summary>
+
 | Tool | Description |
 |------|-------------|
 | `search_semantic` | Semantic vector search |
@@ -138,7 +257,11 @@ Works with **all MCP clients** — no client-side changes required.
 | `search_pattern` | Regex pattern search |
 | `search_suggestions` | Get search suggestions |
 
-### Memory
+</details>
+
+<details>
+<summary><strong>Memory</strong></summary>
+
 | Tool | Description |
 |------|-------------|
 | `memory_create_event` | Store a memory event |
@@ -159,7 +282,11 @@ Works with **all MCP clients** — no client-side changes required.
 | `memory_timeline` | Get chronological timeline |
 | `memory_summary` | Get condensed summary |
 
-### Graph Analysis
+</details>
+
+<details>
+<summary><strong>Graph Analysis</strong></summary>
+
 | Tool | Description |
 |------|-------------|
 | `graph_related` | Find related knowledge nodes |
@@ -172,7 +299,11 @@ Works with **all MCP clients** — no client-side changes required.
 | `graph_unused_code` | Find dead code |
 | `graph_contradictions` | Find conflicting info |
 
-### AI
+</details>
+
+<details>
+<summary><strong>AI</strong></summary>
+
 | Tool | Description |
 |------|-------------|
 | `ai_context` | Build LLM context |
@@ -181,32 +312,29 @@ Works with **all MCP clients** — no client-side changes required.
 | `ai_plan` | Generate dev plan |
 | `ai_tasks` | Generate tasks |
 
-### Session & Auto-Context (CORE-like)
-These tools enable automatic context initialization for AI assistants:
+</details>
+
+<details>
+<summary><strong>Session & Auto-Context</strong></summary>
 
 | Tool | Description |
 |------|-------------|
-| `session_init` | **Initialize conversation** - First tool to call, returns workspace/project info, recent memory, decisions |
-| `session_get_user_context` | Get user preferences and coding style from memory |
-| `session_capture` | Store context (decisions, insights, preferences) to memory |
-| `session_smart_search` | Search with automatic context enrichment (memory + code + decisions) |
-| `session_remember` | Quick natural language memory storage ("Remember I prefer TypeScript strict mode") |
-| `session_recall` | Quick natural language recall ("What were the auth decisions?") |
-
-**Usage in AI Tools:**
-```
-# In Cursor/Claude Code/Windsurf - start with:
-"Initialize session for this workspace"
+| `session_init` | Initialize conversation |
+| `session_get_user_context` | Get user preferences |
+| `session_capture` | Store context to memory |
+| `session_smart_search` | Search with context enrichment |
+| `session_remember` | Quick natural language memory |
+| `session_recall` | Quick natural language recall |
+| `context_smart` | Get relevant context for message |
+| `session_compress` | Compress chat history to memory |
+| `session_summary` | Get compact workspace summary |
+| `session_delta` | Get changes since timestamp |
 
-# Then use natural commands:
-"Remember we decided to use PostgreSQL for the database"
-"Recall the authentication decisions we made"
-"What are my coding preferences?"
-```
+</details>
 
-## Prompts
+---
 
-Pre-built prompts for common workflows:
+## 🔌 Pre-built Prompts
 
 | Prompt | Description |
 |--------|-------------|
@@ -219,35 +347,26 @@ Pre-built prompts for common workflows:
 | `analyze-refactoring` | Find refactoring opportunities |
 | `build-context` | Build comprehensive LLM context |
 
-## Resources
-
-| Resource | Description |
-|----------|-------------|
-| `contextstream:openapi` | OpenAPI specification |
-| `contextstream:workspaces` | Workspace listing |
-| `contextstream:projects/{id}` | Projects for workspace |
-
-## Error Handling
+---
 
-The client includes:
-- **Automatic retries** for transient failures (429, 500, 502, 503, 504)
-- **Exponential backoff** with configurable delays
-- **Detailed error codes** (NETWORK_ERROR, UNAUTHORIZED, RATE_LIMITED, etc.)
-- **Request timeouts** (180s default)
+## ⚙️ Environment Variables
 
-## Security
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CONTEXTSTREAM_API_URL` | Yes | API base URL (`https://api.contextstream.io`) |
+| `CONTEXTSTREAM_API_KEY` | Yes | Your API key from contextstream.io |
 
-- No secrets are bundled — provide your own API key/JWT
-- No internal endpoints hardcoded — API URL is required
-- Minimal logging — credentials are not echoed
-- Public REST API only — no proprietary logic included
+---
 
-## Links
+## 🔗 Links
 
 - **Website:** [contextstream.io](https://contextstream.io)
 - **Documentation:** [contextstream.io/docs](https://contextstream.io/docs)
 - **MCP Setup Guide:** [contextstream.io/docs/mcp](https://contextstream.io/docs/mcp)
+- **npm:** [@contextstream/mcp-server](https://www.npmjs.com/package/@contextstream/mcp-server)
+
+---
 
-## License
+## 📄 License
 
 MIT

package/package.json

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