md-todo-hub 0.3.0__tar.gz

md_todo_hub-0.3.0/.gitignore

@@ -0,0 +1,17 @@
+# docs-mcp database
+.docs-mcp/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/*
+!dist/assets/
+!dist/skill/
+!dist/connector/
+!dist/expert/
+!dist/release/
+build/
+build_pkg/
+.pypirc

md_todo_hub-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 daibou007
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

md_todo_hub-0.3.0/PKG-INFO

@@ -0,0 +1,115 @@
+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.

md_todo_hub-0.3.0/README.md

@@ -0,0 +1,83 @@
+# 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.

md_todo_hub-0.3.0/docs_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""md-todo-hub: a local cross-project todo index over markdown docs."""
+
+__version__ = "0.3.0"

md_todo_hub-0.3.0/docs_mcp/__main__.py

@@ -0,0 +1,33 @@
+"""Entry point: python -m docs_mcp / md-todo-hub（MCP stdio server）"""
+
+import sys
+
+from .server import mcp
+
+
+def main():
+    argv = sys.argv[1:]
+    # MCP 客户端不传参数；手动敲命令时给个友好提示，避免看起来"卡住"
+    if any(a in ("-h", "--help") for a in argv):
+        print(
+            "md-todo-hub — 跨项目 Markdown 待办索引（MCP stdio server）\n\n"
+            "用法：\n"
+            "  md-todo-hub                 启动 MCP stdio server（供 MCP 客户端调用）\n"
+            "  md-todo-hub --version       打印版本\n"
+            "  mdtodo --help               命令行用法（register / overview / next / search）\n\n"
+            "该命令本身不输出内容，需由 MCP 客户端拉起；\n"
+            "若想直接在终端操作，请用 mdtodo：uvx --from md-todo-hub mdtodo --help"
+        )
+        return 0
+    if any(a in ("-V", "--version") for a in argv):
+        from . import __version__
+
+        print(f"md-todo-hub {__version__}")
+        return 0
+
+    mcp.run(transport="stdio")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

md_todo_hub-0.3.0/docs_mcp/cli.py

@@ -0,0 +1,264 @@
+"""Command line interface for md-todo-hub.
+
+The MCP server is the primary interface for agents, but a CLI keeps the same
+index usable from a terminal, a shell script, or a skill that runs without an
+MCP connection.
+
+    mdtodo register ~/project/foo
+    mdtodo index
+    mdtodo overview
+    mdtodo next --limit 5
+    mdtodo done P1-1 --project foo
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import Config
+from .db import TodoDB
+from .projects import (
+    index_all,
+    index_project,
+    locate_item,
+    next_actions,
+    overview,
+    register_project,
+    unregister_project,
+)
+from .search import search_todos
+from .sync import update_todo_status
+
+
+def _db() -> TodoDB:
+    return TodoDB(Config.default())
+
+
+def _print_table(headers: list[str], rows: list[list[str]]) -> None:
+    if not rows:
+        print("(empty)")
+        return
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], len(str(cell)))
+    line = "  ".join(h.ljust(widths[i]) for i, h in enumerate(headers))
+    print(line)
+    print("  ".join("-" * w for w in widths))
+    for row in rows:
+        print("  ".join(str(c).ljust(widths[i]) for i, c in enumerate(row)))
+
+
+def cmd_register(args: argparse.Namespace) -> int:
+    db = _db()
+    try:
+        project = register_project(db, args.path, name=args.name, docs_dir=args.docs)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    result = index_project(db, project)
+    print(f"registered {project.name} -> {project.docs_dir}")
+    print(f"indexed {result['parsed']} items from {result['files']} files")
+    return 0
+
+
+def cmd_unregister(args: argparse.Namespace) -> int:
+    db = _db()
+    if not unregister_project(db, args.project):
+        print(f"error: project not registered: {args.project}", file=sys.stderr)
+        return 1
+    print(f"removed {args.project}")
+    return 0
+
+
+def cmd_index(args: argparse.Namespace) -> int:
+    db = _db()
+    if args.project:
+        project = db.get_project(args.project)
+        if project is None:
+            print(f"error: project not registered: {args.project}", file=sys.stderr)
+            return 1
+        result = index_project(db, project, incremental=not args.full)
+        print(f"{result['project']}: parsed {result['parsed']}, "
+              f"files {result['files_changed']}/{result['files']}, "
+              f"removed {result['removed']}")
+        return 0
+
+    result = index_all(db, incremental=not args.full)
+    print(f"{result['projects']} projects, {result['parsed']} items")
+    for item in result["results"]:
+        print(f"  {item.get('project')}: parsed {item.get('parsed', 0)}")
+    return 0
+
+
+def cmd_projects(args: argparse.Namespace) -> int:
+    db = _db()
+    rows = [[p.name, p.path, p.docs_dir, p.last_indexed or "-"] for p in db.list_projects()]
+    _print_table(["project", "path", "docs_dir", "last_indexed"], rows)
+    return 0
+
+
+def cmd_overview(args: argparse.Namespace) -> int:
+    db = _db()
+    data = overview(db)
+    if args.json:
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+        return 0
+
+    rows = []
+    for p in data["projects"]:
+        flag = "" if p["exists"] else " (missing)"
+        rows.append([p["name"] + flag, p["pending"], p["done"], p["total"], p["path"]])
+    totals = data["totals"]
+    rows.append(["TOTAL", totals["pending"], totals["done"], totals["items"], ""])
+    _print_table(["project", "pending", "done", "total", "path"], rows)
+
+    if data["inconsistencies"]:
+        print()
+        print(f"{len(data['inconsistencies'])} inconsistency(ies) found:")
+        for issue in data["inconsistencies"]:
+            print(f"  - {issue}")
+    return 0
+
+
+def cmd_next(args: argparse.Namespace) -> int:
+    db = _db()
+    actions = next_actions(db, limit=args.limit, project=args.project, priority=args.priority)
+    if args.json:
+        print(json.dumps(actions, ensure_ascii=False, indent=2))
+        return 0
+    rows = [
+        [a["project"], a["priority"], a["id"], a["title"], f"{a['file']}:{a['line']}"]
+        for a in actions
+    ]
+    _print_table(["project", "pri", "id", "title", "location"], rows)
+    return 0
+
+
+def cmd_search(args: argparse.Namespace) -> int:
+    db = _db()
+    items = search_todos(
+        db, query=args.query, mode=args.mode, status=args.status,
+        priority=args.priority, project=args.project, limit=args.limit,
+    )
+    if args.json:
+        print(json.dumps([i.to_dict() for i in items], ensure_ascii=False, indent=2))
+        return 0
+    rows = [
+        [i.project, i.priority, i.id, i.status, i.title, f"{i.file}:{i.line_start}"]
+        for i in items
+    ]
+    _print_table(["project", "pri", "id", "status", "title", "location"], rows)
+    return 0
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    db = _db()
+    locations = locate_item(db, args.item_id)
+    if not locations:
+        print(f"error: item not found: {args.item_id}", file=sys.stderr)
+        return 1
+    for loc in locations:
+        project = db.get_project(loc["project"])
+        base = Path(project.docs_dir) if project else Path(".")
+        print(f"{loc['project']}  {loc['status']}  {base / loc['file']}")
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    db = _db()
+    locations = locate_item(db, args.item_id)
+    if not locations:
+        print(f"error: item not found: {args.item_id}", file=sys.stderr)
+        return 1
+    if args.project is None and len({loc["project"] for loc in locations}) > 1:
+        print("error: item id exists in several projects, pass --project", file=sys.stderr)
+        for loc in locations:
+            print(f"  {loc['project']} ({loc['status']})", file=sys.stderr)
+        return 1
+    project = args.project or locations[0]["project"]
+    row = db.get_project(project)
+    docs_dir = Path(row.docs_dir) if row else Path(args.docs).resolve()
+    result = update_todo_status(db, docs_dir, args.item_id, args.new_status, project=project)
+    if not result.affected_files:
+        print("nothing updated (item not found in markdown)", file=sys.stderr)
+        return 1
+    print(f"{args.item_id} -> {args.new_status} "
+          f"({result.total_replacements} line(s) in {', '.join(result.affected_files)})")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mdtodo",
+        description="Local cross-project todo index over markdown docs.",
+    )
+    parser.add_argument("--version", action="version", version=f"md-todo-hub {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("register", help="register a project and index it")
+    p.add_argument("path")
+    p.add_argument("--name")
+    p.add_argument("--docs", help="markdown root (default: <path>/docs)")
+    p.set_defaults(func=cmd_register)
+
+    p = sub.add_parser("unregister", help="drop a project from the index")
+    p.add_argument("project")
+    p.set_defaults(func=cmd_unregister)
+
+    p = sub.add_parser("index", help="refresh the index")
+    p.add_argument("--project")
+    p.add_argument("--full", action="store_true", help="re-parse everything")
+    p.set_defaults(func=cmd_index)
+
+    p = sub.add_parser("projects", help="list registered projects")
+    p.set_defaults(func=cmd_projects)
+
+    p = sub.add_parser("overview", help="per-project progress dashboard")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_overview)
+
+    p = sub.add_parser("next", help="pending todos ordered by priority")
+    p.add_argument("--limit", type=int, default=10)
+    p.add_argument("--project")
+    p.add_argument("--priority")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_next)
+
+    p = sub.add_parser("search", help="search todos")
+    p.add_argument("query", nargs="?", default=None)
+    p.add_argument("--mode", default="hybrid",
+                   choices=["structured", "fts", "semantic", "hybrid"])
+    p.add_argument("--project")
+    p.add_argument("--status")
+    p.add_argument("--priority")
+    p.add_argument("--limit", type=int, default=20)
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_search)
+
+    p = sub.add_parser("show", help="show where an item lives")
+    p.add_argument("item_id")
+    p.set_defaults(func=cmd_show)
+
+    p = sub.add_parser("status", help="set an item's status (dual-writes markdown)")
+    p.add_argument("item_id")
+    p.add_argument("new_status", choices=["done", "pending", "wontfix"])
+    p.add_argument("--project")
+    p.add_argument("--docs", default="./docs")
+    p.set_defaults(func=cmd_status)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

md_todo_hub-0.3.0/docs_mcp/config.py

@@ -0,0 +1,111 @@
+"""Configuration for docs-mcp.
+
+Two storage modes are supported:
+
+1. Hub mode (default, v0.3+): a single global index database shared by every
+   registered local project, located at ``$MD_TODO_HOME/index.db``
+   (default ``~/.md-todo/index.db``). Each todo row carries a ``project``
+   dimension so cross-project search and aggregation work out of the box.
+
+2. Legacy mode: a per-project database at ``<project>/.docs-todo-mcp/todos.db``.
+   Still honoured when ``MD_TODO_LEGACY_DB=1`` is set or when an explicit
+   ``db_path`` is passed in.
+"""
+
+import os
+from pathlib import Path
+from dataclasses import dataclass, field
+
+
+DEFAULT_HOME_DIRNAME = ".md-todo"
+
+
+def _home_dir() -> Path:
+    """Resolve the hub directory."""
+    env = os.environ.get("MD_TODO_HOME")
+    if env:
+        return Path(env).expanduser().resolve()
+    return Path.home() / DEFAULT_HOME_DIRNAME
+
+
+def _guess_project_name(path: Path) -> str:
+    """Derive a stable project key from an absolute path."""
+    return path.name or "default"
+
+
+@dataclass
+class Config:
+    docs_dir: Path
+    db_path: Path
+    project: str = "default"
+    project_root: Path | None = None
+    embedding_model: str = field(default="text-embedding-3-small")
+    embedding_dim: int = 1536
+    embedding_base_url: str = field(default="")
+    embedding_api_key: str = field(default="")
+
+    def __post_init__(self):
+        """Override with environment variables if set."""
+        # Support any OpenAI-compatible embedding endpoint
+        if os.environ.get("EMBEDDING_MODEL"):
+            self.embedding_model = os.environ["EMBEDDING_MODEL"]
+        if os.environ.get("EMBEDDING_DIM"):
+            self.embedding_dim = int(os.environ["EMBEDDING_DIM"])
+        if os.environ.get("EMBEDDING_BASE_URL"):
+            self.embedding_base_url = os.environ["EMBEDDING_BASE_URL"]
+        if os.environ.get("EMBEDDING_API_KEY"):
+            self.embedding_api_key = os.environ["EMBEDDING_API_KEY"]
+        # Backward compat: OPENAI_BASE_URL / OPENAI_API_KEY
+        if not self.embedding_base_url and os.environ.get("OPENAI_BASE_URL"):
+            self.embedding_base_url = os.environ["OPENAI_BASE_URL"]
+        if not self.embedding_api_key and os.environ.get("OPENAI_API_KEY"):
+            self.embedding_api_key = os.environ["OPENAI_API_KEY"]
+        if os.environ.get("MD_TODO_PROJECT"):
+            self.project = os.environ["MD_TODO_PROJECT"]
+
+    @classmethod
+    def default(cls) -> "Config":
+        """Hub-mode config anchored at the current working directory."""
+        project_root = Path.cwd().resolve()
+        docs_env = os.environ.get("MD_TODO_DOCS")
+        docs_dir = Path(docs_env).expanduser().resolve() if docs_env else project_root / "docs"
+        if os.environ.get("MD_TODO_LEGACY_DB") == "1":
+            return cls(
+                docs_dir=docs_dir,
+                db_path=project_root / ".docs-todo-mcp" / "todos.db",
+                project=_guess_project_name(project_root),
+                project_root=project_root,
+            )
+        return cls(
+            docs_dir=docs_dir,
+            db_path=_home_dir() / "index.db",
+            project=_guess_project_name(project_root),
+            project_root=project_root,
+        )
+
+    @classmethod
+    def for_project(
+        cls,
+        path: str | Path,
+        docs_dir: str | Path | None = None,
+        name: str | None = None,
+    ) -> "Config":
+        """Build a hub-mode config for one registered project."""
+        root = Path(path).expanduser().resolve()
+        docs = Path(docs_dir).expanduser().resolve() if docs_dir else root / "docs"
+        return cls(
+            docs_dir=docs,
+            db_path=_home_dir() / "index.db",
+            project=name or _guess_project_name(root),
+            project_root=root,
+        )
+
+    @property
+    def home_dir(self) -> Path:
+        """Hub directory that owns the shared index database."""
+        return self.db_path.parent
+
+    @property
+    def is_hub_mode(self) -> bool:
+        """True when using the shared cross-project index."""
+        return self.db_path.name == "index.db"