# Threads MCP Server

MCP server exposing Threads CLI data and operations via the Model Context Protocol.

## Installation

```bash
cd threads-mcp
npm install
npm run build
```

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "threads": {
      "command": "node",
      "args": ["C:/Users/joshu/Desktop/threads-mcp/dist/server.js"]
    }
  }
}
```

### Development

```bash
npm run dev        # Run with tsx (no build needed)
npm run build      # Compile TypeScript
npm run start      # Run compiled version
npm run typecheck  # Type check only
```

### Testing with MCP Inspector

```bash
npx @modelcontextprotocol/inspector node dist/server.js
```

## Resources

| URI | Description |
|-----|-------------|
| `threads://threads/list` | All threads |
| `threads://threads/active` | Active threads only |
| `threads://threads/hot` | Hot/warm temperature threads |
| `threads://threads/{id}` | Single thread by ID |
| `threads://containers/list` | All containers |
| `threads://containers/{id}` | Single container by ID |
| `threads://groups/list` | All groups |
| `threads://groups/{id}` | Single group by ID |
| `threads://groups/{id}/members` | Entities in a group |
| `threads://tree` | Full hierarchy tree |
| `threads://next` | Suggested next action |
| `threads://progress/{threadId}` | Progress log for a thread |

## Tools

### Thread Management

| Tool | Description |
|------|-------------|
| `create_thread` | Create a new thread |
| `update_thread` | Update thread properties |
| `archive_thread` | Archive a thread (with optional cascade) |
| `delete_thread` | Permanently delete a thread |
| `get_thread` | Get thread by ID or name |

### Progress Tracking

| Tool | Description |
|------|-------------|
| `add_progress` | Add progress note to a thread |
| `list_progress` | Get progress history |
| `edit_progress` | Edit a progress entry |
| `delete_progress` | Delete a progress entry |

### Organization

| Tool | Description |
|------|-------------|
| `create_container` | Create organizational container |
| `update_container` | Update container properties |
| `delete_container` | Delete a container |
| `create_group` | Create a group |
| `update_group` | Update group properties |
| `delete_group` | Delete a group |
| `set_parent` | Set entity parent |
| `move_to_group` | Move entity to group |
| `get_children` | Get immediate children |
| `get_ancestors` | Get path to root |
| `get_subtree` | Get full subtree |

### Query & Search

| Tool | Description |
|------|-------------|
| `list_threads` | List threads with filters |
| `list_containers` | List containers with filters |
| `list_groups` | List all groups |
| `search_threads` | Full-text search |
| `get_next_action` | Suggest next thread to work on |
| `get_full_tree` | Get complete hierarchy |
| `get_entity` | Get any entity by ID/name |
| `get_container` | Get container by ID/name |
| `get_group` | Get group by ID/name |

## Architecture

```
threads-mcp/
├── src/
│   ├── server.ts           # Entry point, stdio transport
│   ├── lib/
│   │   ├── threads-client.ts  # Wrapper for Threads storage
│   │   └── types.ts           # MCP-specific types
│   ├── resources/
│   │   ├── index.ts        # Resource registration
│   │   ├── threads.ts      # Thread resources
│   │   ├── containers.ts   # Container resources
│   │   └── groups.ts       # Group resources
│   └── tools/
│       ├── index.ts        # Tool registration
│       ├── thread-ops.ts   # Thread operations
│       ├── progress-ops.ts # Progress operations
│       ├── org-ops.ts      # Organization operations
│       └── query-ops.ts    # Query operations
```

## Data Storage

Data is stored in `~/.threads/threads.json` (same as Threads CLI). This server directly reads and writes to that file, maintaining full compatibility with CLI operations.

## Example Workflows

### Create and track a project

```
1. Use create_container to create "My Project"
2. Use create_thread to create threads under that container
3. Use add_progress to log updates as you work
4. Use get_next_action to see what to work on next
```

### Review active work

```
1. Read threads://threads/active resource
2. Or use list_threads with status: "active"
3. Use list_progress to see recent updates
```

### Organize existing threads

```
1. Use create_group to create organizational groups
2. Use move_to_group to assign threads
3. Use set_parent to build hierarchy
```

## License

MIT