web-mcpo-repo scanner

🔭 TodoScope

](https://github.com/Startr/TodoScope)    ](https://www.docker.com/)  ](https://github.com/Startr/TodoScope/stargazers)  ](https://github.com/Startr/TodoScope/commits)

每个代码库都有一个待办事项列表。他们中的大多数都是一团糟。TodoScope是关于团队所说的他们将修复的内容与实际完成的内容之间的差距，以及这种差距揭示了软件是如何构建的。

为您的AI助手提供所有仓库中每个TODO的实时视图。

连接 Sage.is, Claude.ai，或任何与MCP兼容的助手，并询问： *“这个项目中还有什么TODO？”* TodoScope立即响应。它还为您的团队提供了一个干净的web UI，可以在不离开代码库的情况下浏览、跟踪和掌握内联TODO和TODO.md文件。

代码是开放的。项目不断发展。参与进来。

Sage_repo-TODOs.gif

AI和MCP集成

TodoScope实现了 模型上下文协议，使其成为人工智能助手的一流工具。

• Sage.is AI 和 Claude.ai 可以直接调用TodoScope——让你的助手在它可以访问的任何仓库中列出、总结或优先处理TODO。
• 任何兼容MCP的客户端都会通过其清单端点自动发现TodoScope。
• OpenAPI规范是动态生成的-文档总是与实时API匹配。

它做什么

待办事项堆积如山。它们隐藏在注释中，位于TODO.md文件中，并在存储库中被遗忘。TodoScope可以找到所有这些：

• AI就绪API： 符合MCP标准——Sage.is、Claude.ai和其他助手直接查询它。
• 流式扫描： 查看TODO在扫描文件时实时显示。
• TODO.md支持： 检测并呈现独立的TODO文件以及内联代码注释。
• 实时刷新： 监视本地存储库的更改，并在不进行完全重新扫描的情况下更新视图。
• 本地回购管理： 注册本地路径——路径保留在服务器上，永远不会暴露给浏览器。
• .gitignore知道： 跳过项目忽略的文件和目录。

运作原理

1. 提供Git URL或注册本地仓库路径。
2. TodoScope克隆（或读取）存储库。
3. 它扫描所有文本文件以查找TODO模式，并找到独立的TODO.md文件。
4. 结果流到web UI，并可通过API获得。

安装

独立二进制文件（不需要Python）

下载自 并运行：

./todoscope

打开浏览器 http://localhost:5000.数据存储在 ~/.todoscope/.

macOS.app

下载 TodoScope.dmg 从 发布，拖动到“应用程序”。 双击→ 🔭 出现在菜单栏中→ 浏览器打开。菜单栏图标有打开浏览器、显示日志和退出。

pip/uv

pip install todoscope    # or: uv tool install todoscope
todoscope

本地开发

需要Python 3.11+和Git。

git clone https://github.com/Startr/TodoScope.git GIT-TodoScope
cd GIT-TodoScope
pip install pipenv
cd scanner && pipenv install
cd ..
make it_run_dev

打开 http://localhost:5000。页面上的安全警告将引导您设置第一个访问密钥。

码头工人

git clone https://github.com/Startr/TodoScope.git GIT-TodoScope
cd GIT-TodoScope
make it_build
make it_run SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))")

克隆的存储库和您的 access_keys.csv 从主机装载，因此它们可以在容器重启后存活。

CapRover

使用随附的从CapRover仪表板进行部署 caprover-one-click.yml，或将此仓库添加为自定义一键源。设置 SECRET_KEY 设置过程中的变量。部署后，访问应用程序URL，并通过安全面板设置您的第一个访问密钥。

Cloudflare 快速隧道

要公开共享本地实例进行演示，请执行以下操作：

make run_tunnel

API终点

扫描仪提供RESTful API。关键端点包括：

• 扫描存储库：

  curl -X POST http://localhost:5000/api/mpco/scan_repository \
    -H "Content-Type: application/json" \
    -d '{"repo_url": "https://github.com/username/repository.git"}'

• 列出本地存储库：

  curl -X GET http://localhost:5000/api/mpco/list_repositories

• 拉取存储库更新：

  curl -X POST http://localhost:5000/api/mpco/pull_repository \
    -H "Content-Type: application/json" \
    -d '{"repo_name": "repository_name_from_list"}'

API输出示例（扫描存储库）

{
  "repo_url": "https://github.com/username/repository.git",
  "repo_name": "repository",
  "todo_count": 42,
  "todos": [
    {
      "file_path": "src/main.py",
      "line_num": 24,
      "todo_text": "# TODO: Fix this hack when we have time",
      "next_line": "def temporary_solution():"
    }
    // ... more TODOs
  ],
  "web_url": "http://localhost:5000/scan/https://github.com/username/repository.git"
}

所有项目

这个项目虽然致力于寻找TODO，但有自己想要的增强功能和特性列表。欢迎投稿！

品牌和登录页面（CEO评论——按表面范围）

范围A——注销登录（登录页面）

• \[ \] 将login.html升级为真正的登录页面：英雄、投球、特征、登录
• \[ \] 在登录页面上展示MCP/AI代理故事

范围B——登录仪表板（索引页）

• \[ \] 添加仪表板标题：以简短的形式重述单行间距，引导用户
• \[ \] 统一回购条目：一个接受git URL的输入 *或* 具有智能检测的本地路径
• \[ \] 存储库处于空状态：当没有注册回购时，显示一张友好的入职卡，其中包含2-3个建议的快速启动操作（扫描演示回购、注册本地路径、复制MCP端点）
• \[ \] 仪表板上的表面MCP端点：一张小型“连接到AI代理”卡，带有用于清单URL和示例cURL的复制到剪贴板按钮
• \[ \] 将搜索/筛选添加到“存储库”表中 （一旦列表超过~10，则相关）
• \[ \] 添加可见的“上次扫描”时间戳+手动刷新控制 每回购行
• \[ \] 将GitHub贡献横幅移动到页脚 --它正在与主要动作竞争
• \[ \] 澄清“浅克隆”复选框：工具提示或内联帮助，解释何时使用它

范围C——MCP/Sage.is集成表面

• \[ \] 创建专用 /connect 或 /mcp 页 使用分步说明将TodoScope连接到Sage、Claude Desktop和通用MCP客户端
• \[ \] 添加“复制MCP清单URL”按钮 在登录的仪表板上可见
• \[ \] 写一篇简短的指南 — docs/connect-sage.md --屏幕截图显示了端到端的Sage→ TodoScope查询
• \[ \] 添加MCP健康指标 到仪表板：清单端点响应时为绿点，未响应时为红点

范围D——品牌一致性和复制

• \[ \] 审核所有面向用户的副本 反对品牌面试的声音：诚实的创始人语气，清晰第一，从不花言巧语
• \[x\] 页脚更新：为sage.is和startr.style添加了交叉链接；“Startr生态系统的一部分”框架
• \[x\] 重命名“Todoscope”→ “TodoScope” 在模板、README、盖层清单和页面标题之间保持一致
• \[x\] 图标：将剪贴板表情符号替换为望远镜(🔭) — 与名称中的“范围”隐喻一致
• \[x\] 页面标题：描述性，品牌一致 `` 应用于base/index/login的标签
• \[x\] 登录页面无索引：添加 `` 因此，自托管实例不会被索引
• \[x\] 页面描述：在base.html中添加了单行间距作为默认元描述
• \[ \] 错误消息：音调检查——应与Starter声音匹配，而不是一般的烧瓶错误

范围E——首次运行和入职体验

• \[ \] 首次运行向导：设置第一个访问密钥后，引导用户注册仓库并连接AI代理
• \[ \] 包含演示/示例回购选项 首次访问时，用户可以在注册任何自己的内容之前查看流媒体结果
• \[ \] 添加“实时试用”部分 登录后，对公共演示仓库运行预览扫描

文件和规划TODO

• \[ \] 创建全面的API文档：独立API参考指南
• \[ \] 添加架构文档：系统设计和组件概述
• \[ \] 创建贡献者指南：新贡献者详细指南
• \[ \] 增强代码文档：添加全面的文档字符串
• \[ \] 创建开发工作流文档：详细的工作流程指南

高优先级

• \[x\] 修复现有存储库无法工作的主要问题。
• \[x\] 为扫描仪实施稳健的错误处理机制。
• \[x\] 扩大TODO模式识别（例如FIXME、BUG、NOTE）。
• \[x\] DRY Makefile目标。（是否允许向目标传递参数？）
• \[x\] 启用API结果流，以提高响应能力。
• \[\]将Python文件和依赖项迁移到子目录结构。

中优先级

• \[\]添加对TODO.md和TODO.txt文件的检测。#功能#核心（无需大写）
• \[\]实现一个用户友好的web界面来显示TODO文件。
• \[\]包括使用我们的MCPo Api查看TODO文件的选项。
• \[\]将repo自述文件中的摘要添加到web界面。（可选前20行）
• \[\]实现TODO注释的搜索功能。
• \[\]开发一个仪表板，以可视化跨项目的TODO指标。
• \[\]提供多种格式（CSV、JSON、PDF）的报告下载。
• \[\]与GitHub webhooks集成，实现自动存储库扫描。
• \[\]增强TODO文件处理：

技术债务

• \[ \] 重构 stream_results.html JavaScript: createTodoElement() 和 createTodoMarkdownElement() 使用重复的Startr.style字符串手工构建DOM。替换为服务器渲染的Jinja2片段+SSE，它推送HTML片段，或者至少将共享样式提取到命名常量中。

低优先级

• \[\]发布CapRover一键应用源：添加 caprover-one-click.yml 单击Startr存储库并将其注册为CapRover中的自定义源。
• \[\]将TodoScope添加到 Startr/homebrew-apps tap：编写一个公式，提取Docker映像并连接launchd服务。
• \[\]引入用户身份验证以实现安全访问。
• \[\]从TODO注释中实现优先级推断。
• \[\]设计一个插件系统来扩展扫描仪功能。
• \[\]促进与任务管理器（Jira、Asana、Trello）的集成。
• \[\]创建一个多用途的命令行界面（CLI）。
• \[\]提高主页上可滚动本地存储库列表的可见性。

完成

• \[x\] 使用自定义异常、重试和恢复策略实施全面的错误处理。
• \[x\] 使用单元和集成测试创建测试基础架构。
• \[x\] 添加Makefile目标和测试运行器，以便于测试执行。
• \[x\] 存储库扫描期间的Honor.gitignore模式。
• \[x\] 在web UI中高效地流式传输扫描结果。
• \[x\] 确保多行显示的HTML转义正确。
• \[x\] 扩展TODO模式识别，以包括各种注释格式的FIXME、BUG和NOTE。
• \[x\] 修复服务器挂起问题：完成扫描后服务器不再无响应。
• \[x\] 跳过 scanner/repositories/ 当将此项目作为本地存储库扫描时，可以防止重复进入托管克隆存储库。

更新日志

v0.0.1--首次发布（2026-04-16）

• 通过CSV支持的密钥管理和登录/注销流程进行访问密钥认证
• 实时TODO计数徽章端点(/api/badge/todos/:repo)
• 通过SSE在web UI中流式传输扫描结果
• MCP-兼容API：清单、OpenAPI规范和 scan_repository 端点
• 扩展TODO模式识别： FIXME, BUG, NOTE 一起 TODO
• .gitignore-感知扫描；跳跃 scanner/repositories/ 在本地扫描中
• TodoScope品牌：命名、favicon、meta/OG标签、页脚生态系统链接
• 带有英雄副本、功能条和嵌入式演示GIF的登录页面
• 每个注册存储库的code.dev深度链接
• 具有自定义异常、重试和恢复策略的强大错误处理
• 带有Makefile运行器目标的单元和集成测试套件
• CapRover一键部署配置(caprover-one-click.yml)

许可证

版权所有©2025 Startr LLC。

根据GNU Affero通用公共许可证v3.0（AGPL-3.0）发布。

使用它。分享它。让它变得更好。但要保持开放。完整的许可证文本可在 LICENSE 文件。

贡献

强烈鼓励捐款！如果您有改进或修复错误的想法，请：

1. 分叉存储库。
2. 为您的功能或修复创建新分支。
3. 进行更改。
4. 提交一个拉取请求，明确描述您的更改。

让我们共同努力，使这个工具变得更好，并帮助保持我们的代码库干净易管理！