Genel Bakış

Mapfolio MCP Sunucusu, AI asistanlarının ve diğer MCP uyumlu istemcilerin Mapfolio'nun verileri ve işlemleriyle etkileşime girmesini sağlayan bir Model Context Protocol (MCP) sunucusudur. Şirketler, projeler, kullanıcılar, LinkedIn profilleri ve yönetim işlevlerine programatik erişim sağlar.

MCP Nedir?

Model Context Protocol (MCP), AI asistanlarının harici veri kaynaklarına ve araçlara güvenli bir şekilde erişmesini sağlayan açık bir protokoldür. MCP sunucuları, standartlaştırılmış bir arayüz aracılığıyla yetenekleri ortaya çıkarır ve AI asistanlarının:

Veri sorgulama ve alma
İşlem gerçekleştirme
Kaynaklara erişme
Harici sistemlerle entegrasyon

Özellikler

Mapfolio MCP Sunucusu kapsamlı işlevsellik sağlar:

Şirket Verileri

Gelişmiş filtrelerle şirket arama
ID'ye göre şirket detaylarını alma
Kanton ve başlangıç harfine göre şirket alma
Örnekleme için rastgele şirketler alma
Şirket ziyaret istatistiklerine erişim

Proje Yönetimi

Proje oluşturma ve yönetme
Kullanıcı projelerini listeleme ve filtreleme
Proje detaylarını güncelleme
Projeleri silme
Projelere şirket ekleme ve çıkarma

Kullanıcı Profilleri

Kullanıcı profil bilgilerini alma
Profil ayarlarını güncelleme
Kullanıcı projelerini listeleme
API anahtarlarını yönetme

LinkedIn Entegrasyonu

LinkedIn profil verilerini alma
LinkedIn profillerini arama
Bağlantı bilgilerine erişim
Profil sürüm geçmişini görüntüleme
LinkedIn şirket verilerini alma

Yönetim İşlemleri

Tüm kullanıcıları listeleme (sadece admin)
Yeni kullanıcı oluşturma (sadece admin)
API anahtarlarını yönetme (sadece admin)
Admin panel istatistiklerine erişim

İstatistikler

Toplanmış şirket istatistiklerini alma
Kanton seviyesi sayımları görüntüleme
Harf tabanlı sayımlara erişim
İki harfli kombinasyon istatistiklerini alma

Kurulum

Önkoşullar

Node.js >= 20.0.0
npm >= 10.0.0
Mapfolio Supabase örneğine erişim

Kurulum

Bağımlılıkları yükleyin:

cd mcp-server
npm install

Ortam değişkenlerini yapılandırın:

cp .env.example .env

.env dosyasını düzenleyin ve yapılandırın:

# Mapfolio API URL (varsayılan: https://mapfolio.app)
MAPFOLIO_API_URL=https://mapfolio.app

# Taşıma türü: 'stdio' (varsayılan) veya uzaktan erişim için 'http'
MCP_TRANSPORT=stdio

# HTTP portu (yalnızca MCP_TRANSPORT=http olduğunda kullanılır)
MCP_HTTP_PORT=3001

# İsteğe bağlı: Varsayılan kimlik doğrulama (MCP bağlamı veya HTTP başlıkları aracılığıyla sağlanabilir)
MAPFOLIO_API_KEY=mapf_your_api_key_here
MAPFOLIO_JWT_TOKEN=your-jwt-token-here

Sunucuyu derleyin:

npm run build

Kullanım

Sunucuyu Çalıştırma

Yerel Geliştirme (stdio taşıması)

MCP sunucusu varsayılan olarak stdio taşımasını kullanır (standart MCP protokolü):

npm start

Otomatik yeniden yükleme ile geliştirme için:

npm run dev

HTTP Taşıması (uzaktan erişim için)

Yerel testler için HTTP taşımasıyla sunucuyu çalıştırmak için:

MCP_TRANSPORT=http MCP_HTTP_PORT=3001 npm start

Bu, HTTP POST üzerinden JSON-RPC 2.0 isteklerini kabul eden 3001 portunda bir HTTP sunucusu başlatır.

Vercel Dağıtımı (Uzaktan Erişim)

MCP sunucusu Vercel'e dağıtıldığında otomatik olarak HTTP üzerinden kullanılabilir:

Endpoint: https://your-app.vercel.app/api/mcp
Protokol: HTTP POST üzerinden JSON-RPC 2.0
Kimlik Doğrulama: X-API-Key başlığı veya Authorization: Bearer <token> başlığı aracılığıyla

Örnek istek:

curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mapf_your_api_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

MCP İstemci Yapılandırması

Claude Desktop

Yerel dağıtım:

{
  "mcpServers": {
    "mapfolio": {
      "command": "node",
      "args": ["/path/to/mapfolio/mcp-server/dist/index.js"],
      "env": {
        "MAPFOLIO_API_URL": "https://mapfolio.app",
        "MAPFOLIO_API_KEY": "mapf_your_api_key_here"
      }
    }
  }
}

Cursor

MCP ayarları üzerinden yapılandırın:

Komut: node
Args: ["/path/to/mapfolio/mcp-server/dist/index.js"]
Ortam değişkenleri:
- MAPFOLIO_API_URL: https://mapfolio.app
- MAPFOLIO_API_KEY: API anahtarınız (isteğe bağlı)

Kimlik Doğrulama

Sunucu iki kimlik doğrulama yöntemini destekler:

API Anahtarı Kimlik Doğrulaması

API anahtarları mapf_ önekiyle başlar ve şunlar olabilir:

MAPFOLIO_API_KEY ortam değişkeni aracılığıyla ayarlanabilir
Araç çağrılarında apiKey parametresi aracılığıyla istek başına geçirilebilir

JWT Token Kimlik Doğrulaması

Supabase JWT tokenları şunlar olabilir:

MAPFOLIO_JWT_TOKEN ortam değişkeni aracılığıyla ayarlanabilir
Araç çağrılarında jwtToken parametresi aracılığıyla istek başına geçirilebilir

Kimlik Doğrulama Önceliği

HTTP Taşıması: Başlıklar (X-API-Key veya Authorization) önceliklidir
İstek başına kimlik bilgileri (araç argümanlarında apiKey veya jwtToken)
Ortam değişkenleri (MAPFOLIO_API_KEY veya MAPFOLIO_JWT_TOKEN)

HTTP Taşıması Kimlik Doğrulaması

HTTP endpoint'i (/api/mcp) kullanılırken, kimlik doğrulama HTTP başlıkları aracılığıyla sağlanır:

API Anahtarı: X-API-Key: mapf_your_api_key
JWT Token: Authorization: Bearer your_jwt_token

Kullanılabilir Araçlar

Sunucu 6 kategoride 30+ araç sağlar:

Şirket Araçları

search_companies - Filtrelerle arama
get_company - ID'ye göre şirket alma
get_companies_by_canton_letter - Kanton ve harfe göre alma
get_random_companies - Rastgele örnekler alma
get_company_visits - Ziyaret istatistiklerini alma

Proje Araçları

create_project - Yeni proje oluşturma
list_projects - Kullanıcı projelerini listeleme
get_project - Proje detaylarını alma
update_project - Projeyi güncelleme
delete_project - Projeyi silme
add_companies_to_project - Şirket ekleme
remove_companies_from_project - Şirket çıkarma

Kullanıcı Araçları

get_user_profile - Profil alma
update_user_profile - Profil güncelleme
get_user_projects - Projeleri listeleme
get_user_api_keys - API anahtarlarını listeleme

LinkedIn Araçları

get_linkedin_profile - Profil alma
search_linkedin_profiles - Profil arama
get_linkedin_connections - Bağlantıları alma
get_linkedin_profile_versions - Sürüm geçmişini alma
get_linkedin_companies - Şirket verilerini alma

Admin Araçları (Sadece Admin)

list_all_users - Tüm kullanıcıları listeleme
create_user - Kullanıcı oluşturma
get_user_details - Kullanıcı detaylarını alma
list_api_keys - Tüm API anahtarlarını listeleme
create_api_key - API anahtarı oluşturma
revoke_api_key - API anahtarını iptal etme
get_admin_stats - Admin istatistiklerini alma

İstatistik Araçları

get_company_stats - Toplanmış istatistikleri alma
get_canton_counts - Kanton sayımlarını alma
get_letter_counts - Harf sayımlarını alma
get_two_letter_counts - İki harfli sayımları alma

Kaynaklar

Sunucu kaynak tabanlı erişim sağlar:

mapfolio://company/{id} - Şirket verileri
mapfolio://project/{id} - Proje verileri
mapfolio://user/{id} - Kullanıcı profili
mapfolio://linkedin-profile/{id} - LinkedIn profili

Kaynaklar sorgu parametreleri aracılığıyla kimlik doğrulama içerebilir:

mapfolio://company/{id}?apiKey=mapf_...
mapfolio://company/{id}?jwtToken=...

Kullanım Örneği

Şirket Arama

{
  "tool": "search_companies",
  "arguments": {
    "query": "technology",
    "cantons": ["ZH", "BE"],
    "page": 1,
    "limit": 20
  }
}

Proje Oluşturma

{
  "tool": "create_project",
  "arguments": {
    "name": "Tech Companies Zurich",
    "searchType": "company",
    "searchQuery": "technology",
    "isPublic": false
  }
}

Şirket Detaylarını Alma

{
  "tool": "get_company",
  "arguments": {
    "companyId": "company-uuid-here"
  }
}

Hata Yönetimi

Tüm araçlar hataları tutarlı bir formatta döndürür:

{
  "error": "Hata mesajı"
}

Yaygın hata senaryoları:

401 Yetkisiz: Geçersiz veya eksik kimlik doğrulama
403 Yasak: Yetersiz izinler
404 Bulunamadı: Kaynak bulunamadı
500 İç Sunucu Hatası: Sunucu tarafı hata

Sadece API Mimarisi

MCP sunucusu doğrudan veritabanı erişimi yerine mapfolio.app'e HTTP istekleri kullanır. Bu şu anlama gelir:

✅ Supabase kimlik bilgileri gerekmez - Sadece API URL'si ve API anahtarıyla çalışır
✅ Kolay Vercel dağıtımı - Serverless fonksiyon olarak dağıtın
✅ Güvenli - Tüm istekler kimlik doğrulama ile Mapfolio'nun API'sinden geçer
✅ Ölçeklenebilir - Mapfolio'nun API hız sınırlaması ve önbelleğinden yararlanır

Şu Anda API Üzerinden Kullanılabilir

✅ Şirket arama ve alma
✅ Şirket istatistikleri (kanton sayımları, harf sayımları)
✅ Rastgele şirketler
✅ Şirket ziyaretleri

Yakında (API Endpoint'leri Gerektirir)

⏳ Proje yönetimi (oluştur, listele, güncelle, sil)
⏳ Kullanıcı profil yönetimi
⏳ LinkedIn profil erişimi
⏳ Admin işlemleri

Bu özellikler API endpoint'leri oluşturulana kadar yararlı hata mesajları döndürecektir.

Güvenlik Hususları

API Anahtarları: Güvenli bir şekilde saklayın, asla sürüm kontrolüne commit etmeyin
JWT Tokenları: Tokenların süresi dolar, yenilemeyi uygun şekilde yönetin
API Hız Sınırlaması: Mapfolio'nun API hız limitlerine saygı gösterir
Sadece HTTPS: API istekleri için her zaman HTTPS kullanın
Admin İşlemleri: Açık admin kimlik doğrulaması gerektirir (endpoint'ler mevcut olduğunda)

Geliştirme

Tip Kontrolü

npm run type-check

Derleme

npm run build

Geliştirme Modu

npm run dev

Dokümantasyon

Tam dokümantasyon için MCP Sunucusu README dosyasına bakın.

Destek

Sorunlar veya sorular için:

GitHub Issues: [mapfolio repository]
Email: support@mapfolio.app

Lisans

MIT