### Minimal Setup with API Key

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/configuration.md

Set the API URL and API key to get started with the minimal configuration.

```bash
export CONTEXTSTREAM_API_URL="https://api.contextstream.io"
export CONTEXTSTREAM_API_KEY="sk_..."
npx @contextstream/mcp-server@latest
```

--------------------------------

### Hook Installation Methods

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/hooks-and-session-manager.md

Provides instructions on how to install contextstream hooks using the setup wizard, the update command with different scopes, or manual installation by placing hook files in editor-specific directories.

```APIDOC
## Hook Installation

### Via Setup Wizard

```bash
contextstream-mcp setup
```

Wizard detects editor and installs appropriate hooks.

### Via Update Command

```bash
# Install for all editors (global)
contextstream-mcp update-hooks --scope=global

# Install for current project only
contextstream-mcp update-hooks --scope=project

# Install for specific project
contextstream-mcp update-hooks --path=/home/user/my-app
```

### Manual Installation

Hooks are stored in editor-specific directories:

```
Claude Code:   ~/.claude/rules/hooks/*.json (via MCP config)
Cursor:        .cursor/rules/contextstream.md
Cline:         .cline/rules/contextstream.md
Roo:           .roo/rules/contextstream.md
Kilo:          .kilo/rules/contextstream.md
```

Example rule file (Cursor):

```markdown
# ContextStream Rules

- Before using Glob/Grep/Read, try search() to avoid token waste
- Capture decisions in session_capture to remember them
- Call context() every message for smart context injection
- Review lessons() output before risky operations

## Hooks

- When session starts: Run contextstream-mcp hook session-init
- When file saved: Run contextstream-mcp hook post-write
- Before context compressed: Run contextstream-mcp hook pre-compact
```
```

--------------------------------

### Run ContextStream MCP Setup Command

Source: https://github.com/contextstream/mcp-server/blob/main/README.md

After installing via the Rust script, run this command to complete the setup process for the ContextStream MCP Server.

```bash
contextstream-mcp setup
```

--------------------------------

### Setup with Default Workspace and Project

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/configuration.md

Configure the default workspace and project IDs along with the API key.

```bash
export CONTEXTSTREAM_API_KEY="sk_..."
export CONTEXTSTREAM_WORKSPACE_ID="ws_abc123"
export CONTEXTSTREAM_PROJECT_ID="proj_def456"
```

--------------------------------

### Install ContextStream MCP Server (PowerShell)

Source: https://github.com/contextstream/mcp-server/blob/main/README.md

Use this PowerShell command to download and execute the installation script for the ContextStream MCP Server.

```powershell
irm https://contextstream.io/scripts/mcp.ps1 | iex
```

--------------------------------

### Install ContextStream MCP Server (Rust - Recommended)

Source: https://github.com/contextstream/mcp-server/blob/main/README.md

This command downloads and executes a script to set up the Rust version of the ContextStream MCP Server. It's the recommended installation method.

```bash
curl -fsSL https://contextstream.io/scripts/mcp.sh | bash
```

--------------------------------

### Install ContextStream MCP Server (Node.js)

Source: https://github.com/contextstream/mcp-server/blob/main/README.md

Use this command to set up the Node.js version of the ContextStream MCP Server. Ensure you have Node.js and npm installed.

```bash
npx --prefer-online -y @contextstream/mcp-server@latest setup
```

--------------------------------

### Example Cursor Hook Rule File

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/hooks-and-session-manager.md

An example rule file for Cursor, demonstrating hook configurations and best practices for ContextStream.

```markdown
# ContextStream Rules

- Before using Glob/Grep/Read, try search() to avoid token waste
- Capture decisions in session_capture to remember them
- Call context() every message for smart context injection
- Review lessons() output before risky operations

## Hooks

- When session starts: Run contextstream-mcp hook session-init
- When file saved: Run contextstream-mcp hook post-write
- Before context compressed: Run contextstream-mcp hook pre-compact
```

--------------------------------

### Global Workspace Mappings Example

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/configuration.md

Maps folder patterns to workspaces for multi-project setups. This file is typically located at ~/.contextstream/mappings.json.

```json
{
  "mappings": [
    {
      "pattern": "/home/alice/dev/projects/*",
      "workspace_id": "ws_f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "workspace_name": "Main Workspace"
    },
    {
      "pattern": "/home/alice/work/client-*",
      "workspace_id": "ws_7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "workspace_name": "Client Work"
    }
  ],
  "fallback_workspace": {
    "workspace_id": "ws_aaaabbbb-cccc-dddd-eeee-ffff00001111",
    "workspace_name": "Global Fallback",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

--------------------------------

### Node.js Install Command for MCP Server

Source: https://github.com/contextstream/mcp-server/blob/main/README.md

Use this command to install the MCP server using Node.js. Ensure you have Node.js and npm installed.

```bash
npx --prefer-online -y @contextstream/mcp-server@latest
```

--------------------------------

### Run MCP Setup Wizard

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/overview.md

Initiates an interactive wizard for the initial configuration of the MCP server and workspace mapping. Use this for setting up a new environment.

```bash
contextstream-mcp setup
```

--------------------------------

### Multi-Project Folder Setup

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/configuration.md

Define mappings in ~/.contextstream/mappings.json to associate specific project folder patterns with workspace IDs and names.

```json
# ~/.contextstream/mappings.json
{
  "mappings": [
    {
      "pattern": "/home/alice/projects/monorepo/*",
      "workspace_id": "ws_mono123",
      "workspace_name": "Monorepo Workspace"
    },
    {
      "pattern": "/home/alice/clients/*",
      "workspace_id": "ws_clients456",
      "workspace_name": "Client Projects"
    }
  ]
}

# Now /home/alice/projects/monorepo/api/ uses ws_mono123
# And /home/alice/clients/acme/ uses ws_clients456
```

--------------------------------

### Manual Hook Installation Directories

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/hooks-and-session-manager.md

Lists the default directories for editor-specific hook rule files.

```text
Claude Code:   ~/.claude/rules/hooks/*.json (via MCP config)
Cursor:        .cursor/rules/contextstream.md
Cline:         .cline/rules/contextstream.md
Roo:           .roo/rules/contextstream.md
Kilo:          .kilo/rules/contextstream.md
```

--------------------------------

### Tool Consolidation Example

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/README.md

Highlights the difference between standard and consolidated domain tools in v0.4.x, showing how related tools are bundled for reduced token usage.

```text
Standard (v0.3.x): projects_list, projects_create, projects_update, projects_delete, ...
Consolidated (v0.4.x): projects (list, create, update, delete, ...)
```

--------------------------------

### Compact Output Example

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/overview.md

Displays a minimal text response, suitable for token-conscious clients. This is the default output format.

```text
Search found 3 results...
```

--------------------------------

### Local Project Configuration

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/overview.md

Example of a local project configuration file (`.contextstream/config.json`). This file specifies workspace and project details for a specific project.

```json
{
  "workspace_id": "uuid-here",
  "workspace_name": "My Workspace",
  "project_id": "uuid-here",
  "project_name": "My Project",
  "associated_at": "2024-01-01T12:00:00Z",
  "version": "0.4.75",
  "indexing_enabled": true
}
```

--------------------------------

### ContextStream OpenAPI Resource Example

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/resources-and-prompts.md

Example configuration for the 'contextstream:openapi' resource. This resource provides the machine-readable OpenAPI specification of the ContextStream API.

```plaintext
Resource: contextstream:openapi
Title: ContextStream OpenAPI spec
Description: Machine-readable OpenAPI from the configured API endpoint
MimeType: application/json
```

--------------------------------

### List MCP Server Installations

Source: https://github.com/contextstream/mcp-server/blob/main/LESSONS.md

Use this command to check the current MCP server installations and identify any pinned versions.

```bash
claude mcp list
```

--------------------------------

### Run Standard MCP Server

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/overview.md

Starts the MCP server with the standard stdio transport, connecting to the ContextStream API and exposing the full toolset. Use this for typical server operations.

```bash
npx @contextstream/mcp-server@latest
```

--------------------------------

### Example Usage of Context Smart Tool

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/tools-reference.md

Demonstrates how to call the context_smart tool with a user message and specific options for including lessons, decisions, and setting a maximum token limit.

```typescript
const context = await context({
  user_message: "I need to refactor the authentication system",
  include_lessons: true,
  include_decisions: true,
  max_tokens: 2000
});
```

--------------------------------

### Pretty JSON Output Example

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/overview.md

Formats the output with structured JSON metadata, including results and budget information. This provides more detailed information than compact output.

```json
{
  "results": [...],
  "metadata": {
    "total": 3,
    "budget": {...}
  }
}
```

--------------------------------

### Hooks Overview

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/MANIFEST.txt

Documentation for the hooks system, covering 25 hooks across the lifecycle, supported editors, hook installation, and integration patterns.

```APIDOC
## Hooks Overview

### Description
Details the hooks system, which provides 25 hooks across the editor lifecycle. Covers supported editors, hook installation, and integration patterns for developers.

### Features
- **Hook Availability**: 25 hooks across the lifecycle.
- **Supported Editors**: Integration with 8 different editors.
- **Hook Installation**: Methods include wizard, update, and manual installation.
- **Hook Integration Patterns**: Guidance on how to integrate hooks.
- **Hook Execution Environment**: Information on the hook execution context.
- **Debugging**: Tips for debugging hooks.
- **Developer API**: API details for creating and managing hooks.
```

--------------------------------

### Global Mappings Configuration

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/overview.md

Example of a global mappings configuration file (`~/.contextstream/mappings.json`). This file defines patterns to associate project paths with specific workspaces and provides a fallback workspace.

```json
{
  "mappings": [
    {
      "pattern": "/home/user/dev/projects/*",
      "workspace_id": "uuid",
      "workspace_name": "Main Workspace"
    }
  ],
  "fallback_workspace": {
    "workspace_id": "uuid",
    "workspace_name": "Fallback Workspace"
  }
}
```

--------------------------------

### Install Hooks via Update Command

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/hooks-and-session-manager.md

Update hooks for different scopes: global, current project, or a specific project path.

```bash
# Install for all editors (global)
contextstream-mcp update-hooks --scope=global
```

```bash
# Install for current project only
contextstream-mcp update-hooks --scope=project
```

```bash
# Install for specific project
contextstream-mcp update-hooks --path=/home/user/my-app
```

--------------------------------

### Structured Content Response Example

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/overview.md

Shows how MCP supports structured content within tool responses, including a content array and structured content object with results and metadata.

```json
{
  "content": [{"type": "text", "text": "..."}],
  "structuredContent": {
    "results": [...],
    "metadata": {...}
  }
}
```

--------------------------------

### Verify MCP Server Version

Source: https://github.com/contextstream/mcp-server/blob/main/LESSONS.md

After configuration changes, verify the installed MCP server version using this command.

```bash
npx -y @contextstream/mcp-server --version
```

--------------------------------

### Session Initialization Hook Stdin Input Example

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/hooks-and-session-manager.md

This JSON structure represents the expected input for the session-init hook via stdin. It includes session and workspace identifiers.

```json
{
  "session_id": "string",
  "folder_path": "string",
  "workspace_id": "string|null",
  "client_name": "string"
}
```

--------------------------------

### MCP Resources and Prompts

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/MANIFEST.txt

Reference for MCP Resources and Prompts, including 3 core resources and 25 guided workflows for exploration, capture, AI assistance, and utility tasks.

```APIDOC
## MCP Resources and Prompts

### Description
Provides details on MCP Resources and a catalog of 25 guided workflows (prompts) designed for various tasks like exploration, data capture, AI assistance, and utility functions.

### MCP Resources
- `contextstream:openapi`
- `contextstream:workspaces`
- `contextstream:projects/{workspaceId}`

### MCP Prompts (25 guided workflows)
- **Exploration Prompts** (6): For codebase, knowledge, onboarding, refactoring, etc.
- **Capture Prompts** (8): For decisions, lessons, preferences, tasks, bugs, features, etc.
- **AI Prompts** (5): For context, planning, task generation, search, budgeting.
- **Utility Prompts** (6): For review, investigation, recall, summarization, finding todos, generating rules.

### Features
- Prompt features include auto-ID handling and access levels.
- Information on resource and prompt limitations.
- Extensibility patterns for prompts.
```

--------------------------------

### ContextStream Workspaces Resource Response Format

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/resources-and-prompts.md

Example JSON response format for the 'contextstream:workspaces' resource, which lists accessible workspaces for an authenticated user.

```json
{
  "items": [
    {
      "id": "ws_abc123",
      "name": "My Company",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T12:00:00Z",
      "member_count": 5,
      "project_count": 3
    }
  ]
}
```

--------------------------------

### Auto-Initialization

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/hooks-and-session-manager.md

Describes the automatic initialization process of the SessionManager upon the first tool call, including context detection, configuration loading, and setup of monitoring systems. It also notes the exception for the `session_init` tool.

```APIDOC
### Auto-Initialization

On first tool call, SessionManager automatically:

1. Detects folder context (from IDE environment)
2. Loads workspace/project from local config
3. Fetches recent decisions and lessons
4. Initializes token tracking
5. Sets up context pressure monitoring

**Skip**: If tool is `session_init` (user explicitly initializing)
```

--------------------------------

### ContextStream Projects Resource Response Format

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/resources-and-prompts.md

Example JSON response format for the 'contextstream:projects/{workspaceId}' resource, detailing projects within a specific workspace.

```json
{
  "items": [
    {
      "id": "proj_abc123",
      "name": "Backend API",
      "description": "RESTful API server",
      "language": "typescript",
      "workspace_id": "ws_abc123",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}
```

--------------------------------

### Progressive Disclosure Mode Activation

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/README.md

Demonstrates how to enable progressive disclosure mode, which starts with a core set of tools and allows for unlocking additional tool bundles like 'memory'.

```text
CONTEXTSTREAM_PROGRESSIVE_MODE=true →
Core tools available →
tools_enable_bundle("memory") →
Memory tools unlocked
```

--------------------------------

### Run HTTP MCP Gateway

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/overview.md

Starts the MCP server using the HTTP transport, suitable for clients that interact via curl or REST APIs. This is useful for integrating with external services.

```bash
contextstream-mcp http
```

--------------------------------

### Configuration Loading Sequence

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/configuration.md

Illustrates the priority order for loading ContextStream configuration settings, from environment variables to global fallback.

```text
┌─ Environment Variables (highest priority)
│  └─ CONTEXTSTREAM_WORKSPACE_ID, PROJECT_ID, etc.
│
├─ Local Project Config
│  └─ .contextstream/config.json
│
├─ Parent Folder Patterns
│  └─ ~/.contextstream/mappings.json
│
└─ Global Fallback (lowest priority)
   └─ ~/.contextstream-global workspace
```

--------------------------------

### client.init()

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/api-reference-client.md

Initializes the workspace and project context. It can resolve context from a local folder path or use provided workspace and project IDs. The `force` option allows re-detection, ignoring cached data.

```APIDOC
## client.init()

### Description
Initializes the workspace and project context from a folder path or explicit IDs. The `force` option can be used to re-detect the workspace and project, bypassing any cached information.

### Method
`init(options: { folder_path?: string; workspace_id?: string; project_id?: string; force?: boolean; }): Promise<unknown>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
const initResult = await client.init({
  folder_path: '/home/user/my-app',
  force: true
});
console.log('Workspace:', initResult.workspace_id, initResult.workspace_name);
```

### Response
#### Success Response
Resolves with an object containing workspace and project details:
- `workspace_id` (string): Resolved workspace ID.
- `workspace_name` (string): Workspace display name.
- `project_id` (string): Resolved project ID (if associated).
- `project_name` (string): Project display name.
- `folder_path` (string): Normalized folder path.
- `is_multi_project` (boolean): Indicates if the folder contains multiple projects.
- `indexed_file_count` (number): Number of files indexed.
- `last_indexed` (string): ISO timestamp of the last indexing.
- `lessons_available` (number): Count of relevant lessons available.

#### Response Example
```json
{
  "workspace_id": "ws-1234",
  "workspace_name": "My App",
  "project_id": "proj-5678",
  "project_name": "Main Project",
  "folder_path": "/home/user/my-app",
  "is_multi_project": false,
  "indexed_file_count": 150,
  "last_indexed": "2023-10-27T10:00:00Z",
  "lessons_available": 5
}
```
```

--------------------------------

### session

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/tools-reference.md

Manage session configuration and state, including getting status, setting defaults, or clearing context.

```APIDOC
## session

### Description
Manage session configuration and state.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
```json
{
  "action": "get_status" | "set_defaults" | "clear_context",
  "workspace_id": "string",
  "project_id": "string",
  "folder_path": "string"
}
```
- **action** (get_status | set_defaults | clear_context) - Required - The action to perform
- **workspace_id** (string) - Optional - Workspace UUID
- **project_id** (string) - Optional - Project UUID
- **folder_path** (string) - Optional - Local folder path

### Response
#### Success Response (200)
Session status and configuration

#### Response Example
```json
{
  "status": "active",
  "config": {
    "default_workspace_id": "string",
    "default_project_id": "string"
  }
}
```
```

--------------------------------

### Update Editor Hooks Command

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/README.md

Command to install or update hooks for all supported editors, ensuring seamless integration.

```bash
contextstream-mcp update-hooks
```

--------------------------------

### Light Toolset Configuration

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/configuration.md

Use a 'light' toolset and 'compact' schema/output modes for token-conscious operations.

```bash
export CONTEXTSTREAM_TOOLSET="light"
export CONTEXTSTREAM_SCHEMA_MODE="compact"
export CONTEXTSTREAM_OUTPUT_FORMAT="compact"
```

--------------------------------

### auth_me

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/tools-reference.md

Get authenticated user profile. This utility tool retrieves the profile information of the currently authenticated user.

```APIDOC
## auth_me

### Description
Get authenticated user profile.

### Returns
User ID, email, account type, plan
```

--------------------------------

### Troubleshooting: Verbose Logging

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/configuration.md

Enable verbose logging to gather detailed information for diagnosing server startup issues.

```bash
CONTEXTSTREAM_LOG_LEVEL=verbose
```

--------------------------------

### mcp_server_version

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/tools-reference.md

Get MCP server package version. This utility tool returns the server name and its current version.

```APIDOC
## mcp_server_version

### Description
Get MCP server package version.

### Returns
Server name and version
```

--------------------------------

### Performance Tuning: Token Budget

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/configuration.md

Enable context pack and set compact schema and output formats to reduce token usage. Limit search results and snippet size for further efficiency.

```bash
export CONTEXTSTREAM_CONTEXT_PACK=true     # Enable context pack for efficiency
export CONTEXTSTREAM_SCHEMA_MODE="compact"  # Reduce schema size
export CONTEXTSTREAM_OUTPUT_FORMAT="compact" # Reduce output size
export CONTEXTSTREAM_SEARCH_LIMIT=3         # Limit search results
export CONTEXTSTREAM_SEARCH_MAX_CHARS=400   # Limit snippet size
```

--------------------------------

### Update MCP Hooks Non-Interactively

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/overview.md

Installs hooks non-interactively for all editors. You can specify the scope as `global` or `project` and provide a specific path.

```bash
contextstream-mcp update-hooks [--scope=global|project] [--path=/path]
```

--------------------------------

### ParentMapping Interface

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/types.md

Defines the structure for mapping folder path patterns to specific workspaces. This is used for multi-project setups and stored in `~/.contextstream/mappings.json`.

```typescript
interface ParentMapping {
  pattern: string;
  workspace_id: string;
  workspace_name: string;
}
```

--------------------------------

### Troubleshooting: Verify Toolset

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/configuration.md

Ensure the CONTEXTSTREAM_TOOLSET environment variable is set to 'standard' and not 'light' when troubleshooting tools not showing.

```bash
CONTEXTSTREAM_TOOLSET=standard
```

--------------------------------

### Progressive Mode Configuration

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/configuration.md

Enable progressive mode for a more user-friendly experience. Users can enable tool bundles like 'memory' separately.

```bash
export CONTEXTSTREAM_PROGRESSIVE_MODE="true"
# Users call tools_enable_bundle("memory") to expand tool set
```

--------------------------------

### Extract Event Tags

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/api-reference-client.md

Extracts tags from top-level and metadata fields of a memory event. Use this function to get all associated tags for an event.

```typescript
function extractEventTags(item: Record<string, any>): string[]
```

--------------------------------

### ContextStreamClient Constructor

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/api-reference-client.md

Initializes the ContextStreamClient with configuration settings. The configuration object should include the API URL, credentials, and any default workspace IDs.

```APIDOC
## Constructor ContextStreamClient

### Description
Initializes the ContextStreamClient with configuration settings. The configuration object should include the API URL, credentials, and any default workspace IDs.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| config | `Config` | Yes | Configuration object with API URL, credentials, and workspace defaults |

### Request Example
```typescript
import { ContextStreamClient } from './client.js';
import { loadConfig } from './config.js';

const config = loadConfig(); // Loads from environment variables
const client = new ContextStreamClient(config);
```

### Response
None
```

--------------------------------

### Instantiate ContextStreamClient

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/api-reference-client.md

Initialize the ContextStreamClient with configuration loaded from environment variables. Ensure the 'loadConfig' function is available and correctly configured.

```typescript
import { ContextStreamClient } from './client.js';
import { loadConfig } from './config.js';

const config = loadConfig(); // Loads from environment variables
const client = new ContextStreamClient(config);
```

--------------------------------

### Get Session ID

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/hooks-and-session-manager.md

Retrieve the unique identifier for the current MCP connection. This ID is used for transcript saving, session association, and state correlation.

```typescript
const sessionId = sessionManager.getSessionId();  // "mcp-<uuid>"
```

--------------------------------

### GitHub Copilot CLI Add MCP Server

Source: https://github.com/contextstream/mcp-server/blob/main/README.md

Use the GitHub Copilot CLI command '/mcp add' to interactively configure the MCP server. This is a convenient way to set up the server without manual file editing.

```bash
/mcp add
```

--------------------------------

### Get Prompt Access Level

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/resources-and-prompts.md

Returns the access level ('Free' or 'PRO') for a given prompt name. Useful for displaying access information to users.

```typescript
promptAccessLabel("prompt-name") // Returns "Free" or "PRO"

```

--------------------------------

### Initialize Workspace Session

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/tools-reference.md

Use `session_init` to establish the context for the current workspace or project. It loads past decisions, lessons, and sets up token tracking. It can auto-detect the workspace from a folder path or use explicit IDs.

```typescript
const result = await session_init({
  folder_path: "/home/user/my-app"
});
```

--------------------------------

### Session Auto-Initialization Flow

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/README.md

Explains the automatic session initialization process when a tool is called for the first time. This includes resolving the workspace, loading decisions, and initializing token tracking.

```text
Tool called → No session yet? → 
  session_init (auto-resolve workspace) →
  Load workspace decisions/lessons →
  Initialize token tracking →
  Proceed with tool
```

--------------------------------

### Troubleshooting: Check Local Configuration

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/configuration.md

Examine the local configuration file to diagnose workspace not found errors.

```bash
cat .contextstream/config.json
```

--------------------------------

### OpenCode Remote MCP Server Configuration

Source: https://github.com/contextstream/mcp-server/blob/main/README.md

Configure OpenCode to use a remote contextstream MCP server. This setup points to a predefined remote server URL.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "contextstream": {
      "type": "remote",
      "url": "https://mcp.contextstream.com",
      "enabled": true
    }
  }
}
```

--------------------------------

### Get Authenticated User Profile

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/api-reference-client.md

Fetch the profile information of the currently authenticated user. The returned object includes user ID, email, and account type.

```typescript
const user = await client.me();
console.log(user.email, user.account_type);
```

--------------------------------

### Initialize Workspace and Project Context

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/api-reference-client.md

Initializes the workspace and project context using a local folder path. Supports overriding workspace and project IDs, and forcing re-detection.

```typescript
init(options: {
  folder_path?: string;
  workspace_id?: string;
  project_id?: string;
  force?: boolean;
}): Promise<unknown>
```

```typescript
const init = await client.init({
  folder_path: '/home/user/my-app'
});
console.log('Workspace:', init.workspace_id, init.workspace_name);
```

--------------------------------

### session_init / init

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/tools-reference.md

Initialize workspace context from folder path or explicit IDs. This function establishes the context for the current workspace or project, loads past decisions and lessons, and sets up token tracking.

```APIDOC
## session_init / init

### Description
Initialize workspace context from folder path or explicit IDs. Establish context for current workspace/project, load past decisions and lessons, set up token tracking.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
```json
{
  "folder_path": "string",
  "workspace_id": "string",
  "project_id": "string",
  "force": "boolean"
}
```
- **folder_path** (string) - Optional - Local folder path (auto-detects workspace)
- **workspace_id** (string) - Optional - Override: explicit workspace UUID
- **project_id** (string) - Optional - Override: explicit project UUID
- **force** (boolean) - Optional - Force re-detection (ignore cache)

### Request Example
```typescript
const result = await session_init({
  folder_path: "/home/user/my-app"
});
```

### Response
#### Success Response (200)
- **workspace_id** (string) - Resolved workspace UUID
- **workspace_name** (string) - Workspace display name
- **project_id** (string) - Optional - Resolved project UUID (if associated)
- **project_name** (string) - Optional - Project display name
- **folder_path** (string) - Normalized folder path
- **is_multi_project** (boolean) - Folder contains multiple projects
- **indexed_file_count** (number) - Optional - Files in semantic index
- **last_indexed** (string) - Optional - ISO timestamp of last indexing
- **lessons_available** (number) - Count of relevant lessons
- **rules_available** (number) - Count of workspace rules
- **decisions_available** (number) - Count of past decisions
- **estimated_tokens** (number) - Estimated tokens for this session
- **search_mode** (string) - Optional - Default search mode (auto, semantic, hybrid)

#### Response Example
```json
{
  "workspace_id": "string",
  "workspace_name": "string",
  "project_id": "string",
  "project_name": "string",
  "folder_path": "string",
  "is_multi_project": false,
  "indexed_file_count": 0,
  "last_indexed": "string",
  "lessons_available": 0,
  "rules_available": 0,
  "decisions_available": 0,
  "estimated_tokens": 0,
  "search_mode": "string"
}
```
```

--------------------------------

### Session Initialization Hook Invocation

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/hooks-and-session-manager.md

This command invokes the session initialization hook. It's triggered when a new session starts to load initial context and rules.

```bash
contextstream-mcp hook session-init
```

--------------------------------

### Semantic Search Example

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/tools-reference.md

Use semantic search to find code by meaning. Specify the natural language query and optionally a project ID and the maximum number of results.

```typescript
const results = await search_semantic({
  query: "how do we validate user input",
  limit: 5
});
```

--------------------------------

### Specific Editor Hook Startup Command

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/README.md

Command to run a specific editor hook, allowing integration with particular development environments.

```bash
contextstream-mcp hook <name>
```

--------------------------------

### Configure MCP Server for Token Efficiency

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/README.md

Set environment variables to optimize token usage and reduce costs. These settings can significantly decrease the number of tokens processed.

```bash
export CONTEXTSTREAM_TOOLSET="standard"
export CONTEXTSTREAM_SCHEMA_MODE="compact"
export CONTEXTSTREAM_OUTPUT_FORMAT="compact"
export CONTEXTSTREAM_CONSOLIDATED="true"  # ~75% token reduction
export CONTEXTSTREAM_SEARCH_LIMIT="3"
export CONTEXTSTREAM_SEARCH_MAX_CHARS="400"
```

--------------------------------

### Common Hook Pattern: Auto-Initialization

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/hooks-and-session-manager.md

Describes a pattern for automatically detecting the folder, loading workspace context, and setting session defaults when a session is not explicitly initialized.

```plaintext
First tool call → session_init not called → 
Auto-detect folder → Load workspace context → 
Set session defaults
```

--------------------------------

### Get Default Search Mode

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/hooks-and-session-manager.md

Retrieve the preferred search mode for the current session. This mode can be set by the `session_init` response, `context` tool recommendation, or user preferences.

```typescript
const mode = sessionManager.getDefaultSearchMode();
// Returns: "auto" | "semantic" | "hybrid" | "keyword" | null
```

--------------------------------

### GitHub Copilot CLI Node MCP Server Configuration

Source: https://github.com/contextstream/mcp-server/blob/main/README.md

Configure the contextstream MCP server for GitHub Copilot CLI using a local Node.js runtime. This JSON configuration specifies 'npx' as the command and provides necessary environment variables.

```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",
        "CONTEXTSTREAM_TOOLSET": "complete",
        "CONTEXTSTREAM_TRANSCRIPTS_ENABLED": "true",
        "CONTEXTSTREAM_HOOK_TRANSCRIPTS_ENABLED": "true",
        "CONTEXTSTREAM_SEARCH_LIMIT": "15",
        "CONTEXTSTREAM_SEARCH_MAX_CHARS": "2400"
      }
    }
  }
}
```

--------------------------------

### createProject

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/api-reference-client.md

Creates a new project within a workspace. Requires a project name and optionally accepts a description and primary language.

```APIDOC
## createProject

### Description
Creates a new project within a workspace. Requires a project name and optionally accepts a description and primary language.

### Method
`createProject(options: { workspace_id?: string; name: string; description?: string; language?: string }): Promise<unknown>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **workspace_id** (string) - Optional - Workspace ID (defaults to client default).
- **name** (string) - Required - Project name.
- **description** (string) - Optional - Project description.
- **language** (string) - Optional - Primary programming language.

### Request Example
```typescript
const newProject = await client.createProject({
  name: 'My New Project',
  description: 'A project for testing purposes',
  language: 'typescript'
});
```

### Response
#### Success Response
- **created project object** (unknown) - Promise resolving to created project object with ID.
```

--------------------------------

### Workspace ID URI Completion Handler

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/resources-and-prompts.md

Example TypeScript code for a 'complete' handler that provides known workspace IDs for URI auto-completion. It fetches workspaces using the ContextStream client.

```typescript
complete: {
  workspaceId: async () => {
    const workspaces = await client.listWorkspaces({ page_size: 50 });
    return items.map((w) => w.id);
  },
}
```

--------------------------------

### Get Project Ingest Status

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/api-reference-client.md

Use `checkIngestStatus` to retrieve the current indexing status for a given project. This includes the number of indexed files, the current status, and details about pending files.

```typescript
await client.checkIngestStatus(projectId: string): Promise<unknown>
```

--------------------------------

### Troubleshooting: Enable Tool Bundle

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/configuration.md

Call the tools_enable_bundle() function to enable tools, particularly relevant in progressive mode.

```python
tools_enable_bundle()
```

--------------------------------

### OpenCode Local MCP Server Configuration

Source: https://github.com/contextstream/mcp-server/blob/main/README.md

Configure OpenCode to use a local contextstream MCP server. Ensure the CONTEXTSTREAM_API_KEY environment variable is exported before launching OpenCode.

```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
    }
  }
}
```

--------------------------------

### VS Code Node MCP Server Configuration

Source: https://github.com/contextstream/mcp-server/blob/main/README.md

Configure VS Code to use a local Node.js MCP server. This setup involves specifying 'npx' as the command and providing necessary environment variables.

```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",
        "CONTEXTSTREAM_TRANSCRIPTS_ENABLED": "true",
        "CONTEXTSTREAM_HOOK_TRANSCRIPTS_ENABLED": "true",
        "CONTEXTSTREAM_SEARCH_LIMIT": "15",
        "CONTEXTSTREAM_SEARCH_MAX_CHARS": "2400"
      }
    }
  }
}
```

--------------------------------

### Integrate MCP Server in Custom Application

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/README.md

Use this snippet to initialize and register tools with the MCP Server in a custom application. Ensure configuration loading and client initialization are handled.

```typescript
import { loadConfig } from './config.js';
import { ContextStreamClient } from './client.js';
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerTools } from './tools.js';

const config = loadConfig();
const client = new ContextStreamClient(config);
const server = new McpServer({ name: "myapp", version: "1.0" });

registerTools(server, client);
// Connect server to transport...
```

--------------------------------

### Troubleshooting: Check Environment Variables

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/configuration.md

Inspect all active environment variables related to CONTEXTSTREAM to identify potential misconfigurations.

```bash
env | grep CONTEXTSTREAM
```

--------------------------------

### VS Code Rust MCP Configuration

Source: https://github.com/contextstream/mcp-server/blob/main/README.md

Configure VS Code to use a local Rust MCP server. This setup requires specifying the command, arguments, and various environment variables for optimal performance.

```json
{
  "servers": {
    "contextstream": {
      "type": "stdio",
      "command": "contextstream-mcp",
      "args": [],
      "env": {
        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
        "CONTEXTSTREAM_API_KEY": "your_key",
        "CONTEXTSTREAM_TOOLSET": "complete",
        "CONTEXTSTREAM_TRANSCRIPTS_ENABLED": "true",
        "CONTEXTSTREAM_HOOK_TRANSCRIPTS_ENABLED": "true",
        "CONTEXTSTREAM_SEARCH_LIMIT": "15",
        "CONTEXTSTREAM_SEARCH_MAX_CHARS": "2400"
      }
    }
  }
}
```

--------------------------------

### Index Local Repository

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/resources-and-prompts.md

Ingests local files into ContextStream for indexing and search. Use this to set up semantic search for a project.

```python
from mcp.project import projects_ingest_local, projects_index_status

# Example usage:
# projects_ingest_local(local_directory_path)
# Monitor status via projects_index_status()

```

--------------------------------

### VS Code Hosted Remote MCP Configuration

Source: https://github.com/contextstream/mcp-server/blob/main/README.md

Configure VS Code to use the hosted remote MCP server for GitHub Copilot. This is the recommended setup and does not require an API key in the config file.

```json
{
  "servers": {
    "contextstream": {
      "type": "http",
      "url": "https://mcp.contextstream.io/mcp?default_context_mode=fast"
    }
  }
}
```

--------------------------------

### GitHub Copilot CLI Rust MCP Configuration

Source: https://github.com/contextstream/mcp-server/blob/main/README.md

Configure the contextstream MCP server for GitHub Copilot CLI using a local Rust runtime. This JSON configuration specifies the command and environment variables.

```json
{
  "mcpServers": {
    "contextstream": {
      "command": "contextstream-mcp",
      "args": [],
      "env": {
        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
        "CONTEXTSTREAM_API_KEY": "your_key",
        "CONTEXTSTREAM_TOOLSET": "complete",
        "CONTEXTSTREAM_TRANSCRIPTS_ENABLED": "true",
        "CONTEXTSTREAM_HOOK_TRANSCRIPTS_ENABLED": "true",
        "CONTEXTSTREAM_SEARCH_LIMIT": "15",
        "CONTEXTSTREAM_SEARCH_MAX_CHARS": "2400"
      }
    }
  }
}
```

--------------------------------

### Regex Pattern Search Example

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/tools-reference.md

Use regex pattern search to find code matching specific patterns like TODOs or FIXMEs. Specify the regex pattern and optionally a project ID and the maximum number of results.

```typescript
const todos = await search_pattern({
  pattern: "TODO|FIXME|HACK",
  limit: 20
});
```

--------------------------------

### Get Smart Context for Tasks

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/api-reference-client.md

Use `getContext` to retrieve smart context relevant to your current task or query. You can specify workspace, project, query details, folder path, and whether to include lessons or decisions. The context can be limited by token count.

```typescript
await client.getContext({
  workspace_id?: string;
  project_id?: string;
  query?: string;
  folder_path?: string;
  include_lessons?: boolean;
  include_decisions?: boolean;
  max_tokens?: number;
}): Promise<unknown>
```

--------------------------------

### Troubleshooting: Check Global Mappings

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/configuration.md

Inspect the global mappings file to troubleshoot workspace not found issues.

```bash
cat ~/.contextstream/mappings.json
```

--------------------------------

### Register a Custom Prompt

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/resources-and-prompts.md

Register a new prompt with the McpServer. This involves providing a unique name, display title, description, and an async function that returns the messages for the prompt.

```typescript
server.registerPrompt(
  "prompt-name",
  {
    title: "Prompt Title",
    description: "What this prompt does"
  },
  async () => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: "Prompt instruction text"
        }
      }
    ]
  })
)
```

--------------------------------

### Project Files Parameters

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/tools-reference.md

Parameters for browsing the file structure of a project. Allows specifying a path and recursive search.

```typescript
{
  project_id?: string;
  path?: string;       // Start from this path
  recursive?: boolean;     // Include subdirectories
}
```

--------------------------------

### Project List Parameters

Source: https://github.com/contextstream/mcp-server/blob/main/_autodocs/tools-reference.md

Parameters for listing projects within a workspace. Supports pagination.

```typescript
{
  workspace_id?: string;
  page?: number;
  page_size?: number;
}
```