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:

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.

{
  "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.

   # 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:

   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.

   {
     "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:

mcp.run(transport="sse", port=8000) ```

1. Run the server:

   python taskbeacon-mcp/main.py
   

   The server will now be accessible at http://localhost:8000/mcp.

2. LLM Tool Configuration (JSON): To connect an LLM tool to the running SSE server, use a configuration like this:

   {
     "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

5 · Exposed Prompts