Pleasanter MCP Server

Un servidor MCP para interactuar con la plataforma de aplicaciones empresariales low-code/no-code Pleasanter.

GitHub
7
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Pleasanter

Servidor del Model Context Protocol (MCP) para la integración con Implem.Pleasanter. Permite que los asistentes de IA operen los proyectos y tareas de Pleasanter.

Funciones

Herramientas

  • Gestión de tareas: Crear, leer, actualizar y eliminar tareas
  • Búsqueda avanzada: Filtrado y búsqueda complejos en todos los proyectos
  • Funciones de análisis: Análisis de tendencias y resumen del estado del proyecto
  • Operaciones masivas: Procesamiento por lotes eficiente de múltiples tareas

Recursos

  • Sitios: Acceso a los proyectos de Pleasanter disponibles
  • Usuarios/Grupos/Departamentos: Información de la estructura organizativa
  • Recursos dinámicos: Estado del proyecto y datos de tareas en tiempo real

Prompts

  • Informe de estado del proyecto: Informes automatizados de salud del proyecto
  • Análisis de tareas: Análisis de tendencias y recomendaciones
  • Productividad del equipo: Análisis de rendimiento e información
  • Identificación de tareas prioritarias: Identificación de tareas urgentes y planes de acción
  • Preparación del stand-up semanal: Preparación para reuniones de equipo

Instalación

  1. Clonar o descargar el código del servidor

    cd pleasanter-mcp-server

  2. Instalar dependencias

    npm install

  3. Compilar el servidor

    npm run build

Requisitos previos

  • Node.js 18.0.0 o superior (recomendado: 24.x LTS)
  • npm o yarn
  • Acceso al servidor de Pleasanter y clave de API

Entornos verificados

La compilación y verificación se han completado en los siguientes entornos:

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

Configuración

  1. Crear el archivo de entorno

    cp .env.example .env

  2. Editar la configuración

    # 必須設定
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

    Nota:

    • Utilice HTTPS en entornos de producción
    • Gestione las claves de API de forma segura y rote periódicamente

  3. Obtener la clave de API de Pleasanter

    • Inicie sesión en el sistema Pleasanter
    • Vaya a la configuración de usuario
    • Genere o copie la clave de API
    • Verifique que el acceso a la API esté habilitado en la cuenta

Uso con Claude Desktop

Entorno macOS

  1. Agregar a la configuración de 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"
      }
    }
  }
}

Entorno Windows

  1. Agregar a la configuración de Claude Desktop

    Edite %APPDATA%\Claude\claude_desktop_config.json:

    Opción 1: Usar el 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"
      }
    }
  }
}

    Opción 2: Especificar la ruta WSL2 directamente

    {
  "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"
      }
    }
  }
}

    Opción 3: Si copió el proyecto en el lado de 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"
      }
    }
  }
}

Entorno Linux

  1. Agregar a la configuración de 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"
      }
    }
  }
}

  2. Reinicie Claude Desktop

  3. Verificar la conexión

    Pruebe los siguientes prompts en Claude Desktop para verificar que el servidor MCP funciona correctamente:

    Paso 1: Verificación de conexión básica

    利用可能なPleasanterサイトを一覧表示できますか？

    Resultado esperado: Se muestra la lista de sitios o un mensaje de error apropiado

    Paso 2: Verificación de recursos

    利用可能なPleasanterリソースにはどのようなものがありますか？

    Resultado esperado: Se muestra la lista de recursos como pleasanter://sites, pleasanter://users, etc.

    Paso 3: Verificación de herramientas

    Pleasanter関連で利用できるツールや機能を教えてください。

    Resultado esperado: Se muestra la lista de herramientas como pleasanter_create_issue, pleasanter_get_issues, etc.

    Paso 4: Verificación de información de usuario

    Pleasanterのユーザー一覧を最初の5件だけ取得してください。

    Resultado esperado: Se muestra la información del usuario en formato JSON

    Si se produce un error:

    • Verifique que la clave de API esté configurada correctamente
    • Verifique que PLEASANTER_BASE_URL sea correcta
    • Reinicie Claude Desktop por completo
    • Revise los registros del servidor MCP (errores de consola, etc.)

Herramientas disponibles

Gestión de tareas

  • pleasanter_create_issue: Crear una nueva tarea
  • pleasanter_get_issues: Buscar y obtener tareas
  • pleasanter_update_issue: Actualizar una tarea existente
  • pleasanter_delete_issue: Eliminar una tarea
  • pleasanter_bulk_create_issues: Crear múltiples tareas en lote

Búsqueda y análisis avanzados

  • pleasanter_advanced_search: Búsqueda compleja con filtros
  • pleasanter_multi_site_search: Búsqueda transversal en múltiples proyectos
  • pleasanter_trend_analysis: Análisis de tendencias del proyecto
  • pleasanter_status_summary: Resumen del estado del proyecto

Recursos disponibles

  • pleasanter://sites: Lista de proyectos disponibles
  • pleasanter://users: Directorio de usuarios
  • pleasanter://groups: Información de grupos
  • pleasanter://depts: Estructura de departamentos
  • pleasanter://sites/{siteId}/issues: Tareas específicas del proyecto
  • pleasanter://sites/{siteId}/summary: Resumen del proyecto
  • pleasanter://sites/{siteId}/status: Estado del proyecto

Prompts disponibles

  • project_status_report: Generar un informe completo del proyecto
  • issue_analysis: Analizar tendencias de tareas y proporcionar recomendaciones
  • team_productivity_report: Análisis de rendimiento del equipo
  • priority_task_identification: Identificar tareas urgentes y crear un plan de acción
  • weekly_standup_preparation: Preparar información para el stand-up semanal

Desarrollo

Ejecución en modo de desarrollo

npm run dev

Compilación

npm run build

Pruebas

npm test

Lint

npm run lint

Solución de problemas

Problemas comunes

  1. Fallo de conexión

    • Verifique que PLEASANTER_BASE_URL sea correcta
    • Compruebe la validez de la clave de API
    • Verifique la conexión de red

  2. Error de autenticación

    • Verifique que la clave de API sea correcta
    • Compruebe que el acceso a la API del usuario esté habilitado
    • Verifique que el usuario tenga los permisos necesarios

  3. Límites de tasa

    • El servidor respeta los límites de tasa de Pleasanter
    • Implementa retroceso exponencial para los reintentos
    • Supervise el uso diario de la API

Modo de depuración

Para mostrar registros detallados, configure LOG_LEVEL=debug en las variables de entorno.

Problemas específicos del entorno Windows

  1. No se encuentra el comando WSL

    • Verifique que Windows Subsystem for Linux (WSL) esté instalado
    • Verifique la versión de WSL con wsl --version

  2. Problema con los separadores de ruta

    • Las rutas de Windows usan la barra invertida \
    • Se requiere escape en JSON: \\

  3. Problemas de firewall

    • Si Claude Desktop no puede acceder al servidor MCP
    • Es posible que deba permitir el puerto en el Firewall de Windows Defender

Consideraciones de seguridad

  • Almacene las claves de API de forma segura
  • Utilice variables de entorno para la configuración
  • Implemente un control de acceso adecuado
  • Supervise el uso de la API
  • Rote las claves periódicamente

Desarrollo en entornos WSL2

Configuración especial cuando se usa WSL2 en un entorno Windows:

1. Configuración del entorno en 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. Configuración de variables de entorno

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

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

3. Acceso desde el lado de Windows

  • El sistema de archivos de WSL2 es accesible desde \\wsl.localhost\Ubuntu\
  • Dado que Claude Desktop se ejecuta en el lado de Windows, use el comando WSL o la ruta WSL2

Ejecución en entornos Docker

Configuración completa del entorno Docker

Puede construir un entorno completo que incluya el servidor web de Pleasanter y el 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サーバーの状態確認

Estructura de servicios

  • pleasanter-web: Aplicación web de Pleasanter (puerto 8080)
  • db: Base de datos PostgreSQL (puerto 5432)
  • codedefiner: Para inicialización de la base de datos (se ejecuta una sola vez)
  • mcp-server: Servidor MCP (puerto 3000)

Solución de problemas

Detener y reiniciar contenedores

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

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

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

Verificación de registros

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

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

Licencia

Licencia MIT: consulte el archivo LICENSE para obtener más detalles.