Metadata-Version: 2.4
Name: hermes-kanban-mcp-vn
Version: 0.1.0
Summary: Restricted MCP bridge for durable Hermes Kanban tasks
Author-email: NamHT <namht.dev@gmail.com>
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<2,>=1.2
Requires-Dist: pydantic<3,>=2.8
Requires-Dist: uvicorn<1,>=0.30
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: pytest-asyncio<1,>=0.23; extra == "dev"
Requires-Dist: ruff<1,>=0.5; extra == "dev"
Requires-Dist: mypy<2,>=1.10; extra == "dev"

# Hermes Kanban MCP (`hermes-kanban-mcp-vn`)

Restricted stdio MCP bridge that submits durable work to an existing Hermes Kanban board. It does not create another task database and does not expose arbitrary shell, workspace, profile or model selection.

Architecture: `MCP Hub --stdio/uvx--> MCP --HTTPS bearer--> restricted backend --fixed argv--> Hermes Kanban`.

The dashboard token is intentionally not used because it grants broad dashboard access. Both sides enforce board/assignee allowlists. Keep the backend private (loopback, VPN, or authenticated reverse proxy). `ready` requires the profile on disk plus explicit inclusion in `HERMES_KANBAN_READY_ASSIGNEES` after runtime/provider checks. Creating a task does not authorize production deployment, destructive actions, outbound messages, or spending.

## MCP Hub install (after PM approval and publish)

```json
{"mcpServers":{"hermes-kanban":{"command":"uvx","args":["hermes-kanban-mcp-vn==0.1.0"],"env":{"HERMES_KANBAN_URL":"https://hermes-kanban.internal.example","HERMES_KANBAN_TOKEN":"<secret-from-hub-secret-store>","HERMES_KANBAN_ALLOWED_ASSIGNEES":"developer,project-manager","HERMES_KANBAN_ALLOWED_BOARDS":"default","HERMES_KANBAN_TIMEOUT":"20"}}}}
```

Never commit tokens or put them in command arguments.

## Backend contract

Run on the Hermes host with the same board storage/config as `/opt/hermes/bin/hermes`:

```bash
HERMES_KANBAN_BACKEND_TOKEN='<secret>' HERMES_KANBAN_CLI=/opt/hermes/bin/hermes \
HERMES_KANBAN_ALLOWED_ASSIGNEES=developer,project-manager \
HERMES_KANBAN_READY_ASSIGNEES=developer,project-manager \
HERMES_KANBAN_ALLOWED_BOARDS=default \
uvx --from hermes-kanban-mcp-vn==0.1.0 hermes-kanban-backend
```

Authenticated routes: `GET /v1/agents`, `POST /v1/tasks`, `GET /v1/tasks/{id}`, `POST /v1/tasks/{id}/comments`. `/healthz` contains no board data. Use TLS and permit only MCP Hub source addresses.

## Verify and publish

```bash
uv sync --extra dev
uv run pytest -q
uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv run mypy src
uv build
uv run python scripts/mcp_smoke.py
```

The protocol smoke uses a loopback fake backend; it is not proof of live Hermes integration. After PM approval Linus publishes with `UV_PUBLISH_TOKEN='<secret-store>' uv publish`, starts the restricted backend, pins the Hub package version, and validates on an isolated board. Roll back by restoring the previous Hub package pin and stopping the backend; existing tasks remain durable.
