Skip to content

feat: portable, versioned JSON export/import for namespaces #340

Description

@stn1slv

Problem

MetaMCP can bulk import/export MCP server configs, but a namespace — the unit that defines what an agent actually sees — is not portable. Namespace state lives only in PostgreSQL, reachable only through the admin UI: which servers belong to the namespace and their ACTIVE/INACTIVE status, per-tool ACTIVE/INACTIVE status, and tool overrides (name, title, description, annotations).

Consequences for teams running MetaMCP: a namespace change cannot be reviewed in a PR; a namespace cannot be promoted from dev to prod; a bad override cannot be rolled back or diffed; an instance cannot be rebuilt from source control after data loss.

Proposal

Add a portable, deterministic, secret-free, versioned JSON representation of a namespace, exposed via two tRPC procedures under frontend.namespaces.* (mirroring the existing mcpServers bulk path) with matching UI actions on the namespace page.

{
  "version": 1,
  "exportedAt": "2026-07-31T10:00:00Z",
  "namespace": {
    "name": "release-manager",
    "description": "Tools for release coordination",
    "servers": [{ "name": "github", "status": "ACTIVE" }],
    "tools": [
      { "server": "github", "name": "create_pull_request", "status": "ACTIVE",
        "override": { "description": "Create a PR into the release branch." } },
      { "server": "github", "name": "delete_repository", "status": "INACTIVE" }
    ]
  }
}

Design principles

  • Name-based, never UUID — portable across instances. (Overrides are internally keyed by tools.uuid; export denormalizes to (server, tool) names, import re-resolves them.)
  • No secrets — references servers by name only; embeds no env, bearer_token, or headers.
  • Deterministic — servers/tools sorted by a stable key, so two exports of the same namespace are byte-identical (Git-review friendly).
  • Create-only import (v1) — fails clearly if the namespace name already exists.
  • Fail fast on missing servers, but tolerate + warn on tools not yet discovered on the target.
  • Zero schema changes — existing tables/columns only.

Scope

  • PR 1: export (query + UI + tests + docs)
  • PR 2: import (mutation + UI + tests + docs)

Out of scope (for now): endpoints; update/merge semantics; embedding secrets or server config; auto-discovery of tools during import; any change to tool-override business logic.

I'd like to contribute this. Does the direction and format look acceptable before I open the export PR?

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions