@j0hanz/cortex-mcp 0.1.2 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # Cortex MCP
 
-[![npm version](https://img.shields.io/npm/v/cortex-mcp?style=flat-square)](https://www.npmjs.com/package/cortex-mcp) [![Generic badge](https://img.shields.io/badge/Node.js->=24-3c873a?style=flat-square)](https://nodejs.org) [![Generic badge](https://img.shields.io/badge/TypeScript-5.9+-3178c6?style=flat-square)](https://www.typescriptlang.org) [![Generic badge](https://img.shields.io/badge/MCP_SDK-1.26+-ff6600?style=flat-square)](https://modelcontextprotocol.io) [![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/@j0hanz/cortex-mcp?style=flat-square)](https://www.npmjs.com/package/@j0hanz/cortex-mcp) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/j0hanz/cortex-mcp/pkgs/container/cortex-mcp) [![Generic badge](https://img.shields.io/badge/Node.js->=24-3c873a?style=flat-square)](https://nodejs.org) [![Generic badge](https://img.shields.io/badge/TypeScript-5.9+-3178c6?style=flat-square)](https://www.typescriptlang.org) [![Generic badge](https://img.shields.io/badge/MCP_SDK-1.26+-ff6600?style=flat-square)](https://modelcontextprotocol.io) [![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
 
 [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?config=%7B%22name%22%3A%22cortex-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22cortex-mcp%40latest%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode-insiders:mcp/install?config=%7B%22name%22%3A%22cortex-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22cortex-mcp%40latest%22%5D%7D) [![Install in Cursor](https://img.shields.io/badge/Cursor-Install-000000?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=cortex-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvcnRleC1tY3BAbGF0ZXN0Il19)
 
@@ -74,6 +74,13 @@ npx -y cortex-mcp@latest
 npx -y cortex-mcp@latest
 ```
 
+### Docker
+
+```bash
+docker pull ghcr.io/j0hanz/cortex-mcp:latest
+docker run --rm -i ghcr.io/j0hanz/cortex-mcp:latest
+```
+
 ### From Source
 
 ```bash
@@ -226,6 +233,22 @@ Add to your Cursor MCP settings:
 
 </details>
 
+<details>
+<summary><strong>Docker</strong></summary>
+
+```json
+{
+  "mcpServers": {
+    "cortex-mcp": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i", "ghcr.io/j0hanz/cortex-mcp:latest"]
+    }
+  }
+}
+```
+
+</details>
+
 ## Security
 
 - **Stdio Isolation**: The server writes all logs to `stderr` to avoid corrupting the JSON-RPC stream on `stdout`.
@@ -258,6 +281,75 @@ The project uses a custom task runner (`scripts/tasks.mjs`) for build orchestrat
 - **Build**: `npm run build` generates artifacts in `dist/`.
 - **Publish**: `npm run prepublishOnly` ensures linting, type-checking, and building before publish.
 
+### Automated Releases
+
+Releases are fully automated via a single GitHub Actions workflow (`release.yml`). No manual version edits are needed.
+
+**Trigger a release:**
+
+```bash
+# Via GitHub CLI
+gh workflow run release.yml -f bump=patch   # or minor / major
+
+# Custom pre-release version
+gh workflow run release.yml -f custom_version=2.0.0-beta.1
+```
+
+Or use the GitHub UI: **Actions** → **Release** → **Run workflow** → select bump type.
+
+**What the workflow does:**
+
+```text
+workflow_dispatch (patch/minor/major)
+    │
+    ▼
+  release ── bump versions → validate → commit → tag → GitHub Release
+    │
+    ├──► publish-npm ──► publish-mcp  (sequential: MCP Registry needs npm package)
+    │
+    └──► publish-docker              (parallel with npm)
+```
+
+1. **Bump** — Updates `package.json`, `package-lock.json`, and `server.json` atomically
+2. **Validate** — Runs lint, type-check, tests, and build
+3. **Tag & Release** — Commits, creates a git tag, and a GitHub Release with auto-generated notes
+4. **Publish to npm** — Uses OIDC Trusted Publishing (no `NPM_TOKEN` secret needed), with `--provenance` for signed SLSA attestations
+5. **Publish to MCP Registry** — Registers the new version via `mcp-publisher` with GitHub OIDC
+6. **Publish to Docker** — Builds and pushes a multi-platform image (`linux/amd64`, `linux/arm64`) to `ghcr.io/j0hanz/cortex-mcp`
+
+### Docker Image
+
+The project includes a multi-stage `Dockerfile` optimized for MCP servers:
+
+- **Builder stage**: Installs dependencies with `--ignore-scripts` (avoids `prepare` running before source is copied), rebuilds native modules, compiles TypeScript, then prunes dev dependencies
+- **Release stage**: Minimal `node:24-alpine` image running as non-root `mcp` user
+
+```bash
+# Build locally
+docker build -t cortex-mcp .
+
+# Run locally
+docker run --rm -i cortex-mcp
+
+# Or use docker-compose
+docker compose up --build
+```
+
+### Verify a release
+
+```bash
+# npm
+npm view @j0hanz/cortex-mcp dist-tags
+
+# Docker
+docker pull ghcr.io/j0hanz/cortex-mcp:latest
+
+# MCP protocol handshake
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
+  | npx -y @j0hanz/cortex-mcp@latest 2>/dev/null \
+  | head -1 | jq .result.serverInfo
+```
+
 ## Troubleshooting
 
 - **No output**: The server uses `stdio`. Ensure your client is capturing `stdout` correctly. Check `stderr` for logs.

package/dist/assets/logo.svg

@@ -1,49 +1,49 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke-width="1.2" stroke-linecap="round"
-    stroke-linejoin="round" role="img" aria-label="brain">
-    <style>
-        path,
-        circle,
-        rect,
-        line,
-        polyline,
-        polygon {
-            stroke: #000000;
-        }
-
-        @media (prefers-color-scheme: dark) {
-
-            path,
-            circle,
-            rect,
-            line,
-            polyline,
-            polygon {
-                stroke: #FFFFFF;
-            }
-        }
-    </style>
-
-    <g>
-        <!-- Outer silhouette -->
-        <path d="M9 4.2c-2.2 0-4 1.7-4 4v1.1c-1 .6-1.7 1.7-1.7 3 0 1.6 1 2.9 2.4 3.3v.9c0 2.2 1.8 4 4 4h2.3" />
-        <path d="M15 4.2c2.2 0 4 1.7 4 4v1.1c1 .6 1.7 1.7 1.7 3 0 1.6-1 2.9-2.4 3.3v.9c0 2.2-1.8 4-4 4H12" />
-
-        ```
-        <!-- Midline split (subtle) -->
-        <path d="M12 5.1v15.1" />
-
-        <!-- Left hemisphere folds -->
-        <path d="M8.8 7c-1.2.1-2.2 1.1-2.2 2.4" />
-        <path d="M9.3 10.1c-1.4 0-2.6 1.1-2.6 2.6" />
-        <path d="M9.6 13.4c-1.2.2-2.1 1.2-2.1 2.5" />
-        <path d="M10.3 16.4c-1.1 0-2 .7-2.4 1.7" />
-
-        <!-- Right hemisphere folds -->
-        <path d="M15.2 7c1.2.1 2.2 1.1 2.2 2.4" />
-        <path d="M14.7 10.1c1.4 0 2.6 1.1 2.6 2.6" />
-        <path d="M14.4 13.4c1.2.2 2.1 1.2 2.1 2.5" />
-        <path d="M13.7 16.4c1.1 0 2 .7 2.4 1.7" />
-        ```
-
-    </g>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke-width="1.2" stroke-linecap="round"
+    stroke-linejoin="round" role="img" aria-label="brain">
+    <style>
+        path,
+        circle,
+        rect,
+        line,
+        polyline,
+        polygon {
+            stroke: #000000;
+        }
+
+        @media (prefers-color-scheme: dark) {
+
+            path,
+            circle,
+            rect,
+            line,
+            polyline,
+            polygon {
+                stroke: #FFFFFF;
+            }
+        }
+    </style>
+
+    <g>
+        <!-- Outer silhouette -->
+        <path d="M9 4.2c-2.2 0-4 1.7-4 4v1.1c-1 .6-1.7 1.7-1.7 3 0 1.6 1 2.9 2.4 3.3v.9c0 2.2 1.8 4 4 4h2.3" />
+        <path d="M15 4.2c2.2 0 4 1.7 4 4v1.1c1 .6 1.7 1.7 1.7 3 0 1.6-1 2.9-2.4 3.3v.9c0 2.2-1.8 4-4 4H12" />
+
+        ```
+        <!-- Midline split (subtle) -->
+        <path d="M12 5.1v15.1" />
+
+        <!-- Left hemisphere folds -->
+        <path d="M8.8 7c-1.2.1-2.2 1.1-2.2 2.4" />
+        <path d="M9.3 10.1c-1.4 0-2.6 1.1-2.6 2.6" />
+        <path d="M9.6 13.4c-1.2.2-2.1 1.2-2.1 2.5" />
+        <path d="M10.3 16.4c-1.1 0-2 .7-2.4 1.7" />
+
+        <!-- Right hemisphere folds -->
+        <path d="M15.2 7c1.2.1 2.2 1.1 2.2 2.4" />
+        <path d="M14.7 10.1c1.4 0 2.6 1.1 2.6 2.6" />
+        <path d="M14.4 13.4c1.2.2 2.1 1.2 2.1 2.5" />
+        <path d="M13.7 16.4c1.1 0 2 .7 2.4 1.7" />
+        ```
+
+    </g>
 </svg>

package/dist/instructions.md

@@ -1,131 +1,131 @@
-# CORTEX-MCP INSTRUCTIONS
-
-These instructions are available as a resource (internal://instructions) or prompt (get-help). Load them when unsure about tool usage.
-
----
-
-## CORE CAPABILITY
-
-- Domain: Multi-level reasoning engine that decomposes queries into structured thought chains at configurable depth levels (basic, normal, high).
-- Primary Resources: Reasoning sessions (in-memory, 30-minute TTL), thought chains, progress notifications.
-- Tools: `reasoning.think` (WRITE — creates/extends sessions with generated thoughts).
-
----
-
-## PROMPTS
-
-- `get-help`: Returns these instructions for quick recall.
-- `reasoning.basic`: Prepare a basic-depth reasoning request (3–5 thoughts).
-- `reasoning.normal`: Prepare a normal-depth reasoning request (6–10 thoughts).
-- `reasoning.high`: Prepare a high-depth reasoning request (15–25 thoughts).
-- `reasoning.continue`: Continue an existing reasoning session with a follow-up query.
-
----
-
-## RESOURCES & RESOURCE LINKS
-
-- `internal://instructions`: This document.
-- `reasoning://sessions`: List all active reasoning sessions with metadata (JSON).
-- `reasoning://sessions/{sessionId}`: Inspect a specific session's thoughts and metadata (JSON). Supports auto-completion on `sessionId`.
-
-### Resource Subscriptions
-
-- The server supports `resources/subscribe` for real-time change notifications on individual resources.
-- Subscribe to `reasoning://sessions/{sessionId}` to receive `notifications/resources/updated` when thoughts are added or revised.
-- Use subscriptions to monitor session progress without polling.
-
----
-
-## PROGRESS & TASKS
-
-- Include `_meta.progressToken` in requests to receive `notifications/progress` updates during reasoning.
-- Task-augmented tool calls are supported for `reasoning.think`:
-  - `execution.taskSupport: "optional"` — invoke normally or as a task.
-  - Send `tools/call` with `task` to get a task id.
-  - Poll `tasks/get` and fetch results via `tasks/result`.
-  - Use `tasks/cancel` to abort a running task.
-  - For `high` level, progress is emitted every 2 steps to reduce noise; `basic` and `normal` emit after every step.
-
----
-
-## THE "GOLDEN PATH" WORKFLOWS (CRITICAL)
-
-### WORKFLOW A: Sequential Reasoning
-
-1. Call `reasoning.think` with `{ query: "...", level: "basic" | "normal" | "high" }`.
-2. Read `result.thoughts` for the accumulated reasoning chain (each call appends at most one new thought).
-3. Repeat calls with the same `sessionId` until `result.totalThoughts` is reached.
-   NOTE: Choose level based on query complexity — `basic` for straightforward questions, `high` for multi-faceted analysis.
-
-### WORKFLOW B: Multi-Turn Reasoning (Session Continuation)
-
-1. Call `reasoning.think` with `{ query: "initial question", level: "normal" }` — note the returned `sessionId`.
-2. Call `reasoning.think` with `{ query: "follow-up", level: "normal", sessionId: "<id>" }` to append the next thought.
-3. Repeat until `result.totalThoughts` is reached, then read `reasoning://sessions/{sessionId}` for the full chain.
-   NOTE: The `level` MUST match the original session level. Mismatches return `E_SESSION_LEVEL_MISMATCH`.
-
-### WORKFLOW C: Controlled Depth Reasoning
-
-1. Call `reasoning.think` with `{ query: "...", level: "normal", targetThoughts: 8 }` to set the session's planned step count.
-2. Repeat calls with the returned `sessionId` until `result.totalThoughts` is reached.
-   NOTE: `targetThoughts` must fall within the level range (basic: 3–5, normal: 6–10, high: 15–25). Out-of-range values return `E_INVALID_THOUGHT_COUNT`.
-
-### WORKFLOW D: Async Task Execution
-
-1. Call `reasoning.think` as a task (send `tools/call` with `task` field) for long-running `high`-level reasoning.
-2. Poll `tasks/get` until status is `completed` or `failed`.
-3. Retrieve the result via `tasks/result`.
-4. Use `tasks/cancel` to abort if needed.
-
----
-
-## TOOL NUANCES & GOTCHAS
-
-`reasoning.think`
-
-- Purpose: Generate a multi-step reasoning chain for a given query at a specified depth level.
-- Input:
-  - `query` (string, 1–10,000 chars): The question or problem to reason about.
-  - `level` (enum: `basic` | `normal` | `high`): Controls reasoning depth and token budget.
-  - `targetThoughts` (int, 1–25, optional): Override automatic step count. Must fit within the level range.
-  - `sessionId` (string, 1–128 chars, optional): Continue an existing session. Level must match.
-- Output: `{ ok, result: { sessionId, level, thoughts[], generatedThoughts, requestedThoughts, totalThoughts, tokenBudget, tokensUsed, ttlMs, expiresAt, createdAt, updatedAt, summary } }`
-- Side effects: Creates or modifies an in-memory session. Sessions expire after 30 minutes of inactivity.
-- Gotcha: Each call appends at most one thought. When continuing a session, `generatedThoughts` reflects only the newly added thought (0 or 1), not the cumulative total.
-- Gotcha: `requestedThoughts` is the effective requested count for this run: it equals `targetThoughts` when provided, otherwise `totalThoughts`.
-- Gotcha: Token counting is approximate (UTF-8 byte length ÷ 4), not true tokenization.
-- Gotcha: Without `targetThoughts`, the planned step count (`totalThoughts`) is determined by a heuristic based on query length and structural complexity (punctuation markers, keywords like "compare", "analyse", "trade-off").
-- Limits: Level ranges — basic: 3–5 thoughts (2K token budget), normal: 6–10 (8K), high: 15–25 (32K).
-
----
-
-## CROSS-FEATURE RELATIONSHIPS
-
-- Use `reasoning.basic` / `reasoning.normal` / `reasoning.high` prompts to construct a correctly parameterized `reasoning.think` call.
-- Use `reasoning.continue` prompt to construct a session-continuation call — it enforces `sessionId` and `level` pairing.
-- After calling `reasoning.think`, read `reasoning://sessions/{sessionId}` to retrieve the full session state including all accumulated thoughts.
-- Use `reasoning://sessions` to discover active sessions before attempting continuation — avoids `E_SESSION_NOT_FOUND`.
-
----
-
-## CONSTRAINTS & LIMITATIONS
-
-- Sessions are in-memory — all data is lost on process restart.
-- Session TTL: 30 minutes from last update. Expired sessions cannot be recovered.
-- Maximum query length: 10,000 characters.
-- Token budget enforcement is approximate (character-based proxy, not true tokenization).
-- stdio transport only — no HTTP endpoint available.
-- Reasoning steps are structural decompositions, not LLM-generated content.
-- `targetThoughts` must be an integer within the level's min/max range.
-
----
-
-## ERROR HANDLING STRATEGY
-
-- `E_SESSION_NOT_FOUND`: Session expired or never existed. Call `reasoning://sessions` to list active sessions, or start a new session without `sessionId`.
-- `E_SESSION_LEVEL_MISMATCH`: Requested level differs from the existing session. Use the same level as the original session, or start a new session.
-- `E_INVALID_THOUGHT_COUNT`: `targetThoughts` is outside the level range. Check ranges: basic (3–5), normal (6–10), high (15–25).
-- `E_ABORTED`: Reasoning was cancelled via abort signal or task cancellation. Retry with a new request if needed.
-- `E_REASONING`: Unexpected engine error. Check the error `message` field for details and retry.
-
----
+# CORTEX-MCP INSTRUCTIONS
+
+These instructions are available as a resource (internal://instructions) or prompt (get-help). Load them when unsure about tool usage.
+
+---
+
+## CORE CAPABILITY
+
+- Domain: Multi-level reasoning engine that decomposes queries into structured thought chains at configurable depth levels (basic, normal, high).
+- Primary Resources: Reasoning sessions (in-memory, 30-minute TTL), thought chains, progress notifications.
+- Tools: `reasoning.think` (WRITE — creates/extends sessions with generated thoughts).
+
+---
+
+## PROMPTS
+
+- `get-help`: Returns these instructions for quick recall.
+- `reasoning.basic`: Prepare a basic-depth reasoning request (3–5 thoughts).
+- `reasoning.normal`: Prepare a normal-depth reasoning request (6–10 thoughts).
+- `reasoning.high`: Prepare a high-depth reasoning request (15–25 thoughts).
+- `reasoning.continue`: Continue an existing reasoning session with a follow-up query.
+
+---
+
+## RESOURCES & RESOURCE LINKS
+
+- `internal://instructions`: This document.
+- `reasoning://sessions`: List all active reasoning sessions with metadata (JSON).
+- `reasoning://sessions/{sessionId}`: Inspect a specific session's thoughts and metadata (JSON). Supports auto-completion on `sessionId`.
+
+### Resource Subscriptions
+
+- The server supports `resources/subscribe` for real-time change notifications on individual resources.
+- Subscribe to `reasoning://sessions/{sessionId}` to receive `notifications/resources/updated` when thoughts are added or revised.
+- Use subscriptions to monitor session progress without polling.
+
+---
+
+## PROGRESS & TASKS
+
+- Include `_meta.progressToken` in requests to receive `notifications/progress` updates during reasoning.
+- Task-augmented tool calls are supported for `reasoning.think`:
+  - `execution.taskSupport: "optional"` — invoke normally or as a task.
+  - Send `tools/call` with `task` to get a task id.
+  - Poll `tasks/get` and fetch results via `tasks/result`.
+  - Use `tasks/cancel` to abort a running task.
+  - For `high` level, progress is emitted every 2 steps to reduce noise; `basic` and `normal` emit after every step.
+
+---
+
+## THE "GOLDEN PATH" WORKFLOWS (CRITICAL)
+
+### WORKFLOW A: Sequential Reasoning
+
+1. Call `reasoning.think` with `{ query: "...", level: "basic" | "normal" | "high" }`.
+2. Read `result.thoughts` for the accumulated reasoning chain (each call appends at most one new thought).
+3. Repeat calls with the same `sessionId` until `result.totalThoughts` is reached.
+   NOTE: Choose level based on query complexity — `basic` for straightforward questions, `high` for multi-faceted analysis.
+
+### WORKFLOW B: Multi-Turn Reasoning (Session Continuation)
+
+1. Call `reasoning.think` with `{ query: "initial question", level: "normal" }` — note the returned `sessionId`.
+2. Call `reasoning.think` with `{ query: "follow-up", level: "normal", sessionId: "<id>" }` to append the next thought.
+3. Repeat until `result.totalThoughts` is reached, then read `reasoning://sessions/{sessionId}` for the full chain.
+   NOTE: The `level` MUST match the original session level. Mismatches return `E_SESSION_LEVEL_MISMATCH`.
+
+### WORKFLOW C: Controlled Depth Reasoning
+
+1. Call `reasoning.think` with `{ query: "...", level: "normal", targetThoughts: 8 }` to set the session's planned step count.
+2. Repeat calls with the returned `sessionId` until `result.totalThoughts` is reached.
+   NOTE: `targetThoughts` must fall within the level range (basic: 3–5, normal: 6–10, high: 15–25). Out-of-range values return `E_INVALID_THOUGHT_COUNT`.
+
+### WORKFLOW D: Async Task Execution
+
+1. Call `reasoning.think` as a task (send `tools/call` with `task` field) for long-running `high`-level reasoning.
+2. Poll `tasks/get` until status is `completed` or `failed`.
+3. Retrieve the result via `tasks/result`.
+4. Use `tasks/cancel` to abort if needed.
+
+---
+
+## TOOL NUANCES & GOTCHAS
+
+`reasoning.think`
+
+- Purpose: Generate a multi-step reasoning chain for a given query at a specified depth level.
+- Input:
+  - `query` (string, 1–10,000 chars): The question or problem to reason about.
+  - `level` (enum: `basic` | `normal` | `high`): Controls reasoning depth and token budget.
+  - `targetThoughts` (int, 1–25, optional): Override automatic step count. Must fit within the level range.
+  - `sessionId` (string, 1–128 chars, optional): Continue an existing session. Level must match.
+- Output: `{ ok, result: { sessionId, level, thoughts[], generatedThoughts, requestedThoughts, totalThoughts, tokenBudget, tokensUsed, ttlMs, expiresAt, createdAt, updatedAt, summary } }`
+- Side effects: Creates or modifies an in-memory session. Sessions expire after 30 minutes of inactivity.
+- Gotcha: Each call appends at most one thought. When continuing a session, `generatedThoughts` reflects only the newly added thought (0 or 1), not the cumulative total.
+- Gotcha: `requestedThoughts` is the effective requested count for this run: it equals `targetThoughts` when provided, otherwise `totalThoughts`.
+- Gotcha: Token counting is approximate (UTF-8 byte length ÷ 4), not true tokenization.
+- Gotcha: Without `targetThoughts`, the planned step count (`totalThoughts`) is determined by a heuristic based on query length and structural complexity (punctuation markers, keywords like "compare", "analyse", "trade-off").
+- Limits: Level ranges — basic: 3–5 thoughts (2K token budget), normal: 6–10 (8K), high: 15–25 (32K).
+
+---
+
+## CROSS-FEATURE RELATIONSHIPS
+
+- Use `reasoning.basic` / `reasoning.normal` / `reasoning.high` prompts to construct a correctly parameterized `reasoning.think` call.
+- Use `reasoning.continue` prompt to construct a session-continuation call — it enforces `sessionId` and `level` pairing.
+- After calling `reasoning.think`, read `reasoning://sessions/{sessionId}` to retrieve the full session state including all accumulated thoughts.
+- Use `reasoning://sessions` to discover active sessions before attempting continuation — avoids `E_SESSION_NOT_FOUND`.
+
+---
+
+## CONSTRAINTS & LIMITATIONS
+
+- Sessions are in-memory — all data is lost on process restart.
+- Session TTL: 30 minutes from last update. Expired sessions cannot be recovered.
+- Maximum query length: 10,000 characters.
+- Token budget enforcement is approximate (character-based proxy, not true tokenization).
+- stdio transport only — no HTTP endpoint available.
+- Reasoning steps are structural decompositions, not LLM-generated content.
+- `targetThoughts` must be an integer within the level's min/max range.
+
+---
+
+## ERROR HANDLING STRATEGY
+
+- `E_SESSION_NOT_FOUND`: Session expired or never existed. Call `reasoning://sessions` to list active sessions, or start a new session without `sessionId`.
+- `E_SESSION_LEVEL_MISMATCH`: Requested level differs from the existing session. Use the same level as the original session, or start a new session.
+- `E_INVALID_THOUGHT_COUNT`: `targetThoughts` is outside the level range. Check ranges: basic (3–5), normal (6–10), high (15–25).
+- `E_ABORTED`: Reasoning was cancelled via abort signal or task cancellation. Retry with a new request if needed.
+- `E_REASONING`: Unexpected engine error. Check the error `message` field for details and retry.
+
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/cortex-mcp",
-  "version": "0.1.2",
+  "version": "1.0.0",
   "mcpName": "io.github.j0hanz/cortex-mcp",
   "author": "Johanz",
   "license": "MIT",