AI导哈

文件任务管理器

基于Markdown文件和YAML前言的版本化任务管理系统，通过MCP服务器提供CRUD、搜索和工作流功能，无需用户界面。

  • by dlhck
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 dlhck/task-fabric

使用说明

TaskFabric

基于文件的任务管理器完全通过MCP服务器在Streamable HTTP上运行。每个任务都是一个带有YAML frontmatter的markdown文件，通过QMD进行索引，用于混合语义+关键字搜索，并同步git进行版本控制。没有UI——代理是唯一的接口。

运作原理

任务以按状态组织的普通标记文件的形式存在：

/tasks/
├── inbox/          # New, untriaged tasks
├── active/         # Currently being worked on
├── waiting/        # Blocked or waiting
├── done/2026-03/   # Completed (monthly subdirs)
└── archived/2026-03/ # Old tasks (monthly subdirs)

每个任务都有YAML frontmatter（id、标题、状态、优先级、标签、到期、受让人、completed_at、waiting_on、依赖关系）和一个带有自由格式内容和 ## Log 带有时间戳的条目部分。文件名包含任务ID，以防止重复标题的冲突。

每个变异都会自动提交到git并推送到远程，因此所有更改都是版本化和可恢复的。

MCP工具

类别 工具
增删改查 task_create, task_get, task_update, task_delete, task_list
搜索 task_search （关键字/语义/混合+过滤器）， task_expand_query, task_structured_search
工作流程 task_move, task_log, task_link, task_batch
视图 task_dashboard, task_timeline, task_graph, task_summary, task_recent, task_completion_report
维护 task_auto_archive, task_reindex
同步 sync_status, sync_pull, sync_history, sync_diff, sync_restore
设置 settings_get, settings_update

设置

环境变量

变量 必填 描述
TASKS_DIR 是 任务目录的路径
API_KEY 是 MCP身份验证的承载令牌
GIT_USER_NAME 是 Git提交作者姓名
GIT_USER_EMAIL 是 Git提交作者电子邮件
TASKS_REPO_URL 否 Git远程URL（首次启动时克隆）
GIT_TOKEN 否 私有仓库的GitHub PAT（具有内容读/写的细粒度PAT）
PORT 否 服务器端口（默认值：8181）

在本地运行

bun install
TASKS_DIR=./tasks API_KEY=your-secret GIT_USER_NAME="Your Name" GIT_USER_EMAIL="you@example.com" bun run src/server.ts

使用Docker运行

创建一个 .env 文件：

API_KEY=your-secret
GIT_USER_NAME=Your Name
GIT_USER_EMAIL=you@example.com
TASKS_REPO_URL=https://github.com/you/your-tasks-repo.git
GIT_TOKEN=ghp_your_github_pat

docker compose up --build

服务器启动于 http://localhost:8181 与：

  • /mcp --MCP端点（需要 Authorization: Bearer <API_KEY>)
  • /health --健康检查（退货 { "status": "ready" })

连接MCP客户端

克劳德代码（CLI）

claude mcp add --transport http task-fabric http://localhost:8181/mcp \
  --header "Authorization: Bearer your-secret"

或添加到 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "task-fabric": {
      "type": "http",
      "url": "http://localhost:8181/mcp",
      "headers": {
        "Authorization": "Bearer your-secret"
      }
    }
  }
}

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：

{
  "mcpServers": {
    "task-fabric": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8181/mcp",
        "--header",
        "Authorization: Bearer your-secret"
      ]
    }
  }
}

光标

添加 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "task-fabric": {
      "type": "streamable-http",
      "url": "http://localhost:8181/mcp",
      "headers": {
        "Authorization": "Bearer your-secret"
      }
    }
  }
}

OpenAI Codex命令行界面

添加 ~/.codex/config.toml:

[mcp_servers.task-fabric]
command = "http://localhost:8181/mcp"
http_headers = { "Authorization" = "Bearer your-secret" }

或者为令牌使用环境变量：

[mcp_servers.task-fabric]
command = "http://localhost:8181/mcp"
bearer_token_env_var = "TASK_FABRIC_API_KEY"

测试

bun test                          # All tests (159)
bun test src/__tests__/e2e/       # E2E tests (MCP protocol + HTTP)
bun test src/__tests__/tools/     # Integration tests

堆栈

  • 运行时：Bun
  • 主控程序: @modelcontextprotocol/sdk （流式HTTP）
  • 搜索: @tobilu/qmd （BM25+向量+LLM重新排名）
  • Git: simple-git
  • 前言: gray-matter
  • 验证：佐德

相关 MCP