TaskFabric

TaskFabric

A file-based task manager operated entirely through an MCP server over Streamable HTTP. Every task is a markdown file with YAML frontmatter, indexed via QMD for hybrid semantic + keyword search, and git-synced for versioning. No UI — agents are the only interface.

How it works

Tasks live as plain markdown files organized by status:

/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)

Each task has YAML frontmatter (id, title, status, priority, tags, due, assignee, completed_at, waiting_on, dependencies) and a markdown body with free-form content and a ## Log section for timestamped entries. Filenames include the task ID to prevent collisions on duplicate titles.

Every mutation auto-commits to git and pushes to a remote, so all changes are versioned and recoverable.

MCP Tools

| Category | Tools | |----------|-------| | CRUD | task_create, task_get, task_update, task_delete, task_list | | Search | task_search (keyword/semantic/hybrid + filters), task_expand_query, task_structured_search | | Workflow | task_move, task_log, task_link, task_batch | | Views | task_dashboard, task_timeline, task_graph, task_summary, task_recent, task_completion_report | | Maintenance | task_auto_archive, task_reindex | | Sync | sync_status, sync_pull, sync_history, sync_diff, sync_restore | | Settings | settings_get, settings_update |

Setup

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | TASKS_DIR | Yes | Path to the tasks directory | | API_KEY | Yes | Bearer token for MCP authentication | | GIT_USER_NAME | Yes | Git commit author name | | GIT_USER_EMAIL | Yes | Git commit author email | | TASKS_REPO_URL | No | Git remote URL (clones on first start) | | GIT_TOKEN | No | GitHub PAT for private repos (fine-grained PAT with Contents read/write) | | PORT | No | Server port (default: 8181) |

Run locally

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

Run with Docker

Create a .env file:

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

The server starts at http://localhost:8181 with:

• /mcp — MCP endpoint (requires Authorization: Bearer <API_KEY>)
• /health — Health check (returns { "status": "ready" })

Connect MCP Clients

Claude Code (CLI)

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

Or add to .mcp.json in your project root:

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

Claude Desktop

Add to ~/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

Add to ~/.cursor/mcp.json:

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

OpenAI Codex CLI

Add to ~/.codex/config.toml:

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

Or use an environment variable for the token:

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

Tests

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

Stack

• Runtime: Bun
• MCP: @modelcontextprotocol/sdk (Streamable HTTP)
• Search: @tobilu/qmd (BM25 + vector + LLM re-ranking)
• Git: simple-git
• Frontmatter: gray-matter
• Validation: Zod