docs: add MCP OAuth documentation and fix lint

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -102,10 +102,11 @@ curl -s -X POST "https://gitea.jeanlucmakiola.de/api/v1/repos/makiolaj/GearBox/a
 - **Programmatic access**: API keys created in Settings > API Keys. Pass via `X-API-Key` header.
 - **Public read**: All GET endpoints work without auth. POST/PUT/DELETE require auth.
 - **Auth routes**: `/api/auth/login`, `/api/auth/logout`, `/api/auth/setup`, `/api/auth/me`, `/api/auth/password`, `/api/auth/keys`.
+- **MCP OAuth**: OAuth 2.1 + PKCE for Claude mobile/web. Endpoints at `/oauth/*`. Uses existing GearBox credentials.
 
 ## MCP Server
 
-GearBox includes a built-in MCP server for integration with Claude Code and Claude Desktop. Enabled by default, disable with `GEARBOX_MCP=false`. Authenticated via API key.
+GearBox includes a built-in MCP server for integration with Claude Code and Claude Desktop. Enabled by default, disable with `GEARBOX_MCP=false`. Authenticated via API key or OAuth 2.1 Bearer token.
 
 ### Tools (19 total)
 
@@ -167,4 +168,23 @@ GearBox includes a built-in MCP server for integration with Claude Code and Clau
 }
 ```
 
-Generate an API key from Settings > API Keys after logging in.
+Generate an API key from Settings > API Keys after logging in.
+
+### OAuth Authentication (Claude Mobile / claude.ai)
+
+GearBox supports OAuth 2.1 Authorization Code + PKCE for MCP connections from Claude mobile app and claude.ai. The OAuth flow is automatic — Claude handles discovery and token exchange.
+
+**Required environment variable for production:**
+```bash
+GEARBOX_URL=https://your-gearbox-domain.com  # Used as OAuth issuer URL
+```
+
+**OAuth endpoints:**
+- `GET /.well-known/oauth-authorization-server` — Discovery metadata
+- `POST /oauth/register` — Dynamic Client Registration
+- `GET/POST /oauth/authorize` — Authorization with login form
+- `POST /oauth/token` — Token exchange and refresh
+
+**Both auth methods work simultaneously:**
+- **API key** (`X-API-Key` header) — Claude Code, scripts, programmatic access
+- **OAuth Bearer token** (`Authorization: Bearer` header) — Claude mobile, claude.ai

src/db/schema.ts

@@ -154,7 +154,9 @@ export const oauthTokens = sqliteTable("oauth_tokens", {
 	refreshTokenHash: text("refresh_token_hash").notNull().unique(),
 	clientId: text("client_id").notNull(),
 	expiresAt: integer("expires_at", { mode: "timestamp" }).notNull(), // access token expiry
-	refreshExpiresAt: integer("refresh_expires_at", { mode: "timestamp" }).notNull(), // refresh token expiry
+	refreshExpiresAt: integer("refresh_expires_at", {
+		mode: "timestamp",
+	}).notNull(), // refresh token expiry
 	createdAt: integer("created_at", { mode: "timestamp" })
 		.notNull()
 		.$defaultFn(() => new Date()),

src/server/index.ts

@@ -8,10 +8,10 @@ import { authRoutes } from "./routes/auth.ts";
 import { categoryRoutes } from "./routes/categories.ts";
 import { imageRoutes } from "./routes/images.ts";
 import { itemRoutes } from "./routes/items.ts";
+import { oauthRoutes, wellKnownRoute } from "./routes/oauth.ts";
 import { settingsRoutes } from "./routes/settings.ts";
 import { setupRoutes } from "./routes/setups.ts";
 import { threadRoutes } from "./routes/threads.ts";
-import { oauthRoutes, wellKnownRoute } from "./routes/oauth.ts";
 import { totalRoutes } from "./routes/totals.ts";
 
 // Seed default data on startup

src/server/mcp/index.ts

@@ -117,7 +117,8 @@ mcpRoutes.use("/*", async (c, next) => {
 
 	// No auth provided — return 401 with WWW-Authenticate to trigger OAuth flow
 	return c.text("Unauthorized", 401, {
-		"WWW-Authenticate": 'Bearer resource_metadata="/.well-known/oauth-authorization-server"',
+		"WWW-Authenticate":
+			'Bearer resource_metadata="/.well-known/oauth-authorization-server"',
 	});
 });
 

src/server/routes/oauth.ts

@@ -22,7 +22,8 @@ function escapeHtml(str: string): string {
 }
 
 function getBaseUrl(c: any): string {
-	if (process.env.GEARBOX_URL) return process.env.GEARBOX_URL.replace(/\/$/, "");
+	if (process.env.GEARBOX_URL)
+		return process.env.GEARBOX_URL.replace(/\/$/, "");
 	return new URL(c.req.url).origin;
 }
 
@@ -111,7 +112,10 @@ oauthRoutes.post("/register", async (c) => {
 		!Array.isArray(body.redirect_uris) ||
 		body.redirect_uris.length === 0
 	) {
-		return c.json({ error: "redirect_uris is required and must be a non-empty array" }, 400);
+		return c.json(
+			{ error: "redirect_uris is required and must be a non-empty array" },
+			400,
+		);
 	}
 
 	const clientName = body.client_name || "Unknown Client";
@@ -227,7 +231,13 @@ oauthRoutes.post("/token", async (c) => {
 		const clientId = body.client_id as string;
 		const redirectUri = body.redirect_uri as string;
 
-		const result = await exchangeCode(db, code, codeVerifier, clientId, redirectUri);
+		const result = await exchangeCode(
+			db,
+			code,
+			codeVerifier,
+			clientId,
+			redirectUri,
+		);
 		if (!result) {
 			return c.json({ error: "invalid_grant" }, 400);
 		}

tests/routes/oauth.test.ts

@@ -1,9 +1,9 @@
-import { createHash, randomBytes } from "node:crypto";
 import { beforeEach, describe, expect, it } from "bun:test";
+import { createHash, randomBytes } from "node:crypto";
 import { Hono } from "hono";
-import { createUser } from "../../src/server/services/auth.service.ts";
-import { oauthRoutes, wellKnownRoute } from "../../src/server/routes/oauth.ts";
 import { mcpRoutes } from "../../src/server/mcp/index.ts";
+import { oauthRoutes, wellKnownRoute } from "../../src/server/routes/oauth.ts";
+import { createUser } from "../../src/server/services/auth.service.ts";
 import { createTestDb } from "../helpers/db.ts";
 
 function createTestApp() {
@@ -59,7 +59,10 @@ describe("OAuth Routes", () => {
 			expect(body.token_endpoint).toContain("/oauth/token");
 			expect(body.registration_endpoint).toContain("/oauth/register");
 			expect(body.response_types_supported).toEqual(["code"]);
-			expect(body.grant_types_supported).toEqual(["authorization_code", "refresh_token"]);
+			expect(body.grant_types_supported).toEqual([
+				"authorization_code",
+				"refresh_token",
+			]);
 			expect(body.code_challenge_methods_supported).toEqual(["S256"]);
 			expect(body.token_endpoint_auth_methods_supported).toEqual(["none"]);
 		});
@@ -276,7 +279,9 @@ describe("OAuth Routes", () => {
 					}).toString(),
 				},
 			);
-			const code = new URL(authRes.headers.get("location")!).searchParams.get("code")!;
+			const code = new URL(authRes.headers.get("location")!).searchParams.get(
+				"code",
+			)!;
 
 			// 3. Exchange code for tokens
 			const tokenRes = await app.request("/oauth/token", {