# tsforge-mcp

Zero-dependency MCP server exposing **15 timestamp tools that LLMs compute unreliably** — cron edge cases, the Excel 1900 leap-year bug, ISO-8601 duration arithmetic, multi-dialect SQL timestamp generation, business-day counting, and batch conversion.

One codebase, **two transports**:
- `stdio` — Claude Desktop / local agents (MCP native)
- `http` — ChatGPT Apps SDK / any remote MCP client (Streamable HTTP)

No npm dependencies. No network calls. Pure Node.js built-ins.

## Why this exists

The official `mcp-server-time` ships only two tools (`get_current_time`, `convert_time`) — things an LLM can already do. The moat is everything an LLM gets *wrong* at the boundaries:
leap-day cron (`29 Feb`), the Excel 1900 leap-year bug (serial 60 → a non-existent date), ISO week rollovers, DST/timezone offsets, multi-dialect SQL, and holiday-aware business days.

`sql_timestamp` in particular targets a **blue ocean**: Google's AI Overview still only surfaces syntax docs (MS Learn / W3Schools / StackExchange) — no clean dedicated converter ranks for it yet.

## Try it online

If you prefer a web UI, the same engine powers [GotTimestamp.com](https://gotimestamp.com/sql-timestamp-converter.html) — the dedicated SQL timestamp converter page built for this niche.

## Install

```bash
npm install -g tsforge-mcp
# or run directly
node server.mjs --transport stdio
```

## Use with Claude Desktop (stdio)

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tsforge": {
      "command": "node",
      "args": ["/absolute/path/to/tsforge-mcp/server.mjs", "--transport", "stdio"]
    }
  }
}
```

## Use with ChatGPT Apps SDK (remote HTTP)

1. Deploy the HTTP server (any host that keeps a long-lived Node process, e.g. a container / VM):
   ```bash
   node server.mjs --transport http --port 3000
   ```
2. Expose it at a public HTTPS URL (reverse proxy / tunnel).
3. Submit the MCP server via the ChatGPT Apps SDK submission portal. Because the Apps SDK is built on MCP, the same server is callable from both ChatGPT and the Claude/MCP ecosystem.

## Tools

### P0 — moat (LLM boundary errors)
| tool | what it does |
|------|--------------|
| `cron_next` | next N fire times of a 5-field cron, including `29 Feb` |
| `cron_describe` | human-readable cron description |
| `excel_serial` | Excel serial ↔ date, handles the 1900 leap-year bug |
| `iso_duration` | add `PnYnMnDTnHnMnS` to a date (variable months/years) |
| `sql_timestamp` | correct SQL for epoch↔datetime across MySQL / Postgres / SQLite / SQL Server |
| `business_days` | weekdays between dates minus an optional holiday list |
| `batch_convert` | convert an array of epochs/dates in one call (enterprise batch) |

### P1 — general
`convert_timestamp` (s/ms/us/ns) · `timezone_convert` · `week_number` (ISO) · `relative_time` · `date_difference` · `add_subtract` · `age_calculator` · `timestamp_generate` · `date_info`

## Test

```bash
node test_lib.mjs     # boundary correctness (Excel bug, cron leap-day, ISO week…)
node test.mjs        # MCP stdio handshake
node test_http.mjs   # MCP Streamable HTTP handshake + tool calls
```