Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

feat: new docs for mcp; allow mcp by default

Tin5adb647d527f
diff --git a/apps/api/src/auth.ts b/apps/api/src/auth.ts
index 50384e085..ecafc01b9 100644
--- a/apps/api/src/auth.ts
+++ b/apps/api/src/auth.ts
@@ -110,7 +110,7 @@ function getDeviceAuthClientIds(): Set<string> {
.filter(Boolean),
);
}
- return new Set(["kaneo-cli"]);
+ return new Set(["kaneo-cli", "kaneo-mcp"]);
}
function getDeviceAuthVerificationUri(): string {
diff --git a/apps/docs/api-reference/authentication.mdx b/apps/docs/api-reference/authentication.mdx
index 6bd044c7b..e4cf3bb4d 100644
--- a/apps/docs/api-reference/authentication.mdx
+++ b/apps/docs/api-reference/authentication.mdx
@@ -97,7 +97,9 @@ const response = await fetch('https://your-kaneo-instance.com/api/task?workspace
## Using Device Authorization
-Before using device authorization on a self-hosted Kaneo instance, the instance operator must allow your client ID through `DEVICE_AUTH_CLIENT_IDS`.
+By default, self-hosted Kaneo allows the built-in device clients `kaneo-cli` and `kaneo-mcp`.
+
+If you want to use a different device client ID, the instance operator must allow it through `DEVICE_AUTH_CLIENT_IDS`.
### Flow overview
diff --git a/apps/docs/core/installation/environment-variables.mdx b/apps/docs/core/installation/environment-variables.mdx
index 88ddb986e..c3065741e 100644
--- a/apps/docs/core/installation/environment-variables.mdx
+++ b/apps/docs/core/installation/environment-variables.mdx
@@ -50,7 +50,7 @@ This section will cover all the variables related to the authentication.
Name | Description |
--- | --- |
| `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.
-| `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`. |
+| `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`. |
## Optional variables
diff --git a/apps/mcp/README.md b/apps/mcp/README.md
index 132fb7833..77fb89c54 100644
--- a/apps/mcp/README.md
+++ b/apps/mcp/README.md
@@ -1,24 +1,22 @@
# Kaneo MCP server
-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>`.
+`@kaneo/mcp` is a local MCP server for Kaneo.
-**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.
-
-This package lives in the Kaneo monorepo at **`apps/mcp`**.
+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.
## Prerequisites
- Node.js 20+
- A running Kaneo API (for example `http://localhost:1337`) and web app (for device approval UI).
-On the Kaneo server, allow this MCP client’s ID:
+Kaneo allows `kaneo-cli` and `kaneo-mcp` by default, so you usually do not need extra server configuration.
+
+If you want to run this server with a different client ID, allow it on the Kaneo server:
```bash
-DEVICE_AUTH_CLIENT_IDS=kaneo-cli,kaneo-mcp
+DEVICE_AUTH_CLIENT_IDS=kaneo-cli,kaneo-mcp,your-client-id
```
-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).
-
## Environment
| Variable | Description |
@@ -26,9 +24,9 @@ If you omit `DEVICE_AUTH_CLIENT_IDS`, Kaneo defaults to allowing `kaneo-cli` onl
| `KANEO_API_URL` | Kaneo API origin (default `http://localhost:1337`). Do not include `/api`. |
| `KANEO_MCP_CLIENT_ID` | Device-flow client id (default `kaneo-mcp`). Must match `DEVICE_AUTH_CLIENT_IDS` on the server. |
-## Install (published package)
+## Install
-After publishing `@kaneo/mcp` to npm (or a private registry):
+If the package is published to npm or your private registry:
```bash
npm install -g @kaneo/mcp
@@ -41,11 +39,11 @@ Or:
npx @kaneo/mcp
```
-The published tarball includes **`dist/`** and dependencies; `prepublishOnly` runs the TypeScript build before publish.
+The published package includes `dist/`. `prepublishOnly` runs the build before publish.
-## Develop from source (inside this monorepo)
+## Develop from source
-From the **`kaneo/`** directory:
+From the repo root:
```bash
pnpm install
@@ -54,33 +52,34 @@ pnpm --filter @kaneo/mcp run start
pnpm --filter @kaneo/mcp run test
```
-Or with paths:
+Or run it from the package directory:
```bash
pnpm -C apps/mcp run build
```
-The CLI entry is `kaneo-mcp` in `package.json` `bin` → `./dist/index.js`.
-For **Cursor**, point the MCP command at **`…/kaneo/apps/mcp/dist/index.js`** (absolute path after build).
+The CLI entry points to `./dist/index.js`.
+
+For Cursor or another MCP client, point the command at the built file:
+
+```text
+.../kaneo/apps/mcp/dist/index.js
+```
## Authentication
On the first tool call that needs Kaneo, the server:
1. Requests a device code from `POST /api/auth/device/code`
-2. Prints the verification URL and user code to **stderr** (stdout stays clean for MCP)
+2. Prints the verification URL and user code to `stderr`
3. Tries to open the browser
4. Polls `POST /api/auth/device/token` until approved
-5. Stores the access token under `~/.config/kaneo-mcp/credentials.json` (mode `0600`)
+5. Stores the access token at `~/.config/kaneo-mcp/credentials.json` with mode `0600`
## Tools
-Session: `whoami`, `list_workspaces`
-
-Projects: `list_projects`, `get_project`, `create_project`, `update_project`
-
-Tasks: `list_tasks`, `get_task`, `create_task`, `update_task`, `move_task`, `update_task_status`
-
-Comments: `list_task_comments`, `create_task_comment`
-
-Labels: `list_workspace_labels`, `create_label`, `attach_label_to_task`, `detach_label_from_task`
+- Session: `whoami`, `list_workspaces`
+- Projects: `list_projects`, `get_project`, `create_project`, `update_project`
+- Tasks: `list_tasks`, `get_task`, `create_task`, `update_task`, `move_task`, `update_task_status`
+- Comments: `list_task_comments`, `create_task_comment`
+- Labels: `list_workspace_labels`, `create_label`, `attach_label_to_task`, `detach_label_from_task`