Add MCP setup guidance and OAuth flow

apps/api/src/api/endpoints.test.ts

@@ -208,4 +208,49 @@ describe('api endpoint map', () => {
             await runningServer.close();
         }
     });
+
+    it('serves MCP OAuth discovery metadata and challenges unauthenticated MCP requests', async () => {
+        const server = buildServer(testServerConfig(), testLogger(), {
+            knex: {},
+            db: {}
+        } as never);
+        const runningServer = await server.listen(0, '127.0.0.1');
+
+        try {
+            const port = runningServer.address?.port;
+            expect(port).toBeTypeOf('number');
+
+            const baseUrl = `http://127.0.0.1:${port}`;
+            const authorizationServer = await fetch(
+                `${baseUrl}/.well-known/oauth-authorization-server`
+            );
+            await expect(authorizationServer.json()).resolves.toMatchObject({
+                issuer: 'http://localhost:3000',
+                authorization_endpoint:
+                    'http://localhost:3000/mcp/oauth/authorize',
+                token_endpoint:
+                    'http://localhost:3000/external-api/oauth/token',
+                registration_endpoint:
+                    'http://localhost:3000/external-api/oauth/register',
+                code_challenge_methods_supported: ['S256']
+            });
+
+            const protectedResource = await fetch(
+                `${baseUrl}/.well-known/oauth-protected-resource/external-api/mcp`
+            );
+            await expect(protectedResource.json()).resolves.toMatchObject({
+                resource: 'http://localhost:3000/external-api/mcp',
+                authorization_servers: ['http://localhost:3000'],
+                scopes_supported: ['mcp']
+            });
+
+            const mcp = await fetch(`${baseUrl}/api/mcp`, { method: 'POST' });
+            expect(mcp.status).toBe(401);
+            expect(mcp.headers.get('www-authenticate')).toBe(
+                'Bearer resource_metadata="http://localhost:3000/.well-known/oauth-protected-resource/external-api/mcp"'
+            );
+        } finally {
+            await runningServer.close();
+        }
+    });
 });

apps/api/src/api/endpoints.ts

@@ -139,6 +139,44 @@ export const RevokeApiKeyEndpoint = api.users.revokeApiKey
     .tags('api-keys')
     .operationId('revokeApiKey');
 
+export const ListMcpOAuthConnectionsEndpoint = api.users.listMcpOAuthConnections
+    .authorize(PrincipalSchema)
+    .inject({ db: DbToken })
+    .summary('List MCP connections')
+    .description('Lists active MCP OAuth connections for the current user.')
+    .tags('mcp')
+    .operationId('listMcpOAuthConnections');
+
+export const RevokeMcpOAuthConnectionEndpoint =
+    api.users.revokeMcpOAuthConnection
+        .authorize(PrincipalSchema)
+        .inject({ db: DbToken })
+        .summary('Revoke MCP connection')
+        .description(
+            'Revokes an MCP OAuth connection owned by the current user.'
+        )
+        .tags('mcp')
+        .operationId('revokeMcpOAuthConnection');
+
+export const McpOAuthAuthorizationRequestEndpoint =
+    api.oauth.authorizationRequest
+        .authorize(PrincipalSchema)
+        .inject({ db: DbToken })
+        .summary('MCP OAuth authorization request')
+        .description(
+            'Validates an MCP OAuth authorization request before user approval.'
+        )
+        .tags('mcp')
+        .operationId('mcpOAuthAuthorizationRequest');
+
+export const McpOAuthAuthorizeEndpoint = api.oauth.authorize
+    .authorize(PrincipalSchema)
+    .inject({ db: DbToken })
+    .summary('Approve MCP OAuth')
+    .description('Approves an MCP OAuth authorization request for the user.')
+    .tags('mcp')
+    .operationId('mcpOAuthAuthorize');
+
 export const LinkTelegramEndpoint = api.telegram.link
     .inject({ db: DbToken, config: ConfigToken })
     .summary('Link Telegram account')
@@ -413,7 +451,13 @@ export const endpoints = {
         disconnectTelegram: DisconnectTelegramEndpoint,
         listApiKeys: ListApiKeysEndpoint,
         createApiKey: CreateApiKeyEndpoint,
-        revokeApiKey: RevokeApiKeyEndpoint
+        revokeApiKey: RevokeApiKeyEndpoint,
+        listMcpOAuthConnections: ListMcpOAuthConnectionsEndpoint,
+        revokeMcpOAuthConnection: RevokeMcpOAuthConnectionEndpoint
+    },
+    oauth: {
+        authorizationRequest: McpOAuthAuthorizationRequestEndpoint,
+        authorize: McpOAuthAuthorizeEndpoint
     },
     telegram: {
         link: LinkTelegramEndpoint,

apps/api/src/api/handlers/index.ts

@@ -23,6 +23,12 @@ import {
     updateCategoryHandler
 } from './categories.js';
 import { convertCurrencyHandler, listCurrenciesHandler } from './currencies.js';
+import {
+    listMcpOAuthConnectionsHandler,
+    mcpOAuthAuthorizationRequestHandler,
+    mcpOAuthAuthorizeHandler,
+    revokeMcpOAuthConnectionHandler
+} from './mcp-oauth.js';
 import {
     createTelegramLinkTokenHandler,
     disconnectTelegramHandler,
@@ -77,7 +83,13 @@ export const handlers = {
         disconnectTelegram: disconnectTelegramHandler,
         listApiKeys: listApiKeysHandler,
         createApiKey: createApiKeyHandler,
-        revokeApiKey: revokeApiKeyHandler
+        revokeApiKey: revokeApiKeyHandler,
+        listMcpOAuthConnections: listMcpOAuthConnectionsHandler,
+        revokeMcpOAuthConnection: revokeMcpOAuthConnectionHandler
+    },
+    oauth: {
+        authorizationRequest: mcpOAuthAuthorizationRequestHandler,
+        authorize: mcpOAuthAuthorizeHandler
     },
     telegram: {
         link: linkTelegramHandler,

apps/api/src/api/handlers/mcp-oauth.ts

@@ -0,0 +1,61 @@
+import { ActionResult, type Handler } from '@cleverbrush/server';
+import {
+    authorizeMcpOAuthRequest,
+    getMcpOAuthAuthorizationRequest,
+    listMcpOAuthConnections,
+    McpOAuthConnectionNotFoundError,
+    OAuthError,
+    revokeMcpOAuthConnection
+} from '../../application/mcp-oauth.js';
+import type {
+    ListMcpOAuthConnectionsEndpoint,
+    McpOAuthAuthorizationRequestEndpoint,
+    McpOAuthAuthorizeEndpoint,
+    RevokeMcpOAuthConnectionEndpoint
+} from '../endpoints.js';
+
+export const listMcpOAuthConnectionsHandler: Handler<
+    typeof ListMcpOAuthConnectionsEndpoint
+> = async ({ principal }, { db }) => {
+    return listMcpOAuthConnections(db, principal.userId);
+};
+
+export const revokeMcpOAuthConnectionHandler: Handler<
+    typeof RevokeMcpOAuthConnectionEndpoint
+> = async ({ params, principal }, { db }) => {
+    try {
+        await revokeMcpOAuthConnection(db, principal.userId, params.id);
+        return ActionResult.noContent();
+    } catch (err) {
+        if (err instanceof McpOAuthConnectionNotFoundError) {
+            return ActionResult.notFound({ message: err.message });
+        }
+        throw err;
+    }
+};
+
+export const mcpOAuthAuthorizationRequestHandler: Handler<
+    typeof McpOAuthAuthorizationRequestEndpoint
+> = async ({ query }, { db }) => {
+    try {
+        return await getMcpOAuthAuthorizationRequest(db, query);
+    } catch (err) {
+        if (err instanceof OAuthError) {
+            return ActionResult.badRequest({ message: err.message });
+        }
+        throw err;
+    }
+};
+
+export const mcpOAuthAuthorizeHandler: Handler<
+    typeof McpOAuthAuthorizeEndpoint
+> = async ({ body, principal }, { db }) => {
+    try {
+        return await authorizeMcpOAuthRequest(db, principal.userId, body);
+    } catch (err) {
+        if (err instanceof OAuthError) {
+            return ActionResult.badRequest({ message: err.message });
+        }
+        throw err;
+    }
+};