mcp-project-creator

# MCP Server Creator Creates a new MCP server using FastMCP 3.0, Docker, and AWS Lambda. > See [CLAUDE.md](../../../CLAUDE.md) at the repo root for project context. ## Workflow 0. **Check one-time setup** — confirm the shared infra exists (see below). Skip if a server already deploys successfully. 1. **Gather info** — server name (kebab-case) 2. **Create package** — `packages/{name}/` from [references/mcp-server.md](references/mcp-server.md) 3. **Register CDK stack** — add to `infrastructure/bin/infrastructure.ts` per [references/infrastructure.md](references/infrastructure.md) 4. **Wire env vars (only if the server needs them)** — add to `.github/workflows/deploy.yml` per [references/shared-env-vars.md](references/shared-env-vars.md) 5. **Verify** — walk the completion checklist below ## Step 0: One-Time Setup (first server in a fresh clone) The per-server steps below assume shared scaffolding already exists. On the **first** server in a freshly cloned/templated repo, verify (and create if missing): - [ ] **Shared CDK constructs** in `infrastructure/lib/`: `shared-stack.ts`, `mcp-docker-construct.ts`, `mcp-docker-stack.ts`. The skill and the deploy workflow reference these by name but they are easy to miss in a fresh clone. If `cd infrastructure && npx cdk synth` fails with "Cannot find module", recreate them from [references/cdk-constructs.md](references/cdk-constructs.md). - [ ] **`bin/infrastructure.ts`** wires up `SharedStack` (`McpShared-{stage}`) — not the default `InfrastructureStack` scaffold. See [references/infrastructure.md](references/infrastructure.md). - [ ] **Root `package-lock.json`** exists and is committed. The CI/deploy workflows run `npm ci` at the repo root and use `actions/setup-node` with `cache: npm`; both fail immediately without a root lockfile. Generate with `npm install --package-lock-only` at the repo root. - [ ] **AWS OIDC role + `AWS_DEPLOY_ROLE_ARN` secret** are configured **for the account you actually deploy to**. See [references/config-files.md](references/config-files.md). This is the most common first-deploy failure. A quick local sanity check before relying on CI: `npm ci && npm run build --workspace=infrastructure && (cd infrastructure && npx cdk synth)`. ## Completion Checklist Confirm each item before declaring the task done: - [ ] **First server only:** Step 0 one-time setup verified (shared constructs, root lockfile, OIDC role + secret) - [ ] `packages/{name}/` created with `app.py`, `pyproject.toml`, `.python-version`, `uv.lock`, `Dockerfile`, `.env`, `README.md` - [ ] `infrastructure/bin/infrastructure.ts` updated with a new `McpDockerStack` (including the `imageTag` prop) - [ ] If the server needs env vars: those vars are passed to the "Deploy server stack" step in `.github/workflows/deploy.yml` - [ ] If the server needs Secrets Manager: IAM policy granting `secretsmanager:GetSecretValue` added to the stack - [ ] If the server reuses an existing shared variable (declared in `infrastructure.ts`): referenced the existing constant rather than re-declaring it --- ## Step 1: Gather Info Ask for the MCP server name in kebab-case (e.g., `weather`, `pdf-tools`, `github-issues`). Validate: - Lowercase + hyphens only - Does not conflict with an existing `packages/{name}/` - Does not start with `_` (reserved for shared internal packages) ## Step 2: Create the Package ```bash mkdir -p packages/{name} ``` Create from [references/mcp-server.md](references/mcp-server.md): - `app.py` — FastMCP 3.0 server with `create_mcp_server()`, `lambda_handler()`, and a local `__main__` entry. Calls `load_dotenv()` so `.env` values are picked up automatically when running locally. - `pyproject.toml` — Project metadata + dependencies (`fastmcp>=3.0`, `mangum`, `uvicorn`, `python-dotenv`, plus any server deps). `[tool.uv] package = false` marks it as an app. - `.python-version` — Pins to `3.12` so uv auto-uses (and auto-installs) the right interpreter. - `uv.lock` — Generated by `uv lock` (or first `uv sync`); commit it for reproducible builds. - `Dockerfile` — Multi-stage Lambda container that uses uv to install deps into `${LAMBDA_TASK_ROOT}`. - `.env` — Placeholder values for local dev (gitignored repo-wide). Create from [references/readme-template.md](references/readme-template.md): - `README.md` — features, tools table, use cases, quick start **Why include use cases in the README?** They help AI assistants understand when to use each tool, document expected behavior for ambiguous queries, and double as integration test scenarios. ## Step 3: Register with CDK Edit `infrastructure/bin/infrastructure.ts`: ```typescript new McpDockerStack(app, `McpServer-{name}-${stage}`, { env, stage, serverName: '{name}', imageTag, sharedResources: sharedStack.sharedResources, environment: { // Lambda env vars (only if the server needs them) }, }); ``` The `imageTag` constant (defined at the top of `infrastructure.ts`) reads `process.env.IMAGE_TAG` — the deploy workflow sets it to the git SHA so CloudFormation always replaces the Lambda image. **Always pass `imageTag`.** For env vars, IAM permissions, and custom stacks, see [references/infrastructure.md](references/infrastructure.md). ## Step 4: Wire Env Vars (only if needed) If the server reads no environment variables, skip this step. The deploy workflow's "Deploy server stack" step runs `cdk deploy`. Any `process.env.X` your CDK code reads must be in its `env:` block: ```yaml - name: Deploy server stack env: STAGE: ${{ inputs.environment || 'dev' }} IMAGE_TAG: ${{ github.sha }} # {name} env vars: {NAME}_API_BASE_URL: ${{ vars.{NAME}_API_BASE_URL }} {NAME}_API_KEY: ${{ secrets.{NAME}_API_KEY }} ``` - Prefix server-specific vars with `{NAME}_` (uppercase, underscores) — prevents collisions as the repo grows - Use `vars.` for non-sensitive values, `secrets.` for sensitive ones - The GitHub variable/secret must be created in the repo settings *before* the first deploy - If reusing a shared variable already wired up in the workflow, do not re-declare it. See [references/shared-env-vars.md](references/shared-env-vars.md). > **Note:** The deploy workflow auto-detects changed packages — you do **not** need to update a `workflow_dispatch.options` dropdown. ## Step 5: Run Locally (optional) Local dev runs directly via uv — no Docker required. `app.py` calls `load_dotenv()` on startup, so any values in `packages/{name}/.env` are picked up automatically. ```bash cd packages/{name} # Fill in .env with real values for local testing uv sync # installs deps from uv.lock (creates .venv, downloads Python 3.12 if needed) PORT=8000 uv run python app.py # uv run auto-activates the project's .venv # Server: http://localhost:8000 # MCP endpoint: POST http://localhost:8000/mcp ``` **Prerequisite:** [uv installed](https://docs.astral.sh/uv/getting-started/installation/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`). uv handles the Python 3.12 install for you via `.python-version`, so contributors do not need to install python3.12 separately. **Adding a dependency:** `cd packages/{name} && uv add <package>` — this updates both `pyproject.toml` and `uv.lock` atomically. Commit both files. **Note:** The `.env` file is gitignored repo-wide (via the root `.gitignore`'s `.env` entry). Never commit it. ## Step 6: Deploy Push to `main`. GitHub Actions: 1. Detects the new package in `packages/{name}/` 2. Creates the ECR repository if missing 3. Builds and pushes the Docker image (tagged with the git SHA) 4. Deploys `McpServer-{name}-{stage}` via CDK The first deploy creates the ECR repo and Lambda together. Subsequent deploys swap the image based on `IMAGE_TAG`. **Gotchas:** - The workflow's `paths:` filter only watches `packages/**`, `infrastructure/**`, and `deploy.yml`. Changes confined to the **repo root** (e.g. a new root `package-lock.json`) do **not** auto-trigger it — use `gh workflow run deploy.yml -f server=all -f environment=dev` to dispatch manually. - The Lambda is fronted by an **IAM-auth Function URL**, so a plain `curl` returns 403. To verify the live endpoint, SigV4-sign a `POST {FunctionUrl}mcp` request — see [references/cdk-constructs.md](references/cdk-constructs.md#testing-the-live-endpoint). The stack outputs `FunctionUrl` and `FunctionName`. --- ## Configuration Defaults The `McpDockerConstruct` sets: | Setting | Default | Override via | |---------|---------|-------------| | Runtime | Python 3.12 (Lambda container) | Dockerfile base image | | Architecture | X86_64 | construct prop | | Memory | 512 MB | `memorySize` prop | | Timeout | 30 s | `timeout` prop | | Auth | AWS_IAM | construct prop | | Log retention | 14 days | construct prop | ## Environment Variables: Naming Server-specific vars: `{SERVER_NAME}_{VAR}` (uppercase, underscores). Examples for `weather`: - `WEATHER_API_BASE_URL` - `WEATHER_API_KEY` Shared vars (e.g., a common auth provider used by every server) are declared once at the top of `infrastructure.ts` and reused — they don't carry a server prefix. See [references/shared-env-vars.md](references/shared-env-vars.md). ## References - [references/mcp-server.md](references/mcp-server.md) — FastMCP 3.0 server templates (app.py, Dockerfile, etc.) - [references/cdk-constructs.md](references/cdk-constructs.md) — Source for the shared CDK constructs (`SharedStack`, `McpDockerStack`, `McpDockerConstruct`) + live-endpoint test - [references/infrastructure.md](references/infrastructure.md) — CDK integration, IAM helpers, custom stacks - [references/shared-env-vars.md](references/shared-env-vars.md) — Shared-variable patterns + AWS Secrets Manager - [references/readme-template.md](references/readme-template.md) — Per-server README template - [references/config-files.md](references/config-files.md) — Repo-root config (IAM trust policy, OIDC setup)