@thantos66/claude-context-mcp 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,171 @@
+# claude-context-mcp
+
+An MCP server that exposes tools for quickly customizing Claude Code & Claude
+Desktop project context — MCP servers, subagents, skills, and tool permissions
+— across any project on disk.
+
+One place to say *"for project X, install server Y, allow agent Z, deny
+`Bash(curl *)`, scaffold a skill called W"* and have it write all the right
+files in all the right spots.
+
+Follows Anthropic's [`mcp-builder`](https://github.com/anthropics/skills/tree/main/skills/mcp-builder)
+skill conventions: TypeScript, Zod input validation, modern `registerTool()`
+API, tool annotations on every tool, structured content alongside text.
+
+## What it manages
+
+| Subject | Scopes | Files touched |
+|---|---|---|
+| **MCP servers** | `desktop`, `user`, `project` | `claude_desktop_config.json`, `~/.claude.json`, `<project>/.mcp.json` |
+| **Permissions** | `user`, `project` | `~/.claude/settings.json`, `<project>/.claude/settings.json` |
+| **Subagents** | `user`, `project` | `~/.claude/agents/*.md`, `<project>/.claude/agents/*.md` |
+| **Skills** | `user`, `project` | `~/.claude/skills/<name>/SKILL.md`, `<project>/.claude/skills/<name>/SKILL.md` |
+
+## Install
+
+```bash
+cd claude-context-mcp
+npm install
+npm run build
+```
+
+This produces `dist/index.js`, which is the stdio entry point.
+
+## Wire into Claude Desktop
+
+Edit `claude_desktop_config.json`:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "claude-context": {
+      "command": "node",
+      "args": ["/absolute/path/to/claude-context-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Fully quit and relaunch Claude Desktop for the server to register.
+
+## Wire into Claude Code
+
+```bash
+claude mcp add claude-context node /absolute/path/to/claude-context-mcp/dist/index.js
+claude mcp list
+```
+
+## Tool surface
+
+### MCP servers (`mcp_*`)
+
+| Tool | What it does |
+|---|---|
+| `mcp_list_servers` | List configured servers across scopes. Env secrets redacted unless `revealSecrets=true`. |
+| `mcp_get_server` | Show one server's full config. |
+| `mcp_add_server` | Add a stdio (`command`+`args`+`env`) or HTTP (`url`+`headers`) entry. |
+| `mcp_update_server` | Patch individual fields on an existing entry. |
+| `mcp_remove_server` | Delete an entry. |
+| `mcp_set_disabled` | Toggle `disabled: true/false` without deleting. |
+
+### Permissions (`permissions_*`)
+
+| Tool | What it does |
+|---|---|
+| `permissions_list` | Dump `allow` / `deny` / `ask` + `defaultMode` for a scope. |
+| `permissions_add_rules` | Add rules to one of the lists (idempotent — duplicates skipped). |
+| `permissions_remove_rule` | Remove a rule by exact string match. |
+| `permissions_set_default_mode` | Set `defaultMode` to `default` / `acceptEdits` / `plan` / `auto` / `dontAsk` / `bypassPermissions`. |
+
+Rules use the Claude Code grammar: `Tool`, `Bash(npm run *)`, `Read(./.env)`,
+`WebFetch(domain:example.com)`, `mcp__<server>__<tool>`, `Agent(my-agent)`.
+Evaluation order is **deny → ask → allow**, first match wins.
+
+### Subagents (`agent_*`)
+
+| Tool | What it does |
+|---|---|
+| `agent_list` | List subagents in a scope. |
+| `agent_get` | Show one agent's full frontmatter + body. |
+| `agent_create` | Scaffold a new `.claude/agents/<name>.md`. Accepts `tools` as string or array. |
+| `agent_update` | Patch frontmatter fields and/or body. |
+| `agent_delete` | Delete (with backup). |
+
+### Skills (`skill_*`)
+
+| Tool | What it does |
+|---|---|
+| `skill_list` | List skill folders in a scope. |
+| `skill_get` | Show one skill's SKILL.md (frontmatter + body). |
+| `skill_create` | Scaffold `.claude/skills/<name>/SKILL.md`. |
+| `skill_update` | Patch frontmatter fields and/or body. |
+| `skill_set_enabled` | Toggle `disable-model-invocation` flag (preserves files). |
+| `skill_delete` | Remove a skill folder (with full-directory backup). |
+
+### Meta (`meta_*`)
+
+| Tool | What it does |
+|---|---|
+| `meta_platform_paths` | Return the resolved config paths for the current OS + optional project. |
+| `meta_validate` | Parse/validate a config file without writing. |
+| `meta_backup_file` | Manually snapshot a file to `~/.claude/backups/`. |
+
+## Safety
+
+- **Atomic writes.** Parse → Zod validate → mutate → serialize (2-space JSON) → temp file → `fs.rename`. Never string-edited.
+- **Pre-write backups.** Every destructive / mutating tool snapshots the target to `~/.claude/backups/<basename>.<iso-timestamp>.bak` before touching disk. Skill deletes back up the whole directory.
+- **Dry-run.** Every write tool accepts `dryRun: true` and returns a unified diff (or a file preview) without touching disk.
+- **Restart reminders.** Any write to the Claude Desktop config includes `restartRequired: true` in `structuredContent` and a reminder in the text response.
+- **Secret redaction.** `mcp_list_servers` / `mcp_get_server` redact env values whose key matches `/key|token|secret|password|apikey/i` unless you pass `revealSecrets: true`.
+- **Scope safety.** Project-scope tools require an absolute `projectPath` under `$HOME`. Override with `allowOutsideHome: true` at the service level if you need it.
+- **Annotations.** Every destructive tool declares `destructiveHint: true`, every read-only tool declares `readOnlyHint: true`, so your Claude client's approval UI prompts appropriately.
+
+## Development
+
+```bash
+npm run dev       # tsc --watch
+npm test          # run unit tests
+npm run test:watch
+```
+
+Unit tests use a fresh temp directory as `$HOME` for each test (via
+`os.homedir()` spy), so they never touch your real config.
+
+For a manual end-to-end walk through every tool, use the official inspector:
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+## Layout
+
+```
+src/
+├── index.ts                    # server bootstrap + registerTool() wiring
+├── constants.ts                # per-OS config path resolution
+├── services/
+│   ├── paths.ts                # scope → absolute path
+│   ├── backup.ts               # snapshot helpers
+│   ├── atomic-write.ts         # temp-file + rename
+│   ├── mcp-config.ts           # mcpServers CRUD across 3 scopes
+│   ├── permissions.ts          # settings.json permissions CRUD
+│   ├── agents.ts               # .claude/agents/*.md CRUD
+│   └── skills.ts               # .claude/skills/<name>/ CRUD
+├── schemas/
+│   ├── mcp-config.ts           # Zod for stdio + HTTP entries
+│   ├── settings.ts             # Zod for permissions + defaultMode
+│   ├── agent-frontmatter.ts    # Zod for agent YAML
+│   └── skill-frontmatter.ts    # Zod for skill YAML
+└── tools/                      # one file per subject, each exports a register* fn
+    ├── helpers.ts
+    ├── mcp.ts
+    ├── permissions.ts
+    ├── agents.ts
+    ├── skills.ts
+    └── meta.ts
+tests/                          # vitest; each test runs in a spoofed $HOME
+```

package/dist/constants.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Supported scopes across the tool surface.
+ * - `desktop` — Claude Desktop app config (only meaningful for MCP servers)
+ * - `user`    — ~/.claude.json and ~/.claude/… user-wide Claude Code config
+ * - `project` — <projectPath>/.claude/… project-scoped Claude Code config
+ */
+export type Scope = "desktop" | "user" | "project";
+/**
+ * Resolve the Claude Desktop config file path for the current OS.
+ *
+ * - macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
+ * - Windows: %APPDATA%/Claude/claude_desktop_config.json
+ * - Linux:   ~/.config/Claude/claude_desktop_config.json
+ */
+export declare function claudeDesktopConfigPath(): string;
+/** ~/.claude.json — Claude Code user-scope config (holds user mcpServers). */
+export declare function claudeCodeUserJsonPath(): string;
+/** ~/.claude/settings.json — Claude Code user-scope settings (permissions, hooks). */
+export declare function claudeCodeUserSettingsPath(): string;
+/** ~/.claude/agents — user-scope subagent directory. */
+export declare function claudeCodeUserAgentsDir(): string;
+/** ~/.claude/skills — user-scope skills directory. */
+export declare function claudeCodeUserSkillsDir(): string;
+/** ~/.claude/backups — backup snapshot directory. */
+export declare function backupsDir(): string;
+/** <project>/.mcp.json — project-scope MCP server config. */
+export declare function projectMcpJsonPath(projectPath: string): string;
+/** <project>/.claude/settings.json — project-scope settings. */
+export declare function projectSettingsPath(projectPath: string): string;
+/** <project>/.claude/agents — project-scope subagents directory. */
+export declare function projectAgentsDir(projectPath: string): string;
+/** <project>/.claude/skills — project-scope skills directory. */
+export declare function projectSkillsDir(projectPath: string): string;

package/dist/constants.js

@@ -0,0 +1,59 @@
+import os from "node:os";
+import path from "node:path";
+/**
+ * Resolve the Claude Desktop config file path for the current OS.
+ *
+ * - macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
+ * - Windows: %APPDATA%/Claude/claude_desktop_config.json
+ * - Linux:   ~/.config/Claude/claude_desktop_config.json
+ */
+export function claudeDesktopConfigPath() {
+    const home = os.homedir();
+    switch (process.platform) {
+        case "darwin":
+            return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+        case "win32": {
+            const appData = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
+            return path.join(appData, "Claude", "claude_desktop_config.json");
+        }
+        default:
+            return path.join(home, ".config", "Claude", "claude_desktop_config.json");
+    }
+}
+/** ~/.claude.json — Claude Code user-scope config (holds user mcpServers). */
+export function claudeCodeUserJsonPath() {
+    return path.join(os.homedir(), ".claude.json");
+}
+/** ~/.claude/settings.json — Claude Code user-scope settings (permissions, hooks). */
+export function claudeCodeUserSettingsPath() {
+    return path.join(os.homedir(), ".claude", "settings.json");
+}
+/** ~/.claude/agents — user-scope subagent directory. */
+export function claudeCodeUserAgentsDir() {
+    return path.join(os.homedir(), ".claude", "agents");
+}
+/** ~/.claude/skills — user-scope skills directory. */
+export function claudeCodeUserSkillsDir() {
+    return path.join(os.homedir(), ".claude", "skills");
+}
+/** ~/.claude/backups — backup snapshot directory. */
+export function backupsDir() {
+    return path.join(os.homedir(), ".claude", "backups");
+}
+/** <project>/.mcp.json — project-scope MCP server config. */
+export function projectMcpJsonPath(projectPath) {
+    return path.join(projectPath, ".mcp.json");
+}
+/** <project>/.claude/settings.json — project-scope settings. */
+export function projectSettingsPath(projectPath) {
+    return path.join(projectPath, ".claude", "settings.json");
+}
+/** <project>/.claude/agents — project-scope subagents directory. */
+export function projectAgentsDir(projectPath) {
+    return path.join(projectPath, ".claude", "agents");
+}
+/** <project>/.claude/skills — project-scope skills directory. */
+export function projectSkillsDir(projectPath) {
+    return path.join(projectPath, ".claude", "skills");
+}
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAU7B;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IAC1B,QAAQ,OAAO,CAAC,QAAQ,EAAE,CAAC;QACzB,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC,IAAI,CACd,IAAI,EACJ,SAAS,EACT,qBAAqB,EACrB,QAAQ,EACR,4BAA4B,CAC7B,CAAC;QACJ,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;YAC7E,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,4BAA4B,CAAC,CAAC;QACpE,CAAC;QACD;YACE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,4BAA4B,CAAC,CAAC;IAC9E,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,sBAAsB;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,cAAc,CAAC,CAAC;AACjD,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,0BAA0B;IACxC,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC;AAC7D,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,uBAAuB;IACrC,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,uBAAuB;IACrC,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,UAAU;IACxB,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;AAC7C,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC;AAC5D,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,gBAAgB,CAAC,WAAmB;IAClD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AACrD,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,gBAAgB,CAAC,WAAmB;IAClD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AACrD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * claude-context-mcp — MCP server for managing Claude Code & Desktop context.
+ *
+ * Exposes tools for quickly manipulating:
+ *   - MCP servers      (Claude Desktop + Claude Code user + project)
+ *   - Tool permissions (allow / deny / ask + defaultMode)
+ *   - Subagents        (.claude/agents/*.md, user + project)
+ *   - Skills           (.claude/skills/<name>/SKILL.md, user + project)
+ *
+ * Transport: stdio. Follows mcp-builder skill conventions:
+ *   - registerTool() modern API
+ *   - Zod input schemas
+ *   - readOnly/destructive/idempotent/openWorld annotations on every tool
+ *   - structuredContent alongside text responses
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerMcpTools } from "./tools/mcp.js";
+import { registerPermissionsTools } from "./tools/permissions.js";
+import { registerAgentTools } from "./tools/agents.js";
+import { registerSkillTools } from "./tools/skills.js";
+import { registerMetaTools } from "./tools/meta.js";
+async function main() {
+    const server = new McpServer({
+        name: "claude-context-mcp",
+        version: "0.1.0",
+    });
+    registerMcpTools(server);
+    registerPermissionsTools(server);
+    registerAgentTools(server);
+    registerSkillTools(server);
+    registerMetaTools(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // NOTE: we intentionally don't log anything to stdout — it's reserved for
+    // the JSON-RPC framing. Any diagnostics go to stderr.
+    process.stderr.write("[claude-context-mcp] ready on stdio\n");
+}
+main().catch((err) => {
+    process.stderr.write(`[claude-context-mcp] fatal: ${err.stack ?? err}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,oBAAoB;QAC1B,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzB,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACjC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAE1B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,0EAA0E;IAC1E,sDAAsD;IACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;AAChE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,+BAAgC,GAAa,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC,CAAC;IACrF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/schemas/agent-frontmatter.d.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+/**
+ * Claude Code subagent frontmatter schema.
+ *
+ * NOTE: `tools` in the on-disk format is a comma-separated STRING, not a
+ * YAML array. We accept either on input (for tool ergonomics) and always
+ * serialize as a string on write.
+ */
+export declare const AgentModelSchema: z.ZodUnion<[z.ZodEnum<["sonnet", "opus", "haiku", "inherit"]>, z.ZodString]>;
+export declare const AgentFrontmatterSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    model: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["sonnet", "opus", "haiku", "inherit"]>, z.ZodString]>>;
+    tools: z.ZodOptional<z.ZodString>;
+    color: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    name: z.ZodString;
+    description: z.ZodString;
+    model: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["sonnet", "opus", "haiku", "inherit"]>, z.ZodString]>>;
+    tools: z.ZodOptional<z.ZodString>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    name: z.ZodString;
+    description: z.ZodString;
+    model: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["sonnet", "opus", "haiku", "inherit"]>, z.ZodString]>>;
+    tools: z.ZodOptional<z.ZodString>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export type AgentFrontmatter = z.infer<typeof AgentFrontmatterSchema>;
+/** Input shape: accept `tools` as string OR array of strings for ergonomics. */
+export declare const AgentInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    model: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["sonnet", "opus", "haiku", "inherit"]>, z.ZodString]>>;
+    tools: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    color: z.ZodOptional<z.ZodString>;
+    body: z.ZodDefault<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    name: z.ZodString;
+    description: z.ZodString;
+    model: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["sonnet", "opus", "haiku", "inherit"]>, z.ZodString]>>;
+    tools: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    color: z.ZodOptional<z.ZodString>;
+    body: z.ZodDefault<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    name: z.ZodString;
+    description: z.ZodString;
+    model: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["sonnet", "opus", "haiku", "inherit"]>, z.ZodString]>>;
+    tools: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    color: z.ZodOptional<z.ZodString>;
+    body: z.ZodDefault<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export type AgentInput = z.infer<typeof AgentInputSchema>;
+/** Normalize tools input to the on-disk comma-separated string form. */
+export declare function normalizeTools(tools: string | string[] | undefined): string | undefined;

package/dist/schemas/agent-frontmatter.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+/**
+ * Claude Code subagent frontmatter schema.
+ *
+ * NOTE: `tools` in the on-disk format is a comma-separated STRING, not a
+ * YAML array. We accept either on input (for tool ergonomics) and always
+ * serialize as a string on write.
+ */
+export const AgentModelSchema = z.union([
+    z.enum(["sonnet", "opus", "haiku", "inherit"]),
+    z.string().min(1), // allow full model IDs e.g. claude-opus-4-6
+]);
+export const AgentFrontmatterSchema = z
+    .object({
+    name: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]*$/, "agent name must be lowercase alphanumeric + hyphens"),
+    description: z.string().min(1),
+    model: AgentModelSchema.optional(),
+    tools: z.string().optional(), // comma-separated on disk
+    color: z.string().optional(),
+})
+    .passthrough();
+/** Input shape: accept `tools` as string OR array of strings for ergonomics. */
+export const AgentInputSchema = z
+    .object({
+    name: AgentFrontmatterSchema.shape.name,
+    description: z.string().min(1),
+    model: AgentModelSchema.optional(),
+    tools: z.union([z.string(), z.array(z.string())]).optional(),
+    color: z.string().optional(),
+    body: z.string().default(""),
+})
+    .passthrough();
+/** Normalize tools input to the on-disk comma-separated string form. */
+export function normalizeTools(tools) {
+    if (tools === undefined)
+        return undefined;
+    if (Array.isArray(tools))
+        return tools.join(", ");
+    return tools;
+}
+//# sourceMappingURL=agent-frontmatter.js.map

package/dist/schemas/agent-frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-frontmatter.js","sourceRoot":"","sources":["../../src/schemas/agent-frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC;IACtC,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,4CAA4C;CAChE,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC;KACpC,MAAM,CAAC;IACN,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,KAAK,CAAC,sBAAsB,EAAE,qDAAqD,CAAC;IACvF,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,KAAK,EAAE,gBAAgB,CAAC,QAAQ,EAAE;IAClC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,0BAA0B;IACxD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC;KACD,WAAW,EAAE,CAAC;AAIjB,gFAAgF;AAChF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,CAAC;IACN,IAAI,EAAE,sBAAsB,CAAC,KAAK,CAAC,IAAI;IACvC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,KAAK,EAAE,gBAAgB,CAAC,QAAQ,EAAE;IAClC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC5D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;CAC7B,CAAC;KACD,WAAW,EAAE,CAAC;AAIjB,wEAAwE;AACxE,MAAM,UAAU,cAAc,CAC5B,KAAoC;IAEpC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/schemas/mcp-config.d.ts

@@ -0,0 +1,177 @@
+import { z } from "zod";
+/**
+ * Shape of one entry in `mcpServers`. Two forms:
+ *  - stdio: `command` + optional `args`/`env`
+ *  - http:  `url`     + optional `headers`
+ *
+ * We allow extra unknown fields to pass through (the spec is evolving),
+ * but we validate the known ones strictly.
+ */
+export declare const StdioServerSchema: z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">>;
+export declare const HttpServerSchema: z.ZodObject<{
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">>;
+export declare const McpServerEntrySchema: z.ZodUnion<[z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">>, z.ZodObject<{
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">>]>;
+/** The full top-level file shape — both claude_desktop_config.json and .mcp.json
+ *  only use the `mcpServers` key; anything else is passed through untouched. */
+export declare const McpConfigFileSchema: z.ZodObject<{
+    mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodObject<{
+        url: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        url: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        url: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">>]>>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodObject<{
+        url: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        url: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        url: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">>]>>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodObject<{
+        url: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        url: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        url: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.ZodTypeAny, "passthrough">>]>>>;
+}, z.ZodTypeAny, "passthrough">>;
+export type StdioServer = z.infer<typeof StdioServerSchema>;
+export type HttpServer = z.infer<typeof HttpServerSchema>;
+export type McpServerEntry = z.infer<typeof McpServerEntrySchema>;
+export type McpConfigFile = z.infer<typeof McpConfigFileSchema>;
+/** Type guard: stdio vs http entry. */
+export declare function isStdioServer(entry: McpServerEntry): entry is StdioServer;