DEV Community: Miguel Angelo Sepulveda

Something is squatting on port 3000

Miguel Angelo Sepulveda — Mon, 10 Aug 2026 16:12:33 +0000

I run my AI agent in a terminal split inside my IDE. Most of the time, it's a good arrangement. The DX beats the dedicated editor extensions, since the AI companies release console-first and the CLI is where new features land. The agent edits files, I watch the diffs and see what it's doing and why, and everyone stays in their lane.

Then the agent decides it needs a dev server. It runs pnpm dev with its shell tool, the way it runs everything else, and at that moment a process comes into existence that my editor knows nothing about. It's not in my task list. <leader>ow shows my overseer tasks, humming along with their output buffers and their proper lifecycle — and this thing is not among them. I can't stop it from the editor. I can't tail it. If the agent's session dies, the process doesn't die with it; it just loses its parent and keeps listening on port 3000, along with whatever child processes it spawned along the way.

I found this out the usual way: a fresh pnpm dev refusing to bind, a ps aux | grep node full of processes whose sessions had ended an hour ago, and me killing PIDs at some hour when I should have known better.

The irritating part is the asymmetry. The tasks I start go through overseer.nvim, which is the piece of my config I'd defend in a fight. My tasks appear in a list. They have output I can open. When I stop one, its whole process tree gets torn down properly. The agent, sitting in a terminal buffer inside the same editor, gets none of that. It has a shell and a prayer.

The fix, stated plainly

So I built overseer-nvim-mcp, an MCP server that gives the agent the same view of overseer that I have. Seven tools: list tasks, list templates, run, tail, restart, stop, dispose. When the agent needs a dev server now, it starts an overseer task — a real one, in the same list as mine, with the same teardown semantics. I can watch it. I can stop it. When the session ends, nothing is orphaned, because overseer owns the process, not the agent's shell.

That's the whole idea. The rest of this post is the details I cared about getting right, because the idea is obvious and the details are where it either works or annoys you forever.

The transport is just an environment variable

My least favorite genre of developer tool is the one that "discovers" things. It greps process lists, hashes working directories, scans for sockets, and works right up until it confidently connects to the wrong instance.

This server does none of that, because Neovim already solved the problem. Every process spawned inside a Neovim terminal buffer inherits $NVIM — the address of that editor's RPC socket. The MCP client (Claude Code, in my case) inherits it from the terminal. The server is a child of the client, so it inherits it too. Everything the server does is nvim_exec_lua over msgpack-RPC to that one address.

There is no configuration for this. There couldn't be — there's nothing to configure. The variable either points at the Neovim you're sitting in, or it isn't set, in which case the server registers zero tools and gets out of the way. Run the agent outside Neovim and the server simply has nothing to say, which is the correct amount.

Sharing a task list without stepping on it

The part that took actual thought: the agent's tasks and my tasks live in the same list. That's the point — one list, one view. But it means an agent deciding to "clean up" could kill the dev server I started, and an agent restarting "its" task could restart mine.

So every task is tagged with who started it. stop, restart, and dispose refuse to touch a running task the agent didn't start, unless the agent explicitly passes a force flag. The reasoning is about failure costs: a wrong refusal costs the agent one extra tool call to say "yes, really." A wrong stop kills a process I was using. Those aren't symmetric, so the default isn't either.

The tasks the agent starts, it can manage freely. Mine, it has to ask about. This has so far produced exactly the behavior I wanted: the agent restarts its own watcher without asking and leaves my servers alone.

Agents are terrible at waiting

An agent that starts a dev server immediately wants to know when it's ready. The naive pattern is polling — tail the output, sleep, tail again, burn tokens reading the same Turbopack banner five times.

overseer_tail takes a wait_for parameter instead: a regex, and the call blocks until a line matches it. The agent says "wake me when you see ready - listening" and gets exactly one response, when it matters. The call returns on a match, on task exit, or at the timeout — and the result says which of the three happened, so a timeout can't be misread as a server that came up fine. The blocking happens in the server process, outside Neovim, so the editor never freezes while somebody waits on a webpack build.

This is a small feature that changes how the whole thing feels. The agent starts a server, waits on the ready line, and moves on, instead of guessing at sleep durations in a loop.

Templates, or: your repo already knows its commands

Overseer discovers runnable tasks through providers — npm scripts, make targets, just recipes, go-task, VS Code task definitions. Whatever your setup discovers, the agent sees through overseer_list_templates, so instead of reconstructing npm run test:e2e -- --headed from a README, it runs the task by name, the same one I'd pick from the menu.

Plenty of repos return an empty template list, and that's fine. A raw command is the primary path, not a fallback; templates are a bonus when the repo declares them.

And when the task doesn't exist yet, it can create one

A raw command is a one-off, though. It lives in the task list until the session ends, and next time the agent has to reconstruct it. Some commands deserve better — every project has that one incantation you run daily that never made it into an npm script, a Makefile, or a Taskfile.

For those, the server publishes a slash command (/mcp__overseer__directory_local_task in Claude Code) that has the agent write the task into the project itself, using overseer's own register_template in a .nvim.lua at the project root. It's generated against live editor state rather than being a canned recipe: it checks whether exrc is actually enabled and whether a .nvim.lua already exists, and it warns about the two things that make a correct setup look broken — Neovim will ask you to :trust the file, and the new task won't appear until a restart.

The part I find interesting: the agent isn't limited to running the tasks my project already declares. It can author new ones — real overseer templates that show up in <leader>ow next to everything else and outlive the session that created them. The AI stops being a guest that borrows my task runner and starts leaving useful things behind in it.

Who this is for

Any MCP client running inside a Neovim terminal works: Claude Code, Codex CLI, Gemini CLI, opencode. If you're on codecompanion or avante, mcphub.nvim gets you there.

If you're on LazyVim, you're one :LazyExtras toggle away — enable the overseer extra, then:

claude mcp add overseer -- npx -y overseer-nvim-mcp

That's the entire setup. The package is a single file on npm with zero runtime dependencies, which I mention because the median MCP server seems determined to install half of npm before it says hello.

There's a demo gif and the full tool reference in the README, and the server is in the official MCP registry as io.github.impossiblecode/overseer-nvim-mcp.

The general problem, briefly

Stepping back: the orphaned dev server is one instance of something more general. Agents run in our editors now, but they interact with our machines like SSH guests — a shell, a working directory, no awareness of the tooling we've spent years arranging around ourselves. Every long-running process an agent starts through a bare shell is state that our editor can't see and the agent can't reliably clean up.

The answer, at least here, wasn't to build the agent its own parallel infrastructure. It was to hand it mine. Overseer already knew how to run tasks, show them, and tear them down. The missing piece was a protocol adapter and some manners.

It works. My task list finally tells the truth about what's running on my machine, including the parts an AI started. And the next time something is squatting on port 3000, at least it will have a name.

Reading "Ham on Rye" and designing an MCP ecosystem

Miguel Angelo Sepulveda — Thu, 15 Jan 2026 12:32:28 +0000

I've been reading Ham on Rye again. Bukowski's semi-autobiographical novel about growing up poor in Los Angeles during the Depression, about a kid who finds himself at odds with every system designed to help him — school, family, social services. The book isn't about triumph. It's about survival through accumulated small dignities. Making something work that was never designed to work for you.

I kept thinking about this while staring at the platform's documentation problem — and while building the MCP ecosystem that would eventually solve it.

The honest shape of the problem

Here's what nobody talks about at conferences: most enterprise codebases are archaeological sites. Layers of decisions made by people who aren't here anymore, documented by systems that no longer exist, maintained by developers who learned the codebase through oral tradition and strategic grep commands.

This platform had the usual symptoms. Documentation lived in Confluence, in README files, in Swagger specs — some generated, some handwritten, none current — and in the heads of a few senior engineers who'd been there since the beginning.

When LLM agents started to be integrated into workflows, the promise was autonomy. Point an agent at a task, let it figure out what tools exist, let it call them. It didn't work that way. Every conversation started with a bunch of pasted context. "Here's the function signature. Here's what this parameter actually means — ignore the docs, they're wrong. Here's the service that owns this data."

The agents worked. But they worked like I work when my GPS is broken — many times stopping to ask for directions or deciding to guess on a road that leads nowhere safe.

What Model Context Protocol actually solves

MCP is Anthropic's answer to a question that sounds simple: how do you give an LLM structured access to external capabilities?

The naive answer is "put everything in the system prompt". This works until it doesn't. Context windows have limits. Prompts become unwieldy. Worse, you're making the LLM do the parsing work every time — figuring out which of the fifty functions you've described is actually relevant to this specific query.

MCP inverts this. Instead of describing everything upfront, you expose a discovery layer. Tools, resources, prompts — all described in a schema the LLM can query dynamically. The agent asks "what can I do?" and gets back a structured list. It asks "what's this tool's interface?" and gets a JSON schema. Then it calls what it needs.

The protocol is elegant. What isn't elegant is getting your actual codebase into that shape.

The generator: teaching a parser to read your mind

The first package I built was @mxconsulting/mcp-gen, a manifest generator that reads source code and extracts tool definitions from JSDoc annotations.

The simple version would just look for @mcp tags and scrape whatever's nearby. But the actual problem is harder. JSDoc doesn't have a standard for MCP tools. Developers write comments inconsistently. Sometimes the function name is on the next line. Sometimes it's an arrow function assigned to a const. Sometimes it's exported directly, sometimes through a re-export.

So the parser needed to be forensic:

private extractFunctionName(
  content: string,
  commentEndLine: number
): { lineNumber: number; functionName: string } | null {
  const lines = content.split('\n');

  for (let i = commentEndLine; i < Math.min(commentEndLine + 5, lines.length); i++) {
    const line = lines[i].trim();

    // Pattern 1: function functionName(
    const functionDeclaration = line.match(
      /^\s*(?:export\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/
    );
    if (functionDeclaration) {
      return { lineNumber: i + 1, functionName: functionDeclaration[1] };
    }

    // Pattern 2: const functionName = function(
    // Pattern 3: const functionName = (
    // Pattern 4: const functionName = async (
    // Pattern 5: exports.functionName =
    // Pattern 6: functionName: function(
    // ... and more
  }

  return null;
}

This isn't glamorous code. It's code that handles reality — the reality that your codebase has six different ways of defining functions, and you need to find them all.

The generator also validates what it finds. JSDoc parameters with type names in the wrong position, PHP-style variable prefixes copied by accident, descriptions that contain syntax rather than explanations — all caught before they become malformed tool definitions that confuse your agent at runtime.

private validateJSDocParameter(param: Spec, index: number): {
  isValid: boolean;
  errors: string[];
} {
  const errors: string[] = [];

  // Check for type names being used as parameter names
  const jsDocTypes = ['string', 'number', 'boolean', 'array', 'object'];
  if (param.name && jsDocTypes.includes(param.name.toLowerCase())) {
    errors.push(
      `Parameter ${index + 1}: '${param.name}' appears to be a type name ` +
      `rather than a parameter name. Malformed JSDoc syntax.`
    );
  }

  // ... more validation
}

When validation fails, you get line numbers. You get the original function name. You get a specific error that tells you what to fix. Because debugging "tool call failed" at 2 AM is not how anyone should spend their time.

The Kubernetes problem within the problem

Generating manifests is one thing. Getting them to the right place, keeping them current, and doing this across a cluster — that's the infrastructure layer.

Our platform runs on Kubernetes. The manifests needed to be ConfigMaps. The MCP server needed to mount those ConfigMaps. And when documentation changed (because it does change, if you've built a system where changing it is easy), the server needed to pick up the new version without manual intervention.

The traditional approach is to annotate your Deployment with ConfigMap checksums, then use something like Stakater Reloader to watch for changes and trigger rolling updates. This works for static configurations. It's insufficient when your ConfigMaps are generated, numerous, and can change independently of your code deployments.

So I built two components: a mutating admission webhook and a reloader controller.

The webhook: surgery at admission time

A mutating admission webhook intercepts pod creation and modifies the spec before Kubernetes acts on it. Mine looks for pods with specific annotations, finds matching ConfigMaps by label selector, and injects them as volumes.

const mutateHandler: express.RequestHandler = async (req, res) => {
  const pod = admissionReview.request?.object
  const annotations = pod.metadata?.annotations || {}

  // Check for opt-in annotation
  const mountConfigMapsByLabel =
    annotations['mcp.mxconsulting.net/mount-configmaps-by-label'] === 'true'

  if (!mountConfigMapsByLabel) {
    // Not our concern, allow without modification
    return res.json({ response: { allowed: true } })
  }

  // Process indexed label selectors
  let index = 0
  while (true) {
    const selector = annotations[`mcp.mxconsulting.net/configmap-label-selector.${index}`]
    const mountDir = annotations[`mcp.mxconsulting.net/configmap-base-mount-directory.${index}`]

    if (!selector) break

    const configMaps = await k8sApi.listConfigMapForAllNamespaces({
      labelSelector: selector,
    })

    for (const cm of configMaps.items) {
      // Calculate checksum for change detection
      const hash = crypto.createHash('sha256').update(JSON.stringify(cm.data)).digest('hex')

      // Inject volume and mount via JSON Patch
      patch.push({
        op: 'add',
        path: `/metadata/annotations/checksum~1configmap-${cm.metadata.name}`,
        value: hash,
      })
      // ... volume injection
    }

    index++
  }
}

The checksum calculation is the key detail. By storing a hash of each ConfigMap's contents as a pod annotation, we create a declarative trigger for the reloader. When the content changes, the checksum changes. When the checksum changes, the reloader notices.

The reloader: smart reconciliation

The reloader controller watches Deployments and ConfigMaps. When a relevant ConfigMap changes, it needs to update the corresponding Deployment's annotations so that Kubernetes sees a spec change and triggers a rollout.

The naive approach is brute force: on any ConfigMap change, check every Deployment, recalculate all checksums. This doesn't scale. With hundreds of ConfigMaps and dozens of Deployments, you spend all your time reconciling.

So the reloader implements smart reconciliation:

export async function main(): Promise<void> {
  const kubernetesController = new KubernetesController()
  const deploymentReconciler = new DeploymentReconciler(
    kubernetesController.getAppsApi(),
    kubernetesController.getCoreApi()
  )

  const smartReconciler = new SmartReconciler(
    kubernetesController.getAppsApi(),
    deploymentReconciler,
    memoryManager,
    metricsManager
  )

  const bruteForceReconciler = new BruteForceReconciler(/* ... */)

  // Smart reconciliation handles targeted updates
  // Brute force runs periodically as a safety net
  setInterval(async () => {
    if (ENABLE_SMART_RECONCILIATION) {
      await bruteForceReconciler.reconcileAllRelevantDeployments()
    }
  }, FULL_RECONCILIATION_INTERVAL_MS)
}

The smart reconciler tracks which Deployments care about which ConfigMaps. When ConfigMap X changes, it updates only Deployments that mount X. The brute force reconciler runs every few minutes as a safety net — catching any drift that smart reconciliation missed.

Both reconcilers share infrastructure: rate limiting (so we don't hammer the API server), caching (so we don't refetch unchanged data), and memory management (so long-running controllers don't leak).

The server: where it all comes together

The MCP server itself — @mxconsulting/mcp — loads manifest files from its mounted ConfigMap volumes, parses them, and exposes everything over HTTP (or stdio for local development).

export function setupServerWithManifests(server: McpServer) {
  const manifests = loadManifests()

  for (const manifest of manifests) {
    // Register manifest-level resource (summary of what's in this manifest)
    registerManifestResource(server, manifest)

    // Register individual tool resources (JSON descriptions)
    registerToolResources(server, manifest)

    // Register actual callable tools
    registerMcpTools(server, manifest)

    // Register static resources and templates
    registerManifestResources(server, manifest)
    registerManifestResourceTemplates(server, manifest)
  }

  // Category-based organization
  registerCategoryResources(server)
  registerOverviewResources(server)

  // Prompts and completion handlers
  registerPrompts(server)
  registerCompletionHandler(server)
}

The server exposes not just tools, but resources about tools. An LLM can fetch a category overview to understand what's available before diving into specifics. It can read a manifest summary to understand the shape of a subsystem. The protocol supports this naturally; the server makes it useful.

What Bukowski understood about systems

In Ham on Rye, young Henry Chinaski is assigned to write about President Hoover's visit to Los Angeles. He can't attend — Saturdays are consumed by his father's lawn ritual, where missing a single blade of grass means a beating. So he invents the whole thing: the motorcade, the secret service agents, the sun breaking through clouds as the President speaks. His teacher reads the essay to the class, calls it remarkable. Later she asks if he was actually there. He admits he wasn't. "That makes it all the more remarkable," she says. Walking home, Henry realizes: "So, that's what they wanted: lies. Beautiful lies. That's what they needed."

Enterprise documentation is full of beautiful lies. Swagger files that look complete but haven't been updated in eighteen months. README files that describe an architecture from three versions ago. Confluence pages that exist to prove documentation exists. Everyone pretends the system works because admitting otherwise means admitting nobody has time to fix it.

The system I built doesn't solve these problems through policy or discipline. It solves them through automation. Write a JSDoc comment above your function — the manifest generator finds it. Deploy a new ConfigMap — the webhook mounts it and the reloader propagates changes. Point an LLM at the server — it discovers everything automatically.

There's no dignity in a broken documentation system. There's also no dignity in pretending you can fix it through willpower. The dignity is in building something that survives contact with reality.

The result

Our LLM agents now discover available tools at runtime. They understand parameter schemas because the schemas are generated from actual type annotations. When we add a new capability, we add a JSDoc comment and redeploy — the agents pick it up automatically.

Was it worth four weeks of TypeScript compilation errors, webhook debugging, and Kubernetes API mocking? The honest answer is: ask me in a year, when I've forgotten the pain and only remember the outcomes.

But right now, at 3 AM, watching an agent autonomously discover and use tools written years ago without any extra prompting... Yeah, I think it was worth it.

Some systems are designed to be elegant. Some are designed to survive. The best ones manage both. I don't know which category this falls into yet.

But it works. And that's something.