Bureau MCP Server

A Model Context Protocol (MCP) server that helps AI agents reliably manage task-based report files with automatic sequential numbering and consistent directory organization.

Why Bureau?

When using AI subagents for complex workflows, it's useful to have them maintain reports in a structured directory like this:

.tasks/
├── current -> 2025-10-01-implement-feature
├── 2025-10-01-implement-feature/
│   ├── 001-user-request.md
│   ├── 002-plan.md
│   ├── 003-implementation.md
│   └── 004-tests.md
├── 2025-10-01b-fix-bug/
│   ├── 001-bug-report.md
│   └── 002-fix.md
└── 2025-10-02-refactor/
    ├── 001-analysis.md
    └── 002-plan.md

However, AI agents struggle to maintain consistent file numbering and folder organization when managing multi-step tasks. They often:

• Mess up sequential numbering
• Switch to new folders unexpectedly
• Lose track of which task is current

Bureau solves this by managing the directory structure and file numbering, while letting agents focus on reading and writing content.

Features

• Automatic Task Directory Management - Creates dated task folders with automatic suffix handling (2025-10-01, 2025-10-01b, 2025-10-01c, etc.)
• Bureau Dir Auto-Detection - Detects .tasks, _tasks, .reports, or _reports, and defaults to .tasks
• Sequential Report Numbering - Generates next available report file numbers automatically
• Current Task Tracking - Maintains a current symlink pointing to the active task
• Smart File Listing - Returns all files if <50, or earliest 20 + latest 30 for efficiency
• Recent Tasks - Lists tasks from the last 60 days, backfilled to at least 30 task directories when available
• Minimal Dependencies - Built with only essential packages

Installation

Using with Claude Code

Option 1: CLI (recommended)

claude mcp add-json bureau '{"command":"npx","args":["-y","bureau-mcp"]}' --scope user

Option 2: Manual configuration

Edit ~/.claude.json:

{
  "mcpServers": {
    "bureau": {
      "command": "npx",
      "args": ["-y", "bureau-mcp"]
    }
  }
}

Using with Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bureau": {
      "command": "npx",
      "args": ["-y", "bureau-mcp"]
    }
  }
}

Local Development

git clone https://github.com/andreyvit/bureau-mcp.git
cd bureau-mcp
npm install

Then configure with the full path:

{
  "mcpServers": {
    "bureau": {
      "command": "node",
      "args": ["/path/to/bureau-mcp/index.js"]
    }
  }
}

Available Tools

current_task

Returns information about the current task.

Returns:

{
  "task_slug": "implement-feature",
  "task_dir": "2025-10-01-implement-feature",
  "reports_dir": ".tasks/2025-10-01-implement-feature",
  "report_file_names": ["001-user-request.md", "002-plan.md"]
}

start_new_task

Creates a new task directory and makes it current.

Parameters:

• task_slug (string): Slug for the task (e.g., "implement-feature")

Returns: Same format as current_task()

switch_task

Switches to an existing task by full task dir or by slug.

Parameters:

• task_dir (string, optional): Full task directory name to switch to
• task_slug (string, optional): Slug of the task to switch to

Returns: Same format as current_task()

list_recent_tasks

Lists tasks from the last 60 days, backfilled to at least 30 task directories when available.

Returns:

{
  "recent_task_dirs": ["2025-10-01-implement-feature", "2025-10-01b-fix-bug"],
  "recent_task_slugs": ["implement-feature", "fix-bug"]
}

start_new_report_file

Returns the name of the next sequentially numbered report file; create or touch this file before calling again to avoid duplicate numbers.

Parameters:

• suffix (string): Suffix for the report file (e.g., "code-review")

Returns:

{
  "report_file_to_create": ".tasks/2025-10-01-implement-feature/003-code-review.md"
}

Typical Workflow

1. Agent starts a new task:

   • Calls start_new_task({task_slug: "implement-feature"})
   • Gets back the task directory path

2. Agent creates initial report:

   • Calls start_new_report_file({suffix: "user-request"})
   • Writes content to the returned filepath

3. Agent continues work:

   • Calls current_task() to see existing reports
   • Reads report files as needed
   • Calls start_new_report_file() for new reports
   • Writes new content

4. Agent switches between tasks:

   • Calls list_recent_tasks() to see recent task directories
   • Calls switch_task({task_dir: "2025-10-01b-fix-bug"}) or switch_task({task_slug: "fix-bug"})

Task Directory Naming

Task directories follow the pattern: YYYY-MM-DDn-slug-slug-slug

• First task of the day: 2025-10-01-first-task
• Second task same day: 2025-10-01b-second-task
• Third task same day: 2025-10-01c-third-task
• ...continuing through y: 2025-10-01y-task-25
• 26th+ tasks use numeric suffix: 2025-10-01z026-task-26, 2025-10-01z027-task-27, etc.
• Up to 1000 tasks per day

Bureau Dir Selection

By default, Bureau auto-detects an existing tasks dir in this order:

• .tasks
• _tasks
• .reports
• _reports

If more than one exists, Bureau prefers the one that already has a current symlink and existing task directories. You can override auto-detection by setting BUREAU_DIR to a relative or absolute path before starting the server.

Development

Run tests:

npm test

Start server locally:

npm start

The server uses Node.js built-in test runner and memfs for filesystem mocking in tests.

Requirements

• Node.js >= 18.0.0

License

MIT

Contributing

Contributions welcome! Please open an issue or submit a pull request.

Repository

https://github.com/andreyvit/bureau-mcp