### Run ContextStream MCP Server Setup

Source: https://contextstream.io/docs/index

This snippet shows how to run the setup wizard for the ContextStream MCP server using npx. It's the recommended way to get started. No specific inputs or outputs are detailed, but it initiates the server setup process.

```bash
# 1) Run the setup wizard (recommended)
npx -y @contextstream/mcp-server setup
```

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

### Install MCP Server Setup Wizard

Source: https://contextstream.io/docs/team

Installs and sets up the ContextStream MCP server using a command-line wizard. This tool authenticates users and configures their AI editors (like VS Code, Cursor) to connect to the team's shared workspace.

```shell
npx -y @contextstream/mcp-server setup
```

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

### ContextStream Quick Reference Tools

Source: https://contextstream.io/docs/mcp

A quick reference guide for common ContextStream tools and their example usage, including search, session, memory, and graph.

```python
search(mode="hybrid", query="auth", limit=3)
```

```python
session(action="capture", event_type="decision", title="...", content="...")
```

```python
memory(action="list_events", limit=10)
```

```python
graph(action="dependencies", file_path="...")
```

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

### Configure ContextStream MCP Server

Source: https://contextstream.io/docs/quickstart

This JSON configuration snippet sets up the ContextStream MCP server within your AI tool's `.mcp.json` file. It specifies the command to run the server, arguments, and environment variables for API URL and key. Ensure you replace 'YOUR_API_KEY' with your actual key.

```json
{
  "mcpServers": {
    "contextstream": {
      "command": "npx",
      "args": ["-y", "@contextstream/mcp-server"],
      "env": {
        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
        "CONTEXTSTREAM_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

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

### Preview MCP Server Setup Changes

Source: https://contextstream.io/docs/mcp

Runs the ContextStream MCP server setup wizard in dry-run mode, allowing you to preview configuration changes without actually writing them to files. This is useful for verifying settings before applying them.

```bash
npx -y @contextstream/mcp-server setup --dry-run
```

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

### ContextStream Tool Usage Examples

Source: https://contextstream.io/docs/mcp

This section provides quick reference examples for common ContextStream MCP tools, including search, session management for capturing decisions and plans, memory operations, and graph analysis for dependencies.

```tool_usage
search(mode="hybrid", query="auth", limit=3)
session(action="capture", event_type="decision", title="...", content="...")
memory(action="list_events", limit=10)
graph(action="dependencies", file_path="...")
session(action="capture_plan", title="...", steps=[...])
memory(action="create_task", title="...", plan_id="<id>")
```

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

### Summarize GitHub Activity

Source: https://contextstream.io/docs/integrations/github

This example demonstrates how to generate a summary of GitHub activity over a defined period. It's helpful for getting a high-level overview of repository engagement and changes.

```python
summarize_github_activity(period="past 2 weeks")
```

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

### Reminder and Integration Tool Examples

Source: https://contextstream.io/docs/mcp

Shows how to manage reminders and interact with integrations like Slack and GitHub. Examples include listing active reminders, creating new ones, and checking the status or searching within integrations.

```python
reminder(action="active")
reminder(action="list")
reminder(action="create", message="Follow up on PR", due_date="...")
reminder(action="snooze", reminder_id="<uuid>")
reminder(action="complete", reminder_id="<uuid>")
reminder(action="dismiss", reminder_id="<uuid>")
integration(provider="github", action="status")
integration(provider="slack", action="search", query="meeting notes")
integration(provider="github", action="stats", repo="owner/repo")
integration(provider="slack", action="activity")
integration(provider="github", action="contributors", repo="owner/repo")
integration(provider="slack", action="knowledge", query="API design")
integration(provider="github", action="summary", repo="owner/repo")
integration(provider="slack", action="channels")
integration(provider="slack", action="discussions")
integration(provider="github", action="sync_users")
integration(provider="github", action="repos", org="owner")
integration(provider="github", action="issues", repo="owner/repo", query="bug")
```

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

### Integration Tool Example

Source: https://contextstream.io/docs/mcp/tools

Demonstrates the usage of the integration tool, specifically for searching GitHub. This tool allows interaction with external services to enrich context.

```python
integration(provider="github", action="search", query="contextstream mcp")
```

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

### Example ContextStream MCP Queries

Source: https://contextstream.io/docs/index

These examples demonstrate natural language queries that can be used with an AI tool integrated with ContextStream's MCP protocol. They showcase how to ask for session summaries, remember specific details, and retrieve past decisions.

```natural_language
# 2) Ask naturally in your AI tool
"session summary"
"remember we're using PostgreSQL"
"what did we decide about auth?"
```

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

### Retrieve Lessons with Session Get Lessons

Source: https://contextstream.io/docs/mcp

Examples of using the `session_get_lessons` function to retrieve lessons based on different filters such as severity, category, query, and limit. This function allows for targeted retrieval of learned information.

```javascript
// Get all critical lessons
session_get_lessons({ severity: "critical" })

// Get workflow lessons
session_get_lessons({ category: "workflow" })

// Search for relevant lessons
session_get_lessons({ query: "git push images" })

// Combine filters
session_get_lessons({
  category: "verification",
  severity: "high",
  limit: 5
})
```

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

### ContextStream Initial Session Setup

Source: https://contextstream.io/docs/mcp

Shows the initial tool calls required for a new session, including `session_init` for folder context and `context_smart` for processing the user's message.

```python
session_init(folder_path="<cwd>", context_hint="<msg>")
```

```python
context_smart(user_message="<msg>", format="minified", max_tokens=400)
```

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

### Session Domain Tool Actions

Source: https://contextstream.io/docs/mcp

Illustrates the various actions available for the `session` domain tool, including capturing lessons, retrieving past sessions, and managing plans. It shows examples for capturing decisions, getting lessons, and creating plans.

```python
session(action="capture", event_type="decision", title="Use JWT", content="...")
session(action="capture_lesson", title="Incorrect API Usage", trigger="Used deprecated endpoint", impact="API errors", prevention="Check documentation before use")
session(action="get_lessons", query="authentication")
session(action="capture_plan", title="Implement User Authentication", description="Steps to add user auth", goals=["Secure user login", "Implement JWT"], steps=[{"id": "1", "title": "Setup JWT library", "order": 1}])
session(action="list_plans")
session(action="get_plan", plan_id="<uuid>", include_tasks=true)
```

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

### Update ContextStream MCP Server

Source: https://contextstream.io/docs/quickstart

This command updates the ContextStream MCP server to the latest version using npm. Running this command ensures you have the newest features and bug fixes. The MCP server will notify you when an update is available.

```bash
npm update -g @contextstream/mcp-server
```

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

### ContextStream Initialization and Core Functions

Source: https://contextstream.io/docs/mcp

Demonstrates the initial setup and core functions required for every interaction with ContextStream, including session initialization and smart context retrieval.

```markdown
**TL;DR - REQUIRED EVERY MESSAGE**

| Message | What to Call |
|---------|--------------|
| **1st message** | `session_init(folder_path="...", context_hint="<user's message>")`, then `context_smart(user_message="<user's message>", format="minified", max_tokens=400)` |
| **2nd+ messages** | `context_smart(user_message="<user's message>", format="minified", max_tokens=400)` |
| **🔍 ANY code search** | `search(mode="hybrid", query="...")` — ALWAYS before Glob/Grep/Search/Read |
| **Before risky/non-trivial work** | `session(action="get_lessons", query="<topic>")` |
| **After completing task** | `session(action="capture", event_type="decision", ...)` - MUST capture |
| **User frustration/correction** | `session(action="capture_lesson", ...)` - MUST capture lessons |

**NO EXCEPTIONS.** Do not skip even if you think you have enough context.

**First message rule:** After `session_init`, always call `context_smart` before any other tool or response.
```

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

### Context Pack Usage

Source: https://contextstream.io/docs/context-pack

This section details how to use the Context Pack feature via the `context_smart` function. It explains the parameters and provides an example.

```APIDOC
## POST /context_smart

### Description
This endpoint allows you to leverage the Context Pack feature to get a distilled bundle of relevant information for your query. It's designed to keep prompts small while delivering the most pertinent code, graph signals, and memory context.

### Method
POST

### Endpoint
/context_smart

### Parameters
#### Query Parameters
- **user_message** (string) - Required - The user's query or message.
- **format** (string) - Optional - Specifies the output format. Use `"minified"` for compact output.
- **max_tokens** (integer) - Optional - Sets a hard budget for the response payload size.
- **mode** (string) - Required - Set to `"pack"` to enable Context Pack.
- **distill** (boolean) - Optional - If `true`, returns a compact summary when available.

### Request Example
```json
{
  "user_message": "What does the auth refresh worker do?",
  "format": "minified",
  "max_tokens": 400,
  "mode": "pack",
  "distill": true
}
```

### Response
#### Success Response (200)
- **context_pack_content** (string) - The distilled bundle of code, graph signals, and memory context relevant to the user's message.

#### Response Example
```json
{
  "context_pack_content": "// Relevant code snippets and explanations...\n// Dependency information...\n// Prior decisions and preferences..."
}
```
```

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

### Token-Efficient Search Request Example

Source: https://contextstream.io/docs/search

An example JSON payload for a token-efficient search query. This demonstrates setting the query, search type, limit, offset, and content character limit for optimized API calls.

```json
{
  "query": "auth token refresh flow",
  "search_type": "hybrid",
  "limit": 3,
  "offset": 0,
  "content_max_chars": 280
}
```

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

### Session Management: Lessons (Python)

Source: https://contextstream.io/docs/mcp

Provides examples of how to interact with session lessons. This includes checking for lessons after initialization, retrieving lessons based on a query, and capturing new lessons with detailed information.

```python
session_init()
# Check for lessons field in response
session(action="get_lessons", query="<topic>")
session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")
```

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

### Help Domain Tool Functions

Source: https://contextstream.io/docs/mcp

Illustrates the use of the `help` domain tool to get information about available tools, authentication, version, editor rules, and enabling bundles.

```python
help(action="tools")
help(action="auth")
help(action="version")
help(action="editor_rules")
help(action="enable_bundle", bundle_name="python")
```

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

### Get Available Tools (Python)

Source: https://contextstream.io/docs/mcp

Retrieves information about available tools using the `help` tool with the `tools` action. This is helpful for discovering and understanding the capabilities of the ContextStream system.

```python
from contextstream import help

tools_info = help(action="tools")

print(tools_info)
```

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

### Get MCP Server Version with `help(action='version')`

Source: https://contextstream.io/docs/mcp/tools

This function returns the version of the running MCP server. It's essential for compatibility checks and understanding the deployed environment.

```python
help(action="version", ...)
```

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

### Get Authenticated User Info with `help(action='auth')`

Source: https://contextstream.io/docs/mcp/tools

This function retrieves information about the currently authenticated user. It helps in verifying user identity and permissions within the system.

```python
help(action="auth", ...)
```

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

### ContextStream Editor Rules for Claude Code

Source: https://contextstream.io/docs/quickstart

These are mandatory rules for Claude Code to ensure ContextStream is used effectively. They dictate the order of operations, prioritizing ContextStream searches and context retrieval before resorting to local tools. These rules must be displayed verbatim at the start of every AI response to maintain context.

```markdown
## 🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨

<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `mcp__contextstream__search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `mcp__contextstream__context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>

**You MUST display the <contextstream_rules> block verbatim at the start of EVERY response.**
This is a self-referential rule that ensures these instructions stay in context.

---

## ContextStream v0.4.x (Hooks Enforced)

Rules Version: 0.4.35
**Note:** PreToolUse hooks block Glob/Grep/Search when ContextStream is available.

### Required Every Message

| Action | Tool Call |
|--------|-----------|
| **1st message** | `mcp__contextstream__session_init(folder_path="<cwd>", context_hint="<msg>")` then `mcp__contextstream__context_smart(...)` |
| **2nd+ messages** | `mcp__contextstream__context_smart(user_message="<msg>", format="minified", max_tokens=400)` |
| **Code search** | `mcp__contextstream__search(mode="hybrid", query="...")` — BEFORE any local tools |
| **Save decisions** | `mcp__contextstream__session(action="capture", event_type="decision", ...)` |

### Search Modes

| Mode | Use Case |
|------|----------|
| `hybrid` | General code mcp__contextstream__search (default) |
| `keyword` | Exact symbol/string match |
| `exhaustive` | Find ALL matches (grep-like) |
| `semantic` | Conceptual questions |

### Why ContextStream First?

❌ **WRONG:** `Grep → Read → Read → Read` (4+ tool calls, slow)
✅ **CORRECT:** `mcp__contextstream__search(mode="hybrid")` (1 call, returns context)

ContextStream search is **indexed** and returns semantic matches + context in ONE call.

### Quick Reference

| Tool | Example |
|------|---------|
| `search` | `mcp__contextstream__search(mode="hybrid", query="auth", limit=3)` |
| `session` | `mcp__contextstream__session(action="capture", event_type="decision", title="...", content="...")` |
| `memory` | `mcp__contextstream__memory(action="list_events", limit=10)` |
| `graph` | `mcp__contextstream__graph(action="dependencies", file_path="...")` |

### Lessons (Past Mistakes)

- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `mcp__contextstream__session(action="get_lessons", query="<topic>")`
- On mistakes: `mcp__contextstream__session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`

### Plans & Tasks

When user asks for a plan, use ContextStream (not EnterPlanMode):
1. `mcp__contextstream__session(action="capture_plan", title="...", steps=[...])`
2. `mcp__contextstream__memory(action="create_task", title="...", plan_id="<id>")`

Full docs: https://contextstream.io/docs/mcp/tools
```

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

### List Available Tools with `help(action='tools')`

Source: https://contextstream.io/docs/mcp/tools

This function lists all available tools and their associated actions within the ContextStream IO project. It's useful for discovering the capabilities of the system.

```python
help(action="tools", ...)
```

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

### Get All Decisions API Request (cURL)

Source: https://contextstream.io/docs/graphs

Shows a simple cURL command to retrieve all decision nodes within a specified workspace. This is a GET request to a dedicated endpoint for decisions.

```bash
curl https://api.contextstream.io/api/v1/graph/knowledge/decisions?workspace_id=your-workspace-id \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

### Help API - Specific Actions

Source: https://contextstream.io/docs/mcp/tools

This section details specific actions available through the `help` utility, including listing tools, getting authentication info, checking server version, generating editor rules, and enabling bundles.

```APIDOC
## `help(action="tools")`

### Description
List available tools and their actions.

### Method
`help` (function call)

### Endpoint
N/A (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
`help(action="tools", ...)`

### Response
#### Success Response (200)
List of available tools and their associated actions.

#### Response Example
```json
{
  "tools": [
    {
      "name": "auth",
      "description": "Get current authenticated user info."
    },
    {
      "name": "version",
      "description": "Get the running MCP server version."
    }
  ]
}
```

---

## `help(action="auth")`

### Description
Get current authenticated user info.

### Method
`help` (function call)

### Endpoint
N/A (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
`help(action="auth", ...)`

### Response
#### Success Response (200)
Information about the currently authenticated user.

#### Response Example
```json
{
  "user": "authenticated_user@example.com"
}
```

---

## `help(action="version")`

### Description
Get the running MCP server version.

### Method
`help` (function call)

### Endpoint
N/A (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
`help(action="version", ...)`

### Response
#### Success Response (200)
The version string of the running MCP server.

#### Response Example
```json
{
  "version": "v0.4.0"
}
```

---

## `help(action="editor_rules")`

### Description
Generate ContextStream AI rule files for editors.

### Method
`help` (function call)

### Endpoint
N/A (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
`help(action="editor_rules", ...)`

### Response
#### Success Response (200)
ContextStream AI rule files formatted for editors.

#### Response Example
```json
{
  "rules": "# ContextStream AI Rules\n# ..."
}
```

---

## `help(action="enable_bundle")`

### Description
Enable a tool bundle in progressive mode.

### Method
`help` (function call)

### Endpoint
N/A (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
`help(action="enable_bundle", bundle="memory")`

### Response
#### Success Response (200)
Confirmation that the bundle has been enabled.

#### Response Example
```json
{
  "status": "enabled",
  "bundle": "memory"
}
```
```

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

### Context Retrieval and Initialization

Source: https://contextstream.io/docs/mcp

Explains the difference between session_init and context_smart, and when to use each for optimal context retrieval.

```APIDOC
## Context Retrieval and Initialization

### Description
`session_init` retrieves the last ~10 items chronologically, while `context_smart` semantically searches for items relevant to the current message. `context_smart` is crucial for finding older, relevant context that `session_init` might miss.

### Method
POST (Implicit for `session_init` and `context_smart` calls)

### Endpoint
N/A (Tool calls within the API)

### Parameters
#### `session_init`
- **folder_path** (string) - Required - The path to the current working directory.
- **context_hint** (string) - Optional - A hint for the initial context.

#### `context_smart`
- **user_message** (string) - Required - The current user message to find relevant context for.
- **format** (string) - Optional - Specifies the output format (e.g., `minified`). Defaults to `full`.
- **max_tokens** (integer) - Optional - Maximum number of tokens for the response. Defaults to 400 when `format` is `minified`.

### Request Example
```json
{
  "tool_call": "session_init(folder_path=\".\", context_hint=\"User asks about authentication\")"
}
```
```json
{
  "tool_call": "context_smart(user_message=\"How should I implement authentication?\", format=\"minified\", max_tokens=400)"
}
```

### Response
#### Success Response (200)
- **context** (string) - The retrieved context relevant to the user's message.

#### Response Example
```json
{
  "context": "Authentication decisions were made 20 conversations ago..."
}
```
```

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

### Search GitHub Issues by Keyword

Source: https://contextstream.io/docs/integrations/github

This prompt example shows how to search for open GitHub issues related to a specific keyword, such as 'performance'. It helps in quickly identifying relevant issues for further investigation or action.

```text
What open issues do we have about performance?
```

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

### Creating and Managing Plans and Tasks

Source: https://contextstream.io/docs/mcp

Provides code examples for creating and managing project plans and tasks using `session` and `memory` tools. This includes capturing plans with goals and steps, creating tasks associated with a plan, and listing or updating the status of plans and tasks.

```python
session(action="capture_plan", title="Plan Title", description="...", goals=["goal1", "goal2"], steps=[{id: "1", title: "Step 1", order: 1}, ...])
```

```python
memory(action="create_task", title="Task Title", plan_id="<plan_id>", priority="high|medium|low", description="...")
```

```python
session(action="list_plans")
```

```python
session(action="get_plan", plan_id="<uuid>", include_tasks=true)
```

```python
memory(action="list_tasks", plan_id="<uuid>")
```

```python
memory(action="update_task", task_id="<uuid>", task_status="pending|in_progress|completed|blocked")
```

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

### Extract Lessons Learned from GitHub Refactor

Source: https://contextstream.io/docs/integrations/github

This prompt example shows how to extract lessons learned from specific development activities, like an API refactor, by querying GitHub discussions. It facilitates knowledge sharing and prevents repeating past mistakes.

```text
What lessons did we learn from the API refactor?
```

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

### Get Page Content

Source: https://contextstream.io/docs/integrations/notion

Fetches the detailed content of a specific Notion page, including all its blocks, properties, and metadata.

```APIDOC
## GET /integration/notion/get_page

### Description
Get detailed content of a specific page including all blocks, properties, and metadata.

### Method
GET

### Endpoint
`/integration(provider="notion", action="get_page", page_id="...")`

### Parameters
#### Query Parameters
- **provider** (string) - Required - Specifies the data provider, should be "notion".
- **action** (string) - Required - Specifies the action to perform, should be "get_page".
- **page_id** (string) - Required - The unique identifier of the Notion page to retrieve.

### Response
#### Success Response (200)
- **page_content** (object) - An object containing the full details of the Notion page, including its properties, blocks, and metadata.

#### Response Example
```json
{
  "page_content": {
    "id": "page_id_123",
    "title": "Project Kickoff Meeting",
    "properties": {
      "Status": "Completed",
      "Date": "2023-10-26"
    },
    "blocks": [
      {
        "type": "heading_2",
        "text": "Agenda"
      },
      {
        "type": "bulleted_list_item",
        "text": "Introductions"
      },
      {
        "type": "paragraph",
        "text": "Discuss project goals and scope."
      }
    ],
    "metadata": {
      "created_time": "2023-10-26T10:00:00Z",
      "last_edited_time": "2023-10-26T11:30:00Z"
    }
  }
}
```
```

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

### Summarize GitHub Activity by Time Period

Source: https://contextstream.io/docs/integrations/github

This prompt example shows how to obtain a summary of GitHub activity over a specified period, such as the past two weeks. It provides a concise overview of repository events and engagement.

```text
Summarize GitHub activity for the past 2 weeks
```

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

### Kilo Code Rule Enforcement

Source: https://contextstream.io/docs/mcp

Details the mandatory Kilo Code rule that must be displayed at the start of every response.

```APIDOC
## Kilo Code Rule Enforcement

### Description
This rule mandates the verbatim display of the `<contextstream_rules>` block at the beginning of every response to ensure critical instructions remain in context.

### Method
N/A (Mandatory output format)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **Output**: The `<contextstream_rules>` block is prepended to the response.

#### Response Example
```markdown
<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream returns 0 results after retry
</contextstream_rules>

[Rest of the response...]
```
```

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

### Workspace Operations

Source: https://contextstream.io/docs/mcp

Handles workspace-related operations such as listing available workspaces, getting workspace details, associating items, and bootstrapping new workspaces.

```python
workspace(action="list")
```

```python
workspace(action="bootstrap", ...)
```

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

### Initialize Session and Get Context

Source: https://contextstream.io/docs/mcp

Initializes a session with workspace detection and retrieves context. This is the first step for any interaction and should always be followed by `context_smart`.

```python
session_init(folder_path="...", context_hint="<user's message>")
context_smart(user_message="<user's message>", format="minified", max_tokens=400)
```

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

### ContextStream Session Management (Capture and Get Lessons)

Source: https://contextstream.io/docs/mcp

Manages session data by capturing events like decisions and retrieving lessons learned.

```APIDOC
## POST /websites/contextstream_io/session

### Description
Manages session-related actions, including capturing events and retrieving lessons.

### Method
POST

### Endpoint
`/websites/contextstream_io/session`

### Parameters
#### Request Body
- **action** (string) - Required - The action to perform. Options: `capture`, `get_lessons`, `capture_lesson`.
- **event_type** (string) - Optional (Required for `action="capture"`) - The type of event to capture (e.g., `decision`).
- **title** (string) - Optional (Required for `action="capture_lesson"` or `action="capture_plan"`) - The title of the lesson or plan.
- **content** (string) - Optional (Required for `action="capture"`) - The content of the captured event.
- **query** (string) - Optional (Required for `action="get_lessons"`) - The query to find relevant lessons.
- **trigger** (string) - Optional (Required for `action="capture_lesson"`) - The trigger condition for the lesson.
- **impact** (string) - Optional (Required for `action="capture_lesson"`) - The impact of the mistake.
- **prevention** (string) - Optional (Required for `action="capture_lesson"`) - How to prevent the mistake.
- **steps** (array) - Optional (Required for `action="capture_plan"`) - An array of steps for a captured plan.

### Request Example (Capture Decision)
```json
{
  "action": "capture",
  "event_type": "decision",
  "title": "Chose to refactor auth module",
  "content": "Refactoring the auth module to improve security and performance."
}
```

### Request Example (Get Lessons)
```json
{
  "action": "get_lessons",
  "query": "handling user input"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message of the action performed.
- **lessons** (array) - Optional - A list of lessons retrieved (if `action="get_lessons"`).

#### Response Example
```json
{
  "message": "Decision captured successfully."
}
```
```

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

### Slack Integration - Get Top Contributors

Source: https://contextstream.io/docs/integrations/slack

Retrieves a list of top contributors based on their message count, including their user profiles.

```APIDOC
## POST /integration/slack/contributors

### Description
Get top contributors by message count with user profiles.

### Method
POST

### Endpoint
`/integration/slack/contributors`

### Parameters
None

### Request Body
```json
{
  "action": "contributors"
}
```

### Response
#### Success Response (200)
- **contributors** (array) - An array of contributor objects, sorted by message count.
  - **user_id** (string) - Unique identifier for the user.
  - **display_name** (string) - The display name of the user.
  - **real_name** (string) - The real name of the user.
  - **message_count** (integer) - The total number of messages sent by the user.
  - **profile_picture_url** (string) - URL to the user's profile picture.

#### Response Example
```json
{
  "contributors": [
    {
      "user_id": "U123ABC",
      "display_name": "Alice",
      "real_name": "Alice Smith",
      "message_count": 2500,
      "profile_picture_url": "https://example.com/profiles/alice.jpg"
    }
  ]
}
```
```

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

### Managing Lessons with session()

Source: https://contextstream.io/docs/mcp

Illustrates how to interact with lessons learned from past mistakes using the `session` tool. This includes capturing new lessons with relevant details (`capture_lesson`) and retrieving existing lessons based on a query (`get_lessons`).

```python
session(action="get_lessons", query="<topic>")
```

```python
session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")
```

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

### Search GitHub by Keyword and Date

Source: https://contextstream.io/docs/integrations/github

This prompt example demonstrates a targeted search on GitHub for a specific keyword ('memory leak') within a defined date range ('last 7 days'). It allows for precise retrieval of relevant information.

```text
Search GitHub for 'memory leak' from the last 7 days
```

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

### Get New Context Since Timestamp

Source: https://contextstream.io/docs/mcp/tools

Retrieves new context that has been added since a specified timestamp. This is useful for tracking changes over time.

```python
session(action="delta", timestamp="2023-10-27T10:00:00Z")
```

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

### Help API - General

Source: https://contextstream.io/docs/mcp/tools

The `help` action in ContextStream IO is a versatile utility function that allows users to retrieve information about available tools, authentication, server version, and more. It is invoked using the `help(action=...)` syntax.

```APIDOC
## `help`

### Description
Utility and help functions for ContextStream IO.

### Method
`help` (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
`help(action="tools", ...)`

### Response
#### Success Response (200)
Details vary based on the `action` parameter.

#### Response Example
(Depends on the action)
```

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

### Get Workspace Summary

Source: https://contextstream.io/docs/mcp/tools

Generates a compact summary of the current workspace or project context. This provides a quick overview of the project's state.

```python
session(action="summary")
```

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

### Search Recent GitHub Pull Requests

Source: https://contextstream.io/docs/integrations/github

This prompt example demonstrates how to find recent pull requests related to a specific topic, like 'authentication'. It aids in tracking development progress and understanding changes in the codebase.

```text
Show me recent PRs related to authentication
```

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

### Slack Integration - Get Recent Activity Feed

Source: https://contextstream.io/docs/integrations/slack

Retrieves a feed of recent activity within Slack. Can be optionally filtered by channel and timeframe.

```APIDOC
## POST /integration/slack/activity

### Description
Get recent activity feed, optionally filtered by channel and timeframe (days param).

### Method
POST

### Endpoint
`/integration/slack/activity`

### Parameters
#### Query Parameters
- **channel** (string) - Optional - Filter activity by a specific channel (e.g., "#general").
- **days** (integer) - Optional - Filter activity within the last N days (default is 7).

### Request Body
```json
{
  "action": "activity",
  "channel": "#announcements",
  "days": 3
}
```

### Response
#### Success Response (200)
- **activity_feed** (array) - An array of recent activity objects.
  - **type** (string) - The type of activity (e.g., "message", "reaction", "thread_reply").
  - **user** (string) - The user associated with the activity.
  - **details** (object) - Specific details about the activity (e.g., message content, reaction emoji).
  - **timestamp** (string) - Timestamp of the activity.

#### Response Example
```json
{
  "activity_feed": [
    {
      "type": "message",
      "user": "user456",
      "details": {"channel": "#announcements", "text": "New policy update is live.", "message_id": "msg_fgh456"},
      "timestamp": "2023-10-27T11:00:00Z"
    }
  ]
}
```
```

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

### Context Retrieval: session_init vs. context_smart

Source: https://contextstream.io/docs/mcp

Explains the difference between session_init, which provides recent chronological context, and context_smart, which performs semantic searches for relevant information. This distinction is crucial for accurate context retrieval in conversational AI.

```text
session_init returns the last ~10 items BY TIME (chronological)
context_smart SEARCHES for items RELEVANT to THIS message (semantic)
```

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

### Workspace Domain Tool

Source: https://contextstream.io/docs/mcp

Manages workspace operations such as listing available workspaces, getting workspace details, associating projects with workspaces, and bootstrapping new workspaces.

```python
workspace(action="list")
```

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

### Get GitHub Integration Status (Python)

Source: https://contextstream.io/docs/mcp

Checks the status of the GitHub integration using the `integration` tool. This allows monitoring the connection and data synchronization with GitHub.

```python
from contextstream import integration

status = integration(provider="github", action="status")

print(status)
```

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

### Session Initialization with Connected Integrations

Source: https://contextstream.io/docs/integrations

This JSON snippet shows the output of `session_init` after connecting integrations. It lists the available connected integrations and provides a sample of recent memory items, each tagged with its source type (e.g., 'github', 'slack', 'notion').

```json
{
  "connected_integrations": ["github", "slack", "notion"],
  "recent_memory": [
    { "source_type": "github", "title": "Auth flow redesign", ... },
    { "source_type": "slack", "title": "Deployment discussion", ... },
    { "source_type": "notion", "title": "API documentation", ... },
    { "source_type": "manual", "title": "User's captured note", ... }
  ]
}
```

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

### Slack Integration - Get High-Engagement Threads

Source: https://contextstream.io/docs/integrations/slack

Retrieves high-engagement discussion threads, sorted by reactions and reply counts. Supports filtering by channel and timeframe.

```APIDOC
## POST /integration/slack/discussions

### Description
Get high-engagement threads sorted by reactions and reply counts. Filter by channel and timeframe (days param).

### Method
POST

### Endpoint
`/integration/slack/discussions`

### Parameters
#### Query Parameters
- **channel** (string) - Optional - Filter results by a specific channel (e.g., "#general").
- **days** (integer) - Optional - Filter results by threads within the last N days (default is 30).

### Request Body
```json
{
  "action": "discussions",
  "channel": "#team-updates",
  "days": 14
}
```

### Response
#### Success Response (200)
- **threads** (array) - An array of thread objects, sorted by engagement.
  - **thread_id** (string) - Unique identifier for the thread.
  - **title** (string) - The title or first message of the thread.
  - **reply_count** (integer) - The number of replies in the thread.
  - **reaction_count** (integer) - The total number of reactions across messages in the thread.
  - **last_message_timestamp** (string) - Timestamp of the last message in the thread.

#### Response Example
```json
{
  "threads": [
    {
      "thread_id": "thread_xyz789",
      "title": "Discussion about the new project roadmap",
      "reply_count": 50,
      "reaction_count": 120,
      "last_message_timestamp": "2023-10-26T15:00:00Z"
    }
  ]
}
```
```

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

### Help Tool

Source: https://contextstream.io/docs/mcp

Access help information about tools, authentication, and rules.

```APIDOC
## Help Tool

### Description
The `help` tool provides access to information regarding available tools, authentication procedures, editor rules, and version details.

### Method
POST

### Endpoint
- `/help` (Implicitly called)

### Parameters
#### Common Parameters
- **action** (string) - Required - The action to perform. Options: `tools`, `auth`, `version`, `editor_rules`, `enable_bundle`.

### Request Example (`tools`)
```json
{
  "action": "tools"
}
```

### Request Example (`editor_rules`)
```json
{
  "action": "editor_rules"
}
```

### Response
#### Success Response (200) for `tools`
- **available_tools** (array) - A list of available tools and their descriptions.

#### Success Response (200) for `editor_rules`
- **rules** (string) - The current editor rules configuration.
```

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

### Search and Graph Workflow Example

Source: https://contextstream.io/docs/graphs

Demonstrates a typical workflow using ContextStream's search and graph query capabilities. The search function identifies relevant targets, and the graph function performs impact analysis on a specified module.

```contextstream
search(mode="hybrid", query="token refresh flow", limit=3)
graph(action="impact", target={ "type": "module", "path": "src/auth.rs" }, max_depth=2)
```

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

### Project Management

Source: https://contextstream.io/docs/mcp

Manages project-level information, including listing projects, getting project details, creating, updating, indexing, and retrieving project statistics or file lists.

```python
project(action="statistics")
```

```python
project(action="files", ...)
```

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

### Context Retrieval: session_init vs context_smart

Source: https://contextstream.io/docs/mcp

Explains the difference between `session_init` and `context_smart`. `session_init` provides recent chronological context, while `context_smart` semantically searches for relevant information, which is crucial for understanding complex queries or historical decisions.