Content
# YouGile Secure MCP
A local stdio [Model Context Protocol](https://modelcontextprotocol.io/) server for the [YouGile](https://yougile.com) API v2. Read-only by default; writes require an explicit, single-use approval issued after the user confirms the exact payload in chat.
## Tools (v0.2.0)
### Read-only
| Tool | Purpose |
| --- | --- |
| `get_current_user` | Profile that owns the API key |
| `list_projects`, `get_project` | Projects |
| `list_boards`, `get_board` | Boards |
| `list_columns` | Columns |
| `list_tasks` | Compact task summaries with server-side filters (column, assignee, title, sticker) |
| `get_task` | Full task object by UUID |
| `find_task_by_short_id` | Look up a task by human-readable ID such as `ID-484` / `DEV-484` |
| `list_task_comments` | Task chat messages |
| `list_users` | Company users (filter by project or email) |
| `list_string_stickers` | Custom stickers and their states |
All list tools return `{"items": [...], "has_more": bool}`; `limit` is capped at 100, use `offset` for the next page.
### Staged writes (explicit approval required)
| Tool | Purpose |
| --- | --- |
| `propose_task_create` | Stage a new task, returns a preview + single-use approval token |
| `propose_task_update` | Stage changes to an existing task, same contract |
| `apply_approved_action` | Execute a staged action; the only tool that can mutate YouGile |
The flow is: agent stages an action → shows the preview to the user → the user approves in chat → agent calls `apply_approved_action` with the token. Tokens are bound to the exact payload, single-use, and expire after `YOUGILE_APPROVAL_TTL_SECONDS` (default 600). **Delete operations are not implemented at all.**
### Security model
- Uses only `YOUGILE_API_KEY`; never accepts, stores, or sends an account login/password.
- Never creates, lists, or deletes YouGile API keys, webhooks, or users.
- Never writes credentials to disk; API errors never include response bodies, so the key cannot leak through error messages.
- All object IDs interpolated into URL paths are validated as UUIDs (no path traversal).
- `YOUGILE_BASE_URL` must be `https` (plain `http` is allowed only for localhost).
- Handles the YouGile rate limit (50 requests/minute) with bounded retries on HTTP 429.
## Install
```bash
git clone https://github.com/ropuwz-dot/MCP-Yougile.git
cd MCP-Yougile
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]' # Linux/macOS
# .venv\Scripts\python -m pip install -e .[dev] # Windows
```
Run it with the API key in the environment:
```bash
export YOUGILE_API_KEY='your-api-key' # Windows: $env:YOUGILE_API_KEY='your-api-key'
.venv/bin/python run_server.py # Windows: .venv\Scripts\python run_server.py
```
## Configuration
| Variable | Default | Purpose |
| --- | --- | --- |
| `YOUGILE_API_KEY` | — (required) | YouGile API v2 key |
| `YOUGILE_BASE_URL` | `https://yougile.com` | Self-hosted deployments: the `mainPageUrl` from your `conf.json` |
| `YOUGILE_TIMEOUT_SECONDS` | `30` | HTTP timeout |
| `YOUGILE_APPROVAL_TTL_SECONDS` | `600` | Lifetime of a staged write approval |
| `YOUGILE_SSL_CA_CERT` | — | Path to a CA bundle for self-hosted servers with a self-signed certificate |
| `YOUGILE_ALLOW_INSECURE_HTTP` | `false` | Explicit opt-in for plain-http local self-hosted servers |
### Self-hosted (box) YouGile
The [self-hosted Linux Server edition](https://docs.yougile.com/docs/admin-guide-linux/api/) exposes the same API v2 on your own domain. Point `YOUGILE_BASE_URL` at the `mainPageUrl` value from your `conf.json`:
- **HTTPS with a self-signed certificate** — set `YOUGILE_SSL_CA_CERT` to the path of the certificate (or its CA) so TLS verification keeps working. Verification can never be turned off.
- **Plain HTTP on a trusted local network** — allowed by YouGile for local use, but here it requires `YOUGILE_ALLOW_INSECURE_HTTP=true` so the API key is never sent in clear text by accident. `http://localhost` works without the flag.
## Client configuration
### Claude Code
```bash
claude mcp add yougile -e YOUGILE_API_KEY=your-api-key -- /absolute/path/to/MCP-Yougile/.venv/bin/python /absolute/path/to/MCP-Yougile/run_server.py
```
### Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"yougile": {
"command": "/absolute/path/to/MCP-Yougile/.venv/bin/python",
"args": ["/absolute/path/to/MCP-Yougile/run_server.py"],
"env": { "YOUGILE_API_KEY": "your-api-key" }
}
}
}
```
### Hermes
Keep the secret in `~/.hermes/.env` with `0600` permissions:
```dotenv
YOUGILE_API_KEY=your-api-key
```
Then add this server under `mcp_servers` in `~/.hermes/config.yaml`:
```yaml
mcp_servers:
yougile:
command: /absolute/path/to/MCP-Yougile/.venv/bin/python
args: [/absolute/path/to/MCP-Yougile/run_server.py]
env:
YOUGILE_API_KEY: "${YOUGILE_API_KEY}"
timeout: 60
connect_timeout: 30
sampling:
enabled: false
```
Verify it before restarting Hermes: `hermes mcp test yougile`.
## Development
```bash
.venv/bin/python -m pytest -q
.venv/bin/python -m ruff check src tests
.venv/bin/python -m mypy
```
CI runs the same three checks on Python 3.11–3.13 for every push and pull request.
## License
[MIT](LICENSE)
