@atlassian-dc-mcp/confluence 0.12.2 → 0.13.0

package/src/confluence-response-mapper.ts

@@ -0,0 +1,104 @@
+export type ConfluenceBodyMode = 'storage' | 'text' | 'none';
+export type ConfluenceMutationOutputMode = 'ack' | 'full';
+
+const ENTITY_MAP: Record<string, string> = {
+  '&nbsp;': ' ',
+  '&amp;': '&',
+  '&lt;': '<',
+  '&gt;': '>',
+  '&quot;': '"',
+  '&#39;': "'",
+};
+
+function decodeHtmlEntities(value: string): string {
+  return value
+    .replace(/&(nbsp|amp|lt|gt|quot);|&#39;/g, match => ENTITY_MAP[match] ?? match)
+    .replace(/&#(\d+);/g, (_, code) => {
+      const parsed = Number.parseInt(code, 10);
+      return Number.isNaN(parsed) ? '' : String.fromCodePoint(parsed);
+    });
+}
+
+function truncateText(value: string, maxBodyChars?: number): { value: string; truncated?: boolean; originalLength?: number } {
+  if (maxBodyChars === undefined || maxBodyChars < 1 || value.length <= maxBodyChars) {
+    return { value };
+  }
+
+  return {
+    value: value.slice(0, maxBodyChars).trimEnd(),
+    truncated: true,
+    originalLength: value.length,
+  };
+}
+
+export function confluenceStorageToText(storageValue: string): string {
+  const withLineBreaks = storageValue
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<li\b[^>]*>/gi, '\n- ')
+    .replace(/<\/(?:p|div|h[1-6]|li|tr|td|th|blockquote|pre|ul|ol|table|section|article)\s*>/gi, '\n')
+    .replace(/<[^>]+>/g, ' ');
+
+  return decodeHtmlEntities(withLineBreaks)
+    .replace(/\r\n/g, '\n')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/[ \t]{2,}/g, ' ')
+    .trim();
+}
+
+function getContentUrl(content: any): string | undefined {
+  const self = content?._links?.self;
+  if (typeof self === 'string') {
+    return self;
+  }
+
+  const base = content?._links?.base;
+  const webui = content?._links?.webui;
+  if (typeof base === 'string' && typeof webui === 'string') {
+    return `${base}${webui}`;
+  }
+
+  return undefined;
+}
+
+export function shapeConfluenceContent(content: any, bodyMode: ConfluenceBodyMode = 'storage', maxBodyChars?: number) {
+  if (!content || typeof content !== 'object' || bodyMode === 'storage') {
+    return content;
+  }
+
+  const { body, ...rest } = content as Record<string, any>;
+
+  if (bodyMode === 'none') {
+    return rest;
+  }
+
+  const storageValue = typeof body?.storage?.value === 'string' ? body.storage.value : undefined;
+  if (storageValue === undefined) {
+    return rest;
+  }
+
+  const textBody = truncateText(confluenceStorageToText(storageValue), maxBodyChars);
+  return {
+    ...rest,
+    body: {
+      text: {
+        value: textBody.value,
+        representation: 'text',
+        ...(textBody.truncated ? { truncated: true, originalLength: textBody.originalLength } : {}),
+      },
+    },
+  };
+}
+
+export function shapeConfluenceMutationAck(content: any) {
+  const url = getContentUrl(content);
+
+  return {
+    ...(content?.id !== undefined ? { id: content.id } : {}),
+    ...(typeof content?.type === 'string' ? { type: content.type } : {}),
+    ...(typeof content?.title === 'string' ? { title: content.title } : {}),
+    ...(typeof content?.space?.key === 'string' ? { spaceKey: content.space.key } : {}),
+    ...(content?.version?.number !== undefined ? { version: content.version.number } : {}),
+    ...(url ? { url } : {}),
+  };
+}

package/src/confluence-service.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 import { ContentResourceService, OpenAPI, SearchService } from './confluence-client/index.js';
 import { handleApiOperation } from '@atlassian-dc-mcp/common';
+import { getDefaultPageSize, getMissingConfig } from './config.js';
+import { ConfluenceBodyMode, shapeConfluenceContent } from './confluence-response-mapper.js';
 
 /**
  * Escapes user input for safe use inside a CQL quoted string.
@@ -31,14 +33,31 @@ export interface ConfluenceContent {
   ancestors?: Array<{ id: string }>;
 }
 
+function resolveToken(token: string | (() => string | undefined), missingTokenMessage: string) {
+  return async () => {
+    const resolvedToken = typeof token === 'function' ? token() : token;
+    if (!resolvedToken) {
+      throw new Error(missingTokenMessage);
+    }
+    return resolvedToken;
+  };
+}
+
 export class ConfluenceService {
+  private readonly getPageSize: () => number;
+
   /**
    * Creates a new ConfluenceService instance
    * @param host The hostname of the Confluence server (e.g., "host.com")
    * @param token The API token for authentication
    * @param fullApiUrl Optional full API URL (e.g., "https://host.com/wiki/"). If provided, host and apiBasePath are ignored.
    */
-  constructor(host: string | undefined, token: string, fullApiUrl?: string) {
+  constructor(
+    host: string | undefined,
+    token: string | (() => string | undefined),
+    fullApiUrl?: string,
+    getPageSize: () => number = getDefaultPageSize,
+  ) {
     if (fullApiUrl) {
       OpenAPI.BASE = fullApiUrl;
     } else if (host) {
@@ -46,15 +65,16 @@ export class ConfluenceService {
     } else {
       throw new Error('Either host or fullApiUrl must be provided');
     }
-    OpenAPI.TOKEN = token;
+    OpenAPI.TOKEN = resolveToken(token, 'Missing required environment variable: CONFLUENCE_API_TOKEN');
     OpenAPI.VERSION = '1.0';
+    this.getPageSize = getPageSize;
   }
   /**
    * Get a Confluence page by ID
    * @param contentId The ID of the page to retrieve
    * @param expand Optional comma-separated list of properties to expand
    */
-  async getContent(contentId: string, expand?: string) {
+  async getContentRaw(contentId: string, expand?: string) {
     const expandValue = expand || 'body.storage';
     const finalExpand = expand && !expand.includes('body.storage')
       ? `${expand},body.storage`
@@ -62,6 +82,18 @@ export class ConfluenceService {
     return handleApiOperation(() => ContentResourceService.getContentById(contentId, finalExpand), 'Error getting content');
   }
 
+  async getContent(contentId: string, expand?: string, bodyMode: ConfluenceBodyMode = 'storage', maxBodyChars?: number) {
+    const result = await this.getContentRaw(contentId, expand);
+    if (result.success && result.data) {
+      return {
+        ...result,
+        data: shapeConfluenceContent(result.data, bodyMode, maxBodyChars),
+      };
+    }
+
+    return result;
+  }
+
   /**
    * Search for content in Confluence using CQL
    * @param cql Confluence Query Language string
@@ -69,8 +101,19 @@ export class ConfluenceService {
    * @param start Start index for pagination
    * @param expand Optional comma-separated list of properties to expand
    */
-  async searchContent(cql: string, limit?: number, start?: number, expand?: string) {
-    return handleApiOperation(() => SearchService.search1(undefined, expand, undefined, limit?.toString(), start?.toString(), undefined, cql), 'Error searching for content');
+  async searchContent(cql: string, limit?: number, start?: number, expand?: string, excerpt: 'none' | 'highlight' = 'none') {
+    return handleApiOperation(
+      () => SearchService.search1(
+        undefined,
+        expand,
+        undefined,
+        (limit ?? this.getPageSize()).toString(),
+        start?.toString(),
+        excerpt,
+        cql
+      ),
+      'Error searching for content'
+    );
   }
 
   /**
@@ -97,7 +140,13 @@ export class ConfluenceService {
    * @param start Start index for pagination
    * @param expand Optional comma-separated list of properties to expand
    */
-  async searchSpaces(searchText: string, limit?: number, start?: number, expand?: string) {
+  async searchSpaces(
+    searchText: string,
+    limit?: number,
+    start?: number,
+    expand?: string,
+    excerpt: 'none' | 'highlight' = 'none'
+  ) {
     // Create a CQL query that searches for spaces
     // The correct syntax for space search is: type=space AND title ~ "searchText"
     const escapedSearchText = escapeSearchTextForCql(searchText);
@@ -107,59 +156,53 @@ export class ConfluenceService {
       undefined,
       expand,
       undefined,
-      limit?.toString(),
+      (limit ?? this.getPageSize()).toString(),
       start?.toString(),
-      undefined,
+      excerpt,
       cql
     ), 'Error searching for spaces');
   }
 
   static validateConfig(): string[] {
-    const missingVars: string[] = [];
-
-    // API token is always required
-    if (!process.env.CONFLUENCE_API_TOKEN) {
-      missingVars.push('CONFLUENCE_API_TOKEN');
-    }
-
-    // Either CONFLUENCE_HOST or CONFLUENCE_API_BASE_PATH must be set
-    if (!process.env.CONFLUENCE_HOST && !process.env.CONFLUENCE_API_BASE_PATH) {
-      missingVars.push('CONFLUENCE_HOST or CONFLUENCE_API_BASE_PATH');
-    }
-
-    return missingVars;
+    return getMissingConfig();
   }
 }
 
 export const confluenceToolSchemas = {
   getContent: {
     contentId: z.string().describe("Confluence Data Center content ID"),
-    expand: z.string().optional().describe("Comma-separated list of properties to expand")
+    expand: z.string().optional().describe("Comma-separated list of properties to expand"),
+    bodyMode: z.enum(['storage', 'text', 'none']).optional().describe("How to return the page body. Defaults to storage for backward compatibility."),
+    maxBodyChars: z.number().optional().describe("Maximum number of characters to keep when bodyMode is text")
   },
   searchContent: {
     cql: z.string().describe("Confluence Query Language (CQL) search string for Confluence Data Center"),
     limit: z.number().optional().describe("Maximum number of results to return"),
     start: z.number().optional().describe("Start index for pagination"),
-    expand: z.string().optional().describe("Comma-separated list of properties to expand")
+    expand: z.string().optional().describe("Comma-separated list of properties to expand"),
+    excerpt: z.enum(['none', 'highlight']).optional().describe("Excerpt mode for search results. Defaults to none.")
   },
   createContent: {
     title: z.string().describe("Title of the content"),
     spaceKey: z.string().describe("Space key where content will be created"),
     type: z.string().default("page").describe("Content type (page, blogpost, etc)"),
     content: z.string().describe("Content body in Confluence Data Center \"storage\" format (confluence XML)"),
-    parentId: z.string().optional().describe("ID of the parent page (if creating a child page)")
+    parentId: z.string().optional().describe("ID of the parent page (if creating a child page)"),
+    output: z.enum(['ack', 'full']).optional().describe("Return a compact acknowledgement or the full API response. Defaults to ack.")
   },
   updateContent: {
     contentId: z.string().describe("ID of the content to update"),
     title: z.string().optional().describe("New title of the content"),
     content: z.string().optional().describe("New content body in Confluence Data Center storage format (XML-based)"),
     version: z.number().describe("New version number (must be incremented)"),
-    versionComment: z.string().optional().describe("Comment for this version")
+    versionComment: z.string().optional().describe("Comment for this version"),
+    output: z.enum(['ack', 'full']).optional().describe("Return a compact acknowledgement or the full API response. Defaults to ack.")
   },
   searchSpaces: {
     searchText: z.string().describe("Text to search for in Confluence Data Center space names or descriptions. Quotes and backslashes are escaped for CQL; pass the literal search phrase only (do not pre-escape)."),
     limit: z.number().optional().describe("Maximum number of results to return"),
     start: z.number().optional().describe("Start index for pagination"),
-    expand: z.string().optional().describe("Comma-separated list of properties to expand")
+    expand: z.string().optional().describe("Comma-separated list of properties to expand"),
+    excerpt: z.enum(['none', 'highlight']).optional().describe("Excerpt mode for search results. Defaults to none.")
   }
 };

package/src/index.ts

@@ -1,9 +1,9 @@
-import { connectServer, createMcpServer, formatToolResponse } from '@atlassian-dc-mcp/common';
+import { connectServer, createMcpServer, formatToolResponse, initializeRuntimeConfig } from '@atlassian-dc-mcp/common';
 import { ConfluenceService, ConfluenceContent, confluenceToolSchemas } from './confluence-service.js';
-import dotenv from 'dotenv';
+import { shapeConfluenceMutationAck } from './confluence-response-mapper.js';
+import { getConfluenceRuntimeConfig, getDefaultPageSize } from './config.js';
 
-// Load environment variables
-dotenv.config();
+initializeRuntimeConfig();
 
 // Validate required environment variables
 const missingEnvVars = ConfluenceService.validateConfig();
@@ -12,10 +12,12 @@ if (missingEnvVars.length > 0) {
 }
 
 // Initialize Confluence service
+const confluenceConfig = getConfluenceRuntimeConfig();
 const confluenceService = new ConfluenceService(
-  process.env.CONFLUENCE_API_BASE_PATH ? undefined : process.env.CONFLUENCE_HOST!,
-  process.env.CONFLUENCE_API_TOKEN!,
-  process.env.CONFLUENCE_API_BASE_PATH
+  confluenceConfig.host,
+  () => getConfluenceRuntimeConfig().token,
+  confluenceConfig.apiBasePath,
+  getDefaultPageSize
 );
 
 // Define Confluence instance type
@@ -32,8 +34,8 @@ server.tool(
   "confluence_getContent",
   `Get Confluence content by ID from the ${confluenceInstanceType}`,
   confluenceToolSchemas.getContent,
-  async ({ contentId, expand }) => {
-    const result = await confluenceService.getContent(contentId, expand);
+  async ({ contentId, expand, bodyMode, maxBodyChars }) => {
+    const result = await confluenceService.getContent(contentId, expand, bodyMode, maxBodyChars);
     return formatToolResponse(result);
   }
 );
@@ -42,8 +44,8 @@ server.tool(
   "confluence_searchContent",
   `Search for content in ${confluenceInstanceType} using CQL`,
   confluenceToolSchemas.searchContent,
-  async ({ cql, limit, start, expand }) => {
-    const result = await confluenceService.searchContent(cql, limit, start, expand);
+  async ({ cql, limit, start, expand, excerpt }) => {
+    const result = await confluenceService.searchContent(cql, limit, start, expand, excerpt);
     return formatToolResponse(result);
   }
 );
@@ -52,7 +54,7 @@ server.tool(
   "confluence_createContent",
   `Create new content in ${confluenceInstanceType}`,
   confluenceToolSchemas.createContent,
-  async ({ title, spaceKey, type, content, parentId }) => {
+  async ({ title, spaceKey, type, content, parentId, output }) => {
     const contentObj: ConfluenceContent = {
       type: type || 'page',
       title,
@@ -71,6 +73,12 @@ server.tool(
     }
 
     const result = await confluenceService.createContent(contentObj);
+    if (result.success && result.data && output !== 'full') {
+      return formatToolResponse({
+        ...result,
+        data: shapeConfluenceMutationAck(result.data),
+      });
+    }
     return formatToolResponse(result);
   }
 );
@@ -79,9 +87,9 @@ server.tool(
   "confluence_updateContent",
   `Update existing content in ${confluenceInstanceType}`,
   confluenceToolSchemas.updateContent,
-  async ({ contentId, title, content, version, versionComment }) => {
+  async ({ contentId, title, content, version, versionComment, output }) => {
     // First get the current content to build upon
-    const currentContent = await confluenceService.getContent(contentId);
+    const currentContent = await confluenceService.getContentRaw(contentId);
 
     if (!currentContent.success || !currentContent.data) {
       return formatToolResponse({
@@ -119,6 +127,12 @@ server.tool(
     }
 
     const result = await confluenceService.updateContent(contentId, updateObj);
+    if (result.success && result.data && output !== 'full') {
+      return formatToolResponse({
+        ...result,
+        data: shapeConfluenceMutationAck(result.data),
+      });
+    }
     return formatToolResponse(result);
   }
 );
@@ -130,9 +144,10 @@ server.tool('confluence_searchSpace',
            searchText,
            limit,
            start,
-           expand
+           expand,
+           excerpt
          }) => {
-    const result = await confluenceService.searchSpaces(searchText, limit, start, expand);
+    const result = await confluenceService.searchSpaces(searchText, limit, start, expand, excerpt);
     return formatToolResponse(result);
   });