@contextstream/mcp-server 0.2.5

package/.env.example

@@ -0,0 +1,5 @@
+CONTEXTSTREAM_API_URL=http://localhost:8085/api/v1
+CONTEXTSTREAM_API_KEY=
+# CONTEXTSTREAM_JWT=
+# CONTEXTSTREAM_WORKSPACE_ID=
+# CONTEXTSTREAM_PROJECT_ID=

package/README.md

@@ -0,0 +1,255 @@
+# ContextStream MCP Server
+
+A powerful Model Context Protocol (MCP) server that provides code context, memory, knowledge graphs, and AI tools for developers. Connect your AI assistant to your codebase's semantic search, memory system, and dependency analysis.
+
+## 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
+
+### 🧠 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
+
+### 📊 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
+
+### 🤖 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
+
+## Quickstart
+
+```bash
+cd mcp/contextstream-mcp
+cp .env.example .env  # Edit with your API details
+npm install
+npm run dev           # Start MCP server (stdio)
+```
+
+## Client Configuration
+
+### Cursor / VS Code MCP
+```json
+{
+  "mcpServers": {
+    "contextstream": {
+      "command": "npm",
+      "args": ["run", "dev"],
+      "cwd": "/path/to/contextstream/mcp/contextstream-mcp",
+      "env": {
+        "CONTEXTSTREAM_API_URL": "http://localhost:3001/api/v1",
+        "CONTEXTSTREAM_API_KEY": "your-api-key",
+        "CONTEXTSTREAM_WORKSPACE_ID": "optional-default-workspace-uuid",
+        "CONTEXTSTREAM_PROJECT_ID": "optional-default-project-uuid"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+```json
+{
+  "mcpServers": {
+    "contextstream": {
+      "command": "node",
+      "args": ["/path/to/contextstream/mcp/contextstream-mcp/dist/index.js"],
+      "env": {
+        "CONTEXTSTREAM_API_URL": "http://localhost:3001/api/v1",
+        "CONTEXTSTREAM_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CONTEXTSTREAM_API_URL` | Yes | API base URL (e.g., `http://localhost:3001/api/v1`) |
+| `CONTEXTSTREAM_API_KEY` | One of | API key for authentication |
+| `CONTEXTSTREAM_JWT` | One of | JWT token for authentication |
+| `CONTEXTSTREAM_WORKSPACE_ID` | No | Default workspace for operations |
+| `CONTEXTSTREAM_PROJECT_ID` | No | Default project for operations |
+| `CONTEXTSTREAM_USER_AGENT` | No | Custom user agent string |
+
+## Available Tools
+
+### Authentication
+| Tool | Description |
+|------|-------------|
+| `auth_me` | Get current user profile |
+
+### Workspaces
+| Tool | Description |
+|------|-------------|
+| `workspaces_list` | List accessible workspaces |
+| `workspaces_get` | Get workspace details |
+| `workspaces_create` | Create a new workspace |
+| `workspaces_overview` | Get workspace summary |
+| `workspaces_analytics` | Get usage analytics |
+| `workspaces_content` | List workspace content |
+
+### Projects
+| Tool | Description |
+|------|-------------|
+| `projects_list` | List projects (by workspace) |
+| `projects_get` | Get project details |
+| `projects_create` | Create a new project |
+| `projects_overview` | Get project summary |
+| `projects_statistics` | Get code statistics |
+| `projects_files` | List indexed files |
+| `projects_index` | Trigger re-indexing |
+| `projects_index_status` | Check indexing status |
+
+### Search
+| Tool | Description |
+|------|-------------|
+| `search_semantic` | Semantic vector search |
+| `search_hybrid` | Combined semantic + keyword |
+| `search_keyword` | Traditional keyword search |
+| `search_pattern` | Regex pattern search |
+| `search_suggestions` | Get search suggestions |
+
+### Memory
+| Tool | Description |
+|------|-------------|
+| `memory_create_event` | Store a memory event |
+| `memory_get_event` | Retrieve an event |
+| `memory_update_event` | Update an event |
+| `memory_delete_event` | Remove an event |
+| `memory_list_events` | List events in workspace |
+| `memory_bulk_ingest` | Bulk import events |
+| `memory_distill_event` | Extract key insights |
+| `memory_create_node` | Create knowledge node |
+| `memory_get_node` | Get knowledge node |
+| `memory_update_node` | Update knowledge node |
+| `memory_delete_node` | Remove knowledge node |
+| `memory_supersede_node` | Replace with new version |
+| `memory_list_nodes` | List knowledge nodes |
+| `memory_search` | Search memory |
+| `memory_decisions` | Get decision summaries |
+| `memory_timeline` | Get chronological timeline |
+| `memory_summary` | Get condensed summary |
+
+### Graph Analysis
+| Tool | Description |
+|------|-------------|
+| `graph_related` | Find related knowledge nodes |
+| `graph_path` | Find path between nodes |
+| `graph_decisions` | Decision history in graph |
+| `graph_dependencies` | Query code dependencies |
+| `graph_call_path` | Trace call paths |
+| `graph_impact` | Analyze change impact |
+| `graph_circular_dependencies` | Find circular deps |
+| `graph_unused_code` | Find dead code |
+| `graph_contradictions` | Find conflicting info |
+
+### AI
+| Tool | Description |
+|------|-------------|
+| `ai_context` | Build LLM context |
+| `ai_enhanced_context` | Deep context with memory |
+| `ai_embeddings` | Generate embeddings |
+| `ai_plan` | Generate dev plan |
+| `ai_tasks` | Generate tasks |
+
+### Session & Auto-Context (CORE-like)
+These tools enable automatic context initialization for AI assistants:
+
+| 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"
+
+# Then use natural commands:
+"Remember we decided to use PostgreSQL for the database"
+"Recall the authentication decisions we made"
+"What are my coding preferences?"
+```
+
+## Prompts
+
+Pre-built prompts for common workflows:
+
+| Prompt | Description |
+|--------|-------------|
+| `explore-codebase` | Get a codebase overview |
+| `capture-decision` | Document an ADR |
+| `review-context` | Build code review context |
+| `investigate-bug` | Debug investigation helper |
+| `explore-knowledge` | Navigate knowledge graph |
+| `onboard-to-project` | Generate onboarding guide |
+| `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 |
+
+## Scripts
+
+```bash
+npm run dev       # Run with tsx (development)
+npm run build     # Compile TypeScript
+npm start         # Run compiled version
+npm run typecheck # Type check without emit
+```
+
+## Architecture
+
+```
+src/
+├── index.ts      # Server bootstrap
+├── config.ts     # Environment configuration
+├── http.ts       # HTTP client with retries
+├── client.ts     # ContextStream API client
+├── tools.ts      # MCP tools (55+ tools)
+├── resources.ts  # MCP resources
+└── prompts.ts    # MCP prompts (8 workflows)
+```
+
+## 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)
+
+## Security
+
+- 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
+
+## License
+
+MIT