agentic-community / agentic-community/mcp-gateway-registry

feat: standalone boto3 migration tool to export local assets into an AWS Agent Registry

Open
#1,339 1 comment 0 reactions 0 assignees View on GitHub
agentcore api enhancement federation
Dominant language
Python
Stars
911
Forks
234
Avg merge
1d 11h
Merged PRs (30d)
62

Description

## Problem Statement

The registry can **ingest** assets *from* an AWS Agent Registry (Amazon Bedrock AgentCore, `bedrock-agentcore-control`) via `registry/services/federation/agentcore_client.py`. There is no path in the **reverse** direction: taking this registry's own assets and publishing them *into* an AWS Agent Registry.

This is needed for a **one-time migration / cutover** from this registry to an AWS Agent Registry: do a bulk export now, run both registries in parallel for a period, then perform a single incremental "delta" move as the final cutover.

## Proposed Solution

A **standalone CLI script** (`python -m cli.agentcore_export`) that:

1. Reads this registry's **local** servers, agents, and skills via the existing export API (so it never touches credentials).
2. Maps each asset into the AgentCore descriptor format (MCP / A2A / AGENT_SKILLS).
3. Creates/updates registry records in a target AWS Agent Registry via boto3.
4. Records a sidecar manifest (`agentcore_export_manifest.json`) of `local-path -> {recordId, content_hash, exported_at}` so a later `--delta` run moves only what changed.

It is explicitly a **migration tool, not a continuous sync daemon** — no scheduler.

## User Stories

- As a platform operator migrating off this registry, I want to bulk-publish all my local servers/agents/skills into an AWS Agent Registry so consumers can find them there.
- As that operator, I want a final incremental cutover that pushes only the deltas accumulated during the parallel-run period, without creating duplicates.
- As a security-conscious operator, I want assurance that **no credentials/secrets** ever leave my registry during export.

## Acceptance Criteria

- [ ] `python -m cli.agentcore_export --dry-run` lists what would be exported (per type) and the mapped descriptors, with no AWS writes.
- [ ] Bulk run creates one AgentCore record per exported local asset and writes the manifest.
- [ ] Only **local** assets are exported — federated/peer/ingested/read-only items are excluded.
- [ ] **No credentials** are transmitted: MCP servers export `auth_scheme` + placeholder headers only; A2A agents export `securitySchemes` definitions; skills carry no auth.
- [ ] `--delta` re-run creates new records for added assets, updates changed assets (by content hash), skips unchanged, and (with `--prune`) deletes locally-removed ones.
- [ ] Re-runs are duplicate-safe: an "already exists" record reconciles to an update (by name lookup), and the manifest is flushed incrementally so a crash mid-run is resumable.
- [ ] `--rollback` deletes all records recorded in the manifest (optionally the registry too).
- [ ] Sanitized record-name collisions abort the run before any AWS write, naming the conflict.
- [ ] Target registry is created if missing, with a configurable authorizer (`AWS_IAM` default; `CUSTOM_JWT` optional).
- [ ] `submit-for-approval` is configurable (submit vs. leave-draft).
- [ ] Cross-account export supported via `--assume-role-arn` (mirrors ingestion client).
- [ ] Skill markdown is exported inline when available; absent bodies are fetched only from same-origin URLs (SSRF/token-leak guard), else referenced.
- [ ] Unit tests cover the pure mapping functions, delta-diff logic, reconciliation, and a no-secret-leak assertion.

## Out of Scope (v1)

- Custom entities (`descriptorType=CUSTOM`) — servers/agents/skills only.
- Continuous/scheduled sync, daemon mode, or a UI surface.
- Bi-directional conflict resolution — `--delta` treats this registry as source of truth (with `--skip-existing` escape hatch).
- Per-type / per-visibility multiple target registries — single target registry only.

## Dependencies

- `boto3` (already a project dependency, `pyproject.toml`).
- Existing export endpoints: `/api/federation/{servers,agents}`, `/api/skills`.
- A registry auth token (`.token`) with access to those endpoints.
- AWS credentials with `bedrock-agentcore-control` create/update/delete permissions.

## Related

- Mirrors ingestion: `registry/services/federation/agentcore_client.py` (AgentCore federation).
- Reuses local-origin selection semantics from `registry/services/ard_service.py` (#1296).

---

A full low-level design (architecture, mapping spec, CLI, models, multi-persona review, and testing plan) has been prepared. A high-level design summary will be added as a comment below.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.