Kivv

🚀 自動 arXiv 研究論文發現與 AI 摘要系統

本系統能夠自動發現 arXiv 上的研究論文，並藉助 AI 進行總結，同時集成了適用於 Claude Desktop 的 MCP（模型上下文協議）。作為一個氛圍編碼項目，我們確保工具輕量級且反饋循環快速，讓你在輸出研究見解時保持流暢。

✨ 主要特性

• 每日自動搜索：自動在 arXiv 上搜索與你指定主題匹配的論文。
• AI 摘要：由 Claude 驅動的智能論文總結功能，同時優化成本。
• 多用戶支持：支持多個用戶，每個用戶可獨立配置主題。
• MCP 集成：通過模型上下文協議直接與 Claude Desktop 集成。
• RSS 訂閱：為每個用戶提供 RSS/Atom 訂閱源，可用於任何訂閱閱讀器。
• Web 儀表盤：可選的 SvelteKit 儀表盤（即將推出）。
• 成本效益高：主要運行在 Cloudflare 免費層（2 個用戶每月約 3 美元）。

🔧 技術細節

架構

• MCP 服務器：使用 TypeScript 編寫的 Worker，負責處理 MCP 協議和工具執行。
• 每日自動化：由定時任務觸發的 Worker，用於收集和總結論文。
• 存儲：使用 Cloudflare D1（SQLite）、R2（存儲 PDF 文件）和 KV（緩存）。
• AI：採用 Claude 3.5 Sonnet 並結合 Haiku 分類以優化成本。

🚀 快速開始

前提條件

• 啟用了 Workers、D1、KV 和 R2 的 Cloudflare 賬戶。
• Anthropic Claude API 密鑰（可從 console.anthropic.com 獲取）。
• Bun 1.1+（包管理器，可從 bun.sh 安裝）。
• Wrangler CLI（通過 bun 自動安裝）。

📦 安裝指南

# 克隆倉庫
git clone https://github.com/jeffaf/kivv.git
cd kivv

# 使用 bun 安裝依賴（我們默認的氛圍編碼方式）
bun install

# 設置環境變量
cp .env.example .env
# 編輯 .env 文件，填入你的 API 密鑰和 Cloudflare 憑證

部署

完整的部署說明請參考 DEPLOYMENT.md。

快速部署步驟如下：

# 為自動化 Worker 設置密鑰
cd automation
wrangler secret put CLAUDE_API_KEY
wrangler secret put CRON_SECRET

# 部署自動化 Worker
wrangler deploy

# 部署 MCP 服務器
cd ../mcp-server
wrangler deploy

# 配置 Claude Desktop（詳細信息見 DEPLOYMENT.md）
# 將 MCP 服務器 URL 和 API 密鑰添加到 Claude Desktop 配置中

驗證

# 測試自動化 Worker
curl https://kivv-automation.<username>.workers.dev/health

# 測試 MCP 服務器
curl https://kivv-mcp.<username>.workers.dev/health

# 檢查數據庫
wrangler d1 execute kivv-db --command "SELECT COUNT(*) FROM users"

# 或者使用自動化健康檢查腳本
./scripts/health-check.sh

如果遇到任何問題，請參考 TROUBLESHOOTING.md。

自動化部署腳本

使用以下命令進行一鍵部署：

# 運行自動化部署腳本
./scripts/deploy.sh

# 該腳本將執行以下操作：
# - 驗證前提條件
# - 檢查基礎設施
# - 配置密鑰
# - 部署兩個 Worker
# - 提供 Claude Desktop 配置

📚 詳細文檔

項目結構

kivv/
├── mcp-server/          # MCP 服務器 Worker（Claude 集成）
├── automation/          # 每日自動化 Worker（定時任務）
├── shared/              # 共享類型和工具函數
├── tests/
│   ├── security/       # 安全測試（認證、注入、XSS）
│   ├── integration/    # MCP 工具集成測試
│   └── unit/           # 單元測試
├── .checkpoint/         # 開發檢查點
└── package.json         # 帶有工作區的單倉庫根文件

文檔鏈接

• 部署指南 - 完整的生產部署說明
• 故障排除指南 - 常見問題及解決方案
• 設置清單 - 基礎設施設置
• 實施計劃 - 分階段開發指南
• API 文檔 - API 端點和使用方法
• PRD（完整規格） - 完整的技術規格

CI 與自動化

• 測試與類型檢查：GitHub Actions 在推送和拉取請求時運行 bun run type-check 和 bun test，確保氛圍編碼快速且不破壞構建。
• 部署：當 mcp-server/ 或 automation/ 發生更改時，Cloudflare Workers 部署管道將觸發，使用你配置的 Cloudflare 憑證通過 wrangler 進行部署。

💻 使用示例

開發命令

# 運行類型檢查
bun run type-check

# 運行所有測試
bun test

# 專門運行安全測試
bun run test:security

# 以監聽模式運行測試
bun run test:watch

# 在本地運行 MCP 服務器
bun run dev:mcp

# 在本地運行自動化 Worker
bun run dev:automation

# 構建所有工作區
bun run build

測試覆蓋

項目包含全面的測試覆蓋：

• 安全測試（要求 100% 覆蓋）：
  • 認證（API 密鑰驗證）
  • 授權（用戶數據隔離）
  • SQL 注入預防
  • RSS 訂閱源中的 XSS 預防
  • 速率限制實施
• 集成測試：端到端的 MCP 工具工作流測試
• 單元測試：獨立的工具函數測試

# 運行測試並生成覆蓋率報告
bun run test:coverage

📄 許可證

本項目採用 MIT 許可證。