@dsh-cc/mcp-config 0.5.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/mcp/mcp-config/README.md
+README.md: 62d41ce3b30d512ae62eb08004a417da863cc07b
+README.zh.md: 90596f74566303c721d7c92fb490f903a44ef29a

package/README.md

@@ -0,0 +1,103 @@
+# @dsh-cc/mcp-config
+
+English | [中文](README.zh.md)
+
+Claude Code-style MCP workspace-configuration loader: parses a `.mcp.json` document, validates it, expands environment substitutions, applies an enterprise allow/deny policy, and translates the accepted servers into `@dsh-cc/mcp-client` registrations ready to mount.
+
+This package owns the file→config *reading and validation* surface only. It performs no network I/O and mounts nothing; consumers feed its output to `@dsh-cc/mcp-client` instances.
+
+## Usage
+
+```ts
+import { buildRegistrations, type McpConfigPolicy } from '@dsh-cc/mcp-config'
+import { readFileSync } from 'node:fs'
+
+const body = JSON.parse(readFileSync('.mcp.json', 'utf8'))
+const policy: McpConfigPolicy = {
+  deny: (name) => name === 'blocked-saas',
+  allow: (name) => name !== 'experimental',
+}
+// registrations: mcp-client Config objects (with serverName), in stable config order
+const registrations = buildRegistrations(body, { env: process.env, policy })
+
+for (const config of registrations) {
+  await ctx.plugin(mcpClient, config)
+}
+```
+
+A typical `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
+    },
+    "web": {
+      "type": "http",
+      "url": "https://mcp.example.com/mcp",
+      "headers": { "Authorization": "Bearer ${MCP_TOKEN}" }
+    },
+    "feed": {
+      "type": "sse",
+      "url": "https://sse.example.com/events"
+    }
+  }
+}
+```
+
+## Server definition types
+
+A `.mcp.json` `mcpServers` map values are the Claude Code server definitions:
+
+| Shape | `type` | Required | Notes |
+|---|---|---|---|
+| `stdio` | omitted or `"stdio"` | `command` | `args`, `env`, `cwd` optional |
+| `http` | `"http"` (also accepts legacy `"streamable-http"`) | `url` | `headers` optional |
+| `sse` | `"sse"` | `url` | `headers` optional |
+
+`mcpServers` may be an object keyed by server name, or an array of such objects (the array form rejects a name that appears twice).
+
+## Config mapping
+
+Each accepted server translates to one `@dsh-cc/mcp-client` `Config`:
+
+- The server **name** becomes `serverName`, the public namespace for the model-facing tool names (`mcp__<serverName>__*`).
+- `command`-based definitions map to the `stdio` transport.
+- `http` / `streamable-http` definitions map to the `streamable-http` transport.
+- `sse` definitions map to the `sse` transport.
+- Registrations default `toolCallTimeoutMs` to 60000 and `failOnStartupError` to `true` (a malformed or unreachable server fails the load loudly rather than silently activating without tools).
+
+## Environment expansion
+
+Strings in `command`, `args`, `cwd`, `env` values, `url`, and `headers` support:
+
+- `${VAR}` — substituted with the environment value; **throws at load** when the variable is not set.
+- `${VAR:-default}` — falls back to `default` when the variable is unset or empty.
+- `$$` — a literal `$`.
+
+Expansion reads `process.env` by default or the `env` option passed to `buildRegistrations` / `applyEnv`.
+
+## Enterprise allow/deny policy
+
+Pass a `McpConfigPolicy` to `buildRegistrations` to gate servers before translation:
+
+- `deny(name, entry)` — returning `true` drops the server (runs first, wins).
+- `allow(name, entry)` — when present, only servers where it returns `true` are kept.
+
+Hooks receive the raw `McpServerEntry`; they must be synchronous and total. Policy happens after parsing and validation but before translation, in stable config order, and rejected servers never reach the client.
+
+## Errors
+
+Malformed configuration throws at load — a non-object body, a missing or non-map `mcpServers`, a duplicated name, an unknown transport type, a missing required `command`/`url`, or an unset environment variable. Fail loud beats silently skipping a missing referent.
+
+## API
+
+- `parseMcpServers(body)` — validate the `mcpServers` map and return it; throws on malformed input.
+- `dedupServers(map)` — normalize a parsed map into a stable `McpServerSpec[]`; throws on a duplicated name.
+- `normalizeServerEntry(entry)` — one raw entry → an mcp-client `Config` (no env expansion), validating required fields.
+- `applyEnv(config, env?)` — expand `${...}` substitutions in one normalized config.
+- `expandEnv(value, env)` — expand one string's substitutions.
+- `buildRegistrations(body, { env?, policy? })` — full pipeline to mcp-client registrations.

package/README.zh.md

@@ -0,0 +1,103 @@
+# @dsh-cc/mcp-config
+
+[English](README.md) | 中文
+
+Claude Code 风格的 MCP 工作区配置加载器：解析 `.mcp.json` 文档，进行校验、环境变量展开、企业级 allow/deny 策略过滤，并把通过的服务转换为可直接挂载的 `@dsh-cc/mcp-client` 注册项。
+
+本包只负责文件→配置的**读取与校验**。它不做任何网络 I/O，也不自行挂载；下游把输出喂给 `@dsh-cc/mcp-client` 实例。
+
+## 用法
+
+```ts
+import { buildRegistrations, type McpConfigPolicy } from '@dsh-cc/mcp-config'
+import { readFileSync } from 'node:fs'
+
+const body = JSON.parse(readFileSync('.mcp.json', 'utf8'))
+const policy: McpConfigPolicy = {
+  deny: (name) => name === 'blocked-saas',
+  allow: (name) => name !== 'experimental',
+}
+// registrations: mcp-client Config objects (with serverName), in stable config order
+const registrations = buildRegistrations(body, { env: process.env, policy })
+
+for (const config of registrations) {
+  await ctx.plugin(mcpClient, config)
+}
+```
+
+典型的 `.mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
+    },
+    "web": {
+      "type": "http",
+      "url": "https://mcp.example.com/mcp",
+      "headers": { "Authorization": "Bearer ${MCP_TOKEN}" }
+    },
+    "feed": {
+      "type": "sse",
+      "url": "https://sse.example.com/events"
+    }
+  }
+}
+```
+
+## 服务定义类型
+
+`.mcp.json` 的 `mcpServers` 值为 Claude Code 服务定义：
+
+| 形态 | `type` | 必填 | 说明 |
+|---|---|---|---|
+| `stdio` | 省略或 `"stdio"` | `command` | `args`、`env`、`cwd` 可选 |
+| `http` | `"http"`（也接受旧式 `"streamable-http"`） | `url` | `headers` 可选 |
+| `sse` | `"sse"` | `url` | `headers` 可选 |
+
+`mcpServers` 可以是按服务名索引的对象，也可以是若干此类对象的数组（数组形式会拒绝重复出现的服务名）。
+
+## 配置映射
+
+每个通过的服务转换为一个 `@dsh-cc/mcp-client` `Config`：
+
+- 服务**名**成为 `serverName`，即模型可见工具名的公共命名空间（`mcp__<serverName>__*`）。
+- 基于 `command` 的定义映射为 `stdio` 传输。
+- `http` / `streamable-http` 定义映射为 `streamable-http` 传输。
+- `sse` 定义映射为 `sse` 传输。
+- 注册项默认 `toolCallTimeoutMs` 为 60000、`failOnStartupError` 为 `true`（坏配置或不可达服服务在加载时响亮失败，而非静默地无工具激活）。
+
+## 环境变量展开
+
+`command`、`args`、`cwd`、`env` 值、`url`、`headers` 中的字符串支持：
+
+- `${VAR}` —— 用环境变量值替换；**变量未设置时在加载期抛错**。
+- `${VAR:-default}` —— 变量未设置或为空时回退到 `default`。
+- `$$` —— 一个字面量 `$`。
+
+展开默认读取 `process.env`，也可传入 `buildRegistrations`/`applyEnv` 的 `env` 选项。
+
+## 企业级 allow/deny 策略
+
+向 `buildRegistrations` 传入 `McpConfigPolicy` 以在转换前过滤服务：
+
+- `deny(name, entry)` —— 返回 `true` 时丢弃该服务（先执行，优先级更高）。
+- `allow(name, entry)` —— 存在时，只有返回 `true` 的服务被保留。
+
+钩子接收原始 `McpServerEntry`，必须同步且收敛；抛出的钩子会中止整个加载。策略发生在解析与校验之后、转换之前，按稳定配置顺序执行；被拒绝的服务永远不会进入客户端。
+
+## 错误
+
+格式错误的配置在加载期抛错——非对象 body、缺失或非映射的 `mcpServers`、重复的服务名、未知传输类型、缺少必填的 `command`/`url`、或未设置的环境变量。响亮失败胜过静默跳过缺失引用。
+
+## API
+
+- `parseMcpServers(body)` —— 校验 `mcpServers` 映射并返回；畸形输入抛错。
+- `dedupServers(map)` —— 将解析后的映射规范化为稳定的 `McpServerSpec[]`；重复服务名抛错。
+- `normalizeServerEntry(entry)` —— 单个原始条目 → mcp-client `Config`（不展开环境变量），校验必填字段。
+- `applyEnv(config, env?)` —— 在一个规范化配置中展开 `${...}` 替换。
+- `expandEnv(value, env)` —— 展开单个字符串的替换。
+- `buildRegistrations(body, { env?, policy? })` —— 到 mcp-client 注册项的完整流水线。

package/lib/index.d.ts

@@ -0,0 +1,146 @@
+/**
+ * MCP workspace-configuration loader (`@dsh-cc/mcp-config`).
+ *
+ * Parses a Claude Code-style `.mcp.json` document — the `mcpServers` map of
+ * stdio / HTTP(S) / SSE server definitions — validates it (malformed input
+ * throws at load), expands `${VAR}` and `${VAR:-default}` environment
+ * substitutions, dedupes server names, applies an enterprise allow/deny policy,
+ * and translates the accepted servers into `@dsh-cc/mcp-client`
+ * registrations ready for mount.
+ *
+ * The package owns the file→config *reading and validation* surface only; it
+ * performs no network I/O and mounts nothing itself. Consumers translate the
+ * returned registrations into mcp-client plugin instances.
+ *
+ * Two side modules extend that surface: `src/paths.ts` adds side-effect-free
+ * default-path classification and per-file server-name reads, and
+ * `src/migrate.ts` is the package's only file-WRITING surface — the atomic,
+ * user-invoked `/mcp migrate` import into `$DSH_HOME/.mcp.json`.
+ *
+ * @module @dsh-cc/mcp-config
+ */
+import type { Config } from '@dsh-cc/mcp-client';
+/**
+ * A `.mcp.json` server definition before transport normalization.
+ * `stdio` servers omit `type` (the Claude Code default) or set it explicitly;
+ * network servers set `http` / `sse` (or Claude Code's legacy `streamable-http`).
+ */
+export interface McpServerEntry {
+    /** `stdio` (default when absent), `http`, or `sse`. */
+    type?: 'stdio' | 'http' | 'sse' | 'streamable-http';
+    /** Stdio executable (required for the stdio transport). */
+    command?: string;
+    /** Arguments passed directly, without shell interpolation. */
+    args?: string[];
+    /** Extra env vars merged on top of scrubbed ambient env. */
+    env?: Record<string, string>;
+    /** Working directory for the child process. */
+    cwd?: string;
+    /** MCP endpoint URL (required for http/sse transports). */
+    url?: string;
+    /** Additional headers attached to MCP requests. */
+    headers?: Record<string, string>;
+}
+/** A `.mcp.json` document body: a map (or deduping array) of server definitions. */
+export type McpConfigFile = {
+    mcpServers: Record<string, McpServerEntry>;
+} | {
+    mcpServers: Array<Record<string, McpServerEntry>>;
+};
+/** A normalized mcp-client transport config, before the `serverName` is set. */
+export type McpTransport = {
+    transport: 'stdio';
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    cwd: string;
+    toolCallTimeoutMs: number;
+    failOnStartupError: boolean;
+} | {
+    transport: 'streamable-http' | 'sse';
+    url: string;
+    headers: Record<string, string>;
+    toolCallTimeoutMs: number;
+    failOnStartupError: boolean;
+};
+/** Named, validated, normalized server definition. */
+export interface McpServerSpec {
+    /** Server name from the configuration key; becomes the mcp-client `serverName`. */
+    name: string;
+    /** Normalized client transport config (environment still unexpanded). */
+    entry: McpTransport;
+}
+/**
+ * Enterprise gate over the configured servers. `deny` runs first and wins; a
+ * name allowed by neither is dropped. Order is stable config order. Hooks must
+ * be synchronous and total; a throwing hook aborts the whole load.
+ */
+export interface McpConfigPolicy {
+    /** Deny a server by name/entry; returning `true` drops it. */
+    deny?: (name: string, entry: McpServerEntry) => boolean;
+    /** Allow a server by name/entry; returning `true` keeps it (after `deny`). */
+    allow?: (name: string, entry: McpServerEntry) => boolean;
+}
+/**
+ * Resolve one environment substitution in `value`: `${VAR}` requires the
+ * variable to be set (throwing otherwise) and `${VAR:-default}` falls back to
+ * `default` when the variable is unset or empty. Doubled `$$` escapes a literal
+ * `$`. Values with neither form are returned unchanged.
+ *
+ * @param value - raw string possibly containing `${VAR}` / `${VAR:-default}`.
+ * @param env - environment lookup; an unset key is `undefined`.
+ * @returns the fully expanded string.
+ */
+export declare function expandEnv(value: string, env: Record<string, string | undefined>): string;
+/**
+ * Normalize a raw server entry into an mcp-client transport config, validating
+ * transport-specific required fields. Malformed entries throw at load.
+ *
+ * @param entry - raw `.mcp.json` server definition.
+ * @returns a normalized transport config (environment not yet expanded).
+ */
+export declare function normalizeServerEntry(entry: McpServerEntry): McpTransport;
+/**
+ * Expand environment substitutions in a normalized server entry.
+ * @param entry - a normalized transport config before expansion.
+ * @param env - environment lookup; defaults to `process.env`.
+ * @returns a new config with every `${...}` substitution resolved.
+ */
+export declare function applyEnv(entry: McpTransport, env?: Record<string, string | undefined>): McpTransport;
+/**
+ * Read and validate the `mcpServers` map from a `.mcp.json` body.
+ * @param body - parsed JSON document (or its `mcpServers` value).
+ * @returns the raw name→entry map, validated.
+ */
+export declare function parseMcpServers(body: unknown): Record<string, McpServerEntry>;
+/**
+ * Normalize a parsed server map into a stable ordered list. The map form cannot
+ * contain duplicate keys, so this is primarily the revalidation/normalization
+ * pass that also feeds environment expansion.
+ * @param servers - validated name→entry map.
+ * @returns `[name, normalized spec]` pairs in stable order.
+ */
+export declare function dedupServers(servers: Record<string, McpServerEntry>): McpServerSpec[];
+/**
+ * Collapse a Claude Code server name into the mcp-client `[A-Za-z0-9_-]{1,32}` tool-prefix contract.
+ */
+export declare function normalizeServerName(name: string): string;
+/**
+ * Full pipeline: parse, validate, expand environment, dedupe, apply policy,
+ * and translate to mcp-client registrations. Malformed or unknown input throws
+ * at load; policy rejects are dropped silently in stable config order.
+ * @param body - parsed `.mcp.json` body.
+ * @param options - env lookups and enterprise policy.
+ * @returns accepted servers as mcp-client `Config` objects (with `serverName`).
+ */
+export declare function buildRegistrations(body: McpConfigFile, options?: {
+    env?: Record<string, string | undefined>;
+    policy?: McpConfigPolicy;
+    deferStartupConnect?: boolean;
+}): Config[];
+export type { Config };
+export { claudeOnlyServers, readMcpServerNames, resolveDefaultMcpPaths, } from './paths.ts';
+export type { ClaudeOnlySource, McpPathInputs, McpServerNames, ResolvedMcpPaths } from './paths.ts';
+export { migrateMcpServers } from './migrate.ts';
+export type { McpMigrationResult, McpMigrationSourceReport } from './migrate.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/index.js

@@ -0,0 +1,230 @@
+/**
+ * MCP workspace-configuration loader (`@dsh-cc/mcp-config`).
+ *
+ * Parses a Claude Code-style `.mcp.json` document — the `mcpServers` map of
+ * stdio / HTTP(S) / SSE server definitions — validates it (malformed input
+ * throws at load), expands `${VAR}` and `${VAR:-default}` environment
+ * substitutions, dedupes server names, applies an enterprise allow/deny policy,
+ * and translates the accepted servers into `@dsh-cc/mcp-client`
+ * registrations ready for mount.
+ *
+ * The package owns the file→config *reading and validation* surface only; it
+ * performs no network I/O and mounts nothing itself. Consumers translate the
+ * returned registrations into mcp-client plugin instances.
+ *
+ * Two side modules extend that surface: `src/paths.ts` adds side-effect-free
+ * default-path classification and per-file server-name reads, and
+ * `src/migrate.ts` is the package's only file-WRITING surface — the atomic,
+ * user-invoked `/mcp migrate` import into `$DSH_HOME/.mcp.json`.
+ *
+ * @module @dsh-cc/mcp-config
+ */
+/** Whether a env lookup value counts as "set" (present and not the empty string). */
+function isSet(value) {
+    return value !== undefined && value !== '';
+}
+/**
+ * Resolve one environment substitution in `value`: `${VAR}` requires the
+ * variable to be set (throwing otherwise) and `${VAR:-default}` falls back to
+ * `default` when the variable is unset or empty. Doubled `$$` escapes a literal
+ * `$`. Values with neither form are returned unchanged.
+ *
+ * @param value - raw string possibly containing `${VAR}` / `${VAR:-default}`.
+ * @param env - environment lookup; an unset key is `undefined`.
+ * @returns the fully expanded string.
+ */
+export function expandEnv(value, env) {
+    return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}|\$\$/g, (match, name, fallback) => {
+        if (match === '$$')
+            return '$';
+        const key = name;
+        const raw = env[key];
+        if (isSet(raw))
+            return raw;
+        if (fallback !== undefined)
+            return fallback;
+        // A present-but-empty value with no fallback expands to the empty string
+        // rather than throwing; only a truly unset variable is an error.
+        if (raw === '')
+            return '';
+        throw new Error(`dsh-mcp-config: environment variable "${key}" is not set`);
+    });
+}
+/**
+ * Normalize a raw server entry into an mcp-client transport config, validating
+ * transport-specific required fields. Malformed entries throw at load.
+ *
+ * @param entry - raw `.mcp.json` server definition.
+ * @returns a normalized transport config (environment not yet expanded).
+ */
+export function normalizeServerEntry(entry) {
+    // Widen to `string` so an at-runtime unknown transport (from a buggy or
+    // future `.mcp.json`) still reaches the throwing `default` below rather than
+    // being narrowed away by the closed union.
+    const type = entry.type;
+    switch (type) {
+        case undefined:
+        case 'stdio': {
+            if (typeof entry.command !== 'string' || entry.command.length === 0) {
+                throw new Error('dsh-mcp-config: stdio server requires a "command"');
+            }
+            return {
+                transport: 'stdio',
+                command: entry.command,
+                args: entry.args ?? [],
+                env: entry.env ?? {},
+                cwd: entry.cwd ?? '',
+                toolCallTimeoutMs: 60_000,
+                failOnStartupError: true,
+            };
+        }
+        case 'http':
+        case 'streamable-http':
+            return networkConfig('streamable-http', entry);
+        case 'sse':
+            return networkConfig('sse', entry);
+        default:
+            throw new Error(`dsh-mcp-config: unsupported MCP transport "${type}"`);
+    }
+}
+/** Build a network transport config, requiring a valid `url`. */
+function networkConfig(transport, entry) {
+    if (typeof entry.url !== 'string' || entry.url.length === 0) {
+        throw new Error(`dsh-mcp-config: ${transport} server requires a "url"`);
+    }
+    return {
+        transport,
+        url: entry.url,
+        headers: entry.headers ?? {},
+        toolCallTimeoutMs: 60_000,
+        failOnStartupError: true,
+    };
+}
+/** Expand every env substitution inside one normalized transport config. */
+function expandConfig(config, env) {
+    if (config.transport === 'stdio') {
+        return {
+            ...config,
+            command: expandEnv(config.command, env),
+            args: config.args.map(a => expandEnv(a, env)),
+            env: Object.fromEntries(Object.entries(config.env).map(([k, v]) => [k, expandEnv(v, env)])),
+            cwd: expandEnv(config.cwd, env),
+        };
+    }
+    return {
+        ...config,
+        url: expandEnv(config.url, env),
+        headers: Object.fromEntries(Object.entries(config.headers).map(([k, v]) => [k, expandEnv(v, env)])),
+    };
+}
+/**
+ * Expand environment substitutions in a normalized server entry.
+ * @param entry - a normalized transport config before expansion.
+ * @param env - environment lookup; defaults to `process.env`.
+ * @returns a new config with every `${...}` substitution resolved.
+ */
+export function applyEnv(entry, env = process.env) {
+    return expandConfig(entry, env);
+}
+/**
+ * Read and validate the `mcpServers` map from a `.mcp.json` body.
+ * @param body - parsed JSON document (or its `mcpServers` value).
+ * @returns the raw name→entry map, validated.
+ */
+export function parseMcpServers(body) {
+    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+        throw new Error('dsh-mcp-config: config body must be an object');
+    }
+    const servers = body.mcpServers;
+    if (servers === undefined)
+        throw new Error('dsh-mcp-config: config must declare "mcpServers"');
+    const map = {};
+    if (Array.isArray(servers)) {
+        for (const group of servers) {
+            if (group === null || typeof group !== 'object' || Array.isArray(group)) {
+                throw new Error('dsh-mcp-config: each mcpServers array entry must be a name→definition object');
+            }
+            for (const [name, entry] of Object.entries(group)) {
+                if (Object.hasOwn(map, name))
+                    throw new Error(`dsh-mcp-config: duplicate server name "${name}"`);
+                map[name] = entry;
+            }
+        }
+        return map;
+    }
+    if (typeof servers !== 'object' || servers === null) {
+        throw new Error('dsh-mcp-config: "mcpServers" must be an object or array of objects');
+    }
+    Object.assign(map, servers);
+    return map;
+}
+/**
+ * Normalize a parsed server map into a stable ordered list. The map form cannot
+ * contain duplicate keys, so this is primarily the revalidation/normalization
+ * pass that also feeds environment expansion.
+ * @param servers - validated name→entry map.
+ * @returns `[name, normalized spec]` pairs in stable order.
+ */
+export function dedupServers(servers) {
+    const specs = [];
+    for (const [name, entry] of Object.entries(servers)) {
+        specs.push({ name, entry: normalizeServerEntry(entry) });
+    }
+    return specs;
+}
+/** Recover the original raw entry for policy hooks. */
+function findOriginal(name, body) {
+    const servers = body.mcpServers;
+    if (Array.isArray(servers)) {
+        for (const group of servers)
+            if (Object.hasOwn(group, name))
+                return group[name];
+        return undefined;
+    }
+    return servers[name];
+}
+/**
+ * Collapse a Claude Code server name into the mcp-client `[A-Za-z0-9_-]{1,32}` tool-prefix contract.
+ */
+export function normalizeServerName(name) {
+    const normalized = name.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 32);
+    // An all-invalid-char name would collapse to '' — fall back to a dash so the pattern still matches.
+    return normalized === '' ? '-' : normalized;
+}
+/**
+ * Full pipeline: parse, validate, expand environment, dedupe, apply policy,
+ * and translate to mcp-client registrations. Malformed or unknown input throws
+ * at load; policy rejects are dropped silently in stable config order.
+ * @param body - parsed `.mcp.json` body.
+ * @param options - env lookups and enterprise policy.
+ * @returns accepted servers as mcp-client `Config` objects (with `serverName`).
+ */
+export function buildRegistrations(body, options = {}) {
+    const env = options.env ?? process.env;
+    const configs = [];
+    for (const { name, entry: raw } of dedupServers(parseMcpServers(body))) {
+        const original = findOriginal(name, body) ?? {};
+        if (options.policy?.deny?.(name, original) === true)
+            continue;
+        if (options.policy?.allow !== undefined && !options.policy.allow(name, original))
+            continue;
+        const expanded = expandConfig(raw, env);
+        // Policy hooks and findOriginal above see the ORIGINAL name; only the
+        // emitted mcp-client `serverName` (the tool-name prefix) is normalized.
+        // `deferStartupConnect` opts the caller into non-blocking mounts; because
+        // fail-fast startup forces fully blocking behavior in mcp-client, the
+        // deferral also downgrades the normalized `failOnStartupError: true` so
+        // the two flags never contradict each other.
+        configs.push({
+            ...expanded,
+            serverName: normalizeServerName(name),
+            ...(options.deferStartupConnect === true
+                ? { deferStartupConnect: true, failOnStartupError: false }
+                : {}),
+        });
+    }
+    return configs;
+}
+export { claudeOnlyServers, readMcpServerNames, resolveDefaultMcpPaths, } from "./paths.js";
+export { migrateMcpServers } from "./migrate.js";
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@dsh-cc/mcp-config`.
+ * @module @dsh-cc/mcp-config/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "mcp-config-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,oCAAoC;AACpC,eAAO,MAAM,IAAI,yBAAyB,CAAA;AAC1C,2EAA2E;AAC3E,eAAO,MAAM,MAAM,UAAiB,CAAA;AASpC;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,OAAO,KAAG,OAAO,CAAC,MAAM,IAAI,CACU,CAAA"}

package/lib/invariant.js

@@ -0,0 +1,23 @@
+/**
+ * Package-owned invariant companion for `@dsh-cc/mcp-config`.
+ * @module @dsh-cc/mcp-config/invariant
+ */
+const PACKAGE_NAME = '@dsh-cc/mcp-config';
+/** Cordis companion plugin name. */
+export const name = 'mcp-config-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: aside from `migrate.ts`'s atomic, user-invoked file
+ * write, mcp-config produces registrations and introduces no live registries
+ * of its own to reconcile.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/invariant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.js","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,YAAY,GAAG,oBAAoB,CAAA;AAEzC,oCAAoC;AACpC,MAAM,CAAC,MAAM,IAAI,GAAG,sBAAsB,CAAA;AAC1C,2EAA2E;AAC3E,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,YAAY,CAAC,CAAA;AAEpC;;;;GAIG;AACH,MAAM,OAAO,GAAuB,GAAG,EAAE,GAAE,CAAC,CAAA;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,GAAY,EAAuB,EAAE,CACzD,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAA;AACjE,sBAAsB"}

package/lib/migrate.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The package's ONLY file-WRITING surface: `/mcp migrate` importing Claude
+ * Code MCP servers into `$DSH_HOME/.mcp.json`.
+ *
+ * `migrateMcpServers` copies raw `mcpServers` entries verbatim — no env
+ * expansion, no name normalization, no transport reshaping (those belong to
+ * load time; round-tripping them here would corrupt the config). The Claude
+ * Code source files are never modified. Existing target names always win, the
+ * write is atomic (temp file + same-dir rename), and a `.bak` backup is made
+ * only when an existing target is overwritten. Note the backup duplicates any
+ * secrets inside `env` / `headers` entries.
+ *
+ * @module @dsh-cc/mcp-config/migrate
+ */
+/** Per-source migration outcome, in argument order. */
+export interface McpMigrationSourceReport {
+    /** The source file path. */
+    path: string;
+    /** Server names this source contributed (empty when it failed). */
+    servers: string[];
+    /** Present when the source was unreadable/unparseable; its error message. */
+    error?: string;
+}
+/** Full result of one `migrateMcpServers` run. */
+export interface McpMigrationResult {
+    /** The migration target file. */
+    target: string;
+    /** Server names written by this run. */
+    added: string[];
+    /** Names already present in the target (never overwritten). */
+    kept: string[];
+    /** Cross-source collisions: which source kept vs. skipped each name. */
+    sourceConflicts: {
+        name: string;
+        kept: string;
+        skipped: string;
+    }[];
+    /** Per-source reports, in argument order. */
+    sources: McpMigrationSourceReport[];
+    /** `false` when nothing needed adding: no write, no backup (idempotent). */
+    wrote: boolean;
+    /** Backup path, set only when an existing target was overwritten. */
+    backup?: string;
+}
+/**
+ * Import servers from source config files into a target `.mcp.json`.
+ *
+ * @param options - `sources` (Claude Code config files, read independently)
+ * and `target` (typically `$DSH_HOME/.mcp.json`).
+ * @returns the full migration report. When nothing needs adding the target is
+ * untouched and `wrote` is `false`.
+ * @throws when the existing target is unparseable or its `mcpServers` fails
+ * validation, or when the atomic write itself fails (the temp file is removed
+ * and the error names the target path).
+ */
+export declare function migrateMcpServers(options: {
+    sources: string[];
+    target: string;
+}): McpMigrationResult;
+//# sourceMappingURL=migrate.d.ts.map

package/lib/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,uDAAuD;AACvD,MAAM,WAAW,wBAAwB;IACvC,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,wCAAwC;IACxC,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,+DAA+D;IAC/D,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,wEAAwE;IACxE,eAAe,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAClE,6CAA6C;IAC7C,OAAO,EAAE,wBAAwB,EAAE,CAAA;IACnC,4EAA4E;IAC5E,KAAK,EAAE,OAAO,CAAA;IACd,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,kBAAkB,CAkFpG"}

package/lib/migrate.js

@@ -0,0 +1,138 @@
+/**
+ * The package's ONLY file-WRITING surface: `/mcp migrate` importing Claude
+ * Code MCP servers into `$DSH_HOME/.mcp.json`.
+ *
+ * `migrateMcpServers` copies raw `mcpServers` entries verbatim — no env
+ * expansion, no name normalization, no transport reshaping (those belong to
+ * load time; round-tripping them here would corrupt the config). The Claude
+ * Code source files are never modified. Existing target names always win, the
+ * write is atomic (temp file + same-dir rename), and a `.bak` backup is made
+ * only when an existing target is overwritten. Note the backup duplicates any
+ * secrets inside `env` / `headers` entries.
+ *
+ * @module @dsh-cc/mcp-config/migrate
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { parseMcpServers } from "./index.js";
+/**
+ * Import servers from source config files into a target `.mcp.json`.
+ *
+ * @param options - `sources` (Claude Code config files, read independently)
+ * and `target` (typically `$DSH_HOME/.mcp.json`).
+ * @returns the full migration report. When nothing needs adding the target is
+ * untouched and `wrote` is `false`.
+ * @throws when the existing target is unparseable or its `mcpServers` fails
+ * validation, or when the atomic write itself fails (the temp file is removed
+ * and the error names the target path).
+ */
+export function migrateMcpServers(options) {
+    const { sources, target } = options;
+    // Target first: its existing names always win, and a broken target aborts
+    // with nothing written.
+    const targetExisted = existsSync(target);
+    const targetRoot = readTargetRoot(target);
+    const isMap = !Array.isArray(targetRoot.mcpServers);
+    const existing = targetRoot.mcpServers === undefined ? {} : parseMcpServers(targetRoot);
+    const written = new Map(Object.entries(existing));
+    const result = {
+        target,
+        added: [],
+        kept: [],
+        sourceConflicts: [],
+        sources: [],
+        wrote: false,
+    };
+    const addedEntries = [];
+    for (const path of sources) {
+        let entries;
+        try {
+            entries = parseMcpServers(JSON.parse(readFileSync(path, 'utf8')));
+        }
+        catch (error) {
+            result.sources.push({ path, servers: [], error: error.message });
+            continue;
+        }
+        const names = [];
+        for (const [name, entry] of Object.entries(entries)) {
+            if (targetExisted && existing[name] !== undefined) {
+                if (!result.kept.includes(name))
+                    result.kept.push(name);
+                continue;
+            }
+            if (written.has(name)) {
+                // First source wins across sources; later declarations are skipped.
+                const keptBy = result.sources.find(report => report.servers.includes(name)).path;
+                result.sourceConflicts.push({ name, kept: keptBy, skipped: path });
+                continue;
+            }
+            written.set(name, entry);
+            names.push(name);
+            addedEntries.push([name, entry]);
+        }
+        result.sources.push({ path, servers: names });
+    }
+    result.added = addedEntries.map(([name]) => name);
+    if (addedEntries.length === 0)
+        return result;
+    // Preserve the target's other top-level keys and its map-vs-array shape.
+    const output = { ...targetRoot };
+    if (isMap) {
+        output.mcpServers = { ...existing, ...Object.fromEntries(addedEntries) };
+    }
+    else {
+        // Array form gets exactly ONE appended group object.
+        output.mcpServers = [...targetRoot.mcpServers, Object.fromEntries(addedEntries)];
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    let backup;
+    if (targetExisted) {
+        // The backup duplicates any secrets inside env/headers entries.
+        backup = `${target}.bak`;
+        copyFileSync(target, backup);
+    }
+    const temp = `${target}.tmp-${process.pid}`;
+    try {
+        writeFileSync(temp, JSON.stringify(output, null, 2) + '\n');
+        renameSync(temp, target);
+    }
+    catch (error) {
+        try {
+            unlinkSync(temp);
+        }
+        catch {
+            // The temp file may never have been created; nothing to clean up.
+        }
+        throw new Error(`dsh-mcp-config: failed to write migrated config to "${target}": ${error.message}`);
+    }
+    result.wrote = true;
+    if (backup !== undefined)
+        result.backup = backup;
+    return result;
+}
+/**
+ * Read and parse the target document, defaulting to `{ mcpServers: {} }` when
+ * absent. A present-but-unparseable target, or one whose `mcpServers` fails
+ * validation, throws with an actionable message before anything is written.
+ */
+function readTargetRoot(target) {
+    if (!existsSync(target))
+        return { mcpServers: {} };
+    let root;
+    try {
+        root = JSON.parse(readFileSync(target, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`dsh-mcp-config: migration target "${target}" is not valid JSON: ${error.message}`);
+    }
+    if (root === null || typeof root !== 'object' || Array.isArray(root)) {
+        throw new Error(`dsh-mcp-config: migration target "${target}" must be a JSON object`);
+    }
+    const doc = root;
+    if (doc.mcpServers !== undefined) {
+        // Validate an existing mcpServers key (map or array form) before touching anything.
+        parseMcpServers(doc);
+    }
+    return root;
+}
+//# sourceMappingURL=migrate.js.map

package/lib/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"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"}

package/lib/paths.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Side-effect-free path resolution and file-reading for MCP config discovery.
+ *
+ * `resolveDefaultMcpPaths` classifies the default `.mcp.json` locations into
+ * dsh-native, Claude Code, and migration-target buckets as a pure function of
+ * injectable `{ env, cwd, home }`. `readMcpServerNames` reads a single config
+ * file without ever throwing, and `claudeOnlyServers` reports the Claude Code
+ * server names not shadowed by a dsh-native file. Nothing in this module
+ * writes to disk; the package's only file-WRITING surface is `migrate.ts`.
+ *
+ * @module @dsh-cc/mcp-config/paths
+ */
+/** The default MCP config locations, classified by origin. */
+export interface ResolvedMcpPaths {
+    /** dsh-native config files in discovery order (`<cwd>/.mcp.json`, `$DSH_HOME/.mcp.json`). */
+    dsh: string[];
+    /** Claude Code config files in discovery order (`<claudeDir>/.mcp.json`, `<home>/.claude.json`). */
+    claude: string[];
+    /** The migration target: `$DSH_HOME/.mcp.json` (default `~/.dsh/.mcp.json`). */
+    target: string;
+}
+/** Injectable process inputs for {@link resolveDefaultMcpPaths}; defaults read `process`/`os`. */
+export interface McpPathInputs {
+    /** Environment lookup; defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Working directory anchoring the project `.mcp.json`; defaults to `process.cwd()`. */
+    cwd?: string;
+    /** User home directory; defaults to `os.homedir()`. */
+    home?: string;
+}
+/**
+ * Classify the default MCP config paths. `claudeDir` honors
+ * `CLAUDE_CONFIG_DIR` exactly as Claude Code does, while the `~/.claude.json`
+ * state file stays anchored at the user home regardless of the config dir.
+ *
+ * @param inputs - injectable `{ env, cwd, home }`; pure when all are provided.
+ * @returns the dsh-native, Claude Code, and migration-target paths.
+ */
+export declare function resolveDefaultMcpPaths(inputs?: McpPathInputs): ResolvedMcpPaths;
+/**
+ * The declared server names of one config file, without ever throwing.
+ * Names are the raw `mcpServers` keys in file order — never env-expanded or
+ * tool-name normalized.
+ */
+export type McpServerNames = {
+    kind: 'absent';
+} | {
+    kind: 'invalid';
+    error: string;
+} | {
+    kind: 'ok';
+    names: string[];
+};
+/**
+ * Read the server names declared by one `.mcp.json` file.
+ *
+ * @param path - config file to read.
+ * @returns `absent` when the file does not exist, `invalid` with the error
+ * message when it is unreadable/unparseable/fails `mcpServers` validation,
+ * else `ok` with the raw declared names in order.
+ */
+export declare function readMcpServerNames(path: string): McpServerNames;
+/** One Claude Code file's server names that no readable dsh file declares. */
+export interface ClaudeOnlySource {
+    /** The Claude Code config file the names were read from. */
+    path: string;
+    /** Declared names not shadowed by any dsh-native file. */
+    names: string[];
+}
+/**
+ * Report, per Claude Code file, the server names that no dsh-native file
+ * declares — the servers a gating discovery would silently skip. Invalid or
+ * absent files on either side are skipped.
+ *
+ * @param paths - the dsh-native and Claude Code file paths.
+ * @returns one entry per Claude Code file that still declares unshadowed names.
+ */
+export declare function claudeOnlyServers(paths: Pick<ResolvedMcpPaths, 'dsh' | 'claude'>): ClaudeOnlySource[];
+//# sourceMappingURL=paths.d.ts.map

package/lib/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,6FAA6F;IAC7F,GAAG,EAAE,MAAM,EAAE,CAAA;IACb,oGAAoG;IACpG,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAA;CACf;AAED,kGAAkG;AAClG,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IACxC,wFAAwF;IACxF,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAE,aAAkB,GAAG,gBAAgB,CAanF;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEnC;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAa/D;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,QAAQ,CAAC,GAAG,gBAAgB,EAAE,CAcrG"}

package/lib/paths.js

@@ -0,0 +1,91 @@
+/**
+ * Side-effect-free path resolution and file-reading for MCP config discovery.
+ *
+ * `resolveDefaultMcpPaths` classifies the default `.mcp.json` locations into
+ * dsh-native, Claude Code, and migration-target buckets as a pure function of
+ * injectable `{ env, cwd, home }`. `readMcpServerNames` reads a single config
+ * file without ever throwing, and `claudeOnlyServers` reports the Claude Code
+ * server names not shadowed by a dsh-native file. Nothing in this module
+ * writes to disk; the package's only file-WRITING surface is `migrate.ts`.
+ *
+ * @module @dsh-cc/mcp-config/paths
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { parseMcpServers } from "./index.js";
+/**
+ * Classify the default MCP config paths. `claudeDir` honors
+ * `CLAUDE_CONFIG_DIR` exactly as Claude Code does, while the `~/.claude.json`
+ * state file stays anchored at the user home regardless of the config dir.
+ *
+ * @param inputs - injectable `{ env, cwd, home }`; pure when all are provided.
+ * @returns the dsh-native, Claude Code, and migration-target paths.
+ */
+export function resolveDefaultMcpPaths(inputs = {}) {
+    const env = inputs.env ?? process.env;
+    const cwd = inputs.cwd ?? process.cwd();
+    const home = inputs.home ?? homedir();
+    const dshHome = env.DSH_HOME ? resolve(env.DSH_HOME) : join(home, '.dsh');
+    const claudeDir = env.CLAUDE_CONFIG_DIR ? resolve(env.CLAUDE_CONFIG_DIR) : join(home, '.claude');
+    const projectFile = join(resolve(cwd), '.mcp.json');
+    const dshFile = join(dshHome, '.mcp.json');
+    return {
+        dsh: [projectFile, dshFile],
+        claude: [join(claudeDir, '.mcp.json'), join(home, '.claude.json')],
+        target: dshFile,
+    };
+}
+/**
+ * Read the server names declared by one `.mcp.json` file.
+ *
+ * @param path - config file to read.
+ * @returns `absent` when the file does not exist, `invalid` with the error
+ * message when it is unreadable/unparseable/fails `mcpServers` validation,
+ * else `ok` with the raw declared names in order.
+ */
+export function readMcpServerNames(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { kind: 'absent' };
+        return { kind: 'invalid', error: error.message };
+    }
+    try {
+        return { kind: 'ok', names: Object.keys(parseMcpServers(JSON.parse(raw))) };
+    }
+    catch (error) {
+        return { kind: 'invalid', error: error.message };
+    }
+}
+/**
+ * Report, per Claude Code file, the server names that no dsh-native file
+ * declares — the servers a gating discovery would silently skip. Invalid or
+ * absent files on either side are skipped.
+ *
+ * @param paths - the dsh-native and Claude Code file paths.
+ * @returns one entry per Claude Code file that still declares unshadowed names.
+ */
+export function claudeOnlyServers(paths) {
+    const dshNames = new Set();
+    for (const file of paths.dsh) {
+        const names = readMcpServerNames(file);
+        if (names.kind === 'ok')
+            for (const name of names.names)
+                dshNames.add(name);
+    }
+    const result = [];
+    for (const file of paths.claude) {
+        const names = readMcpServerNames(file);
+        if (names.kind !== 'ok')
+            continue;
+        const only = names.names.filter(name => !dshNames.has(name));
+        if (only.length > 0)
+            result.push({ path: file, names: only });
+    }
+    return result;
+}
+//# sourceMappingURL=paths.js.map

package/lib/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@dsh-cc/mcp-config",
+  "description": "MCP workspace-configuration loader: parses .mcp.json into mcp-client registrations",
+  "version": "0.5.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dsh-cc/dsh-cc.git",
+    "directory": "packages/mcp/mcp-config"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": ">=0.1.1-rc.2",
+    "@deepseek-ai/cordis": ">=0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "dependencies": {
+    "@dsh-cc/mcp-client": "^0.5.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "link:../../../../deepseek-harness/packages/runtime-diagnostics/invariants",
+    "@deepseek-ai/cordis": "link:../../../../deepseek-harness/vendor/cordis",
+    "@deepseek-ai/schemastery": "link:../../../../deepseek-harness/vendor/schemastery",
+    "@dsh-cc/mcp-client": "^0.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}