Letta MCP Server Railway

🚀 萊塔MCP服務器鐵路版

萊塔MCP服務器的雲優化HTTP傳輸版本，可在30秒內部署到Railway平臺。它是一個通用的MCP服務器，通過可流式傳輸的HTTP協議，將任何AI客戶端連接到萊塔.ai強大的有狀態代理，實現無縫的雲部署。

🚀 快速部署到Railway

前提條件

• 從 api.letta.com 獲取 萊塔API密鑰（提供免費套餐）
• 擁有 Railway賬戶（免費套餐每月包含500小時使用時長）

一鍵部署

1. 點擊上方的部署按鈕
2. 將你的GitHub賬戶連接 到Railway
3. 添加環境變量：LETTA_API_KEY=your_letta_api_key_here
4. 部署 - 你的MCP服務器將在不到2分鐘內上線！

你的MCP服務器URL

https://your-app-name.up.railway.app/mcp

⚡ 與AI客戶端集成

Claude桌面版（ADE集成）

將以下內容添加到Claude桌面版配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "letta-railway": {
      "url": "https://your-app.up.railway.app/mcp",
      "transport": "streamable_http",
      "timeout": 300,
      "headers": {
        "User-Agent": "Claude-Desktop-MCP/1.0"
      }
    }
  }
}

MCP檢查器測試

使用MCP檢查器測試你的部署：

npx @modelcontextprotocol/inspector https://your-app.up.railway.app/mcp

GitHub Copilot和VS Code

{
  "mcp.servers": {
    "letta-railway": {
      "transport": "streamable_http",
      "url": "https://your-app.up.railway.app/mcp"
    }
  }
}

其他MCP客戶端

• Cursor：將服務器添加到MCP配置中
• Replit：使用兼容MCP的端點配置
• Sourcegraph Cody：通過OpenCtx橋進行配置
• 任何MCP客戶端：使用可流式傳輸的HTTP傳輸協議

🔧 配置

環境變量

萊塔雲設置

1. 註冊：在 letta.com 創建賬戶
2. 獲取API密鑰：訪問 api.letta.com → 設置 → API密鑰
3. 創建代理：使用Web界面創建你的第一個代理
4. 測試連接：使用letta_health_check工具進行驗證

🛠️ 可用工具（20多個萊塔函數）

🤖 代理管理

• letta_list_agents - 帶分頁和過濾功能列出所有代理
• letta_create_agent - 創建帶有內存塊和工具的新代理
• letta_get_agent - 獲取詳細的代理信息
• letta_update_agent - 更新代理配置（名稱、描述、模型）
• letta_delete_agent - 安全刪除代理並確認

💬 對話管理

• letta_send_message - 支持流式傳輸向代理發送消息
• letta_get_conversation_history - 帶分頁功能檢索聊天曆史記錄
• letta_export_conversation - 導出對話（Markdown、JSON、文本格式）

🧠 內存管理

• letta_get_memory - 查看代理的所有內存塊
• letta_update_memory - 更新內存塊（人工、角色、自定義）
• letta_create_memory_block - 創建自定義內存塊
• letta_search_memory - 搜索代理對話內存

🔧 工具管理

• letta_list_tools - 帶過濾功能列出所有可用工具
• letta_get_agent_tools - 查看特定代理附加的工具
• letta_attach_tool - 為代理添加工具
• letta_detach_tool - 從代理中移除工具

📊 監控與健康檢查

• letta_health_check - 驗證API連接和服務狀態
• letta_get_usage_stats - 獲取使用統計信息和分析數據

🏗️ 技術架構

針對Railway優化的特性

• 可流式傳輸的HTTP傳輸：與標準輸入輸出相比，更適合雲部署
• 連接池：維護持久連接以提高性能
• 自動擴展：Railway根據需求自動擴展
• 零停機部署：熱重載且不丟失連接
• 內置監控：Railway儀表盤顯示指標和日誌

性能優化

# 針對Railway雲環境進行優化
- HTTP持久連接
- 請求/響應壓縮  
- 帶退避策略的智能重試邏輯
- 內存高效的JSON流式傳輸
- 自動連接池管理

傳輸方式比較

💻 本地開發

快速本地設置

# 克隆倉庫
git clone https://github.com/SNYCFIRE-CORE/letta-mcp-server-railway.git
cd letta-mcp-server-railway

# 安裝依賴  
pip install -e .

# 設置環境變量
export LETTA_API_KEY=your_api_key_here

# 本地運行
python -m letta_mcp_server_railway.server

本地測試

# 使用MCP檢查器測試
npx @modelcontextprotocol/inspector http://localhost:8000/mcp

# 或者使用curl
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

開發命令

# 運行測試
pytest tests/

# 格式化代碼
black src/ tests/

# 類型檢查  
mypy src/

# 代碼檢查
ruff check src/

🔍 故障排除

常見問題

1. “連接被拒絕”錯誤

# 檢查你的Railway應用是否正在運行
curl https://your-app.up.railway.app/health

# 在Railway儀表盤驗證環境變量
# 確保LETTA_API_KEY設置正確

2. “無效的API密鑰”錯誤

# 直接測試你的萊塔API密鑰
curl -H "Authorization: Bearer your_api_key" https://api.letta.com/v1/agents

3. “超時”錯誤

# 在你的MCP客戶端配置中增加超時時間
{
  "mcpServers": {
    "letta-railway": {
      "url": "https://your-app.up.railway.app/mcp",
      "transport": "streamable_http", 
      "timeout": 300  // 增加到5分鐘
    }
  }
}

4. Claude桌面版無法連接

• 配置更改後重啟Claude桌面版
• 使用JSON驗證器檢查配置文件語法
• 驗證URL是否可從你的瀏覽器訪問

獲取幫助

1. 查看Railway日誌：在Railway儀表盤查看部署日誌
2. 測試健康端點：訪問https://your-app.up.railway.app/health
3. 驗證MCP端點：使用MCP檢查器進行測試
4. 社區支持：加入 萊塔Discord
5. 報告問題：GitHub問題

🚀 生產環境部署

Railway部署最佳實踐

環境管理

# 生產環境變量
LETTA_API_KEY=your_production_api_key
LETTA_BASE_URL=https://api.letta.com
PORT=8000  # Railway自動管理此設置
LETTA_TIMEOUT=300
LETTA_MAX_RETRIES=5

健康監控

Railway提供內置監控，你還可以：

• 設置自定義健康檢查
• 監控響應時間和錯誤率
• 配置停機警報

擴展配置

# railway.toml - 生產環境設置
[build]
builder = "DOCKERFILE"

[deploy] 
restartPolicyType = "ON_FAILURE"

[[deploy.environmentVariables]]
name = "PORT"
value = "8000"

📖 資源

文檔

• 萊塔文檔 - 完整的萊塔平臺指南
• MCP規範 - 模型上下文協議標準
• Railway文檔 - Railway平臺指南
• FastMCP文檔 - HTTP傳輸框架

社區與支持

• 萊塔Discord - 活躍的社區支持
• MCP社區 - 協議開發
• Railway社區 - 部署支持
• GitHub問題 - 錯誤報告和功能請求

示例與教程

• 萊塔代理示例 - 示例代理配置
• MCP客戶端集成 - 客戶端設置指南
• Railway模板 - 部署模板

🤝 貢獻代碼

我們歡迎大家貢獻代碼，讓萊塔MCP服務器鐵路版變得更好！

快速貢獻指南

1. 分叉 倉庫
2. 創建 功能分支：git checkout -b feature/amazing-feature
3. 進行 修改並添加測試
4. 本地測試：pytest tests/
5. 提交 清晰的提交信息：git commit -m "Add amazing feature"
6. 推送 到你的分叉倉庫：git push origin feature/amazing-feature
7. 提交 拉取請求

開發環境設置

# 分叉並克隆你的分叉倉庫
git clone https://github.com/YOUR_USERNAME/letta-mcp-server-railway.git
cd letta-mcp-server-railway

# 安裝開發依賴
pip install -e ".[dev]"

# 安裝預提交鉤子
pre-commit install

# 運行測試
pytest tests/ -v

需要幫助的領域

• 📖 文檔改進
• 🧪 增加測試覆蓋率
• 🔧 Railway部署優化
• 🌐 多語言客戶端示例
• 🐛 錯誤修復和性能改進

📜 許可證

本項目採用MIT許可證，詳情請參閱 LICENSE。

🙏 致謝

本項目由社區用心打造，旨在實現AI代理的無縫部署。

特別感謝：

• 萊塔.ai 提供革命性的有狀態代理
• Railway 提供出色的部署平臺
• Anthropic 在MCP規範方面的領導地位
• FastMCP 提供HTTP傳輸框架
• 所有貢獻者 讓這個項目成為可能

🚂 在30秒內將萊塔代理部署到雲端 - Railway讓部署變得輕鬆。