md-todo-hub

把本地多个项目里散落在 Markdown 中的待办项，索引成一个共享的小型数据库（SQLite），通过 MCP 提供给大模型使用：跨项目查进度、按优先级排下一步、把完成状态写回原文档。

Markdown 是唯一事实来源，索引只是查询层；所有写操作双写数据库与原文件。
支持表格行（| P1-1 | 标题 | 来源 | 影响 | ⏳ |）与清单（- [ ] 文本）两种格式。
索引库默认在 ~/.md-todo/index.db，可用 MD_TODO_HOME 改位置。

安装与启动（MCP）

# 直接运行 MCP server（stdio）
uvx --from md-todo-hub md-todo-hub

# 可选：启用语义检索 / 语义查重
uvx --from "md-todo-hub[semantic]" md-todo-hub

MCP 客户端配置示例：

{
  "mcpServers": {
    "md-todo-hub": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "md-todo-hub", "md-todo-hub"],
      "env": { "PYTHONUTF8": "1" }
    }
  }
}

命令行（同一套索引）

uvx --from md-todo-hub mdtodo register ~/project/foo   # 登记并索引一个项目
uvx --from md-todo-hub mdtodo overview                 # 跨项目进度总览
uvx --from md-todo-hub mdtodo next --limit 5           # 下一步该做什么
uvx --from md-todo-hub mdtodo search "登录"             # 全文检索
uvx --from md-todo-hub mdtodo status P1-1 done         # 标记完成（写回 Markdown）

主要 MCP 工具

工具	作用
`register_project` / `unregister_project` / `list_projects`	项目注册表
`index_projects`	增量 / 全量刷新索引
`get_overview`	跨项目进度仪表盘
`get_next_actions`	按优先级排序的待办队列
`search_all`	structured / fts / semantic / hybrid 检索
`locate_item`	定位 ID 所在项目与文件
`update_status`	改状态并双写 Markdown
`sync_from_md` / `reconcile`	Markdown 与索引对账

环境变量

变量	说明	默认值
`MD_TODO_HOME`	索引库目录	`~/.md-todo`
`MD_TODO_DOCS`	默认 Markdown 根目录	`<cwd>/docs`
`MD_TODO_LEGACY_DB`	设为 `1` 回到 v0.2 的单项目库模式	关闭
`EMBEDDING_API_KEY` / `EMBEDDING_BASE_URL` / `EMBEDDING_MODEL`	可选语义检索	未配置则用 FTS5

上架产物（dist/release）

包	文件	用途
连接器	`dist/release/md-todo-hub-connector-0.3.0.zip`	开放平台「连接器」类目上传
技能	`dist/release/md-todo-hub-skill-1.0.0.zip`	SkillHub 发布团队 Skill
专家	`dist/release/md-todo-steward-expert-1.0.0.zip`	开放平台「专家」类目上传

重新生成：bash scripts/build_release.sh（zip 顶层目录即包名，解压直接看到 .codebuddy-plugin/plugin.json）。

开发

python -m pytest docs_mcp/tests/ -v

MIT License.

Metadata

Release files for md-todo-hub 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for md-todo-hub 0.3.1
File	Size	Uploaded	Provenance
md_todo_hub-0.3.1.tar.gz	35.3 kB	Oct 22, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for md-todo-hub 0.3.1
File	Interpreter	ABI	Platform	Reset
md_todo_hub-0.3.1-py3-none-any.whl 43.5 kB Oct 22, 2026 Without provenance	Python 3	none	any	Details

Total release size: 78.8 kB

Release files / md_todo_hub-0.3.1.tar.gz

Download URL	md_todo_hub-0.3.1.tar.gz
Size	35.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`29cff102c82e9300a975a4e4f110b3d510c99ed2b8b332cf32ed5544231f605a`
BLAKE2b-256 checksum How to use checksums	`1d40dc1e7d1bbedeb52570cc9c869fe04b52e7b3429edf85daf7dc5705be8b66`
Upload date	Oct 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.13`

Release files / md_todo_hub-0.3.1-py3-none-any.whl

Download URL	md_todo_hub-0.3.1-py3-none-any.whl
Size	43.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`74ea412c5d3edf97896bd704d31f9b78f514d16ffe2d5566f511a998ad919ed6`
BLAKE2b-256 checksum How to use checksums	`a00779ba29aa31c5abdace422b1997670a36a8556f0b0242a10af4338a69d946`
Upload date	Oct 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.13`

Security for md-todo-hub 0.3.1

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.