MCP Confluence Demo

mcp汇流演示

用于Confluence与自动生成内容管理集成的模型上下文协议（MCP）服务器。

特性

• MCP服务器：基于JSON-RPC的AI集成工具
• CLI工具：用于测试的直接命令行界面
• 自动生成的内容：管理以下内容 BEGIN_AUTO_GENERATED 和 END_AUTO_GENERATED 标记物
• 基于DOM的处理：使用cheerio进行强大的HTML解析
• 安全更新：保留文档结构和格式
• Markdown支持：汇流存储格式和Markdown之间的转换
• 图像支持：使用Markdown导入/导出自动上传/下载图像

先决条件

此项目使用 布置 用于工具版本管理。

设置

1. 安装所需工具：

mise install
pnpm install

1. 设置环境变量：

export CONFLUENCE_API_TOKEN="your-confluence-api-token"
export CONFLUENCE_EMAIL="your-email@company.com"

# Optional: Set log level (DEBUG, INFO, WARN, ERROR)
export LOG_LEVEL="INFO"

1. 构建项目：

pnpm build

用法

MCP服务器

用作人工智能集成的MCP服务器：

# Start MCP server
pnpm mcp

# Or with development build
pnpm mcp:dev

MCP工具

• conference_read：从Confluence页面读取自动生成的内容
• 汇流更新：更新Confluence页面中自动生成的内容
• conference_info：获取Confluence页面信息
• conference_read_as_markdown：以Markdown格式读取自动生成的内容
• conference_write_as_markdown：使用Markdown格式更新自动生成的内容
• conference_import_markdown_with_images：将带有图像的Markdown文件导入Confluence（将图像作为附件上传）
• 汇流_导出_标记_带图像：将Confluence页面导出到带图像的Markdown文件（将图像下载到本地目录）

CLI工具

直接命令行用法：

# Get page information
pnpm confluence info "https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/ID/PAGE"

# Read auto-generated content
pnpm confluence read "https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/ID/PAGE"

# Update auto-generated content
pnpm confluence update "https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/ID/PAGE" "New content"

# Export auto-generated content to Markdown file
pnpm confluence export-md "https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/ID/PAGE" -f output.md

# Import Markdown file to auto-generated section
pnpm confluence import-md "https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/ID/PAGE" -f input.md

# Export page with images to directory
pnpm confluence export-markdown "https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/ID/PAGE" -o ./output-dir

# Import Markdown with images from file
pnpm confluence import-markdown "https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/ID/PAGE" -f ./input-dir/document.md

图像支持

这 import-markdown 和 export-markdown 命令支持自动图像处理：

• 导入：Markdown中引用的图像（例如。， ![alt](./image.png))自动上传为Confluence附件
• 出口：Confluence页面中的图像会自动下载到输出目录
• 格式：支持PNG、JPG、JPEG、GIF、SVG、WebP
• 大小限制：每张图像最大10MB
• 去重：重复的图像会被自动检测到，并且只上传/下载一次

建筑

• DOM处理：使用cheerio进行强大的HTML操作
• 标记检测：查找 BEGIN_AUTO_GENERATED/END_AUTO_GENERATED 按文本内容
• 结构保护：在仅更新标记部分的同时保持HTML结构
• 错误处理：针对API和解析失败的全面错误处理
• 结构化日志记录：表情符号图标和不同级别的详细日志记录（调试、信息、警告、错误）

日志记录

MCP服务器包括用于监控和调试的全面日志记录：

日志级别

• 调试 🐛: 详细执行信息
• 信息 ℹ️: 一般操作信息
• 警告 ⚠️: 警告条件
• 错误 ❌: 错误条件

日志类型

• 🚀 服务器事件：启动/停止操作
• 🔧 工具执行：工具启动/完成/执行时间错误
• 🌍 API调用：使API请求/响应与时间一致
• 📖 页面操作：使用页面详细信息进行读取/更新/信息操作
• 🔐 认证：隐藏敏感信息

配置

通过环境变量设置日志级别：

export LOG_LEVEL=DEBUG  # Show all logs
export LOG_LEVEL=INFO   # Default level
export LOG_LEVEL=ERROR  # Only errors

超时和取消

所有外部I/O操作（Confluence API调用）都支持超时和取消：

默认超时

• 默认：10秒（10000毫秒）
• 防止挂起操作和资源耗尽
• 自动应用于所有API调用

超时处理

当发生超时时：

• 操作立即中止
• AbortError 被抛出
• 已登录 abortReason: "timeout"
• 错误会传播给调用者（未被抑制）

取消支持

可以通过以下方式取消操作 AbortSignal:

• 自定义超时可以通过以下方式指定 timeoutMs 参数
• 取消原因已记录(timeout 或 cancelled)
• 适当清理资源

技术细节

• 用途 AbortSignal.timeout() 超时
• 用途 AbortSignal.any() 用于组合信号
• Axios在中止时自动取消HTTP请求
• 所有错误保留原始原因链

测试

此项目使用 Vitest 用于单元测试。

运行测试

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

测试覆盖率

测试位于 tests/ 目录和封面：

• Markdown转换器：汇流存储格式和Markdown之间的转换、图像引用提取和宏替换
• 文件应用：文件I/O操作、路径清理、内容类型检测和SHA256计算

写作测试

测试使用Vitest的模拟功能进行文件系统操作。例子：

import { describe, it, expect } from "vitest";
import { someFunction } from "../src/some-module.js";

describe("someFunction", () => {
  it("should do something", () => {
    expect(someFunction()).toBe(expected);
  });
});

工具

• Node.js：22.13.1
• pnpm:10.11.1
• TypeScript：5.9.3
• Vitest:2.1.9
• MCP SDK:1.20.0
• 欢呼声：1.1.2
• 轴距：1.12.2

许可证

Apache许可证2.0