# taskbeacon-mcp

A model context protocol (MCP) for taskbeacon.

---

## Overview

`taskbeacon-mcp` is a lightweight **FastMCP** server that lets a language-model clone, transform, download and localize taskbeacon task templates using a single entry-point tool.

This README provides instructions for setting up and using `taskbeacon-mcp` in different environments.

---

## 1 · Quick Start (Recommended)

The easiest way to use `taskbeacon-mcp` is with `uvx`. This tool automatically downloads the package from PyPI, installs it and its dependencies into a temporary virtual environment, and runs it in a single step. No manual cloning or setup is required.

### 1.1 · Prerequisites

Ensure you have `uvx` installed. If not, you can install it with `pip`:

```bash
pip install uvx
```

### 1.2 · LLM Tool Configuration (JSON)

To integrate `taskbeacon-mcp` with your LLM tool (like Gemini CLI or Cursor), use the following JSON configuration. This tells the tool how to run the server using `uvx`.

```json
{
  "name": "taskbeacon-mcp",
  "type": "stdio",
  "description": "Local FastMCP server for taskbeacon task operations. Uses uvx for automatic setup.",
  "isActive": true,
  "command": "uvx",
  "args": [
    "taskbeacon-mcp"
  ]
}
```

With this setup, the LLM can now use the `taskbeacon-mcp` tools.

---

## 2 · Manual Setup (For Developers)

This method is for developers who want to modify or contribute to the `taskbeacon-mcp` source code.

### 2.1 · Environment Setup

1.  **Create a virtual environment and install dependencies:**
    This project uses `uv`. Make sure you are in the project root directory.
    ```bash
    # Create and activate the virtual environment
    python -m venv .venv
    source .venv/bin/activate  # On Windows, use: .venv\Scripts\activate

    # Install dependencies in editable mode
    pip install -e .
    ```

### 2.2 · Running Locally (StdIO)

This is the standard mode for local development, where the server communicates over `STDIN/STDOUT`.

1.  **Launch the server:**
    ```bash
    python taskbeacon_mcp/main.py
    ```

2.  **LLM Tool Configuration (JSON):**
    To use your local development server with an LLM tool, use the following configuration. Note that you should replace the example path in `args` with the absolute path to the `main.py` file on your machine.

    ```json
    {
      "name": "taskbeacon-mcp_dev",
      "type": "stdio",
      "description": "Local development server for taskbeacon task operations.",
      "isActive": true,
      "command": "python",
      "args": [
        "path\\to\\taskbeacon_mcp\\main.py"
      ]
    }
    ```

### 2.3 · Running as a Persistent Server (SSE)

For a persistent, stateful server, you can run `taskbeacon-mcp` using Server-Sent Events (SSE). This is ideal for production or when multiple clients need to interact with the same server instance.

1.  **Modify `main.py`:**
    In `taskbeacon-mcp/main.py`, change the last line from `mcp.run(transport="stdio")` to:
    ```python
mcp.run(transport="sse", port=8000)
    ```

2.  **Run the server:**
    ```bash
    python taskbeacon-mcp/main.py
    ```
    The server will now be accessible at `http://localhost:8000/mcp`.

3.  **LLM Tool Configuration (JSON):**
    To connect an LLM tool to the running SSE server, use a configuration like this:
    ```json
    {
      "name": "taskbeacon-mcp_sse",
      "type": "http",
      "description": "Persistent SSE server for taskbeacon task operations.",
      "isActive": true,
      "endpoint": "http://localhost:8000/mcp"
    }
    ```

---

## 3 · Conceptual Workflow

1.  **User** describes the task they want (e.g. “Make a Stroop out of Flanker”).
2.  **LLM** calls the `build_task` tool:
    *   If the model already knows the best starting template it passes `source_task`.
    *   Otherwise it omits `source_task`, receives a menu created by `choose_template_prompt`, picks a repo, then calls `build_task` again with that repo.
3.  The server clones the chosen template, returns a Stage 0→5 instruction prompt (`transform_prompt`) plus the local template path.
4.  The LLM edits files locally, optionally invokes `localize` to translate and adapt `config.yaml`, then zips / commits the new task.

---

## 4 · Exposed Tools

| Tool | Arguments | Purpose / Return |
| :--- | :--- | :--- |
| `build_task` | `target_task:str`, `source_task?:str` | **Main entry-point.** • With `source_task` → clones repo and returns: `prompt` (Stage 0→5) **+** `template_path` (local clone). • Without `source_task` → returns `prompt_messages` from `choose_template_prompt` so the LLM can pick the best starting template, then call `build_task` again. |
| `list_tasks` | *none* | Returns an array of objects: `{ repo, readme_snippet, branches }`, where `branches` lists up to 20 branch names for that repo. |
| `download_task` | `repo:str` | Clones any template repo from the registry and returns its local path. |
| `localize` | `task_path:str`, `target_language:str`, `voice?:str` | Reads `config.yaml`, wraps it in `localize_prompt`, and returns `prompt_messages`. If a `voice` is not provided, it first calls `list_voices` to find suitable options. Also deletes old `_voice.mp3` files. |
| `list_voices` | `filter_lang?:str` | Returns a human-readable string of available text-to-speech voices from `taskbeacon`, optionally filtered by language (e.g., "ja", "en"). |

---

## 5 · Exposed Prompts

| Prompt | Parameters | Description |
| :--- | :--- | :--- |
| `transform_prompt` | `source_task`, `target_task` | Single **User** message containing the full Stage 0→5 instructions to convert `source_task` into `target_task`. |
| `choose_template_prompt` | `desc`, `candidates:list[{repo,readme_snippet}]` | Three **User** messages: task description, template list, and selection criteria. The LLM must reply with **one repo name** or the literal word `NONE`. |
| `localize_prompt` | `yaml_text`, `target_language`, `voice_options?` | Two-message sequence: strict translation instruction + raw YAML. The LLM must return the fully-translated YAML body, adding the `voice: <short_name>` if suitable options were provided. |

---