@tinyweb_dev/tracking-mcp-server 0.1.0

package/.env.example

@@ -0,0 +1,43 @@
+# Tiny Tracking MCP Server — environment configuration
+# Copy this file to `.env` (for local dev) or set these vars in your MCP client config.
+
+# --- REQUIRED ---
+
+# Base URL of the Tiny Tracking backend (no trailing slash).
+TT_API_URL=http://localhost:3000
+
+# Personal Access Token (PAT). Generated from the Tiny Tracking dashboard:
+#   1. Sign in to the dashboard
+#   2. Settings → Personal access tokens → Manage tokens
+#      (or visit /<orgId>/settings/api-tokens directly)
+#   3. Click "Create token", give it a name, choose an expiry
+#   4. Copy the `tt_pat_<32 chars>` value SHOWN ONCE (the server only stores
+#      a bcrypt hash; you cannot retrieve the plaintext later)
+#   5. Paste it here.
+#
+# Format: literal prefix `tt_pat_` followed by 32 base62-ish characters
+# (e.g. `tt_pat_aB3xY9Q2cD7eF8gH1iJ4kL5mN6oP7qR8s`).
+# Token inherits the owning user's permissions across all orgs/projects they
+# are a member of. Treat as a password: never commit, never paste in public chats.
+TT_API_KEY=tt_pat_replace_me
+
+# --- OPTIONAL ---
+
+# Default organization ID, used when a tool does not receive `org_id` explicitly.
+# Find it in the URL of your dashboard: /<orgId>/...
+TT_DEFAULT_ORG_ID=
+
+# Request timeout in milliseconds (default: 15000).
+TT_HTTP_TIMEOUT_MS=15000
+
+# Number of retry attempts on transient errors — 5xx, 429, network (default: 3).
+TT_HTTP_RETRIES=3
+
+# Logger level: trace | debug | info | warn | error | fatal (default: info).
+# Output always goes to stderr — stdout is reserved for MCP JSON-RPC.
+LOG_LEVEL=info
+
+# Client identifier sent in `X-MCP-Client` header.
+# Used by the backend audit log to attribute requests to this MCP instance.
+# Default: tiny-tracking-mcp/<pkg-version>.
+TT_MCP_CLIENT_NAME=

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to `@tinyweb_dev/tracking-mcp-server` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-05-26
+
+Initial public release.
+
+### Added
+
+- **62 MCP tools** across 8 resource groups (organizations, projects,
+  monitors, status pages, incidents, errors, recipient groups, invitations)
+  wrapping the Tiny Tracking REST API.
+- **6 read-only resource templates** for browsing org/project/monitor state
+  via `tinytracking://...` URIs.
+- **3 prompt templates** (`triage-incident`, `summarize-error-group`,
+  `weekly-health-report`) that prime the agent with canonical investigation
+  workflows.
+- **Confirmation pattern** on 10 destructive tools (`*_delete`,
+  `project_regenerate_api_key`, `invitation_revoke`, etc.) — each requires
+  an explicit `confirm_*` argument matching the resource's
+  name/slug/uuid before proceeding.
+- **`X-MCP-Client: tiny-tracking-mcp/<version>` header** on every request so
+  backend audit logs can attribute calls to the MCP server.
+- **Stdio transport** compatible with Claude Desktop, VS Code / Roo Code,
+  Cursor, ChatGPT Desktop, and any other MCP-compliant client.
+- **Pino logger pinned to stderr** with automatic redaction of
+  `authorization`, `apiKey`, `token`, `password`, `secret`, `x-api-key`
+  fields — stdout is reserved for MCP JSON-RPC.
+- **Axios HTTP client** with exponential-backoff retries on 5xx / 429 /
+  network errors and structured `McpError` mapping (401/403 →
+  `InvalidRequest`, 404/400/422 → `InvalidParams`, 5xx → `InternalError`).
+- **219 unit tests** across 17 test files; coverage 98.60% lines / 97.96%
+  branches.
+
+### Backend dependencies (required server-side, shipped in the same release)
+
+- **Personal Access Token (PAT) system**: new `POST/GET/DELETE /api/me/tokens`
+  endpoints, bcrypt cost-10 hashing, prefix-indexed lookup, soft revoke.
+- **Enhanced `JwtAuthGuard`**: now accepts both better-auth session cookies
+  AND `Authorization: Bearer tt_pat_*` tokens, hydrating the same
+  `request.user` shape for both paths.
+- **`Settings → API tokens` dashboard page**: user-facing CRUD UI for
+  generating, listing, and revoking PATs.
+- **MCP audit log**: every request carrying the `X-MCP-Client` header is
+  asynchronously recorded to the `mcp_audit_log` table (user, token,
+  org/project context, method, path, status, request/response excerpt with
+  sensitive-field redaction, IP, user-agent, duration). Owner-only read
+  endpoint `GET /api/organizations/:orgId/audit-log`.
+
+### Engineering
+
+- ESM module (`type: "module"`), TypeScript 5.7, Node ≥ 20.
+- Build is `tsc -p tsconfig.json && chmod +x dist/index.js` so the published
+  binary is directly executable.
+- `prepublishOnly` runs clean + typecheck + build + tests to guarantee no
+  broken release reaches the registry.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tinyweb dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,419 @@
+# @tinyweb_dev/tracking-mcp-server
+
+> **MCP server cho Tiny Tracking** — cho phép các AI agent (Claude Desktop, Cursor, Roo Code, VS Code, ChatGPT Desktop, custom agents…) điều khiển và quản lý toàn bộ resource của nền tảng monitoring **Tiny Tracking** thông qua REST API.
+
+Standalone Node.js package, không xâm lấn backend, deploy độc lập, dùng được cho mọi MCP client hỗ trợ stdio transport.
+
+---
+
+## Mục lục
+
+- [Tính năng](#tính-năng)
+- [Yêu cầu](#yêu-cầu)
+- [Cài đặt](#cài-đặt)
+- [Cấu hình](#cấu-hình)
+- [Tích hợp với MCP client](#tích-hợp-với-mcp-client)
+  - [Claude Desktop](#claude-desktop)
+  - [VS Code / Roo Code](#vs-code--roo-code)
+  - [Cursor](#cursor)
+- [Tool reference](#tool-reference)
+- [Resources & Prompts](#resources--prompts)
+- [Bảo mật & confirmation pattern](#bảo-mật--confirmation-pattern)
+- [Troubleshooting](#troubleshooting)
+- [Phát triển](#phát-triển)
+
+---
+
+## Tính năng
+
+- **62 tools** wrap toàn bộ REST API của Tiny Tracking backend (8 resource groups)
+- **6 resources** read-only cho agent browse nhanh workspace
+- **3 prompt templates** (triage incident, summarize error, weekly report)
+- **Stdio transport** — tương thích Claude Desktop, Cursor, Roo Code, VS Code, ChatGPT Desktop
+- **Type-safe** end-to-end với zod schemas mirror các DTO backend
+- **Auto-retry** với exponential backoff trên network errors / 5xx / 429
+- **Audit-friendly** — mỗi request gắn header `X-MCP-Client: <name>/<version>`
+- **Safe by default** — tools destructive (delete, regenerate key) bắt buộc xác nhận
+
+---
+
+## Yêu cầu
+
+- **Node.js 22+**
+- **Tiny Tracking backend** đang chạy và truy cập được (mặc định `http://localhost:3000`)
+- **Personal Access Token (PAT)** — generate từ dashboard:
+  1. Đăng nhập vào Tiny Tracking dashboard
+  2. Vào **Settings → Personal access tokens → Manage tokens** (hoặc truy cập trực tiếp `/<orgId>/settings/api-tokens`)
+  3. Bấm **Create token**, đặt tên (vd "Claude Desktop on MacBook"), chọn thời hạn → **Generate token**
+  4. **Copy ngay** giá trị `tt_pat_...` được hiển thị — backend chỉ lưu bcrypt hash, plaintext không thể recover sau khi đóng dialog
+  5. Paste vào `TT_API_KEY` trong MCP client config (xem ví dụ dưới)
+
+  Token thuộc về user, nên có quyền truy cập **toàn bộ org/project user đang là member**. Treat as password — không commit vào git, không paste vào public chat.
+
+---
+
+## Cài đặt
+
+### Từ source (recommended cho local dev)
+
+```bash
+git clone https://github.com/yourusername/tiny-tracking.git
+cd tiny-tracking/mcp-server
+npm install
+npm run build
+```
+
+Sau khi build thành công, [`dist/index.js`](dist/index.js) là entrypoint, có thể chạy thử:
+
+```bash
+TT_API_URL=http://localhost:3000 TT_API_KEY=tt_pat_xxx node dist/index.js
+```
+
+Server sẽ in một dòng JSON ra **stderr** rồi treo chờ JSON-RPC từ stdin — đó là hành vi đúng cho một MCP server stdio.
+
+---
+
+## Cấu hình
+
+Tất cả config qua biến môi trường. Xem [`.env.example`](.env.example) để có danh sách đầy đủ.
+
+| Biến | Bắt buộc | Mô tả | Mặc định |
+|---|:---:|---|---|
+| `TT_API_URL` | ✅ | Base URL của Tiny Tracking backend (không trailing slash) | — |
+| `TT_API_KEY` | ✅ | Personal Access Token format `tt_pat_<32 chars>` (generate ở Settings → API tokens) | — |
+| `TT_DEFAULT_ORG_ID` |   | Org UUID mặc định khi tool không nhận `org_id` | — |
+| `TT_HTTP_TIMEOUT_MS` |   | Timeout HTTP (ms) | `15000` |
+| `TT_HTTP_RETRIES` |   | Số lần retry với 5xx / 429 / network errors | `3` |
+| `TT_MCP_CLIENT_NAME` |   | Tên cho header `X-MCP-Client` | `mcp-server/<version>` |
+| `LOG_LEVEL` |   | `trace` \| `debug` \| `info` \| `warn` \| `error` \| `fatal` | `info` |
+
+---
+
+## Tích hợp với MCP client
+
+### Claude Desktop
+
+Edit file config tại:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "tiny-tracking": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/tiny-tracking/mcp-server/dist/index.js"
+      ],
+      "env": {
+        "TT_API_URL": "https://api.tinytracking.com",
+        "TT_API_KEY": "tt_pat_replace_me",
+        "TT_DEFAULT_ORG_ID": "org_uuid_optional",
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Mở Settings → Developer → MCP để xem trạng thái connection. Trong chat, gõ `/` để thấy 3 prompt templates (`triage-incident`, `summarize-error-group`, `weekly-health-report`).
+
+### VS Code / Roo Code
+
+Tạo `.vscode/mcp.json` trong workspace:
+
+```json
+{
+  "servers": {
+    "tiny-tracking": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${workspaceFolder}/mcp-server/dist/index.js"],
+      "env": {
+        "TT_API_URL": "http://localhost:3000",
+        "TT_API_KEY": "tt_pat_replace_me"
+      }
+    }
+  }
+}
+```
+
+> ⚠️ **Không commit** file `.vscode/mcp.json` có chứa token thật vào git. Thêm vào `.gitignore` hoặc dùng VS Code user settings.
+
+### Cursor
+
+Tạo `.cursor/mcp.json` ở root project hoặc `~/.cursor/mcp.json` cho global config:
+
+```json
+{
+  "mcpServers": {
+    "tiny-tracking": {
+      "command": "node",
+      "args": ["/absolute/path/to/tiny-tracking/mcp-server/dist/index.js"],
+      "env": {
+        "TT_API_URL": "http://localhost:3000",
+        "TT_API_KEY": "tt_pat_replace_me"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Tool reference
+
+Tổng **62 tools** chia theo 8 resource groups. Naming convention: `<resource>_<action>` (snake_case).
+
+### Organizations (8 tools)
+
+| Tool | Mô tả |
+|---|---|
+| `org_list` | List orgs mà user có quyền truy cập |
+| `org_get` | Lấy chi tiết 1 org |
+| `org_create` | Tạo org mới (user thành owner) |
+| `org_update` | Update name/slug/logo (owner only) |
+| `org_delete` | 🔴 Xóa org + toàn bộ dữ liệu (yêu cầu `confirm_slug`) |
+| `org_list_members` | List members và roles |
+| `org_update_member_role` | Đổi role (owner/member/viewer) |
+| `org_remove_member` | 🔴 Remove user khỏi org (yêu cầu `confirm_user_id`) |
+
+### Projects (12 tools)
+
+| Tool | Mô tả |
+|---|---|
+| `project_list` | List projects trong 1 org |
+| `project_create` | Tạo project mới (trả về API key) |
+| `project_get` | Lấy chi tiết project |
+| `project_update` | Update project |
+| `project_delete` | 🔴 Xóa project + monitors + errors (yêu cầu `confirm_name`) |
+| `project_get_api_key_prefix` | Lấy prefix API key (an toàn share) |
+| `project_reveal_api_key` | 🔐 Reveal full API key (admin only) |
+| `project_regenerate_api_key` | 🔴 Rotate API key — invalidate key cũ |
+| `project_list_members` | List members + roles |
+| `project_add_member` | Thêm user vào project |
+| `project_update_member_role` | Đổi role (admin/editor/viewer) |
+| `project_remove_member` | 🔴 Remove member |
+
+### Monitors (7 tools)
+
+| Tool | Mô tả |
+|---|---|
+| `monitor_list` | List monitors trong project |
+| `monitor_get` | Lấy chi tiết monitor |
+| `monitor_create` | Tạo monitor (http/keyword/ping/tcp/ssl_cert) |
+| `monitor_update` | Update monitor (partial) |
+| `monitor_delete` | 🔴 Xóa monitor (yêu cầu `confirm_name`) |
+| `monitor_toggle` | Pause / resume monitor |
+| `monitor_get_results` | Lấy check history (default 50, max 500) |
+
+### Status Pages (9 tools)
+
+| Tool | Mô tả |
+|---|---|
+| `status_page_list` | List status pages trong project |
+| `status_page_get` | Lấy chi tiết + components |
+| `status_page_create` | Tạo status page với slug public |
+| `status_page_update` | Update name/theme/logo |
+| `status_page_delete` | 🔴 Xóa status page (yêu cầu `confirm_slug`) |
+| `status_page_add_component` | Thêm component (có thể link monitors) |
+| `status_page_update_component` | Update component |
+| `status_page_delete_component` | 🔴 Xóa component |
+| `status_page_reorder_components` | Sắp xếp thứ tự component |
+
+### Incidents (6 tools)
+
+| Tool | Mô tả |
+|---|---|
+| `incident_list` | List incidents của 1 status page |
+| `incident_get` | Lấy incident + timeline updates |
+| `incident_create` | Tạo incident manual |
+| `incident_update` | Update title/status/impact/components |
+| `incident_add_update` | Thêm update vào timeline (public) |
+| `incident_resolve` | Resolve incident với optional message |
+
+### Errors (12 tools)
+
+| Tool | Mô tả |
+|---|---|
+| `error_list` | List error groups của project |
+| `error_get_project_stats` | Aggregate stats của project |
+| `error_get` | Lấy chi tiết 1 error group |
+| `error_get_summary` | Header summary (first/latest/total/IPs/users) |
+| `error_get_timeseries` | Histogram occurrences theo hour/day/2w/2mo |
+| `error_list_occurrences` | Paginated occurrences (cursor-based) |
+| `error_get_occurrence` | Chi tiết 1 occurrence (stack, tags, user) |
+| `error_get_occurrence_neighbors` | Latest/prev/next ids |
+| `error_get_affected_ips` | Top IPs |
+| `error_get_affected_users` | Top users |
+| `error_resolve` | Mark resolved (auto-reopen nếu có occurrence mới) |
+| `error_ignore` | Mark ignored (skip notifications) |
+
+### Recipient Groups (4 tools)
+
+| Tool | Mô tả |
+|---|---|
+| `recipient_group_list` | List email distribution groups |
+| `recipient_group_create` | Tạo group (name + emails) |
+| `recipient_group_update` | Update group |
+| `recipient_group_delete` | 🔴 Xóa group |
+
+### Invitations (4 tools)
+
+| Tool | Mô tả |
+|---|---|
+| `invitation_list` | List pending invitations |
+| `invitation_create` | Mời user (email + role, optional pre-assign project) |
+| `invitation_resend` | Regenerate token + re-send email |
+| `invitation_revoke` | 🔴 Cancel pending invitation |
+
+Legend:
+- 🔴 = **DESTRUCTIVE** — yêu cầu confirmation parameter
+- 🔐 = **SENSITIVE** — trả về secret, không log/share
+
+---
+
+## Resources & Prompts
+
+### Resources (read-only)
+
+Agent có thể list/fetch các URI sau qua `resources/list` và `resources/read`:
+
+| URI | Mô tả |
+|---|---|
+| `tinytracking://organizations` | Tất cả orgs user có quyền |
+| `tinytracking://organizations/{orgId}/projects` | Projects trong 1 org |
+| `tinytracking://projects/{projectId}/overview` | Project + monitors + status pages + error stats |
+| `tinytracking://projects/{projectId}/monitors` | Monitors của project |
+| `tinytracking://projects/{projectId}/errors/stats` | Error stats |
+| `tinytracking://projects/{projectId}/monitors/{monitorId}/health-summary` | Monitor + recent results (50) |
+
+### Prompts
+
+3 prompt templates dùng làm slash commands trong MCP client:
+
+| Prompt | Args | Mục đích |
+|---|---|---|
+| `triage-incident` | `incident_id` | Điều tra root cause incident |
+| `summarize-error-group` | `error_group_id`, `timeframe?` | Tóm tắt error cho dev |
+| `weekly-health-report` | `org_id?` | Báo cáo health tuần qua |
+
+---
+
+## Bảo mật & confirmation pattern
+
+### Destructive actions
+
+Các tool xóa/rotate/revoke đều yêu cầu một field xác nhận matching giá trị thật của resource:
+
+| Tool | Field xác nhận | Match với |
+|---|---|---|
+| `org_delete` | `confirm_slug` | Org slug |
+| `project_delete` | `confirm_name` | Project name |
+| `project_regenerate_api_key` | `confirm_project_id` | Project UUID |
+| `project_remove_member` | `confirm_user_id` | User UUID |
+| `monitor_delete` | `confirm_name` | Monitor name |
+| `status_page_delete` | `confirm_slug` | Status page slug |
+| `status_page_delete_component` | `confirm_component_id` | Component UUID |
+| `recipient_group_delete` | `confirm_group_id` | Group UUID |
+| `invitation_revoke` | `confirm_invitation_id` | Invitation UUID |
+| `org_remove_member` | `confirm_user_id` | User UUID |
+
+Pattern này đảm bảo agent phải explicitly "repeat back" identifier — phòng case prompt injection hoặc nhầm lẫn UUID.
+
+### Secrets
+
+- `TT_API_KEY` **không bao giờ** được hard-code vào file commit. Luôn đọc từ env hoặc MCP client config.
+- Logger tự động redact các field nhạy cảm: `authorization`, `apiKey`, `token`, `password`, `secret`.
+- `project_reveal_api_key` trả full key — đừng share log của tool call này.
+
+### Audit
+
+Mọi HTTP request đều gắn header `X-MCP-Client: tiny-tracking-mcp/<version>`. Backend có thể filter audit log theo header này để phân biệt traffic agent vs UI.
+
+---
+
+## Troubleshooting
+
+### "Configuration error: TT_API_KEY still has placeholder value"
+
+`.env` hoặc env client config vẫn chứa `tt_pat_replace_me`. Generate token thật ở dashboard → Settings → API tokens và thay vào.
+
+### "Authentication/authorization failed (401/403)"
+
+- Kiểm tra `TT_API_KEY` còn hợp lệ (chưa expire, chưa revoke). Vào dashboard → Settings → API tokens để xem trạng thái và `lastUsedAt` của từng token.
+- Verify user owner của PAT là member của org/project bạn đang thao tác — PAT thừa kế đúng permissions của user.
+- Nếu token bị nghi ngờ leak, revoke ngay ở dashboard và generate token mới — backend sẽ từ chối token cũ từ request kế tiếp.
+
+### "Not found (404)"
+
+UUID sai. Dùng resource `tinytracking://organizations` rồi đi xuống dần để chắc chắn lấy đúng id.
+
+### Agent không thấy server
+
+1. Check process Node có chạy không: `ps aux | grep tiny-tracking-mcp`
+2. Xem stderr log — Claude Desktop log tại `~/Library/Logs/Claude/mcp*.log`
+3. Verify path trong config trỏ tới `dist/index.js` đã build (`npm run build`)
+4. Đảm bảo Node 22+: `node --version`
+
+### "Origin ... not allowed by CORS"
+
+Lỗi này KHÔNG xảy ra với MCP server (gọi server-to-server, không browser). Nếu thấy, backend đang reject Bearer token — kiểm tra `TT_API_URL` đúng và token hợp lệ.
+
+### Stdout bị "ô nhiễm" — agent disconnect
+
+Chỉ xảy ra nếu có code `console.log` lẻ trong codebase. Tất cả log phải đi qua [`logger.ts`](src/logger.ts:1) (ghi stderr). Nếu thêm code mới, KHÔNG dùng `console.log`.
+
+---
+
+## Phát triển
+
+```bash
+# Watch mode — auto-restart on file change
+npm run dev
+
+# Typecheck
+npm run typecheck
+
+# Build production bundle to dist/
+npm run build
+
+# Run tests (vitest)
+npm test
+
+# Lint
+npm run lint
+```
+
+### Cấu trúc thư mục
+
+```
+mcp-server/
+├── src/
+│   ├── index.ts              # Entrypoint — boots McpServer + StdioServerTransport
+│   ├── config.ts             # Env loader + zod validation
+│   ├── http-client.ts        # Axios + auth + retry + error mapping
+│   ├── logger.ts             # Pino → stderr (NEVER stdout)
+│   ├── schemas/              # Zod schemas mirror các backend DTOs
+│   ├── tools/                # 62 MCP tools (8 resource groups)
+│   ├── resources/            # 6 read-only resource URIs
+│   └── prompts/              # 3 prompt templates
+├── test/                     # vitest specs
+├── dist/                     # Build output (gitignored)
+├── package.json
+├── tsconfig.json
+└── .env.example
+```
+
+### Thêm tool mới
+
+1. Thêm schema (nếu cần) vào `src/schemas/<resource>.ts`.
+2. Trong `src/tools/<resource>.ts`, thêm một `server.registerTool(...)` block theo pattern hiện có (dùng [`wrapHandler`](src/tools/_helpers.ts:1) + [`buildToolResult`](src/tools/_helpers.ts:1)).
+3. Nếu là destructive action, dùng [`requireConfirmation`](src/tools/_helpers.ts:1).
+4. `npm run typecheck && npm run build` để verify.
+
+---
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+declare const configSchema: z.ZodObject<{
+    TT_API_URL: z.ZodEffects<z.ZodString, string, string>;
+    TT_API_KEY: z.ZodEffects<z.ZodString, string, string>;
+    TT_DEFAULT_ORG_ID: z.ZodOptional<z.ZodString>;
+    TT_HTTP_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
+    TT_HTTP_RETRIES: z.ZodDefault<z.ZodNumber>;
+    TT_MCP_CLIENT_NAME: z.ZodOptional<z.ZodString>;
+    LOG_LEVEL: z.ZodDefault<z.ZodEnum<["trace", "debug", "info", "warn", "error", "fatal"]>>;
+}, "strip", z.ZodTypeAny, {
+    TT_API_URL: string;
+    TT_API_KEY: string;
+    TT_HTTP_TIMEOUT_MS: number;
+    TT_HTTP_RETRIES: number;
+    LOG_LEVEL: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+    TT_DEFAULT_ORG_ID?: string | undefined;
+    TT_MCP_CLIENT_NAME?: string | undefined;
+}, {
+    TT_API_URL: string;
+    TT_API_KEY: string;
+    TT_DEFAULT_ORG_ID?: string | undefined;
+    TT_HTTP_TIMEOUT_MS?: number | undefined;
+    TT_HTTP_RETRIES?: number | undefined;
+    TT_MCP_CLIENT_NAME?: string | undefined;
+    LOG_LEVEL?: "trace" | "debug" | "info" | "warn" | "error" | "fatal" | undefined;
+}>;
+export type AppConfig = z.infer<typeof configSchema> & {
+    packageName: string;
+    packageVersion: string;
+    mcpClientHeader: string;
+};
+/**
+ * Load and validate configuration from environment variables.
+ *
+ * On validation failure, prints a clear error to stderr and exits(1) — this is
+ * intentional for stdio MCP servers, because returning an invalid config would
+ * cause downstream tools to fail in confusing ways.
+ */
+export declare function loadConfig(): AppConfig;
+/** Reset cached config (used by tests). */
+export declare function _resetConfigForTests(): void;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoCxB,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;EAkBhB,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,GAAG;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAIF;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,SAAS,CA2BtC;AAED,2CAA2C;AAC3C,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/config.js

@@ -0,0 +1,85 @@
+/**
+ * Environment configuration loader with zod validation.
+ *
+ * Loads from process.env (which may have been populated via dotenv when running
+ * locally, or directly by the MCP client config in production).
+ */
+import { config as loadDotenv } from 'dotenv';
+import { z } from 'zod';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+// Load .env from package root if present (no-op when vars are already set).
+// This is a no-op in production where the MCP client sets `env` directly.
+loadDotenv();
+function readPackageJson() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        // From src/ or dist/ — package.json is one level up
+        const pkgPath = join(here, '..', 'package.json');
+        const raw = readFileSync(pkgPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return { name: '@tinyweb_dev/tracking-mcp-server', version: '0.0.0' };
+    }
+}
+const pkg = readPackageJson();
+/* ------------------------------------------------------------------ */
+/* Schema                                                              */
+/* ------------------------------------------------------------------ */
+const configSchema = z.object({
+    TT_API_URL: z
+        .string()
+        .url('TT_API_URL must be a valid URL')
+        .transform((url) => url.replace(/\/+$/, '')), // strip trailing slashes
+    TT_API_KEY: z
+        .string()
+        .min(1, 'TT_API_KEY is required')
+        .refine((v) => v !== 'tt_pat_replace_me', {
+        message: 'TT_API_KEY still has placeholder value. Set a real token.',
+    }),
+    TT_DEFAULT_ORG_ID: z.string().min(1).optional(),
+    TT_HTTP_TIMEOUT_MS: z.coerce.number().int().positive().default(15000),
+    TT_HTTP_RETRIES: z.coerce.number().int().min(0).max(10).default(3),
+    TT_MCP_CLIENT_NAME: z.string().min(1).optional(),
+    LOG_LEVEL: z
+        .enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal'])
+        .default('info'),
+});
+let cached = null;
+/**
+ * Load and validate configuration from environment variables.
+ *
+ * On validation failure, prints a clear error to stderr and exits(1) — this is
+ * intentional for stdio MCP servers, because returning an invalid config would
+ * cause downstream tools to fail in confusing ways.
+ */
+export function loadConfig() {
+    if (cached)
+        return cached;
+    const parsed = configSchema.safeParse(process.env);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `  • ${i.path.join('.') || '<root>'}: ${i.message}`)
+            .join('\n');
+        // eslint-disable-next-line no-console
+        console.error(`\n[tiny-tracking-mcp] Configuration error:\n${issues}\n\n` +
+            `Required env vars: TT_API_URL, TT_API_KEY\n` +
+            `See .env.example for full list.\n`);
+        process.exit(1);
+    }
+    const clientHeader = parsed.data.TT_MCP_CLIENT_NAME ?? `${pkg.name.split('/').pop()}/${pkg.version}`;
+    cached = {
+        ...parsed.data,
+        packageName: pkg.name,
+        packageVersion: pkg.version,
+        mcpClientHeader: clientHeader,
+    };
+    return cached;
+}
+/** Reset cached config (used by tests). */
+export function _resetConfigForTests() {
+    cached = null;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}