8 tools 28 tests green MCP over streamable HTTP, verified stateful and stateless linux/arm64 image builds · deploys via the pipeline, by digest
The governance invariant, in one line: no tool can deploy, merge, push, or destroy — a deployment happens (and is torn down) exactly one way: a human approves the pull request this server opened, and the merge does the rest.

## 🔍 `blueprint_search` live output

Ranks the whole catalog against plain language; returns each blueprint's full contract (inputs, cost, maturity).

### 1 · The builder asks

“I want to smoke test that the deploy path works.”

### 2 · Claude calls the tool

    {
      "tool": "blueprint_search",
      "arguments": {
        "query": "smoke test that the deploy path works"
      }
    }

### 3 · Captured output

    {
      "query": "smoke test that the deploy path works",
      "results": [
        {
          "match_score": 18.0,
          "name": "hello-world",
          "version": "0.1.0",
          "maturity": "supported",
          "summary": "Trivial tagged stack that proves the deploy path end to end: one S3 bucket and one SSM deployment marker, carrying the full cornell:* tagging convention.",
          "matches": [
            "prove the deploy path",
            "hello world",
            "smoke test a deployment",
            "check the pipeline works"
          ],
          "inputs": {
            "owner_netid": {
              "type": "string",
              "required": true,
              "description": "NetID of the person who owns the deployment (cornell:owner)"
            }
          },
          "singleton": true,
          "cost": {
            "baseline_monthly_usd": 0,
            "scales_with": []
          },
          "data_classification": [
            "public"
          ]
        }
      ]
    }

## 🏗️ `deployment_create` live output

dry_run=true returns the full plan — repo, registration PR, stack, cost — for the human to confirm. Nothing deploys until a human merges the PR.

### 1 · The builder asks

“Deploy the hello-world blueprint for me. I'm tmf77.”

### 2 · Claude calls the tool

    {
      "tool": "deployment_create",
      "arguments": {
        "blueprint": "hello-world",
        "deployment_name": "hello-world",
        "owner_netid": "tmf77",
        "dry_run": true
      }
    }

### 3 · Captured output

    {
      "dry_run": true,
      "plan": {
        "blueprint": "hello-world v0.1.0 (supported)",
        "stack": "aidlc-main-hello-world",
        "estimated_cost": {
          "baseline_monthly_usd": 0,
          "scales_with": []
        },
        "new_repo": "cu-aaii/deploy-hello-world",
        "registration_pr": {
          "repo": "cu-aaii/ai-dlc-workshop",
          "edits": "pipeline/pipeline.yml \u2014 one new BlueprintDeploy action",
          "parameter_overrides": {
            "Application": "aidlc",
            "Environment": "main",
            "Owner": "tmf77",
            "SourceCommitId": "#{GitRepository.CommitId}"
          }
        },
        "governance": "Deploys only when a human approves and merges the registration PR."
      }
    }

## 📊 `deployment_read` graceful degradation — no AWS creds on this laptop; live values on AgentCore

The whole chain in one view: registration PR → pipeline stages → CloudFormation stack.

### 1 · The builder asks

“Is my hello-world deployment live yet?”

### 2 · Claude calls the tool

    {
      "tool": "deployment_read",
      "arguments": {
        "deployment_name": "hello-world"
      }
    }

### 3 · Captured output

    {
      "deployment": "hello-world",
      "open_registration_prs": [],
      "pipeline": {
        "error": "AWS call failed while reading pipeline aidlc-main: TokenRetrievalError: Error when retrieving token from sso: Token has expired and refresh failed"
      },
      "stack": {
        "error": "AWS call failed while describing stack aidlc-main-hello-world: TokenRetrievalError: Error when retrieving token from sso: Token has expired and refresh failed"
      }
    }

## ✏️ `deployment_update` live output

Changes become a branch + pull request — never a direct push. The review gate stays unbypassable.

### 1 · The builder asks

“Update the README in my deployment repo.”

### 2 · Claude calls the tool

    {
      "tool": "deployment_update",
      "arguments": {
        "repo": "deploy-hello-world",
        "title": "Clarify usage docs",
        "description": "Expand the README usage section.",
        "files": {
          "README.md": "# hello-world\n\nUpdated usage docs..."
        },
        "dry_run": true
      }
    }

### 3 · Captured output

    {
      "dry_run": true,
      "plan": {
        "repo": "cu-aaii/deploy-hello-world",
        "branch": "propose/87278",
        "files_changed": [
          "README.md"
        ],
        "pr_title": "Clarify usage docs"
      }
    }

## 🩺 `deployment_health` graceful degradation — no AWS creds on this laptop; live values on AgentCore

Stack status, failure events, and an inventory audit that every resource carries the four cornell:* tags.

### 1 · The builder asks

“Is my deployment healthy?”

### 2 · Claude calls the tool

    {
      "tool": "deployment_health",
      "arguments": {
        "deployment_name": "hello-world"
      }
    }

### 3 · Captured output

    {
      "deployment": "hello-world",
      "stack": {
        "error": "AWS call failed while describing stack aidlc-main-hello-world: TokenRetrievalError: Error when retrieving token from sso: Token has expired and refresh failed"
      },
      "tag_inventory": {
        "error": "AWS call failed while listing resources tagged aidlc-main-hello-world: TokenRetrievalError: Error when retrieving token from sso: Token has expired and refresh failed"
      },
      "healthy": false
    }

## 🔄 `deployment_restart` graceful degradation — no AWS creds on this laptop; live values on AgentCore

Retries a failed pipeline stage or re-runs at the current version. Can never change WHAT is deployed — that takes a PR.

### 1 · The builder asks

“My deployment looks wedged — restart it.”

### 2 · Claude calls the tool

    {
      "tool": "deployment_restart",
      "arguments": {
        "deployment_name": "hello-world",
        "dry_run": true
      }
    }

### 3 · Captured output

    {
      "deployment": "hello-world",
      "error": "AWS call failed while reading pipeline aidlc-main: TokenRetrievalError: Error when retrieving token from sso: Token has expired and refresh failed"
    }

## 🗑️ `deployment_delete` live output

Governed deletion, symmetric with creation: a deregistration PR removing the pipeline action — never an AWS delete call. The platform removes the stack after merge, per its DeletionPolicy.

### 1 · The builder asks

“I'm done with my hello-world deployment — take it down.”

### 2 · Claude calls the tool

    {
      "tool": "deployment_delete",
      "arguments": {
        "deployment_name": "hello-world",
        "dry_run": true
      }
    }

### 3 · Captured output

    {
      "dry_run": true,
      "plan": {
        "deployment": "hello-world",
        "stack": "aidlc-main-hello-world",
        "deregistration_pr": {
          "repo": "cu-aaii/ai-dlc-workshop",
          "branch": "undeploy/hello-world",
          "edits": "pipeline/pipeline.yml \u2014 remove the HelloWorldCloudFormation BlueprintDeploy action"
        },
        "warning": "The stack itself is deleted by the platform after the PR merges, per its DeletionPolicy \u2014 this tool only removes the deployment's registration.",
        "governance": "Tears down only when a human approves and merges the deregistration PR."
      }
    }

## 📄 `spec_export` live output

One deployment, six audiences: coder, narrative, security, transfer, user, offboarding.

### 1 · The builder asks

“Give me a plain-language writeup of what this system does.”

### 2 · Claude calls the tool

    {
      "tool": "spec_export",
      "arguments": {
        "deployment_name": "hello-world",
        "blueprint": "hello-world",
        "audience": "narrative"
      }
    }

### 3 · Captured output

    {
      "audience": "narrative",
      "spec_markdown": "# hello-world \u2014 narrative spec\n\nDeployment of blueprint **hello-world** v0.1.0 (supported), owned by `see stack parameters`.\n\n## What this system does, in plain language\n\nTrivial tagged stack that proves the deploy path end to end: one S3 bucket and one SSM deployment marker, carrying the full cornell:* tagging convention.\n\nIt was created by asking the Cornell Builder for it; nobody wrote cloud configuration by hand. The running system is called `hello-world` and belongs to `see stack parameters`. It was built from a governed, reusable blueprint (**hello-world**, version 0.1.0) maintained by ai-sei@cornell.edu.\n\nEvery change to it goes through a reviewed pull request \u2014 that review is the governance gate. When the platform improves the blueprint, this deployment receives the improvement as a proposed update to accept or decline.\n\nEstimated baseline cost: $0/month."
    }

Outputs captured by calling the same functions the MCP transport serves (builder-mcp/docs is generated by a script, not hand-written). Amber items show the designed no-credential fallback (NFR7): a clear narrative instead of a stack trace; on the deployed AgentCore runtime these return live AWS state.