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 许可证。