@nones/dsh-session-mcp 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZeiZel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+# @nones/dsh-session-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP (Model Context Protocol) server for **DeepSeek Harness sessions** — lets Claude Code,
+Claude Desktop, Codex, Cursor and any other MCP client list, read and prompt the
+conversations running in your harness.
+
+Ships as a DeepSeek Harness plugin: installing the bundle starts a bearer-authenticated MCP
+endpoint **together with the harness** and writes a ready-to-paste client config. No
+sidecar process to babysit, no port to guess, and no second writer on the session log.
+
+```
+┌──────────────────┐   Bearer token    ┌──────────────────────────────┐
+│  Claude / Codex  │ ────────────────► │  http://127.0.0.1:7801/mcp   │
+│  Cursor / other  │ ◄──────────────── │  inside the Harness process  │
+└──────────────────┘   MCP over HTTP   └───────────────┬──────────────┘
+                                                      │ in-process
+                                                      ▼
+                                           ┌─────────────────────┐
+                                           │  sessionController  │
+                                           │  list / page / …    │
+                                           └─────────────────────┘
+```
+
+## Why
+
+DeepSeek Harness keeps its conversations behind a writer lock: a second `dsh` process that
+tries to resume a live session is rejected, and its own HTTP API authenticates with a
+launch token that lives only in memory. This plugin solves both by serving MCP **inside**
+the harness process, where the session controller is already available, and by giving
+clients a stable bearer token instead of a launch secret.
+
+`session_send` therefore delivers into the conversation a human is looking at, not into a
+copy of it.
+
+## Install
+
+```bash
+dsh plugin --profile desktop add @nones/dsh-session-mcp
+```
+
+From a checkout or straight from git:
+
+```bash
+dsh plugin --profile desktop add /absolute/path/to/dsh-session-mcp
+bun add github:ZeiZel/dsh-session-mcp
+```
+
+Restart the harness (or reload the profile) and the endpoint starts with it.
+
+## Get your config
+
+The harness writes everything to:
+
+```
+$DSH_HOME/state/dsh-session-mcp.json
+```
+
+```json
+{
+  "url": "http://127.0.0.1:7801/mcp",
+  "token": "…",
+  "client": {
+    "mcpServers": {
+      "dsh-sessions": {
+        "type": "http",
+        "url": "http://127.0.0.1:7801/mcp",
+        "headers": { "Authorization": "Bearer …" }
+      }
+    }
+  }
+}
+```
+
+Copy the `client` block into your MCP client. Per client:
+
+**Claude Code**
+
+```bash
+claude mcp add --transport http dsh-sessions http://127.0.0.1:7801/mcp \
+  --header "Authorization: Bearer <token>"
+```
+
+**Claude Desktop / Cursor / generic `mcpServers`**
+
+```json
+{
+  "mcpServers": {
+    "dsh-sessions": {
+      "type": "http",
+      "url": "http://127.0.0.1:7801/mcp",
+      "headers": { "Authorization": "Bearer <token>" }
+    }
+  }
+}
+```
+
+**Codex** (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.dsh-sessions]
+url = "http://127.0.0.1:7801/mcp"
+
+[mcp_servers.dsh-sessions.http_headers]
+Authorization = "Bearer <token>"
+```
+
+Older clients that only speak the 2025 revisions still work: the endpoint serves the modern
+revision and falls back to stateless serving for 2025-era traffic.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `sessions_list` | Conversations with id, title, working directory, running state, token usage |
+| `session_read` | Durable history (user / assistant / tool), pageable back with `beforeSeq` |
+| `session_send` | Deliver a user message into a conversation (`queue` or `steer`) |
+| `session_create` | Open a new blank conversation and return its id |
+| `session_search` | Full-text search — only when the harness enables the session-query index |
+
+## Security
+
+- Binds **loopback only** (`127.0.0.1`) and rejects non-loopback `Host` headers.
+- Every request needs `Authorization: Bearer <token>`; the check is constant-time.
+- The token is 32 random bytes, generated once, stored `0600` at
+  `$DSH_HOME/state/dsh-session-mcp.json`, and reused across restarts so pasted client
+  configs keep working.
+- **Rotate** by deleting that file and restarting the harness. Every client then needs the
+  new token.
+- Never expose this endpoint through a proxy or a tunnel: the bearer is the only thing
+  between a client and every conversation you have.
+
+## Configuration
+
+The plugin row accepts two options (`cordis.patch.yml`):
+
+| Option | Default | Meaning |
+|---|---|---|
+| `port` | `7801` | Preferred loopback port. If taken, an ephemeral port is used and the state file is republished with the real URL. |
+| `host` | `127.0.0.1` | Bind address. |
+
+## How it works
+
+Written in TypeScript, compiled to `dist/` (committed, so installs need no build step).
+
+| Source | Role |
+|---|---|
+| `src/index.ts` | Cordis plugin: reads/creates the bearer, starts the listener, publishes the state file, closes the listener on unload |
+| `src/server.ts` | `node:http` listener with the bearer gate in front of the official SDK's `createMcpHandler` + `toNodeHandler` |
+| `src/tools.ts` | The five tools, backed directly by `ctx.sessionController` |
+| `src/config.ts` | Token persistence, constant-time bearer comparison, client snippet |
+| `src/types.ts` | The narrow structural slice of Harness types this package needs |
+
+## Development
+
+```bash
+bun install
+bun run typecheck   # tsc --noEmit
+bun run build       # tsc -> dist/
+```
+
+Requires Node ≥ 20. Runtime dependencies: `@modelcontextprotocol/server`,
+`@modelcontextprotocol/node`, `zod`. Dev: `typescript`, `@types/node`.
+
+`dist/` is committed so `bun add github:ZeiZel/dsh-session-mcp` and
+`dsh plugin add <dir>` work without a build step; `prepublishOnly` rebuilds it for npm.
+
+Releases: push a `v*` tag and the `release` workflow builds, publishes to npm and cuts a
+GitHub release.
+
+## License
+
+MIT © ZeiZel

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# dsh-session-mcp bundle patch.
+#
+# One row: the Host plugin that starts the bearer-authenticated MCP endpoint with
+# the Harness and publishes the client configuration. `port` is the preferred
+# loopback port; if it is taken the plugin binds an ephemeral one and republishes
+# the resolved URL.
+- insert:
+    - id: dsh-session-mcp
+      name: '@nones/dsh-session-mcp'
+      config:
+        port: 7801

package/dist/config.d.ts

@@ -0,0 +1,77 @@
+/** Default loopback port for the MCP endpoint. */
+export declare const DEFAULT_PORT = 7801;
+/** Default bind address. Loopback only, on purpose. */
+export declare const DEFAULT_HOST = "127.0.0.1";
+/** Name this server advertises to MCP clients. */
+export declare const SERVER_NAME = "dsh-session-mcp";
+/** Key used in generated client configuration snippets. */
+export declare const CLIENT_KEY = "dsh-sessions";
+/** One `mcpServers` entry as most MCP clients accept it. */
+export interface ClientEntry {
+    readonly type: 'http';
+    readonly url: string;
+    readonly headers: {
+        readonly Authorization: string;
+    };
+}
+/** The copy-paste fragment written to the endpoint file. */
+export interface ClientConfig {
+    readonly mcpServers: Record<string, ClientEntry>;
+}
+/** Persisted endpoint state. */
+export interface EndpointState {
+    readonly version: 1;
+    readonly name: string;
+    readonly url: string;
+    readonly host: string;
+    readonly port: number;
+    readonly token: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly client: ClientConfig;
+}
+/** The subset of stored state read back on restart. */
+export interface StoredState {
+    readonly token: string;
+    readonly createdAt?: string;
+}
+/**
+ * Resolve `$DSH_HOME` the way the launcher does.
+ * @returns absolute Harness home.
+ */
+export declare function dshHome(): string;
+/**
+ * Absolute path of the endpoint state file.
+ * @returns the file the server writes and clients read.
+ */
+export declare function stateFile(): string;
+/**
+ * Create a fresh opaque bearer token.
+ * @returns 32 random bytes, base64url encoded.
+ */
+export declare function createToken(): string;
+/**
+ * Read the persisted endpoint state, if any.
+ * @returns the stored state, or `undefined` when absent or unreadable.
+ */
+export declare function readState(): StoredState | undefined;
+/**
+ * Persist the endpoint state with owner-only permissions.
+ * @param state - resolved endpoint facts and the client snippet.
+ * @returns the file path written.
+ */
+export declare function writeState(state: EndpointState): string;
+/**
+ * Constant-time bearer comparison.
+ * @param expected - the stored token.
+ * @param header - the raw `Authorization` header value.
+ * @returns true only for exactly `Bearer <expected>`.
+ */
+export declare function bearerMatches(expected: string, header: string | undefined): boolean;
+/**
+ * Build the copy-paste client configuration for this endpoint.
+ * @param url - full MCP endpoint URL.
+ * @param token - bearer token.
+ * @returns an `mcpServers` fragment accepted by most MCP clients.
+ */
+export declare function clientConfig(url: string, token: string): ClientConfig;

package/dist/config.js

@@ -0,0 +1,122 @@
+/**
+ * Endpoint state for the DeepSeek Harness session MCP server.
+ *
+ * The bearer token and the listening URL must survive restarts: a client config
+ * the user pasted into Claude/Codex/Cursor keeps working only while both stay
+ * stable. The token is therefore generated once, stored with 0600 permissions,
+ * and reused; only the URL changes when the port has to fall back.
+ *
+ * @module dsh-session-mcp/config
+ */
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** Default loopback port for the MCP endpoint. */
+export const DEFAULT_PORT = 7801;
+/** Default bind address. Loopback only, on purpose. */
+export const DEFAULT_HOST = '127.0.0.1';
+/** Name this server advertises to MCP clients. */
+export const SERVER_NAME = 'dsh-session-mcp';
+/** Key used in generated client configuration snippets. */
+export const CLIENT_KEY = 'dsh-sessions';
+/**
+ * Resolve `$DSH_HOME` the way the launcher does.
+ * @returns absolute Harness home.
+ */
+export function dshHome() {
+    const fromEnv = process.env.DSH_HOME;
+    if (typeof fromEnv === 'string' && fromEnv.length > 0)
+        return fromEnv;
+    return join(homedir(), '.dsh');
+}
+/**
+ * Absolute path of the endpoint state file.
+ * @returns the file the server writes and clients read.
+ */
+export function stateFile() {
+    return join(dshHome(), 'state', 'dsh-session-mcp.json');
+}
+/**
+ * Create a fresh opaque bearer token.
+ * @returns 32 random bytes, base64url encoded.
+ */
+export function createToken() {
+    return randomBytes(32).toString('base64url');
+}
+/**
+ * Read the persisted endpoint state, if any.
+ * @returns the stored state, or `undefined` when absent or unreadable.
+ */
+export function readState() {
+    try {
+        const parsed = JSON.parse(readFileSync(stateFile(), 'utf8'));
+        if (parsed === null || typeof parsed !== 'object')
+            return undefined;
+        const candidate = parsed;
+        if (typeof candidate.token !== 'string' || candidate.token.length < 16)
+            return undefined;
+        return {
+            token: candidate.token,
+            ...(typeof candidate.createdAt === 'string' ? { createdAt: candidate.createdAt } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Persist the endpoint state with owner-only permissions.
+ * @param state - resolved endpoint facts and the client snippet.
+ * @returns the file path written.
+ */
+export function writeState(state) {
+    mkdirSync(join(dshHome(), 'state'), { recursive: true });
+    const file = stateFile();
+    writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        /* A pre-existing file keeps its mode; the token is local-only either way. */
+    }
+    return file;
+}
+/**
+ * Constant-time bearer comparison.
+ * @param expected - the stored token.
+ * @param header - the raw `Authorization` header value.
+ * @returns true only for exactly `Bearer <expected>`.
+ */
+export function bearerMatches(expected, header) {
+    if (typeof header !== 'string')
+        return false;
+    const match = /^Bearer\s+(\S+)$/iu.exec(header.trim());
+    if (match === null)
+        return false;
+    const presented = match[1];
+    if (presented === undefined)
+        return false;
+    const actual = Buffer.from(presented, 'utf8');
+    const wanted = Buffer.from(expected, 'utf8');
+    if (actual.byteLength !== wanted.byteLength)
+        return false;
+    return timingSafeEqual(actual, wanted);
+}
+/**
+ * Build the copy-paste client configuration for this endpoint.
+ * @param url - full MCP endpoint URL.
+ * @param token - bearer token.
+ * @returns an `mcpServers` fragment accepted by most MCP clients.
+ */
+export function clientConfig(url, token) {
+    return {
+        mcpServers: {
+            [CLIENT_KEY]: {
+                type: 'http',
+                url,
+                headers: { Authorization: `Bearer ${token}` },
+            },
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import type { PluginContext } from './types.js';
+/** Stable Cordis plugin name. */
+export declare const name = "dsh-session-mcp";
+/** The session controller is the only capability this plugin needs. */
+export declare const inject: readonly ['sessionController'];
+/** Row configuration accepted by the bundle patch. */
+export interface Config {
+    /** Preferred loopback port; an ephemeral one is used when it is taken. */
+    readonly port?: number;
+    /** Bind address. Defaults to `127.0.0.1`. */
+    readonly host?: string;
+}
+/**
+ * Mount the endpoint.
+ * @param ctx - Host context carrying `sessionController`.
+ * @param config - Loader row config: `{ port?, host? }`.
+ */
+export declare function apply(ctx: PluginContext, config?: Config): Promise<void>;

package/dist/index.js

@@ -0,0 +1,91 @@
+/**
+ * dsh-session-mcp — Host plugin.
+ *
+ * Starting this plugin starts the MCP endpoint with the Harness: it binds a
+ * loopback listener, requires the bearer token stored for this Harness home,
+ * and serves the session tools in-process through `ctx.sessionController`.
+ *
+ * The bearer token is generated once and reused, so a client configuration the
+ * user pasted into Claude/Codex/Cursor keeps working across restarts. The
+ * resolved endpoint and a ready `mcpServers` fragment are written to
+ * `$DSH_HOME/state/dsh-session-mcp.json` on every start.
+ *
+ * @module dsh-session-mcp
+ */
+import { readFileSync } from 'node:fs';
+import { clientConfig, createToken, DEFAULT_HOST, DEFAULT_PORT, readState, SERVER_NAME, writeState, } from './config.js';
+import { startEndpoint } from './server.js';
+/** Stable Cordis plugin name. */
+export const name = 'dsh-session-mcp';
+/** The session controller is the only capability this plugin needs. */
+export const inject = ['sessionController'];
+/**
+ * Read this package's version without assuming a checkout layout.
+ * @returns the `version` field of the package manifest.
+ */
+function packageVersion() {
+    try {
+        const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        if (manifest !== null && typeof manifest === 'object') {
+            const version = manifest.version;
+            if (typeof version === 'string')
+                return version;
+        }
+    }
+    catch {
+        /* A missing manifest only affects the advertised version string. */
+    }
+    return '0.0.0';
+}
+/**
+ * Resolve the row config with defaults and type checks.
+ * @param config - raw Loader row config.
+ * @returns the effective `{ port, host }`.
+ */
+function settingsOf(config) {
+    const port = config?.port ?? DEFAULT_PORT;
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new RangeError(`dsh-session-mcp: port ${String(port)} is out of range`);
+    }
+    const host = config?.host !== undefined && config.host.length > 0 ? config.host : DEFAULT_HOST;
+    return { port, host };
+}
+/**
+ * Mount the endpoint.
+ * @param ctx - Host context carrying `sessionController`.
+ * @param config - Loader row config: `{ port?, host? }`.
+ */
+export async function apply(ctx, config) {
+    const { port, host } = settingsOf(config);
+    const version = packageVersion();
+    const stored = readState();
+    const token = stored?.token ?? createToken();
+    const createdAt = stored?.createdAt ?? new Date().toISOString();
+    const endpoint = await startEndpoint({
+        controller: ctx.sessionController,
+        token,
+        host,
+        port,
+        version,
+        logger: ctx.logger,
+    });
+    const state = {
+        version: 1,
+        name: SERVER_NAME,
+        url: endpoint.url,
+        host,
+        port: endpoint.port,
+        token,
+        createdAt,
+        updatedAt: new Date().toISOString(),
+        client: clientConfig(endpoint.url, token),
+    };
+    const file = writeState(state);
+    ctx.logger?.info?.(`dsh-session-mcp: MCP endpoint listening at ${endpoint.url}`);
+    ctx.logger?.info?.(`dsh-session-mcp: bearer token and client config in ${file}`);
+    console.log(`dsh-session-mcp: ${endpoint.url} (bearer in ${file})`);
+    console.log(JSON.stringify(state.client, null, 2));
+    ctx.effect(() => () => {
+        void endpoint.close();
+    }, 'dsh-session-mcp: endpoint lifetime');
+}

package/dist/server.d.ts

@@ -0,0 +1,33 @@
+import type { PluginLogger, SessionController } from './types.js';
+/** Path the MCP endpoint answers on. */
+export declare const MCP_PATH = "/mcp";
+/** Description every client receives during `initialize`. */
+export declare const SERVER_INSTRUCTIONS: string;
+/** A running endpoint. */
+export interface RunningEndpoint {
+    readonly url: string;
+    readonly port: number;
+    close(): Promise<void>;
+}
+/** Options accepted by {@link startEndpoint}. */
+export interface StartEndpointOptions {
+    readonly controller: SessionController;
+    readonly token: string;
+    readonly host: string;
+    readonly port: number;
+    readonly version: string;
+    readonly logger?: PluginLogger | undefined;
+}
+/**
+ * Build the web-standard MCP handler for one session controller.
+ * @param controller - Harness `sessionController` service.
+ * @param version - advertised server version.
+ * @returns an object exposing `fetch(Request)`.
+ */
+export declare function buildMcpHandler(controller: SessionController, version: string): import("@modelcontextprotocol/server").McpHttpHandler;
+/**
+ * Start the bearer-authenticated MCP endpoint.
+ * @param options - controller, token, host, port, version, logger.
+ * @returns the resolved endpoint plus a disposer.
+ */
+export declare function startEndpoint(options: StartEndpointOptions): Promise<RunningEndpoint>;

package/dist/server.js

@@ -0,0 +1,147 @@
+/**
+ * Bearer-authenticated HTTP MCP endpoint.
+ *
+ * The MCP protocol work is the official SDK's: `createMcpHandler` serves the
+ * modern revision from a per-request server factory and falls back to stateless
+ * serving for 2025-era clients, so older MCP clients keep working. This module
+ * owns only what the SDK deliberately leaves to the caller: the loopback
+ * listener, the path, and the bearer check.
+ *
+ * @module dsh-session-mcp/server
+ */
+import { createServer } from 'node:http';
+import { toNodeHandler } from '@modelcontextprotocol/node';
+import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
+import { bearerMatches, SERVER_NAME } from './config.js';
+import { registerTools } from './tools.js';
+/** Path the MCP endpoint answers on. */
+export const MCP_PATH = '/mcp';
+/** Description every client receives during `initialize`. */
+export const SERVER_INSTRUCTIONS = [
+    'This server exposes one running DeepSeek Harness instance: its conversations, their durable history,',
+    'and the ability to deliver a new user message into a live conversation.',
+    'Start with sessions_list to discover conversation ids, then session_read to inspect history,',
+    'or session_send to deliver a message. session_send joins the chat a human is watching and starts a',
+    'model turn, so send complete, deliberate messages rather than fragments.',
+].join(' ');
+/** Loopback hostnames accepted in the Host header. */
+const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost', '[::1]']);
+/**
+ * Build the web-standard MCP handler for one session controller.
+ * @param controller - Harness `sessionController` service.
+ * @param version - advertised server version.
+ * @returns an object exposing `fetch(Request)`.
+ */
+export function buildMcpHandler(controller, version) {
+    return createMcpHandler(() => {
+        const server = new McpServer({ name: SERVER_NAME, version }, { instructions: SERVER_INSTRUCTIONS });
+        registerTools(server, controller);
+        return server;
+    });
+}
+/**
+ * Whether a request's Host header names this machine.
+ * @param req - incoming request.
+ * @returns false for anything that is not loopback.
+ */
+function hostIsLoopback(req) {
+    const header = req.headers.host;
+    if (typeof header !== 'string')
+        return false;
+    const name = header.replace(/:\d+$/u, '');
+    return LOOPBACK.has(name.toLowerCase());
+}
+/**
+ * Write one small JSON response.
+ * @param res - node response.
+ * @param status - HTTP status.
+ * @param body - JSON-serializable body.
+ * @param headers - extra headers.
+ */
+function json(res, status, body, headers = {}) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(payload),
+        'cache-control': 'no-store',
+        ...headers,
+    });
+    res.end(payload);
+}
+/**
+ * Bind a listener, falling back to an ephemeral port when the wanted one is taken.
+ * @param server - node http server.
+ * @param port - preferred port, `0` for ephemeral.
+ * @param host - bind address.
+ * @returns the bound port and whether the fallback ran.
+ */
+async function bind(server, port, host) {
+    const attempt = (wanted) => new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off('listening', onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            const address = server.address();
+            if (address === null || typeof address === 'string') {
+                reject(new Error('dsh-session-mcp: the listener bound without an address'));
+                return;
+            }
+            resolve(address.port);
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(wanted, host);
+    });
+    try {
+        return { port: await attempt(port), fellBack: false };
+    }
+    catch (error) {
+        const code = error?.code;
+        if (port === 0 || code !== 'EADDRINUSE')
+            throw error;
+        return { port: await attempt(0), fellBack: true };
+    }
+}
+/**
+ * Start the bearer-authenticated MCP endpoint.
+ * @param options - controller, token, host, port, version, logger.
+ * @returns the resolved endpoint plus a disposer.
+ */
+export async function startEndpoint(options) {
+    const { controller, token, host, port, version, logger } = options;
+    const handler = buildMcpHandler(controller, version);
+    const nodeHandler = toNodeHandler(handler);
+    const server = createServer((req, res) => {
+        if (!hostIsLoopback(req)) {
+            json(res, 403, { error: 'forbidden', message: 'this endpoint accepts loopback hosts only' });
+            return;
+        }
+        if (!bearerMatches(token, req.headers.authorization)) {
+            json(res, 401, { error: 'unauthorized', message: 'send Authorization: Bearer <token> from the Harness endpoint file' }, { 'www-authenticate': `Bearer realm="${SERVER_NAME}"` });
+            return;
+        }
+        const path = (req.url ?? '').split('?')[0];
+        if (path !== MCP_PATH && path !== `${MCP_PATH}/`) {
+            json(res, 404, { error: 'not_found', message: `the MCP endpoint lives at ${MCP_PATH}` });
+            return;
+        }
+        void nodeHandler(req, res);
+    });
+    const bound = await bind(server, port, host);
+    if (bound.fellBack) {
+        logger?.warn?.(`dsh-session-mcp: port ${port} is in use; bound an ephemeral port ${bound.port} instead`);
+    }
+    const url = `http://${host === '::1' ? '[::1]' : host}:${bound.port}${MCP_PATH}`;
+    return {
+        url,
+        port: bound.port,
+        async close() {
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+                server.closeAllConnections?.();
+            });
+        },
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from '@modelcontextprotocol/server';
+import type { SessionController } from './types.js';
+/**
+ * Register the session tools on one MCP server instance.
+ * @param server - a fresh `McpServer` for one serving unit.
+ * @param controller - the Harness `sessionController` service.
+ */
+export declare function registerTools(server: McpServer, controller: SessionController): void;

package/dist/tools.js

@@ -0,0 +1,205 @@
+/**
+ * The MCP tool surface over a DeepSeek Harness session controller.
+ *
+ * Every tool answers from `ctx.sessionController` in-process, as the owner, so
+ * a prompt lands in the live conversation instead of opening a second writer on
+ * the session log (which is what a `dsh --profile sdk`/`acp` resume of a live
+ * session would collide with).
+ *
+ * @module dsh-session-mcp/tools
+ */
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+/** Longest single message body returned to a client. */
+const MAX_TEXT_CHARS = 4000;
+/** A signal that never aborts; the controller only needs a cancellation handle. */
+function never() {
+    return new AbortController().signal;
+}
+/** Collapse one content-block array into readable text. */
+function blocksToText(blocks) {
+    if (typeof blocks === 'string')
+        return blocks;
+    if (!Array.isArray(blocks))
+        return '';
+    const parts = [];
+    for (const block of blocks) {
+        if (block === null || typeof block !== 'object')
+            continue;
+        const candidate = block;
+        if (candidate.type === 'text' && typeof candidate.text === 'string')
+            parts.push(candidate.text);
+        else if (candidate.type === 'tool-call') {
+            parts.push(`[tool ${String(candidate.name ?? '?')} ${String(candidate.arguments ?? '').slice(0, 400)}]`);
+        }
+        else if (candidate.type === 'image')
+            parts.push('[image]');
+    }
+    return parts.join('\n').trim();
+}
+/**
+ * Reduce one durable Session event to a compact message.
+ * @param record - one entry of `sessionController.page().records`.
+ * @returns a message, or `null` for events without conversational content.
+ */
+function reduceRecord(record) {
+    const event = (record.event ?? record);
+    if (event === null || typeof event !== 'object')
+        return null;
+    const data = (event.data ?? {});
+    const message = (data.message ?? {});
+    const out = { seq: event.seq, type: event.type, text: '' };
+    if (event.time !== undefined)
+        out.time = event.time;
+    if (event.type === 'user/message' || event.type === 'assistant/message') {
+        out.role = message.role ?? (event.type === 'user/message' ? 'user' : 'assistant');
+        out.text = blocksToText(message.content);
+    }
+    else if (event.type === 'tool/call') {
+        out.role = 'tool';
+        out.name = typeof data.name === 'string' ? data.name : undefined;
+        out.text = String(data.arguments ?? '');
+    }
+    else if (event.type === 'tool/result') {
+        out.role = 'tool';
+        out.text = blocksToText(message.content);
+    }
+    else {
+        return null;
+    }
+    if (out.text.length > MAX_TEXT_CHARS)
+        out.text = `${out.text.slice(0, MAX_TEXT_CHARS)}… [truncated]`;
+    return out;
+}
+/** Wrap one value as an MCP text result. */
+function ok(value) {
+    return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+/** Wrap one failure as an MCP error result. */
+function fail(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+/**
+ * Register the session tools on one MCP server instance.
+ * @param server - a fresh `McpServer` for one serving unit.
+ * @param controller - the Harness `sessionController` service.
+ */
+export function registerTools(server, controller) {
+    server.registerTool('sessions_list', {
+        title: 'List conversations',
+        description: 'List DeepSeek Harness conversations with id, title, working directory, running state and token usage. Call this first to discover the sessionId to read or prompt.',
+        inputSchema: z.object({
+            limit: z.number().int().min(1).max(500).optional().describe('Maximum rows, newest first. Default 50.'),
+        }),
+    }, async ({ limit }) => {
+        try {
+            const value = await controller.list({}, never());
+            const rows = [...(value?.items ?? [])]
+                .sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0))
+                .slice(0, limit ?? 50)
+                .map((item) => ({
+                sessionId: item.sessionId,
+                title: item.projections?.values?.title ?? null,
+                cwd: item.cwd ?? null,
+                updatedAt: item.updatedAt === undefined ? null : new Date(item.updatedAt).toISOString(),
+                running: item.running === true,
+                blank: item.blank === true,
+                agentAvailable: item.agentAvailable === true,
+                tokens: item.projections?.values?.tokenUsage ?? null,
+            }));
+            return ok({ count: rows.length, sessions: rows });
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool('session_read', {
+        title: 'Read conversation history',
+        description: 'Read durable history of one conversation (user, assistant and tool messages). Use beforeSeq to page further back.',
+        inputSchema: z.object({
+            sessionId: z.string().min(1).describe('Conversation id from sessions_list.'),
+            maxMessages: z.number().int().min(1).max(200).optional().describe('Roughly how many messages. Default 20.'),
+            beforeSeq: z.number().int().min(0).optional().describe('Only return events before this sequence number.'),
+        }),
+    }, async ({ sessionId, maxMessages, beforeSeq }) => {
+        try {
+            const rows = await controller.list({}, never());
+            const cut = (rows?.items ?? []).find((item) => item.sessionId === sessionId)?.projections?.asOfSeq;
+            const projections = typeof cut === 'number' ? undefined : await controller.projections({ sessionId }, never());
+            const throughSeq = typeof cut === 'number' ? cut : projections?.asOfSeq;
+            if (typeof throughSeq !== 'number')
+                throw new Error(`Session ${sessionId} has no readable log cut`);
+            const request = {
+                address: { kind: 'session', sessionId },
+                throughSeq,
+                maxMessages: maxMessages ?? 20,
+            };
+            if (beforeSeq !== undefined)
+                request.beforeSeq = beforeSeq;
+            const page = await controller.page(request, never());
+            const messages = (page?.records ?? []).map(reduceRecord).filter((entry) => entry !== null);
+            return ok({ sessionId, throughSeq, hasMore: page?.hasMore === true, messages });
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool('session_send', {
+        title: 'Send a message into a conversation',
+        description: 'Send a user message into an existing conversation. The message joins the live chat a human sees and starts a model turn. mode=queue waits for the current turn, mode=steer interrupts into it.',
+        inputSchema: z.object({
+            sessionId: z.string().min(1).describe('Conversation id from sessions_list.'),
+            text: z.string().min(1).describe('Message text to deliver.'),
+            mode: z.enum(['queue', 'steer']).optional().describe('Delivery mode. Default queue.'),
+        }),
+    }, async ({ sessionId, text, mode }) => {
+        try {
+            if (text.trim().length === 0)
+                throw new Error('text must contain non-whitespace content');
+            const requestId = randomUUID();
+            const delivery = mode ?? 'queue';
+            const value = await controller.prompt({ requestId, sessionId, mode: delivery, content: [{ type: 'text', text }] }, never());
+            return ok({ sessionId, requestId, mode: delivery, accepted: value?.accepted === true });
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool('session_create', {
+        title: 'Open a new conversation',
+        description: 'Open a new blank conversation in the Harness and return its id. Combine with session_send to start work in a fresh chat.',
+        inputSchema: z.object({
+            cwd: z.string().min(1).optional().describe('Absolute directory the conversation works in.'),
+            agentPreset: z.string().min(1).optional().describe('Agent preset name. Omit for the configured default.'),
+        }),
+    }, async ({ cwd, agentPreset }) => {
+        try {
+            const request = {};
+            if (cwd !== undefined)
+                request.cwd = cwd;
+            if (agentPreset !== undefined)
+                request.agentPreset = agentPreset;
+            const value = await controller.create(request);
+            return ok({ sessionId: value?.sessionId ?? null, agentPreset: value?.agentPreset ?? null });
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool('session_search', {
+        title: 'Search conversations',
+        description: 'Full-text search across conversations. Works only when the Harness has the session-query index enabled; otherwise the Host reports that search is disabled.',
+        inputSchema: z.object({
+            query: z.string().min(1).describe('Search text.'),
+        }),
+    }, async ({ query }) => {
+        try {
+            const value = await controller.search({ query }, never());
+            return ok({ items: value?.items ?? [], hasMore: value?.hasMore === true });
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The narrow slice of DeepSeek Harness types this package depends on.
+ *
+ * The plugin ships as a standalone npm package, so it does not import the
+ * harness's own type packages (which resolve only inside a Harness profile).
+ * These structural declarations mirror the parts of `ctx.sessionController`
+ * and the Cordis plugin context the bridge actually uses.
+ *
+ * @module dsh-session-mcp/types
+ */
+/** One conversation row as `sessionController.list` reports it. */
+export interface SessionSummary {
+    readonly sessionId: string;
+    readonly updatedAt?: number;
+    readonly cwd?: string;
+    readonly running?: boolean;
+    readonly blank?: boolean;
+    readonly agentAvailable?: boolean;
+    readonly projections?: {
+        readonly asOfSeq?: number;
+        readonly values?: {
+            readonly title?: string | null;
+            readonly tokenUsage?: unknown;
+        };
+    };
+}
+/** A durable conversation event envelope. */
+export interface SessionEventRecord {
+    readonly type?: string;
+    readonly event?: {
+        readonly type?: string;
+        readonly seq?: number;
+        readonly time?: number;
+        readonly data?: Record<string, unknown>;
+    };
+}
+/** One page of durable history. */
+export interface SessionPage {
+    readonly records?: readonly SessionEventRecord[];
+    readonly hasMore?: boolean;
+}
+/** One message part accepted by `prompt`. */
+export interface PromptContentPart {
+    readonly type: 'text';
+    readonly text: string;
+}
+/** The controller surface used by the MCP tools. */
+export interface SessionController {
+    list(request: Record<string, never>, signal: AbortSignal): Promise<{
+        items?: readonly SessionSummary[];
+    }>;
+    page(request: Record<string, unknown>, signal: AbortSignal): Promise<SessionPage>;
+    prompt(request: Record<string, unknown>, signal: AbortSignal): Promise<{
+        accepted?: boolean;
+    }>;
+    create(request: Record<string, unknown>): Promise<{
+        sessionId?: string;
+        agentPreset?: string;
+    }>;
+    search(request: {
+        query: string;
+    }, signal: AbortSignal): Promise<{
+        items?: unknown[];
+        hasMore?: boolean;
+    }>;
+    projections(request: {
+        sessionId: string;
+    }, signal: AbortSignal): Promise<{
+        asOfSeq?: number;
+    } | null>;
+}
+/** Minimal logger surface shared by Cordis and this package's tests. */
+export interface PluginLogger {
+    info?(message: string): void;
+    warn?(message: string): void;
+}
+/** Minimal Cordis plugin context used by {@link apply}. */
+export interface PluginContext {
+    readonly sessionController: SessionController;
+    readonly logger?: PluginLogger;
+    effect(setup: () => () => void, label?: string): void;
+}

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * The narrow slice of DeepSeek Harness types this package depends on.
+ *
+ * The plugin ships as a standalone npm package, so it does not import the
+ * harness's own type packages (which resolve only inside a Harness profile).
+ * These structural declarations mirror the parts of `ctx.sessionController`
+ * and the Cordis plugin context the bridge actually uses.
+ *
+ * @module dsh-session-mcp/types
+ */
+export {};

package/icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="DSH Session MCP Bridge">
+  <g fill="none" stroke="#2f6f4e" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
+    <rect x="6" y="14" width="22" height="36" rx="5"/>
+    <rect x="36" y="14" width="22" height="36" rx="5"/>
+    <path d="M28 26h8M28 38h8"/>
+    <path d="M14 24h6M14 32h6M14 40h6"/>
+    <path d="M44 24h6M44 32h6M44 40h6"/>
+  </g>
+</svg>

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Session MCP Server",
+    "description": "Starts a bearer-authenticated MCP endpoint with the Harness so other agents can list, read and prompt your conversations."
+  }
+}

package/locale/ru.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "MCP-сервер сессий",
+    "description": "Поднимает вместе с харнесом MCP-эндпоинт с Bearer-авторизацией: другие агенты могут смотреть список сессий, читать историю и отправлять сообщения."
+  }
+}

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@nones/dsh-session-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "MCP server for DeepSeek Harness sessions — list, read and prompt live conversations from any MCP client",
+  "type": "module",
+  "license": "MIT",
+  "author": "ZeiZel <valera2003lvov@yandex.ru>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZeiZel/dsh-session-mcp.git"
+  },
+  "homepage": "https://github.com/ZeiZel/dsh-session-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/ZeiZel/dsh-session-mcp/issues"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "sessions",
+    "claude",
+    "codex",
+    "cursor",
+    "plugin",
+    "bundle"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "dist",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/node": "^2.1.2",
+    "@modelcontextprotocol/server": "^2.4.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "typescript": "^7.0.2"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}