mcp-hello

Hello world MCP server, structured just like mcp: McpServer from the official SDK, stdio/HTTP transports, and AWS Lambda deploy via the Serverless Framework. Also includes an invoices ("facturas") feature backed by DynamoDB, exposed both as MCP tools and as a REST API.

Install

npm install
npm run build

Local (stdio)

• npm run mcp — starts the server over stdio (tsx src/server.ts)

To connect it to Claude Code / Cursor, point the MCP client at the npx tsx src/server.ts command (or the compiled binary in dist/server.js after npm run build).

Local (HTTP)

npm run mcp:http

• MCP: http://localhost:8787/mcp
• Health: http://localhost:8787/health
• Invoices REST API: http://localhost:8787/invoices

Requires AWS credentials with access to the InvoicesTable DynamoDB table (see Invoices below). Set INVOICES_TABLE_NAME (and optionally AWS_REGION / DYNAMODB_ENDPOINT for DynamoDB Local) in your .env.

Deploy (AWS Lambda)

npm run deploy -- --stage dev
npm run deploy:remove -- --stage dev

The deploy uses serverless-esbuild to bundle lambdas/handler.ts and exposes the MCP server through API Gateway (HTTP API). Once it finishes, serverless deploy prints the public URL (https://<id>.execute-api.<region>.amazonaws.com/mcp); add serverless-domain-manager and your own DNS config if you want a custom domain.

Scripts

Script	Description
npm run mcp	MCP over stdio (local)
npm run mcp:http	MCP over HTTP (local)
npm run build	Compiles src/ to dist/
npm run ts:check	Type-checks without emitting
npm run deploy	Lambda + API Gateway
npm run deploy:remove	Removes the deployed stack

Tools

• say_hello({ name? }) → returns Hello, <name>! (or Hello, world! if no name is given).
• save_invoice({ invoiceNumber?, date, provider, concept, currency, amount, status?, items? }) → creates an invoice in DynamoDB.
• get_invoice({ id }) → fetches a single invoice by id.
• list_invoices({ from?, to?, limit?, cursor? }) → lists invoices sorted by date (newest first), optionally filtered by date range (YYYY-MM-DD).

Invoices

Invoices are stored in a DynamoDB table (InvoicesTable, provisioned in serverless.yml) with id as the primary key and a byDate global secondary index for date-range queries.

Fields: id, invoiceNumber?, date (ISO YYYY-MM-DD), provider, concept, currency (default USD), amount, status (pending | paid, default pending), items? ({ description, quantity, unitPrice }[]), createdAt, updatedAt.

REST API

Method & path	Description
POST /invoices	Create an invoice. Body matches the invoice fields above (minus id/createdAt/updatedAt).
GET /invoices	List invoices. Query params: from, to (ISO dates), limit (default 20, max 100), cursor (pagination token from a previous response).
GET /invoices/:id	Fetch a single invoice, 404 if not found.

No authentication yet — add it before exposing this outside a trusted network.

Architecture

MCP client → src/server.ts (stdio) | src/index.ts / lambdas/handler.ts (HTTP) → src/register-server.ts → tools/
REST client → src/app.ts (Express) → src/routes/ → src/repositories/ → DynamoDB

File	Role
src/register-server.ts	Factory that creates the McpServer and registers the tools
src/server.ts	Stdio entrypoint (Cursor/Claude Code, local)
src/app.ts	Express app with the Streamable HTTP transport (/mcp, /health, /invoices)
src/index.ts	Local HTTP entrypoint (npm run mcp:http)
lambdas/handler.ts	@codegenie/serverless-express wrapper for AWS Lambda
src/tools/	One register*Tool function per MCP tool
src/routes/	Express routers for the REST API
src/repositories/	DynamoDB data access (shared by MCP tools and REST routes)
src/models/	Zod schemas / types for domain entities
src/db/dynamo-client.ts	Shared DynamoDBDocumentClient + table/index names