kaneo (minimalist kanban) fork to experiment adding a tangled integration
github.com/usekaneo/kaneo
feat: new docs for mcp; allow mcp by default
+31
-30
+1
-1
apps/api/src/auth.ts
+1
-1
apps/api/src/auth.ts
+3
-1
apps/docs/api-reference/authentication.mdx
+3
-1
apps/docs/api-reference/authentication.mdx
···
97
97
98
98
## Using Device Authorization
99
99
100
-
Before using device authorization on a self-hosted Kaneo instance, the instance operator must allow your client ID through `DEVICE_AUTH_CLIENT_IDS`.
100
+
By default, self-hosted Kaneo allows the built-in device clients `kaneo-cli` and `kaneo-mcp`.
101
+
102
+
If you want to use a different device client ID, the instance operator must allow it through `DEVICE_AUTH_CLIENT_IDS`.
101
103
102
104
### Flow overview
103
105
+1
-1
apps/docs/core/installation/environment-variables.mdx
+1
-1
apps/docs/core/installation/environment-variables.mdx
···
50
50
Name | Description |
51
51
--- | --- |
52
52
| `AUTH_SECRET` | The secret key for the JWT token. **Must be at least 32 characters long**, use a long, random value in production. Example: use `openssl rand -base64 32` to generate a secure key in Linux/macOS.
53
-
| `DEVICE_AUTH_CLIENT_IDS` | Comma-separated list of allowed device authorization client IDs. When unset, `kaneo-cli` is allowed by default, so no extra configuration is required for the CLI. Use this to permit trusted external app identifiers such as `kaneo-cli,my-desktop-app`. |
53
+
| `DEVICE_AUTH_CLIENT_IDS` | Comma-separated list of allowed device authorization client IDs. When unset, Kaneo allows `kaneo-cli` and `kaneo-mcp` by default. Use this to permit trusted external app identifiers such as `kaneo-cli,kaneo-mcp,my-desktop-app`. |
54
54
55
55
56
56
## Optional variables
+26
-27
apps/mcp/README.md
+26
-27
apps/mcp/README.md
···
1
1
# Kaneo MCP server
2
2
3
-
Model Context Protocol (stdio) server that talks to a [Kaneo](https://github.com/usekaneo/kaneo) instance using the OAuth 2.0 device authorization flow (RFC 8628), then calls Kaneo’s REST API with `Authorization: Bearer <token>`.
4
-
5
-
**How MCP fits here:** clients (Cursor, Claude Desktop, etc.) start a **local process** and talk to it over **stdin/stdout** using the MCP protocol. This package ships a **`bin`** (`kaneo-mcp`) for installable CLIs.
3
+
`@kaneo/mcp` is a local MCP server for Kaneo.
6
4
7
-
This package lives in the Kaneo monorepo at **`apps/mcp`**.
5
+
It runs over stdio, signs in with Kaneo's device flow, and then calls the Kaneo API with a bearer token. The package lives in `apps/mcp` in this monorepo and exposes the `kaneo-mcp` CLI.
8
6
9
7
## Prerequisites
10
8
11
9
- Node.js 20+
12
10
- A running Kaneo API (for example `http://localhost:1337`) and web app (for device approval UI).
13
11
14
-
On the Kaneo server, allow this MCP client’s ID:
12
+
Kaneo allows `kaneo-cli` and `kaneo-mcp` by default, so you usually do not need extra server configuration.
13
+
14
+
If you want to run this server with a different client ID, allow it on the Kaneo server:
15
15
16
16
```bash
17
-
DEVICE_AUTH_CLIENT_IDS=kaneo-cli,kaneo-mcp
17
+
DEVICE_AUTH_CLIENT_IDS=kaneo-cli,kaneo-mcp,your-client-id
18
18
```
19
-
20
-
If you omit `DEVICE_AUTH_CLIENT_IDS`, Kaneo defaults to allowing `kaneo-cli` only—you must include `kaneo-mcp` (or set `KANEO_MCP_CLIENT_ID` to an ID you have allowlisted).
21
19
22
20
## Environment
23
21
···
26
24
| `KANEO_API_URL` | Kaneo API origin (default `http://localhost:1337`). Do not include `/api`. |
27
25
| `KANEO_MCP_CLIENT_ID` | Device-flow client id (default `kaneo-mcp`). Must match `DEVICE_AUTH_CLIENT_IDS` on the server. |
28
26
29
-
## Install (published package)
27
+
## Install
30
28
31
-
After publishing `@kaneo/mcp` to npm (or a private registry):
29
+
If the package is published to npm or your private registry:
32
30
33
31
```bash
34
32
npm install -g @kaneo/mcp
···
41
39
npx @kaneo/mcp
42
40
```
43
41
44
-
The published tarball includes **`dist/`** and dependencies; `prepublishOnly` runs the TypeScript build before publish.
42
+
The published package includes `dist/`. `prepublishOnly` runs the build before publish.
45
43
46
-
## Develop from source (inside this monorepo)
44
+
## Develop from source
47
45
48
-
From the **`kaneo/`** directory:
46
+
From the repo root:
49
47
50
48
```bash
51
49
pnpm install
···
54
52
pnpm --filter @kaneo/mcp run test
55
53
```
56
54
57
-
Or with paths:
55
+
Or run it from the package directory:
58
56
59
57
```bash
60
58
pnpm -C apps/mcp run build
61
59
```
62
60
63
-
The CLI entry is `kaneo-mcp` in `package.json` `bin` → `./dist/index.js`.
64
-
For **Cursor**, point the MCP command at **`…/kaneo/apps/mcp/dist/index.js`** (absolute path after build).
61
+
The CLI entry points to `./dist/index.js`.
62
+
63
+
For Cursor or another MCP client, point the command at the built file:
64
+
65
+
```text
66
+
.../kaneo/apps/mcp/dist/index.js
67
+
```
65
68
66
69
## Authentication
67
70
68
71
On the first tool call that needs Kaneo, the server:
69
72
70
73
1. Requests a device code from `POST /api/auth/device/code`
71
-
2. Prints the verification URL and user code to **stderr** (stdout stays clean for MCP)
74
+
2. Prints the verification URL and user code to `stderr`
72
75
3. Tries to open the browser
73
76
4. Polls `POST /api/auth/device/token` until approved
74
-
5. Stores the access token under `~/.config/kaneo-mcp/credentials.json` (mode `0600`)
77
+
5. Stores the access token at `~/.config/kaneo-mcp/credentials.json` with mode `0600`
75
78
76
79
## Tools
77
80
78
-
Session: `whoami`, `list_workspaces`
79
-
80
-
Projects: `list_projects`, `get_project`, `create_project`, `update_project`
81
-
82
-
Tasks: `list_tasks`, `get_task`, `create_task`, `update_task`, `move_task`, `update_task_status`
83
-
84
-
Comments: `list_task_comments`, `create_task_comment`
85
-
86
-
Labels: `list_workspace_labels`, `create_label`, `attach_label_to_task`, `detach_label_from_task`
81
+
- Session: `whoami`, `list_workspaces`
82
+
- Projects: `list_projects`, `get_project`, `create_project`, `update_project`
83
+
- Tasks: `list_tasks`, `get_task`, `create_task`, `update_task`, `move_task`, `update_task_status`
84
+
- Comments: `list_task_comments`, `create_task_comment`
85
+
- Labels: `list_workspace_labels`, `create_label`, `attach_label_to_task`, `detach_label_from_task`