| Name | taskbeacon-mcp JSON |
| Version |
0.1.7
JSON |
| download |
| home_page | None |
| Summary | A model contexture protocal (MCP) for TaskBeacon |
| upload_time | 2025-09-07 07:38:34 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
taskbeacon
mcp
uv
taskbeacon
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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. |
---
Raw data
{
"_id": null,
"home_page": null,
"name": "taskbeacon-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "taskbeacon, mcp, uv, TaskBeacon",
"author": null,
"author_email": "Zhipeng Cao <zhipeng30@foxmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e1/04/1c2ea19b0af6e3bbb0fcff34898f21d87f9b66522795b2de78dbaf127ded/taskbeacon_mcp-0.1.7.tar.gz",
"platform": null,
"description": "# taskbeacon-mcp\r\n\r\nA model context protocol (MCP) for taskbeacon.\r\n\r\n---\r\n\r\n## Overview\r\n\r\n`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.\r\n\r\nThis README provides instructions for setting up and using `taskbeacon-mcp` in different environments.\r\n\r\n---\r\n\r\n## 1 \u00b7 Quick Start (Recommended)\r\n\r\nThe 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.\r\n\r\n### 1.1 \u00b7 Prerequisites\r\n\r\nEnsure you have `uvx` installed. If not, you can install it with `pip`:\r\n\r\n```bash\r\npip install uvx\r\n```\r\n\r\n### 1.2 \u00b7 LLM Tool Configuration (JSON)\r\n\r\nTo 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`.\r\n\r\n```json\r\n{\r\n \"name\": \"taskbeacon-mcp\",\r\n \"type\": \"stdio\",\r\n \"description\": \"Local FastMCP server for taskbeacon task operations. Uses uvx for automatic setup.\",\r\n \"isActive\": true,\r\n \"command\": \"uvx\",\r\n \"args\": [\r\n \"taskbeacon-mcp\"\r\n ]\r\n}\r\n```\r\n\r\nWith this setup, the LLM can now use the `taskbeacon-mcp` tools.\r\n\r\n---\r\n\r\n## 2 \u00b7 Manual Setup (For Developers)\r\n\r\nThis method is for developers who want to modify or contribute to the `taskbeacon-mcp` source code.\r\n\r\n### 2.1 \u00b7 Environment Setup\r\n\r\n1. **Create a virtual environment and install dependencies:**\r\n This project uses `uv`. Make sure you are in the project root directory.\r\n ```bash\r\n # Create and activate the virtual environment\r\n python -m venv .venv\r\n source .venv/bin/activate # On Windows, use: .venv\\Scripts\\activate\r\n\r\n # Install dependencies in editable mode\r\n pip install -e .\r\n ```\r\n\r\n### 2.2 \u00b7 Running Locally (StdIO)\r\n\r\nThis is the standard mode for local development, where the server communicates over `STDIN/STDOUT`.\r\n\r\n1. **Launch the server:**\r\n ```bash\r\n python taskbeacon_mcp/main.py\r\n ```\r\n\r\n2. **LLM Tool Configuration (JSON):**\r\n 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.\r\n\r\n ```json\r\n {\r\n \"name\": \"taskbeacon-mcp_dev\",\r\n \"type\": \"stdio\",\r\n \"description\": \"Local development server for taskbeacon task operations.\",\r\n \"isActive\": true,\r\n \"command\": \"python\",\r\n \"args\": [\r\n \"path\\\\to\\\\taskbeacon_mcp\\\\main.py\"\r\n ]\r\n }\r\n ```\r\n\r\n### 2.3 \u00b7 Running as a Persistent Server (SSE)\r\n\r\nFor 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.\r\n\r\n1. **Modify `main.py`:**\r\n In `taskbeacon-mcp/main.py`, change the last line from `mcp.run(transport=\"stdio\")` to:\r\n ```python\r\nmcp.run(transport=\"sse\", port=8000)\r\n ```\r\n\r\n2. **Run the server:**\r\n ```bash\r\n python taskbeacon-mcp/main.py\r\n ```\r\n The server will now be accessible at `http://localhost:8000/mcp`.\r\n\r\n3. **LLM Tool Configuration (JSON):**\r\n To connect an LLM tool to the running SSE server, use a configuration like this:\r\n ```json\r\n {\r\n \"name\": \"taskbeacon-mcp_sse\",\r\n \"type\": \"http\",\r\n \"description\": \"Persistent SSE server for taskbeacon task operations.\",\r\n \"isActive\": true,\r\n \"endpoint\": \"http://localhost:8000/mcp\"\r\n }\r\n ```\r\n\r\n---\r\n\r\n## 3 \u00b7 Conceptual Workflow\r\n\r\n1. **User** describes the task they want (e.g. \u201cMake a Stroop out of Flanker\u201d).\r\n2. **LLM** calls the `build_task` tool:\r\n * If the model already knows the best starting template it passes `source_task`.\r\n * Otherwise it omits `source_task`, receives a menu created by `choose_template_prompt`, picks a repo, then calls `build_task` again with that repo.\r\n3. The server clones the chosen template, returns a Stage 0\u21925 instruction prompt (`transform_prompt`) plus the local template path.\r\n4. The LLM edits files locally, optionally invokes `localize` to translate and adapt `config.yaml`, then zips / commits the new task.\r\n\r\n---\r\n\r\n## 4 \u00b7 Exposed Tools\r\n\r\n| Tool | Arguments | Purpose / Return |\r\n| :--- | :--- | :--- |\r\n| `build_task` | `target_task:str`, `source_task?:str` | **Main entry-point.** \u2022 With `source_task` \u2192 clones repo and returns: `prompt` (Stage 0\u21925) **+** `template_path` (local clone). \u2022 Without `source_task` \u2192 returns `prompt_messages` from `choose_template_prompt` so the LLM can pick the best starting template, then call `build_task` again. |\r\n| `list_tasks` | *none* | Returns an array of objects: `{ repo, readme_snippet, branches }`, where `branches` lists up to 20 branch names for that repo. |\r\n| `download_task` | `repo:str` | Clones any template repo from the registry and returns its local path. |\r\n| `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. |\r\n| `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\"). |\r\n\r\n---\r\n\r\n## 5 \u00b7 Exposed Prompts\r\n\r\n| Prompt | Parameters | Description |\r\n| :--- | :--- | :--- |\r\n| `transform_prompt` | `source_task`, `target_task` | Single **User** message containing the full Stage 0\u21925 instructions to convert `source_task` into `target_task`. |\r\n| `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`. |\r\n| `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. |\r\n\r\n---\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A model contexture protocal (MCP) for TaskBeacon",
"version": "0.1.7",
"project_urls": {
"Bug Tracker": "https://github.com/TaskBeacon/taskbeacon-mcp/issues",
"Homepage": "https://github.com/TaskBeacon/taskbeacon-mcp",
"Repository": "https://github.com/TaskBeacon/taskbeacon-mcp"
},
"split_keywords": [
"taskbeacon",
" mcp",
" uv",
" taskbeacon"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6281495a68ec50a72399829ff2a4c6daac4fe3497d7b404d1ab4636b455a95f4",
"md5": "372b72a0763f33ba44300c5b8cc0f5bc",
"sha256": "ce73d24d5d552a6be34baecbb6d3dacfe8c792f4e90b392666ef34f13af2e811"
},
"downloads": -1,
"filename": "taskbeacon_mcp-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "372b72a0763f33ba44300c5b8cc0f5bc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11694,
"upload_time": "2025-09-07T07:38:33",
"upload_time_iso_8601": "2025-09-07T07:38:33.012732Z",
"url": "https://files.pythonhosted.org/packages/62/81/495a68ec50a72399829ff2a4c6daac4fe3497d7b404d1ab4636b455a95f4/taskbeacon_mcp-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e1041c2ea19b0af6e3bbb0fcff34898f21d87f9b66522795b2de78dbaf127ded",
"md5": "9901c3c0d4c5bdccd255813ab7853258",
"sha256": "1f9af04cfd61e411430d87436991f54fd76250a84edca8277e5f76633ae4d034"
},
"downloads": -1,
"filename": "taskbeacon_mcp-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "9901c3c0d4c5bdccd255813ab7853258",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 13696,
"upload_time": "2025-09-07T07:38:34",
"upload_time_iso_8601": "2025-09-07T07:38:34.345653Z",
"url": "https://files.pythonhosted.org/packages/e1/04/1c2ea19b0af6e3bbb0fcff34898f21d87f9b66522795b2de78dbaf127ded/taskbeacon_mcp-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 07:38:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TaskBeacon",
"github_project": "taskbeacon-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "taskbeacon-mcp"
}
