Confluence

Interaja com a API do Confluence para gerenciar espaços, páginas e conteúdo. Suporta pesquisa, criação e atualização de páginas.

GitHub
4
Experimente este MCPPatrocinado

Documentação

Serviço MCP Confluence

Este é um serviço de implementação da API do Confluence baseado em MCP (Model Context Protocol). O serviço fornece capacidade de interação com o Confluence, suportando obtenção de informações de espaços, conteúdo de páginas, busca e outras funcionalidades.

Sumário

Funcionalidades

🔐 Métodos de Autenticação

  • Autenticação por Access Token (recomendado)
  • Autenticação por nome de usuário e senha
  • Suporte a configuração de múltiplos ambientes

🔧 Arquitetura de Ferramentas MCP (otimizada)

  • Otimização de fusão de ferramentas: reduzido de 12 ferramentas para 8 (redução de 33%)
  • Design de API unificado: diferencia tipos de operação por meio do parâmetro action
  • Validação inteligente de parâmetros: valida automaticamente parâmetros obrigatórios com base na operação
  • Comentários completos de parâmetros: descrições detalhadas visíveis no MCP Inspector

📄 Funcionalidades de Gerenciamento de Páginas

  • managePages: ferramenta unificada de gerenciamento de páginas ⭐️
    • Criar página (suporta página pai e formato de conteúdo)
    • Atualizar página (suporte a atualização incremental)
    • Excluir página ⭐️ novo recurso
    • Obter informações básicas da página
    • Obter conteúdo detalhado da página
    • Suporte a Markdown 🆕 conversão automática para HTML
  • getPageByPrettyUrl: obter página com precisão por título
  • getSpace: obter informações do espaço

💬 Funcionalidades de Gerenciamento de Comentários

  • manageComments: ferramenta unificada de gerenciamento de comentários ⭐️
    • Comentários normais: criar, atualizar, excluir, responder
    • Comentários inline: criar, atualizar, excluir, responder
    • Suporte a controle de versão e monitoramento de comentários
    • Suporte a Markdown 🆕 detecção e conversão inteligentes
  • getPageComments: obter todos os comentários de uma página (suporta paginação)
  • getComment: obter detalhes de um único comentário

🔍 Funcionalidade de Busca

  • searchContent: busca de conteúdo em texto completo (suporta sintaxe CQL)
  • searchComments: busca de conteúdo de comentários (suporta limitação por espaço)
  • Mecanismo de fallback de erros: tenta automaticamente busca básica quando há erro de sintaxe CQL

⚡ Otimização de Desempenho

  • Reutilização de conexão HTTP: suporte a Keep-Alive
  • Compressão de resposta: compressão automática na transmissão
  • Controle de timeout de requisição: tempo de timeout configurável
  • Mecanismo de nova tentativa de erros: nova tentativa automática de requisições com falha

📊 Logs e Monitoramento

  • Saída de logs estruturados: logs em formato JSON
  • Estatísticas de tempo de requisição: monitoramento de desempenho
  • Informações detalhadas de erro: facilita a depuração
  • Rastreamento de registros de operação: log completo de operações

Início Rápido

Requisitos de Ambiente

  • Node.js >= 14.0.0
  • TypeScript >= 4.0.0

Instalação

# 安装依赖
npm install

Build

# 清理并构建项目
npm run build:clean

Iniciar o Serviço

# 启动服务
npm start

Instruções de Configuração

Configuração de Autenticação

O serviço suporta dois métodos de autenticação; você pode escolher um deles:

1. Autenticação por Access Token (recomendado)

Configure no arquivo .env:

CONFLUENCE_URL=https://your-confluence-url
CONFLUENCE_ACCESS_TOKEN=your-access-token

2. Autenticação por nome de usuário e senha

Configure no arquivo .env:

CONFLUENCE_URL=https://your-confluence-url
CONFLUENCE_USERNAME=your-username
CONFLUENCE_PASSWORD=your-password

Outros Itens de Configuração

# 服务器配置
PORT=3000
NODE_ENV=development
TIMEOUT=10000
REJECT_UNAUTHORIZED=true

Configuração do Cursor IDE

Configuração no Windows

  1. Usando Smithery (recomendado) Adicione em %USERPROFILE%\.cursor\mcp.json:
{
  "mcpServers": {
    "mcp-server-confluence-ts": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@smithery/cli@latest",
        "run",
        "@enjoyzl/mcp-server-confluence-ts",
        "--config",
        "{\"confluenceUrl\":\"your-confluence-url\",\"confluenceUsername\":\"your-username\",\"confluencePassword\":\"your-password\"}"
      ]
    }
  }
}
  1. Modo de serviço local Adicione em %USERPROFILE%\.cursor\mcp.json:
{
  "mcpServers": {
    "mcp-server-confluence-ts": {
      "command": "cmd",
      "args": [
        "/k",
        "cd",
        "/d",
        "D:\\workspace\\code\\mcp\\mcp-server-confluence-ts",
        "&",
        "node",
        "dist/index.js"
      ]
    }
  }
}

Instruções de configuração no Windows:

  • /k: mantém a janela de comando aberta após executar o comando, facilitando a visualização dos logs
  • /d: alterna para a unidade especificada
  • Use & para conectar vários comandos
  • Use barras invertidas duplas \\ para escape nos caminhos
  • As variáveis de ambiente podem ser configuradas no arquivo .env do projeto

Configuração no Mac/Linux

  1. Usando Smithery (recomendado) Adicione em ~/.cursor/mcp.json:
{
  "mcpServers": {
    "mcp-server-confluence-ts": {
      "command": "bash",
      "args": [
        "-c",
        "npx -y @smithery/cli@latest run @enjoyzl/mcp-server-confluence-ts --config '{\"confluenceUrl\":\"your-confluence-url\",\"confluenceUsername\":\"your-username\",\"confluencePassword\":\"your-password\"}'"
      ]
    }
  }
}
  1. Modo de serviço local Adicione em ~/.cursor/mcp.json:
{
  "mcpServers": {
    "mcp-server-confluence-ts": {
      "command": "node",
      "args": ["/Users/your-username/workspace/code/mcp/mcp-server-confluence-ts/dist/index.js"],
      "env": {
        "CONFLUENCE_URL": "your-confluence-url",
        "CONFLUENCE_USERNAME": "youraccount",
        "CONFLUENCE_PASSWORD": "yourpwd",
      }
    }
  }
}

Instruções de configuração no Mac/Linux:

  • -c: executa a string de comando
  • Use && para conectar vários comandos
  • Use barras normais / nos caminhos
  • As variáveis de ambiente podem ser configuradas no arquivo .env do projeto
  • O diretório pessoal do usuário no Mac geralmente fica em /Users/your-username/
  • O diretório pessoal do usuário no Linux geralmente fica em /home/your-username/

Modo de Desenvolvimento

# 监听文件变化并自动编译
npm run dev

# 监听文件变化并自动重启服务
npm run dev:start

Comando de Build

# 仅构建项目
npm run build

# 清理构建目录
npm run clean

# 清理并重新构建
npm run build:clean

Ferramentas de Depuração

# 基本调试模式
npm run inspector

# 开发调试模式（带详细日志）
npm run inspector:dev

Guia de Uso das Ferramentas MCP

🚀 Otimização da Arquitetura de Ferramentas

Este serviço concluiu a otimização da arquitetura de ferramentas, reorganizada por funcionalidade e frequência de uso:

📁 1. 基础信息工具（最常用）
📁 2. 页面管理工具（核心功能）  
📁 3. 评论管理工具（扩展功能）
📁 4. 搜索工具（专用搜索）

🔧 Lista de Ferramentas MCP

1. Ferramentas de Informações Básicas - as consultas mais usadas

getSpace - obter informações do espaço

{
  "name": "getSpace",
  "arguments": {
    "spaceKey": "DEV"
  }
}

getPageByPrettyUrl - obter página com precisão por título

{
  "name": "getPageByPrettyUrl",
  "arguments": {
    "spaceKey": "DEV",
    "title": "API 开发指南"
  }
}

2. Ferramentas de Gerenciamento de Páginas - funcionalidade principal

managePages - gerenciamento unificado de páginas ⭐️ otimização por fusão

Criar página:

{
  "name": "managePages",
  "arguments": {
    "action": "create",
    "spaceKey": "DEV",
    "title": "新页面标题",
    "content": "<p>页面内容</p>",
    "parentId": "123456789",
    "representation": "storage"
  }
}

Atualizar página:

{
  "name": "managePages",
  "arguments": {
    "action": "update",
    "pageId": "123456789",
    "title": "更新的标题",
    "content": "<p>更新的内容</p>",
    "version": 2,
    "representation": "storage"
  }
}

Excluir página: ⭐️ novo recurso

{
  "name": "managePages",
  "arguments": {
    "action": "delete",
    "pageId": "123456789"
  }
}

Obter informações básicas da página:

{
  "name": "managePages",
  "arguments": {
    "action": "get",
    "pageId": "123456789"
  }
}

Obter conteúdo detalhado da página:

{
  "name": "managePages",
  "arguments": {
    "action": "getContent",
    "pageId": "123456789",
    "expand": "body.storage,version,space"
  }
}

3. Ferramentas de Gerenciamento de Comentários - funcionalidade estendida

manageComments - gerenciamento unificado de comentários ⭐️ otimização por fusão

Criar comentário normal (formato HTML):

{
  "name": "manageComments",
  "arguments": {
    "action": "create",
    "commentType": "regular",
    "pageId": "123456789",
    "content": "这是一条普通评论",
    "representation": "storage"
  }
}

Criar comentário normal (formato Markdown): 🆕

{
  "name": "manageComments",
  "arguments": {
    "action": "create",
    "commentType": "regular",
    "pageId": "123456789",
    "content": "## 代码审查意见\n\n这段代码需要优化：\n\n- **性能问题**: 数据库查询未优化\n- **安全问题**: 缺少输入验证\n\n建议修改：\n\n``javascript\n// 使用索引查询\nconst user = await User.findById(id).lean();\n```",
    "representation": "markdown"
  }
}

Criar comentário inline:

{
  "name": "manageComments",
  "arguments": {
    "action": "create",
    "commentType": "inline",
    "pageId": "123456789",
    "content": "这里需要注意性能问题",
    "originalSelection": "QueryHoldingsService.setHoldingData()",
    "matchIndex": 0,
    "numMatches": 1
  }
}

Atualizar comentário:

{
  "name": "manageComments",
  "arguments": {
    "action": "update",
    "commentType": "regular",
    "commentId": "98765432",
    "content": "更新后的评论内容",
    "version": 2
  }
}

Excluir comentário:

{
  "name": "manageComments",
  "arguments": {
    "action": "delete",
    "commentType": "regular",
    "commentId": "98765432"
  }
}

Responder a comentário normal:

{
  "name": "manageComments",
  "arguments": {
    "action": "reply",
    "commentType": "regular",
    "pageId": "123456789",
    "parentCommentId": "98765432",
    "content": "这是一条回复",
    "watch": false
  }
}

Responder a comentário inline:

{
  "name": "manageComments",
  "arguments": {
    "action": "reply",
    "commentType": "inline",
    "commentId": "98765432",
    "pageId": "123456789",
    "content": "这是对行内评论的回复"
  }
}

getPageComments - obter todos os comentários de uma página

{
  "name": "getPageComments",
  "arguments": {
    "pageId": "123456789",
    "start": 0,
    "limit": 25
  }
}

getComment - obter detalhes de um único comentário

{
  "name": "getComment",
  "arguments": {
    "commentId": "98765432"
  }
}

4. Ferramentas de Busca - funcionalidade de busca dedicada

searchContent - buscar conteúdo de páginas (suporta CQL)

{
  "name": "searchContent",
  "arguments": {
    "query": "API 开发"
  }
}

searchComments - buscar conteúdo de comentários

{
  "name": "searchComments",
  "arguments": {
    "query": "性能优化",
    "spaceKey": "DEV",
    "start": 0,
    "limit": 25
  }
}

📝 Descrição dos Parâmetros

Opções do parâmetro action:

  • Gerenciamento de páginas: create, update, delete, get, getContent
  • Gerenciamento de comentários: create, update, delete, reply

Opções do parâmetro commentType:

  • regular (padrão): comentário normal
  • inline: comentário inline

Opções do parâmetro representation:

  • storage (recomendado): formato de armazenamento HTML
  • wiki: sintaxe de marcação Wiki
  • editor2: formato do editor
  • view: formato de visualização
  • markdown 🆕: formato Markdown (conversão automática para HTML)

🎯 Destaques da Otimização

✅ Otimização do número de ferramentas: de 12 ferramentas para 8 (redução de 33%)
✅ Design de API unificado: diferencia tipos de operação por meio do parâmetro action
✅ Validação inteligente de parâmetros: valida automaticamente parâmetros obrigatórios com base no tipo de operação
✅ Comentários completos de parâmetros: descrições detalhadas de parâmetros visíveis no MCP Inspector
✅ Novo recurso de exclusão: suporte à operação de exclusão de páginas
✅ Dois tipos de comentários: gerenciamento unificado de comentários normais e inline

🚀 Novo Recurso: Exportação em Markdown

Visão Geral do Recurso de Exportação

Agora é possível exportar páginas do Confluence como arquivos Markdown para o espaço de trabalho atual!

🎯 Métodos de Exportação Suportados

  1. Exportação de página única (exportPage)

    • Exporta uma página especificada como arquivo Markdown
    • Suporta divisão de documentos grandes por seções
    • Metadados YAML frontmatter opcionais

  2. Exportação hierárquica (exportPageHierarchy)

    • Exporta recursivamente a página e todas as suas subpáginas
    • Mantém a estrutura hierárquica de diretórios original
    • Controle da profundidade da recursão

  3. Exportação em lote (batchExportPages)

    • Exporta várias páginas especificadas simultaneamente
    • Controle inteligente de concorrência e tratamento de erros
    • Otimização de desempenho e acompanhamento de progresso

🌟 Funcionalidades Principais

  • ✅ Conversão inteligente de conteúdo: conversão de alta qualidade de HTML para Markdown
  • ✅ Divisão em seções: divisão automática de documentos grandes com base nos níveis de título
  • ✅ Preservação de metadados: informações completas da página como YAML frontmatter
  • ✅ Gerenciamento de arquivos: nomeação inteligente de arquivos e tratamento de conflitos
  • ✅ Otimização de desempenho: controle de concorrência, mecanismo de nova tentativa, otimização de memória
  • ✅ Acompanhamento de progresso: status de exportação em tempo real e relatórios de erros

📖 Início Rápido

# 导出单个页面
{
  "pageId": "123456789",
  "outputDir": "my-docs",
  "includeMetadata": true
}

# 按章节拆分导出
{
  "pageId": "123456789",
  "splitByChapters": true,
  "splitLevel": "2"
}

# 导出页面层次结构
{
  "pageId": "123456789",
  "maxDepth": 3,
  "includeChildren": true
}

# 批量导出多个页面
{
  "pageIds": ["123", "456", "789"],
  "concurrency": 3
}

📁 Exemplo de Saída

confluence-export/
├── API_Documentation.md           # 单页面导出
├── User_Guide/                    # 层次结构导出
│   ├── User_Guide.md
│   ├── Getting_Started/
│   │   └── Installation.md
│   └── Advanced_Topics/
│       └── Configuration.md
└── Large_Document/                # 章节拆分导出
    ├── README.md                  # 章节索引
    ├── 01_introduction.md
    ├── 02_setup.md
    └── 03_usage.md

Para um guia de uso detalhado, consulte: Guia do Recurso de Exportação

Recomendações de Segurança

  1. Priorize o uso da autenticação por Access Token, que é mais segura
  2. Alterne o Access Token periodicamente
  3. Não codifique informações de autenticação no código
  4. Garanta que o arquivo .env esteja adicionado ao .gitignore
  5. Em ambientes de produção, use variáveis de ambiente ou um sistema seguro de gerenciamento de configuração
  6. Se ambos os métodos de autenticação estiverem configurados, o sistema priorizará o Access Token

Observações

  1. A autenticação por Access Token e por nome de usuário e senha só pode escolher um dos métodos
  2. Se ambos os métodos de autenticação estiverem configurados, o sistema priorizará o Access Token
  3. Garanta que a URL configurada seja o endereço correto da API do Confluence
  4. Em ambientes de produção, recomenda-se o uso de HTTPS

Otimização de Desempenho

  1. Otimização de conexão

    • Habilitar HTTP Keep-Alive
    • Limitar o número máximo de conexões simultâneas
    • Controlar o número de conexões ociosas

  2. Otimização de requisições

    • Compressão de resposta
    • Controle de timeout
    • Limitação de redirecionamentos

  3. Tratamento de erros

    • Mecanismo automático de nova tentativa
    • Informações detalhadas de erro
    • Estatísticas de tempo de requisição

Guia de Depuração

Saída de Logs

O serviço usa saída de logs estruturados, contendo as seguintes informações:

{
  "jsonrpc": "2.0",
  "method": "log",
  "params": {
    "level": "info",
    "message": "请求信息",
    "timestamp": "2024-04-16T12:00:44.000Z"
  }
}

Tratamento de Erros

Formato de resposta de erro:

interface ErrorResponse {
  message: string;
  statusCode?: number;
  error?: any;
  config?: {
    url?: string;
    method?: string;
    params?: any;
  };
}

Visão Geral das Ferramentas

🎯 Agrupamento de Ferramentas Após Otimização da Arquitetura

Após a otimização da arquitetura, as ferramentas foram reorganizadas por frequência de uso e agrupamento lógico:

📁 1. Ferramentas de Informações Básicas (mais usadas)

  • getSpace - obter informações do espaço
  • getPageByPrettyUrl - obter página com precisão por título

📁 2. Ferramentas de Gerenciamento de Páginas (funcionalidade principal)

  • managePages ⭐️ - gerenciamento unificado de páginas (create/update/delete/get/getContent)

📁 3. Ferramentas de Gerenciamento de Comentários (funcionalidade estendida)

  • manageComments ⭐️ - gerenciamento unificado de comentários (create/update/delete/reply, suporta comentários normais + inline)
  • getPageComments - obter todos os comentários de uma página
  • getComment - obter detalhes de um único comentário

📁 4. Ferramentas de Busca (busca dedicada)

  • searchContent - buscar conteúdo de páginas (suporta sintaxe CQL)
  • searchComments - buscar conteúdo de comentários

📊 Resultados da Otimização

  • Número de ferramentas: de 12 para 8 (redução de 33%)
  • API unificada: fusão de funcionalidades semelhantes, diferenciando operações pelo parâmetro action
  • Funcionalidades aprimoradas: novo recurso de exclusão de páginas, comentários de parâmetros aprimorados
  • Experiência melhorada: ordenação por frequência de uso, maior eficiência na localização

Documentação

Contribuição

Contribuições com Issues e Pull Requests são bem-vindas.

Licença

Licença MIT

Configuração

Configuração de Variáveis de Ambiente

Crie o arquivo .env na raiz do projeto e configure os seguintes parâmetros:

# Confluence 连接配置
CONFLUENCE_URL=https://your-confluence.com
CONFLUENCE_USERNAME=your-username
CONFLUENCE_PASSWORD=your-password
# 或者使用访问令牌
CONFLUENCE_ACCESS_TOKEN=your-access-token

# 服务器配置
PORT=3000
NODE_ENV=development
SERVER_TIMEOUT=10000

# 评论 API 策略配置
COMMENT_API_STRATEGY=standard
COMMENT_ENABLE_FALLBACK=true
COMMENT_TIMEOUT=15000

Instruções de Configuração da Estratégia de Comentários

A funcionalidade de comentários suporta três estratégias de implementação de API, configuráveis pela variável de ambiente COMMENT_API_STRATEGY:

1. standard (padrão, recomendado)

  • Usa a API REST padrão
  • Boa compatibilidade, adequado para Confluence 7.4+
  • Alta estabilidade, adequado para ambientes de produção

2. tinymce

  • Usa o endpoint TinyMCE
  • Funcionalidades mais ricas, simula o comportamento do navegador
  • Suporta funcionalidades de comentários mais complexas

3. auto

  • Seleção automática de estratégia
  • Prioriza o uso de TinyMCE, com fallback para a API padrão em caso de falha
  • Equilibra funcionalidade e compatibilidade

Outras Configurações de Comentários

  • COMMENT_ENABLE_FALLBACK: se o mecanismo de fallback está habilitado (padrão: true)

    • true: quando a API preferida falha, tenta automaticamente a API alternativa
    • false: usa apenas a API especificada, lançando erro diretamente em caso de falha

  • COMMENT_TIMEOUT: tempo de timeout de requisições de comentários, em milissegundos (padrão: 15000)

    • Recomenda-se 10-15 segundos para a API padrão
    • Para a API TinyMCE, que requer etapas como obtenção de token, recomenda-se 15-20 segundos

Observações Especiais sobre o Confluence 7.4

  • A API padrão é mais estável na versão 7.4
  • A API TinyMCE oferece funcionalidades mais ricas, mas pode ter problemas de compatibilidade
  • Recomenda-se usar a estratégia standard em ambientes de produção; em ambientes de desenvolvimento, pode-se escolher conforme necessário

Publicação em Repositório npm Privado

Referência de login no repositório: [PRIVATE_DOCUMENTATION_URL]

# 登录并部署
npm login --registry=[PRIVATE_REGISTRY]
npm publish @[ORGANIZATION]/mcp-server-confluence-ts

Instalação via Claude CLI (recomendado)

``shell claude mcp add --transport stdio mcp-server-confluence-ts -- npx --registry=[PRIVATE_REGISTRY] -y @[ORGANIZATION]/mcp-server-confluence-ts


#### Cursor 安装

**Cursor MCP 配置文件** (通常位于 `~/.cursor/settings.json` 或项目 `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "mcp-server-confluence-ts": {
      "command": "npx",
      "args": ["--registry=[PRIVATE_REGISTRY]","-y", "@[ORGANIZATION]/mcp-server-confluence-ts"],
      "env": {
        "CONFLUENCE_URL": "your-confluence-url",
        "CONFLUENCE_USERNAME": "youraccount",
        "CONFLUENCE_PASSWORD": "yourpwd",
      }
    }
  }
}