yougile-mcp-server

# YouGile MCP Server Python MCP server for using YouGile as both a context source and an action layer for AI agents. The current MVP supports: - listing projects; - listing boards inside a project; - listing columns inside a board; - listing tasks inside a column; - creating tasks; - moving tasks between columns; - starting and stopping task timers; - adding comments to tasks. ## Installation 1. Create and activate a virtual environment. 2. Install the project dependencies: ```bash pip install -e ".[dev]" ``` ## Configuration Copy `.env.example` to `.env` and fill in the required variables: ```env YOUGILE_API_KEY=your_api_key YOUGILE_BASE_URL=https://ru.yougile.com/api-v2 YOUGILE_TIMEOUT_SECONDS=20 ``` ## Run ```bash yougile-mcp-server ``` ## Connecting To An Agent To expose this project as an MCP server, your client needs: - a `command` that starts the server; - a `cwd` that points to the project root; - access to `YOUGILE_API_KEY`; - optionally `YOUGILE_BASE_URL` and `YOUGILE_TIMEOUT_SECONDS`. Example MCP client configuration: ```json { "mcpServers": { "yougile": { "command": "/opt/example/yougile-mcp-server/.venv/bin/yougile-mcp-server", "cwd": "/opt/example/yougile-mcp-server", "env": { "YOUGILE_API_KEY": "your_api_key", "YOUGILE_BASE_URL": "https://ru.yougile.com/api-v2", "YOUGILE_TIMEOUT_SECONDS": "20" } } } } ``` If your MCP client does not support passing `env`, you can keep the token in `.env` and launch the server with the project root as `cwd`. Alternative setup using Python directly: ```json { "mcpServers": { "yougile": { "command": "/opt/example/yougile-mcp-server/.venv/bin/python", "args": [ "-m", "yougile_mcp_server.server" ], "cwd": "/opt/example/yougile-mcp-server", "env": { "YOUGILE_API_KEY": "your_api_key" } } } } ``` After connecting, the agent should see these 9 tools: - `list_projects` - `list_boards` - `list_columns` - `list_tasks` - `create_task` - `move_task` - `start_task_timer` - `stop_task_timer` - `add_task_comment` ## Available Tools - `list_projects()` - `list_boards(project_id: str)` - `list_columns(board_id: str)` - `list_tasks(board_id: str, column_id: str, limit: int = 50)` - `create_task(board_id: str, column_id: str, title: str, description: str | None = None)` - `move_task(task_id: str, column_id: str)` - `start_task_timer(task_id: str)` - `stop_task_timer(task_id: str)` - `add_task_comment(task_id: str, text: str)` ## Example Workflow 1. List projects. 2. Choose a project. 3. List boards in that project. 4. Choose a board. 5. List columns in that board. 6. List tasks in the target column. 7. Create a new task in the selected column. 8. Move the task to another column. 9. Start the task timer. 10. Stop the task timer. 11. Add a comment to the task. ## Current Limitations - YouGile API responses are normalized into a consistent JSON shape for MCP tools. - The client is intentionally implemented as a thin wrapper, so if an endpoint contract changes, updates should mostly stay inside `src/yougile_mcp_server/clients/yougile_client.py`.