b0211e5e08
- Updated README to clarify that the app runs entirely locally and added a comprehensive table of contents. - Enhanced the description of the Claude Agent Teams UI to better convey its functionality and target audience. - Improved the SortableTab component to ensure immediate rendering of team colors based on available data. - Filtered out team lead members in the TeamDetailView to streamline member display. - Eagerly patched team data in the state management to improve UI responsiveness and data accuracy.
301 lines
9.4 KiB
Markdown
301 lines
9.4 KiB
Markdown
# @claude-team/mcp-server
|
||
|
||
**Model Context Protocol (MCP) server for managing Claude Agent Teams kanban board and tasks.**
|
||
|
||
Exposes 13 tools so AI agents (Claude, Cursor, or any MCP-compatible client) can create tasks, manage the kanban board, conduct code reviews, and send messages — backed by the same `teamctl.js` CLI that powers the Claude Agent Teams UI desktop app.
|
||
|
||
---
|
||
|
||
## Table of Contents
|
||
|
||
- [Overview](#overview)
|
||
- [Relationship to Claude Agent Teams UI](#relationship-to-claude-agent-teams-ui)
|
||
- [Quick start](#quick-start)
|
||
- [Prerequisites](#prerequisites)
|
||
- [Installation](#installation)
|
||
- [Configuration](#configuration)
|
||
- [Tools Reference](#tools-reference)
|
||
- [Data Storage](#data-storage)
|
||
- [Development](#development)
|
||
- [Testing](#testing)
|
||
- [Troubleshooting](#troubleshooting)
|
||
- [License](#license)
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
Implements the [Model Context Protocol](https://modelcontextprotocol.io/) over **stdio**. All operations are delegated to `teamctl.js`, which:
|
||
|
||
- Stores task data as JSON under `~/.claude/tasks/{teamName}/`
|
||
- Stores team config under `~/.claude/teams/{teamName}/`
|
||
- Is installed automatically when you run Claude Agent Teams UI at least once
|
||
|
||
### Use cases
|
||
|
||
| Scenario | Description |
|
||
|----------|-------------|
|
||
| **Cursor / Claude Desktop** | Add the server to MCP config so AI assistants can create tasks, assign owners, move cards, and send messages without leaving the chat |
|
||
| **Automation scripts** | Programmatic interface to the same task board that Claude Code agents use |
|
||
| **Multi-agent workflows** | Multiple AI agents sharing one task board, coordinating via comments and messages |
|
||
|
||
### Architecture
|
||
|
||
```
|
||
┌─────────────────────┐ stdio ┌──────────────────────┐ spawn ┌─────────────────┐
|
||
│ MCP Client │ ◄────────────► │ @claude-team/ │ ◄────────────► │ teamctl.js │
|
||
│ (Cursor, Claude, │ │ mcp-server │ │ ~/.claude/ │
|
||
│ custom scripts) │ │ (FastMCP + 13 tools) │ │ tools/ │
|
||
└─────────────────────┘ └──────────────────────┘ └─────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Relationship to Claude Agent Teams UI
|
||
|
||
| Component | Role |
|
||
|-----------|------|
|
||
| **Claude Agent Teams UI** | Desktop app (Electron). Visualizes sessions, kanban board, code review, team messaging. Installs `teamctl.js` on first run. |
|
||
| **teamctl.js** | CLI at `~/.claude/tools/teamctl.js`. Reads/writes task JSON, manages kanban, inboxes, reviews. Used by both the app and agents. |
|
||
| **@claude-team/mcp-server** | MCP server wrapping `teamctl.js` so Cursor, Claude Desktop, and other MCP clients can call the same operations as tools. |
|
||
|
||
Agents in Claude Code use `teamctl.js` via Bash. Agents in Cursor or Claude Desktop use this MCP server. Both operate on the same data.
|
||
|
||
---
|
||
|
||
## Quick start
|
||
|
||
1. Run **Claude Agent Teams UI** at least once (installs `teamctl.js`)
|
||
2. Build the MCP server: `cd mcp-server && pnpm install && pnpm build`
|
||
3. Add to Cursor MCP config (`~/.cursor/mcp.json`):
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"claude-team-tools": {
|
||
"command": "node",
|
||
"args": ["/absolute/path/to/claude_agent_teams_ui/mcp-server/dist/index.js"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
4. Restart Cursor. The 13 tools will appear for the AI assistant.
|
||
|
||
---
|
||
|
||
## Prerequisites
|
||
|
||
- **Node.js 20+**
|
||
- **Claude Agent Teams UI** run at least once (installs `teamctl.js` to `~/.claude/tools/teamctl.js`)
|
||
|
||
If `teamctl.js` is missing, the server throws at startup:
|
||
|
||
```
|
||
teamctl.js not found at ~/.claude/tools/teamctl.js.
|
||
Make sure Claude Agent Teams UI has been run at least once,
|
||
or set the TEAMCTL_PATH environment variable.
|
||
```
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
### From the monorepo (development)
|
||
|
||
```bash
|
||
cd mcp-server
|
||
pnpm install
|
||
pnpm build
|
||
```
|
||
|
||
### As a dependency
|
||
|
||
```bash
|
||
pnpm add @claude-team/mcp-server
|
||
# or
|
||
npm install @claude-team/mcp-server
|
||
```
|
||
|
||
---
|
||
|
||
## Configuration
|
||
|
||
### Cursor
|
||
|
||
Add to `~/.cursor/mcp.json` or project `.cursor/mcp.json`:
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"claude-team-tools": {
|
||
"command": "node",
|
||
"args": ["/path/to/claude_agent_teams_ui/mcp-server/dist/index.js"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
With global install (`pnpm link` or `npm link`):
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"claude-team-tools": {
|
||
"command": "team-mcp-server"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Claude Desktop
|
||
|
||
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or equivalent:
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"claude-team-tools": {
|
||
"command": "node",
|
||
"args": ["/absolute/path/to/mcp-server/dist/index.js"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Environment variables
|
||
|
||
| Variable | Description |
|
||
|----------|-------------|
|
||
| `TEAMCTL_PATH` | Path to `teamctl.js` if not at `~/.claude/tools/teamctl.js` |
|
||
|
||
---
|
||
|
||
## Tools Reference
|
||
|
||
All tools require a `team` parameter (team name, folder under `~/.claude/teams/`).
|
||
|
||
### Task CRUD
|
||
|
||
| Tool | Description |
|
||
|------|-------------|
|
||
| `task_create` | Create a task. Optional: `owner`, `description`, `blocked_by`, `related`, `status`, `notify`, `from` |
|
||
| `task_get` | Get a task by ID. Returns full JSON (status, owner, comments, dependencies, work intervals, history) |
|
||
| `task_list` | List all tasks. Returns JSON array (filter internal tasks client-side if needed) |
|
||
| `task_set_status` | Set status: `pending` → `in_progress` → `completed` → `deleted`. Records work intervals |
|
||
| `task_set_owner` | Assign or unassign owner. Use `owner="clear"` to unassign. Optional: `notify`, `from` |
|
||
|
||
### Task collaboration
|
||
|
||
| Tool | Description |
|
||
|------|-------------|
|
||
| `task_comment` | Add a comment. Sends inbox notification to owner (unless commenter is owner). Optional: `from` |
|
||
| `task_link` | Link/unlink dependencies. Types: `blocked-by`, `blocks`, `related`. Bidirectional; circular deps rejected |
|
||
| `task_briefing` | Human-readable briefing for a member: their assigned tasks vs full board |
|
||
| `task_attach` | Attach a file. Modes: `copy`, `link`. MIME auto-detected (PNG, JPEG, GIF, WebP, PDF, ZIP). Max 20 MB |
|
||
|
||
### Kanban board
|
||
|
||
| Tool | Description |
|
||
|------|-------------|
|
||
| `kanban_move` | Move to `review` or `approved`, or `clear` from board. Moving to column sets status to `completed` |
|
||
| `kanban_reviewers` | Manage reviewers: `list` (JSON array), `add`, `remove` |
|
||
|
||
### Code review
|
||
|
||
| Tool | Description |
|
||
|------|-------------|
|
||
| `review_action` | `approve` — mark approved (optional comment, `notify_owner`). `request-changes` — remove from kanban, reset to `in_progress`, notify owner (comment required) |
|
||
|
||
### Messaging
|
||
|
||
| Tool | Description |
|
||
|------|-------------|
|
||
| `message_send` | Send inbox message to a member. Optional: `summary`, `from`. Triggers notifications |
|
||
|
||
---
|
||
|
||
## Data Storage
|
||
|
||
| Location | Contents |
|
||
|----------|----------|
|
||
| `~/.claude/tasks/{teamName}/` | Task JSON files (`1.json`, `2.json`, …) |
|
||
| `~/.claude/teams/{teamName}/` | Team config, kanban reviewers, inboxes |
|
||
|
||
Task IDs are numeric (highwatermark). Team and member names must be safe path segments (no `.`, `..`, `/`, `\`, null bytes).
|
||
|
||
---
|
||
|
||
## Development
|
||
|
||
### Scripts
|
||
|
||
| Command | Description |
|
||
|---------|-------------|
|
||
| `pnpm build` | Build with tsup → `dist/index.js` |
|
||
| `pnpm dev` | Run with tsx (no build) |
|
||
| `pnpm test` | Run Vitest tests |
|
||
| `pnpm test:watch` | Watch mode |
|
||
| `pnpm typecheck` | TypeScript check |
|
||
|
||
### Project structure
|
||
|
||
```
|
||
mcp-server/
|
||
├── src/
|
||
│ ├── index.ts # FastMCP server, registers all tools
|
||
│ ├── teamctl-runner.ts # Spawns teamctl.js subprocess
|
||
│ ├── output-parser.ts # Parses JSON / "OK ..." from teamctl stdout
|
||
│ ├── schemas.ts # Zod schemas (team, taskId, member, etc.)
|
||
│ └── tools/
|
||
│ ├── index.ts # registerAllTools()
|
||
│ ├── task-create.ts
|
||
│ ├── task-get.ts
|
||
│ ├── ...
|
||
│ └── message-send.ts
|
||
├── test/
|
||
│ ├── tools/ # Per-tool tests
|
||
│ ├── teamctl-runner.test.ts
|
||
│ ├── output-parser.test.ts
|
||
│ └── schemas.test.ts
|
||
├── package.json
|
||
├── tsup.config.ts
|
||
└── vitest.config.ts
|
||
```
|
||
|
||
### Adding a new tool
|
||
|
||
1. Create `src/tools/your-tool.ts` with `register(server, runner)`
|
||
2. Add to `ALL_TOOLS` in `src/tools/index.ts`
|
||
3. Add Zod parameters and map to `teamctl` CLI args
|
||
4. Use `parseJsonOutput`, `parseOkOutput`, or `parseTextOutput` from `output-parser.ts`
|
||
5. Add tests in `test/tools/your-tool.test.ts`
|
||
|
||
---
|
||
|
||
## Testing
|
||
|
||
Tests use a mock `ITeamctlRunner` (no real `teamctl.js` required):
|
||
|
||
```bash
|
||
pnpm test
|
||
```
|
||
|
||
For integration tests with real `teamctl.js`, use the main app: `test/main/services/team/teamctl.test.ts`.
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
| Issue | Solution |
|
||
|-------|----------|
|
||
| **teamctl.js not found** | Run Claude Agent Teams UI at least once, or set `TEAMCTL_PATH` |
|
||
| **Invalid team/member name** | Names: 1–128 chars, no `.`, `..`, `/`, `\`, null bytes |
|
||
| **MCP client not discovering tools** | Check server starts without errors; use absolute path in config; some clients require it |
|
||
| **Timeout errors** | Default 10s. Increase via `TeamctlRunnerOptions.timeoutMs` (code change) |
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
Same as the parent project: [AGPL-3.0](../LICENSE).
|