The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Search help center through the docs.twenty.com MCP server (#28405)
Etienne861b9aee4606
diff --git a/packages/twenty-server/src/engine/core-modules/tool/tools/search-help-center-tool/search-help-center-tool.ts b/packages/twenty-server/src/engine/core-modules/tool/tools/search-help-center-tool/search-help-center-tool.tsindex d767632a6dd..f706d6f84b0 100644--- a/packages/twenty-server/src/engine/core-modules/tool/tools/search-help-center-tool/search-help-center-tool.ts+++ b/packages/twenty-server/src/engine/core-modules/tool/tools/search-help-center-tool/search-help-center-tool.ts@@ -10,8 +10,9 @@ import { type ToolInput } from 'src/engine/core-modules/tool/types/tool-input.tyimport { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';import { type ToolExecutionContext } from 'src/engine/core-modules/tool/types/tool-execution-context.type';import { type Tool } from 'src/engine/core-modules/tool/types/tool.type';-import { TwentyConfigService } from 'src/engine/core-modules/twenty-config/twenty-config.service';+const HELP_CENTER_MCP_URL = 'https://docs.twenty.com/mcp';+const HELP_CENTER_MCP_SEARCH_TOOL_NAME = 'search_twenty_documentation';const HELP_CENTER_REQUEST_TIMEOUT_MS = 10_000;const HELP_CENTER_REQUEST_RETRIES = 2;@@ -22,7 +23,6 @@ export class SearchHelpCenterTool implements Tool {inputSchema = SearchHelpCenterInputZodSchema;constructor(- private readonly twentyConfigService: TwentyConfigService,private readonly secureHttpClientService: SecureHttpClientService,) {}@@ -33,21 +33,6 @@ export class SearchHelpCenterTool implements Tool {const { query } = parameters;try {- const MINTLIFY_API_KEY = this.twentyConfigService.get('MINTLIFY_API_KEY');- const MINTLIFY_SUBDOMAIN =- this.twentyConfigService.get('MINTLIFY_SUBDOMAIN');-- const useDirectApi = MINTLIFY_API_KEY && MINTLIFY_SUBDOMAIN;-- const endpoint = useDirectApi- ? `https://api-dsc.mintlify.com/v1/search/${MINTLIFY_SUBDOMAIN}`- : 'https://twenty-help-search.com/search/twenty';-- const headers = {- 'Content-Type': 'application/json',- ...(useDirectApi && { Authorization: `Bearer ${MINTLIFY_API_KEY}` }),- };-const httpClient = this.secureHttpClientService.getHttpClient({timeout: HELP_CENTER_REQUEST_TIMEOUT_MS,retries: HELP_CENTER_REQUEST_RETRIES,@@ -55,9 +40,23 @@ export class SearchHelpCenterTool implements Tool {});const response = await httpClient.post(- endpoint,- { query, pageSize: 10 },- { headers },+ HELP_CENTER_MCP_URL,+ {+ jsonrpc: '2.0',+ id: 1,+ method: 'tools/call',+ params: {+ name: HELP_CENTER_MCP_SEARCH_TOOL_NAME,+ arguments: { query },+ },+ },+ {+ headers: {+ 'Content-Type': 'application/json',+ Accept: 'application/json, text/event-stream',+ },+ responseType: 'text',+ },);const extraction = extractHelpCenterResults(response.data);@@ -66,8 +65,7 @@ export class SearchHelpCenterTool implements Tool {return {success: false,message: `Failed to search help center for "${query}"`,- error:- 'Help center search returned a response in an unrecognized shape',+ error: extraction.error,};}diff --git a/packages/twenty-server/src/engine/core-modules/tool/tools/search-help-center-tool/utils/__tests__/extract-help-center-results.util.spec.ts b/packages/twenty-server/src/engine/core-modules/tool/tools/search-help-center-tool/utils/__tests__/extract-help-center-results.util.spec.tsindex cbe836529e8..238c32ec76a 100644--- a/packages/twenty-server/src/engine/core-modules/tool/tools/search-help-center-tool/utils/__tests__/extract-help-center-results.util.spec.ts+++ b/packages/twenty-server/src/engine/core-modules/tool/tools/search-help-center-tool/utils/__tests__/extract-help-center-results.util.spec.ts@@ -1,56 +1,71 @@import { extractHelpCenterResults } from 'src/engine/core-modules/tool/tools/search-help-center-tool/utils/extract-help-center-results.util';+const buildSseFrame = (message: object) =>+ `event: message\ndata: ${JSON.stringify(message)}\n\n`;++const buildSearchResultText = (index: number) =>+ `Title: Article ${index}\nLink: https://docs.twenty.com/article-${index}\nPage: article-${index}\nContent: Content ${index}`;+describe('extractHelpCenterResults', () => {- it('passes a bare array straight through', () => {- const results = [{ title: 'Importing data' }];+ it('reads the text of each search result and keeps the first five', () => {+ const body = buildSseFrame({+ result: {+ content: [1, 2, 3, 4, 5, 6].map((index) => ({+ type: 'text',+ text: buildSearchResultText(index),+ })),+ },+ jsonrpc: '2.0',+ id: 1,+ });- expect(extractHelpCenterResults(results)).toEqual({+ expect(extractHelpCenterResults(body)).toEqual({isReadable: true,- results,+ results: [1, 2, 3, 4, 5].map(buildSearchResultText),});});- it('unwraps a results envelope', () => {- const results = [{ title: 'Inviting a team member' }];+ it('reports a JSON-RPC error with its message', () => {+ const body = buildSseFrame({+ jsonrpc: '2.0',+ id: 1,+ error: { code: -32602, message: 'Tool nope not found' },+ });- expect(extractHelpCenterResults({ results })).toEqual({- isReadable: true,- results,+ expect(extractHelpCenterResults(body)).toEqual({+ isReadable: false,+ error: 'Tool nope not found',});});- it('reads an empty answer as a real, readable result', () => {- expect(extractHelpCenterResults([])).toEqual({- isReadable: true,- results: [],+ it('reports a tool error with its text', () => {+ const body = buildSseFrame({+ result: {+ content: [{ type: 'text', text: 'No results found' }],+ isError: true,+ },+ jsonrpc: '2.0',+ id: 1,});- expect(extractHelpCenterResults({ results: [] })).toEqual({- isReadable: true,- results: [],++ expect(extractHelpCenterResults(body)).toEqual({+ isReadable: false,+ error: 'No results found',});});- it('reports an unrecognized payload as unreadable rather than empty', () => {- for (const payload of [- { error: 'Rate limit exceeded' },- { results: 'not-an-array' },- 'unexpected',- null,+ it('reports a body without an SSE data line as unreadable', () => {+ for (const body of [+ '<html>Bad Gateway</html>',+ 'event: message\ndata: {not json\n\n',+ { results: [] },undefined,- 0,]) {- expect(extractHelpCenterResults(payload)).toEqual({ isReadable: false });- }- });-- it('never yields a results value whose length is undefined', () => {- for (const payload of [[], { results: [] }, {}, null, 'x']) {- const extraction = extractHelpCenterResults(payload);-- if (extraction.isReadable) {- expect(Array.isArray(extraction.results)).toBe(true);- expect(extraction.results.length).toEqual(expect.any(Number));- }+ expect(extractHelpCenterResults(body)).toEqual({+ isReadable: false,+ error:+ 'Help center search returned a response in an unrecognized shape',+ });}});});diff --git a/packages/twenty-server/src/engine/core-modules/tool/tools/search-help-center-tool/utils/extract-help-center-results.util.ts b/packages/twenty-server/src/engine/core-modules/tool/tools/search-help-center-tool/utils/extract-help-center-results.util.tsindex e2e4eb473ce..f8cef27cb68 100644--- a/packages/twenty-server/src/engine/core-modules/tool/tools/search-help-center-tool/utils/extract-help-center-results.util.ts+++ b/packages/twenty-server/src/engine/core-modules/tool/tools/search-help-center-tool/utils/extract-help-center-results.util.ts@@ -1,19 +1,67 @@-import { isArray, isObject } from '@sniptt/guards';+import { isString } from '@sniptt/guards';+import { isDefined } from 'twenty-shared/utils';+import { z } from 'zod';++const HELP_CENTER_MAX_RESULTS = 5;+const SSE_DATA_PREFIX = 'data:';+const UNRECOGNIZED_SHAPE_ERROR =+ 'Help center search returned a response in an unrecognized shape';++const HelpCenterJsonRpcResponseZodSchema = z.union([+ z.object({ error: z.object({ message: z.string() }) }),+ z.object({+ result: z.object({+ isError: z.boolean().optional(),+ content: z.array(z.object({ text: z.string().optional() })),+ }),+ }),+]);export type HelpCenterResultsExtraction =- | { isReadable: true; results: unknown[] }- | { isReadable: false };+ | { isReadable: true; results: string[] }+ | { isReadable: false; error: string };++const parseSseData = (body: string): unknown => {+ const dataLine = body+ .split('\n')+ .find((line) => line.startsWith(SSE_DATA_PREFIX));++ if (!isDefined(dataLine)) {+ return undefined;+ }++ try {+ return JSON.parse(dataLine.slice(SSE_DATA_PREFIX.length));+ } catch {+ return undefined;+ }+};export const extractHelpCenterResults = (- data: unknown,+ body: unknown,): HelpCenterResultsExtraction => {- if (isArray(data)) {- return { isReadable: true, results: data };+ const parsed = HelpCenterJsonRpcResponseZodSchema.safeParse(+ isString(body) ? parseSseData(body) : undefined,+ );++ if (!parsed.success) {+ return { isReadable: false, error: UNRECOGNIZED_SHAPE_ERROR };}- if (isObject(data) && 'results' in data && isArray(data.results)) {- return { isReadable: true, results: data.results };+ if ('error' in parsed.data) {+ return { isReadable: false, error: parsed.data.error.message };+ }++ const texts = parsed.data.result.content+ .map((item) => item.text)+ .filter(isDefined);++ if (parsed.data.result.isError) {+ return {+ isReadable: false,+ error: texts.join('\n') || UNRECOGNIZED_SHAPE_ERROR,+ };}- return { isReadable: false };+ return { isReadable: true, results: texts.slice(0, HELP_CENTER_MAX_RESULTS) };};diff --git a/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts b/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.tsindex 60ed0502b54..2d48cb2710c 100644--- a/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts+++ b/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts@@ -2376,28 +2376,6 @@ export class ConfigVariables {@IsOptional()IS_ONBOARDING_AI_CHAT_ENABLED = false;- @ConfigVariablesMetadata({- group: ConfigVariablesGroup.ADVANCED_SETTINGS,- isSensitive: true,- description: 'Mintlify API key for documentation search',- isEnvOnly: true,- isHiddenInAdminPanel: true,- type: ConfigVariableType.STRING,- })- @IsOptional()- MINTLIFY_API_KEY: string;-- @ConfigVariablesMetadata({- group: ConfigVariablesGroup.ADVANCED_SETTINGS,- isSensitive: true,- description: 'Mintlify subdomain for documentation search',- isEnvOnly: true,- isHiddenInAdminPanel: true,- type: ConfigVariableType.STRING,- })- @IsOptional()- MINTLIFY_SUBDOMAIN: string;-@ConfigVariablesMetadata({group: ConfigVariablesGroup.AWS_SES_SETTINGS,description: