[English](README.md) · [한국어](README.ko.md)

# missed-deadline-mcp (놓치면 손해 MCP)

A Korean-language, loss-prevention **MCP server**. Paste in the text you already
have — a reservation notice, a coupon, a bill, an A/S warranty, or text copied
from a screenshot/PDF — and it finds the **deadlines that cost you money or
opportunity if missed**, ranks them by risk, and turns each into something you
can actually do today.

It never crawls your accounts, never sends or cancels anything, and never
invents a date it isn't sure about. Every extracted item comes back with a short
source excerpt, a confidence score, and a "needs confirmation" flag when the
text is ambiguous.

![Representative image](docs/assets/playmcp-representative.png)

## Quick start

Requires [Bun](https://bun.sh).

```bash
bun install
bun run start
```

The server listens on `http://localhost:3000` by default (override with `PORT`).
It exposes two endpoints:

- `POST /mcp` — the MCP endpoint (streamable HTTP transport)
- `GET /health` — liveness check, returns `{ "status": "ok", ... }`

For hot-reload during development:

```bash
bun run dev
```

## Tools

The server registers five MCP tools:

| Tool | What it does |
|---|---|
| `extract_loss_deadlines` | Extracts loss-bearing deadline items (refund, cancellation, payment, coupon, warranty, application…) from Korean text, a public URL, or fallback text copied from a screenshot/PDF. |
| `rank_loss_risk` | Sorts extracted items by deadline urgency, amount at stake, reversibility, and confidence. |
| `make_action_plan` | Drafts the first check / cancel / inquire / apply steps as safe guidance the user runs themselves. |
| `create_reminder_payload` | Produces a copy-pasteable reminder draft — no real calendar write. |
| `daily_loss_digest` | Bundles today's loss-risk items into a short Korean summary. |

### Example: `extract_loss_deadlines`

Input shapes are validated with [Zod](https://zod.dev). The most common call
passes Korean text directly:

```json
{
  "sourceType": "text",
  "sourceText": "주문 취소는 6월 25일까지 가능하며, 이후에는 환불 수수료 10%가 부과됩니다.",
  "requestDate": "2026-06-19"
}
```

Other `sourceType` values: `public_url` (requires `sourceUrl`), and
`screenshot` / `pdf` (require `fallbackText` — the server processes copied text,
not raw binary files).

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `PORT` | `3000` | HTTP port the server binds to. |

Copy `.env.example` to `.env` and adjust as needed (`.env` is gitignored).
The port can also be passed as `--port <n>` on the command line.

## Development

```bash
bun run lint        # biome check
bun run typecheck   # tsc --noEmit
bun test            # run the test suite
bun run build       # bundle to dist/
```

## Project structure

```
src/
  index.ts          # entry: starts the Bun HTTP server
  server/           # Hono app, /health, port config
  mcp/              # MCP server + tool schemas
  tools/            # the five tool implementations
  domain/           # contracts, Korean parsers, redaction, safe errors
  ingest/           # public URL + text fallback ingestion, URL safety
  storage/          # in-memory loss-deadline store
tests/              # unit + contract + endpoint tests (bun test)
docs/               # deployment, privacy, registration, smoke notes
deploy/             # Kakao Cloud manifest
Dockerfile          # oven/bun runtime image
```

## Deploy

A `Dockerfile` (based on `oven/bun`) builds a runtime image that serves the same
`/mcp` and `/health` endpoints. See [docs/deployment.md](docs/deployment.md) for
the Kakao Cloud / PlayMCP registration path.

## Privacy & scope

This is a preliminary hackathon MVP (PlayMCP). By design it:

- processes **only user-supplied** text, copied fallback text, or public URLs;
- does **not** crawl accounts, mailboxes, or SMS, and uses no private APIs;
- does **not** auto-pay, cancel, refund, apply, message, or write to a calendar;
- does **not** durably store raw input — masks phone/card/account-like strings in
  logs and errors.

It is not legal, medical, tax, or financial advice. See
[docs/privacy.md](docs/privacy.md) for details.

## License

[License — not yet specified]