Pleasanter MCP Server

Um servidor MCP para interagir com a plataforma de aplicações de negócios low-code/no-code Pleasanter.

Documentação

Servidor Pleasanter MCP

Servidor Model Context Protocol (MCP) para integração com Implem.Pleasanter. Permite que assistentes de IA operem projetos e tarefas do Pleasanter.

Funcionalidades

Ferramentas

Gerenciamento de tarefas: criação, leitura, atualização e exclusão de tarefas
Busca avançada: filtragem e busca complexas em todos os projetos
Recursos de análise: análise de tendências e resumo do status do projeto
Operações em lote: processamento eficiente em lote de múltiplas tarefas

Recursos

Sites: acesso aos projetos Pleasanter disponíveis
Usuários/Grupos/Departamentos: informações da estrutura organizacional
Recursos dinâmicos: status do projeto e dados de tarefas em tempo real

Prompts

Relatório de status do projeto: relatórios automatizados de saúde do projeto
Análise de tarefas: análise de tendências e recomendações
Produtividade da equipe: análise de desempenho e insights
Identificação de tarefas prioritárias: identificação de tarefas urgentes e planos de ação
Preparação para stand-up semanal: preparação para reuniões de equipe

Instalação

Clone ou baixe o código do servidor
```
cd pleasanter-mcp-server
```
Instale as dependências
```
npm install
```
Compile o servidor
```
npm run build
```

Pré-requisitos

Node.js 18.0.0 ou superior (recomendado: 24.x LTS)
npm ou yarn
Acesso ao servidor Pleasanter e chave de API

Ambientes testados

A compilação e os testes foram concluídos nos seguintes ambientes:

OS: Ubuntu 24.04.2 LTS (WSL2)
Node.js: v24.2.0
npm: v11.3.0
TypeScript: v5.8.3
Plataforma: WSL2 no Windows

Configuração

Crie o arquivo de ambiente
```
cp .env.example .env
```

Edite a configuração

# 必須設定
PLEASANTER_BASE_URL=http://10.255.20.80:50001  # ローカルネットワーク内のPleasanterサーバー
PLEASANTER_API_KEY=your-api-key-here          # PleasanterのAPIキー

# オプション設定
PLEASANTER_TIMEOUT=30000
PLEASANTER_RETRIES=3
LOG_LEVEL=info

Atenção:

Use HTTPS em ambientes de produção
Gerencie a chave de API com segurança e faça rotação periodicamente

Obtenha a chave de API do Pleasanter
- Faça login no sistema Pleasanter
- Acesse as configurações do usuário
- Gere ou copie a chave de API
- Verifique se o acesso à API está habilitado na conta

Como usar com o Claude Desktop

Ambiente macOS

Adicione à configuração do Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pleasanter": {
      "command": "node",
      "args": ["/path/to/pleasanter-mcp-server/dist/index.js"],
      "env": {
        "PLEASANTER_BASE_URL": "https://your-pleasanter-server.com",
        "PLEASANTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Ambiente Windows

Adicione à configuração do Claude Desktop

Edite %APPDATA%\Claude\claude_desktop_config.json:

Opção 1: Usar comando WSL (recomendado)

{
  "mcpServers": {
    "pleasanter": {
      "command": "wsl",
      "args": [
        "node",
        "/home/ubuntu/github/Implem.Pleasanter/pleasanter-mcp-server/dist/index.js"
      ],
      "env": {
        "PLEASANTER_BASE_URL": "http://10.255.20.80:50001",
        "PLEASANTER_API_KEY": "your-api-key-here",
        "PLEASANTER_TIMEOUT": "30000",
        "PLEASANTER_RETRIES": "3",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Opção 2: Especificar o caminho WSL2 diretamente

{
  "mcpServers": {
    "pleasanter": {
      "command": "node",
      "args": [
        "\\\\wsl.localhost\\Ubuntu\\home\\ubuntu\\github\\Implem.Pleasanter\\pleasanter-mcp-server\\dist\\index.js"
      ],
      "env": {
        "PLEASANTER_BASE_URL": "http://10.255.20.80:50001",
        "PLEASANTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Opção 3: Se o projeto foi copiado para o lado Windows

{
  "mcpServers": {
    "pleasanter": {
      "command": "node",
      "args": ["C:\\path\\to\\pleasanter-mcp-server\\dist\\index.js"],
      "env": {
        "PLEASANTER_BASE_URL": "http://10.255.20.80:50001",
        "PLEASANTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Ambiente Linux

Adicione à configuração do Claude Desktop

Edite ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pleasanter": {
      "command": "node",
      "args": ["/path/to/pleasanter-mcp-server/dist/index.js"],
      "env": {
        "PLEASANTER_BASE_URL": "https://your-pleasanter-server.com",
        "PLEASANTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Reinicie o Claude Desktop
Verifique a conexão

No Claude Desktop, experimente os seguintes prompts para verificar se o servidor MCP está funcionando corretamente:

Etapa 1: Verificação básica de conexão
```
利用可能なPleasanterサイトを一覧表示できますか？
```
Resultado esperado: a lista de sites é exibida ou uma mensagem de erro apropriada é mostrada

Etapa 2: Verificação de recursos
```
利用可能なPleasanterリソースにはどのようなものがありますか？
```
Resultado esperado: a lista de recursos como pleasanter://sites, pleasanter://users é exibida

Etapa 3: Verificação de ferramentas
```
Pleasanter関連で利用できるツールや機能を教えてください。
```
Resultado esperado: a lista de ferramentas como pleasanter_create_issue, pleasanter_get_issues é exibida

Etapa 4: Verificação de informações do usuário
```
Pleasanterのユーザー一覧を最初の5件だけ取得してください。
```
Resultado esperado: as informações do usuário são exibidas em formato JSON

Se ocorrer um erro:
- Verifique se a chave de API está configurada corretamente
- Verifique se PLEASANTER_BASE_URL está correto
- Reinicie completamente o Claude Desktop
- Verifique os logs do servidor MCP (erros de console, etc.)

Ferramentas disponíveis

Gerenciamento de tarefas

pleasanter_create_issue: criar uma nova tarefa
pleasanter_get_issues: buscar e obter tarefas
pleasanter_update_issue: atualizar uma tarefa existente
pleasanter_delete_issue: excluir uma tarefa
pleasanter_bulk_create_issues: criar múltiplas tarefas em lote

Busca e análise avançadas

pleasanter_advanced_search: busca complexa com filtros
pleasanter_multi_site_search: busca transversal em múltiplos projetos
pleasanter_trend_analysis: análise de tendências do projeto
pleasanter_status_summary: resumo do status do projeto

Recursos disponíveis

pleasanter://sites: lista de projetos disponíveis
pleasanter://users: diretório de usuários
pleasanter://groups: informações de grupos
pleasanter://depts: estrutura de departamentos
pleasanter://sites/{siteId}/issues: tarefas específicas do projeto
pleasanter://sites/{siteId}/summary: resumo do projeto
pleasanter://sites/{siteId}/status: status do projeto

Prompts disponíveis

project_status_report: gerar um relatório abrangente do projeto
issue_analysis: analisar tendências de tarefas e fornecer recomendações
team_productivity_report: análise de desempenho da equipe
priority_task_identification: identificar tarefas urgentes e criar um plano de ação
weekly_standup_preparation: preparar informações para o stand-up semanal

Desenvolvimento

Executar em modo de desenvolvimento

npm run dev

Compilação

npm run build

Testes

npm test

Lint

npm run lint

Solução de problemas

Problemas comuns

Falha de conexão
- Verifique se PLEASANTER_BASE_URL está correto
- Verifique a validade da chave de API
- Verifique a conexão de rede
Erro de autenticação
- Verifique se a chave de API está correta
- Verifique se o acesso à API do usuário está habilitado
- Verifique se o usuário possui as permissões necessárias
Limite de taxa
- O servidor respeita os limites de taxa do Pleasanter
- Implementa backoff exponencial para novas tentativas
- Monitore o uso diário da API

Modo de depuração

Para exibir logs detalhados, defina LOG_LEVEL=debug na variável de ambiente.

Problemas específicos do ambiente Windows

Comando WSL não encontrado
- Verifique se o Windows Subsystem for Linux (WSL) está instalado
- Verifique a versão do WSL com wsl --version
Problemas com separadores de caminho
- Os caminhos do Windows usam barra invertida \
- É necessário escape em JSON: \\
Problemas de firewall
- Se o Claude Desktop não conseguir acessar o servidor MCP
- Pode ser necessário liberar a porta no Firewall do Windows Defender

Considerações de segurança

Armazene a chave de API com segurança
Use variáveis de ambiente para configuração
Implemente controle de acesso adequado
Monitore o uso da API
Faça rotação periódica das chaves

Desenvolvimento em ambiente WSL2

Configurações especiais ao usar WSL2 no ambiente Windows:

1. Configuração do ambiente no WSL2

# WSL2 Ubuntu環境でのセットアップ
sudo apt update
sudo apt install nodejs npm

# プロジェクトのセットアップ
cd /home/ubuntu/github/Implem.Pleasanter/pleasanter-mcp-server
npm install
npm run build

2. Configuração das variáveis de ambiente

# WSL2環境でのPleasanter設定
cp .env.example .env

# .envファイルを編集
PLEASANTER_BASE_URL=http://10.255.20.80:50001
PLEASANTER_API_KEY=your-api-key-here

3. Acesso pelo lado Windows

O sistema de arquivos do WSL2 é acessível a partir de \\wsl.localhost\Ubuntu\
Como o Claude Desktop é executado no lado Windows, use o comando WSL ou o caminho WSL2

Execução em ambiente Docker

Configuração completa do ambiente Docker

Você pode construir um ambiente completo incluindo o servidor web do Pleasanter e o servidor MCP:

# 1. 環境変数を設定
cp .env.example .env
# .envファイルを編集してPleasanter APIキーを設定

# 2. Docker環境を起動
docker-compose up -d

# 3. 初回セットアップの確認
docker-compose logs codedefiner

# 4. Webアプリケーションにアクセス
# http://localhost:8080 でPleasanterにアクセス

# 5. MCPサーバーの動作確認
# http://localhost:3000 でMCPサーバーの状態確認

Estrutura de serviços

pleasanter-web: aplicação web do Pleasanter (porta 8080)
db: banco de dados PostgreSQL (porta 5432)
codedefiner: para inicialização do banco de dados (executar apenas uma vez)
mcp-server: servidor MCP (porta 3000)

Solução de problemas

Parar e reiniciar contêineres

# 全サービス停止
docker-compose down

# データベースも含めて完全削除
docker-compose down -v

# 再構築
docker-compose up --build -d

Verificação de logs

# 全サービスのログ
docker-compose logs

# 特定サービスのログ
docker-compose logs pleasanter-web
docker-compose logs mcp-server

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.