WordPress MCP桥接插件

MCP WP Bridge (WordPress) – Teknik Kullanım Kılavuzu

Bu eklenti, WordPress’i Model Context Protocol (MCP) uyumlu araçlarla (Cursor, Windsurf, Claude Code, Gemini CLI, CodeX CLI, VS Code vb.) güvenli ve performanslı biçimde entegre eder. Amaç: komutla içerik/sayfa oluşturmak, medya yüklemek, tema/eklenti yönetmek ve (kontrollü) dosya düzenleme yapmaktır.

Hedef depo (GitHub): cetinibs/wordpress-mcp

1) Kurulum (WordPress Eklentisi)

1. wp-mcp-bridge klasörünü sitenizde wp-content/plugins/ altına kopyalayın.
2. WordPress yönetiminde: Eklentiler → MCP WP Bridge → Etkinleştir.
3. Ayarlar → MCP Bridge sayfasında:
   • API Token: otomatik oluşturulur; gerekirse değiştirin. Tüm çağrılarda X-MCP-Token başlığı zorunludur.
   • MFA (TOTP) Zorunlu: İsterseniz etkinleştirin. Etkinse her istekte X-MCP-OTP (6 haneli OTP) zorunlu.
   • Loglama: Gerekli ise açın. Üretimde genelde kapalı tutun.
   • Rate Limit: Maks istek (varsayılan 60) ve pencere (saniye, varsayılan 300) değerlerini ayarlayın.

Notlar (Güvenlik):

• Token olmadan tüm istekler reddedilir. MFA açıksa geçerli OTP zorunlu.
• İçerik uçları için edit_posts, yönetim uçları için manage_options yetkisi ve giriş zorunludur.
• Dosya erişimi sadece aktif tema ve wp-content/plugins altında normalize edilmiş yollar için açıktır.

2) REST API – Uçlar ve Örnekler

Temel URL: https://site-adresiniz.com/wp-json/mcp/v1 Zorunlu başlıklar:

• X-MCP-Token: <token>

• MFA açıksa: X-MCP-OTP: <6-haneli-kod>

• Site bilgisi

  • GET /site
  • Örnek:
    复制

    curl -H "X-MCP-Token: $TOKEN" https://site/wp-json/mcp/v1/site
    

• Yazı oluşturma

  • POST /posts
  • Body JSON: { "title": "...", "content": "<p>...</p>", "status": "draft|publish", "slug": "opsiyonel" }
  • Yanıt: { id, link }

• Sayfa oluşturma

  • POST /pages
  • Body JSON: { "title": "...", "content": "<p>...</p>", "status": "draft|publish", "slug": "opsiyonel" }
  • Yanıt: { id, link }

• Medya yükleme

  • POST /media
  • URL ile: { "url": "https://.../image.png", "filename": "image.png", "title": "opsiyonel" }
  • Base64 ile: { "base64": "iVBORw0K...", "filename": "image.png", "title": "opsiyonel" } (yaklaşık 5MB sınır)
  • Yanıt: { id, url }

• Tema yönetimi (Admin)

  • GET /themes → temaları ve aktif olanı listeler (5 dk cache)
  • POST /themes/{stylesheet}/activate → temayı etkinleştirir ve cache’i temizler

• Eklenti yönetimi (Admin)

  • GET /plugins → eklentileri ve aktiflik durumlarını listeler (5 dk cache)
  • POST /plugins/{plugin}/{activate|deactivate} → eklentiyi aç/kapatır ve cache’i temizler

• Dosya işlemleri (Admin)

  • GET /files?context=theme&target={stylesheet}&ext=php&ext=css → dosya listesi
  • GET /files?context=plugin&target={plugin-klasoru} → dosya listesi
  • GET /file?path={goreli-veya-mutlak-yol} → dosya içeriği
  • PUT /file body: { "path": "relative/or/absolute", "content": "yeni içerik" }

3) MCP Sunucusu (Opsiyonel, Node)

mcp-server/ klasörü, REST köprüsünü MCP araçlarına dönüştüren basit bir Node sunucusudur.

Kurulum:

cd mcp-server
npm install

Geliştirme:

# Ortam değişkenlerini set edin ve geliştirme modunda çalıştırın
# WP_BASE: https://site/wp-json/mcp/v1
# MCP_TOKEN: Ayarlar → MCP Bridge → API Token
WP_BASE="https://site/wp-json/mcp/v1" MCP_TOKEN="..." npm run dev

Sağlanan MCP araç örnekleri: getSiteInfo, createPost, createPage, uploadImage, listThemes, activateTheme, listPlugins, togglePlugin, listFiles, readFile, writeFile.

Cursor / Windsurf / VS Code Entegrasyonu (Özet)

• MCP özelliği olan istemcilerde komut/araç olarak yukarıdaki tool’ları tanımlayın.
• Sunucuyu node dist/index.js (veya npm run dev) ile başlatın; stdio tabanlı iletişim desteklenir.
• Her istek otomatik olarak X-MCP-Token gönderir (MCP sunucusu tarafında set edilen MCP_TOKEN). MFA açıksa istemci tarafında X-MCP-OTP’yi ekleyecek şekilde araç/komutları düzenleyin.

4) Güvenlik

• Zorunlu Token ve opsiyonel MFA (TOTP) kontrolü.
• En az ayrıcalık: içerik uçları için edit_posts, yönetim uçları için manage_options.
• OWASP doğrulamaları: sanitize_text_field, wp_kses_post, esc_url_raw, sanitize_file_name.
• Dosya erişimi: yalnızca aktif tema ve wp-content/plugins, realpath normalize.
• Oran sınırlama: varsayılan 60 istek/5 dk; admin ayarından değiştirilebilir.
• Loglama/izleme: error_log + mcp_bridge_event hook (admin’den kapatılabilir).

5) Performans

• Transient cache: Site/tema/eklenti listeleri 5 dk cache; değişiklikte otomatik temizlenir.
• Ayarlanabilir rate limit/loglama.
• Öneri: Redis/Memcached ile persistent object cache ve PHP OPcache etkinleştirin.

6) Testler

• Composer ile kurulum: composer install
• Çalıştırma: vendor/bin/phpunit (Windows: vendor\bin\phpunit)
• Kapsam: Token + MFA, rate limit, status whitelist, dosya yol normalize kritik akışları.

7) Sorun Giderme

• 401/403: Token/MFA/oturum/yetki kontrolü yapın.
• 429: Rate limit aşıldı; pencere bitimini bekleyin veya ayardan artırın.
• 413: Base64 yükleme boyutu sınırı aşıldı.
• Dosya yazma izni: Sunucu dosya izinlerini kontrol edin; WP_Filesystem yapılandırmasını doğrulayın.

8) Dağıtım (GitHub)

• Hedef depo: cetinibs/wordpress-mcp
• Aşağıdaki komutlarla ilk push (kimlik doğrulamanız gerekir):

git init
git add .
git commit -m "feat: MCP WP Bridge eklentisi ve teknik dokümantasyon"
git branch -M main
git remote add origin https://github.com/cetinibs/wordpress-mcp.git
git push -u origin main

Kurulum ve entegrasyon tamamdır. Sorularınız olursa issue olarak iletebilirsiniz.