@tinyweb_dev/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
• Yêu cầu
• Cài đặt
• Cấu hình
• Tích hợp với MCP client
  • Claude Desktop
  • VS Code / Roo Code
  • Cursor
• Tool reference
• Resources & Prompts
• Bảo mật & confirmation pattern
• Troubleshooting
• 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)

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 là entrypoint, có thể chạy thử:

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 để 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

{
  "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:

{
  "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:

{
  "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 (ghi stderr). Nếu thêm code mới, KHÔNG dùng console.log.

Phát triển

# 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 + buildToolResult).
3. Nếu là destructive action, dùng requireConfirmation.
4. npm run typecheck && npm run build để verify.

License

MIT