Anytype MCP ve API v2: kasayı programla okumak ve yazmak

AFFiNE dizisindeki [[AFFiNE MCP]] yazısında sunucu, bulutta ya da kendi sunucunda duran çalışma alanını okur. Anytype'ta kapı bilgisayarının içindedir.

Local API

Local API sayfası API'nin ilk sürümünü 0.46 sürümüne bağlar. API masaüstü uygulamasıyla gelir, tamamen localhost'ta çalışır, bulut bağımlılığı yoktur. Belgenin örneğiyle: uçakta da çalışır (Anytype, Local API).

Anahtar almak için:

1. **Vault Settings**'i aç.
2. **Data Management** altında **API Keys**'i seç.
3. **Create New** ile bir anahtar oluştur ve ad ver.

İstediğin kadar anahtar oluşturabilir, istediğini iptal edebilirsin. Belgenin güvenlik uyarısı kırmızı kutudadır: bir API anahtarı ya da eklenti, kasana sınırlı erişim verir ve nesneleri düzenlemek ya da silmek bu erişimin içindedir. Yalnız güvendiğin eklentileri kullan.

v1 ve v2

Geliştirici portalı iki sürümü ayırır (Anytype, API v2):

İki sürüm aynı süreçte, aynı portta çalışır ve aynı API anahtarlarını kabul eder. Kalıcı bir entegrasyon kuruyorsan portal v1'i önerir.

v2 nasıl düşünüyor

v2'nin giriş sayfası birkaç kuralı sayar (Anytype, API v2 Introduction):

• **Tek okuma, toplu yazma.** Bir `GET` nesnenin özelliklerini ve içeriğini birlikte getirir. Bir `PATCH`, bir dizi düzenlemeyi tek seferde uygular. Eşzamanlılık denetimi, yeniden deneme ve kuru çalıştırma (dry run) vardır.
• **Masaüstünden eşleşme.** Uygulama adınla bir istek gönderirsin. Anytype masaüstünde hangi kanallara ve hangi izinlerle erişileceğini sen onaylarsın, dört haneli bir kod alırsın. Kodu gönderince anahtar gelir.
• **Kararlı anahtarlar.** Özellik ve tür, oluşturulduğu an bir anahtar alır (`due_date` gibi). Özelliğin adını sonra değiştirsen de anahtar aynı kalır. Betikte anahtarı kullan.
• **Hoşgörülü girdi.** `due_date`, `dueDate`, `due-date` ve `Due date` aynı özelliğe gider. Belirsiz bir yazım 400 hatası ve aday listesi döndürür. Bilinmeyen bir ad hiçbir zaman sessizce yeni özellik oluşturmaz.
• **Küçük okumalar.** `?outline=true` yalnız yapıyı, `?format=md` salt okunur bir Markdown çıktısını verir. Markdown çıktısını geri yazamazsın; düzenleme `PATCH` işlemleriyle yapılır.

[[İkinci bölümdeki]] tür ve özellik modeli burada makineye açılır: tür bir kalıp, özellik o kalıbın alanı, alanın kalıcı bir anahtarı var. Markdown kasasındaki karşılığı [[YAML alanlarıdır]].

MCP sunucusu

Resmî MCP sunucusu `@anyproto/anytype-mcp` paketidir. Anytype'ın OpenAPI tanımını MCP araçlarına çevirir. Portal şu işleri sayar: kanal içi ve kanallar arası arama, kanal ve üye yönetimi, nesne ve liste oluşturma, özellik ve etiket, tür ve şablon (Anytype, MCP Server).

Anahtarı uygulamadan alabilir ya da `npx -y @anyproto/anytype-mcp get-key` komutunu kullanabilirsin. İstemci ayarına anahtarı ve `Anytype-Version` başlığını yazarsın. Bu başlık v1'in başlığıdır; sunucu v1 üzerinden konuşur.

Agents' Skill

Agents' Skill, Anytype'ın açık kaynak araç setidir. Claude Code, Cursor, Gemini CLI ve GitHub Copilot gibi ajanlara yaklaşık 30 hazır yöntem verir: nesne okuma, oluşturma, güncelleme, arama, tür ve özellik, koleksiyon ve sorgu (Anytype, Agents' Skill).

Ajan bir JavaScript betiği yazar ve betiği yalıtılmış bir çalışma ortamında çalıştırır. Betik dosya sistemine ya da Local API dışındaki ağa erişemez. Belgenin parantez içi uyarısı önemli: Anytype'ın içinde betik, API'nin izin verdiği her şeyi değiştirebilir.

Belgenin üç ipucu:

AFFiNE'den farkı

Anytype'ta veri bilgisayarından çıkmadan ajana açılır. Karşılığında anahtarın yetkisi geniştir ve uygulamanın açık olması gerekir. Agents' Skill de Anytype'ın aynı cihazda kurulu ve çalışır olmasını şart koşar.

Diyelim ki "Okuma" kanalındaki her Kitap nesnesi için bağlı bir Değerlendirme nesnesi istiyorsun. Ajana ayrı bir anahtar verirsin, önce beş kitapta denemesini istersin, çıkan betiği okursun. Doğruysa bütün kanalda çalıştırırsın, iş bitince anahtarı iptal edersin.