Skip to content

The open alternative to Salesforce, designed for AI.

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.ts
index 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.ty
import { 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.ts
index 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.ts
index 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.ts
index 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: