# agent-mcp-tools-1

A production-leaning MCP server starter for AWS Lambda. It follows the shape of
[`aal80/peppa-mcp-server-on-lambda`](https://github.com/aal80/peppa-mcp-server-on-lambda)
but uses maintained, widely adopted building blocks:

- Official Model Context Protocol TypeScript SDK (`@modelcontextprotocol/sdk`)
- Streamable HTTP transport, the current MCP remote-server transport
- Express 5 for local HTTP routing
- Zod for tool input validation
- AWS Lambda Web Adapter for running the same HTTP app locally, in Docker, or on Lambda
- Terraform for AWS Lambda + API Gateway HTTP API infrastructure
- Vitest, TypeScript, ESLint, and Prettier for day-to-day engineering hygiene

The sample MCP surface mirrors the Peppa-style flow:

- Resource: `tickets://timeslots`
- Tool: `order_tickets`

## Local Development

```bash
npm install
npm run dev
```

In another terminal:

```bash
npm run client
```

Or inspect it with the MCP Inspector:

```bash
npm run inspect
```

## Stdio Mode

Some local MCP clients prefer stdio:

```bash
npm run stdio
```

## Verify

```bash
npm run typecheck
npm test
npm run lint
npm run build
```

## Docker

```bash
docker build -t agent-mcp-tools-1:local .
docker run --rm -p 8080:8080 \
  -e HOST=0.0.0.0 \
  -e MCP_ALLOWED_ORIGINS=http://127.0.0.1:6274,http://localhost:6274 \
  agent-mcp-tools-1:local
```

## AWS Deploy

Build and push the container image to ECR, then pass the ECR image URI to
Terraform:

```bash
cd terraform
terraform init
terraform apply -var "image_uri=<account>.dkr.ecr.<region>.amazonaws.com/agent-mcp-tools-1:latest"
```

Terraform outputs `endpoint_url`, which is the MCP Streamable HTTP endpoint.

## Security Notes

MCP's Streamable HTTP specification calls out origin validation, localhost-only
binding for local servers, and authentication for remote deployments. This starter
implements origin validation and localhost binding by default. Add your preferred
auth layer before exposing a real production tool publicly.

## Replacing The Sample Tool

Keep the transport and deployment code as-is, then replace:

- `src/domain/tickets.ts`
- the resource/tool registrations in `src/mcp/server.ts`
- the smoke client arguments in `src/client.ts`