@principles/pd-mcp-server 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,73 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+     (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+     (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+     (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+     (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+     You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+Principles Disciple
+Copyright 2026 Principles Disciple Contributors

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @principles/pd-mcp-server
 
-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.
+Principles Disciple 的正式 MCP Server —— 三个宿主（Codex、OpenClaw、WorkBuddy）共享的**同一份** Server 实现（SPEC-PD-MCP-GATE4-001）。每个宿主以插件内置 MCP 配置启动自己的 Server 子进程，业务数据**只**经 Gate 3 Capability（`@principles/core/runtime-v2/pain-recall-capability`，OD-A v1 披露）读取。
+
+## 唯一 Tool：`pd_recall_principle_pains`（只读）
+
+| 契约 | 值 |
+|---|---|
+| 输入 | `principleId`（1..200，必填）、`limit`（1..10，默认 3）；其余属性一律拒绝（协议层校验 + Capability 层复验） |
+| 输出 | 单个 text content block，携带 `pd.capability.v1` JSON；不使用 structuredContent |
+| 响应预算 | ≤ 32768 UTF-8 bytes（32768 通过 / 32769 拒绝 → `unavailable` + `response_budget_exceeded`，`isError:true`，绝不静默截断） |
+| 调用截止 | 10 秒（handler 起算，含校验/Capability/投影/序列化；超时 = `tool_execution_failed`，迟到结果抑制；不宣称底层可取消） |
+| isError=true | 仅两类：披露断言失败；Adapter 执行失败（预算超限/超时/异常/关闭中）——普通业务状态一律非错误 |
+| 进程边界 | stdout 仅 MCP 协议消息；日志走 stderr（结构化脱敏 JSON）；无常驻 daemon |
+
+## 工作区绑定（fail-closed）
+
+业务 `workspaceDir` 是**启动配置**，绝不出现在 Tool 参数中。它由宿主插件的 PD 自有 `mcp-binding.json`（经 `launcher.cjs`）注入为环境变量 `PD_MCP_WORKSPACE_DIR`（可选 `PD_MCP_HOST` ∈ codex|openclaw|workbuddy）。绑定缺失/相对/不存在 → 启动即失败（stderr 一行结构化原因 + exit 1），**没有任何** `process.cwd()`/`HOME` 回退。
+
+## 架构守卫
+
+`src/__tests__/architecture-guards.test.ts` 机械保证：Core 零 MCP SDK 依赖；本包仅经 Capability 公共子路径访问业务；无 CLI 子进程查询；pd-cli 与本包互不依赖；SDK 精确锁版（`@modelcontextprotocol/server@2.4.0`）。
+
+## 构建 / 测试
+
+```bash
+npm run build   # tsc → dist/
+npm test        # build + vitest（协议契约 / 预算边界 / deadline / 绑定 / 真实进程 stdio / 架构守卫）
+```
+
+发布随 PD release 列车（changesets）；SDK 与 zod 均为精确锁版。

package/dist/budget.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Response budget — SPEC-PD-MCP-GATE4-001 §4.6 (Gate 4 Adapter responsibility;
+ * NOT a Core Capability constraint).
+ *
+ * The single text content block carries the `pd.capability.v1` JSON. Its
+ * UTF-8 byte size must be ≤ 32768: 32768 passes, 32769 is over budget.
+ * Over budget is a bounded failure envelope (`unavailable` +
+ * `response_budget_exceeded`), never a silent truncation, never a field-drop
+ * disguised as success. The failure envelope itself must fit the budget.
+ */
+export declare const RESPONSE_BUDGET_BYTES: 32768;
+/** UTF-8 byte length of the exact string that will be placed in the text
+ * content block — the measure the contract is written against. */
+export declare function measureTextBytes(text: string): number;
+export declare function withinBudget(text: string): boolean;

package/dist/budget.js

@@ -0,0 +1,19 @@
+/**
+ * Response budget — SPEC-PD-MCP-GATE4-001 §4.6 (Gate 4 Adapter responsibility;
+ * NOT a Core Capability constraint).
+ *
+ * The single text content block carries the `pd.capability.v1` JSON. Its
+ * UTF-8 byte size must be ≤ 32768: 32768 passes, 32769 is over budget.
+ * Over budget is a bounded failure envelope (`unavailable` +
+ * `response_budget_exceeded`), never a silent truncation, never a field-drop
+ * disguised as success. The failure envelope itself must fit the budget.
+ */
+export const RESPONSE_BUDGET_BYTES = 32768;
+/** UTF-8 byte length of the exact string that will be placed in the text
+ * content block — the measure the contract is written against. */
+export function measureTextBytes(text) {
+    return Buffer.byteLength(text, 'utf8');
+}
+export function withinBudget(text) {
+    return measureTextBytes(text) <= RESPONSE_BUDGET_BYTES;
+}

package/dist/deadline.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Call deadline — SPEC-PD-MCP-GATE4-001 §4.7 (Gate 4 Adapter responsibility).
+ *
+ * Every tool call gets at most `deadlineMs` (production: 10 s) counted from
+ * handler entry, covering input validation, capability call, projection and
+ * JSON serialization. The Gate 3 Capability exposes no AbortSignal, so this
+ * is HONEST non-cancellation: on expiry we stop waiting, suppress the late
+ * result (a timeout must never later be reported as success), and track the
+ * still-running operation in a bounded orphan set whose eventual settlement
+ * is observed — proving resources are released (§4.7). `Promise.race` here is
+ * explicitly NOT claimed as underlying cancellation.
+ */
+export declare const DEFAULT_DEADLINE_MS: 10000;
+/** Upper bound on concurrently EXECUTING capability calls (§4.7). Admission
+ * is reserved synchronously before the capability is called, so the bound is
+ * real even when every in-flight call later outlives its deadline. Small by
+ * design: a read-only recall that takes >10 s is already pathological; four
+ * concurrent ones is a stuck host, not load. */
+export declare const MAX_CONCURRENT_CALLS: 4;
+/** Upper bound on still-running timed-out operations. Orphans are a subset of
+ * admitted calls; this registry keeps their settlement observable even after
+ * the caller stopped waiting (§4.7 “限制仍在运行的超时任务数量”). */
+export declare const MAX_TRACKED_ORPHANS: 4;
+export type DeadlineOutcome<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly timedOut: true;
+};
+/**
+ * Run `fn` under a deadline. On timeout the returned promise settles
+ * `{ timedOut }` immediately while `fn`'s promise keeps running; it is handed
+ * to `onOrphan` (the caller registers it in the orphan limiter). If
+ * `onOrphan` returns false (limiter saturated), the caller must refuse new
+ * work — the operation is still tracked for settlement by the race itself.
+ */
+export declare function runWithDeadline<T>(fn: () => Promise<T>, deadlineMs: number, onOrphan?: (orphaned: Promise<T>) => boolean): Promise<DeadlineOutcome<T>>;
+/**
+ * Bounded registry of still-running timed-out operations. `register` refuses
+ * (returns false) once `max` orphans are unsettled; settled promises remove
+ * themselves, so the limit reflects *currently running* stragglers only.
+ */
+export declare class OrphanLimiter {
+    #private;
+    constructor(max?: number);
+    get size(): number;
+    get saturated(): boolean;
+    register(orphaned: Promise<unknown>): boolean;
+}
+/**
+ * Synchronous admission semaphore for executing capability calls (§4.7).
+ *
+ * The previous design only counted already-timed-out stragglers, so N requests
+ * could all pass the saturation check before any of them timed out and then
+ * start N > limit capability calls. Admission is now reserved at handler entry
+ * — BEFORE the capability is invoked — and released only when the underlying
+ * work actually settles (normal completion, exception, or an orphaned call
+ * that outlived its deadline). A timeout therefore stops the WAIT, never the
+ * capacity reservation.
+ */
+export declare class AdmissionLimiter {
+    #private;
+    constructor(max?: number);
+    get max(): number;
+    /** Number of admitted calls whose underlying work has not settled yet. */
+    get active(): number;
+    get saturated(): boolean;
+    /** Reserve one execution slot. Never awaits — the check and the reservation
+     * are one synchronous step, so concurrent handlers cannot both pass. */
+    tryAcquire(): boolean;
+    /** Release a previously reserved slot. Exactly one release per successful
+     * acquire; underflow is a programming error and fails loud. */
+    release(): void;
+}

package/dist/deadline.js

@@ -0,0 +1,136 @@
+/**
+ * Call deadline — SPEC-PD-MCP-GATE4-001 §4.7 (Gate 4 Adapter responsibility).
+ *
+ * Every tool call gets at most `deadlineMs` (production: 10 s) counted from
+ * handler entry, covering input validation, capability call, projection and
+ * JSON serialization. The Gate 3 Capability exposes no AbortSignal, so this
+ * is HONEST non-cancellation: on expiry we stop waiting, suppress the late
+ * result (a timeout must never later be reported as success), and track the
+ * still-running operation in a bounded orphan set whose eventual settlement
+ * is observed — proving resources are released (§4.7). `Promise.race` here is
+ * explicitly NOT claimed as underlying cancellation.
+ */
+export const DEFAULT_DEADLINE_MS = 10_000;
+/** Upper bound on concurrently EXECUTING capability calls (§4.7). Admission
+ * is reserved synchronously before the capability is called, so the bound is
+ * real even when every in-flight call later outlives its deadline. Small by
+ * design: a read-only recall that takes >10 s is already pathological; four
+ * concurrent ones is a stuck host, not load. */
+export const MAX_CONCURRENT_CALLS = 4;
+/** Upper bound on still-running timed-out operations. Orphans are a subset of
+ * admitted calls; this registry keeps their settlement observable even after
+ * the caller stopped waiting (§4.7 “限制仍在运行的超时任务数量”). */
+export const MAX_TRACKED_ORPHANS = 4;
+/**
+ * Run `fn` under a deadline. On timeout the returned promise settles
+ * `{ timedOut }` immediately while `fn`'s promise keeps running; it is handed
+ * to `onOrphan` (the caller registers it in the orphan limiter). If
+ * `onOrphan` returns false (limiter saturated), the caller must refuse new
+ * work — the operation is still tracked for settlement by the race itself.
+ */
+export async function runWithDeadline(fn, deadlineMs, onOrphan) {
+    const startedAt = Date.now();
+    let timer;
+    const timerPromise = new Promise((resolveTimer) => {
+        timer = setTimeout(() => resolveTimer(), deadlineMs);
+        // Never hold the event loop open for the deadline alone.
+        timer.unref?.();
+    });
+    const work = fn();
+    const winner = await Promise.race([
+        work.then((value) => ({ kind: 'value', value })),
+        timerPromise.then(() => ({ kind: 'timeout' })),
+    ]);
+    if (winner.kind === 'value') {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        // The timer cannot fire while synchronous work blocks the loop, so a value
+        // that raced in just before the deadline but finished assembling after it
+        // would otherwise be reported as an in-time success. The window covers
+        // validation → capability → projection → serialization (§4.7): past the
+        // deadline, this is a miss. The underlying promise already settled, so no
+        // orphan exists and no capacity is left reserved.
+        if (Date.now() - startedAt < deadlineMs)
+            return { ok: true, value: winner.value };
+        return { ok: false, timedOut: true };
+    }
+    if (onOrphan)
+        onOrphan(work);
+    // Observe settlement so a rejected orphan never becomes an unhandled
+    // rejection long after the caller stopped caring (resource hygiene).
+    void work.catch(() => undefined);
+    return { ok: false, timedOut: true };
+}
+/**
+ * Bounded registry of still-running timed-out operations. `register` refuses
+ * (returns false) once `max` orphans are unsettled; settled promises remove
+ * themselves, so the limit reflects *currently running* stragglers only.
+ */
+export class OrphanLimiter {
+    #max;
+    #orphans = new Set();
+    constructor(max = MAX_TRACKED_ORPHANS) {
+        this.#max = max;
+    }
+    get size() {
+        return this.#orphans.size;
+    }
+    get saturated() {
+        return this.#orphans.size >= this.#max;
+    }
+    register(orphaned) {
+        if (this.saturated)
+            return false;
+        const observed = orphaned.then(() => undefined, () => undefined);
+        this.#orphans.add(observed);
+        void observed.then(() => {
+            this.#orphans.delete(observed);
+        });
+        return true;
+    }
+}
+/**
+ * Synchronous admission semaphore for executing capability calls (§4.7).
+ *
+ * The previous design only counted already-timed-out stragglers, so N requests
+ * could all pass the saturation check before any of them timed out and then
+ * start N > limit capability calls. Admission is now reserved at handler entry
+ * — BEFORE the capability is invoked — and released only when the underlying
+ * work actually settles (normal completion, exception, or an orphaned call
+ * that outlived its deadline). A timeout therefore stops the WAIT, never the
+ * capacity reservation.
+ */
+export class AdmissionLimiter {
+    #max;
+    #active = 0;
+    constructor(max = MAX_CONCURRENT_CALLS) {
+        if (!Number.isInteger(max) || max < 1)
+            throw new Error('admission limit must be a positive integer');
+        this.#max = max;
+    }
+    get max() {
+        return this.#max;
+    }
+    /** Number of admitted calls whose underlying work has not settled yet. */
+    get active() {
+        return this.#active;
+    }
+    get saturated() {
+        return this.#active >= this.#max;
+    }
+    /** Reserve one execution slot. Never awaits — the check and the reservation
+     * are one synchronous step, so concurrent handlers cannot both pass. */
+    tryAcquire() {
+        if (this.saturated)
+            return false;
+        this.#active += 1;
+        return true;
+    }
+    /** Release a previously reserved slot. Exactly one release per successful
+     * acquire; underflow is a programming error and fails loud. */
+    release() {
+        if (this.#active <= 0)
+            throw new Error('admission release without a matching acquire');
+        this.#active -= 1;
+    }
+}

package/dist/envelope.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Tool result envelope assembly — SPEC-PD-MCP-GATE4-001 §4.6/§4.8, obeying
+ * Gate 3 v0.5 §10.1.
+ *
+ * `isError: true` is used for exactly two families (§4.8):
+ *   1. disclosure assertion failure (the withheld capability shell already
+ *      says `unavailable` + `disclosure_assertion_failed`);
+ *   2. Adapter execution failure — response_budget_exceeded,
+ *      tool_execution_failed (unexpected exception / 10 s deadline /
+ *      shutting down / saturated by orphaned timed-out calls).
+ * Ordinary business states (ok / no_matches / partial / not_found / plain
+ * unavailable / invalid_input) return the capability envelope verbatim with
+ * no isError marker.
+ *
+ * Adapter failure envelopes reuse the capability shell shape so the Agent
+ * always sees one `pd.capability.v1` JSON document. Messages carry a stable
+ * code + next action; they never contain stacks, paths, env values or raw
+ * business text (§4.8: no internal details to the Agent).
+ */
+import { type PainRecallCapabilityResult } from '@principles/core/runtime-v2/pain-recall-capability';
+/** MCP tool result as produced by the handler (single text content block,
+ * `structuredContent` intentionally never used — §4.6). The shapes match the
+ * SDK's expected result type (mutable content array + index signature). */
+export interface ToolResult {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError?: boolean;
+    [extra: string]: unknown;
+}
+export declare function textResult(text: string, isError?: boolean): ToolResult;
+/** Adapter failure envelope in the capability shell shape (§7.2 null form). */
+export declare function adapterFailureEnvelope(code: string, message: string): PainRecallCapabilityResult;
+/** §4.8 — does this capability envelope require `isError: true`?
+ * Only the disclosure assertion failure (the capability withheld its
+ * payload); every ordinary business status stays a normal result. */
+export declare function requiresIsError(envelope: PainRecallCapabilityResult): boolean;
+/**
+ * Assemble the final tool result from a capability envelope.
+ *
+ * Order: serialize → budget check → emit. Over budget returns
+ * `response_budget_exceeded` (Adapter execution failure, isError: true).
+ * The failure envelope is asserted to fit the budget itself (§4.6).
+ */
+export declare function assembleResult(envelope: PainRecallCapabilityResult): {
+    ok: true;
+    result: ToolResult;
+} | {
+    ok: false;
+    overBudgetBytes: number;
+};

package/dist/envelope.js

@@ -0,0 +1,63 @@
+/**
+ * Tool result envelope assembly — SPEC-PD-MCP-GATE4-001 §4.6/§4.8, obeying
+ * Gate 3 v0.5 §10.1.
+ *
+ * `isError: true` is used for exactly two families (§4.8):
+ *   1. disclosure assertion failure (the withheld capability shell already
+ *      says `unavailable` + `disclosure_assertion_failed`);
+ *   2. Adapter execution failure — response_budget_exceeded,
+ *      tool_execution_failed (unexpected exception / 10 s deadline /
+ *      shutting down / saturated by orphaned timed-out calls).
+ * Ordinary business states (ok / no_matches / partial / not_found / plain
+ * unavailable / invalid_input) return the capability envelope verbatim with
+ * no isError marker.
+ *
+ * Adapter failure envelopes reuse the capability shell shape so the Agent
+ * always sees one `pd.capability.v1` JSON document. Messages carry a stable
+ * code + next action; they never contain stacks, paths, env values or raw
+ * business text (§4.8: no internal details to the Agent).
+ */
+import { CAPABILITY_SCHEMA_VERSION, OD_A_DISCLOSURE_PROFILE, RECALL_PAIN_CAPABILITY_ID, } from '@principles/core/runtime-v2/pain-recall-capability';
+import { withinBudget } from './budget.js';
+export function textResult(text, isError) {
+    return isError === undefined
+        ? { content: [{ type: 'text', text }] }
+        : { content: [{ type: 'text', text }], isError };
+}
+/** Adapter failure envelope in the capability shell shape (§7.2 null form). */
+export function adapterFailureEnvelope(code, message) {
+    return {
+        schemaVersion: CAPABILITY_SCHEMA_VERSION,
+        capability: RECALL_PAIN_CAPABILITY_ID,
+        disclosureProfile: OD_A_DISCLOSURE_PROFILE,
+        status: 'unavailable',
+        data: null,
+        provenance: { workspaceBinding: 'configured', sources: [] },
+        warnings: [],
+        error: { code, message },
+        nextAction: {
+            code: 'retry_or_report',
+            message: 'If this repeats, run the PD host health check (pd health) and include the MCP stage in the report.',
+        },
+    };
+}
+/** §4.8 — does this capability envelope require `isError: true`?
+ * Only the disclosure assertion failure (the capability withheld its
+ * payload); every ordinary business status stays a normal result. */
+export function requiresIsError(envelope) {
+    return envelope.status === 'unavailable' && envelope.error?.code === 'disclosure_assertion_failed';
+}
+/**
+ * Assemble the final tool result from a capability envelope.
+ *
+ * Order: serialize → budget check → emit. Over budget returns
+ * `response_budget_exceeded` (Adapter execution failure, isError: true).
+ * The failure envelope is asserted to fit the budget itself (§4.6).
+ */
+export function assembleResult(envelope) {
+    const json = JSON.stringify(envelope);
+    if (withinBudget(json)) {
+        return { ok: true, result: textResult(json, requiresIsError(envelope) ? true : undefined) };
+    }
+    return { ok: false, overBudgetBytes: Buffer.byteLength(json, 'utf8') };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+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 declare function main(env?: Record<string, unknown>): Promise<number>;

package/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/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/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/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/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/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/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/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/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/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@principles/pd-mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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": "^2.0.0",
+    "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"
+  },
+  "gitHead": "d3355465b090daf098581cdb4c174634fe1e5279"
+}