edgeex-mcp-start

EdgeEx MCP — Local Setup & Start

This skill ships two helper scripts under scripts/ that automate the day-to-day flow. Prefer them over running the raw commands by hand.

• scripts/start-mcp.sh — pulls, builds, and starts the server
• scripts/refresh-creds.sh — prompts for bearer tokens (no disk I/O) and injects AWS session creds for any/all envs

refresh-creds.sh uses aws sso login + aws configure export-credentials for a single chosen profile. It deliberately does NOT call aws sso logout, which would wipe every cached SSO token in ~/.aws/sso/cache/ and break other in-flight sessions (e.g. a Bedrock-backed Claude Code running alongside).

Path resolution

Before running the scripts, confirm where this user keeps the MCP repo. If the user hasn't told you, probe for it:

for d in ~/git/edgeex-mcp-internal ~/work/edgeex-mcp-internal \
         ~/work/ai-workspace/edgeex-mcp-internal ~/code/edgeex-mcp-internal \
         ~/src/edgeex-mcp-internal ~/Projects/edgeex-mcp-internal; do
  [ -d "$d/.git" ] && echo "MCP: $d"
done

If a match is found, start-mcp.sh will pick it automatically. Otherwise, pass --dir (or set EDGEEX_MCP_DIR). If nothing resolves, fall through to the first-time clone below.

Step 1 — First-time setup (if the repos are missing)

Clone the MCP repo to the user's preferred directory (ask if you don't know). Example using ~/git:

git clone git@github.com:edgenuity/edgeex-mcp-internal.git ~/git/edgeex-mcp-internal
cd ~/git/edgeex-mcp-internal && npm install

One-time AWS profile setup (only needed if ~/.aws/config doesn't already have OTK-Courseware-Nonprod / OTK-Courseware-Production):

git clone git@github.com:ImagineLearning/otk-util.git ~/git/otk-util
cd ~/git/otk-util/connect/setup_aws_config && bash ./build_aws_config.sh

Step 2 — Start the server

Run the start script. It will pull, install, build, and launch the server, and is a no-op if the server is already running.

"$CLAUDE_PLUGIN_ROOT/skills/edgeex-mcp-start/scripts/start-mcp.sh"

Override the repo location if needed:

EDGEEX_MCP_DIR=~/custom/path/edgeex-mcp-internal \
  "$CLAUDE_PLUGIN_ROOT/skills/edgeex-mcp-start/scripts/start-mcp.sh"
# or
"$CLAUDE_PLUGIN_ROOT/skills/edgeex-mcp-start/scripts/start-mcp.sh" --dir ~/custom/path/edgeex-mcp-internal

The server listens on http://127.0.0.1:8808, serving all four envs at /<env>/mcp. Leave this terminal running. The server does not need to restart when tokens expire.

Because start-mcp.sh runs the server in the foreground, kick it off in a separate terminal or background process — don't block your current session. From within a Claude Code session, consider using a tmux split, run_in_background, or asking the user to run it themselves.

First-time launch must be in a real terminal. On a fresh clone with no .env.local, the server prompts interactively for PII_HASH_SALT (press Enter to auto-generate) and offers to save it to .env.local (gitignored, lives on your machine only). Background/non-TTY launches skip the prompt and the server will fail to start with PII_HASH_SALT must be at least 32 characters. Once .env.local exists, subsequent launches can run non-interactively (e.g. via run_in_background).

Step 3 — Inject tokens and AWS credentials

Run the refresh script. It will:

1. Verify the server is reachable
2. Prompt you to pick an AWS profile (or pass --profile/AWS_SSO_PROFILE)
   • OTK-Courseware-Nonprod for dev, qa, staging
   • OTK-Courseware-Production for prod
3. Run aws sso login for that profile only (no global logout)
4. Export creds into the script's shell via aws configure export-credentials --format env
5. Loop dev→qa→staging→prod, prompting silently (read -rs) for each bearer token. Leave a prompt blank to skip that env's token.
6. PUT the creds to each env
7. Print /healthz so you can confirm which envs are configured: true

"$CLAUDE_PLUGIN_ROOT/skills/edgeex-mcp-start/scripts/refresh-creds.sh"

Only refresh specific envs:

"$CLAUDE_PLUGIN_ROOT/skills/edgeex-mcp-start/scripts/refresh-creds.sh" dev qa

Pick the profile non-interactively:

AWS_SSO_PROFILE=OTK-Courseware-Nonprod \
  "$CLAUDE_PLUGIN_ROOT/skills/edgeex-mcp-start/scripts/refresh-creds.sh"
# or
"$CLAUDE_PLUGIN_ROOT/skills/edgeex-mcp-start/scripts/refresh-creds.sh" \
  --profile OTK-Courseware-Nonprod

The script never writes tokens to disk. Each TOKEN variable is unset immediately after its single curl call, and AWS creds stay only in the current shell + the running server's memory.

Unlike sourcing otk-util's login_aws.sh, this script does NOT call aws sso logout, so it won't clobber other active SSO sessions (e.g. the claude-code profile Bedrock uses to power Claude Code itself).

Troubleshooting

• configured: false after injection — the PUT didn't hit the right env path. Re-run the script and watch for FAILED lines.
• DynamoDB-backed tools (customization, supplemental history) fail with auth errors — AWS session likely expired (typical lifetime 1–8 hours). Re-run refresh-creds.sh.
• Bearer token rejected — ask the Courseware team for a fresh standard heritage user/app token. Pass blank for envs you don't want to update.
• aws configure export-credentials fails — requires AWS CLI v2. Upgrade with brew upgrade awscli (or equivalent).
• MCP repo not found — set EDGEEX_MCP_DIR=<path> or pass --dir.
• Server fails with PII_HASH_SALT must be at least 32 characters — first-time launch was non-interactive (e.g. via run_in_background), so the salt prompt was skipped. Run start-mcp.sh once in a real terminal and press Enter at the salt prompt to auto-generate, then save to .env.local.

Manual fallback (if the scripts can't be used)

If for some reason you need to do this by hand, the underlying calls are:

# Start:
cd <edgeex-mcp-internal> && git pull && npm install && npm run build && npm run start:dist

# Inject bearer token:
curl -X PUT http://127.0.0.1:8808/<env>/token \
  -H "Content-Type: application/json" \
  -d '{"token":"..."}'

# Inject AWS creds (requires AWS_* in current shell):
curl -X PUT http://127.0.0.1:8808/<env>/aws-credentials \
  -H "Content-Type: application/json" \
  -d "{\"accessKeyId\":\"$AWS_ACCESS_KEY_ID\",\"secretAccessKey\":\"$AWS_SECRET_ACCESS_KEY\",\"sessionToken\":\"$AWS_SESSION_TOKEN\"}"

# Verify:
curl -s http://127.0.0.1:8808/healthz