飞书 MCP Server

English Documentation

Bu, Model Context Protocol (MCP) sunucusu uzaktan bağlantı desteği ve yerleşik Feishu OAuth kimlik doğrulaması ile sağlanmaktadır.

Bu proje cloudflare/ai/demos/remote-mcp-github-oauth dosyasından değiştirilmiş olup GitHub OAuth, Feishu OAuth ile değiştirilmiştir.

Bunu kendi Cloudflare hesabınıza dağıtabilir ve kendi Feishu OAuth istemci uygulamasını oluşturduktan sonra, tamamen işlevsel bir uzaktan MCP sunucusuna sahip olabilirsiniz. Kullanıcılar Feishu hesabı aracılığıyla MCP sunucunuza bağlanabilir.

📋 İçindekiler

• Feishu Resmi MCP Server ile Farklar
• Özellikler
• Hızlı Başlangıç
• Dağıtım Yöntemleri
  • Üretim Ortamı Dağıtımı
  • Yerel Geliştirme Ortamı
• İstemci Entegrasyonu
  • Inspector Kullanarak Test Etme
  • Cursor Kullanma
  • ChatWise Kullanma
• Erişim Kontrolü
• Araç Geliştirme Yol Haritası
• Teknik İlkeler
• Geliştirme Kılavuzu

🆚 Feishu Resmi MCP Server ile Farklar

Feishu resmi olarak da bir MCP Server yayınlamış olsa da, bu proje birkaç açıdan önemli avantajlara sahiptir:

🎯 Sıfır Yapılandırma Deneyimi

• Bu Proje: Kullanıcılar herhangi bir parametreyi manuel olarak yapılandırmaya gerek kalmaz, tüm süreç user_access_token kullanır ve otomatik olarak yenilenir
• Resmi Proje: Kullanıcıların birden çok parametreyi manuel olarak yapılandırması gerekir, yapılandırma karmaşıktır

🚀 Uç Kullanılabilirlik Optimizasyonu

• Bu Proje: Araç boyutu ve yapısını derinlemesine optimize eder, özellikle belge oluşturma bloğu araçları, iç içe geçmiş blok oluşturma araçları gibi karmaşık işlevleri içerir, Cursor gibi istemcilerde normal kullanım sağlar
• Resmi Proje: Basit API'den MCP aracına dönüştürme, bazı araçlar çok büyüktür, gerçek kullanımda kullanılabilirlik sorunları vardır

🌐 İleri Temel Altyapı

• Cloudflare Workers'a dağıtımı destekler, endüstrinin en ileri kenar bilişim altyapısından yararlanır

✨ Özellikler

• 🎯 Sıfır Yapılandırma Deneyimi: Kullanıcılar herhangi bir parametreyi manuel olarak yapılandırmaya gerek kalmaz, user_access_token otomatik olarak yönetilir ve yenilenir
• 🔐 Feishu OAuth Kimlik Doğrulaması: Güvenli kullanıcı kimlik doğrulaması
• 🌐 Uzaktan MCP Sunucusu: Birden çok istemci bağlantısını destekler
• 🚀 Cloudflare Workers: Yüksek performanslı, global dağıtılmış dağıtım, endüstrinin en ileri kenar bilişim altyapısından yararlanır
• 🛠️ Derinlemesine Optimize Edilmiş Araç Seti: Belge oluşturma, iç içe geçmiş bloklar gibi karmaşık araçları özel olarak optimize eder, çeşitli istemcilerde normal kullanım sağlar
• 🔧 Yerel Geliştirme Desteği: Geliştirme ve test için uygun ortam
• ⚡ Uç Kullanılabilirlik: Resmi MCP Server ile karşılaştırıldığında, gerçek kullanım deneyimini ve istikrarını önemli ölçüde iyileştirir

🚀 Hızlı Başlangıç

Ön Koşullar

• Node.js 18+ ve npm
• Cloudflare hesabı
• Feishu Açık Platform hesabı

Kurulum

# Depoyu klonlayın
git clone <repository-url>
cd open-feishu-mcp-server

# Bağımlılıkları yükleyin
npm install

🚀 Dağıtım Yöntemleri

Üretim Ortamı Dağıtımı

Adım 1: Feishu Uygulaması Oluşturun

1. Feishu Açık Platform ziyaret edin ve giriş yapın
2. "Geliştirici Arka Planda" tıklayın ve yeni bir uygulama oluşturun
3. Uygulama ayarlarında izinleri yapılandırın:
   • "İzinler ve İşlevler" bölümüne girin ve aşağıdaki izinleri ekleyin:

     • "Kullanıcı ID'sini Al" (auth:user.id:read)

     • "Kullanıcı Görev Bilgisini Al" (task:task:read)

     • "Kullanıcı Yetkilendirme Kimlik Bilgisini Al" (offline_access)

     • "Kullanıcı Temel Bilgisini Al" (user_profile)

       ...

4. Uygulama ID ve Uygulama Parolası not alın

Adım 2: Cloudflare Ortamını Yapılandırın

# Gerekli gizli anahtarları ayarlayın
wrangler secret put FEISHU_APP_ID
wrangler secret put FEISHU_APP_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY  # openssl rand -hex 32 kullanarak oluşturun

# KV ad alanı oluşturun
wrangler kv namespace create "OAUTH_KV"

Adım 3: Yapılandırma Dosyasını Güncelleyin

Adım 2'de alınan KV ID'sini kullanarak wrangler.toml dosyasındaki KV ad alanı yapılandırmasını güncelleyin.

Adım 4: Sunucuyu Dağıtın

npm run deploy

Dağıtım tamamlandıktan sonra, gerçek subdomain'inizi not alın (dağıtım günlüğünde gösterilir).

Adım 5: Yeniden Yönlendirme URL'sini Yapılandırın

Feishu uygulama ayarlarına geri dönün:

1. "Güvenlik Ayarları" bölümüne girin
2. Yeniden Yönlendirme URL'sini ekleyin: https://feishu-mcp-server.<your-actual-subdomain>.workers.dev/callback

Yerel Geliştirme Ortamı

Yerel Ortamı Yapılandırın

1. Feishu Uygulamasını Yapılandırın:

   • Feishu uygulamasının "Güvenlik Ayarları" bölümüne şunu ekleyin: http://localhost:8788/callback
   • Gerekli izinlere sahip olduğunuzdan emin olun (üretim ortamı gibi)

2. Ortam Değişkenini Dosya Oluşturun: Proje kök dizininde .dev.vars dosyası oluşturun:

   FEISHU_APP_ID=your_development_feishu_app_id
   FEISHU_APP_SECRET=your_development_feishu_app_secret
   COOKIE_ENCRYPTION_KEY=any_random_string_here
   

Yerel Sunucuyu Başlatın

npm run dev

Sunucu http://localhost:8788 adresinde çalışacaktır.

🔌 İstemci Entegrasyonu

Inspector Kullanarak Test Etme

Sunucunuzu test etmek için resmi MCP Inspector'ı kullanın:

npx @modelcontextprotocol/inspector@latest

Bağlantı Adresi:

• Üretim ortamı: https://feishu-mcp-server.<your-subdomain>.workers.dev/sse
• Yerel ortam: http://localhost:8788/sse

Cursor Kullanma

Tek tıklamayla yükleme düğmesi aracılığıyla hızlı yapılandırma:

Veya manuel olarak yapılandırın:

{
  "mcpServers": {
    "feishu": {
      "url": "http://localhost:8788/sse"
    }
  }
}

ChatWise Kullanma

1. Yapılandırma Adımları:

   • ChatWise ayarları arayüzünü açın
   • Araçlar seçeneğine gidin
   • Yeni komut satırı giriş/çıkış (stdio) ekleyin
   • Komut: npx -y mcp-remote ${URL}

2. Bağlantı Adresi:

   • Yerel: http://localhost:8788/sse
   • Üretim: https://feishu-mcp-server.<your-subdomain>.workers.dev/sse

3. İlk Kullanım:

   • Yapılandırma kaydedildikten sonra Feishu OAuth giriş sayfası otomatik olarak açılır
   • Yetkilendirmeyi tamamladıktan sonra Feishu ilgili işlevlerini kullanabilirsiniz

🔐 Erişim Kontrolü

• Kimlik Doğrulama: Kullanıcı kimlik doğrulaması için Feishu OAuth kullanır
• İzin Kapsamı: Tüm kimlik doğrulaması yapılmış Feishu kullanıcıları tüm araçlara erişebilir

📋 Araç Geliştirme Yol Haritası

🚧 Şu Anda Geliştirme Aşamasında (Feishu Belgeleri)

• 🔧Geliştirme Yardımcı Araçları
  • ✅ Belge İçeriği Arama ve Geri Çağırma
• 📄 Belge Temel İşlemleri
  • ✅ Belge Bloğu Ağaç Yapısı Alma
  • ✅ Blok Türü Oluşturma Parametreleri Schema Alma
  • ✅ Belge Bloğu Oluşturma (çeşitli blok türlerini destekler)
  • ✅ Belge Bloğu İçeriğini Güncelleme
  • ✅ Toplu Belge Bloğu Silme
• 🔧 Belge İleri İşlevleri
  • ✅ Tablo Oluşturma ve İşletme
  • ✅ Resim, Video, Dosya Yükleme ve Ekleme
  • ✅ Markdown İçe Aktarma İşlevi
  • ✅ Malzeme Yükleme ve Yönetimi
  • ✅ Belge Arama

🎯 Gelecek Planları

• 📊 Elektronik Tablo (Sheets)

  • 📋 Çalışma Sayfası Temel İşlemleri (oluşturma, silme, yeniden adlandırma)
  • 📋 Hücre Veri Okuma/Yazma
  • 📋 Formül Hesaplaması ve Uygulaması
  • 📋 Grafik Oluşturma ve Düzenleme
  • 📋 Veri Filtreleme ve Sıralama
  • 📋 İşbirliği ve İzin Yönetimi

• 🗃️ Çok Boyutlu Tablo (Base/Bitable)

  • 📋 Veri Tablosu Temel İşlemleri
  • 📋 Kayıt Ekleme, Silme, Güncelleme, Okuma
  • 📋 Alan Türü Yönetimi
  • 📋 Görünüm Oluşturma ve Yapılandırma
  • 📋 Otomasyon Kuralı Ayarları
  • 📋 Veri İçe/Dışa Aktarma

  ...

Açıklama: ✅ Tamamlandı | 🔄 Geliştirme Aşamasında | 📋 Planlı

🛠️ Teknik İlkeler

Mimari Bileşenler

OAuth Sağlayıcı

Tam OAuth 2.1 sunucusu uygulaması, aşağıdakileri işler:

• MCP istemcisi kimlik doğrulaması
• Feishu OAuth hizmet bağlantı yönetimi
• KV depolamasında güvenli token yönetimi

Dayanıklı MCP

Cloudflare Durable Objects tabanlı MCP uzantısı:

• Dayanıklı durum yönetimi
• Kimlik doğrulama bağlamı depolaması
• this.props aracılığıyla kullanıcı bilgisine erişim
• Kullanıcı kimliğine dayalı koşullu araç kullanılabilirliği

MCP Uzaktan

Uzaktan MCP istemci bağlantılarını destekler:

• İstemci-sunucu iletişim protokolü tanımı
• Yapılandırılmış araç tanımı yöntemi
• İstek/Yanıt serileştirmesini işler
• SSE bağlantısını korur

👨‍💻 Geliştirme Kılavuzu

MCP Sunucusu (Cloudflare Workers tarafından desteklenir)

Bu proje çift OAuth rolü uygular:

• MCP istemcilerine karşı OAuth sunucusu olarak davranır
• Feishu OAuth hizmetine karşı OAuth istemcisi olarak davranır

Araç Geliştirme

Mevcut araçlar kullanıcı erişim token'ı kullanarak kimlik doğrulaması yapar, bu aşağıdakları sağlar:

• Feishu API'sine güvenli erişim
• Kullanıcı izinlerine dayalı özellik erişimi
• Eksiksiz hata işleme ve günlüğe kaydetme

---

📝 Not: Dağıtmadan önce tüm ortam değişkenlerini ve Feishu uygulama ayarlarını doğru şekilde yapılandırdığınızdan emin olun. Sorun yaşarsanız, Feishu uygulama izin yapılandırması ve yeniden yönlendirme URL'si ayarlarını kontrol edin.

Star History