Yokan Board MCP

🚀 Yokan Board MCP

本項目是一個面向 Yokan 看板 API 的模型上下文協議（MCP）服務器。它為 AI 代理提供了一個基於工具的接口，用於與看板、列和任務進行交互和管理。

✨ 主要特性

• 看板管理：創建、檢索、更新和刪除看板。
• 列管理：在看板內創建、檢索、更新、重新排序和刪除列。
• 任務管理：創建、檢索、更新、移動和刪除任務。
• 支持代理：設計用於 AI 代理通過主控制協議使用。

🛠️ 技術棧

• Python
• FastAPI
• Pydantic
• fastmcp

🚀 快速開始

構建並運行 Docker 鏡像

對於新用戶或不想設置開發環境就運行服務器的用戶，我們建議使用 Docker。

1. 構建 Docker 鏡像：

docker build -t yokanboard/yokan-mcp .

2. 運行 Docker 容器：

docker run -p 8888:8888 --name yokan-mcp -e YOKAN_API_BASE_URL=http://your-yokan-api-host:port/api yokanboard/yokan-mcp

請確保將 http://your-yokan-api-host:port/api 替換為你實際的 Yokan API 實例的 URL。

MCP 客戶端配置

使用可流式傳輸的 Gemini CLI

創建 .gemini/settings.json 文件，內容如下：

{
    "mcpServers": {
        "yokan-board": {
            "httpUrl": "http://[your-yokan-mcp-host]:8888/mcp",
            "headers": {
                "Authorization": "Bearer [TOKEN]",
                "accept": "application/json"
            }
        }
    }
}

使用標準輸入輸出傳輸的 VS Code Copilot

創建 .vscode/mcp.json 文件，內容如下：

{
    "servers": {
        "yokan-board": {
            "type": "stdio",
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "/full/path/to/yokan-board-mcp-project-folder/yokan-board-mcp",
                "-m",
                "src.main",
                "--stdio"
            ]
        }
    }
}

🛠️ 開發

前提條件

• Python 3.8+
• uv（用於管理 Python 環境）
• 能夠訪問正在運行的 Yokan API 實例。

環境搭建

1. 克隆倉庫：

git clone https://github.com/yokan-board/yokan-board-mcp.git
cd yokan-board-mcp

2. 創建並激活虛擬環境：

uv venv
source .venv/bin/activate

3. 安裝依賴：

uv sync

配置

1. 通過複製 .env.example 文件創建 .env 文件：

cp .env.example .env

2. 編輯 .env 文件，指向你的 Yokan API 實例：

YOKAN_API_BASE_URL=http://your-yokan-api-host:port/api

運行服務器

要啟動用於開發的 MCP 服務器，請運行以下命令：

uvicorn src.main:app --host localhost --port 8888 --reload

🧪 測試

要運行集成測試，你需要有一個正在運行的 Yokan API 實例和一個測試用戶。測試配置為使用用戶名 user 和密碼 password。 確保你的 .env 文件已正確配置 YOKAN_API_BASE_URL。 使用以下命令運行測試：

make test

🛠️ 可用工具

MCP 服務器提供了以下用於管理 Yokan 看板的工具：

💻 使用示例

你可以使用 fastmcp 客戶端庫與 MCP 服務器進行交互。

身份驗證

要使用這些工具，你首先需要從你的 Yokan API 實例獲取 JWT 令牌。你可以通過向 Yokan API 的 /login 端點發送 POST 請求來實現。 使用 curl 的示例：

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}' \
  http://localhost:3001/api/v1.1/login

示例：與 MCP 服務器交互

一個展示如何使用 fastmcp 客戶端與 Yokan MCP 服務器進行交互的 Python 示例可以在 中找到。

📄 版權信息

Yokan Board MCP 由 Julian I. Kamil 創建。 © 版權所有 2025 Julian I. Kamil。保留所有權利。

📄 許可證

Yokan Board MCP 採用雙重許可：

• AGPLv3：根據 GNU Affero 通用公共許可證第 3 版的條款免費使用、修改和分發（請參閱 LICENSE.AGPLv3）。
• 商業許可證：適用於希望在不遵循 AGPLv3 版權共享要求的情況下使用 Yokan 的組織（請參閱 LICENSE.COMMERCIAL）。 如需商業使用許可信息，請發送電子郵件至：yokan.board@gmail.com