@j0hanz/thinkseq-mcp 2.0.0 → 2.2.0

package/README.md

@@ -1,85 +1,92 @@
 # ThinkSeq MCP Server
 
-<img src="docs/logo.png" alt="ThinkSeq MCP Server Logo" width="175" />
+[![npm version](https://img.shields.io/npm/v/@j0hanz/thinkseq-mcp)](https://www.npmjs.com/package/@j0hanz/thinkseq-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24-green)](https://nodejs.org) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9%2B-blue)](https://www.typescriptlang.org) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-%5E1.26-purple)](https://modelcontextprotocol.io)
 
-An MCP server for structured, sequential thinking with revision support.
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0078d7?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22thinkseq%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fthinkseq-mcp%40latest%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22thinkseq%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fthinkseq-mcp%40latest%22%5D%7D)
 
-[![npm version](https://img.shields.io/npm/v/@j0hanz/thinkseq-mcp.svg)](https://www.npmjs.com/package/@j0hanz/thinkseq-mcp)
+A thinking and reasoning engine for the Model Context Protocol (MCP). Enables AI assistants to capture structured, sequential reasoning chains with full revision (destructive rewind) support, session isolation, and progress tracking.
 
-## One-click install
-
-[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=thinkseq&inputs=%5B%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fthinkseq-mcp%40latest%22%5D%7D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=thinkseq&inputs=%5B%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fthinkseq-mcp%40latest%22%5D%7D&quality=insiders)
-
-[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=thinkseq&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovdGhpbmtzZXEtbWNwQGxhdGVzdCJdfQ==)
+---
 
 ## Overview
 
-ThinkSeq exposes a single MCP tool, `thinkseq`, for structured, sequential thinking. The server runs over stdio and stores an in-memory thought history so it can return progress, active-path context, and revision metadata on each call.
+ThinkSeq provides an MCP server that exposes a single `thinkseq` tool for recording concise thinking steps. Each step is stored in-memory within isolated sessions, and the engine supports revising earlier steps — superseding the target and all subsequent active thoughts while preserving the full audit trail. The server communicates exclusively over **stdio** transport.
 
-## Quick start
+---
 
-```bash
-npx -y @j0hanz/thinkseq-mcp@latest
-```
+## Key Features
 
-## CLI options
+- **Sequential thinking steps** — Record atomic reasoning steps (up to 8,000 characters each) in order
+- **Destructive revision (rewind)** — Revise any active thought; the target and all later thoughts are superseded, continuing from the corrected step
+- **Session isolation** — Multiple independent thought histories via session IDs with pinned LRU eviction (default: 50 sessions)
+- **Progress tracking** — Automatic `progress` (0–1) and `isComplete` signals returned with every response
 
-```bash
-thinkseq --max-thoughts 500 --max-memory-mb 100
-```
+---
 
-Available flags:
+## Tech Stack
 
-- `--max-thoughts <number>`: Max thoughts to keep in memory.
-- `--max-memory-mb <number>`: Max memory (MB) for stored thoughts.
-- `--shutdown-timeout-ms <number>`: Graceful shutdown timeout.
-- `--package-read-timeout-ms <number>`: Package.json read timeout.
-- `-h, --help`: Show help.
+| Component       | Technology                               |
+| --------------- | ---------------------------------------- |
+| Runtime         | Node.js ≥ 24                             |
+| Language        | TypeScript 5.9+                          |
+| MCP SDK         | `@modelcontextprotocol/sdk` ^1.26.0      |
+| Validation      | `zod` ^4.3.6                             |
+| Test framework  | Native Node.js Test Runner (`node:test`) |
+| Package manager | npm                                      |
 
-Defaults and limits:
+---
 
-- `maxThoughts` default: 500 (cap 10000).
-- `maxMemoryBytes` default: 100 MB (derived from `--max-memory-mb`).
-- `packageReadTimeoutMs` default: 2000 ms.
-- `shutdownTimeoutMs` default: 5000 ms.
+## Architecture
 
-## MCP client configuration
+1. **CLI** parses arguments (`--max-thoughts`, `--max-memory-mb`, etc.)
+2. **`run()`** resolves dependencies and reads `package.json` for server identity
+3. **McpServer** is created with embedded instructions, the `thinkseq` tool, `internal://instructions` resource, and `get-help` prompt
+4. **StdioServerTransport** connects the server (stdio only)
+5. **Stdio guards** are installed: initialization enforcement, invalid message rejection, parse error responder
+6. **Shutdown handlers** listen for `SIGTERM`/`SIGINT` and gracefully close server, engine, and transport within a configurable timeout
 
-Add this to your MCP client settings:
+---
+
+## Repository Structure
 
-```json
-{
-  "mcpServers": {
-    "thinkseq": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
-    }
-  }
-}
+```
+thinkseq-mcp/
+├── src/
+│   ├── appConfig/        # Environment, run dependencies, shutdown, types
+│   ├── engine/           # Revision logic, thought queries, thought store
+│   ├── lib/              # CLI, context, diagnostics, errors, MCP logging, stdio guards
+│   ├── schemas/          # Zod input/output schemas
+│   ├── tools/            # MCP tool registration (thinkseq)
+│   ├── app.ts            # Core application wiring and lifecycle
+│   ├── engine.ts         # ThinkingEngine class (session management, processing)
+│   ├── engineConfig.ts   # Engine constants and defaults
+│   ├── index.ts          # Entry point (CLI → run)
+│   └── instructions.md   # Server instructions (bundled as resource/prompt)
+├── tests/                # Unit and integration tests
+├── scripts/
+│   └── tasks.mjs         # Custom build/test task runner
+├── assets/
+│   └── logo.svg          # Server icon
+├── package.json
+└── tsconfig.json
 ```
 
-<details>
-<summary><b>VS Code</b></summary>
+---
 
-Add to your `mcp.json` (command palette: "MCP: Open Settings"):
+## Requirements
 
-```json
-{
-  "mcpServers": {
-    "thinkseq": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
-    }
-  }
-}
-```
+- **Node.js** ≥ 24
+- **npm** (included with Node.js)
 
-</details>
+---
 
-<details>
-<summary><b>Claude Desktop</b></summary>
+## Quickstart
 
-Add to your `claude_desktop_config.json`:
+```bash
+npx -y @j0hanz/thinkseq-mcp@latest
+```
+
+Add to your MCP client configuration:
 
 ```json
 {
@@ -92,111 +99,99 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
-</details>
-
-<details>
-<summary><b>Cursor</b></summary>
+---
 
-1. Go to **Cursor Settings** > **General** > **MCP**.
-2. Click **Add New MCP Server**.
-3. Fill in the details:
-   - **Name:** `thinkseq`
-   - **Type:** `command`
-   - **Command:** `npx -y @j0hanz/thinkseq-mcp@latest`
+## Installation
 
-</details>
+### NPX (recommended)
 
-<details>
-<summary><b>Windsurf</b></summary>
+```bash
+npx -y @j0hanz/thinkseq-mcp@latest
+```
 
-Add to your `~/.codeium/windsurf/mcp_config.json`:
+### Global Install
 
-```json
-{
-  "mcpServers": {
-    "thinkseq": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
-    }
-  }
-}
+```bash
+npm install -g @j0hanz/thinkseq-mcp
+thinkseq
 ```
 
-</details>
+### From Source
 
-## Tool: `thinkseq`
+```bash
+git clone https://github.com/j0hanz/thinkseq-mcp-server.git
+cd thinkseq-mcp-server
+npm install
+npm run build
+npm start
+```
 
-Record a concise thinking step. Be brief: capture only the essential insight, calculation, or decision-like a minimal draft, not a verbose explanation.
+---
 
-### Input
+## Configuration
 
-| Field            | Type   | Required | Description                                                        |
-| :--------------- | :----- | :------: | :----------------------------------------------------------------- |
-| `thought`        | string |   yes    | Current thinking step (1-8000 chars).                              |
-| `sessionId`      | string |    no    | Optional session identifier to isolate thought histories.          |
-| `totalThoughts`  | number |    no    | Estimated total thoughts (1-25, default: 3).                       |
-| `revisesThought` | number |    no    | Revise a previous thought by number. Original preserved for audit. |
+### CLI Arguments
 
-### Output
+| Flag                                 | Type   | Description                         |
+| ------------------------------------ | ------ | ----------------------------------- |
+| `--max-thoughts <number>`            | number | Max thoughts to keep in memory      |
+| `--max-memory-mb <number>`           | number | Max memory (MB) for stored thoughts |
+| `--shutdown-timeout-ms <number>`     | number | Graceful shutdown timeout (ms)      |
+| `--package-read-timeout-ms <number>` | number | Package.json read timeout (ms)      |
+| `-h`, `--help`                       | flag   | Show help text                      |
 
-The tool returns `structuredContent` with an `ok` flag. On success, `result` is populated; on error, `error` is populated.
+### Engine Defaults
 
-Envelope fields:
+| Parameter                 | Default  | Max    |
+| ------------------------- | -------- | ------ |
+| Max thoughts per session  | 500      | 10,000 |
+| Max memory                | 100 MB   | —      |
+| Thought overhead estimate | 200 B    | —      |
+| Max sessions (LRU)        | 50       | 10,000 |
+| Default total thoughts    | 3        | 25     |
+| Default shutdown timeout  | 5,000 ms | —      |
+| Package read timeout      | 2,000 ms | —      |
 
-| Field    | Type    | Description                          |
-| :------- | :------ | :----------------------------------- |
-| `ok`     | boolean | `true` on success, `false` on error. |
-| `result` | object  | Present when `ok` is true.           |
-| `error`  | object  | Present when `ok` is false.          |
+### Environment Variables
 
-Result fields:
+| Variable                        | Default | Description                                                                    |
+| ------------------------------- | ------- | ------------------------------------------------------------------------------ |
+| `THINKSEQ_INCLUDE_TEXT_CONTENT` | `true`  | Set to `0`, `false`, `no`, or `off` to omit JSON string content from responses |
 
-| Field                  | Type     | Description                                          |
-| :--------------------- | :------- | :--------------------------------------------------- |
-| `thoughtNumber`        | number   | Auto-incremented thought number.                     |
-| `totalThoughts`        | number   | Effective total thoughts (at least `thoughtNumber`). |
-| `progress`             | number   | `thoughtNumber / totalThoughts` (0 to 1).            |
-| `isComplete`           | boolean  | `true` when `thoughtNumber >= totalThoughts`.        |
-| `thoughtHistoryLength` | number   | Stored thought count after pruning.                  |
-| `hasRevisions`         | boolean  | `true` if any thought has been revised.              |
-| `activePathLength`     | number   | Count of non-superseded thoughts.                    |
-| `revisableThoughts`    | number[] | Thought numbers available for revision.              |
-| `context`              | object   | Recent context summary (see below).                  |
+---
 
-Context fields:
+## Usage
 
-| Field            | Type   | Description                                                             |
-| :--------------- | :----- | :---------------------------------------------------------------------- |
-| `recentThoughts` | array  | Up to the last 5 active thoughts with `stepIndex`, `number`, `preview`. |
-| `revisionInfo`   | object | Present when revising: `revises` (number) and `supersedes` (number[]).  |
+### stdio (default and only transport)
 
-Notes:
+```bash
+# Direct
+npx -y @j0hanz/thinkseq-mcp@latest
 
-- `recentThoughts` previews are truncated to 100 characters.
-- Revisions are a destructive rewind: they supersede the target thought and any later active thoughts in the active chain.
-- `recentThoughts[].stepIndex` is a contiguous 1-based index in the current active chain (useful when thought numbers become non-contiguous after revisions).
+# With options
+npx -y @j0hanz/thinkseq-mcp@latest --max-thoughts 1000 --max-memory-mb 200
+```
 
-Error fields:
+---
 
-| Code                           | Description                                     |
-| :----------------------------- | :---------------------------------------------- |
-| `E_REVISION_TARGET_NOT_FOUND`  | The requested thought number does not exist.    |
-| `E_REVISION_TARGET_SUPERSEDED` | The requested thought was already superseded.   |
-| `E_THINK`                      | Unexpected tool failure while processing input. |
+## MCP Surface
 
-### Example
+### Tools
 
-**Basic usage:**
+#### `thinkseq`
 
-Input:
+Record a concise thinking step. Supports sequential appending and destructive revision of prior steps.
 
-```json
-{
-  "thought": "3 steps: parse -> validate -> transform"
-}
-```
+**Parameters:**
 
-Output (success):
+| Name             | Type   | Required | Default     | Description                                                                |
+| ---------------- | ------ | -------- | ----------- | -------------------------------------------------------------------------- |
+| `thought`        | string | Yes      | —           | Your current thinking step (1–8,000 characters)                            |
+| `sessionId`      | string | No       | `"default"` | Session identifier to isolate thought histories (1–200 chars)              |
+| `totalThoughts`  | number | No       | `3`         | Estimated total thoughts (1–25)                                            |
+| `revisesThought` | number | No       | —           | Revise a previous thought by number (≥ 1). Original is preserved for audit |
+
+**Returns** (structured output):
 
 ```json
 {
@@ -204,18 +199,19 @@ Output (success):
   "result": {
     "thoughtNumber": 1,
     "totalThoughts": 3,
-    "progress": 0.3333333333333333,
+    "progress": 0.333,
     "isComplete": false,
     "thoughtHistoryLength": 1,
     "hasRevisions": false,
     "activePathLength": 1,
     "revisableThoughts": [1],
+    "revisableThoughtsTotal": 1,
     "context": {
       "recentThoughts": [
         {
           "stepIndex": 1,
           "number": 1,
-          "preview": "3 steps: parse -> validate -> transform"
+          "preview": "First step of reasoning..."
         }
       ]
     }
@@ -223,128 +219,225 @@ Output (success):
 }
 ```
 
-**Revising a thought:**
+**Revision example:**
 
-If you realize an earlier step was wrong, use `revisesThought` to correct it:
+```json
+{
+  "thought": "Better approach: use caching instead",
+  "revisesThought": 2
+}
+```
 
-Input:
+Returns additional `revisionInfo` in `context`:
 
 ```json
 {
-  "thought": "Better approach: validate first, then parse",
-  "revisesThought": 1
+  "context": {
+    "recentThoughts": [...],
+    "revisionInfo": {
+      "revises": 2,
+      "supersedes": [2, 3],
+      "supersedesTotal": 2
+    }
+  }
 }
 ```
 
-Output:
+**Error codes:**
+
+| Code                           | Description                                |
+| ------------------------------ | ------------------------------------------ |
+| `E_THINK`                      | General processing error                   |
+| `E_REVISION_MISSING`           | `revisesThought` required but not provided |
+| `E_REVISION_TARGET_NOT_FOUND`  | Target thought number does not exist       |
+| `E_REVISION_TARGET_SUPERSEDED` | Target thought was already superseded      |
+
+### Resources
+
+| URI                       | MIME Type       | Description               |
+| ------------------------- | --------------- | ------------------------- |
+| `internal://instructions` | `text/markdown` | Server usage instructions |
+
+### Prompts
+
+| Name       | Description                            |
+| ---------- | -------------------------------------- |
+| `get-help` | Get usage instructions for this server |
+
+---
+
+## Client Configuration Examples
+
+<details>
+<summary>VS Code / VS Code Insiders</summary>
+
+Add to your VS Code MCP settings (`.vscode/mcp.json` or User Settings):
 
 ```json
 {
-  "ok": true,
-  "result": {
-    "thoughtNumber": 2,
-    "totalThoughts": 3,
-    "progress": 0.6666666666666666,
-    "isComplete": false,
-    "thoughtHistoryLength": 2,
-    "hasRevisions": true,
-    "activePathLength": 1,
-    "revisableThoughts": [2],
-    "context": {
-      "recentThoughts": [
-        {
-          "stepIndex": 1,
-          "number": 2,
-          "preview": "Better approach: validate first, then parse"
-        }
-      ],
-      "revisionInfo": {
-        "revises": 1,
-        "supersedes": [1]
-      }
+  "mcpServers": {
+    "thinkseq": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
     }
   }
 }
 ```
 
-## Behavior and validation
+</details>
 
-- Inputs are validated with Zod and unknown keys are rejected.
-- `thoughtNumber` is auto-incremented (1, 2, 3...).
-- `totalThoughts` defaults to 3, must be in 1-25, and is adjusted up to at least `thoughtNumber`.
-- The engine stores thoughts in memory and prunes when limits are exceeded:
-  - `maxThoughts` default: 500 (cap 10000). When exceeded, prunes the oldest 10% (minimum excess).
-  - `maxMemoryBytes` default: 100 MB. When exceeded and history is large, prunes roughly 20% of history.
-  - `estimatedThoughtOverheadBytes` default: 200.
+<details>
+<summary>Claude Desktop</summary>
 
-## Diagnostics
+Add to `claude_desktop_config.json`:
 
-This server publishes events via `node:diagnostics_channel`:
+```json
+{
+  "mcpServers": {
+    "thinkseq": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
+    }
+  }
+}
+```
 
-- `thinkseq:tool` for `tool.start` and `tool.end` (includes duration, errors, and request context).
-- `thinkseq:lifecycle` for `lifecycle.started` and `lifecycle.shutdown`.
+</details>
 
-## Configuration
+<details>
+<summary>Cursor</summary>
 
-No environment variables or CLI flags are required for basic operation. The server runs over stdio, enforces MCP initialization order, and validates protocol versions. Invalid JSON-RPC message shapes and parse errors are surfaced as JSON-RPC errors on stdio.
+Add to Cursor MCP settings:
 
-## Development
+```json
+{
+  "mcpServers": {
+    "thinkseq": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
+    }
+  }
+}
+```
 
-### Prerequisites
+Or use the deeplink:
 
-- Node.js >= 20.0.0
+```
+cursor://anysphere.cursor-deeplink/mcp/install?name=thinkseq&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovdGhpbmtzZXEtbWNwQGxhdGVzdCJdfQ==
+```
 
-### Scripts
+</details>
+
+<details>
+<summary>Windsurf</summary>
 
-| Command                  | Description                      |
-| :----------------------- | :------------------------------- |
-| `npm run build`          | Compile TypeScript to `dist/`.   |
-| `npm run dev`            | Run the server in watch mode.    |
-| `npm start`              | Run `dist/index.js`.             |
-| `npm run test`           | Run the test suite.              |
-| `npm run test:ci`        | Build, then run the test suite.  |
-| `npm run test:coverage`  | Run tests with coverage output.  |
-| `npm run lint`           | Lint with ESLint.                |
-| `npm run format`         | Format with Prettier.            |
-| `npm run format:check`   | Check formatting with Prettier.  |
-| `npm run type-check`     | Type-check without emitting.     |
-| `npm run inspector`      | Launch the MCP inspector.        |
-| `npm run clean`          | Remove `dist/`.                  |
-| `npm run prepublishOnly` | Lint, type-check, and build.     |
-| `npm run benchmark`      | Run `benchmark/engine.bench.ts`. |
-
-Benchmark environment variables:
-
-- `THINKSEQ_BENCH_SAMPLES` (default: 1)
-- `THINKSEQ_BENCH_NEW_ITERATIONS` (default: 10000)
-- `THINKSEQ_BENCH_REV_ITERATIONS` (default: 1000)
-- `THINKSEQ_BENCH_WARMUP` (default: 1000)
-- `THINKSEQ_BENCH_PIN` (optional CPU affinity mask)
-
-### Project structure
-
-```text
-src/
-  app.ts           # Application setup and MCP wiring
-  appConfig.ts     # Dependency wiring and shutdown handling
-  engine.ts        # Core thinking engine
-  engineConfig.ts  # Defaults and limits
-  engine/          # Revision and query helpers
-  lib/             # CLI, diagnostics, errors, protocol, stdio utilities
-  schemas/         # Zod input/output schemas
-  tools/           # MCP tool definitions (thinkseq)
-tests/             # Node.js tests
-benchmark/         # Benchmark targets
-docs/              # Assets (logo)
-dist/              # Build output
-scripts/           # Quality gates and metrics helpers
-metrics/           # Generated metrics outputs
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "thinkseq": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
+    }
+  }
+}
+```
+
+</details>
+
+---
+
+## Security
+
+### stdio Transport
+
+- **stdout protection:** `console.log` and `console.warn` are bridged to MCP logging messages to prevent polluting the JSON-RPC stdio channel.
+- **Initialization enforcement:** The server rejects any request before a valid `initialize` handshake and requires `notifications/initialized` before accepting tool calls.
+- **Invalid message rejection:** Non-object and batch JSON-RPC messages are rejected with proper error codes.
+- **Parse error handling:** Malformed JSON on stdin receives a JSON-RPC Parse Error response.
+
+### Process Safety
+
+- Unhandled rejections and uncaught exceptions are caught and result in a clean process exit.
+- Graceful shutdown on `SIGTERM`/`SIGINT` with configurable timeout (default: 5 seconds).
+
+---
+
+## Development Workflow
+
+### Install Dependencies
+
+```bash
+npm install
 ```
 
+### Scripts
+
+| Script          | Command                                      | Purpose                                                           |
+| --------------- | -------------------------------------------- | ----------------------------------------------------------------- |
+| `dev`           | `tsc --watch --preserveWatchOutput`          | Watch mode TypeScript compilation                                 |
+| `dev:run`       | `node --env-file=.env --watch dist/index.js` | Run built server with auto-reload                                 |
+| `build`         | `node scripts/tasks.mjs build`               | Full build pipeline (clean → compile → validate → assets → chmod) |
+| `start`         | `node dist/index.js`                         | Run the built server                                              |
+| `test`          | `node scripts/tasks.mjs test`                | Run all tests (builds first)                                      |
+| `test:coverage` | `node scripts/tasks.mjs test --coverage`     | Run tests with coverage                                           |
+| `type-check`    | `node scripts/tasks.mjs type-check`          | TypeScript type checking                                          |
+| `lint`          | `eslint .`                                   | Run ESLint                                                        |
+| `lint:fix`      | `eslint . --fix`                             | Auto-fix lint issues                                              |
+| `format`        | `prettier --write .`                         | Format code with Prettier                                         |
+| `clean`         | `node scripts/tasks.mjs clean`               | Remove dist and build info files                                  |
+| `inspector`     | `npx @modelcontextprotocol/inspector`        | Launch MCP Inspector for debugging                                |
+| `knip`          | `knip`                                       | Detect unused exports/dependencies                                |
+
+---
+
+## Build and Release
+
+The build pipeline (`npm run build`) executes:
+
+1. **Clean** — Remove `dist/` and `.tsbuildinfo` files
+2. **Compile** — TypeScript compilation via `tsconfig.build.json`
+3. **Validate** — Ensure `src/instructions.md` exists
+4. **Copy assets** — Bundle `instructions.md` and `assets/` (including `logo.svg`) into `dist/`
+5. **Make executable** — Set `dist/index.js` to mode `755`
+
+### Publishing
+
+Publishing is automated via GitHub Actions (`.github/workflows/publish.yml`):
+
+- Triggered on GitHub release publication
+- Pipeline: lint → type-check → test → coverage → build → `npm publish --access public`
+- Uses npm Trusted Publishing (OIDC) for authentication
+
+---
+
 ## Troubleshooting
 
-- CI workflow references `npm run maintainability` and `npm run duplication`, but these scripts are not defined in `package.json`.
+### MCP Inspector
+
+Use the MCP Inspector to debug and test the server interactively:
+
+```bash
+npx @modelcontextprotocol/inspector
+```
+
+### Common Issues
+
+| Issue                                              | Solution                                                                                             |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Server not responding                              | Ensure Node.js ≥ 24 is installed; check `node --version`                                             |
+| `initialize must be first request`                 | Client must send `initialize` before any other request                                               |
+| `notifications/initialized must follow initialize` | Client must send `notifications/initialized` after successful `initialize`                           |
+| Thoughts disappearing                              | Check `--max-thoughts` and `--max-memory-mb` limits; old thoughts are pruned when limits are reached |
+| Session not found                                  | Sessions are in-memory only; they reset on server restart. Max 50 sessions by default (LRU eviction) |
+
+### stdout/stderr Guidance
+
+When running as a stdio MCP server, **never write directly to stdout** from custom code — this would corrupt the JSON-RPC protocol. The server automatically bridges `console.log`/`console.warn` to MCP logging. Use `console.error` for debug output that bypasses MCP.
+
+---
 
-## Contributing
+## License
 
-Contributions are welcome. Please open a pull request with a clear description and include relevant tests.
+[MIT](https://opensource.org/licenses/MIT)