TSGram MCP 🚀

Claude Code'u 3 dakikada yerel projenizde Telegram'a bağlayın!

TSGram MCP, Claude Code oturumlarını TS/Node/Docker/cli-utils kullanarak Telegram'a bağlayarak, AI destekli kod yardımını doğrudan Telegram sohbetlerinizde etkinleştirir. Kodtabanınız hakkında sorular sorun, AI içgörüleri alın ve hatta dosyaları düzenleyin - tümü telefonunuzdan Telegram'dan!

🔒 Nasıl Çalışır (Tamamen Yerel)

Yerel Docker konteyneri Telegram webhook sunucusunu çalıştırır
TSGram MCP sunucusu yerel olarak çalışır
Claude Code veya Claude Desktop'unuz yerel olarak çalışır ve MCP'yi yerel olarak ekler
Telegram aracılığıyla uygulamada botları oluşturun ve silin, erişim telegram kullanıcı kimliğinizle sınırlı
Localhost'tan botları yönetmek için modern yerel web panosu
Yerel demek yerel demek! Bilgisayarınız çevrimdışıysa, botlarınız da öyledir.

Hızlı Başlangıç (3 Dakika)

🤖 AI Aracı Geliştirilmiş Kurulum (Önerilir!)

Claude'un tüm kurulumu yapmasına ve gereken değerleri sormasına izin verin.

Terminal'inizden: 0. Docker Desktop ve Node.js 20+ (npm dahil) yükleyin

Depoyu klonlayın:

git clone https://github.com/areweai/tsgram-mcp.git
cd tsgram-mcp

Komut satırından Claude'u başlatın:
```
claude --model sonnet
```
/init ile başlatın
Bu istemi kopyalayıp yapıştırın:

First, explain to the human how to register a new Telegram bot with @BotFather and get their bot token (TELEGRAM_BOT_TOKEN), and how to get their Telegram user ID from @userinfobot (for AUTHORIZED_CHAT_ID). They can work on getting these credentials while you set up the system. Then help the user set up tsgram-mcp for claude code. Do everything from installing node modules to creating and deploying the local docker containers. Finally, when everything is deployed, remind the user to configure their bot token and authorized chat ID along wither other required .env variables.

TELEGRAM_BOT_TOKEN ve AUTHORIZED_CHAT_ID yer tutucularını gerçek değerlerle değiştirdiğinizden emin olun.

Bu değerleri almak için aşağıdaki Telegram botlarına mesaj göndermeli ve talimatlarını izlemelisiniz:

AI daha sonra tüm kurulum adımlarını sizin için gerçekleştirecektir:

Bağımlılıkları yükleme
Ortam değişkenlerini yapılandırma
Docker konteynerlerini oluşturma
Hizmetleri başlatma
Bot kaydı konusunda rehberlik etme
MCP sunucusunu kurma (ve işlevselliği yerel olarak genişletmenize izin verme)

LLM sorunlarıyla karşılaşırsanız CLI AI Alternatifi: Kurulum Shell Betiği Proje kökünüzden çalıştırın:

# Tek satırlı yükleme (macOS/Linux)
curl -sSL https://raw.githubusercontent.com/areweai/tsgram-mcp/main/setup.sh | bash

# Veya önce incelemek isterseniz:
curl -sSL https://raw.githubusercontent.com/areweai/tsgram-mcp/main/setup.sh > setup.sh
chmod +x setup.sh
./setup.sh

TSGram'ı Mevcut Bir Projeye Ekleme:

Zaten bir projeniz varsa ve TSGram'ı MCP sunucusu olarak eklemek istiyorsanız:

Mevcut proje kökünüzden:

git clone https://github.com/areweai/tsgram-mcp.git .tsgram-mcp
cd .tsgram-mcp

Claude'u kullanarak kurun:
```
claude model --sonnet
/init
```
Bu istemi yapıştırın:

"First, explain to the human how to register a new Telegram bot with @BotFather and get their bot token (TELEGRAM_BOT_TOKEN) from @UserBotInfoBot, and how to get their Telegram user ID from @userinfobot (for AUTHORIZED_CHAT_ID). They can work on getting these credentials while you set up the system. Then help me add TSGram MCP to my existing project in the parent directory. Set up the Docker containers and MCP configuration so I can use Telegram to interact with my project files. The project root is one level up from here."

Bu, TSGram'ı mevcut proje yapınızla çalışacak şekilde yapılandıracaktır (ve işlevselliği yerel olarak genişletmenize izin verecektir).

Bot'unuzu Test Edin! 🎉

ÖNEMLİ: Bot'unuza ilk olarak mesaj göndermeniz gerekir, böylece sizin size mesaj gönderebilir.

Bot'unuza bir mesaj gönderin ve yerel projeniz hakkında bir şey sorun!

⚠️ Güvenlik Notu: TSGram, .env dosyalarını listelememe, önizlememe veya sunmamaya yönelik temel güvenlik önlemleri alır, ancak yine de TSGram'ı, taşıma katmanının üçüncü taraf sunucuları içerdiği yüksek duyarlılıklı herhangi bir şey için kullanmamanız şiddetle tavsiye edilir.

📊 Web Panosu

http://localhost:3000'da web panosu aracılığıyla botlarınızı izleyin ve yönetin:

Pano aşağıdakileri sağlar:

Gerçek zamanlı bot durumu ve etkinlik izleme
Sistem sağlığı göstergeleri (MCP sunucusu, AI modeli, API anahtarları)
Bot yönetimi - Telegram botlarını oluşturun, test edin ve izleyin
Etkinlik günlükleri - Mesajları, yanıtları ve sistem olaylarını izleyin
Hızlı eylemler - Test mesajları gönderin ve bot yapılandırmalarını yönetin
Yerel olarak çalıştır - npm run dashboard ile görüntüleyin (Chrome önerilir)

📋 İhtiyacınız Olan Şeyler

Docker Desktop
Node.js 20+ (npm dahil)
Telefonda Telegram
Claude Desktop veya Claude Code (CLI)
OpenRouter API anahtarı (Yeni bir API anahtarını $1.00 limitiyle oluşturmanızı öneriyoruz. Güvenin ama sınırlayın!)
Chrome (Yerel yönetim UI'ı için isteğe bağlı ancak yüksek oranda önerilir)

Manuel Kurulum Adımları

1. Bot Token'ınızı ve Kullanıcı Kimliğinizi Alın

Bot Oluşturun: Telegram'da @BotFather'a mesaj gönderin
/newbot gönderin ve istemleri izleyin
Bot token'ınızı kopyalayın (bunu gizli tutun!)
Kullanıcı Kimliğinizi Alın (ÖNEMLİ): @userinfobot'a mesaj gönderin
- Bu sizin sayısal kullanıcı kimliğinizi döndürür (örn. 123456789)
- Güvenlik için kullanıcı kimliğini kullanın, kullanıcı adınızı DEĞİL (kullanıcı adları değiştirilebilir)

2. Ortamı Yapılandırın

.env dosyasını değerlerinizle düzenleyin:

TELEGRAM_BOT_TOKEN=your_bot_token_here
# KRİTİK: @userinfobot'tan sayısal kullanıcı kimliğini kullanın, kullanıcı adınızı değil!
AUTHORIZED_CHAT_ID=123456789  # Adım 1'den sayısal kullanıcı kimliğiniz

# Bir AI sağlayıcısı SEÇİN:
OPENROUTER_API_KEY=your_openrouter_key  # Claude için (önerilen, $1 limit ile)
# VEYA
OPENAI_API_KEY=your_openai_key         # GPT-4 için

Güvenlik Notu: Bot şimdi yetkilendirme için kullanıcı adı yerine sayısal kullanıcı kimliğinizi kullanır. Bu daha güvenlidir çünkü:

Kullanıcı kimlikleri hiçbir zaman değişmez
Kullanıcı adları kullanıcılar tarafından değiştirilebilir
Kullanıcı kimlikleri tahmin edilemez veya kolayca keşfedilemez

3. TSGram'ı Başlatın

npm install
npm run docker:build
npm run docker:start

🎯 Temel Özellikler

TSGram bot sohbetinde "Stop" ve "Start" komutları uygun çıkış kontrolü sağlar
Unix komutlarının desteklenen alt kümesi (:h ls veya :h cat $FILE)
Opt-in edit modu vibe kodlaması ve hareket halindeyken hata ayıklama için (:dangerzone ile etkinleştirin)
AI Destekli Yanıtlar: Claude 3.5 Sonnet veya GPT-4 kullanır
Kod Anlama: Tüm kodtabanınızı okur ve analiz eder
Web Panosu: http://localhost:3000'da botları izleyin

💬 Bot Komutları

Düzenli mesajlar: Kodunuz hakkında AI yanıtları alın
:h - Yardım ve mevcut komutları göster
:h ls [path] - Dizindeki dosyaları listele
:h cat filename - Dosya içeriğini görüntüle
:dangerzone - Dosya düzenlemesini etkinleştir (dikkatli olun!)
:safetyzone - Dosya düzenlemesini devre dışı bırak
stop - Bot yanıtlarını duraklat
start - Bot yanıtlarını devam ettir

🛠️ Yaygın Komutlar

# Günlükleri görüntüle
npm run docker:logs

# Sağlığı kontrol et
npm run docker:health

# Hizmetleri durdur
npm run docker:stop

# Değişikliklerden sonra yeniden oluştur
npm run docker:rebuild

# Panoya erişim (Chrome önerilir)
npm run dashboard

📜 Faydalı Betikler

Proje, scripts/ dizininde birkaç yardımcı betiği içerir:

Kurulum ve Yapılandırma

setup.sh - Otomatik yükleme betiği (curl aracılığıyla çalıştırılabilir)
configure-mcp.sh - Claude Desktop/Code için MCP ayarlarını yapılandır
fix-permissions.sh - Gerekirse dosya izinlerini düzelt

Güncellemeler ve Bakım

update-system.sh - TSGram'ı en son sürüme güncelle
update-ai-context.sh - AI bağlam dosyalarını güncelle

Test ve Hata Ayıklama

test-api-keys.sh - API anahtarlarınızın çalıştığını doğrula
test-docker-setup.sh - Docker yapılandırmasını test et

Herhangi bir betiği şu şekilde çalıştırın:

./scripts/script-name.sh
# veya
npm run script-name  # npm tarafından sarılan betikler için

🔧 Gelişmiş Kurulum

Claude Code ile Kullanma

Claude Code MCP ayarlarınıza ekleyin:

{
  "tsgram": {
    "command": "docker",
    "args": ["exec", "-i", "tsgram-mcp-workspace", "npx", "tsx", "src/mcp-server.ts"],
    "env": {
      "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
      "AUTHORIZED_CHAT_ID": "123456789"
    }
  }
}

Not: 123456789 yerine @userinfobot'dan aldığınız gerçek sayısal kullanıcı kimliğini girin

MCP Uyumluluğu

TSGram, standart Model Context Protocol (MCP) biçimini kullanır ve herhangi bir MCP destekleyen IDE veya araçla uyumlu olmalıdır. Tespit edilen:

✅ Claude Code CLI
✅ Claude Desktop

Aşağıdakilerle çalışması gerekir (standart MCP biçimi):

Cursor IDE
GitHub Copilot
Diğer MCP uyumlu editörler

Belirli MCP istemciniz için söz dizimini uyarlayarak yukarıda gösterilen Docker yapılandırma deseni kullanın.

CLI-to-Telegram Köprüsü

Claude Code CLI yanıtlarını Telegram'a ilet:

# Genel komutu kur (npm küresel yüklemesi için sudo parolası isteyebilir /usr/local/bin/claude-tg)
npm run setup

# 'claude' yerine kullan
claude-tg "analyze this codebase"

🚨 Sorun Giderme

Bot yanıt vermiyor?

# Hizmetlerin çalışıp çalışmadığını kontrol edin
npm run docker:health

# Hatalar için günlükleri görüntüleyin
npm run docker:logs

Bot'a bağlanamıyor?

.env'de bot token'ının doğru olduğunu doğrulayın
Kullanıcı kimliğinizi kontrol edin: AUTHORIZED_CHAT_ID'nin sayısal kullanıcı kimliğiniz olduğundan emin olun (kullanıcı adı değil)
- Emin değilseniz @userinfobot'dan alın
Önce bot'unuza mesaj gönderdiğinizden emin olun
"authorization not configured" hatası alırsanız, .env dosyanızda AUTHORIZED_CHAT_ID ayarlayın

Dosya düzenlemeleri çalışmıyor?

:dangerzone yazarak etkinleştirin (tek sefer)
İzin hataları için günlükleri kontrol edin
Docker'ın dosya erişimine sahip olduğundan emin olun

📚 Proje Yapısı

tsgram/
├── src/
│   ├── telegram-bot-ai-powered.ts    # Ana bot mantığı
│   ├── telegram-mcp-webhook-server.ts # MCP entegrasyonu
│   └── models/                        # AI sağlayıcıları
├── docker-compose.tsgram-workspace.yml # Ana Docker yapılandırması
├── .env.example                       # Ortam şablonu
└── data/                             # Kalıcı depolama

🤝 Katkı Yapma

PR'ler hoşlanır! Lütfen:

Depoyu fork edin
Bir özellik dalı oluşturun
Uygulanabilirse testler ekleyin
Bir pull request gönderin

📄 Lisans

MIT - Kendi projelerinizde kullanmakta özgürsünüz!

Yardıma mı ihtiyacınız var? GitHub'da bir issue açın veya bot'unuza sorularla mesaj gönderin!

areweai/tsgram-mcp

Bu MCP sunucusu hakkında