@contextstream/mcp-server

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

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

{
  "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

{
  "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

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