ymcp_manager 0.1.0

package/Unlicense

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <http://unlicense.org/>

package/bin/ymcp.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+
+require("../server.js");

package/docs/mcp_server_guide.md

@@ -0,0 +1,130 @@
+# Guide on how to create MCP servers
+
+Write concise, authoritative MCP server implementations for developers and LLMs.
+
+Audience:
+- LLMs (for tool discovery and reasoning)
+- Developers writing local MCP servers
+
+Tone:
+- Technical
+- Minimal
+- Explicit rules
+
+## 1) What MCP Is
+- MCP is a function-calling interface for LLMs.
+- MCP tools are semantic actions, not transport APIs.
+- MCP servers expose capabilities, not implementation internals.
+
+## 2) Design Rules (MANDATORY)
+- Tools represent one semantic intention.
+- Tool names are verbs (`add`, `validate`, `attach`, `detach`).
+- Inputs are small, explicit, strongly typed JSON objects.
+- Outputs are deterministic, structured JSON objects.
+- Prefer IDs/paths over natural-language descriptions.
+- LLMs do symbolic reasoning; tools do numeric operations and side effects.
+- Hide REST/HTTP/shell/PowerShell behind MCP tools.
+
+## 3) Tool Shape (Canonical)
+Tool:
+- `name`: verb
+- `inputs`: small JSON object
+- `outputs`: small JSON object
+
+Rules:
+- No plain strings for structured payloads.
+- No implicit units.
+
+Example:
+- `sin({ x: number }) -> { value: number }`
+
+## 4) Node.js MCP Server Requirements
+- Use `@modelcontextprotocol/sdk`.
+- Use stdio transport (`StdioServerTransport`).
+- Do not expose HTTP as the MCP transport.
+- One server may expose multiple tools.
+
+## 5) Repository Convention (REQUIRED)
+Each MCP server repo must contain:
+- `docs/mcp.json`
+
+Required contract:
+
+```json
+{
+  "name": "string",
+  "description": "string",
+  "entry": "relative path to MCP server entry js",
+  "command": "node",
+  "args": ["relative/path/to/entry.js"],
+  "tools": [
+    {
+      "name": "string",
+      "description": "string",
+      "inputs": { "argName": "type" },
+      "outputs": { "field": "type" }
+    }
+  ]
+}
+```
+
+Validation expectations used by `ymcp_manager`:
+- `docs/mcp.json` must parse as JSON object.
+- `name`, `description`, `entry`, `command` are non-empty strings.
+- `command` must be `"node"`.
+- `args` is an array of strings.
+- `tools` is an array of objects with `name`, `description`, `inputs`, `outputs`.
+- `entry` is relative and exists on disk.
+- Entry source references `@modelcontextprotocol/sdk`.
+- Entry source appears to use stdio transport.
+
+## 6) Execution Model
+- MCP servers are launched by a runtime/manager, not by the LLM.
+- LLMs do not start arbitrary processes.
+- LLMs only call registered tools.
+- If a tool is not registered, the LLM must not emulate side effects.
+
+## 7) Installation Feedback Loop (REQUIRED)
+If an MCP server fails to attach in `ymcp_manager`, a file is written:
+- `docs/mcp_installation_problem.md`
+
+The LLM or developer maintaining that MCP server must:
+1. Read `docs/mcp_installation_problem.md`.
+2. Fix all listed problems in the repository.
+3. Re-run validation and attach.
+4. Delete `docs/mcp_installation_problem.md` after successful attach.
+
+This rule is mandatory so failed installations produce actionable feedback.
+
+## 8) Anti-Patterns (FORBIDDEN)
+- Exposing REST endpoints directly as tools.
+- Exposing raw shell or PowerShell commands.
+- Accepting unconstrained natural-language tool arguments.
+- Overloading one tool with unrelated responsibilities.
+- Parsing symbolic math inside tools.
+
+## 9) Minimal Node.js Example
+```js
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const server = new McpServer({ name: "math-demo", version: "0.1.0" });
+
+server.registerTool(
+  "sin",
+  { description: "Compute sine", inputSchema: { x: z.number() } },
+  async ({ x }) => ({
+    content: [{ type: "text", text: JSON.stringify({ value: Math.sin(x) }) }],
+    structuredContent: { value: Math.sin(x) }
+  })
+);
+
+await server.connect(new StdioServerTransport());
+```
+
+Optimization goals:
+- Automatic validation
+- Tool discovery
+- Meta-MCP attachment

package/install.bat

@@ -0,0 +1,4 @@
+@echo off
+setlocal
+node "%~dp0server.js" install
+endlocal

package/install.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+set -eu
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+node "$SCRIPT_DIR/server.js" install

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "ymcp_manager",
+  "version": "0.1.0",
+  "description": "Local meta-MCP manager for adding, validating, and attaching MCP servers.",
+  "main": "server.js",
+  "bin": {
+    "ymcp": "bin/ymcp.js"
+  },
+  "scripts": {
+    "start": "node server.js",
+    "help": "node server.js help",
+    "validate": "node server.js validate",
+    "install:mcp": "node server.js install",
+    "uninstall:mcp": "node server.js uninstall",
+    "republish": "version-select && npm publish && npm uninstall -g ymcp_manager && npm install -g ymcp_manager && ymcp help"
+  },
+  "license": "Unlicense",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.25.76"
+  }
+}

package/republish.bat

@@ -0,0 +1 @@
+version-select && npm publish && npm uninstall -g ymcp_manager && npm install -g ymcp_manager && ymcp help

package/server.js

@@ -0,0 +1,764 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs/promises");
+const fsSync = require("node:fs");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+const { createRequire } = require("node:module");
+
+const META_NAME = "ymcp-manager";
+const META_VERSION = "0.1.0";
+const HELP_DOC_PATH = path.join(__dirname, "docs", "mcp_server_guide.md");
+
+const repos = new Map();
+const attached = new Map();
+
+function log(message) {
+  console.error(`[${META_NAME}] ${message}`);
+}
+
+function toResult(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    structuredContent: payload,
+  };
+}
+
+function normalizePath(inputPath) {
+  return path.resolve(inputPath);
+}
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+async function fileExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readManifest(repoPath) {
+  const manifestPath = path.join(repoPath, "docs", "mcp.json");
+  const raw = await fs.readFile(manifestPath, "utf8");
+  return JSON.parse(raw);
+}
+
+function getRepoByPathOrName(pathOrName) {
+  if (!pathOrName || typeof pathOrName !== "string") {
+    return null;
+  }
+
+  const normalizedInput = normalizePath(pathOrName);
+  if (repos.has(normalizedInput)) {
+    return repos.get(normalizedInput);
+  }
+
+  for (const repo of repos.values()) {
+    if (repo.name === pathOrName) {
+      return repo;
+    }
+  }
+  return null;
+}
+
+function resolveEntry(repoPath, entry) {
+  return path.resolve(repoPath, entry);
+}
+
+async function validateRepoPath(repoPath) {
+  const errors = [];
+  const normalizedPath = normalizePath(repoPath);
+  const manifestPath = path.join(normalizedPath, "docs", "mcp.json");
+
+  if (!(await fileExists(normalizedPath))) {
+    errors.push(`Path does not exist: ${normalizedPath}`);
+    return { valid: false, errors };
+  }
+
+  if (!(await fileExists(manifestPath))) {
+    errors.push("Missing docs/mcp.json");
+    return { valid: false, errors };
+  }
+
+  let manifest;
+  try {
+    manifest = await readManifest(normalizedPath);
+  } catch (error) {
+    errors.push(`Invalid docs/mcp.json: ${error.message}`);
+    return { valid: false, errors };
+  }
+
+  if (!isObject(manifest)) {
+    errors.push("docs/mcp.json must be an object");
+    return { valid: false, errors };
+  }
+
+  if (typeof manifest.name !== "string" || !manifest.name.trim()) {
+    errors.push("Manifest field 'name' must be a non-empty string");
+  }
+  if (typeof manifest.description !== "string" || !manifest.description.trim()) {
+    errors.push("Manifest field 'description' must be a non-empty string");
+  }
+  if (typeof manifest.entry !== "string" || !manifest.entry.trim()) {
+    errors.push("Manifest field 'entry' must be a non-empty string");
+  }
+  if (typeof manifest.command !== "string" || !manifest.command.trim()) {
+    errors.push("Manifest field 'command' must be a non-empty string");
+  }
+  if (!Array.isArray(manifest.args) || !manifest.args.every((arg) => typeof arg === "string")) {
+    errors.push("Manifest field 'args' must be an array of strings");
+  }
+  if (!Array.isArray(manifest.tools)) {
+    errors.push("Manifest field 'tools' must be an array");
+  } else {
+    for (let i = 0; i < manifest.tools.length; i += 1) {
+      const tool = manifest.tools[i];
+      if (!isObject(tool)) {
+        errors.push(`tools[${i}] must be an object`);
+        continue;
+      }
+      if (typeof tool.name !== "string" || !tool.name.trim()) {
+        errors.push(`tools[${i}].name must be a non-empty string`);
+      }
+      if (typeof tool.description !== "string" || !tool.description.trim()) {
+        errors.push(`tools[${i}].description must be a non-empty string`);
+      }
+      if (!isObject(tool.inputs)) {
+        errors.push(`tools[${i}].inputs must be an object`);
+      }
+      if (!isObject(tool.outputs)) {
+        errors.push(`tools[${i}].outputs must be an object`);
+      }
+    }
+  }
+
+  if (manifest.command && manifest.command !== "node") {
+    errors.push("Manifest field 'command' must be 'node' for this local manager");
+  }
+
+  if (manifest.entry) {
+    if (path.isAbsolute(manifest.entry)) {
+      errors.push("Manifest field 'entry' must be a relative path");
+    } else {
+      const entryPath = resolveEntry(normalizedPath, manifest.entry);
+      if (!(await fileExists(entryPath))) {
+        errors.push(`Entry file not found: ${manifest.entry}`);
+      } else {
+        try {
+          const source = await fs.readFile(entryPath, "utf8");
+          if (!source.includes("@modelcontextprotocol/sdk")) {
+            errors.push("Entry file does not reference @modelcontextprotocol/sdk");
+          }
+          const looksLikeStdio =
+            /StdioServerTransport/.test(source) ||
+            /\bstdio\b/i.test(source) ||
+            /transport/i.test(source);
+          if (!looksLikeStdio) {
+            errors.push("Entry file does not appear to use stdio transport");
+          }
+        } catch (error) {
+          errors.push(`Unable to inspect entry file '${manifest.entry}': ${error.message}`);
+        }
+      }
+    }
+  }
+
+  if (Array.isArray(manifest.args)) {
+    const jsArgs = manifest.args.filter((arg) => arg.endsWith(".js"));
+    for (const argPath of jsArgs) {
+      if (!path.isAbsolute(argPath)) {
+        const candidate = path.resolve(normalizedPath, argPath);
+        if (!(await fileExists(candidate))) {
+          errors.push(`Args entry references missing file: ${argPath}`);
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors: errors.length > 0 ? errors : undefined,
+    manifest,
+    path: normalizedPath,
+  };
+}
+
+function toServerInfo(repo) {
+  const proc = attached.get(repo.path);
+  return {
+    name: repo.name,
+    description: repo.description,
+    path: repo.path,
+    attached: Boolean(proc),
+    pid: proc ? proc.child.pid : null,
+    tools: Array.isArray(repo.tools) ? repo.tools : [],
+    options: repo.options || {},
+  };
+}
+
+async function addRepo(inputPath) {
+  const repoPath = normalizePath(inputPath);
+  if (repos.has(repoPath)) {
+    return { added: true, alreadyPresent: true, server: toServerInfo(repos.get(repoPath)) };
+  }
+
+  const validation = await validateRepoPath(repoPath);
+  const name = validation.manifest?.name || path.basename(repoPath);
+  const description = validation.manifest?.description || "";
+  const tools = validation.manifest?.tools || [];
+
+  const repo = {
+    path: repoPath,
+    name,
+    description,
+    tools,
+    manifest: validation.manifest || null,
+    options: {},
+  };
+  repos.set(repoPath, repo);
+  return {
+    added: true,
+    valid: validation.valid,
+    errors: validation.errors,
+    server: toServerInfo(repo),
+  };
+}
+
+async function attachRepo(pathOrName) {
+  const repo = getRepoByPathOrName(pathOrName);
+  if (!repo) {
+    return { attached: false, error: `Unknown MCP repo: ${pathOrName}` };
+  }
+  if (attached.has(repo.path)) {
+    return { attached: true, alreadyAttached: true, server: toServerInfo(repo) };
+  }
+
+  const validation = await validateRepoPath(repo.path);
+  if (!validation.valid) {
+    await writeInstallationProblem(repo.path, "validation_failed", validation.errors || []);
+    return { attached: false, errors: validation.errors };
+  }
+
+  repo.manifest = validation.manifest;
+  repo.name = validation.manifest.name;
+  repo.description = validation.manifest.description;
+  repo.tools = validation.manifest.tools || [];
+
+  const command = repo.options.command || validation.manifest.command || "node";
+  const args = repo.options.args || validation.manifest.args || [validation.manifest.entry];
+  const cwd = repo.options.cwd || repo.path;
+  const env = { ...process.env, ...(repo.options.env || {}) };
+
+  const child = spawn(command, args, {
+    cwd,
+    env,
+    stdio: ["pipe", "pipe", "pipe"],
+    windowsHide: true,
+  });
+
+  const record = { child, command, args, cwd, startedAt: new Date().toISOString() };
+  attached.set(repo.path, record);
+
+  child.on("error", async (error) => {
+    await writeInstallationProblem(repo.path, "spawn_error", [error.message]);
+    log(`child process error (${repo.name}): ${error.message}`);
+  });
+  child.on("exit", async (code, signal) => {
+    attached.delete(repo.path);
+    if (code !== 0) {
+      const msg = `process exited with code=${code} signal=${signal || "none"}`;
+      await writeInstallationProblem(repo.path, "process_exit", [msg]);
+    }
+    log(`detached ${repo.name} (exit=${code}, signal=${signal || "none"})`);
+  });
+  child.stderr.on("data", (buf) => {
+    const line = String(buf).trim();
+    if (line) {
+      log(`${repo.name}: ${line}`);
+    }
+  });
+
+  log(`attached ${repo.name} pid=${child.pid}`);
+  await clearInstallationProblem(repo.path);
+  return { attached: true, server: toServerInfo(repo) };
+}
+
+function detachRepo(pathOrName) {
+  const repo = getRepoByPathOrName(pathOrName);
+  if (!repo) {
+    return { detached: false, error: `Unknown MCP repo: ${pathOrName}` };
+  }
+
+  const record = attached.get(repo.path);
+  if (!record) {
+    return { detached: true, alreadyDetached: true, server: toServerInfo(repo) };
+  }
+
+  record.child.kill();
+  attached.delete(repo.path);
+  log(`detached ${repo.name}`);
+  return { detached: true, server: toServerInfo(repo) };
+}
+
+function removeRepo(pathOrName) {
+  if (!pathOrName) {
+    for (const repo of repos.values()) {
+      if (attached.has(repo.path)) {
+        detachRepo(repo.path);
+      }
+    }
+    const count = repos.size;
+    repos.clear();
+    return { removed: true, removedAll: true, count };
+  }
+
+  const repo = getRepoByPathOrName(pathOrName);
+  if (!repo) {
+    return { removed: false, error: `Unknown MCP repo: ${pathOrName}` };
+  }
+
+  if (attached.has(repo.path)) {
+    detachRepo(pathOrName);
+  }
+  repos.delete(repo.path);
+  return { removed: true, path: repo.path, name: repo.name };
+}
+
+async function reconfigRepo(pathOrName, opts) {
+  const repo = getRepoByPathOrName(pathOrName);
+  if (!repo) {
+    return { reconfigured: false, error: `Unknown MCP repo: ${pathOrName}` };
+  }
+  if (!isObject(opts)) {
+    return { reconfigured: false, error: "opts must be an object" };
+  }
+
+  repo.options = { ...repo.options, ...opts };
+  const shouldRestart = opts.restart === true;
+  const isAttached = attached.has(repo.path);
+
+  if (isAttached && shouldRestart) {
+    detachRepo(pathOrName);
+    const result = await attachRepo(pathOrName);
+    return {
+      reconfigured: true,
+      restarted: true,
+      attached: result.attached === true,
+      errors: result.errors,
+      options: repo.options,
+    };
+  }
+
+  return {
+    reconfigured: true,
+    restarted: false,
+    attached: isAttached,
+    options: repo.options,
+  };
+}
+
+async function closeAll() {
+  for (const [repoPath, record] of attached.entries()) {
+    const repo = repos.get(repoPath);
+    try {
+      record.child.kill();
+      if (repo) {
+        log(`shutdown detached ${repo.name}`);
+      }
+    } catch (error) {
+      log(`shutdown detach error (${repo?.name || repoPath}): ${error.message}`);
+    }
+  }
+  attached.clear();
+}
+
+function listAll() {
+  return Array.from(repos.values()).map(toServerInfo);
+}
+
+function listAttached() {
+  return Array.from(repos.values())
+    .filter((repo) => attached.has(repo.path))
+    .map(toServerInfo);
+}
+
+function getProblemDocPath(repoPath) {
+  return path.join(repoPath, "docs", "mcp_installation_problem.md");
+}
+
+async function writeInstallationProblem(repoPath, context, errors) {
+  if (!repoPath) {
+    return;
+  }
+  const docsDir = path.join(repoPath, "docs");
+  const problemPath = getProblemDocPath(repoPath);
+  const lines = [
+    "# MCP Installation Problem",
+    "",
+    `Generated: ${new Date().toISOString()}`,
+    `Context: ${context}`,
+    "",
+    "The manager could not attach this MCP server. Fix the issues below.",
+    "",
+  ];
+  if (Array.isArray(errors) && errors.length > 0) {
+    lines.push("## Errors");
+    for (const err of errors) {
+      lines.push(`- ${err}`);
+    }
+    lines.push("");
+  }
+  lines.push("## Required Follow-up");
+  lines.push("- Review this file and fix the issues in the repo.");
+  lines.push("- Re-run validation and attach.");
+  lines.push("- Delete `docs/mcp_installation_problem.md` after successful attach.");
+  lines.push("");
+  await fs.mkdir(docsDir, { recursive: true });
+  await fs.writeFile(problemPath, `${lines.join("\n")}\n`, "utf8");
+}
+
+async function clearInstallationProblem(repoPath) {
+  const problemPath = getProblemDocPath(repoPath);
+  if (await fileExists(problemPath)) {
+    await fs.unlink(problemPath);
+  }
+}
+
+async function readHelpDocument() {
+  return fs.readFile(HELP_DOC_PATH, "utf8");
+}
+
+function resolveCodexHome() {
+  if (process.env.CODEX_HOME && process.env.CODEX_HOME.trim()) {
+    return path.resolve(process.env.CODEX_HOME.trim());
+  }
+  const home = process.env.USERPROFILE || process.env.HOME;
+  if (!home) {
+    throw new Error("Unable to resolve home directory or CODEX_HOME");
+  }
+
+  const codex = path.join(home, ".codex");
+  const codexOlga = path.join(home, ".codex-olga");
+  if (require("node:fs").existsSync(codex)) {
+    return codex;
+  }
+  if (require("node:fs").existsSync(codexOlga)) {
+    return codexOlga;
+  }
+  return codex;
+}
+
+function getCodexConfigPath() {
+  return path.join(resolveCodexHome(), "config.toml");
+}
+
+function toTomlString(value) {
+  if (!value.includes("'")) {
+    return `'${value}'`;
+  }
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function buildSelfMcpBlock() {
+  const serverPath = path.resolve(__filename);
+  return [
+    `[mcp_servers.${META_NAME}]`,
+    'command = "node"',
+    `args = [${toTomlString(serverPath)}]`,
+    "startup_timeout_sec = 30",
+  ].join("\n");
+}
+
+function stripSelfMcpBlock(content) {
+  const sectionHeader = `[mcp_servers.${META_NAME}]`;
+  const lines = content.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim() === sectionHeader);
+  if (start < 0) {
+    return { changed: false, content };
+  }
+
+  let end = start + 1;
+  while (end < lines.length) {
+    const trimmed = lines[end].trim();
+    if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+      break;
+    }
+    end += 1;
+  }
+
+  let from = start;
+  while (from > 0 && lines[from - 1].trim() === "") {
+    from -= 1;
+  }
+
+  lines.splice(from, end - from);
+  const next = `${lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}\n`;
+  return { changed: true, content: next };
+}
+
+function hasRuntimeDependencies() {
+  const localRequire = createRequire(__filename);
+  try {
+    localRequire.resolve("@modelcontextprotocol/sdk/package.json");
+    localRequire.resolve("zod/package.json");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function installSelfIntoCodex() {
+  const depState = {
+    ready: hasRuntimeDependencies(),
+    note: "Run 'npm install' in ymcp_manager if ready=false",
+  };
+  const configPath = getCodexConfigPath();
+  const configDir = path.dirname(configPath);
+  await fs.mkdir(configDir, { recursive: true });
+
+  const existing = (await fileExists(configPath)) ? await fs.readFile(configPath, "utf8") : "";
+  const cleaned = stripSelfMcpBlock(existing).content.trimEnd();
+  const block = buildSelfMcpBlock();
+  const next = cleaned.length > 0 ? `${cleaned}\n\n${block}\n` : `${block}\n`;
+
+  await fs.writeFile(configPath, next, "utf8");
+  return { installed: true, configPath, dependencies: depState };
+}
+
+async function uninstallSelfFromCodex() {
+  const configPath = getCodexConfigPath();
+  if (!(await fileExists(configPath))) {
+    return { uninstalled: true, configPath, existed: false };
+  }
+
+  const existing = await fs.readFile(configPath, "utf8");
+  const removed = stripSelfMcpBlock(existing);
+  if (!removed.changed) {
+    return { uninstalled: true, configPath, existed: true, removed: false };
+  }
+
+  await fs.writeFile(configPath, removed.content, "utf8");
+  return { uninstalled: true, configPath, existed: true, removed: true };
+}
+
+function asPathCandidate(pathOrName) {
+  if (!pathOrName || typeof pathOrName !== "string") {
+    return null;
+  }
+  if (pathOrName.includes("/") || pathOrName.includes("\\") || pathOrName.includes(":")) {
+    return normalizePath(pathOrName);
+  }
+  return null;
+}
+
+async function ensureRepoKnown(pathOrName) {
+  const existing = getRepoByPathOrName(pathOrName);
+  if (existing) {
+    return existing;
+  }
+  const candidatePath = asPathCandidate(pathOrName);
+  if (!candidatePath) {
+    return null;
+  }
+  if (!(await fileExists(candidatePath))) {
+    return null;
+  }
+  await addRepo(candidatePath);
+  return getRepoByPathOrName(candidatePath);
+}
+
+function parseMaybeJson(input) {
+  if (!input) {
+    return {};
+  }
+  return JSON.parse(input);
+}
+
+async function runCliCommandIfAny() {
+  const command = process.argv[2];
+  if (!command) {
+    return false;
+  }
+
+  const arg = process.argv[3];
+  if (command === "help" || command === "--help" || command === "-h") {
+    console.log(await readHelpDocument());
+    return true;
+  }
+
+  if (command === "install") {
+    console.log(JSON.stringify(await installSelfIntoCodex(), null, 2));
+    return true;
+  }
+  if (command === "uninstall") {
+    console.log(JSON.stringify(await uninstallSelfFromCodex(), null, 2));
+    return true;
+  }
+  if (command === "add") {
+    console.log(JSON.stringify(await addRepo(arg), null, 2));
+    return true;
+  }
+  if (command === "validate") {
+    const repo = await ensureRepoKnown(arg);
+    const targetPath = repo ? repo.path : arg;
+    const validation = await validateRepoPath(targetPath);
+    console.log(
+      JSON.stringify(
+        {
+          valid: validation.valid,
+          errors: validation.errors,
+          path: validation.path || normalizePath(targetPath),
+        },
+        null,
+        2
+      )
+    );
+    return true;
+  }
+  if (command === "attach") {
+    await ensureRepoKnown(arg);
+    console.log(JSON.stringify(await attachRepo(arg), null, 2));
+    return true;
+  }
+  if (command === "detach") {
+    console.log(JSON.stringify(detachRepo(arg), null, 2));
+    return true;
+  }
+  if (command === "list") {
+    console.log(JSON.stringify({ servers: listAll() }, null, 2));
+    return true;
+  }
+  if (command === "listAttached") {
+    console.log(JSON.stringify({ servers: listAttached() }, null, 2));
+    return true;
+  }
+  if (command === "remove") {
+    console.log(JSON.stringify(removeRepo(arg), null, 2));
+    return true;
+  }
+  if (command === "reconfig") {
+    const opts = parseMaybeJson(process.argv[4]);
+    console.log(JSON.stringify(await reconfigRepo(arg, opts), null, 2));
+    return true;
+  }
+
+  console.error(
+    `Unknown command '${command}'. Use: help | install | uninstall | add | validate | attach | detach | list | listAttached | remove | reconfig`
+  );
+  process.exitCode = 1;
+  return true;
+}
+
+async function main() {
+  const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+  const { z } = await import("zod");
+
+  const server = new McpServer({
+    name: META_NAME,
+    version: META_VERSION,
+    description: "Local meta-MCP manager for local git-hosted MCP servers",
+  });
+
+  const registerTool = (name, description, schema, handler) => {
+    if (typeof server.registerTool === "function") {
+      server.registerTool(name, { description, inputSchema: schema }, handler);
+      return;
+    }
+    if (typeof server.tool === "function") {
+      server.tool(name, description, schema, handler);
+      return;
+    }
+    throw new Error("Unsupported @modelcontextprotocol/sdk tool registration API");
+  };
+
+  registerTool("help", "Show MCP server authoring guide used by ymcp-manager", {}, async () =>
+    toResult({ guide: await readHelpDocument() })
+  );
+
+  registerTool(
+    "add",
+    "Add MCP repo path to manager list without attaching",
+    { path: z.string().min(1) },
+    async ({ path: repoPath }) => toResult(await addRepo(repoPath))
+  );
+
+  registerTool(
+    "validate",
+    "Validate MCP repo by path or known name",
+    { pathOrName: z.string().min(1) },
+    async ({ pathOrName }) => {
+      const repo = getRepoByPathOrName(pathOrName);
+      const targetPath = repo ? repo.path : pathOrName;
+      const validation = await validateRepoPath(targetPath);
+      return toResult({
+        valid: validation.valid,
+        errors: validation.errors,
+        path: validation.path || normalizePath(targetPath),
+      });
+    }
+  );
+
+  registerTool(
+    "attach",
+    "Validate and attach MCP repo process via stdio",
+    { pathOrName: z.string().min(1) },
+    async ({ pathOrName }) => toResult(await attachRepo(pathOrName))
+  );
+
+  registerTool(
+    "detach",
+    "Detach attached MCP repo process",
+    { pathOrName: z.string().min(1) },
+    async ({ pathOrName }) => toResult(detachRepo(pathOrName))
+  );
+
+  registerTool("listAttached", "List currently attached MCP repos", {}, async () =>
+    toResult({ servers: listAttached() })
+  );
+
+  registerTool("list", "List all known MCP repos", {}, async () => toResult({ servers: listAll() }));
+
+  registerTool(
+    "remove",
+    "Remove MCP repo from manager list",
+    { pathOrName: z.string().min(1).optional() },
+    async ({ pathOrName }) => toResult(removeRepo(pathOrName))
+  );
+
+  registerTool(
+    "reconfig",
+    "Update runtime options for a managed MCP server",
+    { pathOrName: z.string().min(1), opts: z.any() },
+    async ({ pathOrName, opts }) => toResult(await reconfigRepo(pathOrName, opts))
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  log("meta MCP server started");
+
+  const shutdown = async () => {
+    await closeAll();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+runCliCommandIfAny()
+  .then((handled) => {
+    if (!handled) {
+      return main();
+    }
+    return undefined;
+  })
+  .catch((error) => {
+    console.error(`[${META_NAME}] fatal:`, error);
+    process.exit(1);
+  });

package/uninstall.bat

@@ -0,0 +1,4 @@
+@echo off
+setlocal
+node "%~dp0server.js" uninstall
+endlocal

package/uninstall.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+set -eu
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+node "$SCRIPT_DIR/server.js" uninstall