Mudah MCP Server

Dokumentasi MCP Server

Hubungkan asisten AI ke Timemoz lewat Model Context Protocol (MCP). Ambil data proyek, task, pelacakan waktu, laporan, dan acara kalender — tanpa perlu keluar dari chat.

Streamable HTTPOAuth 2.0 / PATRead-only

Ringkasan

Mudah MCP adalah server Model Context Protocol (MCP) yang menghubungkan asisten AI ke Timemoz — platform pelacakan waktu untuk tim. Server ini menyediakan tools read-only untuk mengambil data proyek, task, entri pelacakan waktu, laporan, dan acara kalender, sehingga asisten AI dapat menampilkan insight produktivitas dan membuat laporan tanpa perlu keluar dari chat.

Transport: Streamable HTTP
Autentikasi: OAuth 2.0 (Authorization Code + PKCE) atau Personal Access Token (PAT)
Semua tools bersifat read-only — tidak ada data yang dibuat, diubah, atau dihapus

Autentikasi

Dua Cara Melakukan Autentikasi

Opsi 1 — OAuth 2.0

Direkomendasikan

Authorization Code flow dengan PKCE. Endpoint discovery metadata OAuth mengikuti RFC 8414.

Endpoint	URL
Metadata OAuth	`/.well-known/oauth-authorization-server`
Otorisasi	`/mcp-api/oauth/authorize`
Token	`/mcp-api/oauth/token`
Registrasi	`/mcp-api/oauth/register`
Pencabutan	`/mcp-api/oauth/revoke`

Setelah menyelesaikan alur OAuth, sertakan token tersebut di setiap request:

Authorization: Bearer mcp_oauth_<token>

Opsi 2 — Personal Access Token

Buat PAT dari pengaturan akun Timemoz Anda, lalu sertakan di request header. Cocok untuk script pribadi dan integrasi yang tidak memerlukan alur OAuth lengkap.

Tambahkan ini ke request header Anda:

Authorization: Bearer mcp_pat_<token>

Tips: Perlakukan PAT seperti password. Cabut (revoke) token mana pun yang Anda curigai telah bocor lewat Timemoz → Settings → Tokens.

MCP Endpoint

POST /mcp

Server menerima pesan MCP lewat HTTP POST. Semua tools mengikuti MCP Specification.

Tools

Tools yang Tersedia

Setiap tool yang disediakan oleh server Mudah MCP. Semua bersifat read-only.

get_me

Ambil informasi tentang user yang sedang login (authenticated).

Parameter: tidak ada

Hasil: Nama user, username, role, dan company.

list_projects

Tampilkan semua proyek dalam company, dengan filter opsional.

Parameter	Tipe	Wajib	Deskripsi
`search`	`string`	Tidak	Filter berdasarkan nama proyek
`status`	`active \| archived`	Tidak	Status proyek (default: active)
`clientUuid`	`string`	Tidak	Filter berdasarkan UUID client
`page`	`number`	Tidak	Nomor halaman (default: 1)
`perPage`	`number`	Tidak	Jumlah item per halaman, maks 100 (default: 20)

Hasil: Daftar proyek dengan pagination.

get_project_detail

Ambil detail lengkap satu proyek.

Parameter	Tipe	Wajib	Deskripsi
`uuid`	`string`	Ya	UUID proyek

Hasil: Budget, daftar member, jumlah task, dan info client.

get_tracking_summary

Ambil ringkasan jam yang tercatat dalam rentang tanggal tertentu, dikelompokkan berdasarkan hari, user, proyek, atau task.

Parameter	Tipe	Wajib	Deskripsi
`dateFrom`	`string`	Ya	Tanggal mulai (YYYY-MM-DD)
`dateTo`	`string`	Ya	Tanggal akhir (YYYY-MM-DD), rentang maksimal 366 hari
`projectUuid`	`string`	Tidak	Filter berdasarkan proyek
`userUuid`	`string`	Tidak	UUID user; kosongkan untuk user saat ini, isi "all" untuk seluruh tim
`groupBy`	`user \| project \| task \| day`	Tidak	Kelompokkan hasil berdasarkan (default: day)

Hasil: Total jam yang diagregasi berdasarkan dimensi pengelompokan yang dipilih.

get_recent_trackings

Ambil entri pelacakan waktu terbaru lengkap dengan detail proyek dan task.

Parameter	Tipe	Wajib	Deskripsi
`limit`	`number`	Tidak	Jumlah entri, maks 100 (default: 20)
`userUuid`	`string`	Tidak	UUID user (default: user saat ini; role MANAGER+ dapat melihat user lain)

Hasil: Entri waktu terbaru beserta konteks proyek dan task terkait.

list_tasks

Tampilkan task dari semua proyek, dengan filter opsional. Termasuk task yang tersinkron dari integrasi Jira dan ClickUp.

Parameter	Tipe	Wajib	Deskripsi
`projectUuid`	`string`	Tidak	Filter berdasarkan proyek
`assigneeUuid`	`string`	Tidak	Filter berdasarkan assignee
`status`	`string`	Tidak	Status task: open, in_progress, done, dll.
`keyword`	`string`	Tidak	Cari berdasarkan nama task
`page`	`number`	Tidak	Nomor halaman (default: 1)
`perPage`	`number`	Tidak	Jumlah item per halaman, maks 100 (default: 20)

Hasil: Daftar task dengan pagination.

get_project_report

Ambil laporan lengkap satu proyek, termasuk total jam, kontributor, penggunaan budget, dan rincian per user, task, dan hari.

Parameter	Tipe	Wajib	Deskripsi
`uuid`	`string`	Ya	UUID proyek
`dateFrom`	`string`	Tidak	Tanggal mulai (YYYY-MM-DD), default: 30 hari lalu
`dateTo`	`string`	Tidak	Tanggal akhir (YYYY-MM-DD), default: hari ini

Hasil: Laporan proyek lengkap dengan analisis waktu dan budget.

get_team_report

Ambil laporan produktivitas tim, mencakup total jam, proyek, dan rincian per anggota.

Role yang dibutuhkan: MANAGER atau di atasnya.

Parameter	Tipe	Wajib	Deskripsi
`dateFrom`	`string`	Ya	Tanggal mulai (YYYY-MM-DD)
`dateTo`	`string`	Ya	Tanggal akhir (YYYY-MM-DD)
`userUuids`	`string[]`	Tidak	Filter berdasarkan UUID user tertentu

Hasil: Metrik produktivitas seluruh tim dan rincian per anggota.

list_calendar_events

Tampilkan acara Google Calendar dalam rentang tanggal tertentu. Acara diambil dari data Google Calendar yang tersinkron.

Parameter	Tipe	Wajib	Deskripsi
`startDate`	`string`	Ya	Tanggal mulai (ISO 8601, mis. 2026-05-01T00:00:00Z)
`endDate`	`string`	Ya	Tanggal akhir (ISO 8601, mis. 2026-05-31T23:59:59Z)
`source`	`company \| personal \| all`	Tidak	Filter sumber acara (default: all)
`skip`	`number`	Tidak	Offset pagination (default: 0)
`take`	`number`	Tidak	Jumlah acara, maks 100 (default: 20)

Hasil: Acara kalender lengkap dengan judul, waktu, dan informasi sumber.

Contoh Prompt

Coba Tanyakan ke Asisten AI Anda

Setelah terhubung, Anda bisa bertanya ke asisten AI seperti:

"Berapa jam yang saya catat minggu ini?"

"Tampilkan semua proyek yang aktif."

"Buatkan laporan untuk proyek Alpha bulan lalu."

"Task apa saja yang sedang berjalan untuk proyek backend?"

"Berikan ringkasan produktivitas tim untuk Q1 2026."

"Acara company apa saja yang dijadwalkan minggu ini?"

Health Check

GET /healthz

Mengembalikan payload berikut saat server berjalan:

{ "ok": true, "service": "mudah-mcp", "timestamp": "..." }

Catatan Perilaku Tool

Bagaimana setiap tool Mudah MCP berperilaku secara default.

Read-only

Semua tools bersifat read-only (readOnlyHint: true, destructiveHint: false).

Idempotent

Memanggilnya berkali-kali akan menghasilkan hasil yang sama untuk input yang sama.

Company-scoped

Data dibatasi ke company milik user yang sedang login — akses lintas company tidak didukung.

Role-based access

get_team_report membutuhkan role MANAGER+; get_recent_trackings hanya bisa melihat data user lain pada role MANAGER+.

Siap Menghubungkan AI Anda?

Buat Personal Access Token di pengaturan Timemoz Anda, atau mulai alur OAuth, lalu arahkan asisten AI yang kompatibel dengan MCP ke endpoint kami.

Dapatkan Bantuan untuk Terhubung Kebijakan Privasi MCP