> Build Together is a lightweight, self-hosted project management tool built for AI+Human collaboration. It features a web interface, a RESTful API, and full Model Context Protocol (MCP) support for integration with AI coding assistants like Cursor, Claude Code, and Windsurf.

Build Together allows you to create and manage projects, organize work into sprints, track tasks and issues, and collaborate with AI assistants through natural language. The application is designed to be simple to set up and use, with a focus on providing a smooth experience for both human users and AI assistants.

Key features:
- Create and manage projects with requirements and implementation details
- Organize work into sprints with different statuses (Planned, Active, Completed)
- Track tasks and issues with completion status
- Star important tasks and issues for quick identification
- RESTful API for all operations
- MCP server for AI assistant integration

## API Usage

The Build Together API is available at `http://127.0.0.1:3149/api` when the application is running locally.

### Authentication

No authentication is required for local development.

### API Endpoints

#### Projects

- `GET /api/projects` - List all projects
- `GET /api/projects/{id}` - Get project by ID
- `POST /api/projects` - Create a new project
- `PUT /api/projects/{id}` - Update a project
- `DELETE /api/projects/{id}` - Delete a project

#### Sprints

- `GET /api/sprints` - List all sprints
- `GET /api/sprints/{id}` - Get sprint by ID
- `POST /api/sprints` - Create a new sprint
- `PUT /api/sprints/{id}` - Update a sprint
- `DELETE /api/sprints/{id}` - Delete a sprint

#### Tasks

- `GET /api/tasks` - List all tasks
- `GET /api/tasks/{id}` - Get task by ID
- `POST /api/tasks` - Create a new task
- `PUT /api/tasks/{id}` - Update a task
- `DELETE /api/tasks/{id}` - Delete a task
- `PUT /api/tasks/{id}/star` - Star/unstar a task

#### Issues

- `GET /api/issues` - List all issues
- `GET /api/issues/{id}` - Get issue by ID
- `POST /api/issues` - Create a new issue
- `PUT /api/issues/{id}` - Update an issue
- `DELETE /api/issues/{id}` - Delete an issue
- `PUT /api/issues/{id}/star` - Star/unstar an issue

### API Examples

#### List all projects
```bash
curl -X GET http://127.0.0.1:3149/api/projects
```

#### Get a specific project
```bash
curl -X GET http://127.0.0.1:3149/api/projects/1
```

#### Create a new project
```bash
curl -X POST http://127.0.0.1:3149/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Project",
    "description": "Project description",
    "requirements": "Project requirements",
    "implementation": "Implementation details"
  }'
```

#### Update a project
```bash
curl -X PUT http://127.0.0.1:3149/api/projects/1 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Project",
    "description": "Updated description",
    "requirements": "Updated requirements",
    "implementation": "Updated implementation details"
  }'
```

#### Delete a project
```bash
curl -X DELETE http://127.0.0.1:3149/api/projects/1
```

## MCP Server Usage

The MCP server allows AI assistants to interact with Build Together using natural language commands.

### Available MCP Tools

#### Project Management

- `list_projects` - List all projects
- `get_project` - Get detailed information about a specific project
- `create_project` - Create a new project
- `update_project` - Update an existing project

#### Sprint Management

- `list_sprints` - List all sprints or sprints for a specific project
- `get_sprint` - Get detailed information about a specific sprint
- `create_sprint` - Create a new sprint
- `update_sprint` - Update an existing sprint

#### Task Management

- `list_tasks` - List all tasks for a sprint
- `get_task` - Get detailed information about a specific task
- `create_task` - Create a new task
- `update_task` - Update an existing task (e.g., mark as completed)

#### Issue Management

- `list_issues` - List all issues or issues for a specific sprint
- `get_issue` - Get detailed information about a specific issue
- `create_issue` - Create a new issue
- `update_issue` - Update an existing issue (e.g., mark as resolved)

### MCP Examples

#### List all projects
```json
{
  "name": "list_projects",
  "parameters": {}
}
```

#### Get a specific project
```json
{
  "name": "get_project",
  "parameters": {
    "project_id": 1
  }
}
```

#### Create a new project
```json
{
  "name": "create_project",
  "parameters": {
    "name": "New Project",
    "description": "Project description",
    "requirements": "Project requirements"
  }
}
```

#### Update a project
```json
{
  "name": "update_project",
  "parameters": {
    "project_id": 1,
    "data": {
      "name": "Updated Project Name",
      "description": "Updated description",
      "requirements": "Updated requirements",
      "implementation_details": "Updated implementation details"
    }
  }
}
```

#### List all sprints or sprints for a project
```json
{
  "name": "list_sprints",
  "parameters": {
    "project_id": 1
  }
}
```

#### Get a specific sprint
```json
{
  "name": "get_sprint",
  "parameters": {
    "sprint_id": 1
  }
}
```

#### Create a new sprint for a project
```json
{
  "name": "create_sprint",
  "parameters": {
    "project_id": 1,
    "name": "Sprint 1",
    "description": "First sprint",
    "status": "Planned"
  }
}
```

#### Update a sprint
```json
{
  "name": "update_sprint",
  "parameters": {
    "sprint_id": 1,
    "name": "Updated Sprint Name",
    "description": "Updated sprint description",
    "status": "Active"
  }
}
```

#### List all tasks for a sprint
```json
{
  "name": "list_tasks",
  "parameters": {
    "sprint_id": 1
  }
}
```

#### Get a specific task
```json
{
  "name": "get_task",
  "parameters": {
    "task_id": 1
  }
}
```

#### Create a new task in a sprint
```json
{
  "name": "create_task",
  "parameters": {
    "sprint_id": 1,
    "details": "Implement feature X",
    "completed": false
  }
}
```

#### Update a task
```json
{
  "name": "update_task",
  "parameters": {
    "task_id": 1,
    "details": "Updated task description",
    "completed": true
  }
}
```

#### List all issues or issues for a sprint
```json
{
  "name": "list_issues",
  "parameters": {
    "sprint_id": 1
  }
}
```

#### Get a specific issue
```json
{
  "name": "get_issue",
  "parameters": {
    "issue_id": 1
  }
}
```

#### Create a new issue in a sprint
```json
{
  "name": "create_issue",
  "parameters": {
    "sprint_id": 1,
    "details": "Bug: Feature X not working correctly",
    "completed": false
  }
}
```

#### Update an issue
```json
{
  "name": "update_issue",
  "parameters": {
    "issue_id": 1,
    "details": "Updated issue description",
    "completed": true
  }
}
```

### Tips for AI Assistants

1. **Working with Tasks and Issues**: When a user asks you to "work on tasks or issues," you should:
   - List all tasks or issues using `list_tasks` or `list_issues` with the appropriate sprint_id
   - Focus on implementing or providing solutions for these tasks or issues

2. **Project Context**: Always maintain context about the current project structure:
   - Which project is the user working on?
   - What sprints exist in this project?
   - What tasks and issues are in the current sprint?

3. **Natural Language Processing**: Common user requests and their MCP tool mappings:
   - "Show me all projects" → `list_projects`
   - "Create a new sprint" → `create_sprint`
   - "Mark this task as complete" → `update_task` with completed=true
   - "Mark this issue as resolved" → `update_issue` with completed=true

4. **Error Handling**: If an MCP command fails:
   - Check if the referenced ID exists
   - Verify all required parameters are provided
   - Ensure parameter values are valid (e.g., sprint status must be one of: "Planned", "Active", "Completed")
   - Make sure you're using the correct parameter names (e.g., "details" for task and issue content, not "title" or "description")

5. **Workflow Suggestions**: Recommend efficient workflows to users:
   - Create projects with clear requirements
   - Organize work into sprints with specific goals
   - Use tasks for planned work and issues for problems that arise
   - Update tasks and issues as work progresses

## Executing MCP Commands

To execute an MCP command, send a POST request to the MCP server endpoint:

```bash
curl -X POST http://127.0.0.1:3149/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{
    "name": "list_projects",
    "parameters": {}
  }' | python -m json.tool
```

For AI assistants with direct MCP integration (like Windsurf or Cursor), you can use the natural language interface to issue commands, and the assistant will handle the MCP protocol details.

## Known Limitations

1. AI assistants may sometimes have trouble executing MCP commands or the MCP server might require multiple tool calls
2. Copy task/issue ID functionality doesn't work within Windsurf Browser Preview
3. Various UX/UI improvements are planned for future releases

## Best Practices

1. Always verify the success of operations by checking the response
2. Maintain context about the project structure to avoid unnecessary API calls
3. Use descriptive titles and detailed descriptions for all items
4. Leverage Markdown formatting in description fields for better readability
5. Star important tasks and issues to make them stand out