Eklentiler ve MCP

Crewhall üç yolla genişletilir. Eklentiler sekme, kart, komut ve araç ekler. MCP, Claude gibi yapay zekâ asistanlarının çalışma alanında senin adına çalışmasını sağlar. REST API, betiklerin ve CI işlerinin Crewhall'ı kişisel token ile çağırmasını sağlar. Üçü de gerçek bir kişinin yetkileriyle çalışır, onları hiçbir zaman aşmaz.

Eklentiler​

Bir eklenti şunları ekleyebilir:

Crewhall eklenti kodu çalıştırmaz. Eklentinin arayüzü ve mantığı kendi sunucusunda çalışır. Sekme ve kartları korumalı bir çerçevede açılır, Crewhall'ın eklentiye gönderdiği her istek imzalıdır. Eklenti bir kişi adına çalışırken o kişinin yapabildiğinden fazlasını yapamaz ve yöneticinin onayladığı izinlerle sınırlıdır. Mesajları ve değişiklikleri eklentinin rozetini taşır.

Pazar yerindeki her eklentinin bir etiketi vardır: Resmî (Crewhall ekibinin eklentisi), İncelendi (pazar yerinde incelendi ve imzalandı) ya da Gayriresmî (bağlandığı hizmetin izin vermediği bir yolla çalışır; riskler kurmadan önce listelenir).

Eklenti kur​

Kurum sahipleri ve yöneticileri eklentileri Yönetim › Eklentiler'den yönetir.

1. Pazar yeri sekmesini aç ve eklentiyi bul.
2. Kur'u seç. Pencerede eklentinin sunucusu, istediği izinler ve Crewhall'da görüneceği yerler yazar.
3. Vermek istemediğin izinlerin işaretini kaldır. Eklentiye neyin verildiği bildirilir, gerisi olmadan çalışır.
4. İzinleri onayla ve kur'u seç.

Katalogda görünmeyen bir eklenti için, örneğin kurumuna özel olan, ID ya da bağlantıyla kur'u kullan ve eklenti kimliğini ya da pazar yerinin kurulum bağlantısını yapıştır.

Bazı eklentiler Kendi sunucunda olarak işaretlidir. Bunların kopyasını kurumun kendisi çalıştırır, böylece veri yayıncının sunucusundan geçmez. Kurarken kendi sunucunun https adresini gir. Bu sunucu, pazar yerinin imzaladığı manifesti kendi adresiyle /.well-known/crewhall-plugin.json adresinde sunmalıdır. Crewhall bunu denetler ve sonra yalnız bu adresle konuşur.

Kurulu eklentileri yönet​

Kurulu sekmesinde şunları yapabilirsin:

• Eklentiyi aç ya da kapat. Kapalıyken sekmeleri, kartları ve komutları kaybolur.
• Verilen izinleri İzinler ile değiştir.
• Yeni sürüme güncelle. Yeni sürüm ek izin istiyorsa yalnız yeni izinler sorulur.
• Kaldır. Eklentinin sunucusuna kurulumun kaldırıldığı bildirilir.
• Mikrofon, kamera, konum ya da panoya kopyalama gibi tarayıcı yeteneklerine izin ver. Kişi yine tarayıcının kendi onayını verir.

Bazı eklentiler arka planda çalışabilir, örneğin panoları başka bir sistemle eşitlemek için. Bunun için yöneticinin izni vermesi ve her kişinin ayrıca onaylaması gerekir. Kişiler bunu Bildirim ayarları › Eklentiler'den kapatır. Misafirler eklenti görmez.

Sunucu ayarları​

Eklentiler tek bir pazar yerinden gelir. Bunu iki backend değişkeni belirler:

Her eklenti paketi kurulumda ve her güncellemede bu anahtarlarla denetlenir. İmzasız eklenti kurulamaz.

Eklenti yaz​

Eklenti SDK'sı packages/plugin-sdk içindeki @crewhall/plugin-sdk paketidir. MIT lisanslıdır; eklenti yazıp serbestçe satabilirsin. Üç bölümü vardır:

Manifest eklenti kimliğini (com.example.hello gibi ters alan adı), sürümü, adı, yayıncıyı, sunucu adresini (origin), istenen izinleri ve giriş noktalarını tanımlar. İzinler MCP ve kişisel token'larla aynı kapsamları kullanır, ör. hub:read ve chat:send.

En küçük eklenti sayfası:

import { connect } from '@crewhall/plugin-sdk/bridge';

const bridge = await connect();
document.body.textContent = `Merhaba ${bridge.context.user.name}`;
const token = await bridge.getToken(); // eklenti sunucuna gönder

Sunucunda oturum token'ını doğrula. Token 5 dakika geçerlidir ve Crewhall REST API'sini de kişinin yetkileri ve eklentinin izinleriyle açar.

import { verifySessionToken } from '@crewhall/plugin-sdk/server';

const who = await verifySessionToken(token, {
  issuer: installation.apiUrl,
  audience: 'com.example.hello',
});

Manifestini denetle, sonra incelemeye göndermek için pazar yerine yükle. Pazar yeri sürümü onaylayınca imzalar; geliştiriciler paketi kendileri imzalamaz.

pnpm --filter @crewhall/plugin-sdk plugin validate manifest.json

apps/plugin-hello (o da MIT) bütün giriş noktalarını gösteren örnek eklentidir: bir sekme, bir ana sayfa kartı, /hello komutu, greet aracı ve message.created olayı. Yerelde şöyle çalıştırırsın:

PORT=4331 PLUGIN_ORIGIN=http://localhost:4331 pnpm --filter @crewhall/plugin-hello dev

MCP: yapay zekâ asistanı bağla​

Crewhall'ın https://hub.example.com/mcp adresinde yerleşik bir MCP sunucusu vardır. Streamable HTTP, PKCE ile OAuth 2.1 ve dinamik istemci kaydını destekler. OAuth desteklemeyen istemciler kişisel token'ı Authorization: Bearer başlığında gönderir. Adresi ve kurulum adımlarını Hesabım › MCP ve API'de bulursun.

Claude Code:

claude mcp add --transport http crewhall https://hub.example.com/mcp

Sonra Claude Code'da /mcp yaz ve crewhall › Kimlik doğrula'yı seç. Tarayıcıda Crewhall onay ekranı açılır.

Claude Desktop ve claude.ai: Ayarlar › Bağlayıcılar'a git, Özel bağlayıcı ekle'yi seç, adresi yapıştır, Bağlan de ve onay ekranında izin ver. Takım planında bağlayıcıyı önce kurum yöneticisi ekler, sonra herkes kendi hesabıyla bağlanır.

Kapsamlar ve onay ekranı​

Onay ekranında istemcinin ne yapabileceğini, hangi space'lere ulaşabileceğini ve bağlantının ne kadar süreceğini (7, 30 ya da 90 gün veya süresiz) seçersin. Okuma her zaman zorunludur. İstemci hiçbir zaman senin yapabildiğinden fazlasını alamaz.

Bir bağlantıyı istediğin an Hesabım › MCP ve API'den daraltabilir ya da kaldırabilirsin. Daraltma hemen geçerli olur.

Onaylar​

Riskli işlemler bir kişinin onayını bekler. Kurum politikasına göre bunlar arasında Çöp'e taşıma, 20 ya da daha fazla öğelik toplu değişiklik, dış paylaşım linki, portal yayını ve space sohbetine mesaj vardır. Bazıları her zaman onay ister.

Bekleyen istekler Hesabım › Onay bekleyenler'de önizlemesiyle görünür. Onayla ve uygula passkey ya da şifreyle doğrulanır. İstek beklerken hedef değişirse istek eskir ve asistanın yeniden istemesi gerekir.

Etkinlik ve araç belgeleri​

• Etkinlik her çağrıyı zaman, istemci, araç, hedef ve sonuçla listeler. Yazma, onay bekleyen, hata ya da geri alınan olarak süzebilirsin. Bazı yazmalar buradan geri alınabilir. Kayıtlar 90 gün saklanır.
• Araç belgeleri her aracı açıklaması, gereken kapsamı, onay isteyip istemediği, girdi şeması ve oran sınırlarıyla listeler.

Yönetici politikası​

Yönetim › MCP ve API'de yöneticiler MCP sunucusunun ve kişisel token'ların açık olup olmadığına, misafirlerin bağlanıp bağlanamayacağına, oran sınırlarına, en uzun token ömrüne, tüm MCP istemcilerinin mi yoksa yalnız listedekilerin mi bağlanabileceğine ve hangi işlemlerin insan onayı istediğine karar verir. Yöneticiler kurumdaki herhangi bir bağlantıyı kesebilir ama içeriğini ya da token değerini hiçbir zaman göremez.

Kişisel token ile REST API​

REST API, web ve mobil uygulamanın kullandığı API'nin aynısıdır. MCP araçlarıyla aynı servisleri aynı kapsam, space sınırı, onay ve oran sınırlarıyla çağırır.

Token oluşturmak için:

1. Hesabım › MCP ve API'yi aç ve Token oluştur'u seç.
2. Bir ad gir, sonra kapsamları, space'leri ve son kullanma tarihini seç. İstersen IP aralıklarıyla sınırla.
3. Token'ı kopyala. Yalnız bir kez gösterilir; sonra yalnız iptal edilip yenisi oluşturulabilir.

Aynı yerdeki REST API sayfasından OpenAPI 3.1 belgesini indir. Her uç, şeması ve gereken kapsamla listelenir.

curl -H "Authorization: Bearer $CREWHALL_TOKEN" https://hub.example.com/api/v1/spaces

Bilmen gereken kurallar:

• Token sahibinin yetkileriyle çalışır, seçilen kapsam ve space'lerle sınırlıdır.
• Hesap, güvenlik, oturum, token yönetimi ve kasa uçları token'a hiçbir zaman açık değildir. Çöp'e taşıma ve paylaşım linki de gerçek bir oturum ister.
• Hata gövdesi { code, message, details? } biçimindedir. Token'ın kapsamı dışındaki istek 403 token_scope alır.
• Listeler imleçlidir: cursor ve limit gönderilir, yanıt { items, nextCursor } biçimindedir.
• Yazan istekler Idempotency-Key başlığını kabul eder, böylece tekrar denemek güvenlidir.

WebDAV​

Kişisel token, Drive'ı WebDAV ile Finder'da, Windows Gezgini'nde ya da rclone'da klasör olarak bağlarken parola olarak da kullanılır. Bkz. Drive.