feat(mcp): add Server Registry tools + port registry in servers.md (v0.10.0)

- Add MCP tools: servers_check_port, servers_list_registry, servers_add_entry
  - servers_check_port: returns free/allocated/mutex status for a port
  - servers_list_registry: returns full Port Allocation Registry as structured JSON
  - servers_add_entry: validates and writes new rows to tools/servers.md,
    rejects mutex ports (80/443) and duplicate allocations
- Add tools/mcp-server/src/handlers/servers.ts with registry parser and
  appendRegistryRow writer
- Bump MCP server to v0.10.0 (26 tools across 7 areas)
- Add Port Allocation Registry table to tools/servers.md with all known
  services and agent-readable 6-step workflow callout at top
- Add Server Registry Workflow section and trigger to AGENTS.md
- Fix tools/servers-audit.sh: remove 'local' keyword at top-level scope
  (lines 1225, 1229, 1250); change grep -Eq to grep -Fxq for process names
  with regex metacharacters (GitHub Desktop Helper (Renderer))
- Fix broken symlink ~/bin/servers-audit.sh -> tools/servers-audit.sh
- Add tools/servers-audit-bugs.md documenting the three bugs
- Update CHANGELOG.md [2.0.0] with full change summary

Author: noelsaw1

AGENTS.md

@@ -129,7 +129,7 @@ If you need a **persistent background server** (e.g., for HTTP mode or external
 
 #### Available MCP Tools
 
-The server exposes **23 typed tools** across 6 areas:
+The server exposes **26 typed tools** across 7 areas:
 
 | Area | Tools |
 |------|-------|
@@ -139,6 +139,7 @@ The server exposes **23 typed tools** across 6 areas:
 | **Query Monitor** | `qm_profile_page`, `qm_slow_queries`, `qm_duplicate_queries` |
 | **AJAX Testing** | `wp_ajax_test` |
 | **Tmux** | `tmux_start`, `tmux_send`, `tmux_capture`, `tmux_stop`, `tmux_list`, `tmux_status` |
+| **Server Registry** | `servers_check_port`, `servers_list_registry`, `servers_add_entry` |
 
 #### Available MCP Prompts
 
@@ -190,8 +191,25 @@ For detailed command syntax, parameters, examples, and troubleshooting, see:
 | “login to WP admin”, “browser automation”, “inspect DOM” | `pw-auth` |
 | “test this AJAX endpoint” | `wp-ajax-test` |
 | “slow”, “bottleneck”, “profile” | QM profiling (`qm_profile_page`, `qm_slow_queries`, `qm_duplicate_queries`) + WP Performance Timer |
-| “fix”, “verify”, “iterate”, “debug” | Fix-Iterate Loop |
+| “fix”, “verify”, “iterate”, “debug” | Fix-Iterate Loop || "install", "add", "set up" a new server, tool, or daemon | **Server Registry Workflow** (see below) |
 
+### Server Registry Workflow
+
+**Any time a new networked service is installed** (Homebrew daemon, Docker container, local dev server, etc.), run this workflow before and after:
+
+1. **Read the port registry** — `cat ~/bin/ai-ddtk/tools/servers.md` — check for conflicts with the intended port
+2. **Reserve the port** — add a row to the Port Allocation Registry in `tools/servers.md` before installing
+3. **Install and start** the service
+4. **Run the audit** — `~/bin/ai-ddtk/tools/servers-audit.sh --output /tmp/servers-now.md`
+5. **Confirm no new conflicts** in the audit output
+6. **Update the registry entry** with confirmed port, hostname, and any notes
+
+**Port 80/443 are a mutex.** Only one service holds them at a time: Dify (Docker), Valet (*.test), or Local WP (*.local). Never bind `0.0.0.0:80` from a new service without checking first.
+
+**Hostname namespace rules:**
+- `*.local` — managed exclusively by Local WP; never add manually
+- `*.test` — managed by Valet/dnsmasq; add via `valet proxy <name> --to=http://127.0.0.1:<port>`
+- Manual `/etc/hosts` entries for `.test` hostnames **override dnsmasq** — avoid unless intentional
 ### Task Management
 
 Use task tools for complex or multi-step work. Mark tasks complete immediately after finishing them.

CHANGELOG.md

@@ -13,6 +13,17 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Do not edit a version block that has already been committed and pushed
 -->
 
+## [2.0.0] - 2026-04-11
+
+### Added
+- **MCP tools: `servers_check_port`, `servers_list_registry`, `servers_add_entry`** — three new Server Registry tools in MCP server v0.10.0. `servers_list_registry` returns the full Port Allocation Registry from `tools/servers.md` as structured JSON so agents never need to parse markdown. `servers_check_port` returns `free`, `allocated`, or `mutex` for any given port with the conflicting entry if taken. `servers_add_entry` validates the port is not already allocated or a mutex port (80/443), then writes the new row to `tools/servers.md` with correct table formatting — preventing duplicate ports and malformed table edits. These tools enforce the Server Registry Workflow automatically rather than relying on agents reading instructions.
+- **Server Registry Workflow in `AGENTS.md`** — new "Server Registry Workflow" section and workflow trigger (`"install", "add", "set up" a new server, tool, or daemon`) instructs all agents to read `tools/servers.md`, reserve a port, install, audit, and update before and after adding any networked service.
+- **Port Allocation Registry in `tools/servers.md`** — machine-readable registry table with all known local services (Dify, Valet, Local WP, Homebrew MySQL/Postgres/Ollama, Docker services) and port 80/443 mutex rules. Agents are instructed at the top of the file with a 6-step workflow callout.
+- **Bug fixes: `tools/servers-audit.sh`** — three crashes fixed: (1) `local` keyword used outside a function at lines 1225, 1229, 1250 — replaced with bare variable initialization; (2) `grep -Eq "^${lower_name}$"` with unescaped regex metacharacters from process names containing `(` — changed to `grep -Fxq` (fixed-string whole-line match); (3) broken symlink `~/bin/servers-audit.sh` pointing to non-existent `experimental/servers-audit.sh` — updated to `~/bin/ai-ddtk/tools/servers-audit.sh`.
+
+### Changed
+- **MCP server version bump to v0.10.0** — new Server Registry area added; tool count updated from 23 to 26 across 7 areas in AGENTS.md.
+
 ## [1.9.1] - 2026-04-09
 
 ### Changed

tools/mcp-server/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-ddtk-mcp",
-  "version": "0.9.0",
-  "description": "AI-DDTK MCP server for LocalWP, pw-auth, wp-ajax-test, tmux, WPCC, Query Monitor, and post-flight session cleanup workflows",
+  "version": "0.10.0",
+  "description": "AI-DDTK MCP server for LocalWP, pw-auth, wp-ajax-test, tmux, WPCC, Query Monitor, post-flight session cleanup, and server port registry workflows",
   "type": "module",
   "main": "dist/src/index.js",
   "bin": {

tools/mcp-server/src/handlers/servers.ts

@@ -0,0 +1,197 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { homedir } from "node:os";
+
+const REGISTRY_HEADER = "| Port | Service | Owner | Hostname | Notes |";
+const REGISTRY_SEPARATOR = "|------|---------|-------|----------|-------|";
+const MUTEX_PORTS = new Set([80, 443]);
+
+export type PortStatus = "free" | "allocated" | "mutex";
+
+export type RegistryEntry = {
+  port: number;
+  service: string;
+  owner: string;
+  hostname: string;
+  notes: string;
+};
+
+export type ServersCheckPortResult = Record<string, unknown> & {
+  port: number;
+  status: PortStatus;
+  entry: RegistryEntry | null;
+  registryPath: string;
+};
+
+export type ServersListRegistryResult = Record<string, unknown> & {
+  entries: RegistryEntry[];
+  allocatedPorts: number[];
+  mutexPorts: number[];
+  registryPath: string;
+};
+
+export type ServersAddEntryResult = Record<string, unknown> & {
+  added: boolean;
+  entry: RegistryEntry;
+  conflict: RegistryEntry | null;
+  registryPath: string;
+  message: string;
+};
+
+export interface ServersHandlerDeps {
+  repoRoot: string;
+  registryPath?: string;
+}
+
+function resolveRegistryPath(repoRoot: string, override?: string): string {
+  if (override) {
+    return override.startsWith("~") ? override.replace("~", homedir()) : override;
+  }
+  return path.join(repoRoot, "tools/servers.md");
+}
+
+/**
+ * Parse the Port Allocation Registry table from servers.md.
+ * Returns only rows that begin with a numeric port (skips mutex-only rows
+ * that start with bold text like "**MUTEX**").
+ */
+function parseRegistry(content: string): RegistryEntry[] {
+  const lines = content.split("\n");
+  const tableStart = lines.findIndex((l) => l.includes(REGISTRY_HEADER));
+  if (tableStart === -1) return [];
+
+  const entries: RegistryEntry[] = [];
+
+  for (let i = tableStart + 2; i < lines.length; i++) {
+    const line = lines[i].trim();
+    // Stop at blank line or non-table line
+    if (!line.startsWith("|") || line === "") break;
+
+    const cells = line
+      .split("|")
+      .map((c) => c.trim())
+      .filter((_, idx, arr) => idx > 0 && idx < arr.length - 1);
+
+    if (cells.length < 4) continue;
+
+    const portNum = parseInt(cells[0] ?? "", 10);
+    if (isNaN(portNum)) continue; // skip mutex header rows
+
+    entries.push({
+      port: portNum,
+      service: cells[1] ?? "",
+      owner: cells[2] ?? "",
+      hostname: cells[3] ?? "",
+      notes: cells[4] ?? "",
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Append a new row immediately before the blank line that follows the last
+ * table row, preserving the existing table formatting.
+ */
+function appendRegistryRow(content: string, entry: RegistryEntry): string {
+  const lines = content.split("\n");
+  const tableStart = lines.findIndex((l) => l.includes(REGISTRY_HEADER));
+  if (tableStart === -1) {
+    throw new Error("Port Allocation Registry table not found in servers.md");
+  }
+
+  // Find the last table row (last line beginning with "|" after tableStart)
+  let lastTableRow = tableStart + 1; // separator line
+  for (let i = tableStart + 2; i < lines.length; i++) {
+    if (lines[i].trim().startsWith("|")) {
+      lastTableRow = i;
+    } else {
+      break;
+    }
+  }
+
+  const newRow = `| ${entry.port} | ${entry.service} | ${entry.owner} | ${entry.hostname} | ${entry.notes} |`;
+  lines.splice(lastTableRow + 1, 0, newRow);
+  return lines.join("\n");
+}
+
+export function createServersHandlers(deps: ServersHandlerDeps) {
+  const { repoRoot, registryPath: registryPathOverride } = deps;
+
+  async function checkPort(port: number): Promise<ServersCheckPortResult> {
+    const registryPath = resolveRegistryPath(repoRoot, registryPathOverride);
+    const content = await readFile(registryPath, "utf8");
+    const entries = parseRegistry(content);
+
+    if (MUTEX_PORTS.has(port)) {
+      return {
+        port,
+        status: "mutex",
+        entry: null,
+        registryPath,
+      };
+    }
+
+    const match = entries.find((e) => e.port === port);
+    return {
+      port,
+      status: match ? "allocated" : "free",
+      entry: match ?? null,
+      registryPath,
+    };
+  }
+
+  async function listRegistry(): Promise<ServersListRegistryResult> {
+    const registryPath = resolveRegistryPath(repoRoot, registryPathOverride);
+    const content = await readFile(registryPath, "utf8");
+    const entries = parseRegistry(content);
+
+    return {
+      entries,
+      allocatedPorts: entries.map((e) => e.port),
+      mutexPorts: [...MUTEX_PORTS],
+      registryPath,
+    };
+  }
+
+  async function addEntry(entry: RegistryEntry): Promise<ServersAddEntryResult> {
+    const registryPath = resolveRegistryPath(repoRoot, registryPathOverride);
+    const content = await readFile(registryPath, "utf8");
+    const entries = parseRegistry(content);
+
+    // Check for conflict
+    const conflict = entries.find((e) => e.port === entry.port) ?? null;
+    if (conflict) {
+      return {
+        added: false,
+        entry,
+        conflict,
+        registryPath,
+        message: `Port ${entry.port} is already allocated to "${conflict.service}" (${conflict.owner}). Choose a different port.`,
+      };
+    }
+
+    if (MUTEX_PORTS.has(entry.port)) {
+      return {
+        added: false,
+        entry,
+        conflict: null,
+        registryPath,
+        message: `Port ${entry.port} is a mutex port shared by Dify, Valet, and Local WP. Do not register individual services on it.`,
+      };
+    }
+
+    const updated = appendRegistryRow(content, entry);
+    await writeFile(registryPath, updated, "utf8");
+
+    return {
+      added: true,
+      entry,
+      conflict: null,
+      registryPath,
+      message: `Port ${entry.port} registered for "${entry.service}" in ${registryPath}.`,
+    };
+  }
+
+  return { checkPort, listRegistry, addEntry };
+}