Yokan 看板 MCP

<p align="center"> <img src="./images/avatar.png" alt="Yokan Logo" width="150" style="border-radius: 50%;"> </p>

该项目是一个用于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-yok[an-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与标准I/O传输

创建.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看板：

类别	工具
看板	get_boards, get_board, create_board, update_board, delete_board
列	create_column, get_columns, update_column, reorder_columns, delete_column, update_column_color
任务	create_task, create_tasks, get_tasks, update_task, move_task, delete_task

使用示例

您可以使用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示例可以在examples/mcp_client.py中找到。

版权

Yokan看板MCP由：Julian I. Kamil 创建

© 2025 Julian I. Kamil. 保留所有权利。

许可

Yokan看板MCP提供双重许可：

• AGPLv3：根据GNU Affero通用公共许可证第3版免费使用、修改和分发（参见LICENSE.AGPLv3）
• 商业许可：适用于希望在没有AGPLv3的复制权要求下使用Yokan的组织（参见LICENSE.COMMERCIAL）

有关商业使用许可的信息，请发送电子邮件至：yokan.board@gmail.com