ws-mcp

ws-mcp

An MCP server that gives LLMs full visibility into your ws-cli workspace tree.

Ask your AI assistant things like:

• "What projects have I abandoned? Summarize where I left off on each one."
• "Which workspaces have uncommitted git changes?"
• "What tasks are open across all my ws/ projects?"*
• "Find everything I was working on related to authentication."

The server traverses your workspace tree, reads metadata, checks git status, parses saved browser tabs, reads beads task databases, and exposes it all through MCP tools — no state of its own.

Prerequisites

• Node.js >= 18
• ws-cli installed and configured (provides the workspace tree that this server reads)

Installation

git clone https://github.com/camggould/ws-mcp.git
cd ws-mcp
npm install

Registering with an MCP Client

Claude Code (per-project)

Add a .mcp.json file to any project directory:

{
  "mcpServers": {
    "ws-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ws-mcp/src/server.js"]
    }
  }
}

Claude Code (global)

claude mcp add --global ws-mcp node /absolute/path/to/ws-mcp/src/server.js

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ws-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ws-mcp/src/server.js"]
    }
  }
}

Any MCP-compatible client

ws-mcp uses stdio transport — pipe stdin/stdout to node src/server.js.

Tools

list_workspaces

List all workspaces with metadata. Filter by status, staleness, or tags.

| Parameter | Type | Description | |---|---|---| | status | string | Filter by status: active, paused, archived, abandoned | | stale_days | number | Only show workspaces not opened in this many days | | tags | string | Comma-separated tags to filter by (matches any) |

list_workspaces({})
list_workspaces({ status: "active" })
list_workspaces({ stale_days: 30, tags: "coding,research" })

Returns: Array of { name, status, last_opened, created, tags, path }.

---

get_workspace

Deep-dive into a single workspace. Returns everything the server knows.

| Parameter | Type | Description | |---|---|---| | name | string | Workspace name (e.g. "my-project" or "parent/child") |

get_workspace({ name: "ws/cli" })

Returns:

• meta — status, tags, created/last opened dates
• git — branch, dirty/clean, ahead/behind remote, modified/untracked/staged file counts
• tabs — saved browser tabs from last session (count + URLs)
• tab_history — session count, first/last session timestamps, unique URL count across all sessions
• beads — task tracker summary: total_issues, by_status counts, open_by_priority counts (or null if no beads database)
• days_since_opened / stale — staleness indicator (stale = 30+ days)
• notes — full workspace.md content

---

get_workspace_tree

Full parent-child hierarchy as a nested JSON tree. No parameters.

get_workspace_tree({})

Returns: Nested tree with { name, children[], meta?, path? } at each node.

---

find_stale_workspaces

Identify workspaces you may have forgotten about, sorted by most stale first.

| Parameter | Type | Default | Description | |---|---|---|---| | days | number | 14 | Days without activity to consider stale |

find_stale_workspaces({ days: 7 })

Returns: Array of { name, status, last_opened, days_since, tags }.

---

search_workspaces

Full-text search across workspace names, tags, workspace.md notes, and saved tab URLs.

| Parameter | Type | Description | |---|---|---| | query | string | Search query (case-insensitive substring match) |

search_workspaces({ query: "authentication" })

Returns: Array of { workspace, status, matches[] } where each match includes the field name and matching value/context.

---

summarize_all

High-level dashboard across all workspaces. No parameters.

summarize_all({})

Returns:

• total_workspaces — count
• by_status — breakdown ({ active: 3, paused: 1, ... })
• recently_active — workspaces opened in the last 7 days
• stale_30_plus_days — workspaces untouched for 30+ days

---

list_beads

List individual tasks from a workspace's beads issue tracker. Supports filtering and returns tasks sorted by priority then creation date.

| Parameter | Type | Default | Description | |---|---|---|---| | workspace | string | required | Workspace name (e.g. "betterlife" or "ws/mcp") | | status | string | | Filter: open, in_progress, blocked, closed | | priority | number | | Filter: 0=critical, 1=high, 2=normal, 3=low, 4=trivial | | type | string | | Filter: bug, feature, task, epic, chore | | label | string | | Filter by label (exact match) | | limit | number | 50 | Max issues to return (1–200) |

list_beads({ workspace: "betterlife" })
list_beads({ workspace: "betterlife", status: "open", priority: 1 })

Returns: { workspace, count, issues[] } where each issue includes id, title, description, status, priority, priority_label, type, assignee, labels[], created_at, updated_at.

---

get_beads_across_workspaces

Aggregate task counts across multiple workspaces. Scope to a parent prefix or query everything.

| Parameter | Type | Description | |---|---|---| | parent | string | Only include workspaces under this prefix (e.g. "ws" for ws/* workspaces). Omit for all. | | status | string | Only show workspaces that have at least one issue with this status |

get_beads_across_workspaces({})
get_beads_across_workspaces({ parent: "ws" })
get_beads_across_workspaces({ status: "open" })

Returns:

• aggregate — total_open, workspaces_with_beads, by_status counts, open_by_priority counts
• workspaces[] — per-workspace breakdown with by_status, open_by_priority, open_total (sorted by most open issues first)

How It Works

┌──────────────┐     stdio      ┌──────────┐     reads      ┌──────────────────┐
│  MCP Client  │ ◄────────────► │  ws-mcp  │ ──────────────► │  ~/Workspaces/   │
│  (Claude,    │   JSON-RPC     │  server  │                 │  .workspace.yaml │
│   Cursor,    │                │          │                 │  tabs.json       │
│   etc.)      │                │          │                 │  tabs-history.jsonl│
└──────────────┘                └──────────┘                 │  workspace.md    │
                                     │                       │  .beads/beads.db │
│  .git/           │
                                     ▼                       └──────────────────┘
                              ~/.config/ws/
                              config.json

1. Reads ~/.config/ws/config.json to find the workspaces root (defaults to ~/Workspaces)
2. Recursively walks the directory tree, following symlinks, looking for .workspace.yaml marker files
3. Parses workspace metadata (YAML), saved tabs (tabs.json), tab history (tabs-history.jsonl), and notes (workspace.md)
4. Reads beads SQLite databases (.beads/beads.db) in read-only mode for task counts and issue listings
5. Runs git status on workspaces that are git repos (via simple-git)
6. Exposes everything through MCP tools over stdio transport

The server is stateless — it reads directly from the filesystem that ws-cli manages. No database, no cache, no background processes.

Development

# Run with auto-reload on file changes
npm run dev

# Run directly
npm start

Dependencies

| Package | Purpose | |---|---| | @modelcontextprotocol/sdk | MCP server framework | | better-sqlite3 | Read-only access to beads task databases | | simple-git | Git status checks | | js-yaml | Workspace metadata parsing | | fast-glob | File pattern matching | | zod | Tool parameter validation |

Related

• ws-cli — the CLI tool that creates and manages the workspace tree this server reads

License

MIT