MCP: claim_subdomain and bind_subdomain tools need a design first (the daemon models routes, not reservations)

Open
  • Is something wrong?
#2,145 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
go
Domain
api, backend-api-design, cli, documentation

Research direction

Start by reading #1971 and the existing route-tool conventions, then inspect the .proto definitions and the MCP and CLI entry points for route operations. Write the design under docs/architecture/, choosing an ownership model, naming the motivating agent workflow, and specifying RPCs, CLI verbs, tool schemas, scopes, and the downstream contract. Done means implementation issues with separate acceptance criteria are filed and no code is changed.

Written by the indexing model from the issue text.

Description

enhancement

Follow-up to the decision on #1971. This issue is the design for two new MCP tools, not their implementation.

Decision this comes from

The sprint owner decided on 2026-09-28 to add claim_subdomain (a bare reservation with no bind) and bind_subdomain (rebind an existing claim by id) to the MCP tool surface. list_subdomains and delete_subdomain are not being added: list_routes and delete_route already cover them. (The one-line list_routes description tweak suggested in #1971 was not part of this decision; it is independent and cheap.)

Problem

expose_port claims and binds in one upsert, and no RPC returns a claim without also binding it. So a bare reservation cannot be expressed today, and there is nothing for a claim_subdomain tool to wrap.

The first question the design must answer, before any code

The daemon models routes. A reservation that exists without a bound route, and that counts against a quota, is a concept that today lives only in a hosted control plane running on top of the daemon. Adding these tools raises an ownership question:

  • A. The daemon grows a reservation model of its own, with an RPC to claim one, so the tools work against any daemon.
  • B. The tools ship in the MCP surface but are only usable against a server that advertises the capability, and the daemon itself does not model reservations.
  • C. The tools live in a hosted-control-plane layer and not in this repository's MCP server.

The design should pick one and say why, including what it means for the open-core boundary and for self-hosted users, who have no quota to reserve against.

Requirements the design must meet (repository conventions)

  • Proto first: any new RPC is defined in .proto with google.api.http annotations, and REST, the client, and OpenAPI regenerate from it. States or kinds are enums, not strings.
  • CLI first: a containarium subcommand exists before the MCP tool, and the tool is a thin wrapper over the same Go function.
  • Scoped like the existing route tools (routes:read and routes:write), with the scope choice stated.
  • A downstream control plane that serves OSS-shaped paths will need to mirror any new RPC from this proto; note the contract it must keep.

The condition attached to the original recommendation

The original recommendation was to add these two only "if a real agent workflow needs a bare reservation as a distinct step from claim+bind". The design must name that workflow concretely, so the tools are justified by a use case and not only by the decision to add them.

Acceptance criteria

  • A design doc under docs/architecture/ answers the ownership question above, names the motivating workflow, and lists the RPC(s), CLI verb(s), and tool schemas.
  • Implementation issues are filed from that design, each with its own acceptance criteria.
  • Nothing is implemented from this issue.

Refs #1971.

Dominant language
Go
Stars
296
Forks
38
Avg merge
7h 16m
Merged PRs (30d)
689

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from FootprintAI/Containarium

All issues in FootprintAI/Containarium

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.