# voidhub-mcp

Claude'dan **Void Business** görev panolarını okuyup yazmanı sağlayan MCP sunucusu.
Kart açar, taşır, atar, yorumlar. Panoyu sen görmeden Claude senin adına düzenler.

> *English below.*

---

## MCP nedir, kısaca

MCP barındırılan bir servis değil. Bu paket, **senin bilgisayarında** çalışan küçük
bir program. Claude onu başlatır ve aralarında konuşurlar. Ortada açılacak bir port
ya da kurulacak bir sunucu yok.

Buradan çıkan üç sonuç var:

- Her kullanıcı **kendi token'ını** kullanır. Token paylaşmak, hesabını paylaşmaktır.
- Claude yalnızca token'ın yetkisi kadarını yapabilir. Fazlasını yapamaz, yapmaya
  çalışırsa sunucu reddeder.
- Program yerelde çalıştığı için panolarına internet üzerinden üçüncü bir taraf
  erişmez; istekler doğrudan senin Void sunucuna gider.

## Kurulum

Claude Code MCP yapılandırmana ekle:

```json
{
  "mcpServers": {
    "void-tasks": {
      "command": "npx",
      "args": ["-y", "voidhub-mcp"]
    }
  }
}
```

Sonra token'ını yaz:

```bash
echo 'void_app_...' > ~/.void-mcp-token
chmod 600 ~/.void-mcp-token
```

Claude Code'u yeniden başlat. `/mcp` yazınca `void-tasks` görünmeli.

Token'ı başka yerde tutuyorsan `VOID_BOT_TOKEN_FILE` ile yolunu ver, ya da
`VOID_BOT_TOKEN` ile doğrudan geç. Kendi Void sunucunu çalıştırıyorsan
`VOID_API_URL` ekle; varsayılan `https://api.thevoidhub.com`.

## Token nasıl alınır

Void Business'ta, **Ayarlar → Uygulamalar**:

1. **Yeni uygulama** oluştur.
2. Geliştirici bölümünü aç. `tasks.read` ve `tasks.write` kapsamlarını işaretle,
   sonra **Token oluştur**. Düğmenin üstünde hangi kapsamlarla üretileceği yazar,
   basmadan önce oraya bak.
3. Çıkan değeri kopyala. **`void_app_` ile başlar.** Hemen üstündeki, `app_` ile
   başlayan değer istemci kimliğidir, gizli değildir ve işine yaramaz.
4. Uygulamayı sunucuna kur. İzin olarak **Kanalı gör** ve **Görevleri yönet** ver.

Dördüncü adımı yalnızca **grup yöneticisi** yapabilir, ve yalnızca kendisinde olan
yetkileri devredebilir.

## Yetki modeli

Üç ayrı kapı var, üçünü birden geçmen gerekiyor:

| Kapı | Kim belirler | Geçilmezse |
|---|---|---|
| Token kapsamı | Uygulamayı oluşturan | `missing_scope` |
| Kurulum izni | Grup yöneticisi, sunucu başına | `forbidden` |
| Pano görünürlüğü | Pano üyeliği | Pano listede çıkmaz |

**`Görevleri yönet`, `Mesaj gönder`den ayrıdır.** Bir uygulamaya kanala yazma izni
vermek, panolarını düzenleme izni vermez. Bunlar iki farklı güven seviyesi ve tek
kutucukla ifade edilemez.

Uygulamanın eklenmediği **özel bir pano** listede hiç görünmez ve kimliği tahmin
edilerek de okunamaz. Beklediğin bir pano yoksa, cevap "uygulamanın erişimi yok"
olur, "pano silinmiş" değil.

## Araçlar

| Araç | Ne yapar | Gereken izin |
|---|---|---|
| `void_list_workspaces` | Uygulamanın kurulu olduğu sunucular ve verilen izinler | — |
| `void_find_board` | Bütün sunucularda isimle pano arar | Kanalı gör |
| `void_list_boards` | Bir sunucudaki panolar, `q` ile filtre | Kanalı gör |
| `void_list_tasks` | Panodaki kartlar, sütunlar, etiketler | Kanalı gör |
| `void_create_task` | Yeni kart | Görevleri yönet |
| `void_update_task` | Taşı, ata, başlık, öncelik, tarih | Görevleri yönet |
| `void_list_comments` | Karttaki yorumlar | Kanalı gör |
| `void_add_comment` | Karta yorum | Görevleri yönet |

Araç adlarını ezberlemene gerek yok. "test-pano'da ne var" ya da "ödeme akışını
gözden geçir diye kart aç, öncelik yüksek" demen yeter.

Aynı isimde birden fazla pano varsa `void_find_board` **hepsini** döndürür ve
hiçbirini seçmez. Yanlış ekibin panosuna yazmak, sormaktan kötüdür.

## Bir şey çalışmıyorsa

| Belirti | Sebep |
|---|---|
| Araçlar Claude'da görünmüyor | Claude Code yeniden başlatılmadı |
| "does not look like an app token" | `app_` ile başlayan istemci kimliğini yapıştırmışsın |
| Her şey `missing_scope` | Token kapsamsız üretilmiş. Kutucukları işaretleyip yeniden üret |
| Okuyor ama yazamıyor | Kurulumda **Görevleri yönet** verilmemiş. Yönetici verecek |
| Pano listede yok | Özel pano ve uygulama eklenmemiş, ya da uygulama o sunucuda kurulu değil |
| Sunucu hemen kapanıyor | Token bulunamadı. `~/.void-mcp-token` dosyasına bak |

403 hataları geçici değildir. Tekrar denemek sonucu değiştirmez; eksik izni bir
insanın vermesi gerekir.

## Ajanlar için

[`AGENT.md`](./AGENT.md) uç noktaları, hata kodlarını ve bir asistanın uyması
gereken davranış kurallarını içerir. Claude'un okuması için yazıldı.

## Kaynaktan çalıştırma

```bash
npm install
npm run build
node dist/index.js
```

## Lisans

MIT.

---

# English

MCP server that lets Claude read and write **Void Business** task boards: create
cards, move them between columns, assign them, comment on them.

**MCP is not a hosted service.** This package is a small program that runs on your
machine; Claude starts it and talks to it over stdio. So every user brings their
own token, and Claude can only ever do what that token is allowed to do.

### Install

```json
{
  "mcpServers": {
    "void-tasks": { "command": "npx", "args": ["-y", "voidhub-mcp"] }
  }
}
```

```bash
echo 'void_app_...' > ~/.void-mcp-token && chmod 600 ~/.void-mcp-token
```

Restart Claude Code. Override the token location with `VOID_BOT_TOKEN_FILE`, pass it
inline with `VOID_BOT_TOKEN`, or point at a self-hosted instance with `VOID_API_URL`.

### Getting a token

In Void Business, **Settings → Apps**: create an app, tick the `tasks.read` and
`tasks.write` scopes, then issue a token. It starts with `void_app_` — the `app_`
value above it is the public client id, not the secret. Then install the app on your
server with **View channel** and **Manage tasks**. Only a group admin can do that.

**Manage tasks is separate from Send messages** on purpose: letting an app post in a
channel should not also let it rewrite your boards.

A private board the app was not added to is not listed and cannot be read by
guessing its id.

See [`AGENT.md`](./AGENT.md) for the endpoint reference and the working rules an
assistant should follow.

MIT licensed.