Metadata-Version: 2.5
Name: md-todo-hub
Version: 0.3.0
Summary: Local cross-project todo index over markdown docs, exposed to LLMs via MCP
Project-URL: Homepage, https://github.com/daibou007/ai_my_notion
Project-URL: Repository, https://github.com/daibou007/ai_my_notion
Project-URL: Issues, https://github.com/daibou007/ai_my_notion/issues
Author-email: daibou007 <daibou007@163.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,llm,markdown,mcp,sqlite,todo
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: openai>=1.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: semantic
Requires-Dist: openai>=1.0; extra == 'semantic'
Description-Content-Type: text/markdown

# md-todo-hub

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

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

## 安装与启动（MCP）

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

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

MCP 客户端配置示例：

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

## 命令行（同一套索引）

```bash
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`）。

## 开发

```bash
python -m pytest docs_mcp/tests/ -v
```

MIT License.
