@j0hanz/thinkseq-mcp 1.0.4 → 1.1.0

package/README.md

@@ -1,130 +1,67 @@
-# thinkseq-mcp-server
+# ThinkSeq MCP Server
 
-<img src="docs/logo.png" alt="Filesystem Context MCP Server Logo" width="175">
+<img src="docs/logo.png" alt="ThinkSeq MCP Server Logo" width="175" />
 
-An MCP implementation for advanced reasoning and thinking sequences.
+An MCP server for structured, sequential thinking with revision support.
 
 [![npm version](https://img.shields.io/npm/v/@j0hanz/thinkseq-mcp.svg)](https://www.npmjs.com/package/@j0hanz/thinkseq-mcp)
 
-## One-Click Install
+## 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==)
 
-## ✨ Features
+## Overview
 
-This MCP server provides a powerful `thinkseq` tool that enables AI agents to maintain rigorous thinking sequences.
+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.
 
-| Feature                    | Description                                                                             |
-| :------------------------- | :-------------------------------------------------------------------------------------- |
-| 🧠 **Sequential Thinking** | Break down complex problems into manageable steps with maintained context.              |
-| 🌿 **Branching**           | Explore multiple solution paths simultaneously without losing track of the main thread. |
-| 🔄 **Revision Support**    | Dynamically revise previous thoughts and conclusions based on new insights.             |
-| 🏗️ **Structured Output**   | Returns structured data for better agent-reasoning loops.                               |
-
-## 🎯 When to Use
-
-Use `thinkseq` when the AI agent needs to:
-
-- **Plan complex architectures** before writing code.
-- **Analyze interdependent parameters** or conflicting information.
-- **Debug tricky issues** where initial assumptions might need correction.
-- **Determine feature prioritization** based on multiple constraints.
-- **Structure a "Chain of Thought"** that is visible and reviewable.
-
-## 🚀 Quick Start
-
-The easiest way to use the server is via `npx`:
+## Quick start
 
 ```bash
 npx -y @j0hanz/thinkseq-mcp@latest
 ```
 
-## 📦 Installation
-
-### NPX (Recommended)
+## CLI options
 
-Add this configuration to your MCP client settings:
-
-```json
-{
-  "thinkseq": {
-    "command": "npx",
-    "args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
-  }
-}
+```bash
+thinkseq --max-thoughts 500 --max-memory-mb 100
 ```
 
-### From Source
-
-1. Clone the repository:
-
-   ```bash
-   git clone https://github.com/j0hanz/thinkseq-mcp-server.git
-   cd thinkseq-mcp
-   ```
-
-2. Install dependencies:
-
-   ```bash
-   npm install
-   ```
-
-3. Build the server:
-
-   ```bash
-   npm run build
-   ```
-
-4. Start the server:
-
-   ```bash
-   npm start
-   ```
-
-## ⚙️ Configuration
-
-The server currently does not require environment variables or command-line arguments for basic operation. It runs over stdio by default.
+Available flags:
 
-## 🔧 Tools
+- `--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.
 
-### `thinkseq`
+Defaults and limits:
 
-Structured sequential thinking with branching and revision support.
+- `maxThoughts` default: 500 (cap 10000).
+- `maxMemoryBytes` default: 100 MB (derived from `--max-memory-mb`).
+- `packageReadTimeoutMs` default: 2000 ms.
+- `shutdownTimeoutMs` default: 5000 ms.
 
-| Parameter           | Type    | Required | Default | Description                                                               |
-| :------------------ | :------ | :------- | :------ | :------------------------------------------------------------------------ |
-| `thought`           | string  | ✅       | -       | Your current thinking step.                                               |
-| `thoughtNumber`     | number  | ✅       | -       | Current thought number in sequence (starts at 1).                         |
-| `totalThoughts`     | number  | ✅       | -       | Estimated total thoughts needed (can adjust).                             |
-| `nextThoughtNeeded` | boolean | ✅       | -       | Whether another thought step is needed.                                   |
-| `isRevision`        | boolean | ❌       | -       | Whether this revises previous thinking.                                   |
-| `revisesThought`    | number  | ❌       | -       | Which thought number is being reconsidered.                               |
-| `branchFromThought` | number  | ❌       | -       | Branching point thought number.                                           |
-| `branchId`          | string  | ❌       | -       | Branch identifier.                                                        |
-| `thoughtType`       | string  | ❌       | -       | Type: `analysis`, `hypothesis`, `verification`, `revision`, `conclusion`. |
+## MCP client configuration
 
-**Returns:** A JSON result containing the processed thought data, which helps the agent maintain context.
-
-**Example Input:**
+Add this to your MCP client settings:
 
 ```json
 {
-  "thought": "I need to break down the user's request into smaller tasks.",
-  "thoughtNumber": 1,
-  "totalThoughts": 3,
-  "nextThoughtNeeded": true,
-  "thoughtType": "analysis"
+  "mcpServers": {
+    "thinkseq": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/thinkseq-mcp@latest"]
+    }
+  }
 }
 ```
 
-## 🔌 Client Configuration
-
 <details>
 <summary><b>VS Code</b></summary>
 
-Add to your `mcp.json` (access via command palette: "MCP: Open Settings"):
+Add to your `mcp.json` (command palette: "MCP: Open Settings"):
 
 ```json
 {
@@ -187,7 +124,168 @@ Add to your `~/.codeium/windsurf/mcp_config.json`:
 
 </details>
 
-## 🛠️ Development
+## Tool: `thinkseq`
+
+Record a concise thinking step. Be brief: capture only the essential insight, calculation, or decision-like a minimal draft, not a verbose explanation.
+
+### Input
+
+| Field            | Type   | Required | Description                                                        |
+| :--------------- | :----- | :------: | :----------------------------------------------------------------- |
+| `thought`        | string |   yes    | Current thinking step (1-2000 chars).                              |
+| `totalThoughts`  | number |    no    | Estimated total thoughts (1-25, default: 3).                       |
+| `revisesThought` | number |    no    | Revise a previous thought by number. Original preserved for audit. |
+
+### Output
+
+The tool returns `structuredContent` with an `ok` flag. On success, `result` is populated; on error, `error` is populated.
+
+Envelope fields:
+
+| 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.          |
+
+Result fields:
+
+| 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:
+
+| Field            | Type   | Description                                                            |
+| :--------------- | :----- | :--------------------------------------------------------------------- |
+| `recentThoughts` | array  | Up to the last 5 active thoughts with `number` and `preview`.          |
+| `revisionInfo`   | object | Present when revising: `revises` (number) and `supersedes` (number[]). |
+
+Notes:
+
+- `recentThoughts` previews are truncated to 100 characters.
+- Revisions supersede the target thought and any later active thoughts.
+
+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. |
+
+### Example
+
+**Basic usage:**
+
+Input:
+
+```json
+{
+  "thought": "3 steps: parse -> validate -> transform"
+}
+```
+
+Output (success):
+
+```json
+{
+  "ok": true,
+  "result": {
+    "thoughtNumber": 1,
+    "totalThoughts": 3,
+    "progress": 0.3333333333333333,
+    "isComplete": false,
+    "thoughtHistoryLength": 1,
+    "hasRevisions": false,
+    "activePathLength": 1,
+    "revisableThoughts": [1],
+    "context": {
+      "recentThoughts": [
+        {
+          "number": 1,
+          "preview": "3 steps: parse -> validate -> transform"
+        }
+      ]
+    }
+  }
+}
+```
+
+**Revising a thought:**
+
+If you realize an earlier step was wrong, use `revisesThought` to correct it:
+
+Input:
+
+```json
+{
+  "thought": "Better approach: validate first, then parse",
+  "revisesThought": 1
+}
+```
+
+Output:
+
+```json
+{
+  "ok": true,
+  "result": {
+    "thoughtNumber": 2,
+    "totalThoughts": 3,
+    "progress": 0.6666666666666666,
+    "isComplete": false,
+    "thoughtHistoryLength": 2,
+    "hasRevisions": true,
+    "activePathLength": 1,
+    "revisableThoughts": [2],
+    "context": {
+      "recentThoughts": [
+        {
+          "number": 2,
+          "preview": "Better approach: validate first, then parse"
+        }
+      ],
+      "revisionInfo": {
+        "revises": 1,
+        "supersedes": [1]
+      }
+    }
+  }
+}
+```
+
+## Behavior and validation
+
+- 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.
+
+## Diagnostics
+
+This server publishes events via `node:diagnostics_channel`:
+
+- `thinkseq:tool` for `tool.start` and `tool.end` (includes duration, errors, and request context).
+- `thinkseq:lifecycle` for `lifecycle.started` and `lifecycle.shutdown`.
+- `thinkseq:engine` for internal engine events such as `engine.sequence_gap`.
+
+## Configuration
+
+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.
+
+## Development
 
 ### Prerequisites
 
@@ -195,26 +293,55 @@ Add to your `~/.codeium/windsurf/mcp_config.json`:
 
 ### Scripts
 
-| Command             | Description                                         |
-| :------------------ | :-------------------------------------------------- |
-| `npm run build`     | Compiles TypeScript to `dist/`.                     |
-| `npm run dev`       | Runs the server in watch mode for development.      |
-| `npm run test`      | Runs the test suite.                                |
-| `npm run lint`      | Lints the codebase using ESLint.                    |
-| `npm run inspector` | Launches the MCP Inspector for interactive testing. |
-
-### Project Structure
+| 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
-├── engine.ts       # Core thinking engine logic
-├── index.ts        # Entry point
-├── lib/            # Shared utilities
-├── schemas/        # Zod input/output schemas
-└── tools/          # Tool definitions (thinkseq.ts)
+  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
 ```
 
-## 🤝 Contributing
+## Troubleshooting
+
+- CI workflow references `npm run maintainability` and `npm run duplication`, but these scripts are not defined in `package.json`.
+
+## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome. Please open a pull request with a clear description and include relevant tests.

package/dist/app.d.ts

@@ -1,42 +1,9 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { ThinkingEngine } from './engine.js';
-import type { LifecycleEvent } from './lib/diagnostics.js';
-import type { PackageInfo } from './lib/package.js';
-interface Closeable extends Record<string, unknown> {
-    close?: () => Promise<void> | void;
-}
-interface ProcessLike {
-    on: (event: string, listener: (...args: unknown[]) => void) => void;
-    exit: (code: number) => void;
-}
-type ServerLike = Pick<McpServer, 'connect' | 'registerTool'>;
-type TransportLike = Pick<StdioServerTransport, 'close'>;
-type EngineLike = Pick<ThinkingEngine, 'processThought'>;
-export interface ProcessErrorHandlerDeps {
+import { type ProcessLike, type RunDependencies } from './appConfig.js';
+interface ProcessErrorHandlerDeps {
     processLike?: ProcessLike;
     logError?: (message: string) => void;
     exit?: (code: number) => void;
 }
-interface ShutdownDependencies {
-    processLike?: ProcessLike;
-    server: Closeable;
-    transport: Closeable;
-    publishLifecycleEvent?: (event: LifecycleEvent) => void;
-    now?: () => number;
-}
-export interface RunDependencies {
-    processLike?: ProcessLike;
-    packageReadTimeoutMs?: number;
-    readPackageJson?: (signal?: AbortSignal) => Promise<PackageInfo>;
-    publishLifecycleEvent?: (event: LifecycleEvent) => void;
-    createServer?: (name: string, version: string) => ServerLike;
-    connectServer?: (server: ServerLike) => Promise<TransportLike>;
-    registerTool?: (server: ServerLike, engine: EngineLike) => void;
-    engineFactory?: () => EngineLike;
-    installShutdownHandlers?: (deps: ShutdownDependencies) => void;
-    now?: () => number;
-}
 export declare function installProcessErrorHandlers(deps?: ProcessErrorHandlerDeps): void;
 export declare function run(deps?: RunDependencies): Promise<void>;
 export {};

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAcpD,UAAU,SAAU,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACjD,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACpC;AAED,UAAU,WAAW;IACnB,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,IAAI,CAAC;IACpE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,KAAK,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,SAAS,GAAG,cAAc,CAAC,CAAC;AAC9D,KAAK,aAAa,GAAG,IAAI,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC;AACzD,KAAK,UAAU,GAAG,IAAI,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;AAEzD,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAED,UAAU,oBAAoB;IAC5B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,qBAAqB,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACxD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,eAAe,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACjE,qBAAqB,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACxD,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,UAAU,CAAC;IAC7D,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/D,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IAChE,aAAa,CAAC,EAAE,MAAM,UAAU,CAAC;IACjC,uBAAuB,CAAC,EAAE,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC/D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAID,wBAAgB,2BAA2B,CACzC,IAAI,GAAE,uBAA4B,GACjC,IAAI,CAkBN;AA8ED,wBAAsB,GAAG,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BnE"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAGhB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAGxB,UAAU,uBAAuB;IAC/B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAqBD,wBAAgB,2BAA2B,CACzC,IAAI,GAAE,uBAA4B,GACjC,IAAI,CAQN;AAED,wBAAsB,GAAG,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBnE"}

package/dist/app.js

@@ -1,96 +1,24 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { ThinkingEngine } from './engine.js';
-import { publishLifecycleEvent } from './lib/diagnostics.js';
-import { readSelfPackageJson } from './lib/package.js';
+import { buildShutdownDependencies, resolvePackageIdentity, resolveRunDependencies, } from './appConfig.js';
 import { installInitializationGuards } from './lib/protocolGuards.js';
-import { installStdioInvalidMessageGuards, installStdioParseErrorResponder, } from './lib/stdioGuards.js';
-import { registerThinkSeq } from './tools/thinkseq.js';
-const SERVER_INSTRUCTIONS = 'ThinkSeq is a tool for structured, sequential thinking with branching and revision support.';
-const DEFAULT_PACKAGE_READ_TIMEOUT_MS = 2000;
+const toError = (value) => value instanceof Error ? value : new Error(String(value));
+const createExit = (proc, exit) => exit ?? ((code) => proc.exit(code));
+const createHandlerFor = (logError, exit) => (label) => (value) => {
+    const error = toError(value);
+    logError(`thinkseq: ${label}: ${error.message}`);
+    exit(1);
+};
 export function installProcessErrorHandlers(deps = {}) {
     const proc = deps.processLike ?? process;
     const logError = deps.logError ?? console.error;
-    const exit = deps.exit ??
-        ((code) => {
-            proc.exit(code);
-        });
-    const handlerFor = (label) => (value) => {
-        const error = value instanceof Error ? value : new Error(String(value));
-        logError(`thinkseq: ${label}: ${error.message}`);
-        exit(1);
-    };
+    const exit = createExit(proc, deps.exit);
+    const handlerFor = createHandlerFor(logError, exit);
     proc.on('unhandledRejection', handlerFor('unhandledRejection'));
     proc.on('uncaughtException', handlerFor('uncaughtException'));
 }
-function createServer(name, version) {
-    return new McpServer({ name, version }, {
-        instructions: SERVER_INSTRUCTIONS,
-        capabilities: { logging: {} },
-    });
-}
-async function connectServer(server) {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    installStdioInvalidMessageGuards(transport);
-    installStdioParseErrorResponder(transport);
-    return transport;
-}
-const DEFAULT_RUN_DEPENDENCIES = {
-    processLike: process,
-    packageReadTimeoutMs: DEFAULT_PACKAGE_READ_TIMEOUT_MS,
-    readPackageJson: readSelfPackageJson,
-    publishLifecycleEvent,
-    createServer,
-    connectServer,
-    registerTool: registerThinkSeq,
-    engineFactory: () => new ThinkingEngine(),
-    installShutdownHandlers,
-    now: Date.now,
-};
-async function closeSafely(value) {
-    try {
-        if (typeof value.close === 'function') {
-            await value.close();
-        }
-    }
-    catch {
-        return;
-    }
-}
-function installShutdownHandlers({ processLike, server, transport, publishLifecycleEvent: publishLifecycle, now, }) {
-    const proc = processLike ?? process;
-    const emit = publishLifecycle ?? publishLifecycleEvent;
-    const timestamp = now ?? Date.now;
-    let shuttingDown = false;
-    const shutdown = async (signal) => {
-        if (shuttingDown)
-            return;
-        shuttingDown = true;
-        emit({
-            type: 'lifecycle.shutdown',
-            ts: timestamp(),
-            signal,
-        });
-        await closeSafely(server);
-        await closeSafely(transport);
-        proc.exit(0);
-    };
-    proc.on('SIGTERM', () => {
-        void shutdown('SIGTERM');
-    });
-    proc.on('SIGINT', () => {
-        void shutdown('SIGINT');
-    });
-}
 export async function run(deps = {}) {
-    const resolved = {
-        ...DEFAULT_RUN_DEPENDENCIES,
-        ...deps,
-    };
+    const resolved = resolveRunDependencies(deps);
     const pkg = await resolved.readPackageJson(AbortSignal.timeout(resolved.packageReadTimeoutMs));
-    const name = pkg.name ?? 'thinkseq';
-    const version = pkg.version ?? '0.0.0';
+    const { name, version } = resolvePackageIdentity(pkg);
     resolved.publishLifecycleEvent({
         type: 'lifecycle.started',
         ts: resolved.now(),
@@ -100,12 +28,6 @@ export async function run(deps = {}) {
     resolved.registerTool(server, engine);
     installInitializationGuards(server);
     const transport = await resolved.connectServer(server);
-    resolved.installShutdownHandlers({
-        processLike: resolved.processLike,
-        server,
-        transport,
-        publishLifecycleEvent: resolved.publishLifecycleEvent,
-        now: resolved.now,
-    });
+    resolved.installShutdownHandlers(buildShutdownDependencies(resolved, { server, engine, transport }));
 }
 //# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EAEzB,sBAAsB,EACtB,sBAAsB,GAEvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAUtE,MAAM,OAAO,GAAG,CAAC,KAAc,EAAS,EAAE,CACxC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAE5D,MAAM,UAAU,GAAG,CACjB,IAAiB,EACjB,IAA6B,EACH,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAE3E,MAAM,gBAAgB,GACpB,CAAC,QAAmC,EAAE,IAA4B,EAAE,EAAE,CACtE,CAAC,KAAiB,EAAE,EAAE,CACtB,CAAC,KAAc,EAAQ,EAAE;IACvB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7B,QAAQ,CAAC,aAAa,KAAK,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IACjD,IAAI,CAAC,CAAC,CAAC,CAAC;AACV,CAAC,CAAC;AAEJ,MAAM,UAAU,2BAA2B,CACzC,OAAgC,EAAE;IAElC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC;IACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC;IAChD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,UAAU,GAAG,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAEpD,IAAI,CAAC,EAAE,CAAC,oBAAoB,EAAE,UAAU,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAChE,IAAI,CAAC,EAAE,CAAC,mBAAmB,EAAE,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,OAAwB,EAAE;IAClD,MAAM,QAAQ,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,eAAe,CACxC,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CACnD,CAAC;IACF,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;IAEtD,QAAQ,CAAC,qBAAqB,CAAC;QAC7B,IAAI,EAAE,mBAAmB;QACzB,EAAE,EAAE,QAAQ,CAAC,GAAG,EAAE;KACnB,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,EAAE,CAAC;IACxC,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,2BAA2B,CAAC,MAAM,CAAC,CAAC;IAEpC,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACvD,QAAQ,CAAC,uBAAuB,CAC9B,yBAAyB,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CACnE,CAAC;AACJ,CAAC"}

package/dist/appConfig/runDependencies.d.ts

@@ -0,0 +1,36 @@
+import type { LifecycleEvent } from '../lib/diagnostics.js';
+import type { PackageInfo } from '../lib/package.js';
+import type { ShutdownDependencies } from './shutdown.js';
+import type { EngineLike, ProcessLike, ServerLike, TransportLike } from './types.js';
+export interface RunDependencies {
+    processLike?: ProcessLike;
+    packageReadTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    readPackageJson?: (signal?: AbortSignal) => Promise<PackageInfo>;
+    publishLifecycleEvent?: (event: LifecycleEvent) => void;
+    createServer?: (name: string, version: string) => ServerLike;
+    connectServer?: (server: ServerLike, createTransport?: () => TransportLike) => Promise<TransportLike>;
+    registerTool?: (server: ServerLike, engine: EngineLike) => void;
+    engineFactory?: () => EngineLike;
+    installShutdownHandlers?: (deps: ShutdownDependencies) => void;
+    now?: () => number;
+}
+export interface ResolvedRunDependencies {
+    processLike: ProcessLike;
+    packageReadTimeoutMs: number;
+    shutdownTimeoutMs?: number;
+    readPackageJson: (signal?: AbortSignal) => Promise<PackageInfo>;
+    publishLifecycleEvent: (event: LifecycleEvent) => void;
+    createServer: (name: string, version: string) => ServerLike;
+    connectServer: (server: ServerLike, createTransport?: () => TransportLike) => Promise<TransportLike>;
+    registerTool: (server: ServerLike, engine: EngineLike) => void;
+    engineFactory: () => EngineLike;
+    installShutdownHandlers: (deps: ShutdownDependencies) => void;
+    now: () => number;
+}
+export declare function resolveRunDependencies(deps: RunDependencies): ResolvedRunDependencies;
+export declare function resolvePackageIdentity(pkg: PackageInfo): {
+    name: string;
+    version: string;
+};
+//# sourceMappingURL=runDependencies.d.ts.map

package/dist/appConfig/runDependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runDependencies.d.ts","sourceRoot":"","sources":["../../src/appConfig/runDependencies.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAOrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,UAAU,EACV,aAAa,EACd,MAAM,YAAY,CAAC;AAMpB,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACjE,qBAAqB,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACxD,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,UAAU,CAAC;IAC7D,aAAa,CAAC,EAAE,CACd,MAAM,EAAE,UAAU,EAClB,eAAe,CAAC,EAAE,MAAM,aAAa,KAClC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5B,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IAChE,aAAa,CAAC,EAAE,MAAM,UAAU,CAAC;IACjC,uBAAuB,CAAC,EAAE,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC/D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,WAAW,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAChE,qBAAqB,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACvD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,UAAU,CAAC;IAC5D,aAAa,EAAE,CACb,MAAM,EAAE,UAAU,EAClB,eAAe,CAAC,EAAE,MAAM,aAAa,KAClC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5B,YAAY,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IAC/D,aAAa,EAAE,MAAM,UAAU,CAAC;IAChC,uBAAuB,EAAE,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC9D,GAAG,EAAE,MAAM,MAAM,CAAC;CACnB;AAyED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,eAAe,GACpB,uBAAuB,CAOzB;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,WAAW,GAAG;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAKA"}