create-principles-disciple 1.146.9 → 1.147.0

package/pd-mcp-server/dist/index.js

@@ -0,0 +1,76 @@
+/**
+ * PD MCP Server process entry — SPEC-PD-MCP-GATE4-001 §5.5.
+ *
+ * Startup: resolve the fixed workspace binding (fail-closed: a missing or
+ * invalid binding logs ONE sanitized reason to stderr and exits 1 BEFORE the
+ * MCP initialize — the server never serves with an unconfirmed workspace) →
+ * build the server → connect the stdio transport → wait for requests.
+ *
+ * Shutdown (host closes stdin / terminates): stop accepting new calls
+ * (in-flight ones drain bounded by the 10 s deadline; late results are
+ * suppressed), release resources, exit 0.
+ *
+ * stdout carries MCP protocol messages ONLY (§5.3). This module never
+ * console.log's; logs go through the sanitized stderr logger.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { createHash } from 'node:crypto';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createPdMcpServer } from './server.js';
+import { resolveWorkspaceBinding } from './workspace.js';
+import { stderrLog } from './logging.js';
+export { createPdMcpServer, TOOL_NAME, toolInputSchema } from './server.js';
+export { resolveWorkspaceBinding, WORKSPACE_DIR_ENV, HOST_ENV } from './workspace.js';
+export { RESPONSE_BUDGET_BYTES, withinBudget, measureTextBytes } from './budget.js';
+export { DEFAULT_DEADLINE_MS, MAX_TRACKED_ORPHANS, runWithDeadline, OrphanLimiter } from './deadline.js';
+export { SERVER_NAME, SERVER_VERSION, MCP_SDK_PIN } from './version.js';
+/**
+ * Run the stdio server against the real process env. Returns the intended
+ * process exit code: 0 after a clean shutdown, 1 for a fail-closed startup.
+ */
+export async function main(env = process.env) {
+    const binding = resolveWorkspaceBinding(env);
+    if (!binding.ok) {
+        // Fail-closed BEFORE initialize: one sanitized stderr line with the
+        // reason and the next action; nothing about values or paths.
+        stderrLog('error', 'startup_binding_failed', {
+            envVar: binding.envVar,
+            reasonCategory: 'invalid_binding',
+            reason: binding.reason,
+            nextAction: binding.nextAction,
+        });
+        return 1;
+    }
+    // Workspace fingerprint (NOT the path): lets operators and acceptance runs
+    // prove WHICH workspace this process bound without leaking a directory
+    // (§10 forbids logging full paths). Multi-agent hosts must never see two
+    // different fingerprints for the same binding.
+    const workspaceFingerprint = createHash('sha256')
+        .update(path.resolve(binding.binding.workspaceDir))
+        .digest('hex')
+        .slice(0, 16);
+    stderrLog('info', 'startup', { host: binding.binding.host ?? 'unspecified', workspaceFingerprint });
+    const handle = createPdMcpServer({ workspaceDir: binding.binding.workspaceDir, host: binding.binding.host });
+    const transport = new StdioServerTransport();
+    await handle.mcpServer.connect(transport);
+    // Host-driven shutdown: stdin close → SDK closes the transport → we stop
+    // accepting new work, let in-flight calls drain (bounded by the deadline)
+    // and exit cleanly. The transport close callback is the single trigger.
+    transport.onclose = () => {
+        handle.beginShutdown();
+        stderrLog('info', 'transport_closed', { orphans: handle.orphans.size });
+    };
+    return 0;
+}
+// Process-mode guard: only run when executed directly (not when the launcher
+// or tests import this module). Windows-safe via pathToFileURL.
+const { 1: invokedPath } = process.argv;
+if (invokedPath !== undefined &&
+    import.meta.url === pathToFileURL(invokedPath).href) {
+    void main().then((code) => {
+        if (code !== 0)
+            process.exit(code);
+        // code 0: exit naturally once the event loop drains (timers unref'd).
+    });
+}

package/pd-mcp-server/dist/logging.d.ts

@@ -0,0 +1,12 @@
+export type LogField = string | number | boolean;
+export type LogFields = Readonly<Record<string, LogField>>;
+export type LogLevel = 'info' | 'warn' | 'error';
+/** Bound logger: sink fixed at construction, ≤3 params per call. */
+export type LogFn = (level: LogLevel, event: string, fields?: LogFields) => void;
+declare function sanitizeErrorKind(err: unknown): string;
+/** Default stderr sink. One JSON line per event, nothing else. */
+export declare function stderrSink(line: string): void;
+export declare function createLogger(sink: (line: string) => void, baseFields?: LogFields): LogFn;
+/** Convenience logger bound to stderr (startup/shutdown paths). */
+export declare const stderrLog: LogFn;
+export { sanitizeErrorKind };

package/pd-mcp-server/dist/logging.js

@@ -0,0 +1,42 @@
+/**
+ * Stderr-only structured logging — SPEC-PD-MCP-GATE4-001 §10.
+ *
+ * stdout carries MCP protocol messages ONLY; every log line goes to stderr
+ * as one JSON object. Redaction is by construction: callers may pass only
+ * scalar event/category/duration fields — never Pain text, evidence bodies,
+ * env values, raw tool results, absolute workspace/db paths or stack traces.
+ * The `errKind` field carries a sanitized exception category (the error's
+ * `name`), never `message` or `stack`.
+ */
+import { SERVER_NAME, SERVER_VERSION } from './version.js';
+function sanitizeErrorKind(err) {
+    if (err !== null && typeof err === 'object' && Object.hasOwn(err, 'name') && typeof err.name === 'string') {
+        const { name } = err;
+        return name.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 60) || 'Error';
+    }
+    return 'Error';
+}
+/** Default stderr sink. One JSON line per event, nothing else. */
+export function stderrSink(line) {
+    process.stderr.write(line + '\n');
+}
+export function createLogger(sink, baseFields) {
+    return (level, event, fields) => {
+        const entry = {
+            ts: new Date().toISOString(),
+            server: SERVER_NAME,
+            version: SERVER_VERSION,
+            level,
+            event,
+        };
+        const merged = { ...baseFields, ...fields };
+        for (const [k, v] of Object.entries(merged)) {
+            if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
+                entry[k] = v;
+        }
+        sink(JSON.stringify(entry));
+    };
+}
+/** Convenience logger bound to stderr (startup/shutdown paths). */
+export const stderrLog = createLogger(stderrSink);
+export { sanitizeErrorKind };

package/pd-mcp-server/dist/server.d.ts

@@ -0,0 +1,90 @@
+/**
+ * PD MCP Server assembly — SPEC-PD-MCP-GATE4-001 §3/§4/§5 (Gate 4-B).
+ *
+ * One server implementation shared by all three hosts (Codex / OpenClaw /
+ * WorkBuddy each spawn their own process around this module). Business data
+ * flows EXCLUSIVELY through the Gate 3 Capability public subpath
+ * `@principles/core/runtime-v2/pain-recall-capability` — never the read
+ * model, never a CLI subprocess, never a second query implementation
+ * (§3.2). Core stays MCP-SDK-free (architecture guard test pins this).
+ *
+ * The single registered tool is the read-only `pd_recall_principle_pains`
+ * with an honest `readOnlyHint: true` (a host hint, not an OS boundary).
+ */
+import { McpServer, type StandardSchemaWithJSON } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+import { type PainRecallCapabilityResult } from '@principles/core/runtime-v2/pain-recall-capability';
+import { OrphanLimiter, AdmissionLimiter } from './deadline.js';
+export declare const TOOL_NAME: 'pd_recall_principle_pains';
+export declare const TOOL_DESCRIPTION = "Recall a principle's verifiably-associated historical pain experience (availability-level disclosure only, OD-A v1). Read-only.";
+/** §4.2 input contract: `principleId` (1..200, required) and `limit`
+ * (1..10, default 3); every other property is rejected at the protocol
+ * input-validation stage (`additionalProperties: false`) before the
+ * capability is called. No path, SQL, host/session/turn/pain id, or
+ * ordering parameters exist. The capability re-validates field-by-field
+ * (defense in depth). */
+export declare const toolInputJsonSchema: {
+    readonly type: 'object';
+    readonly properties: {
+        readonly principleId: {
+            readonly type: 'string';
+            readonly minLength: 1;
+            readonly maxLength: 200;
+            readonly description: 'Principle identifier to recall pains for.';
+        };
+        readonly limit: {
+            readonly type: 'integer';
+            readonly minimum: 1;
+            readonly maximum: 10;
+            readonly default: 3;
+            readonly description: 'Maximum number of pain entries to return (1..10, default 3).';
+        };
+    };
+    readonly required: readonly ['principleId'];
+    readonly additionalProperties: false;
+};
+/** Protocol-level schema handed to the SDK (JSON-Schema-first: strict
+ * rejection of undeclared parameters at the input-validation stage). */
+export declare const toolProtocolSchema: StandardSchemaWithJSON<unknown, unknown>;
+/** In-handler typed re-validation (idempotent post-SDK parse; applies the
+ * `limit` default and yields the typed value). Mirrors the JSON schema
+ * above — kept in lockstep by the contract tests. */
+export declare const toolInputSchema: z.ZodObject<{
+    principleId: z.ZodString;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strict>;
+export type ToolInput = z.infer<typeof toolInputSchema>;
+/** The capability entry the server calls — injectable for adapter-contract
+ * tests; production always uses the real Gate 3 Facade. */
+export type CapabilityCall = (input: {
+    readonly workspaceDir: string;
+    readonly principleId: string;
+    readonly limit: number;
+}) => Promise<PainRecallCapabilityResult>;
+export interface PdMcpServerOptions {
+    readonly workspaceDir: string;
+    readonly host?: string | null;
+    readonly deadlineMs?: number;
+    readonly callCapability?: CapabilityCall;
+    readonly logSink?: (line: string) => void;
+}
+export interface PdMcpServerHandle {
+    readonly mcpServer: McpServer;
+    /** Timeout stragglers tracked until their underlying work settles. */
+    readonly orphans: OrphanLimiter;
+    /** Executing-call capacity; admission is reserved before the capability is
+     * invoked and released only on real settlement (§4.7). */
+    readonly admissions: AdmissionLimiter;
+    /** Lifecycle flag: once closing, in-flight work drains and new calls get
+     * the shutting-down failure (§5.5). */
+    beginShutdown(): void;
+    isShuttingDown(): boolean;
+}
+/**
+ * Build the PD MCP server (not yet connected to any transport).
+ *
+ * Handler flow per §4.7/§4.8: shutdown/saturation gates → deadline-wrapped
+ * capability call → envelope assembly (serialize → 32 KiB budget → emit) →
+ * explicit isError mapping. Nothing here writes to stdout.
+ */
+export declare function createPdMcpServer(options: PdMcpServerOptions): PdMcpServerHandle;

package/pd-mcp-server/dist/server.js

@@ -0,0 +1,178 @@
+/**
+ * PD MCP Server assembly — SPEC-PD-MCP-GATE4-001 §3/§4/§5 (Gate 4-B).
+ *
+ * One server implementation shared by all three hosts (Codex / OpenClaw /
+ * WorkBuddy each spawn their own process around this module). Business data
+ * flows EXCLUSIVELY through the Gate 3 Capability public subpath
+ * `@principles/core/runtime-v2/pain-recall-capability` — never the read
+ * model, never a CLI subprocess, never a second query implementation
+ * (§3.2). Core stays MCP-SDK-free (architecture guard test pins this).
+ *
+ * The single registered tool is the read-only `pd_recall_principle_pains`
+ * with an honest `readOnlyHint: true` (a host hint, not an OS boundary).
+ */
+import { McpServer, fromJsonSchema } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+import { recallPrinciplePainsCapability, } from '@principles/core/runtime-v2/pain-recall-capability';
+import { runWithDeadline, OrphanLimiter, AdmissionLimiter, DEFAULT_DEADLINE_MS } from './deadline.js';
+import { assembleResult, adapterFailureEnvelope, textResult } from './envelope.js';
+import { RESPONSE_BUDGET_BYTES, withinBudget } from './budget.js';
+import { createLogger, sanitizeErrorKind, stderrSink } from './logging.js';
+import { SERVER_NAME, SERVER_VERSION } from './version.js';
+export const TOOL_NAME = 'pd_recall_principle_pains';
+export const TOOL_DESCRIPTION = 'Recall a principle\'s verifiably-associated historical pain experience (availability-level disclosure only, OD-A v1). Read-only.';
+/** §4.2 input contract: `principleId` (1..200, required) and `limit`
+ * (1..10, default 3); every other property is rejected at the protocol
+ * input-validation stage (`additionalProperties: false`) before the
+ * capability is called. No path, SQL, host/session/turn/pain id, or
+ * ordering parameters exist. The capability re-validates field-by-field
+ * (defense in depth). */
+export const toolInputJsonSchema = {
+    type: 'object',
+    properties: {
+        principleId: { type: 'string', minLength: 1, maxLength: 200, description: 'Principle identifier to recall pains for.' },
+        limit: { type: 'integer', minimum: 1, maximum: 10, default: 3, description: 'Maximum number of pain entries to return (1..10, default 3).' },
+    },
+    required: ['principleId'],
+    additionalProperties: false,
+};
+/** Protocol-level schema handed to the SDK (JSON-Schema-first: strict
+ * rejection of undeclared parameters at the input-validation stage). */
+export const toolProtocolSchema = fromJsonSchema(toolInputJsonSchema);
+/** In-handler typed re-validation (idempotent post-SDK parse; applies the
+ * `limit` default and yields the typed value). Mirrors the JSON schema
+ * above — kept in lockstep by the contract tests. */
+export const toolInputSchema = z.strictObject({
+    principleId: z.string().min(1).max(200),
+    limit: z.number().int().min(1).max(10).optional().default(3),
+});
+/** §4.8 Adapter 执行失败 row (timeout / exception / saturated / shutting
+ * down) — one sanitized `tool_execution_failed` envelope, isError: true. */
+function executionFailedResult(message) {
+    const envelope = adapterFailureEnvelope('tool_execution_failed', message);
+    return textResult(JSON.stringify(envelope), true);
+}
+/** §4.8 "Server 正在关闭" row: refused without touching the capability. */
+function shuttingDownResult() {
+    return executionFailedResult('The server is shutting down; the call was not completed.');
+}
+/**
+ * Build the PD MCP server (not yet connected to any transport).
+ *
+ * Handler flow per §4.7/§4.8: shutdown/saturation gates → deadline-wrapped
+ * capability call → envelope assembly (serialize → 32 KiB budget → emit) →
+ * explicit isError mapping. Nothing here writes to stdout.
+ */
+export function createPdMcpServer(options) {
+    const { workspaceDir, host = null, deadlineMs = DEFAULT_DEADLINE_MS, callCapability = recallPrinciplePainsCapability, logSink = stderrSink, } = options;
+    const orphans = new OrphanLimiter();
+    const admissions = new AdmissionLimiter();
+    let shuttingDown = false;
+    const mcpServer = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    const log = createLogger(logSink, { host: host ?? 'unspecified' });
+    mcpServer.registerTool(TOOL_NAME, {
+        description: TOOL_DESCRIPTION,
+        // Static type-interop shim ONLY: our zod 4.6.7 type instantiation does
+        // not match the SDK's bundled zod-4.2-based generic constraint, so the
+        // overloads fall through to the raw-shape one. Runtime validation is
+        // unaffected — the SDK still validates every call against exactly this
+        // (fromJsonSchema-built) schema. NOT a validation bypass (rc-2 scope:
+        // untrusted-data validation stays fully runtime-checked).
+        inputSchema: toolProtocolSchema,
+        annotations: { readOnlyHint: true },
+    }, async (rawInput) => {
+        const startedAt = Date.now();
+        // §4.7 admission: reserve execution capacity SYNCHRONOUSLY at handler
+        // entry, before any await and before the capability is called. Without
+        // this, N concurrent requests all pass an orphan-count check while none
+        // has timed out yet and N > limit capability calls start.
+        if (shuttingDown) {
+            log('warn', 'tool_call_refused_shutting_down', { durationMs: Date.now() - startedAt });
+            return shuttingDownResult();
+        }
+        if (!admissions.tryAcquire()) {
+            log('warn', 'tool_call_refused_saturated', {
+                durationMs: Date.now() - startedAt,
+                active: admissions.active,
+                max: admissions.max,
+            });
+            return executionFailedResult('The server is already executing the maximum number of concurrent calls; retry shortly.');
+        }
+        // The window covers validation → capability → projection →
+        // serialization; validation of the parsed input is part of the race.
+        // The `finally` releases capacity when the UNDERLYING work actually
+        // settles — a deadline stops the wait, not the reservation. An orphan
+        // therefore keeps its slot until its promise resolves/rejects.
+        const outcome = await runWithDeadline(async () => {
+            try {
+                // The SDK already validated against the zod schema; parse again
+                // for the typed value (idempotent) and count it inside the window.
+                const parsed = toolInputSchema.parse(rawInput);
+                const envelope = await callCapability({
+                    workspaceDir,
+                    principleId: parsed.principleId,
+                    limit: parsed.limit,
+                });
+                const assembled = assembleResult(envelope);
+                if (assembled.ok)
+                    return { kind: 'envelope', result: assembled.result };
+                return { kind: 'overBudget', bytes: assembled.overBudgetBytes };
+            }
+            catch (err) {
+                // §4.8 非预期异常: map to a sanitized Adapter failure here — the
+                // raw exception (message/stack may carry paths or internals)
+                // must NEVER reach the SDK's default handler-error path.
+                return { kind: 'exception', errorKind: sanitizeErrorKind(err) };
+            }
+            finally {
+                admissions.release();
+            }
+        }, deadlineMs, (orphaned) => orphans.register(orphaned));
+        const durationMs = Date.now() - startedAt;
+        if (outcome.ok) {
+            switch (outcome.value.kind) {
+                case 'envelope': {
+                    log('info', 'tool_call_completed', { durationMs, resultKind: 'envelope' });
+                    return outcome.value.result;
+                }
+                case 'overBudget': {
+                    log('warn', 'tool_call_over_budget', { durationMs, bytes: outcome.value.bytes, budget: RESPONSE_BUDGET_BYTES });
+                    const failure = adapterFailureEnvelope('response_budget_exceeded', 'The response exceeded the 32 KiB MCP budget and was withheld without truncation.');
+                    const failureJson = JSON.stringify(failure);
+                    if (!withinBudget(failureJson)) {
+                        // Cannot happen (static shell), but fail loud over silent breakage.
+                        log('error', 'failure_envelope_over_budget', {});
+                    }
+                    return textResult(failureJson, true);
+                }
+                case 'exception': {
+                    // Sanitized category only — no message, no stack, no paths.
+                    log('error', 'tool_call_unexpected_exception', { durationMs, errorKind: outcome.value.errorKind });
+                    return executionFailedResult('The call failed unexpectedly; the error was logged server-side with a sanitized category only.');
+                }
+            }
+        }
+        // Deadline exceeded (§4.7): stop waiting, suppress the late result,
+        // report an Adapter execution failure. Not underlying cancellation:
+        // the capacity slot stays reserved until the orphan settles.
+        log('warn', 'tool_call_deadline_exceeded', {
+            durationMs,
+            deadlineMs,
+            active: admissions.active,
+            orphans: orphans.size,
+        });
+        return executionFailedResult(`The call exceeded the ${deadlineMs} ms deadline; the late result is suppressed and will not be delivered.`);
+    });
+    return {
+        mcpServer,
+        orphans,
+        admissions,
+        beginShutdown() {
+            shuttingDown = true;
+            log('info', 'shutdown_begun', { orphans: orphans.size, active: admissions.active });
+        },
+        isShuttingDown() {
+            return shuttingDown;
+        },
+    };
+}

package/pd-mcp-server/dist/version.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Server identity — SPEC-PD-MCP-GATE4-001 §9.3 release manifest anchor.
+ *
+ * SERVER_VERSION mirrors the package version through the release
+ * materialization step (`syncMcpServerVersionMirror` in
+ * scripts/release/lib/version-plan.mjs); changesets alone rewrites only
+ * package.json. A unit test pins it to package.json so the two cannot drift.
+ */
+export declare const SERVER_NAME: 'pd-mcp-server';
+export declare const SERVER_VERSION: '0.2.0';
+/** The only MCP SDK family/version this server is released against
+ * (Gate 4-A freeze, PD_MCP_GATE4A_REALITY_CHECK §3). Exact pin — no ranges. */
+export declare const MCP_SDK_PIN: '@modelcontextprotocol/server@2.4.0';

package/pd-mcp-server/dist/version.js

@@ -0,0 +1,13 @@
+/**
+ * Server identity — SPEC-PD-MCP-GATE4-001 §9.3 release manifest anchor.
+ *
+ * SERVER_VERSION mirrors the package version through the release
+ * materialization step (`syncMcpServerVersionMirror` in
+ * scripts/release/lib/version-plan.mjs); changesets alone rewrites only
+ * package.json. A unit test pins it to package.json so the two cannot drift.
+ */
+export const SERVER_NAME = 'pd-mcp-server';
+export const SERVER_VERSION = '0.2.0';
+/** The only MCP SDK family/version this server is released against
+ * (Gate 4-A freeze, PD_MCP_GATE4A_REALITY_CHECK §3). Exact pin — no ranges. */
+export const MCP_SDK_PIN = '@modelcontextprotocol/server@2.4.0';

package/pd-mcp-server/dist/workspace.d.ts

@@ -0,0 +1,23 @@
+export declare const WORKSPACE_DIR_ENV: 'PD_MCP_WORKSPACE_DIR';
+export declare const HOST_ENV: 'PD_MCP_HOST';
+export declare const KNOWN_HOSTS: readonly string[];
+export interface WorkspaceBinding {
+    readonly workspaceDir: string;
+    readonly host: string | null;
+}
+export type WorkspaceBindingResolution = {
+    readonly ok: true;
+    readonly binding: WorkspaceBinding;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly envVar: string;
+    readonly nextAction: string;
+};
+/**
+ * Resolve and validate the launch-time workspace binding from a process env
+ * (injected for testability; production passes `process.env`). Checks, in
+ * order: presence → non-empty string → absolute path → existing directory →
+ * (optional) host marker sanity. Any failure is terminal for the process.
+ */
+export declare function resolveWorkspaceBinding(env: Record<string, unknown>): WorkspaceBindingResolution;

package/pd-mcp-server/dist/workspace.js

@@ -0,0 +1,77 @@
+/**
+ * Startup workspace binding — SPEC-PD-MCP-GATE4-001 §3.5.
+ *
+ * The business `workspaceDir` is launch configuration, NEVER a model-supplied
+ * tool parameter. It arrives via `PD_MCP_WORKSPACE_DIR`, which the host
+ * plugin's PD-owned `mcp-binding.json` (through launcher.cjs) injects.
+ *
+ * Fail-closed everywhere: a missing/relative/nonexistent binding, an unknown
+ * host marker, or any attempt to smuggle a path through the tool input
+ * refuses to serve. There is NO `process.cwd()`, `HOME` or `USERPROFILE`
+ * fallback for business workspace resolution (§3.5: no implicit fallback).
+ *
+ * This module reads ONLY install/startup metadata (one env + one stat);
+ * business data stays behind the Gate 3 Capability.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export const WORKSPACE_DIR_ENV = 'PD_MCP_WORKSPACE_DIR';
+export const HOST_ENV = 'PD_MCP_HOST';
+export const KNOWN_HOSTS = ['codex', 'openclaw', 'workbuddy'];
+/**
+ * Resolve and validate the launch-time workspace binding from a process env
+ * (injected for testability; production passes `process.env`). Checks, in
+ * order: presence → non-empty string → absolute path → existing directory →
+ * (optional) host marker sanity. Any failure is terminal for the process.
+ */
+export function resolveWorkspaceBinding(env) {
+    const raw = env[WORKSPACE_DIR_ENV];
+    if (typeof raw !== 'string' || raw.length === 0) {
+        return {
+            ok: false,
+            reason: 'workspace binding env is missing or empty',
+            envVar: WORKSPACE_DIR_ENV,
+            nextAction: `Re-run the PD host setup (this writes the PD-owned mcp-binding.json and launches via launcher.cjs). Do not set ${WORKSPACE_DIR_ENV} by hand from agent context.`,
+        };
+    }
+    if (!path.isAbsolute(raw)) {
+        return {
+            ok: false,
+            reason: 'workspace binding is not an absolute path',
+            envVar: WORKSPACE_DIR_ENV,
+            nextAction: 'Re-run the PD host setup so the binding records the absolute governance workspace directory.',
+        };
+    }
+    let stat;
+    try {
+        stat = fs.statSync(raw);
+    }
+    catch {
+        return {
+            ok: false,
+            reason: 'workspace binding directory does not exist or is not readable',
+            envVar: WORKSPACE_DIR_ENV,
+            nextAction: 'Re-run the PD host setup; if the workspace was moved, re-install PD for this host so the binding is regenerated.',
+        };
+    }
+    if (!stat.isDirectory()) {
+        return {
+            ok: false,
+            reason: 'workspace binding is not a directory',
+            envVar: WORKSPACE_DIR_ENV,
+            nextAction: 'Re-run the PD host setup so the binding points at the governance workspace directory.',
+        };
+    }
+    const host = env[HOST_ENV];
+    if (host !== undefined) {
+        if (typeof host !== 'string' || !KNOWN_HOSTS.includes(host)) {
+            return {
+                ok: false,
+                reason: 'host marker is not one of the known PD hosts',
+                envVar: HOST_ENV,
+                nextAction: 'Re-run the PD host setup; the host marker is written by the PD installer and must not be edited.',
+            };
+        }
+    }
+    return { ok: true, binding: { workspaceDir: path.resolve(raw), host: typeof host === 'string' ? host : null } };
+}

package/pd-mcp-server/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@principles/pd-mcp-server",
+  "version": "0.2.0",
+  "description": "Principles Disciple MCP Server — the single shared MCP server implementation for the three PD hosts (Codex, OpenClaw, WorkBuddy). Read-only pain recall through the Gate 3 Capability (SPEC-PD-MCP-GATE4-001).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "clean": "node ../../scripts/build/clean-dist.mjs",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node ../../scripts/build/check-dist-hygiene.mjs",
+    "test": "npm run build && vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint \"src/**/*.ts\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.4.0",
+    "@principles/core": "file:../core",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.4.0",
+    "@types/node": "^26.4.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/csuzngjh/principles.git",
+    "directory": "packages/pd-mcp-server"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}