MCP Server

PaceCraft menyediakan MCP server (Model Context Protocol) supaya asisten AI — Claude Desktop, Cursor, dan client MCP lain — bisa membaca data project kamu: daftar space, cari task, baca doc, lihat aktivitas tim.

Server ini membaca semua, menulis dokumen saja: asisten bisa melihat space, task, doc, dan aktivitas tim, lalu membuat atau menyunting dokumen. Task, status, komentar, dan custom field tidak bisa diubah lewat MCP. Daftar lengkapnya di bagian 4.

Transport: HTTP (Streamable HTTP, JSON-RPC 2.0). Auth: Personal Access Token (Bearer). Scope: satu koneksi = satu workspace.

⚠️ Token ini bisa menulis dokumen di semua workspace kamu. Aksesnya memang dibatasi ke dokumen, tapi tetap tulis — dan token tidak bisa dipersempit ke satu workspace saja. Perlakukan seperti password: jangan tempel di repo, jangan berikan ke layanan pihak ketiga, cabut kalau sudah tidak dipakai.

1. Buat Personal Access Token

1. Buka Settings (ikon di dashboard) → bagian Personal Access Tokens.
2. Klik Generate Token, beri nama (mis. Claude Desktop).
3. Salin token sekarang — formatnya pc_xxxx…. Token cuma ditampilkan sekali; setelah dialog ditutup, tidak bisa dilihat lagi (yang disimpan server cuma hash-nya). Kalau hilang, cabut dan buat baru.

Satu token mewakili akun kamu dan bisa mengakses semua workspace yang kamu punya. Cabut kapan saja lewat tombol hapus di Settings — client yang memakainya langsung kehilangan akses.

2. Endpoint

Endpoint hanya menerima POST. GET dan DELETE sengaja dibalas 405 — server ini stateless dan tidak membuka aliran SSE, jadi tidak ada session id yang perlu dipegang client.

Client yang didukung

Auth memakai Bearer token statis, bukan OAuth. Artinya:

• ✅ Cursor dan client lain yang bisa mengirim header khusus — konek langsung.
• ✅ Claude Desktop lewat jembatan mcp-remote (lihat bawah).
• ❌ Custom connector remote bawaan Claude.ai / Claude Desktop — alur itu menuntut discovery OAuth (/.well-known/oauth-protected-resource), yang belum disediakan server ini. Pakai mcp-remote sebagai gantinya.

Memilih workspace

Karena satu token mengakses banyak workspace, tapi tiap koneksi MCP terikat ke satu workspace, tentukan workspace lewat query di URL:

https://pacecraft.duckdns.org/api/mcp?workspace=NamaWorkspace

• ?workspace= menerima nama workspace (mis. ?workspace=alfagift) atau id-nya.
• Kalau akunmu cuma punya satu workspace, ?workspace= boleh dilewat — otomatis dipilih.
• Kalau punya lebih dari satu dan tidak menyebut ?workspace=, tool call akan membalas pesan yang menyebutkan pilihan workspace yang ada.

3. Setup client

Cursor

Edit ~/.cursor/mcp.json (atau Settings → MCP → Add new):

{
  "mcpServers": {
    "pacecraft": {
      "url": "https://pacecraft.duckdns.org/api/mcp?workspace=NamaWorkspace",
      "headers": {
        "Authorization": "Bearer pc_TOKEN_KAMU"
      }
    }
  }
}

Untuk dev lokal, ganti URL-nya jadi http://localhost:3000/api/mcp?workspace=NamaWorkspace.

Claude Desktop

Claude Desktop menjalankan MCP lewat perintah lokal, jadi endpoint HTTP dijembatani dengan mcp-remote. Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "pacecraft": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://pacecraft.duckdns.org/api/mcp?workspace=NamaWorkspace",
        "--header",
        "Authorization: Bearer pc_TOKEN_KAMU"
      ]
    }
  }
}

Restart Claude Desktop. Kalau tersambung, tool PaceCraft muncul di daftar tool (ikon 🔌). npx butuh Node.js terpasang di mesin.

Client MCP lain

Endpoint bicara JSON-RPC 2.0 di atas HTTP POST. Header wajib:

Authorization: Bearer pc_TOKEN_KAMU
Content-Type: application/json

Alur standar MCP: initialize → tools/list → tools/call.

4. Tool yang tersedia

Read:

Write — hanya dokumen. Lewat MCP, asisten luar bisa membuat dan menulis dokumen, tidak bisa menyentuh task, status, komentar, atau custom field. Tool tulis task memang ada di PaceCraft, tapi sengaja tidak diekspos ke MCP — memanggilnya lewat MCP dibalas Tool "…" tidak tersedia via MCP eksternal.

update_doc menambah di akhir dokumen secara default (mode: "append"). Isi lama tidak disentuh — konten baru ditempel sebagai blok tambahan, jadi tabel, callout, checklist, dan toggle yang sudah ada tetap utuh. Untuk menulis ulang seluruh dokumen, kirim mode: "replace" secara eksplisit; isi lama akan hilang dan tidak ada riwayat versi untuk memulihkannya.

Dua tool ini tetap dua langkah: panggilan pertama tanpa confirmed membalas proposal (tidak menulis apa pun), eksekusi nyata butuh panggilan ulang dengan confirmed=true. Perlu dipahami: lewat MCP confirmed diisi oleh asisten, bukan oleh PaceCraft — di client MCP tidak ada UI PaceCraft, jadi rem sesungguhnya adalah dialog persetujuan tool milik client kamu. Gunanya langkah proposal di sini: satu panggilan tak sengaja tidak pernah mengubah apa pun, dan panggilan yang merusak (mode: "replace") terlihat jelas di dialog itu sebelum kamu menyetujuinya. Jangan setel always allow untuk update_doc.

Setiap penulisan tercatat di Activity space yang bersangkutan (DOC_CREATED / DOC_UPDATED) atas nama pemilik token, jadi perubahan lewat MCP selalu bisa ditelusuri.

Format Markdown yang didukung

read_doc mengeluarkan Markdown dan create_doc/update_doc menerimanya, jadi siklus baca → ubah → tulis aman selama tetap di konstruk berikut: heading #/##/###, paragraf, bullet list (-), ordered list (1.), blockquote (>), fenced code block, horizontal rule (---), serta **tebal**, *miring*, ***tebal miring***, ~~coret~~, `kode`, dan [teks](url).

Konstruk editor di luar daftar itu — tabel, callout, checklist, toggle — tidak muncul di hasil read_doc. Karena itu mode: "append" adalah default: ia tidak pernah membaca-ulang isi lama, jadi tidak bisa menghapusnya. Hindari mode: "replace" pada dokumen yang memakai konstruk tersebut.

Semua tool otomatis dibatasi ke workspace koneksi dan hanya mengembalikan data yang memang boleh kamu akses — tool tidak bisa menembus ke workspace lain.

Contoh percakapan: "Task apa saja yang sudah lewat deadline?" → asisten memanggil search_tasks dengan overdueOnly=true. "Rangkum doc rencana rilis" → list_docs lalu read_doc.

5. Uji cepat via curl

TOKEN="pc_TOKEN_KAMU"
URL="https://pacecraft.duckdns.org/api/mcp?workspace=NamaWorkspace"

# Handshake
curl -s -X POST "$URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

# Daftar tool
curl -s -X POST "$URL" -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# Panggil tool
curl -s -X POST "$URL" -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_spaces","arguments":{}}}'

6. Troubleshooting

Catatan untuk pengembang

Tool tidak didefinisikan di route handler. Satu-satunya sumber definisi tool adalah src/lib/ai-tools/registry.ts — dipakai bersama oleh MCP server ini (src/server/mcp-adapter.ts + src/app/api/mcp/route.ts) dan asisten AI in-app (F32). Menambah tool = tambah satu entri di registry; MCP dan asisten langsung ikut punya tool itu. Menulis ulang definisi tool di route = dilarang (dua sumber kebenaran pasti menyimpang).