agentic-community / agentic-community/mcp-gateway-registry
feat: standalone boto3 migration tool to export local assets into an AWS Agent Registry
- 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
Assessment
This issue has not been assessed yet.