mirror of https://github.com/ghostfolio/ghostfolio
Thomas Kaul
5 days ago
committed by
GitHub
GitHub
46 changed files with 1038 additions and 100 deletions
@ -0,0 +1,42 @@ |
|||||
|
import { AiService } from '@ghostfolio/api/app/endpoints/ai/ai.service'; |
||||
|
import { Impersonation } from '@ghostfolio/api/decorators/impersonation.decorator'; |
||||
|
import { RequiresScopeOfAccess } from '@ghostfolio/api/decorators/requires-scope-of-access.decorator'; |
||||
|
import { McpToolExceptionFilter } from '@ghostfolio/api/filters/mcp-tool-exception.filter'; |
||||
|
import { DEFAULT_LANGUAGE_CODE } from '@ghostfolio/common/config'; |
||||
|
import { scopes } from '@ghostfolio/common/scopes'; |
||||
|
import type { ImpersonationContext } from '@ghostfolio/common/types'; |
||||
|
|
||||
|
import { UseFilters } from '@nestjs/common'; |
||||
|
import { McpController, Tool } from '@rekog/mcp-nest'; |
||||
|
|
||||
|
@McpController() |
||||
|
@UseFilters(McpToolExceptionFilter) |
||||
|
export class GhostfolioMcpController { |
||||
|
public constructor(private readonly aiService: AiService) {} |
||||
|
|
||||
|
@RequiresScopeOfAccess(scopes.portfolioRead) |
||||
|
@Tool({ |
||||
|
annotations: { |
||||
|
openWorldHint: false, |
||||
|
readOnlyHint: true, |
||||
|
title: 'Get portfolio' |
||||
|
}, |
||||
|
description: `Gives the holdings of the portfolio with these columns: ${AiService.getHoldingsTableColumnNames().join( |
||||
|
', ' |
||||
|
)}.`,
|
||||
|
name: 'get-portfolio' |
||||
|
}) |
||||
|
public async getPortfolio( |
||||
|
@Impersonation() { filters, userId, userSettings }: ImpersonationContext |
||||
|
) { |
||||
|
const prompt = await this.aiService.getPrompt({ |
||||
|
filters, |
||||
|
userId, |
||||
|
languageCode: userSettings.language ?? DEFAULT_LANGUAGE_CODE, |
||||
|
mode: 'portfolio', |
||||
|
userCurrency: userSettings.baseCurrency |
||||
|
}); |
||||
|
|
||||
|
return { content: [{ text: prompt, type: 'text' as const }] }; |
||||
|
} |
||||
|
} |
||||
@ -0,0 +1,47 @@ |
|||||
|
import { AiModule } from '@ghostfolio/api/app/endpoints/ai/ai.module'; |
||||
|
import { environment } from '@ghostfolio/api/environments/environment'; |
||||
|
import { ConfigurationModule } from '@ghostfolio/api/services/configuration/configuration.module'; |
||||
|
import { ConfigurationService } from '@ghostfolio/api/services/configuration/configuration.service'; |
||||
|
import { MCP_ENDPOINT } from '@ghostfolio/common/config'; |
||||
|
|
||||
|
import { Module } from '@nestjs/common'; |
||||
|
import { |
||||
|
MCP_STRATEGY, |
||||
|
McpStrategy, |
||||
|
StreamableHttpTransport |
||||
|
} from '@rekog/mcp-nest'; |
||||
|
|
||||
|
import { GhostfolioMcpController } from './mcp.controller'; |
||||
|
|
||||
|
@Module({ |
||||
|
controllers: [GhostfolioMcpController], |
||||
|
imports: [AiModule, ConfigurationModule], |
||||
|
providers: [ |
||||
|
{ |
||||
|
inject: [ConfigurationService], |
||||
|
provide: MCP_STRATEGY, |
||||
|
useFactory: (configurationService: ConfigurationService) => { |
||||
|
const { hostname } = new URL(configurationService.get('ROOT_URL')); |
||||
|
|
||||
|
return new McpStrategy({ |
||||
|
instructions: |
||||
|
'Ghostfolio is a wealth management application. The tools read the portfolio of the user who granted the access. They give no monetary value.', |
||||
|
name: 'ghostfolio', |
||||
|
title: 'Ghostfolio', |
||||
|
transports: [ |
||||
|
new StreamableHttpTransport({ |
||||
|
endpoint: MCP_ENDPOINT, |
||||
|
security: { |
||||
|
allowedHosts: [hostname], |
||||
|
allowedOrigins: [hostname] |
||||
|
} |
||||
|
}) |
||||
|
], |
||||
|
version: environment.version, |
||||
|
websiteUrl: 'https://ghostfol.io' |
||||
|
}); |
||||
|
} |
||||
|
} |
||||
|
] |
||||
|
}) |
||||
|
export class McpModule {} |
||||
@ -0,0 +1,18 @@ |
|||||
|
import { REQUIRES_SCOPE_KEY } from '@ghostfolio/api/decorators/requires-scope.decorator'; |
||||
|
import { AccessGuard } from '@ghostfolio/api/guards/access.guard'; |
||||
|
import { ScopeGuard } from '@ghostfolio/api/guards/scope.guard'; |
||||
|
import { Scope } from '@ghostfolio/common/scopes'; |
||||
|
|
||||
|
import { applyDecorators, SetMetadata, UseGuards } from '@nestjs/common'; |
||||
|
|
||||
|
/** |
||||
|
* Marks a handler which requires the given scopes of an access, but no |
||||
|
* authenticated user. The access itself is the credential, hence a client of |
||||
|
* the model context protocol can use it. |
||||
|
*/ |
||||
|
export function RequiresScopeOfAccess(...requiredScopes: Scope[]) { |
||||
|
return applyDecorators( |
||||
|
SetMetadata(REQUIRES_SCOPE_KEY, requiredScopes), |
||||
|
UseGuards(AccessGuard, ScopeGuard) |
||||
|
); |
||||
|
} |
||||
@ -0,0 +1,62 @@ |
|||||
|
import { PortfolioSnapshotComputationError } from '@ghostfolio/api/app/portfolio/errors/portfolio-snapshot-computation.error'; |
||||
|
|
||||
|
import { |
||||
|
Catch, |
||||
|
HttpException, |
||||
|
Logger, |
||||
|
RpcExceptionFilter |
||||
|
} from '@nestjs/common'; |
||||
|
import { RpcException } from '@nestjs/microservices'; |
||||
|
import { getReasonPhrase, StatusCodes } from 'http-status-codes'; |
||||
|
import { Observable, throwError } from 'rxjs'; |
||||
|
|
||||
|
/** |
||||
|
* Turns an exception of a tool of the model context protocol into an error of |
||||
|
* the caller. Only a message which is written for the caller is passed on, so |
||||
|
* that an unexpected exception cannot expose internals of the application. |
||||
|
*/ |
||||
|
@Catch() |
||||
|
export class McpToolExceptionFilter implements RpcExceptionFilter { |
||||
|
private readonly logger = new Logger(McpToolExceptionFilter.name); |
||||
|
|
||||
|
public catch(exception: unknown): Observable<never> { |
||||
|
this.logger.error(exception); |
||||
|
|
||||
|
if (exception instanceof RpcException) { |
||||
|
return throwError(() => { |
||||
|
return exception.getError(); |
||||
|
}); |
||||
|
} |
||||
|
|
||||
|
return throwError(() => { |
||||
|
return { message: this.getMessage(exception), status: 'error' }; |
||||
|
}); |
||||
|
} |
||||
|
|
||||
|
private getMessage(exception: unknown) { |
||||
|
// The message of an exception can carry internals, for example the
|
||||
|
// property names of a data transfer object of a failed validation, hence
|
||||
|
// the reason phrase of the status is passed on instead
|
||||
|
return this.getReasonPhraseOfStatus(this.getStatus(exception)); |
||||
|
} |
||||
|
|
||||
|
private getReasonPhraseOfStatus(statusCode: number) { |
||||
|
try { |
||||
|
return getReasonPhrase(statusCode); |
||||
|
} catch { |
||||
|
return getReasonPhrase(StatusCodes.INTERNAL_SERVER_ERROR); |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
private getStatus(exception: unknown) { |
||||
|
if (exception instanceof PortfolioSnapshotComputationError) { |
||||
|
return StatusCodes.SERVICE_UNAVAILABLE; |
||||
|
} |
||||
|
|
||||
|
if (exception instanceof HttpException) { |
||||
|
return exception.getStatus(); |
||||
|
} |
||||
|
|
||||
|
return StatusCodes.INTERNAL_SERVER_ERROR; |
||||
|
} |
||||
|
} |
||||
@ -0,0 +1,42 @@ |
|||||
|
import { getRequest } from '@ghostfolio/api/helper/execution-context.helper'; |
||||
|
import type { RequestWithUser } from '@ghostfolio/common/types'; |
||||
|
|
||||
|
import { |
||||
|
CanActivate, |
||||
|
ExecutionContext, |
||||
|
HttpException, |
||||
|
Injectable |
||||
|
} from '@nestjs/common'; |
||||
|
import { StatusCodes, getReasonPhrase } from 'http-status-codes'; |
||||
|
|
||||
|
/** |
||||
|
* Admits a request which is identified by an access instead of by an |
||||
|
* authenticated user, for example a request of a client of the model context |
||||
|
* protocol. The access is the bearer token, which is the credential such a |
||||
|
* client expects and which a token of an authorization server can replace |
||||
|
* later. |
||||
|
* |
||||
|
* The authorization middleware of the endpoint resolves the bearer token |
||||
|
* before the transport reads the message, because the specification asks for |
||||
|
* the status 401 and a challenge, which a guard can no longer set. This guard |
||||
|
* therefore accepts the context of that middleware only. It never accepts the |
||||
|
* context of the ImpersonationGuard, which comes from the Impersonation-Id |
||||
|
* header of an authenticated user and is not a bearer token. |
||||
|
*/ |
||||
|
@Injectable() |
||||
|
export class AccessGuard implements CanActivate { |
||||
|
public canActivate(context: ExecutionContext) { |
||||
|
const request = getRequest<RequestWithUser>(context); |
||||
|
|
||||
|
if (!request?.impersonationOfBearerToken?.isActive) { |
||||
|
throw new HttpException( |
||||
|
getReasonPhrase(StatusCodes.FORBIDDEN), |
||||
|
StatusCodes.FORBIDDEN |
||||
|
); |
||||
|
} |
||||
|
|
||||
|
request.impersonation = request.impersonationOfBearerToken; |
||||
|
|
||||
|
return true; |
||||
|
} |
||||
|
} |
||||
@ -0,0 +1,18 @@ |
|||||
|
const PREFIX_OF_BEARER_TOKEN = 'bearer '; |
||||
|
|
||||
|
/** |
||||
|
* Gives the identifier of the access which the authorization header carries as |
||||
|
* a bearer token. The scheme is compared without regard to the case, because |
||||
|
* RFC 7235 defines it as case-insensitive. |
||||
|
*/ |
||||
|
export function getAccessIdOfBearerToken(authorization?: string) { |
||||
|
if (typeof authorization !== 'string') { |
||||
|
return undefined; |
||||
|
} |
||||
|
|
||||
|
const value = authorization.trim(); |
||||
|
|
||||
|
return value.toLowerCase().startsWith(PREFIX_OF_BEARER_TOKEN) |
||||
|
? value.slice(PREFIX_OF_BEARER_TOKEN.length).trim() || undefined |
||||
|
: undefined; |
||||
|
} |
||||
@ -0,0 +1,19 @@ |
|||||
|
import { ExecutionContext } from '@nestjs/common'; |
||||
|
|
||||
|
/** |
||||
|
* Gives the underlying HTTP request of a request of any kind. A tool of the |
||||
|
* model context protocol is a message handler, hence its execution context is |
||||
|
* not of the kind http and the request has to be taken from the context of the |
||||
|
* message instead. |
||||
|
*/ |
||||
|
export function getRequest<T>(context: ExecutionContext): T | undefined { |
||||
|
if (context.getType() === 'http') { |
||||
|
return context.switchToHttp().getRequest<T>(); |
||||
|
} |
||||
|
|
||||
|
const contextOfMessage = context.switchToRpc().getContext<{ |
||||
|
getRawRequest?: <U>() => U | undefined; |
||||
|
}>(); |
||||
|
|
||||
|
return contextOfMessage?.getRawRequest?.<T>(); |
||||
|
} |
||||
@ -0,0 +1,61 @@ |
|||||
|
import { getAccessIdOfBearerToken } from '@ghostfolio/api/helper/bearer-token.helper'; |
||||
|
import { ImpersonationService } from '@ghostfolio/api/services/impersonation/impersonation.service'; |
||||
|
import { HEADER_KEY_TOKEN, MCP_REALM } from '@ghostfolio/common/config'; |
||||
|
import type { ImpersonationContext } from '@ghostfolio/common/types'; |
||||
|
|
||||
|
import { NextFunction, Request, Response } from 'express'; |
||||
|
import { getReasonPhrase, StatusCodes } from 'http-status-codes'; |
||||
|
|
||||
|
/** |
||||
|
* Authenticates a request of a client of the model context protocol before the |
||||
|
* transport reads it. The specification tells a server to answer an |
||||
|
* unauthorized request with the status 401 and a challenge, hence the answer |
||||
|
* cannot come from a guard: a guard runs while the transport dispatches the |
||||
|
* message and can no longer set the status of the response. |
||||
|
* |
||||
|
* The challenge names no resource metadata, because Ghostfolio has no |
||||
|
* authorization server. A client which reads the challenge asks the user for |
||||
|
* the identifier of the access instead of starting a flow which would fail. |
||||
|
*/ |
||||
|
export function createMcpAuthorizationMiddleware( |
||||
|
impersonationService: ImpersonationService |
||||
|
) { |
||||
|
return async ( |
||||
|
request: Request & { impersonationOfBearerToken?: ImpersonationContext }, |
||||
|
response: Response, |
||||
|
next: NextFunction |
||||
|
) => { |
||||
|
const accessId = getAccessIdOfBearerToken( |
||||
|
request.headers[HEADER_KEY_TOKEN.toLowerCase()] as string |
||||
|
); |
||||
|
|
||||
|
const impersonation = await impersonationService.resolve({ |
||||
|
impersonationId: accessId, |
||||
|
types: ['MCP'] |
||||
|
}); |
||||
|
|
||||
|
if (!impersonation.isActive) { |
||||
|
const parameters = [`realm="${MCP_REALM}"`]; |
||||
|
|
||||
|
if (accessId) { |
||||
|
parameters.push( |
||||
|
'error="invalid_token"', |
||||
|
'error_description="The access cannot be resolved"' |
||||
|
); |
||||
|
} |
||||
|
|
||||
|
response.setHeader('WWW-Authenticate', `Bearer ${parameters.join(', ')}`); |
||||
|
|
||||
|
return response.status(StatusCodes.UNAUTHORIZED).json({ |
||||
|
error: getReasonPhrase(StatusCodes.UNAUTHORIZED), |
||||
|
message: 'A valid access is required as a bearer token' |
||||
|
}); |
||||
|
} |
||||
|
|
||||
|
// The guard of the route reads the resolved context from the same request,
|
||||
|
// hence the access is looked up once
|
||||
|
request.impersonationOfBearerToken = impersonation; |
||||
|
|
||||
|
return next(); |
||||
|
}; |
||||
|
} |
||||
@ -1 +0,0 @@ |
|||||
export type AccessType = 'PRIVATE' | 'PUBLIC'; |
|
||||
@ -0,0 +1,12 @@ |
|||||
|
-- CreateEnum |
||||
|
CREATE TYPE "AccessType" AS ENUM ('MCP', 'PRIVATE', 'PUBLIC'); |
||||
|
|
||||
|
-- AlterTable |
||||
|
ALTER TABLE "Access" ADD COLUMN "type" "AccessType" NOT NULL DEFAULT 'PRIVATE'; |
||||
|
|
||||
|
-- Derive the type from the grantee of the existing accesses |
||||
|
UPDATE "Access" |
||||
|
SET "type" = CASE |
||||
|
WHEN "granteeUserId" IS NULL THEN 'PUBLIC'::"AccessType" |
||||
|
ELSE 'PRIVATE'::"AccessType" |
||||
|
END; |
||||
Loading…
Reference in new issue